@shisho/plugin-sdk 0.0.21

package/README.md

@@ -0,0 +1,119 @@
+# @shisho/plugin-sdk
+
+TypeScript SDK for [Shisho](https://github.com/shishobooks/shisho) plugin development. Provides IDE autocompletion and type checking for the `shisho.*` host APIs, hook contexts, metadata structures, and manifest schema.
+
+## Installation
+
+```bash
+npm install --save-dev @shisho/plugin-sdk
+```
+
+## Usage
+
+The types provide autocompletion for:
+
+- **`shisho.*`** - Host APIs (log, config, http, fs, archive, xml, ffmpeg)
+- **`plugin`** - Hook structure (inputConverter, fileParser, metadataEnricher, outputGenerator)
+- **Hook contexts** - Typed `context` parameters for each hook method
+- **Return types** - `ParsedMetadata`, `ConvertResult`, `SearchResponse`, etc.
+
+### TypeScript
+
+If you write your plugin in TypeScript (and compile to JavaScript for deployment), import the types directly:
+
+```typescript
+import type {
+  FileParserContext,
+  ParsedMetadata,
+  SearchContext,
+  SearchResponse,
+  ShishoPlugin,
+} from "@shisho/plugin-sdk";
+
+const plugin: ShishoPlugin = {
+  fileParser: {
+    parse(context: FileParserContext): ParsedMetadata {
+      const content = shisho.fs.readTextFile(context.filePath);
+      return {
+        title: "My Book",
+        authors: [{ name: "Author Name", role: "writer" }],
+        identifiers: [{ type: "isbn_13", value: "9781234567890" }],
+      };
+    },
+  },
+
+  metadataEnricher: {
+    search(context: SearchContext): SearchResponse {
+      const apiKey = shisho.config.get("apiKey");
+      const resp = shisho.http.fetch(
+        `https://api.example.com/search?q=${context.query}`,
+        { method: "GET" },
+      );
+      const data = resp.json() as {
+        results: Array<{ title: string; description: string }>;
+      };
+      return {
+        results: data.results.map((r) => ({
+          title: r.title,
+          description: r.description,
+        })),
+      };
+    },
+  },
+};
+```
+
+### JavaScript with JSDoc
+
+Add a triple-slash reference at the top of your `main.js` and use JSDoc annotations for type checking:
+
+```javascript
+/// <reference types="@shisho/plugin-sdk" />
+
+var plugin = (function () {
+  return {
+    fileParser: {
+      /** @param {FileParserContext} context @returns {ParsedMetadata} */
+      parse: function (context) {
+        var content = shisho.fs.readTextFile(context.filePath);
+        return {
+          title: "My Book",
+          authors: [{ name: "Author Name" }],
+        };
+      },
+    },
+
+    metadataEnricher: {
+      /** @param {SearchContext} context @returns {SearchResponse} */
+      search: function (context) {
+        var apiKey = shisho.config.get("apiKey");
+        var resp = shisho.http.fetch(
+          "https://api.example.com/search?q=" + context.query,
+          { method: "GET" },
+        );
+        var data = resp.json();
+        return {
+          results: data.results.map(function (r) {
+            return { title: r.title, description: r.description };
+          }),
+        };
+      },
+    },
+  };
+})();
+```
+
+## What's Included
+
+| File            | Contents                                                              |
+| --------------- | --------------------------------------------------------------------- |
+| `global.d.ts`   | Global `shisho` and `plugin` variable declarations                    |
+| `host-api.d.ts` | `ShishoHostAPI` and all namespace interfaces                          |
+| `hooks.d.ts`    | Hook context/result types and `ShishoPlugin` interface                |
+| `metadata.d.ts` | `ParsedMetadata`, `ParsedAuthor`, `ParsedIdentifier`, `ParsedChapter` |
+| `manifest.d.ts` | `PluginManifest`, `Capabilities`, `ConfigSchema`                      |
+
+## Links
+
+- [Plugin Development Guide](https://github.com/shishobooks/shisho/blob/master/docs/plugins.md)
+- [Shisho Repository](https://github.com/shishobooks/shisho)

package/global.d.ts

@@ -0,0 +1,9 @@
+import { ShishoPlugin } from "./hooks";
+import { ShishoHostAPI } from "./host-api";
+
+declare global {
+  /** Host API object providing logging, config, HTTP, URL utilities, filesystem, archive, XML, FFmpeg, and shell access. */
+  var shisho: ShishoHostAPI;
+  /** Plugin object that defines hook implementations. */
+  var plugin: ShishoPlugin;
+}

package/hooks.d.ts

@@ -0,0 +1,130 @@
+import { ParsedMetadata } from "./metadata";
+
+/** Context passed to inputConverter.convert(). */
+export interface InputConverterContext {
+  /** Path to the input file. */
+  sourcePath: string;
+  /** Directory where the converted output should be written. */
+  targetDir: string;
+}
+
+/** Result returned from inputConverter.convert(). */
+export interface ConvertResult {
+  /** Whether conversion succeeded. */
+  success: boolean;
+  /** Path to the converted output file. */
+  targetPath: string;
+}
+
+/** Context passed to fileParser.parse(). */
+export interface FileParserContext {
+  /** Path to the file being parsed. */
+  filePath: string;
+  /** File extension (e.g., "pdf", "epub"). */
+  fileType: string;
+}
+
+/** Context passed to metadataEnricher.search(). */
+export interface SearchContext {
+  /** Search query — title or free-text. Always present. */
+  query: string;
+  /** Author name to narrow results. Optional. */
+  author?: string;
+  /** Structured identifiers for direct lookup (ISBN, ASIN, etc.). Optional. */
+  identifiers?: Array<{ type: string; value: string }>;
+  /** Read-only file metadata for matching hints. Not user-editable. */
+  file?: {
+    /** File type extension (e.g., "epub", "cbz", "m4b", "pdf"). */
+    fileType?: string;
+    /** Audiobook duration in seconds. */
+    duration?: number;
+    /** Number of pages (CBZ/PDF). */
+    pageCount?: number;
+    /** File size in bytes. */
+    filesizeBytes?: number;
+  };
+}
+
+/** Result returned from metadataEnricher.search(). */
+export interface SearchResponse {
+  results: ParsedMetadata[];
+}
+
+/** Context passed to outputGenerator.generate(). */
+export interface OutputGeneratorContext {
+  /** Path to the source book file. */
+  sourcePath: string;
+  /** Path where the output file should be written. */
+  destPath: string;
+  /** Book metadata. */
+  book: {
+    title?: string;
+    authors?: Array<{ name: string; role?: string }>;
+    series?: string;
+    seriesNumber?: number;
+    publisher?: string;
+    description?: string;
+    genres?: string[];
+    tags?: string[];
+    identifiers?: Array<{ type: string; value: string }>;
+  };
+  /** File metadata. */
+  file: {
+    fileType?: string;
+    filePath?: string;
+  };
+}
+
+/** Context passed to outputGenerator.fingerprint(). */
+export interface FingerprintContext {
+  /** Book metadata. */
+  book: {
+    title?: string;
+    authors?: Array<{ name: string; role?: string }>;
+    series?: string;
+    seriesNumber?: number;
+    publisher?: string;
+  };
+  /** File metadata. */
+  file: {
+    fileType?: string;
+    filePath?: string;
+  };
+}
+
+/** Input converter hook. */
+export interface InputConverterHook {
+  convert(context: InputConverterContext): ConvertResult;
+}
+
+/** File parser hook. */
+export interface FileParserHook {
+  parse(context: FileParserContext): ParsedMetadata;
+}
+
+/** Metadata enricher hook. */
+export interface MetadataEnricherHook {
+  /** Search for candidate results from external sources. */
+  search(context: SearchContext): SearchResponse;
+}
+
+/** Output generator hook. */
+export interface OutputGeneratorHook {
+  generate(context: OutputGeneratorContext): void;
+  fingerprint(context: FingerprintContext): string;
+}
+
+/** The plugin object exported by main.js via IIFE. */
+export interface ShishoPlugin {
+  inputConverter?: InputConverterHook;
+  fileParser?: FileParserHook;
+  metadataEnricher?: MetadataEnricherHook;
+  outputGenerator?: OutputGeneratorHook;
+
+  /**
+   * Optional lifecycle hook called before the plugin is uninstalled.
+   * Use this to clean up resources (revoke tokens, delete caches, close connections).
+   * Errors in this hook do not prevent uninstall.
+   */
+  onUninstalling?: () => void;
+}

package/host-api.d.ts

@@ -0,0 +1,408 @@
+/** Logging methods. */
+export interface ShishoLog {
+  debug(msg: string): void;
+  info(msg: string): void;
+  warn(msg: string): void;
+  error(msg: string): void;
+}
+
+/** Plugin configuration access. */
+export interface ShishoConfig {
+  /** Get a single config value by key. Returns undefined if not set. */
+  get(key: string): string | undefined;
+  /** Get all config values as a key-value map. */
+  getAll(): Record<string, string>;
+}
+
+/** Options for shisho.http.fetch(). */
+export interface FetchOptions {
+  /** HTTP method (default: "GET"). */
+  method?: string;
+  /** Request headers. */
+  headers?: Record<string, string>;
+  /** Request body string. */
+  body?: string;
+}
+
+/** Response from shisho.http.fetch(). */
+export interface FetchResponse {
+  /** Whether the status code is 2xx. */
+  ok: boolean;
+  /** HTTP status code. */
+  status: number;
+  /** HTTP status text. */
+  statusText: string;
+  /** Response headers (lowercase keys). */
+  headers: Record<string, string>;
+  /** Get response body as string. */
+  text(): string;
+  /** Get response body as ArrayBuffer. */
+  arrayBuffer(): ArrayBuffer;
+  /** Parse response body as JSON. */
+  json(): unknown;
+}
+
+/**
+ * HTTP client with domain whitelisting.
+ *
+ * Domain patterns in manifest httpAccess.domains:
+ * - Exact match: "example.com" only allows "example.com"
+ * - Wildcard: "*.example.com" allows "example.com", "api.example.com", "a.b.example.com"
+ */
+export interface ShishoHTTP {
+  /**
+   * Fetch a URL. Domain must be declared in manifest httpAccess.domains.
+   * Supports wildcard patterns like "*.example.com" for subdomains.
+   */
+  fetch(url: string, options?: FetchOptions): FetchResponse;
+}
+
+/** Parsed URL components from shisho.url.parse(). */
+export interface ParsedURL {
+  /** The original URL string. */
+  href: string;
+  /** URL scheme without ":" (e.g., "https"). */
+  protocol: string;
+  /** Host including port if present (e.g., "example.com:8080"). */
+  host: string;
+  /** Hostname without port (e.g., "example.com"). */
+  hostname: string;
+  /** Port number as string, or empty if not specified. */
+  port: string;
+  /** Path component (e.g., "/path/to/resource"). */
+  pathname: string;
+  /** Query string with leading "?" or empty string. */
+  search: string;
+  /** Fragment with leading "#" or empty string. */
+  hash: string;
+  /** Username from URL, or empty string. */
+  username: string;
+  /** Password from URL, or empty string. */
+  password: string;
+  /** Parsed query parameters. Single values are strings, repeated keys are arrays. */
+  query: Record<string, string | string[]>;
+}
+
+/**
+ * URL utilities that aren't available in Goja's ES5.1 runtime.
+ * Provides functionality similar to browser URLSearchParams and URL APIs.
+ */
+export interface ShishoURL {
+  /**
+   * Encode a string for use in URL query parameters.
+   * Similar to JavaScript's encodeURIComponent().
+   */
+  encodeURIComponent(str: string): string;
+
+  /**
+   * Decode a URL-encoded string.
+   * Similar to JavaScript's decodeURIComponent().
+   */
+  decodeURIComponent(str: string): string;
+
+  /**
+   * Convert an object to a URL query string.
+   * Keys are sorted alphabetically for deterministic output.
+   * Array values create multiple key=value pairs.
+   * Null/undefined values are skipped.
+   *
+   * @example
+   * shisho.url.searchParams({ q: "test", page: 1 }) // "page=1&q=test"
+   * shisho.url.searchParams({ tags: ["a", "b"] })   // "tags=a&tags=b"
+   */
+  searchParams(params: Record<string, unknown>): string;
+
+  /**
+   * Parse a URL string into its components.
+   *
+   * @example
+   * const url = shisho.url.parse("https://api.example.com/search?q=test");
+   * url.hostname // "api.example.com"
+   * url.pathname // "/search"
+   * url.query.q  // "test"
+   */
+  parse(url: string): ParsedURL;
+}
+
+/** Filesystem operations (sandboxed). */
+export interface ShishoFS {
+  /** Read file contents as ArrayBuffer. */
+  readFile(path: string): ArrayBuffer;
+  /** Read file contents as UTF-8 string. */
+  readTextFile(path: string): string;
+  /** Write ArrayBuffer data to a file. */
+  writeFile(path: string, data: ArrayBuffer): void;
+  /** Write string content to a file. */
+  writeTextFile(path: string, content: string): void;
+  /** Check if a path exists. */
+  exists(path: string): boolean;
+  /** Create a directory (and parents). */
+  mkdir(path: string): void;
+  /** List directory entries (file/dir names). */
+  listDir(path: string): string[];
+  /** Get a temporary directory path (auto-cleaned after hook returns). */
+  tempDir(): string;
+}
+
+/** ZIP archive operations. */
+export interface ShishoArchive {
+  /** Extract all entries from a ZIP archive to a directory. */
+  extractZip(archivePath: string, destDir: string): void;
+  /** Create a ZIP archive from a directory's contents. */
+  createZip(srcDir: string, destPath: string): void;
+  /** Read a specific entry from a ZIP archive as ArrayBuffer. */
+  readZipEntry(archivePath: string, entryPath: string): ArrayBuffer;
+  /** List all entry paths in a ZIP archive. */
+  listZipEntries(archivePath: string): string[];
+}
+
+/** A parsed XML element. */
+export interface XMLElement {
+  /** Element tag name (local part). */
+  tag: string;
+  /** Element namespace URI. */
+  namespace: string;
+  /** Direct text content. */
+  text: string;
+  /** Element attributes. */
+  attributes: Record<string, string>;
+  /** Child elements. */
+  children: XMLElement[];
+}
+
+/** XML parsing and querying. */
+export interface ShishoXML {
+  /** Parse an XML string into an element tree. */
+  parse(content: string): XMLElement;
+  /** Find the first element matching a selector. Supports "prefix|tag" namespace syntax. */
+  querySelector(
+    doc: XMLElement,
+    selector: string,
+    namespaces?: Record<string, string>,
+  ): XMLElement | null;
+  /** Find all elements matching a selector. Supports "prefix|tag" namespace syntax. */
+  querySelectorAll(
+    doc: XMLElement,
+    selector: string,
+    namespaces?: Record<string, string>,
+  ): XMLElement[];
+}
+
+/** A parsed HTML element returned by shisho.html queries. */
+export interface HtmlElement {
+  /** Element tag name (e.g., "div", "meta", "script"). */
+  tag: string;
+  /** Element attributes as key-value pairs. */
+  attributes: Record<string, string>;
+  /** Recursive inner text content (all text nodes concatenated). */
+  text: string;
+  /** Raw inner HTML string. Useful for script tags (JSON-LD) or rich content. */
+  innerHTML: string;
+  /** Direct child elements. */
+  children: HtmlElement[];
+}
+
+/** HTML parsing with CSS selector support. Uses a two-step parse-then-query pattern. */
+export interface ShishoHTML {
+  /**
+   * Parse an HTML string into an element tree.
+   * Returns the root element with stored node references for efficient querying.
+   *
+   * @example
+   * var doc = shisho.html.parse(htmlString);
+   * var title = shisho.html.querySelector(doc, "title");
+   */
+  parse(html: string): HtmlElement;
+
+  /**
+   * Find the first element matching a CSS selector.
+   * Supports full CSS selector syntax (attribute selectors, combinators, pseudo-classes).
+   * The doc argument must be a parsed element from shisho.html.parse() or a previous query result.
+   *
+   * @example
+   * var doc = shisho.html.parse(html);
+   * var meta = shisho.html.querySelector(doc, 'meta[name="description"]');
+   * var description = meta ? meta.attributes.content : "";
+   */
+  querySelector(doc: HtmlElement, selector: string): HtmlElement | null;
+
+  /**
+   * Find all elements matching a CSS selector.
+   * The doc argument must be a parsed element from shisho.html.parse() or a previous query result.
+   *
+   * @example
+   * var doc = shisho.html.parse(html);
+   * var scripts = shisho.html.querySelectorAll(doc, 'script[type="application/ld+json"]');
+   * var jsonLd = JSON.parse(scripts[0].text);
+   */
+  querySelectorAll(doc: HtmlElement, selector: string): HtmlElement[];
+}
+
+/** Result from shisho.ffmpeg.transcode(). */
+export interface TranscodeResult {
+  /** Process exit code (0 = success). */
+  exitCode: number;
+  /** Standard output. */
+  stdout: string;
+  /** Standard error. */
+  stderr: string;
+}
+
+/** Result from shisho.ffmpeg.probe(). */
+export interface ProbeResult {
+  format: ProbeFormat;
+  streams: ProbeStream[];
+  chapters: ProbeChapter[];
+  /** Standard error output (for debugging). */
+  stderr: string;
+  /** JSON parse error message if ffprobe output could not be parsed. Empty string if parsing succeeded. */
+  parseError: string;
+}
+
+/** Format information from ffprobe. */
+export interface ProbeFormat {
+  filename: string;
+  nb_streams: number;
+  nb_programs: number;
+  format_name: string;
+  format_long_name: string;
+  start_time: string;
+  duration: string;
+  size: string;
+  bit_rate: string;
+  probe_score: number;
+  tags?: Record<string, string>;
+}
+
+/** Stream information from ffprobe. */
+export interface ProbeStream {
+  index: number;
+  codec_name?: string;
+  codec_long_name?: string;
+  codec_type: "video" | "audio" | "subtitle" | "data" | "attachment";
+  codec_tag_string?: string;
+  codec_tag?: string;
+
+  // Video-specific
+  width?: number;
+  height?: number;
+  coded_width?: number;
+  coded_height?: number;
+  closed_captions?: number;
+  has_b_frames?: number;
+  sample_aspect_ratio?: string;
+  display_aspect_ratio?: string;
+  pix_fmt?: string;
+  level?: number;
+  color_range?: string;
+  color_space?: string;
+  color_transfer?: string;
+  color_primaries?: string;
+  chroma_location?: string;
+  field_order?: string;
+  refs?: number;
+
+  // Audio-specific
+  sample_fmt?: string;
+  sample_rate?: string;
+  channels?: number;
+  channel_layout?: string;
+  bits_per_sample?: number;
+
+  // Common (optional since not all stream types have these)
+  r_frame_rate?: string;
+  avg_frame_rate?: string;
+  time_base?: string;
+  start_pts?: number;
+  start_time?: string;
+  duration_ts?: number;
+  duration?: string;
+  bit_rate?: string;
+  bits_per_raw_sample?: string;
+  nb_frames?: string;
+  disposition?: ProbeDisposition;
+  tags?: Record<string, string>;
+}
+
+/** Stream disposition flags from ffprobe. */
+export interface ProbeDisposition {
+  default: number;
+  dub: number;
+  original: number;
+  comment: number;
+  lyrics: number;
+  karaoke: number;
+  forced: number;
+  hearing_impaired: number;
+  visual_impaired: number;
+  clean_effects: number;
+  attached_pic: number;
+  timed_thumbnails: number;
+}
+
+/** Chapter information from ffprobe. */
+export interface ProbeChapter {
+  id: number;
+  time_base: string;
+  start: number;
+  start_time: string;
+  end: number;
+  end_time: string;
+  tags?: Record<string, string>;
+}
+
+/** Result from shisho.ffmpeg.version(). */
+export interface VersionResult {
+  /** FFmpeg version string (e.g., "7.0"). */
+  version: string;
+  /** Build configuration flags (e.g., ["--enable-libx264", "--enable-gpl"]). */
+  configuration: string[];
+  /** Library versions (e.g., { libavcodec: "60.31.102", ... }). */
+  libraries: Record<string, string>;
+}
+
+/** FFmpeg subprocess execution. */
+export interface ShishoFFmpeg {
+  /** Transcode files with FFmpeg. Requires ffmpegAccess capability. */
+  transcode(args: string[]): TranscodeResult;
+  /** Probe file metadata with ffprobe. Returns parsed JSON. Requires ffmpegAccess capability. */
+  probe(args: string[]): ProbeResult;
+  /** Get FFmpeg version and configuration. Requires ffmpegAccess capability. */
+  version(): VersionResult;
+}
+
+/** Result from shisho.shell.exec(). */
+export interface ExecResult {
+  /** Process exit code (0 = success). */
+  exitCode: number;
+  /** Standard output. */
+  stdout: string;
+  /** Standard error. */
+  stderr: string;
+}
+
+/** Shell command execution (with allowlist). */
+export interface ShishoShell {
+  /**
+   * Execute an allowed command with arguments.
+   * Command must be declared in manifest shellAccess.commands.
+   * Uses exec directly (no shell) to prevent injection.
+   */
+  exec(command: string, args: string[]): ExecResult;
+}
+
+/** Top-level host API object available as the global `shisho` variable. */
+export interface ShishoHostAPI {
+  /** Persistent data directory for this plugin. Created lazily on first access. */
+  readonly dataDir: string;
+  log: ShishoLog;
+  config: ShishoConfig;
+  http: ShishoHTTP;
+  url: ShishoURL;
+  fs: ShishoFS;
+  archive: ShishoArchive;
+  xml: ShishoXML;
+  html: ShishoHTML;
+  ffmpeg: ShishoFFmpeg;
+  shell: ShishoShell;
+}

package/index.d.ts

@@ -0,0 +1,6 @@
+import "./global";
+
+export * from "./metadata";
+export * from "./manifest";
+export * from "./host-api";
+export * from "./hooks";