ANG-007: Markdown preprocessing & embedding pipeline

api/Global.d.ts

@@ -1,5 +1,7 @@
 import Plugin from '../Plugin';
 import Joplin from './Joplin';
+import BasePlatformImplementation from '../BasePlatformImplementation';
+import type { Store } from 'redux';
 /**
  * @ignore
  */
@@ -8,7 +10,7 @@ import Joplin from './Joplin';
  */
 export default class Global {
     private joplin_;
-    constructor(implementation: any, plugin: Plugin, store: any);
+    constructor(implementation: BasePlatformImplementation, plugin: Plugin, store: Store<any>);
     get joplin(): Joplin;
-    get process(): any;
+    get process(): NodeJS.Process;
 }

api/Joplin.d.ts

@@ -12,6 +12,9 @@ import JoplinClipboard from './JoplinClipboard';
 import JoplinWindow from './JoplinWindow';
 import BasePlatformImplementation from '../BasePlatformImplementation';
 import JoplinImaging from './JoplinImaging';
+import JoplinFs from './JoplinFs';
+import JoplinAi from './JoplinAi';
+import type { Store } from 'redux';
 /**
  * This is the main entry point to the Joplin API. You can access various services using the provided accessors.
  *
@@ -28,6 +31,7 @@ export default class Joplin {
     private data_;
     private plugins_;
     private imaging_;
+    private fs_;
     private workspace_;
     private filters_;
     private commands_;
@@ -37,11 +41,13 @@ export default class Joplin {
     private contentScripts_;
     private clipboard_;
     private window_;
+    private ai_;
     private implementation_;
-    constructor(implementation: BasePlatformImplementation, plugin: Plugin, store: any);
+    constructor(implementation: BasePlatformImplementation, plugin: Plugin, store: Store<any>);
     get data(): JoplinData;
     get clipboard(): JoplinClipboard;
     get imaging(): JoplinImaging;
+    get fs(): JoplinFs;
     get window(): JoplinWindow;
     get plugins(): JoplinPlugins;
     get workspace(): JoplinWorkspace;
@@ -57,6 +63,13 @@ export default class Joplin {
     get views(): JoplinViews;
     get interop(): JoplinInterop;
     get settings(): JoplinSettings;
+    /**
+     * Access to AI features: chat completions and semantic search over the
+     * local embeddings index. See {@link JoplinAi}.
+     *
+     * <span class="platform-desktop">desktop</span>
+     */
+    get ai(): JoplinAi;
     /**
      * It is not possible to bundle native packages with a plugin, because they
      * need to work cross-platforms. Instead access to certain useful native

api/JoplinAi.d.ts

@@ -0,0 +1,80 @@
+import { ChatMessage, ChatOptions, SearchOptions, SearchResult } from './types';
+/**
+ * Provides access to AI models configured by the user. The active provider
+ * (Joplin Cloud AI, OpenAI-compatible, or Anthropic) and the model are picked
+ * by the user in the Joplin settings — plugins inherit whichever is active.
+ *
+ * AI is disabled by default. The user must enable it in the settings, and
+ * separately grant permission to use a remote (cloud-hosted) provider before
+ * any plugin call will succeed.
+ *
+ * If the user is signed into Joplin Cloud, AI works zero-config — they only
+ * need to flip the master toggle on.
+ *
+ * <span class="platform-desktop">desktop</span>
+ */
+export default class JoplinAi {
+    /**
+     * Sends a chat completion request to the active AI provider and returns the
+     * assistant's text response.
+     *
+     * The active provider and model are controlled by the user in Settings →
+     * AI. Plugins should not assume any particular provider or model.
+     *
+     * This call throws when:
+     *
+     * - AI features are disabled (`AI features are disabled`).
+     * - The active provider is remote and the user has not allowed remote
+     *   providers (`Remote AI access is not allowed`).
+     * - The provider is misconfigured, e.g. missing API key or model name
+     *   (`*provider* has no API key configured`).
+     * - The provider returns an HTTP error (the message includes the status
+     *   and any detail returned by the provider).
+     *
+     * Plugins should catch these errors and present a user-friendly message
+     * pointing the user at the Joplin settings.
+     *
+     * @example
+     * ```typescript
+     * const reply = await joplin.ai.chat([
+     *     { role: 'system', content: 'You are a concise assistant.' },
+     *     { role: 'user', content: 'Summarise this note: ...' },
+     * ]);
+     * console.log(reply);
+     * ```
+     */
+    chat(messages: ChatMessage[], options?: ChatOptions): Promise<string>;
+    /**
+     * Runs a semantic search against the locally-indexed embeddings and
+     * returns matching chunks ranked by similarity.
+     *
+     * The `query` is either plain text (which gets embedded internally) or
+     * `{ noteId }`, which reuses the note's already-indexed chunks as the
+     * query — useful for "find related notes" / tag suggestion / semantic
+     * graph use cases without spending another embedding pass.
+     *
+     * The `scope` restricts the search: `'all'` (default), `'note'`,
+     * `'folder'` (by folder id), or `'tag'` (by tag id).
+     * Trashed and conflict notes are excluded from results.
+     *
+     * The `relevance` preset controls how strict the match is:
+     * `'strict' | 'normal' | 'loose'`. Joplin owns the mapping from preset
+     * to model-specific (k, minScore) — plugins write against the preset
+     * and stay compatible when the bundled model changes.
+     *
+     * Throws when AI features are disabled or no embedding provider is
+     * active (e.g. ONNX failed to load on this platform).
+     *
+     * @example
+     * ```typescript
+     * const results = await joplin.ai.search({
+     *     query: { text: 'pizza dough hydration' },
+     *     relevance: 'normal',
+     * });
+     * for (const r of results) {
+     *     console.log(r.score, r.noteId, r.chunkText.slice(0, 80));
+     * }
+     * ```
+     */
+    search(options: SearchOptions): Promise<SearchResult[]>;
+}

api/JoplinClipboard.d.ts

@@ -1,8 +1,23 @@
 import { ClipboardContent } from './types';
+interface ElectronClipboardLike {
+    readText(): string;
+    writeText(text: string): void;
+    readHTML(): string;
+    writeHTML(html: string): void;
+    readImage(): {
+        toDataURL(): string;
+    } | null;
+    writeImage(image: unknown): void;
+    availableFormats(): string[];
+    write(data: Record<string, unknown>): void;
+}
+interface ElectronNativeImageLike {
+    createFromDataURL(dataUrl: string): unknown;
+}
 export default class JoplinClipboard {
     private electronClipboard_;
     private electronNativeImage_;
-    constructor(electronClipboard: any, electronNativeImage: any);
+    constructor(electronClipboard: ElectronClipboardLike, electronNativeImage: ElectronNativeImageLike);
     readText(): Promise<string>;
     writeText(text: string): Promise<void>;
     /** <span class="platform-desktop">desktop</span> */
@@ -43,3 +58,4 @@ export default class JoplinClipboard {
      */
     write(content: ClipboardContent): Promise<void>;
 }
+export {};

api/JoplinContentScripts.d.ts

@@ -1,4 +1,4 @@
-import Plugin from '../Plugin';
+import Plugin, { MessageListenerCallback } from '../Plugin';
 import { ContentScriptType } from './types';
 export default class JoplinContentScripts {
     private plugin;
@@ -37,5 +37,5 @@ export default class JoplinContentScripts {
      * [postMessage
      * demo](https://github.com/laurent22/joplin/tree/dev/packages/app-cli/tests/support/plugins/post_messages)
      */
-    onMessage(contentScriptId: string, callback: any): Promise<void>;
+    onMessage(contentScriptId: string, callback: MessageListenerCallback): Promise<void>;
 }

api/JoplinData.d.ts

@@ -1,4 +1,5 @@
 import { ModelType } from '../../../BaseModel';
+import { RequestFile } from '../../rest/Api';
 import Plugin from '../Plugin';
 import { Path } from './types';
 /**
@@ -45,8 +46,8 @@ export default class JoplinData {
     private serializeApiBody;
     private pathToString;
     get(path: Path, query?: any): Promise<any>;
-    post(path: Path, query?: any, body?: any, files?: any[]): Promise<any>;
-    put(path: Path, query?: any, body?: any, files?: any[]): Promise<any>;
+    post(path: Path, query?: any, body?: any, files?: RequestFile[]): Promise<any>;
+    put(path: Path, query?: any, body?: any, files?: RequestFile[]): Promise<any>;
     delete(path: Path, query?: any): Promise<any>;
     itemType(itemId: string): Promise<ModelType>;
     resourcePath(resourceId: string): Promise<string>;

api/JoplinFs.d.ts

@@ -0,0 +1,22 @@
+export interface ArchiveEntry {
+    entryName: string;
+    name: string;
+}
+/**
+ * Provides file system utilities for plugins.
+ *
+ * <span class="platform-desktop">desktop</span>
+ */
+export default class JoplinFs {
+    /**
+     * Extracts an archive to the specified directory. Currently only ZIP files
+     * are supported.
+     *
+     * <span class="platform-desktop">desktop</span>
+     *
+     * @param sourcePath Path to the archive file to extract
+     * @param destinationPath Path to the directory where the contents should be extracted
+     * @returns List of entries extracted from the archive
+     */
+    archiveExtract(sourcePath: string, destinationPath: string): Promise<ArchiveEntry[]>;
+}

api/JoplinImaging.d.ts

@@ -1,3 +1,4 @@
+import { ResourceEntity } from '../../database/types';
 import { Rectangle } from './types';
 export interface CreateFromBufferOptions {
     width?: number;
@@ -65,7 +66,10 @@ export default class JoplinImaging {
     createFromPdfResource(resourceId: string, options?: CreateFromPdfOptions): Promise<Handle[]>;
     getPdfInfoFromPath(path: string): Promise<PdfInfo>;
     getPdfInfoFromResource(resourceId: string): Promise<PdfInfo>;
-    getSize(handle: Handle): Promise<any>;
+    getSize(handle: Handle): Promise<{
+        width: number;
+        height: number;
+    }>;
     resize(handle: Handle, options?: ResizeOptions): Promise<string>;
     crop(handle: Handle, rectangle: Rectangle): Promise<string>;
     toPngFile(handle: Handle, filePath: string): Promise<void>;
@@ -78,12 +82,12 @@ export default class JoplinImaging {
      * Creates a new Joplin resource from the image data. The image will be
      * first converted to a JPEG.
      */
-    toJpgResource(handle: Handle, resourceProps: any, quality?: number): Promise<import("../../database/types").ResourceEntity>;
+    toJpgResource(handle: Handle, resourceProps: Partial<ResourceEntity>, quality?: number): Promise<ResourceEntity>;
     /**
      * Creates a new Joplin resource from the image data. The image will be
      * first converted to a PNG.
      */
-    toPngResource(handle: Handle, resourceProps: any): Promise<import("../../database/types").ResourceEntity>;
+    toPngResource(handle: Handle, resourceProps: Partial<ResourceEntity>): Promise<ResourceEntity>;
     /**
      * Image data is not automatically deleted by Joplin so make sure you call
      * this method on the handle once you are done.

api/JoplinSettings.d.ts

@@ -40,7 +40,7 @@ export default class JoplinSettings {
     /**
      * Gets setting values (only applies to setting you registered from your plugin)
      */
-    values(keys: string[] | string): Promise<Record<string, unknown>>;
+    values(keys: string[] | string): Promise<Record<string, any>>;
     /**
      * Gets a setting value (only applies to setting you registered from your plugin).
      *

api/JoplinViews.d.ts

@@ -1,4 +1,6 @@
+import { JoplinViews as JoplinViewsImplementation } from '../BasePlatformImplementation';
 import Plugin from '../Plugin';
+import { PluginStore } from '../ViewController';
 import JoplinViewsDialogs from './JoplinViewsDialogs';
 import JoplinViewsMenuItems from './JoplinViewsMenuItems';
 import JoplinViewsMenus from './JoplinViewsMenus';
@@ -32,7 +34,7 @@ export default class JoplinViews {
     private editors_;
     private noteList_;
     private implementation_;
-    constructor(implementation: any, plugin: Plugin, store: any);
+    constructor(implementation: JoplinViewsImplementation, plugin: Plugin, store: PluginStore);
     get dialogs(): JoplinViewsDialogs;
     get panels(): JoplinViewsPanels;
     get editors(): JoplinViewsEditors;

api/JoplinViewsDialogs.d.ts

@@ -1,5 +1,7 @@
 import Plugin from '../Plugin';
 import { ButtonSpec, ViewHandle, DialogResult, Toast } from './types';
+import { JoplinViewsDialogs as JoplinViewsDialogsImplementation, ShowOpenDialogOptions } from '../BasePlatformImplementation';
+import { PluginStore } from '../ViewController';
 /**
  * Allows creating and managing dialogs. A dialog is modal window that
  * contains a webview and a row of buttons. You can update the
@@ -33,7 +35,7 @@ export default class JoplinViewsDialogs {
     private store;
     private plugin;
     private implementation_;
-    constructor(implementation: any, plugin: Plugin, store: any);
+    constructor(implementation: JoplinViewsDialogsImplementation, plugin: Plugin, store: PluginStore);
     private controller;
     /**
      * Creates a new dialog
@@ -54,7 +56,7 @@ export default class JoplinViewsDialogs {
      *
      * <span class="platform-desktop">desktop</span>
      */
-    showOpenDialog(options: any): Promise<any>;
+    showOpenDialog(options: ShowOpenDialogOptions): Promise<string[] | null>;
     /**
      * Sets the dialog HTML content
      */

api/JoplinViewsEditor.d.ts

@@ -1,4 +1,5 @@
-import Plugin from '../Plugin';
+import Plugin, { MessageListenerCallback } from '../Plugin';
+import { PluginStore } from '../ViewController';
 import { ActivationCheckCallback, ViewHandle, UpdateCallback, EditorPluginCallbacks } from './types';
 interface SaveNoteOptions {
     /**
@@ -55,7 +56,7 @@ export default class JoplinViewsEditors {
     private plugin;
     private activationCheckHandlers_;
     private unhandledActivationCheck_;
-    constructor(plugin: Plugin, store: any);
+    constructor(plugin: Plugin, store: PluginStore);
     private controller;
     /**
      * Registers a new editor plugin. Joplin will call the provided callback to create new editor views
@@ -79,7 +80,7 @@ export default class JoplinViewsEditors {
     /**
      * See [[JoplinViewPanels]]
      */
-    onMessage(handle: ViewHandle, callback: Function): Promise<void>;
+    onMessage(handle: ViewHandle, callback: MessageListenerCallback): Promise<void>;
     /**
      * Saves the content of the editor, without calling `onUpdate` for editors in the same window.
      */

api/JoplinViewsMenuItems.d.ts

@@ -1,5 +1,6 @@
 import { CreateMenuItemOptions, MenuItemLocation } from './types';
 import Plugin from '../Plugin';
+import { PluginStore } from '../ViewController';
 /**
  * Allows creating and managing menu items.
  *
@@ -10,7 +11,7 @@ import Plugin from '../Plugin';
 export default class JoplinViewsMenuItems {
     private store;
     private plugin;
-    constructor(plugin: Plugin, store: any);
+    constructor(plugin: Plugin, store: PluginStore);
     /**
      * Creates a new menu item and associate it with the given command. You can specify under which menu the item should appear using the `location` parameter.
      */

api/JoplinViewsMenus.d.ts

@@ -1,5 +1,6 @@
 import { MenuItem, MenuItemLocation } from './types';
 import Plugin from '../Plugin';
+import { PluginStore } from '../ViewController';
 /**
  * Allows creating menus.
  *
@@ -10,7 +11,7 @@ import Plugin from '../Plugin';
 export default class JoplinViewsMenus {
     private store;
     private plugin;
-    constructor(plugin: Plugin, store: any);
+    constructor(plugin: Plugin, store: PluginStore);
     private registerCommandAccelerators;
     /**
      * Creates a new menu from the provided menu items and place it at the given location. As of now, it is only possible to place the

api/JoplinViewsPanels.d.ts

@@ -1,4 +1,5 @@
-import Plugin from '../Plugin';
+import Plugin, { MessageListenerCallback } from '../Plugin';
+import { PluginStore } from '../ViewController';
 import { ViewHandle } from './types';
 /**
  * Allows creating and managing view panels. View panels allow displaying any HTML
@@ -17,7 +18,7 @@ import { ViewHandle } from './types';
 export default class JoplinViewsPanels {
     private store;
     private plugin;
-    constructor(plugin: Plugin, store: any);
+    constructor(plugin: Plugin, store: PluginStore);
     private controller;
     /**
      * Creates a new panel
@@ -50,7 +51,7 @@ export default class JoplinViewsPanels {
      * demo](https://github.com/laurent22/joplin/tree/dev/packages/app-cli/tests/support/plugins/post_messages) for more details.
      *
      */
-    onMessage(handle: ViewHandle, callback: Function): Promise<void>;
+    onMessage(handle: ViewHandle, callback: MessageListenerCallback): Promise<void>;
     /**
      * Sends a message to the webview.
      *