@ashdev/codex-plugin-sdk 1.9.3 → 1.10.0

package/dist/server.js

@@ -1,10 +1,19 @@
 /**
  * Plugin server - handles JSON-RPC communication over stdio
+ *
+ * Provides factory functions for creating different plugin types.
+ * All plugin types share a common base server that handles:
+ * - stdin readline parsing
+ * - JSON-RPC error handling
+ * - initialize/ping/shutdown lifecycle methods
+ *
+ * Each plugin type adds its own method routing on top.
  */
 import { createInterface } from "node:readline";
 import { PluginError } from "./errors.js";
 import { createLogger } from "./logger.js";
-import { JSON_RPC_ERROR_CODES, } from "./types/rpc.js";
+import { PluginStorage } from "./storage.js";
+import { JSON_RPC_ERROR_CODES } from "./types/rpc.js";
 /**
  * Validate that the required string fields are present and non-empty
  */
@@ -87,78 +96,29 @@ function invalidParamsError(id, error) {
     };
 }
 /**
- * Create and run a metadata provider plugin
- *
- * Creates a plugin server that handles JSON-RPC communication over stdio.
- * The TypeScript compiler will ensure you implement all required methods.
- *
- * @example
- * ```typescript
- * import { createMetadataPlugin, type MetadataProvider } from "@ashdev/codex-plugin-sdk";
+ * Shared plugin server that handles JSON-RPC communication over stdio.
  *
- * const provider: MetadataProvider = {
- *   async search(params) {
- *     return {
- *       results: [{
- *         externalId: "123",
- *         title: "Example",
- *         alternateTitles: [],
- *         relevanceScore: 0.95,
- *       }],
- *     };
- *   },
- *   async get(params) {
- *     return {
- *       externalId: params.externalId,
- *       externalUrl: "https://example.com/123",
- *       alternateTitles: [],
- *       genres: [],
- *       tags: [],
- *       authors: [],
- *       artists: [],
- *       externalLinks: [],
- *     };
- *   },
- * };
- *
- * createMetadataPlugin({
- *   manifest: {
- *     name: "my-plugin",
- *     displayName: "My Plugin",
- *     version: "1.0.0",
- *     description: "Example plugin",
- *     author: "Me",
- *     protocolVersion: "1.0",
- *     capabilities: { metadataProvider: ["series"] },
- *   },
- *   provider,
- * });
- * ```
+ * Handles the common lifecycle methods (initialize, ping, shutdown) and
+ * delegates capability-specific methods to the provided router.
  */
-export function createMetadataPlugin(options) {
-    const { manifest, provider, bookProvider, onInitialize, logLevel = "info" } = options;
+function createPluginServer(options) {
+    const { manifest, onInitialize, logLevel = "info", label, router } = options;
     const logger = createLogger({ name: manifest.name, level: logLevel });
-    // Validate that required providers are present based on manifest
-    const contentTypes = manifest.capabilities.metadataProvider;
-    if (contentTypes.includes("series") && !provider) {
-        throw new Error("Series metadata provider is required when 'series' is in metadataProvider capabilities");
-    }
-    if (contentTypes.includes("book") && !bookProvider) {
-        throw new Error("Book metadata provider is required when 'book' is in metadataProvider capabilities");
-    }
-    logger.info(`Starting plugin: ${manifest.displayName} v${manifest.version}`);
+    const prefix = label ? `${label} plugin` : "plugin";
+    const storage = new PluginStorage();
+    logger.info(`Starting ${prefix}: ${manifest.displayName} v${manifest.version}`);
     const rl = createInterface({
         input: process.stdin,
         terminal: false,
     });
     rl.on("line", (line) => {
-        void handleLine(line, manifest, provider, bookProvider, onInitialize, logger);
+        void handleLine(line, manifest, onInitialize, router, logger, storage);
     });
     rl.on("close", () => {
         logger.info("stdin closed, shutting down");
+        storage.cancelAll();
         process.exit(0);
     });
-    // Handle uncaught errors
     process.on("uncaughtException", (error) => {
         logger.error("Uncaught exception", error);
         process.exit(1);
@@ -167,47 +127,50 @@ export function createMetadataPlugin(options) {
         logger.error("Unhandled rejection", reason);
     });
 }
-// =============================================================================
-// Backwards Compatibility (deprecated)
-// =============================================================================
 /**
- * @deprecated Use createMetadataPlugin instead
+ * Detect whether a parsed JSON object is a JSON-RPC response (not a request).
+ *
+ * A response has `id` and either `result` or `error`, but no `method`.
+ * A request always has `method`.
  */
-export function createSeriesMetadataPlugin(options) {
-    // Convert legacy options to new format
-    const newOptions = {
-        ...options,
-        manifest: {
-            ...options.manifest,
-            capabilities: {
-                ...options.manifest.capabilities,
-                metadataProvider: ["series"],
-            },
-        },
-    };
-    createMetadataPlugin(newOptions);
+function isJsonRpcResponse(obj) {
+    if (obj.method !== undefined)
+        return false;
+    if (obj.id === undefined || obj.id === null)
+        return false;
+    return "result" in obj || "error" in obj;
 }
-// =============================================================================
-// Internal Implementation
-// =============================================================================
-async function handleLine(line, manifest, provider, bookProvider, onInitialize, logger) {
+async function handleLine(line, manifest, onInitialize, router, logger, storage) {
     const trimmed = line.trim();
     if (!trimmed)
         return;
+    // Try to detect storage responses before full request handling.
+    // Storage responses come from the host on stdin — they have id + (result|error)
+    // but no method field.
+    let parsed;
+    try {
+        parsed = JSON.parse(trimmed);
+    }
+    catch {
+        // Will be handled as a parse error below
+    }
+    if (parsed && isJsonRpcResponse(parsed)) {
+        logger.debug("Routing storage response", { id: parsed.id });
+        storage.handleResponse(trimmed);
+        return;
+    }
     let id = null;
     try {
-        const request = JSON.parse(trimmed);
+        const request = (parsed ?? JSON.parse(trimmed));
         id = request.id;
         logger.debug(`Received request: ${request.method}`, { id: request.id });
-        const response = await handleRequest(request, manifest, provider, bookProvider, onInitialize, logger);
-        // Shutdown handler writes response directly and returns null
+        const response = await handleRequest(request, manifest, onInitialize, router, logger, storage);
         if (response !== null) {
             writeResponse(response);
         }
     }
     catch (error) {
         if (error instanceof SyntaxError) {
-            // JSON parse error
             writeResponse({
                 jsonrpc: "2.0",
                 id: null,
@@ -238,205 +201,278 @@ async function handleLine(line, manifest, provider, bookProvider, onInitialize,
         }
     }
 }
-async function handleRequest(request, manifest, provider, bookProvider, onInitialize, logger) {
+async function handleRequest(request, manifest, onInitialize, router, logger, storage) {
     const { method, params, id } = request;
+    // Common lifecycle methods
     switch (method) {
-        case "initialize":
-            // Call onInitialize callback if provided (to receive credentials/config)
+        case "initialize": {
+            const initParams = (params ?? {});
+            // Inject the storage client so plugins can persist data
+            initParams.storage = storage;
             if (onInitialize) {
-                await onInitialize(params);
+                await onInitialize(initParams);
             }
-            return {
-                jsonrpc: "2.0",
-                id,
-                result: manifest,
-            };
+            return { jsonrpc: "2.0", id, result: manifest };
+        }
         case "ping":
-            return {
-                jsonrpc: "2.0",
-                id,
-                result: "pong",
-            };
+            return { jsonrpc: "2.0", id, result: "pong" };
         case "shutdown": {
             logger.info("Shutdown requested");
-            // Write response directly with callback to ensure it's flushed before exit
-            const response = {
-                jsonrpc: "2.0",
-                id,
-                result: null,
-            };
+            storage.cancelAll();
+            const response = { jsonrpc: "2.0", id, result: null };
             process.stdout.write(`${JSON.stringify(response)}\n`, () => {
-                // Callback is called after the write is flushed to the OS
                 process.exit(0);
             });
-            // Return a sentinel that handleLine will recognize and skip normal writeResponse
+            // Response already written above; return null so handleLine skips the write
             return null;
         }
-        // =========================================================================
-        // Series metadata methods
-        // =========================================================================
-        case "metadata/series/search": {
-            if (!provider) {
-                return {
-                    jsonrpc: "2.0",
-                    id,
-                    error: {
-                        code: JSON_RPC_ERROR_CODES.METHOD_NOT_FOUND,
-                        message: "This plugin does not support series metadata",
-                    },
-                };
-            }
-            const validationError = validateSearchParams(params);
-            if (validationError) {
-                return invalidParamsError(id, validationError);
-            }
-            return {
-                jsonrpc: "2.0",
-                id,
-                result: await provider.search(params),
-            };
-        }
-        case "metadata/series/get": {
-            if (!provider) {
-                return {
-                    jsonrpc: "2.0",
-                    id,
-                    error: {
-                        code: JSON_RPC_ERROR_CODES.METHOD_NOT_FOUND,
-                        message: "This plugin does not support series metadata",
-                    },
-                };
-            }
-            const validationError = validateGetParams(params);
-            if (validationError) {
-                return invalidParamsError(id, validationError);
+    }
+    // Delegate to capability-specific router
+    const response = await router(method, params, id);
+    if (response !== null) {
+        return response;
+    }
+    // Unknown method
+    return {
+        jsonrpc: "2.0",
+        id,
+        error: {
+            code: JSON_RPC_ERROR_CODES.METHOD_NOT_FOUND,
+            message: `Method not found: ${method}`,
+        },
+    };
+}
+function writeResponse(response) {
+    process.stdout.write(`${JSON.stringify(response)}\n`);
+}
+// =============================================================================
+// Response Helpers
+// =============================================================================
+function methodNotFound(id, message) {
+    return {
+        jsonrpc: "2.0",
+        id,
+        error: {
+            code: JSON_RPC_ERROR_CODES.METHOD_NOT_FOUND,
+            message,
+        },
+    };
+}
+function success(id, result) {
+    return { jsonrpc: "2.0", id, result };
+}
+/**
+ * Create and run a metadata provider plugin
+ *
+ * Creates a plugin server that handles JSON-RPC communication over stdio.
+ * The TypeScript compiler will ensure you implement all required methods.
+ *
+ * @example
+ * ```typescript
+ * import { createMetadataPlugin, type MetadataProvider } from "@ashdev/codex-plugin-sdk";
+ *
+ * const provider: MetadataProvider = {
+ *   async search(params) {
+ *     return {
+ *       results: [{
+ *         externalId: "123",
+ *         title: "Example",
+ *         alternateTitles: [],
+ *         relevanceScore: 0.95,
+ *       }],
+ *     };
+ *   },
+ *   async get(params) {
+ *     return {
+ *       externalId: params.externalId,
+ *       externalUrl: "https://example.com/123",
+ *       alternateTitles: [],
+ *       genres: [],
+ *       tags: [],
+ *       authors: [],
+ *       artists: [],
+ *       externalLinks: [],
+ *     };
+ *   },
+ * };
+ *
+ * createMetadataPlugin({
+ *   manifest: {
+ *     name: "my-plugin",
+ *     displayName: "My Plugin",
+ *     version: "1.0.0",
+ *     description: "Example plugin",
+ *     author: "Me",
+ *     protocolVersion: "1.0",
+ *     capabilities: { metadataProvider: ["series"] },
+ *   },
+ *   provider,
+ * });
+ * ```
+ */
+export function createMetadataPlugin(options) {
+    const { manifest, provider, bookProvider, onInitialize, logLevel } = options;
+    // Validate that required providers are present based on manifest
+    const contentTypes = manifest.capabilities.metadataProvider;
+    if (contentTypes.includes("series") && !provider) {
+        throw new Error("Series metadata provider is required when 'series' is in metadataProvider capabilities");
+    }
+    if (contentTypes.includes("book") && !bookProvider) {
+        throw new Error("Book metadata provider is required when 'book' is in metadataProvider capabilities");
+    }
+    const router = async (method, params, id) => {
+        switch (method) {
+            // Series metadata methods
+            case "metadata/series/search": {
+                if (!provider)
+                    return methodNotFound(id, "This plugin does not support series metadata");
+                const err = validateSearchParams(params);
+                if (err)
+                    return invalidParamsError(id, err);
+                return success(id, await provider.search(params));
             }
-            return {
-                jsonrpc: "2.0",
-                id,
-                result: await provider.get(params),
-            };
-        }
-        case "metadata/series/match": {
-            if (!provider) {
-                return {
-                    jsonrpc: "2.0",
-                    id,
-                    error: {
-                        code: JSON_RPC_ERROR_CODES.METHOD_NOT_FOUND,
-                        message: "This plugin does not support series metadata",
-                    },
-                };
+            case "metadata/series/get": {
+                if (!provider)
+                    return methodNotFound(id, "This plugin does not support series metadata");
+                const err = validateGetParams(params);
+                if (err)
+                    return invalidParamsError(id, err);
+                return success(id, await provider.get(params));
             }
-            if (!provider.match) {
-                return {
-                    jsonrpc: "2.0",
-                    id,
-                    error: {
-                        code: JSON_RPC_ERROR_CODES.METHOD_NOT_FOUND,
-                        message: "This plugin does not support series match",
-                    },
-                };
+            case "metadata/series/match": {
+                if (!provider)
+                    return methodNotFound(id, "This plugin does not support series metadata");
+                if (!provider.match)
+                    return methodNotFound(id, "This plugin does not support series match");
+                const err = validateMatchParams(params);
+                if (err)
+                    return invalidParamsError(id, err);
+                return success(id, await provider.match(params));
             }
-            const validationError = validateMatchParams(params);
-            if (validationError) {
-                return invalidParamsError(id, validationError);
+            // Book metadata methods
+            case "metadata/book/search": {
+                if (!bookProvider)
+                    return methodNotFound(id, "This plugin does not support book metadata");
+                const err = validateBookSearchParams(params);
+                if (err)
+                    return invalidParamsError(id, err);
+                return success(id, await bookProvider.search(params));
             }
-            return {
-                jsonrpc: "2.0",
-                id,
-                result: await provider.match(params),
-            };
-        }
-        // =========================================================================
-        // Book metadata methods
-        // =========================================================================
-        case "metadata/book/search": {
-            if (!bookProvider) {
-                return {
-                    jsonrpc: "2.0",
-                    id,
-                    error: {
-                        code: JSON_RPC_ERROR_CODES.METHOD_NOT_FOUND,
-                        message: "This plugin does not support book metadata",
-                    },
-                };
+            case "metadata/book/get": {
+                if (!bookProvider)
+                    return methodNotFound(id, "This plugin does not support book metadata");
+                const err = validateGetParams(params);
+                if (err)
+                    return invalidParamsError(id, err);
+                return success(id, await bookProvider.get(params));
             }
-            const validationError = validateBookSearchParams(params);
-            if (validationError) {
-                return invalidParamsError(id, validationError);
+            case "metadata/book/match": {
+                if (!bookProvider)
+                    return methodNotFound(id, "This plugin does not support book metadata");
+                if (!bookProvider.match)
+                    return methodNotFound(id, "This plugin does not support book match");
+                const err = validateBookMatchParams(params);
+                if (err)
+                    return invalidParamsError(id, err);
+                return success(id, await bookProvider.match(params));
             }
-            return {
-                jsonrpc: "2.0",
-                id,
-                result: await bookProvider.search(params),
-            };
+            default:
+                return null;
         }
-        case "metadata/book/get": {
-            if (!bookProvider) {
-                return {
-                    jsonrpc: "2.0",
-                    id,
-                    error: {
-                        code: JSON_RPC_ERROR_CODES.METHOD_NOT_FOUND,
-                        message: "This plugin does not support book metadata",
-                    },
-                };
-            }
-            const validationError = validateGetParams(params);
-            if (validationError) {
-                return invalidParamsError(id, validationError);
+    };
+    createPluginServer({ manifest, onInitialize, logLevel, router });
+}
+/**
+ * Create and run a sync provider plugin
+ *
+ * Creates a plugin server that handles JSON-RPC communication over stdio
+ * for sync operations (push/pull reading progress with external services).
+ *
+ * @example
+ * ```typescript
+ * import { createSyncPlugin, type SyncProvider } from "@ashdev/codex-plugin-sdk";
+ *
+ * const provider: SyncProvider = {
+ *   async getUserInfo() {
+ *     return { externalId: "123", username: "user" };
+ *   },
+ *   async pushProgress(params) {
+ *     return { success: [], failed: [] };
+ *   },
+ *   async pullProgress(params) {
+ *     return { entries: [], hasMore: false };
+ *   },
+ * };
+ *
+ * createSyncPlugin({
+ *   manifest: {
+ *     name: "my-sync-plugin",
+ *     displayName: "My Sync Plugin",
+ *     version: "1.0.0",
+ *     description: "Syncs reading progress",
+ *     author: "Me",
+ *     protocolVersion: "1.0",
+ *     capabilities: { userReadSync: true },
+ *   },
+ *   provider,
+ * });
+ * ```
+ */
+export function createSyncPlugin(options) {
+    const { manifest, provider, onInitialize, logLevel } = options;
+    const router = async (method, params, id) => {
+        switch (method) {
+            case "sync/getUserInfo":
+                return success(id, await provider.getUserInfo());
+            case "sync/pushProgress":
+                return success(id, await provider.pushProgress(params));
+            case "sync/pullProgress":
+                return success(id, await provider.pullProgress(params));
+            case "sync/status": {
+                if (!provider.status)
+                    return methodNotFound(id, "This plugin does not support sync/status");
+                return success(id, await provider.status());
             }
-            return {
-                jsonrpc: "2.0",
-                id,
-                result: await bookProvider.get(params),
-            };
+            default:
+                return null;
         }
-        case "metadata/book/match": {
-            if (!bookProvider) {
-                return {
-                    jsonrpc: "2.0",
-                    id,
-                    error: {
-                        code: JSON_RPC_ERROR_CODES.METHOD_NOT_FOUND,
-                        message: "This plugin does not support book metadata",
-                    },
-                };
+    };
+    createPluginServer({ manifest, onInitialize, logLevel, label: "sync", router });
+}
+/**
+ * Create and run a recommendation provider plugin
+ *
+ * Creates a plugin server that handles JSON-RPC communication over stdio
+ * for recommendation operations (get recommendations, update profile, dismiss).
+ */
+export function createRecommendationPlugin(options) {
+    const { manifest, provider, onInitialize, logLevel } = options;
+    const router = async (method, params, id) => {
+        switch (method) {
+            case "recommendations/get":
+                return success(id, await provider.get(params));
+            case "recommendations/updateProfile": {
+                if (!provider.updateProfile)
+                    return methodNotFound(id, "This plugin does not support recommendations/updateProfile");
+                return success(id, await provider.updateProfile(params));
             }
-            if (!bookProvider.match) {
-                return {
-                    jsonrpc: "2.0",
-                    id,
-                    error: {
-                        code: JSON_RPC_ERROR_CODES.METHOD_NOT_FOUND,
-                        message: "This plugin does not support book match",
-                    },
-                };
+            case "recommendations/clear": {
+                if (!provider.clear)
+                    return methodNotFound(id, "This plugin does not support recommendations/clear");
+                return success(id, await provider.clear());
             }
-            const validationError = validateBookMatchParams(params);
-            if (validationError) {
-                return invalidParamsError(id, validationError);
+            case "recommendations/dismiss": {
+                if (!provider.dismiss)
+                    return methodNotFound(id, "This plugin does not support recommendations/dismiss");
+                const err = validateStringFields(params, ["externalId"]);
+                if (err)
+                    return invalidParamsError(id, err);
+                return success(id, await provider.dismiss(params));
             }
-            return {
-                jsonrpc: "2.0",
-                id,
-                result: await bookProvider.match(params),
-            };
+            default:
+                return null;
         }
-        default:
-            return {
-                jsonrpc: "2.0",
-                id,
-                error: {
-                    code: JSON_RPC_ERROR_CODES.METHOD_NOT_FOUND,
-                    message: `Method not found: ${method}`,
-                },
-            };
-    }
-}
-function writeResponse(response) {
-    // Write to stdout - this is the JSON-RPC channel
-    process.stdout.write(`${JSON.stringify(response)}\n`);
+    };
+    createPluginServer({ manifest, onInitialize, logLevel, label: "recommendation", router });
 }
 //# sourceMappingURL=server.js.map