@ashdev/codex-plugin-sdk 1.0.0

package/dist/types/manifest.js

@@ -0,0 +1,21 @@
+/**
+ * Plugin manifest types - describes plugin capabilities and requirements
+ */
+// =============================================================================
+// Type Guards for Manifest Validation
+// =============================================================================
+/**
+ * Type guard to check if manifest declares series metadata provider capability
+ */
+export function hasSeriesMetadataProvider(manifest) {
+    return (Array.isArray(manifest.capabilities.metadataProvider) &&
+        manifest.capabilities.metadataProvider.includes("series"));
+}
+/**
+ * Type guard to check if manifest declares book metadata provider capability
+ */
+export function hasBookMetadataProvider(manifest) {
+    return (Array.isArray(manifest.capabilities.metadataProvider) &&
+        manifest.capabilities.metadataProvider.includes("book"));
+}
+//# sourceMappingURL=manifest.js.map

package/dist/types/manifest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.js","sourceRoot":"","sources":["../../src/types/manifest.ts"],"names":[],"mappings":"AAAA;;GAEG;AAoEH,gFAAgF;AAChF,sCAAsC;AACtC,gFAAgF;AAEhF;;GAEG;AACH,MAAM,UAAU,yBAAyB,CAAC,QAAwB;IAGhE,OAAO,CACL,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAC,gBAAgB,CAAC;QACrD,QAAQ,CAAC,YAAY,CAAC,gBAAgB,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAC1D,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,uBAAuB,CAAC,QAAwB;IAG9D,OAAO,CACL,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAC,gBAAgB,CAAC;QACrD,QAAQ,CAAC,YAAY,CAAC,gBAAgB,CAAC,QAAQ,CAAC,MAAM,CAAC,CACxD,CAAC;AACJ,CAAC"}

package/dist/types/protocol.d.ts

@@ -0,0 +1,185 @@
+/**
+ * Protocol types - these MUST match the Rust protocol exactly
+ *
+ * These types define the JSON-RPC protocol contract between plugins and Codex.
+ * Field names use camelCase to match JSON serialization.
+ *
+ * @see src/services/plugin/protocol.rs in the Codex backend
+ */
+/**
+ * Parameters for metadata/series/search method (and future metadata/book/search)
+ */
+export interface MetadataSearchParams {
+    /** Search query string */
+    query: string;
+    /** Maximum number of results to return */
+    limit?: number;
+    /** Pagination cursor from previous response */
+    cursor?: string;
+}
+/**
+ * Response from metadata/series/search method (and future metadata/book/search)
+ */
+export interface MetadataSearchResponse {
+    /** Search results */
+    results: SearchResult[];
+    /** Cursor for next page (if more results available) */
+    nextCursor?: string;
+}
+/**
+ * Individual search result
+ */
+export interface SearchResult {
+    /** External ID from the provider */
+    externalId: string;
+    /** Primary title */
+    title: string;
+    /** Alternative titles */
+    alternateTitles: string[];
+    /** Year of publication/release */
+    year?: number;
+    /** Cover image URL */
+    coverUrl?: string;
+    /** Relevance score (0.0-1.0, where 1.0 is perfect match) */
+    relevanceScore?: number;
+    /** Preview data for displaying in search results */
+    preview?: SearchResultPreview;
+}
+/**
+ * Preview data shown in search result list
+ */
+export interface SearchResultPreview {
+    /** Publication status */
+    status?: string;
+    /** Genres */
+    genres: string[];
+    /** Rating (normalized 0-10) */
+    rating?: number;
+    /** Short description */
+    description?: string;
+}
+/**
+ * Parameters for metadata/series/get method (and future metadata/book/get)
+ */
+export interface MetadataGetParams {
+    /** External ID from the provider */
+    externalId: string;
+}
+/**
+ * Full series metadata from a provider
+ */
+export interface PluginSeriesMetadata {
+    /** External ID from the provider */
+    externalId: string;
+    /** URL to the series on the provider's website */
+    externalUrl: string;
+    /** Primary title */
+    title?: string;
+    /** Alternative titles with language info */
+    alternateTitles: AlternateTitle[];
+    /** Full description/summary */
+    summary?: string;
+    /** Publication status */
+    status?: SeriesStatus;
+    /** Year of first publication */
+    year?: number;
+    /** Expected total number of books in the series */
+    totalBookCount?: number;
+    /** BCP47 language code (e.g., "en", "ja", "ko") */
+    language?: string;
+    /** Age rating (e.g., 0, 13, 16, 18) */
+    ageRating?: number;
+    /** Reading direction: "ltr", "rtl", or "ttb" */
+    readingDirection?: ReadingDirection;
+    /** Genres (e.g., "Action", "Romance") */
+    genres: string[];
+    /** Tags/themes (e.g., "Time Travel", "School Life") */
+    tags: string[];
+    /** Authors/writers */
+    authors: string[];
+    /** Artists (if different from authors) */
+    artists: string[];
+    /** Publisher name */
+    publisher?: string;
+    /** Cover image URL */
+    coverUrl?: string;
+    /** Banner/background image URL */
+    bannerUrl?: string;
+    /** External rating information (primary rating) */
+    rating?: ExternalRating;
+    /** Multiple external ratings from different sources (e.g., AniList, MAL) */
+    externalRatings?: ExternalRating[];
+    /** Links to other sites */
+    externalLinks: ExternalLink[];
+}
+/**
+ * Alternate title with language info
+ */
+export interface AlternateTitle {
+    /** The title text */
+    title: string;
+    /** ISO 639-1 language code (e.g., "en", "ja") */
+    language?: string;
+    /** Title type (e.g., "romaji", "native", "english") */
+    titleType?: string;
+}
+/**
+ * Series publication status
+ *
+ * These values MUST match the backend's canonical SeriesStatus enum.
+ * @see src/db/entities/series_metadata.rs in the Codex backend
+ */
+export type SeriesStatus = "ongoing" | "ended" | "hiatus" | "abandoned" | "unknown";
+/**
+ * Reading direction for content
+ */
+export type ReadingDirection = "ltr" | "rtl" | "ttb";
+/**
+ * External rating from provider
+ */
+export interface ExternalRating {
+    /** Normalized score (0-100) */
+    score: number;
+    /** Number of votes */
+    voteCount?: number;
+    /** Source name (e.g., "mangaupdates") */
+    source: string;
+}
+/**
+ * External link to other sites
+ */
+export interface ExternalLink {
+    /** URL */
+    url: string;
+    /** Display label */
+    label: string;
+    /** Link type */
+    linkType?: ExternalLinkType;
+}
+/**
+ * Type of external link
+ */
+export type ExternalLinkType = "provider" | "official" | "social" | "purchase" | "read" | "other";
+/**
+ * Parameters for metadata/series/match method (and future metadata/book/match)
+ */
+export interface MetadataMatchParams {
+    /** Title to match against */
+    title: string;
+    /** Year hint for matching */
+    year?: number;
+    /** Author hint for matching */
+    author?: string;
+}
+/**
+ * Response from metadata/series/match method (and future metadata/book/match)
+ */
+export interface MetadataMatchResponse {
+    /** Best match result, or null if no confident match */
+    match: SearchResult | null;
+    /** Confidence score (0.0-1.0) */
+    confidence: number;
+    /** Alternative matches if confidence is low */
+    alternatives?: SearchResult[];
+}
+//# sourceMappingURL=protocol.d.ts.map

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

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

package/dist/types/protocol.js

@@ -0,0 +1,10 @@
+/**
+ * Protocol types - these MUST match the Rust protocol exactly
+ *
+ * These types define the JSON-RPC protocol contract between plugins and Codex.
+ * Field names use camelCase to match JSON serialization.
+ *
+ * @see src/services/plugin/protocol.rs in the Codex backend
+ */
+export {};
+//# sourceMappingURL=protocol.js.map

package/dist/types/protocol.js.map

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

package/dist/types/rpc.d.ts

@@ -0,0 +1,56 @@
+/**
+ * JSON-RPC 2.0 types for plugin communication
+ */
+export interface JsonRpcRequest {
+    jsonrpc: "2.0";
+    id: string | number | null;
+    method: string;
+    params?: unknown;
+}
+export interface JsonRpcSuccessResponse {
+    jsonrpc: "2.0";
+    id: string | number | null;
+    result: unknown;
+}
+export interface JsonRpcErrorResponse {
+    jsonrpc: "2.0";
+    id: string | number | null;
+    error: JsonRpcError;
+}
+export interface JsonRpcError {
+    code: number;
+    message: string;
+    data?: unknown;
+}
+export type JsonRpcResponse = JsonRpcSuccessResponse | JsonRpcErrorResponse;
+/**
+ * Standard JSON-RPC error codes
+ */
+export declare const JSON_RPC_ERROR_CODES: {
+    /** Invalid JSON was received */
+    readonly PARSE_ERROR: -32700;
+    /** The JSON sent is not a valid Request object */
+    readonly INVALID_REQUEST: -32600;
+    /** The method does not exist / is not available */
+    readonly METHOD_NOT_FOUND: -32601;
+    /** Invalid method parameter(s) */
+    readonly INVALID_PARAMS: -32602;
+    /** Internal JSON-RPC error */
+    readonly INTERNAL_ERROR: -32603;
+};
+/**
+ * Plugin-specific error codes (in the -32000 to -32099 range)
+ */
+export declare const PLUGIN_ERROR_CODES: {
+    /** Rate limited by external API */
+    readonly RATE_LIMITED: -32001;
+    /** Resource not found (e.g., series ID doesn't exist) */
+    readonly NOT_FOUND: -32002;
+    /** Authentication failed (invalid credentials) */
+    readonly AUTH_FAILED: -32003;
+    /** External API error */
+    readonly API_ERROR: -32004;
+    /** Plugin configuration error */
+    readonly CONFIG_ERROR: -32005;
+};
+//# sourceMappingURL=rpc.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"rpc.d.ts","sourceRoot":"","sources":["../../src/types/rpc.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,KAAK,CAAC;IACf,EAAE,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,sBAAsB;IACrC,OAAO,EAAE,KAAK,CAAC;IACf,EAAE,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;IAC3B,MAAM,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,KAAK,CAAC;IACf,EAAE,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;IAC3B,KAAK,EAAE,YAAY,CAAC;CACrB;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED,MAAM,MAAM,eAAe,GAAG,sBAAsB,GAAG,oBAAoB,CAAC;AAE5E;;GAEG;AACH,eAAO,MAAM,oBAAoB;IAC/B,gCAAgC;;IAEhC,kDAAkD;;IAElD,mDAAmD;;IAEnD,kCAAkC;;IAElC,8BAA8B;;CAEtB,CAAC;AAEX;;GAEG;AACH,eAAO,MAAM,kBAAkB;IAC7B,mCAAmC;;IAEnC,yDAAyD;;IAEzD,kDAAkD;;IAElD,yBAAyB;;IAEzB,iCAAiC;;CAEzB,CAAC"}

package/dist/types/rpc.js

@@ -0,0 +1,34 @@
+/**
+ * JSON-RPC 2.0 types for plugin communication
+ */
+/**
+ * Standard JSON-RPC error codes
+ */
+export const JSON_RPC_ERROR_CODES = {
+    /** Invalid JSON was received */
+    PARSE_ERROR: -32700,
+    /** The JSON sent is not a valid Request object */
+    INVALID_REQUEST: -32600,
+    /** The method does not exist / is not available */
+    METHOD_NOT_FOUND: -32601,
+    /** Invalid method parameter(s) */
+    INVALID_PARAMS: -32602,
+    /** Internal JSON-RPC error */
+    INTERNAL_ERROR: -32603,
+};
+/**
+ * Plugin-specific error codes (in the -32000 to -32099 range)
+ */
+export const PLUGIN_ERROR_CODES = {
+    /** Rate limited by external API */
+    RATE_LIMITED: -32001,
+    /** Resource not found (e.g., series ID doesn't exist) */
+    NOT_FOUND: -32002,
+    /** Authentication failed (invalid credentials) */
+    AUTH_FAILED: -32003,
+    /** External API error */
+    API_ERROR: -32004,
+    /** Plugin configuration error */
+    CONFIG_ERROR: -32005,
+};
+//# sourceMappingURL=rpc.js.map

package/dist/types/rpc.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rpc.js","sourceRoot":"","sources":["../../src/types/rpc.ts"],"names":[],"mappings":"AAAA;;GAEG;AA6BH;;GAEG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG;IAClC,gCAAgC;IAChC,WAAW,EAAE,CAAC,KAAK;IACnB,kDAAkD;IAClD,eAAe,EAAE,CAAC,KAAK;IACvB,mDAAmD;IACnD,gBAAgB,EAAE,CAAC,KAAK;IACxB,kCAAkC;IAClC,cAAc,EAAE,CAAC,KAAK;IACtB,8BAA8B;IAC9B,cAAc,EAAE,CAAC,KAAK;CACd,CAAC;AAEX;;GAEG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG;IAChC,mCAAmC;IACnC,YAAY,EAAE,CAAC,KAAK;IACpB,yDAAyD;IACzD,SAAS,EAAE,CAAC,KAAK;IACjB,kDAAkD;IAClD,WAAW,EAAE,CAAC,KAAK;IACnB,yBAAyB;IACzB,SAAS,EAAE,CAAC,KAAK;IACjB,iCAAiC;IACjC,YAAY,EAAE,CAAC,KAAK;CACZ,CAAC"}

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@ashdev/codex-plugin-sdk",
+  "version": "1.0.0",
+  "description": "SDK for building Codex plugins",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "clean": "rm -rf dist",
+    "prepublishOnly": "npm run lint && npm run build",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "biome check .",
+    "lint:fix": "biome check --write .",
+    "format": "biome format --write .",
+    "check": "biome check . && tsc --noEmit"
+  },
+  "keywords": [
+    "codex",
+    "plugin",
+    "sdk",
+    "metadata"
+  ],
+  "author": "Codex",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/AshDevFr/codex.git",
+    "directory": "plugins/sdk-typescript"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "codex": {
+    "protocolVersion": "1.0"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.3.11",
+    "@types/node": "^22.0.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0"
+  }
+}