@isdk/tool-electron 1.0.0

package/dist/index.d.mts

@@ -0,0 +1,463 @@
+import { ClientToolTransport, Funcs, ActionName, ServerToolTransport, RpcServerDispatcher, ToolRpcRequest, ToolRpcResponse } from '@isdk/tool-rpc';
+import { IpcMainEvent, WebContents } from 'electron';
+import { IPubSubServerTransport, PubSubServerSession, PubSubCtx, IPubSubClientTransport, PubSubClientStream } from '@isdk/tool-event';
+
+/**
+ * Bridge type for Electron IPC transports.
+ *
+ * All four bridge types are the single source of truth for injectable
+ * IPC methods used by the renderer-side (`Bridge`, `PubSubBridge`) and
+ * main-side (`ServerIpcMain`, `ServerPubSubIpcMain`) transports.
+ *
+ * Import directly:
+ * ```ts
+ * import { Bridge, ServerIpcMain, PubSubBridge, ServerPubSubIpcMain } from '@isdk/tool-electron';
+ * ```
+ */
+/**
+ * Renderer-side RPC bridge.
+ * Injected into {@link import('./ipc-client').IpcClientToolTransport}
+ * to call `ipcRenderer.invoke` via `contextBridge` instead of importing `electron` directly.
+ */
+type Bridge = {
+    invoke: (channel: string, ...args: any[]) => Promise<any>;
+};
+/**
+ * Main-side RPC bridge.
+ * Injected into {@link import('./ipc-server').IpcServerToolTransport}
+ * to register `ipcMain.handle` handlers via a custom object (e.g. mock).
+ */
+type ServerIpcMain = {
+    handle(channel: string, handler: (event: any, ...args: any[]) => any): void;
+    removeHandler(channel: string): void;
+};
+/**
+ * Renderer-side Pub/Sub bridge.
+ * Injected into {@link import('./pubsub/electron-client').ElectronClientPubSubTransport}
+ * to listen, remove listeners, and send IPC messages for the event bus.
+ */
+type PubSubBridge = {
+    on(channel: string, listener: (event: any, ...args: any[]) => void): void;
+    off(channel: string, listener: (event: any, ...args: any[]) => void): void;
+    send(channel: string, ...args: any[]): void;
+};
+/**
+ * Main-side Pub/Sub bridge.
+ * Injected into {@link import('./pubsub/electron-server').ElectronServerPubSubTransport}
+ * to register `ipcMain.on` listeners and clean them up via a custom object.
+ */
+type ServerPubSubIpcMain = {
+    on(channel: string, listener: (...args: any[]) => void): void;
+    removeAllListeners(channel?: string): void;
+};
+type Channels = {
+    discover: string;
+    rpc: string;
+};
+
+/**
+ * IpcClientToolTransport — Electron renderer-side RPC transport.
+ *
+ * Uses `ipcRenderer.invoke` (or an injectable bridge) to call server tools
+ * over Electron IPC channels. The `apiUrl` follows the `electron://` URI convention:
+ *
+ * ```ts
+ * const transport = new IpcClientToolTransport('electron://my-app', { bridge });
+ * // → channels: my-app:discover, my-app:rpc
+ * ```
+ *
+ * The `electron` scheme is auto-registered with `RpcTransportManager` on import,
+ * so `RpcTransportManager.instance.getClient('electron://my-app')` works automatically.
+ *
+ * @example
+ * ```ts
+ * // preload.ts — expose minimal bridge
+ * import { contextBridge, ipcRenderer } from 'electron';
+ * contextBridge.exposeInMainWorld('electronIpc', {
+ *   invoke: (ch: string, ...args: any[]) => ipcRenderer.invoke(ch, ...args),
+ * });
+ *
+ * // renderer.ts
+ * const transport = new IpcClientToolTransport('electron://my-app', {
+ *   bridge: (window as any).electronIpc,
+ * });
+ * await transport.loadApis();
+ * const result = await transport._fetch('greet', { name: 'World' });
+ * ```
+ */
+
+type IpcClientToolTransportOptions = {
+    apiUrl?: string;
+    /**
+     * Optional custom bridge object with an `invoke` method,
+     * for use with contextBridge in secure Electron apps.
+     * When provided, this bridge's invoke is used instead of directly
+     * importing `ipcRenderer`.
+     */
+    bridge?: Bridge;
+    [key: string]: any;
+};
+/**
+ * Renderer-side RPC transport over Electron IPC.
+ *
+ * @param apiUrl - URI in `electron://host` format; defaults to `IPCDefaultChannelName`
+ *   (see {@link normalizeNamespace} for URI extraction logic).
+ * @param options - Optional config.
+ * @param options.bridge - Injectable bridge object with `invoke` method.
+ *   When provided, used instead of directly importing `ipcRenderer`.
+ *   Required when `contextIsolation` is enabled.
+ */
+declare class IpcClientToolTransport extends ClientToolTransport {
+    channels: Channels;
+    private _bridge?;
+    constructor(apiUrl?: string, options?: IpcClientToolTransportOptions);
+    /**
+     * Mount the transport to a tools class and register with RpcTransportManager.
+     * @param toolsClass - The client tools class to mount (e.g., `ClientTools`).
+     */
+    mount(toolsClass: any): void;
+    /**
+     * Set the API URL and derive IPC channel names.
+     * @param apiUrl - URI in `electron://host` format (e.g., `'electron://my-app'`).
+     *   The host is extracted as the namespace for channel generation:
+     *   `electron://my-app` → channels `my-app:discover`, `my-app:rpc`.
+     */
+    setApiUrl(apiUrl: string): void;
+    /** @deprecated Use {@link setApiUrl} instead */
+    setApiRoot(apiRoot: string): void;
+    /**
+     * Load available tool definitions from the server via IPC.
+     * Invokes the `{namespace}:discover` channel to fetch the tool manifest.
+     * @returns A promise resolving to the tool function definitions.
+     * @throws If `apiUrl` has not been set (channels not initialized).
+     */
+    loadApis(): Promise<Funcs>;
+    /**
+     * Call a remote tool via IPC.
+     * Sends an RPC request on the `{namespace}:rpc` channel and returns the result.
+     * Server errors (`{ __error__: true, error: ... }`) are automatically re-thrown as `CommonError`.
+     *
+     * @param name - Tool name (becomes `toolId` in the IPC payload).
+     * @param args - Parameters to pass to the tool.
+     * @param act - Optional action name for REST-style sub-resources.
+     * @param subName - Optional sub-resource identifier.
+     * @param _fetchOptions - Optional fetch options (e.g., `{ signal: AbortSignal }` for cancellation).
+     * @returns The tool's return value.
+     * @throws {CommonError} If the server returns an error response.
+     * @throws {AbortError} If the request is cancelled via `AbortSignal`.
+     */
+    _fetch(name: string, args?: any, act?: ActionName | string, subName?: any, _fetchOptions?: any): Promise<any>;
+    /**
+     * Convert an IPC response to a plain object.
+     * If the response contains a server error (`{ __error__: true }`),
+     * it is re-thrown as a `CommonError`.
+     * Otherwise, the response is passed through as-is.
+     *
+     * @param res - The raw response from the IPC channel.
+     * @returns The deserialized result.
+     * @throws {CommonError} If the response indicates a server error.
+     * @deprecated Use `_fetch` directly, which throws `CommonError` automatically.
+     */
+    toObject(res: any): Promise<any>;
+}
+
+/**
+ * Main-process RPC transport over Electron IPC.
+ *
+ * Registers `ipcMain.handle` listeners for tool discovery and RPC calls.
+ * Supports injectable `ipcMain` bridge for testing or custom setups.
+ */
+declare class IpcServerToolTransport extends ServerToolTransport {
+    private channels;
+    private started;
+    private _ipcMain;
+    /**
+     * Creates an IPC server transport.
+     * @param options.apiUrl - URI in `electron://host` format (e.g., `'electron://my-app'`).
+     *   The host is extracted as the namespace for IPC channel generation:
+     *   `electron://my-app` → channels `my-app:discover`, `my-app:rpc`.
+     *   Defaults to {@link IPCDefaultChannelName} (`'electron://ai-tool'`).
+     * @param options.dispatcher - Optional RpcServerDispatcher for v2.6 dispatch pattern.
+     * @param options.ipcMain - Optional custom ipcMain bridge (with `handle` and `removeHandler` methods).
+     *   When provided, used instead of the direct `electron` import.
+     *   Useful for testing or custom main-process IPC setups.
+     */
+    constructor(options?: {
+        apiUrl?: string;
+        dispatcher?: RpcServerDispatcher;
+        ipcMain?: ServerIpcMain;
+        [key: string]: any;
+    });
+    /**
+     * Set the API URL and derive IPC channel names.
+     * @param apiUrl - URI in `electron://host` format (e.g., `'electron://my-app'`).
+     *   The host is extracted as the namespace for channel generation:
+     *   `electron://my-app` → channels `my-app:discover`, `my-app:rpc`.
+     */
+    setApiUrl(apiUrl: string): void;
+    /** @deprecated Use setApiUrl instead */
+    setApiRoot(apiRoot: string): void;
+    private ensureChannels;
+    /**
+     * Register an IPC handler for tool discovery.
+     * Listens on the `{namespace}:discover` channel and returns the tool manifest.
+     * Automatically removes any previous handler for the same channel to prevent duplicates.
+     *
+     * @param apiPrefix - URI or namespace for the IPC channel (e.g., `'electron://my-app'`).
+     * @param handler - Function returning the tool definitions.
+     *   If the return value has a `toJSON()` method, it is called for serialization.
+     */
+    addDiscoveryHandler(apiPrefix: string, handler: () => any): void;
+    /**
+     * Register an IPC handler for RPC calls.
+     * Listens on the `{namespace}:rpc` channel and routes incoming requests
+     * to the appropriate tool handler. In v2.6, uses the dispatcher for routing
+     * when available; falls back to direct tool lookup for backward compatibility.
+     *
+     * @param apiPrefix - URI or namespace for the IPC channel (e.g., `'electron://my-app'`).
+     * @param options - Optional config.
+     * @param options.registry - A Tools class (with static `.get()`) or a map-like registry
+     *   (with `.get()` method). Defaults to `ServerTools`.
+     * @param options.tools - Alias for `options.registry`. If both are provided, `tools` takes precedence.
+     */
+    addRpcHandler(apiPrefix: string, options?: {
+        registry?: any;
+        tools?: any;
+        [key: string]: any;
+    }): void;
+    protected toRpcRequest(rawReq: any, rawRes?: any): Promise<ToolRpcRequest>;
+    protected sendRpcResponse(rpcRes: ToolRpcResponse, rawRes: any): Promise<void>;
+    private toErrorResponse;
+    /**
+     * Start the transport (marks as started).
+     * IPC handlers are already registered via `addRpcHandler`/`addDiscoveryHandler`,
+     * so this method primarily serves as a lifecycle flag.
+     */
+    _start(): Promise<void>;
+    /**
+     * Stop the transport and remove IPC handlers.
+     * @param force - If `true`, skip the `started` check and always stop.
+     */
+    stop(force?: boolean): Promise<void>;
+    /**
+     * Get the raw IPC main object and channel names.
+     * Useful for testing and introspection.
+     */
+    getRaw(): {
+        ipcMain: ServerIpcMain;
+        channels: Channels;
+    };
+    /**
+     * Get the listen address (URI) for this transport.
+     * Returns the `apiUrl` in `electron://` format (e.g., `'electron://my-app'`),
+     * or the default `IPCDefaultChannelName` if not set.
+     */
+    getListenAddr(): string;
+    /**
+     * Get the routes exposed by this transport.
+     * IPC transports expose a single root route `['/']`.
+     */
+    getRoutes(): string[];
+}
+
+/**
+ * ElectronServerPubSubTransport — Electron main-process Pub/Sub transport.
+ *
+ * Manages client sessions and broadcasts events over Electron IPC channels.
+ * Compatible with {@link ElectronClientPubSubTransport} in the renderer.
+ *
+ * IPC channel naming (derived from the namespace via {@link normalizeNamespace}):
+ * - `pubsub-downstream:{ns}` — server → client events
+ * - `pubsub-upstream:{ns}` — client → server events
+ * - `pubsub-connect:{ns}` — initiate connection
+ * - `pubsub-disconnect:{ns}` — disconnect session
+ *
+ * @example
+ * ```ts
+ * const pubSubServer = new ElectronServerPubSubTransport('electron://my-app-events');
+ * pubSubServer.listen();
+ * pubSubServer.publish('server-event', { msg: 'hello' });
+ * ```
+ */
+
+/**
+ * Main-process Pub/Sub transport over Electron IPC.
+ *
+ * @param namespace - Namespace in `electron://` URI format (e.g., `'electron://my-app'`).
+ *   Used to derive all IPC channel names for PubSub communication.
+ *   Must be non-empty.
+ * @param options - Optional config.
+ * @param options.ipcMain - Injectable bridge with `on`, `removeAllListeners` methods.
+ *   When provided, used instead of directly importing `ipcMain`.
+ */
+declare class ElectronServerPubSubTransport implements IPubSubServerTransport {
+    readonly name = "electron";
+    readonly protocol: "electron";
+    private sessions;
+    private subscriptions;
+    private onConn?;
+    private onDis?;
+    private onMsg?;
+    private channels;
+    private _listenersInitialized;
+    private _ipcMain;
+    constructor(namespace: string, options?: {
+        ipcMain?: ServerPubSubIpcMain;
+    });
+    /**
+     * Activates the transport by setting up listeners for IPC events.
+     * This method should be called once in the main process during application setup.
+     */
+    listen(): void;
+    /**
+     * Connect a client session.
+     * Called internally by the IPC listener (registered in {@link listen}) when
+     * a client sends a `pubsub-connect:{ns}` message. Creates a `PubSubServerSession`
+     * for the new client and stores it for event broadcasting.
+     *
+     * @param options.req - The `IpcMainEvent` from Electron IPC.
+     * @param options.res - The `WebContents` of the client window.
+     * @param options.events - Optional initial event subscriptions for the session.
+     * @returns The newly created `PubSubServerSession`.
+     * @throws If `req` or `res` are not provided.
+     */
+    connect(options?: {
+        req: IpcMainEvent;
+        res: WebContents;
+        events?: string[];
+    }): PubSubServerSession;
+    private handleDisconnect;
+    /**
+     * Subscribe a client session to one or more events.
+     * Events must be subscribed before they can be received by the client.
+     * @param session - The client session to subscribe.
+     * @param events - Array of event names to subscribe to.
+     */
+    subscribe(session: PubSubServerSession, events: string[]): void;
+    /**
+     * Unsubscribe a client session from one or more events.
+     * @param session - The client session to unsubscribe.
+     * @param events - Array of event names to unsubscribe from.
+     */
+    unsubscribe(session: PubSubServerSession, events: string[]): void;
+    /**
+     * Publish an event to connected clients.
+     * If `target.clientId` is provided, only the specified client(s) receive the event.
+     * Otherwise, the event is broadcast to all subscribed clients.
+     *
+     * @param event - The event name to publish.
+     * @param data - The event payload.
+     * @param target - Optional target specification for directed delivery.
+     * @param target.clientId - A single client ID or array of client IDs to target.
+     * @param ctx - Optional PubSub context.
+     */
+    publish(event: string, data: any, target?: {
+        clientId?: string | string[];
+    }, ctx?: PubSubCtx): void;
+    /**
+     * Register a callback for new client connections.
+     * @param cb - Callback receiving the new `PubSubServerSession`.
+     */
+    onConnection(cb: (s: PubSubServerSession) => void): void;
+    /**
+     * Register a callback for client disconnections.
+     * @param cb - Callback receiving the disconnected `PubSubServerSession`.
+     */
+    onDisconnect(cb: (s: PubSubServerSession) => void): void;
+    /**
+     * Register a callback for incoming messages from clients.
+     * @param cb - Callback receiving the session, event name, data, and optional context.
+     */
+    onMessage(cb: (session: PubSubServerSession, event: string, data: any, ctx?: PubSubCtx) => void): void;
+    /**
+     * Clean up all IPC listeners and session state.
+     * Removes `connect`, `disconnect`, and `upstream` IPC listeners,
+     * clears all sessions and subscriptions.
+     * Should be called when the transport is no longer needed (e.g., during app shutdown).
+     */
+    cleanup(): void;
+    /**
+     * Find a client session by its IPC request event.
+     * @param req - The `IpcMainEvent` to look up.
+     * @returns The corresponding `PubSubServerSession`, or `undefined` if not found.
+     */
+    getSessionFromReq(req: IpcMainEvent): PubSubServerSession | undefined;
+}
+
+/**
+ * ElectronClientPubSubTransport — Electron renderer-side Pub/Sub transport.
+ *
+ * Uses `ipcRenderer` (or an injectable bridge) to send and receive real-time
+ * events over Electron IPC PubSub channels.
+ *
+ * IPC channel naming (derived from the namespace via {@link normalizeNamespace}):
+ * - `pubsub-downstream:{ns}` — server → client events
+ * - `pubsub-upstream:{ns}` — client → server events
+ * - `pubsub-connect:{ns}` — initiate connection
+ * - `pubsub-disconnect:{ns}` — disconnect session
+ *
+ * @example
+ * ```ts
+ * const pubsub = new ElectronClientPubSubTransport('electron://my-app-events', {
+ *   bridge: { on: ipcRenderer.on, off: ipcRenderer.off, send: ipcRenderer.send },
+ * });
+ * const stream = pubsub.connect('my-app-events');
+ * stream.on('server-event', (data) => console.log('received:', data));
+ * ```
+ */
+
+/**
+ * Renderer-side Pub/Sub transport over Electron IPC.
+ *
+ * @param apiRoot - Namespace for IPC channel generation. Supports `electron://` URI format
+ *   (e.g., `'electron://my-app'` → namespace `my-app`). Defaults to empty string
+ *   (call {@link setApiRoot} before {@link connect}).
+ * @param options - Optional config.
+ * @param options.bridge - Injectable bridge with `on`, `off`, and `send` methods.
+ *   When provided, used instead of directly importing `ipcRenderer`.
+ */
+declare class ElectronClientPubSubTransport implements IPubSubClientTransport {
+    private apiRoot;
+    private channels?;
+    private ipcListenerAttached;
+    private allListeners;
+    private _bridge?;
+    constructor(apiRoot?: string, options?: {
+        bridge?: PubSubBridge;
+    });
+    /**
+     * Set the API root (namespace) and derive IPC channel names.
+     * @param apiRoot - Namespace in `electron://` URI format (e.g., `'electron://my-app'`).
+     *   The host is extracted as the namespace for PubSub channel generation.
+     */
+    setApiRoot(apiRoot: string): void;
+    private onMessage;
+    private ensureIpcListener;
+    /**
+     * Establish a PubSub connection stream.
+     * Sends a `pubsub-connect:{ns}` IPC message and returns a `PubSubClientStream`
+     * for subscribing to events and sending messages upstream.
+     *
+     * @param toolName - Logical connection name (not used for channel routing;
+     *   channels are derived from the constructor's `apiRoot`).
+     * @param params - Optional connection parameters (e.g., `{ events: ['event-a', 'event-b'] }`
+     *   for initial event subscriptions).
+     * @returns A `PubSubClientStream` instance.
+     */
+    connect(toolName: string, params?: any): PubSubClientStream;
+    /**
+     * Disconnect a PubSub stream.
+     * Delegates to `stream.close()` which sends a `pubsub-disconnect:{ns}` IPC message
+     * and cleans up local event listeners.
+     * @param stream - The stream to disconnect.
+     */
+    disconnect(stream: PubSubClientStream): void;
+    /**
+     * Clean up all IPC listeners and event subscriptions.
+     * Removes the downstream IPC listener and clears all registered event handlers.
+     * Should be called when the transport is no longer needed (e.g., when the window closes).
+     */
+    cleanup(): Promise<void>;
+}
+
+export { type Bridge, type Channels, ElectronClientPubSubTransport, ElectronServerPubSubTransport, IpcClientToolTransport, IpcServerToolTransport, type PubSubBridge, type ServerIpcMain, type ServerPubSubIpcMain };