@ashdev/codex-plugin-sdk 1.9.3 → 1.10.0

package/README.md

@@ -75,7 +75,6 @@ const provider: MetadataProvider = {
   async match(params) {
     const result = await this.search({
       query: params.title,
-      contentType: params.contentType,
     });
 
     return {

package/dist/index.d.ts

@@ -54,6 +54,7 @@
  */
 export { ApiError, AuthError, ConfigError, NotFoundError, PluginError, RateLimitError, } from "./errors.js";
 export { createLogger, Logger, type LoggerOptions, type LogLevel } from "./logger.js";
-export { createMetadataPlugin, createSeriesMetadataPlugin, type InitializeParams, type MetadataPluginOptions, type SeriesMetadataPluginOptions, } from "./server.js";
+export { createMetadataPlugin, createRecommendationPlugin, createSyncPlugin, type InitializeParams, type MetadataPluginOptions, type RecommendationPluginOptions, type SyncPluginOptions, } from "./server.js";
+export { PluginStorage, type StorageClearResponse, type StorageDeleteResponse, StorageError, type StorageGetResponse, type StorageKeyEntry, type StorageListResponse, type StorageSetResponse, } from "./storage.js";
 export * from "./types/index.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AAGH,OAAO,EACL,QAAQ,EACR,SAAS,EACT,WAAW,EACX,aAAa,EACb,WAAW,EACX,cAAc,GACf,MAAM,aAAa,CAAC;AAGrB,OAAO,EAAE,YAAY,EAAE,MAAM,EAAE,KAAK,aAAa,EAAE,KAAK,QAAQ,EAAE,MAAM,aAAa,CAAC;AAEtF,OAAO,EAEL,oBAAoB,EAEpB,0BAA0B,EAC1B,KAAK,gBAAgB,EACrB,KAAK,qBAAqB,EAC1B,KAAK,2BAA2B,GACjC,MAAM,aAAa,CAAC;AAGrB,cAAc,kBAAkB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AAGH,OAAO,EACL,QAAQ,EACR,SAAS,EACT,WAAW,EACX,aAAa,EACb,WAAW,EACX,cAAc,GACf,MAAM,aAAa,CAAC;AAGrB,OAAO,EAAE,YAAY,EAAE,MAAM,EAAE,KAAK,aAAa,EAAE,KAAK,QAAQ,EAAE,MAAM,aAAa,CAAC;AAGtF,OAAO,EACL,oBAAoB,EACpB,0BAA0B,EAC1B,gBAAgB,EAChB,KAAK,gBAAgB,EACrB,KAAK,qBAAqB,EAC1B,KAAK,2BAA2B,EAChC,KAAK,iBAAiB,GACvB,MAAM,aAAa,CAAC;AAGrB,OAAO,EACL,aAAa,EACb,KAAK,oBAAoB,EACzB,KAAK,qBAAqB,EAC1B,YAAY,EACZ,KAAK,kBAAkB,EACvB,KAAK,eAAe,EACpB,KAAK,mBAAmB,EACxB,KAAK,kBAAkB,GACxB,MAAM,cAAc,CAAC;AAGtB,cAAc,kBAAkB,CAAC"}

package/dist/index.js

@@ -57,11 +57,9 @@ export { ApiError, AuthError, ConfigError, NotFoundError, PluginError, RateLimit
 // Logger
 export { createLogger, Logger } from "./logger.js";
 // Server
-export { 
-// Primary exports
-createMetadataPlugin, 
-// Deprecated aliases
-createSeriesMetadataPlugin, } from "./server.js";
-// Types
+export { createMetadataPlugin, createRecommendationPlugin, createSyncPlugin, } from "./server.js";
+// Storage
+export { PluginStorage, StorageError, } from "./storage.js";
+// Types (all types re-exported from barrel)
 export * from "./types/index.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AAEH,SAAS;AACT,OAAO,EACL,QAAQ,EACR,SAAS,EACT,WAAW,EACX,aAAa,EACb,WAAW,EACX,cAAc,GACf,MAAM,aAAa,CAAC;AAErB,SAAS;AACT,OAAO,EAAE,YAAY,EAAE,MAAM,EAAqC,MAAM,aAAa,CAAC;AACtF,SAAS;AACT,OAAO;AACL,kBAAkB;AAClB,oBAAoB;AACpB,qBAAqB;AACrB,0BAA0B,GAI3B,MAAM,aAAa,CAAC;AAErB,QAAQ;AACR,cAAc,kBAAkB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AAEH,SAAS;AACT,OAAO,EACL,QAAQ,EACR,SAAS,EACT,WAAW,EACX,aAAa,EACb,WAAW,EACX,cAAc,GACf,MAAM,aAAa,CAAC;AAErB,SAAS;AACT,OAAO,EAAE,YAAY,EAAE,MAAM,EAAqC,MAAM,aAAa,CAAC;AAEtF,SAAS;AACT,OAAO,EACL,oBAAoB,EACpB,0BAA0B,EAC1B,gBAAgB,GAKjB,MAAM,aAAa,CAAC;AAErB,UAAU;AACV,OAAO,EACL,aAAa,EAGb,YAAY,GAKb,MAAM,cAAc,CAAC;AAEtB,4CAA4C;AAC5C,cAAc,kBAAkB,CAAC"}

package/dist/server.d.ts

@@ -1,16 +1,35 @@
 /**
  * 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 type { BookMetadataProvider, MetadataContentType, MetadataProvider } from "./types/capabilities.js";
+import { PluginStorage } from "./storage.js";
+import type { BookMetadataProvider, MetadataContentType, MetadataProvider, RecommendationProvider, SyncProvider } from "./types/capabilities.js";
 import type { PluginManifest } from "./types/manifest.js";
 /**
  * Initialize parameters received from Codex
  */
 export interface InitializeParams {
-    /** Plugin configuration */
-    config?: Record<string, unknown>;
+    /** Admin-level plugin configuration (from plugin settings) */
+    adminConfig?: Record<string, unknown>;
+    /** Per-user plugin configuration (from user plugin settings) */
+    userConfig?: Record<string, unknown>;
     /** Plugin credentials (API keys, tokens, etc.) */
     credentials?: Record<string, string>;
+    /**
+     * Per-user key-value storage client.
+     *
+     * Use this to persist data across plugin restarts (e.g., dismissed IDs,
+     * cached profiles, user preferences). Storage is scoped per user-plugin
+     * instance — the host resolves the user context automatically.
+     */
+    storage: PluginStorage;
 }
 /**
  * Options for creating a metadata plugin
@@ -82,24 +101,81 @@ export interface MetadataPluginOptions {
  */
 export declare function createMetadataPlugin(options: MetadataPluginOptions): void;
 /**
- * @deprecated Use createMetadataPlugin instead
+ * Options for creating a sync provider plugin
+ */
+export interface SyncPluginOptions {
+    /** Plugin manifest - must have capabilities.userReadSync: true */
+    manifest: PluginManifest & {
+        capabilities: {
+            userReadSync: true;
+        };
+    };
+    /** SyncProvider implementation */
+    provider: SyncProvider;
+    /** Called when plugin receives initialize with credentials/config */
+    onInitialize?: (params: InitializeParams) => void | Promise<void>;
+    /** Log level (default: "info") */
+    logLevel?: "debug" | "info" | "warn" | "error";
+}
+/**
+ * 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 declare function createSeriesMetadataPlugin(options: SeriesMetadataPluginOptions): void;
+export declare function createSyncPlugin(options: SyncPluginOptions): void;
 /**
- * @deprecated Use MetadataPluginOptions instead
+ * Options for creating a recommendation provider plugin
  */
-export interface SeriesMetadataPluginOptions {
-    /** Plugin manifest - must have capabilities.seriesMetadataProvider: true */
+export interface RecommendationPluginOptions {
+    /** Plugin manifest - must have capabilities.userRecommendationProvider: true */
     manifest: PluginManifest & {
         capabilities: {
-            seriesMetadataProvider: true;
+            userRecommendationProvider: true;
         };
     };
-    /** SeriesMetadataProvider implementation */
-    provider: MetadataProvider;
+    /** RecommendationProvider implementation */
+    provider: RecommendationProvider;
     /** Called when plugin receives initialize with credentials/config */
     onInitialize?: (params: InitializeParams) => void | Promise<void>;
     /** Log level (default: "info") */
     logLevel?: "debug" | "info" | "warn" | "error";
 }
+/**
+ * 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 declare function createRecommendationPlugin(options: RecommendationPluginOptions): void;
 //# sourceMappingURL=server.d.ts.map

package/dist/server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA;;GAEG;AAKH,OAAO,KAAK,EACV,oBAAoB,EACpB,mBAAmB,EACnB,gBAAgB,EACjB,MAAM,yBAAyB,CAAC;AACjC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAqH1D;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,2BAA2B;IAC3B,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,kDAAkD;IAClD,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACtC;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,mFAAmF;IACnF,QAAQ,EAAE,cAAc,GAAG;QACzB,YAAY,EAAE;YAAE,gBAAgB,EAAE,mBAAmB,EAAE,CAAA;SAAE,CAAC;KAC3D,CAAC;IACF,wFAAwF;IACxF,QAAQ,CAAC,EAAE,gBAAgB,CAAC;IAC5B,oFAAoF;IACpF,YAAY,CAAC,EAAE,oBAAoB,CAAC;IACpC,qEAAqE;IACrE,YAAY,CAAC,EAAE,CAAC,MAAM,EAAE,gBAAgB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAClE,kCAAkC;IAClC,QAAQ,CAAC,EAAE,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;CAChD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,qBAAqB,GAAG,IAAI,CA0CzE;AAMD;;GAEG;AACH,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,2BAA2B,GAAG,IAAI,CAarF;AAED;;GAEG;AACH,MAAM,WAAW,2BAA2B;IAC1C,4EAA4E;IAC5E,QAAQ,EAAE,cAAc,GAAG;QACzB,YAAY,EAAE;YAAE,sBAAsB,EAAE,IAAI,CAAA;SAAE,CAAC;KAChD,CAAC;IACF,4CAA4C;IAC5C,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,qEAAqE;IACrE,YAAY,CAAC,EAAE,CAAC,MAAM,EAAE,gBAAgB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAClE,kCAAkC;IAClC,QAAQ,CAAC,EAAE,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;CAChD"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAKH,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAC7C,OAAO,KAAK,EACV,oBAAoB,EACpB,mBAAmB,EACnB,gBAAgB,EAChB,sBAAsB,EACtB,YAAY,EACb,MAAM,yBAAyB,CAAC;AACjC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AA0H1D;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,8DAA8D;IAC9D,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACtC,gEAAgE;IAChE,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,kDAAkD;IAClD,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACrC;;;;;;OAMG;IACH,OAAO,EAAE,aAAa,CAAC;CACxB;AAkOD;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,mFAAmF;IACnF,QAAQ,EAAE,cAAc,GAAG;QACzB,YAAY,EAAE;YAAE,gBAAgB,EAAE,mBAAmB,EAAE,CAAA;SAAE,CAAC;KAC3D,CAAC;IACF,wFAAwF;IACxF,QAAQ,CAAC,EAAE,gBAAgB,CAAC;IAC5B,oFAAoF;IACpF,YAAY,CAAC,EAAE,oBAAoB,CAAC;IACpC,qEAAqE;IACrE,YAAY,CAAC,EAAE,CAAC,MAAM,EAAE,gBAAgB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAClE,kCAAkC;IAClC,QAAQ,CAAC,EAAE,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;CAChD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,qBAAqB,GAAG,IAAI,CAmEzE;AAMD;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,kEAAkE;IAClE,QAAQ,EAAE,cAAc,GAAG;QACzB,YAAY,EAAE;YAAE,YAAY,EAAE,IAAI,CAAA;SAAE,CAAC;KACtC,CAAC;IACF,kCAAkC;IAClC,QAAQ,EAAE,YAAY,CAAC;IACvB,qEAAqE;IACrE,YAAY,CAAC,EAAE,CAAC,MAAM,EAAE,gBAAgB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAClE,kCAAkC;IAClC,QAAQ,CAAC,EAAE,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;CAChD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,iBAAiB,GAAG,IAAI,CAqBjE;AAMD;;GAEG;AACH,MAAM,WAAW,2BAA2B;IAC1C,gFAAgF;IAChF,QAAQ,EAAE,cAAc,GAAG;QACzB,YAAY,EAAE;YAAE,0BAA0B,EAAE,IAAI,CAAA;SAAE,CAAC;KACpD,CAAC;IACF,4CAA4C;IAC5C,QAAQ,EAAE,sBAAsB,CAAC;IACjC,qEAAqE;IACrE,YAAY,CAAC,EAAE,CAAC,MAAM,EAAE,gBAAgB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAClE,kCAAkC;IAClC,QAAQ,CAAC,EAAE,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;CAChD;AAED;;;;;GAKG;AACH,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,2BAA2B,GAAG,IAAI,CA8BrF"}