@ashdev/codex-plugin-sdk 1.0.0

package/dist/server.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Plugin server - handles JSON-RPC communication over stdio
+ */
+import type { MetadataContentType, MetadataProvider } 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>;
+    /** Plugin credentials (API keys, tokens, etc.) */
+    credentials?: Record<string, string>;
+}
+/**
+ * Options for creating a metadata plugin
+ */
+export interface MetadataPluginOptions {
+    /** Plugin manifest - must have capabilities.metadataProvider with content types */
+    manifest: PluginManifest & {
+        capabilities: {
+            metadataProvider: MetadataContentType[];
+        };
+    };
+    /** MetadataProvider implementation */
+    provider: MetadataProvider;
+    /** 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 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 declare function createMetadataPlugin(options: MetadataPluginOptions): void;
+/**
+ * @deprecated Use createMetadataPlugin instead
+ */
+export declare function createSeriesMetadataPlugin(options: SeriesMetadataPluginOptions): void;
+/**
+ * @deprecated Use MetadataPluginOptions instead
+ */
+export interface SeriesMetadataPluginOptions {
+    /** Plugin manifest - must have capabilities.seriesMetadataProvider: true */
+    manifest: PluginManifest & {
+        capabilities: {
+            seriesMetadataProvider: true;
+        };
+    };
+    /** SeriesMetadataProvider implementation */
+    provider: MetadataProvider;
+    /** Called when plugin receives initialize with credentials/config */
+    onInitialize?: (params: InitializeParams) => void | Promise<void>;
+    /** Log level (default: "info") */
+    logLevel?: "debug" | "info" | "warn" | "error";
+}
+//# sourceMappingURL=server.d.ts.map

package/dist/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA;;GAEG;AAKH,OAAO,KAAK,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AACrF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAsF1D;;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,sCAAsC;IACtC,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;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,qBAAqB,GAAG,IAAI,CA6BzE;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"}

package/dist/server.js

@@ -0,0 +1,306 @@
+/**
+ * Plugin server - handles JSON-RPC communication over stdio
+ */
+import { createInterface } from "node:readline";
+import { PluginError } from "./errors.js";
+import { createLogger } from "./logger.js";
+import { JSON_RPC_ERROR_CODES, } from "./types/rpc.js";
+/**
+ * Validate that the required string fields are present and non-empty
+ */
+function validateStringFields(params, fields) {
+    if (params === null || params === undefined) {
+        return { field: "params", message: "params is required" };
+    }
+    if (typeof params !== "object") {
+        return { field: "params", message: "params must be an object" };
+    }
+    const obj = params;
+    for (const field of fields) {
+        const value = obj[field];
+        if (value === undefined || value === null) {
+            return { field, message: `${field} is required` };
+        }
+        if (typeof value !== "string") {
+            return { field, message: `${field} must be a string` };
+        }
+        if (value.trim() === "") {
+            return { field, message: `${field} cannot be empty` };
+        }
+    }
+    return null;
+}
+/**
+ * Validate MetadataSearchParams
+ */
+function validateSearchParams(params) {
+    return validateStringFields(params, ["query"]);
+}
+/**
+ * Validate MetadataGetParams
+ */
+function validateGetParams(params) {
+    return validateStringFields(params, ["externalId"]);
+}
+/**
+ * Validate MetadataMatchParams
+ */
+function validateMatchParams(params) {
+    return validateStringFields(params, ["title"]);
+}
+/**
+ * Create an INVALID_PARAMS error response
+ */
+function invalidParamsError(id, error) {
+    return {
+        jsonrpc: "2.0",
+        id,
+        error: {
+            code: JSON_RPC_ERROR_CODES.INVALID_PARAMS,
+            message: `Invalid params: ${error.message}`,
+            data: { field: error.field },
+        },
+    };
+}
+/**
+ * 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, onInitialize, logLevel = "info" } = options;
+    const logger = createLogger({ name: manifest.name, level: logLevel });
+    logger.info(`Starting plugin: ${manifest.displayName} v${manifest.version}`);
+    const rl = createInterface({
+        input: process.stdin,
+        terminal: false,
+    });
+    rl.on("line", (line) => {
+        void handleLine(line, manifest, provider, onInitialize, logger);
+    });
+    rl.on("close", () => {
+        logger.info("stdin closed, shutting down");
+        process.exit(0);
+    });
+    // Handle uncaught errors
+    process.on("uncaughtException", (error) => {
+        logger.error("Uncaught exception", error);
+        process.exit(1);
+    });
+    process.on("unhandledRejection", (reason) => {
+        logger.error("Unhandled rejection", reason);
+    });
+}
+// =============================================================================
+// Backwards Compatibility (deprecated)
+// =============================================================================
+/**
+ * @deprecated Use createMetadataPlugin instead
+ */
+export function createSeriesMetadataPlugin(options) {
+    // Convert legacy options to new format
+    const newOptions = {
+        ...options,
+        manifest: {
+            ...options.manifest,
+            capabilities: {
+                ...options.manifest.capabilities,
+                metadataProvider: ["series"],
+            },
+        },
+    };
+    createMetadataPlugin(newOptions);
+}
+// =============================================================================
+// Internal Implementation
+// =============================================================================
+async function handleLine(line, manifest, provider, onInitialize, logger) {
+    const trimmed = line.trim();
+    if (!trimmed)
+        return;
+    let id = null;
+    try {
+        const request = JSON.parse(trimmed);
+        id = request.id;
+        logger.debug(`Received request: ${request.method}`, { id: request.id });
+        const response = await handleRequest(request, manifest, provider, onInitialize, logger);
+        // Shutdown handler writes response directly and returns null
+        if (response !== null) {
+            writeResponse(response);
+        }
+    }
+    catch (error) {
+        if (error instanceof SyntaxError) {
+            // JSON parse error
+            writeResponse({
+                jsonrpc: "2.0",
+                id: null,
+                error: {
+                    code: JSON_RPC_ERROR_CODES.PARSE_ERROR,
+                    message: "Parse error: invalid JSON",
+                },
+            });
+        }
+        else if (error instanceof PluginError) {
+            writeResponse({
+                jsonrpc: "2.0",
+                id,
+                error: error.toJsonRpcError(),
+            });
+        }
+        else {
+            const message = error instanceof Error ? error.message : "Unknown error";
+            logger.error("Request failed", error);
+            writeResponse({
+                jsonrpc: "2.0",
+                id,
+                error: {
+                    code: JSON_RPC_ERROR_CODES.INTERNAL_ERROR,
+                    message,
+                },
+            });
+        }
+    }
+}
+async function handleRequest(request, manifest, provider, onInitialize, logger) {
+    const { method, params, id } = request;
+    switch (method) {
+        case "initialize":
+            // Call onInitialize callback if provided (to receive credentials/config)
+            if (onInitialize) {
+                await onInitialize(params);
+            }
+            return {
+                jsonrpc: "2.0",
+                id,
+                result: manifest,
+            };
+        case "ping":
+            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,
+            };
+            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
+            return null;
+        }
+        // Series metadata methods (scoped by content type)
+        case "metadata/series/search": {
+            const validationError = validateSearchParams(params);
+            if (validationError) {
+                return invalidParamsError(id, validationError);
+            }
+            return {
+                jsonrpc: "2.0",
+                id,
+                result: await provider.search(params),
+            };
+        }
+        case "metadata/series/get": {
+            const validationError = validateGetParams(params);
+            if (validationError) {
+                return invalidParamsError(id, validationError);
+            }
+            return {
+                jsonrpc: "2.0",
+                id,
+                result: await provider.get(params),
+            };
+        }
+        case "metadata/series/match": {
+            if (!provider.match) {
+                return {
+                    jsonrpc: "2.0",
+                    id,
+                    error: {
+                        code: JSON_RPC_ERROR_CODES.METHOD_NOT_FOUND,
+                        message: "This plugin does not support match",
+                    },
+                };
+            }
+            const validationError = validateMatchParams(params);
+            if (validationError) {
+                return invalidParamsError(id, validationError);
+            }
+            return {
+                jsonrpc: "2.0",
+                id,
+                result: await provider.match(params),
+            };
+        }
+        // Future: book metadata methods
+        // case "metadata/book/search":
+        // case "metadata/book/get":
+        // case "metadata/book/match":
+        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`);
+}
+//# sourceMappingURL=server.js.map

package/dist/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"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"}

package/dist/types/capabilities.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Capability interfaces - type-safe contracts for plugin capabilities
+ *
+ * Plugins declare which content types they support in their manifest's
+ * capabilities.metadataProvider array. The SDK automatically routes
+ * scoped methods (e.g., metadata/series/search) to the provider.
+ *
+ * @example
+ * ```typescript
+ * // If manifest has capabilities.metadataProvider: ["series"],
+ * // the plugin must implement MetadataProvider
+ * const provider: MetadataProvider = {
+ *   search: async (params) => { ... },
+ *   get: async (params) => { ... },
+ *   match: async (params) => { ... }, // optional
+ * };
+ * ```
+ */
+import type { MetadataGetParams, MetadataMatchParams, MetadataMatchResponse, MetadataSearchParams, MetadataSearchResponse, PluginSeriesMetadata } from "./protocol.js";
+/**
+ * Content types that a metadata provider can support.
+ * Plugins declare which types they support in capabilities.metadataProvider.
+ */
+export type MetadataContentType = "series" | "book";
+/**
+ * Interface for plugins that provide metadata.
+ *
+ * Plugins implementing this capability can:
+ * - Search for content by query
+ * - Get full metadata by external ID
+ * - Optionally match existing content to provider entries
+ *
+ * The same interface is used for both series and book metadata.
+ * The content type is determined by the method being called:
+ * - metadata/series/search -> provider.search()
+ * - metadata/book/search -> provider.search() (when book support is added)
+ */
+export interface MetadataProvider {
+    /**
+     * Search for content matching a query
+     *
+     * @param params - Search parameters
+     * @returns Search results with relevance scores
+     */
+    search(params: MetadataSearchParams): Promise<MetadataSearchResponse>;
+    /**
+     * Get full metadata for a specific external ID
+     *
+     * @param params - Get parameters including external ID
+     * @returns Full metadata
+     */
+    get(params: MetadataGetParams): Promise<PluginSeriesMetadata>;
+    /**
+     * Find the best match for existing content (optional)
+     *
+     * This is used for auto-matching during library scans.
+     * If not implemented, Codex will use search() and pick the top result.
+     *
+     * @param params - Match parameters including title and hints
+     * @returns Best match with confidence score
+     */
+    match?(params: MetadataMatchParams): Promise<MetadataMatchResponse>;
+}
+/**
+ * Interface for plugins that sync reading progress (syncProvider: true)
+ * @future v2 - Methods will be defined when sync capability is implemented
+ */
+export interface SyncProvider {
+}
+/**
+ * Interface for plugins that provide recommendations (recommendationProvider: true)
+ * @future v2 - Methods will be defined when recommendation capability is implemented
+ */
+export interface RecommendationProvider {
+}
+/**
+ * Partial metadata provider - allows implementing only some methods
+ * Use this for testing or gradual implementation
+ */
+export type PartialMetadataProvider = Partial<MetadataProvider>;
+/**
+ * @deprecated Use MetadataProvider instead
+ */
+export type SeriesMetadataProvider = MetadataProvider;
+/**
+ * @deprecated Use PartialMetadataProvider instead
+ */
+export type PartialSeriesMetadataProvider = PartialMetadataProvider;
+//# sourceMappingURL=capabilities.d.ts.map

package/dist/types/capabilities.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capabilities.d.ts","sourceRoot":"","sources":["../../src/types/capabilities.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EACV,iBAAiB,EACjB,mBAAmB,EACnB,qBAAqB,EACrB,oBAAoB,EACpB,sBAAsB,EACtB,oBAAoB,EACrB,MAAM,eAAe,CAAC;AAMvB;;;GAGG;AACH,MAAM,MAAM,mBAAmB,GAAG,QAAQ,GAAG,MAAM,CAAC;AAMpD;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;;;OAKG;IACH,MAAM,CAAC,MAAM,EAAE,oBAAoB,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAAC;IAEtE;;;;;OAKG;IACH,GAAG,CAAC,MAAM,EAAE,iBAAiB,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAAC;IAE9D;;;;;;;;OAQG;IACH,KAAK,CAAC,CAAC,MAAM,EAAE,mBAAmB,GAAG,OAAO,CAAC,qBAAqB,CAAC,CAAC;CACrE;AAMD;;;GAGG;AAEH,MAAM,WAAW,YAAY;CAAG;AAEhC;;;GAGG;AAEH,MAAM,WAAW,sBAAsB;CAAG;AAM1C;;;GAGG;AACH,MAAM,MAAM,uBAAuB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC;AAMhE;;GAEG;AACH,MAAM,MAAM,sBAAsB,GAAG,gBAAgB,CAAC;AAEtD;;GAEG;AACH,MAAM,MAAM,6BAA6B,GAAG,uBAAuB,CAAC"}

package/dist/types/capabilities.js

@@ -0,0 +1,20 @@
+/**
+ * Capability interfaces - type-safe contracts for plugin capabilities
+ *
+ * Plugins declare which content types they support in their manifest's
+ * capabilities.metadataProvider array. The SDK automatically routes
+ * scoped methods (e.g., metadata/series/search) to the provider.
+ *
+ * @example
+ * ```typescript
+ * // If manifest has capabilities.metadataProvider: ["series"],
+ * // the plugin must implement MetadataProvider
+ * const provider: MetadataProvider = {
+ *   search: async (params) => { ... },
+ *   get: async (params) => { ... },
+ *   match: async (params) => { ... }, // optional
+ * };
+ * ```
+ */
+export {};
+//# sourceMappingURL=capabilities.js.map

package/dist/types/capabilities.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"capabilities.js","sourceRoot":"","sources":["../../src/types/capabilities.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG"}

package/dist/types/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Re-export all types
+ */
+export type { MetadataContentType, MetadataProvider, PartialMetadataProvider, PartialSeriesMetadataProvider, RecommendationProvider, SeriesMetadataProvider, SyncProvider, } from "./capabilities.js";
+export type { CredentialField, PluginCapabilities, PluginManifest } from "./manifest.js";
+export { hasBookMetadataProvider, hasSeriesMetadataProvider } from "./manifest.js";
+export type { AlternateTitle, ExternalLink, ExternalLinkType, ExternalRating, MetadataGetParams, MetadataMatchParams, MetadataMatchResponse, MetadataSearchParams, MetadataSearchResponse, PluginSeriesMetadata, ReadingDirection, SearchResult, SearchResultPreview, SeriesStatus, } from "./protocol.js";
+export * from "./rpc.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/types/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,YAAY,EAEV,mBAAmB,EACnB,gBAAgB,EAChB,uBAAuB,EACvB,6BAA6B,EAC7B,sBAAsB,EAEtB,sBAAsB,EACtB,YAAY,GACb,MAAM,mBAAmB,CAAC;AAG3B,YAAY,EAAE,eAAe,EAAE,kBAAkB,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AACzF,OAAO,EAAE,uBAAuB,EAAE,yBAAyB,EAAE,MAAM,eAAe,CAAC;AAGnF,YAAY,EACV,cAAc,EACd,YAAY,EACZ,gBAAgB,EAChB,cAAc,EACd,iBAAiB,EACjB,mBAAmB,EACnB,qBAAqB,EACrB,oBAAoB,EACpB,sBAAsB,EACtB,oBAAoB,EACpB,gBAAgB,EAChB,YAAY,EACZ,mBAAmB,EACnB,YAAY,GACb,MAAM,eAAe,CAAC;AACvB,cAAc,UAAU,CAAC"}

package/dist/types/index.js

@@ -0,0 +1,6 @@
+/**
+ * Re-export all types
+ */
+export { hasBookMetadataProvider, hasSeriesMetadataProvider } from "./manifest.js";
+export * from "./rpc.js";
+//# sourceMappingURL=index.js.map

package/dist/types/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAiBH,OAAO,EAAE,uBAAuB,EAAE,yBAAyB,EAAE,MAAM,eAAe,CAAC;AAmBnF,cAAc,UAAU,CAAC"}

package/dist/types/manifest.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Plugin manifest types - describes plugin capabilities and requirements
+ */
+import type { MetadataContentType } from "./capabilities.js";
+/**
+ * Credential field configuration for admin UI
+ */
+export interface CredentialField {
+    /** Unique key for this credential (used in environment variables) */
+    key: string;
+    /** Human-readable label for the UI */
+    label: string;
+    /** Help text explaining where to get this credential */
+    description?: string;
+    /** Whether this credential is required */
+    required: boolean;
+    /** Whether to mask this value in the UI (for passwords/API keys) */
+    sensitive: boolean;
+    /** Input type for the UI */
+    type: "text" | "password" | "url";
+    /** Placeholder text */
+    placeholder?: string;
+}
+/**
+ * Plugin capabilities
+ */
+export interface PluginCapabilities {
+    /**
+     * Content types this plugin can provide metadata for.
+     * E.g., ["series"] or ["series", "book"]
+     */
+    metadataProvider?: MetadataContentType[];
+    /** Can sync reading progress with external service */
+    syncProvider?: boolean;
+    /** Can provide recommendations */
+    recommendationProvider?: boolean;
+}
+/**
+ * Plugin manifest returned by the `initialize` method
+ */
+export interface PluginManifest {
+    /** Unique plugin identifier (lowercase, alphanumeric, hyphens) */
+    name: string;
+    /** Human-readable name for UI display */
+    displayName: string;
+    /** Plugin version (semver) */
+    version: string;
+    /** Short description of what the plugin does */
+    description: string;
+    /** Author name or organization */
+    author: string;
+    /** Homepage URL (documentation, source code) */
+    homepage?: string;
+    /** Icon URL (optional, for UI display) */
+    icon?: string;
+    /** Protocol version this plugin implements */
+    protocolVersion: "1.0";
+    /** What this plugin can do */
+    capabilities: PluginCapabilities;
+    /** Credentials required from admin */
+    requiredCredentials?: CredentialField[];
+}
+/**
+ * Type guard to check if manifest declares series metadata provider capability
+ */
+export declare function hasSeriesMetadataProvider(manifest: PluginManifest): manifest is PluginManifest & {
+    capabilities: {
+        metadataProvider: MetadataContentType[];
+    };
+};
+/**
+ * Type guard to check if manifest declares book metadata provider capability
+ */
+export declare function hasBookMetadataProvider(manifest: PluginManifest): manifest is PluginManifest & {
+    capabilities: {
+        metadataProvider: MetadataContentType[];
+    };
+};
+/**
+ * @deprecated Use PluginCapabilities with metadataProvider array instead
+ */
+export interface LegacyPluginCapabilities {
+    /** @deprecated Use metadataProvider: ["series"] instead */
+    seriesMetadataProvider?: boolean;
+    syncProvider?: boolean;
+    recommendationProvider?: boolean;
+}
+//# sourceMappingURL=manifest.d.ts.map

package/dist/types/manifest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../../src/types/manifest.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAE7D;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,qEAAqE;IACrE,GAAG,EAAE,MAAM,CAAC;IACZ,sCAAsC;IACtC,KAAK,EAAE,MAAM,CAAC;IACd,wDAAwD;IACxD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,0CAA0C;IAC1C,QAAQ,EAAE,OAAO,CAAC;IAClB,oEAAoE;IACpE,SAAS,EAAE,OAAO,CAAC;IACnB,4BAA4B;IAC5B,IAAI,EAAE,MAAM,GAAG,UAAU,GAAG,KAAK,CAAC;IAClC,uBAAuB;IACvB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC;;;OAGG;IACH,gBAAgB,CAAC,EAAE,mBAAmB,EAAE,CAAC;IACzC,sDAAsD;IACtD,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,kCAAkC;IAClC,sBAAsB,CAAC,EAAE,OAAO,CAAC;CAClC;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,kEAAkE;IAClE,IAAI,EAAE,MAAM,CAAC;IACb,yCAAyC;IACzC,WAAW,EAAE,MAAM,CAAC;IACpB,8BAA8B;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,gDAAgD;IAChD,WAAW,EAAE,MAAM,CAAC;IACpB,kCAAkC;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,gDAAgD;IAChD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,0CAA0C;IAC1C,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd,8CAA8C;IAC9C,eAAe,EAAE,KAAK,CAAC;IAEvB,8BAA8B;IAC9B,YAAY,EAAE,kBAAkB,CAAC;IAEjC,sCAAsC;IACtC,mBAAmB,CAAC,EAAE,eAAe,EAAE,CAAC;CACzC;AAMD;;GAEG;AACH,wBAAgB,yBAAyB,CAAC,QAAQ,EAAE,cAAc,GAAG,QAAQ,IAAI,cAAc,GAAG;IAChG,YAAY,EAAE;QAAE,gBAAgB,EAAE,mBAAmB,EAAE,CAAA;KAAE,CAAC;CAC3D,CAKA;AAED;;GAEG;AACH,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,cAAc,GAAG,QAAQ,IAAI,cAAc,GAAG;IAC9F,YAAY,EAAE;QAAE,gBAAgB,EAAE,mBAAmB,EAAE,CAAA;KAAE,CAAC;CAC3D,CAKA;AAMD;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACvC,2DAA2D;IAC3D,sBAAsB,CAAC,EAAE,OAAO,CAAC;IACjC,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,sBAAsB,CAAC,EAAE,OAAO,CAAC;CAClC"}