@shisho/plugin-sdk 0.0.21

package/manifest.d.ts

@@ -0,0 +1,166 @@
+/** Input converter capability declaration. */
+export interface InputConverterCap {
+  description?: string;
+  /** File extensions this converter accepts (e.g., ["mobi"]). */
+  sourceTypes: string[];
+  /** MIME types this converter accepts. */
+  mimeTypes?: string[];
+  /** Target file type to convert to (e.g., "epub"). */
+  targetType: string;
+}
+
+/** File parser capability declaration. */
+export interface FileParserCap {
+  description?: string;
+  /** File extensions this parser handles (e.g., ["pdf"]). */
+  types: string[];
+  /** MIME types this parser handles (e.g., ["application/pdf"]). */
+  mimeTypes?: string[];
+}
+
+/** Output generator capability declaration. */
+export interface OutputGeneratorCap {
+  description?: string;
+  /** Unique format identifier (e.g., "mobi"). */
+  id: string;
+  /** Display name (e.g., "MOBI"). */
+  name: string;
+  /** Source file types this generator can convert from. */
+  sourceTypes: string[];
+}
+
+/** Valid metadata field names for enricher declarations. */
+export type MetadataField =
+  | "title"
+  | "subtitle"
+  | "authors"
+  | "narrators"
+  | "series"
+  | "seriesNumber"
+  | "genres"
+  | "tags"
+  | "description"
+  | "publisher"
+  | "imprint"
+  | "url"
+  | "releaseDate"
+  | "cover"
+  | "identifiers";
+
+/** Metadata enricher capability declaration. */
+export interface MetadataEnricherCap {
+  description?: string;
+  /** File types this enricher applies to (e.g., ["epub", "cbz"]). */
+  fileTypes?: string[];
+  /**
+   * Metadata fields this enricher may set.
+   * Required for enrichers - if omitted, the enricher hook is disabled.
+   */
+  fields: MetadataField[];
+}
+
+/** Custom identifier type declaration. */
+export interface IdentifierTypeCap {
+  /** Unique identifier type ID (e.g., "goodreads"). */
+  id: string;
+  /** Display name (e.g., "Goodreads"). */
+  name: string;
+  /** URL template with {value} placeholder. */
+  urlTemplate?: string;
+  /** Regex pattern for validation. */
+  pattern?: string;
+}
+
+/** HTTP access capability declaration. */
+export interface HTTPAccessCap {
+  description?: string;
+  /** Allowed domains for HTTP requests. */
+  domains: string[];
+}
+
+/** File access capability declaration. */
+export interface FileAccessCap {
+  /** Access level: "read" or "readwrite". */
+  level: "read" | "readwrite";
+  description?: string;
+}
+
+/** FFmpeg access capability declaration. */
+export interface FFmpegAccessCap {
+  description?: string;
+}
+
+/** Shell access capability declaration. */
+export interface ShellAccessCap {
+  description?: string;
+  /** Allowed commands (e.g., ["convert", "magick", "identify"]). */
+  commands: string[];
+}
+
+/** All plugin capabilities. */
+export interface Capabilities {
+  inputConverter?: InputConverterCap;
+  fileParser?: FileParserCap;
+  outputGenerator?: OutputGeneratorCap;
+  metadataEnricher?: MetadataEnricherCap;
+  identifierTypes?: IdentifierTypeCap[];
+  httpAccess?: HTTPAccessCap;
+  fileAccess?: FileAccessCap;
+  ffmpegAccess?: FFmpegAccessCap;
+  shellAccess?: ShellAccessCap;
+}
+
+/** Option for select-type config fields. */
+export interface SelectOption {
+  value: string;
+  label: string;
+}
+
+/** A single configuration field definition. */
+export interface ConfigField {
+  /** Field type. */
+  type: "string" | "boolean" | "number" | "select" | "textarea";
+  /** Display label. */
+  label: string;
+  /** Help text description. */
+  description?: string;
+  /** Whether this field is required. */
+  required?: boolean;
+  /** Whether this field contains sensitive data. */
+  secret?: boolean;
+  /** Default value. */
+  default?: string | number | boolean;
+  /** Minimum value (number fields). */
+  min?: number;
+  /** Maximum value (number fields). */
+  max?: number;
+  /** Options (select fields). */
+  options?: SelectOption[];
+}
+
+/** Configuration schema mapping field keys to definitions. */
+export interface ConfigSchema {
+  [key: string]: ConfigField;
+}
+
+/** Complete plugin manifest (manifest.json). */
+export interface PluginManifest {
+  /** Must be 1. */
+  manifestVersion: 1;
+  /** Plugin identifier (e.g., "goodreads-metadata"). */
+  id: string;
+  /** Display name. */
+  name: string;
+  /** Semver version string. */
+  version: string;
+  /** Short one-liner overview (separate from longer description). */
+  overview?: string;
+  description?: string;
+  author?: string;
+  homepage?: string;
+  license?: string;
+  /** Minimum Shisho version required. */
+  minShishoVersion?: string;
+  capabilities?: Capabilities;
+  configSchema?: ConfigSchema;
+}

package/metadata.d.ts

@@ -0,0 +1,77 @@
+/** An author with optional role information. */
+export interface ParsedAuthor {
+  /** Author name. */
+  name: string;
+  /** Role (empty for generic author, or one of: writer, penciller, inker, colorist, letterer, cover_artist, editor, translator). */
+  role?: string;
+}
+
+/** An identifier parsed from file metadata. */
+export interface ParsedIdentifier {
+  /** Identifier type (e.g., isbn_10, isbn_13, asin, uuid, goodreads, google, other). */
+  type: string;
+  /** The identifier value. */
+  value: string;
+}
+
+/** A chapter parsed from file metadata. */
+export interface ParsedChapter {
+  /** Chapter title. */
+  title: string;
+  /** CBZ: 0-indexed page number. */
+  startPage?: number;
+  /** M4B: milliseconds from start. */
+  startTimestampMs?: number;
+  /** EPUB: content document href. */
+  href?: string;
+  /** Nested child chapters (EPUB nesting only). */
+  children?: ParsedChapter[];
+}
+
+/** Full metadata object returned by file parsers and metadata enrichers. */
+export interface ParsedMetadata {
+  title?: string;
+  subtitle?: string;
+  authors?: ParsedAuthor[];
+  narrators?: string[];
+  series?: string;
+  seriesNumber?: number;
+  genres?: string[];
+  tags?: string[];
+  description?: string;
+  publisher?: string;
+  imprint?: string;
+  url?: string;
+  /** ISO 8601 date string (e.g., "2023-06-15T00:00:00Z"). */
+  releaseDate?: string;
+  /** MIME type of cover image (e.g., "image/jpeg"). */
+  coverMimeType?: string;
+  /**
+   * URL to download the cover image from. The server handles downloading and validates
+   * the domain against the plugin's httpAccess.domains. This is the recommended way for
+   * enricher plugins to provide covers.
+   */
+  coverUrl?: string;
+  /**
+   * Raw cover image data as an ArrayBuffer. Use this for file parsers that extract
+   * embedded covers, or enrichers that generate/composite images. If both coverData
+   * and coverUrl are set, coverData takes precedence (no download occurs).
+   */
+  coverData?: ArrayBuffer;
+  /** 0-indexed page number for CBZ cover. */
+  coverPage?: number;
+  /** Duration in seconds (float, M4B files). */
+  duration?: number;
+  /** Audio bitrate in bits per second (M4B files). */
+  bitrateBps?: number;
+  /** Number of pages (CBZ files). */
+  pageCount?: number;
+  identifiers?: ParsedIdentifier[];
+  chapters?: ParsedChapter[];
+  /**
+   * Confidence score (0-1) indicating how well this result matches the search query.
+   * Used by the scan pipeline to decide whether to auto-apply enrichment.
+   * If omitted, the result is always applied (backwards compatible).
+   */
+  confidence?: number;
+}

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@shisho/plugin-sdk",
+  "version": "0.0.21",
+  "description": "TypeScript SDK for Shisho plugin development — types, host API declarations, and test utilities",
+  "homepage": "https://github.com/shishobooks/shisho/blob/master/packages/plugin-sdk/README.md",
+  "types": "index.d.ts",
+  "exports": {
+    ".": "./index.d.ts",
+    "./testing": {
+      "types": "./testing/index.d.ts",
+      "import": "./testing/index.js",
+      "require": "./testing/index.js"
+    }
+  },
+  "files": [
+    "*.d.ts",
+    "testing/"
+  ],
+  "scripts": {
+    "build": "cd testing && npx tsc -p tsconfig.json"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/shishobooks/shisho.git",
+    "directory": "packages/plugin-sdk"
+  },
+  "dependencies": {
+    "fast-xml-parser": "^5.5.9",
+    "linkedom": "^0.18.12"
+  }
+}

package/testing/index.d.ts

@@ -0,0 +1,44 @@
+import type { ShishoHostAPI } from "../index";
+/** Configuration for a mock fetch response. */
+export interface MockFetchResponse {
+    /** HTTP status code (default: 200). */
+    status?: number;
+    /** Response body as string (default: ""). */
+    body?: string;
+    /** Response headers (default: {}). */
+    headers?: Record<string, string>;
+}
+/** Options for createMockShisho(). */
+export interface MockShishoOptions {
+    /** Route-based fetch mock. Keys are URL strings, values are mock responses. */
+    fetch?: Record<string, MockFetchResponse>;
+    /** Config key-value pairs returned by shisho.config. */
+    config?: Record<string, string>;
+    /**
+     * Path-based filesystem mock.
+     * - string values are returned by readTextFile/readFile
+     * - Buffer values are returned by readFile (as ArrayBuffer)
+     * - string[] values are returned by listDir
+     */
+    fs?: Record<string, string | Buffer | string[]>;
+}
+/**
+ * Create a mock `shisho` host API object for testing plugins.
+ *
+ * Provides mock implementations of log, config, http, url, and fs.
+ * Provides real implementations of xml and html (backed by fast-xml-parser and linkedom).
+ *
+ * @example
+ * ```ts
+ * const shisho = createMockShisho({
+ *   fetch: {
+ *     "https://api.example.com/search?q=test": {
+ *       status: 200,
+ *       body: JSON.stringify({ results: [] }),
+ *     },
+ *   },
+ *   config: { apiKey: "test-key" },
+ * });
+ * ```
+ */
+export declare function createMockShisho(options?: MockShishoOptions): ShishoHostAPI;