@shisho/plugin-types 0.0.0

package/README.md

@@ -0,0 +1,114 @@
+# @shisho/plugin-types
+
+TypeScript type definitions 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-types
+```
+
+## 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`, `EnrichmentResult`, etc.
+
+### TypeScript
+
+If you write your plugin in TypeScript (and compile to JavaScript for deployment), import the types directly:
+
+```typescript
+import type {
+  EnrichmentResult,
+  FileParserContext,
+  MetadataEnricherContext,
+  ParsedMetadata,
+  ShishoPlugin,
+} from "@shisho/plugin-types";
+
+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: {
+    enrich(context: MetadataEnricherContext): EnrichmentResult {
+      const apiKey = shisho.config.get("apiKey");
+      const resp = shisho.http.fetch(
+        `https://api.example.com/lookup?title=${context.book.title}`,
+        { method: "GET" },
+      );
+      const data = resp.json() as { description: string };
+      return {
+        modified: true,
+        metadata: { description: data.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-types" />
+
+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 {MetadataEnricherContext} context @returns {EnrichmentResult} */
+      enrich: function (context) {
+        var apiKey = shisho.config.get("apiKey");
+        var resp = shisho.http.fetch(
+          "https://api.example.com/lookup?title=" + context.book.title,
+          { method: "GET" },
+        );
+        var data = resp.json();
+        return {
+          modified: true,
+          metadata: { description: data.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,11 @@
+import { ShishoPlugin } from "./hooks";
+import { ShishoHostAPI } from "./host-api";
+
+declare global {
+  /** Host API object providing logging, config, HTTP, filesystem, archive, XML, and FFmpeg access. */
+  // eslint-disable-next-line no-var
+  var shisho: ShishoHostAPI;
+  /** Plugin object that defines hook implementations. */
+  // eslint-disable-next-line no-var
+  var plugin: ShishoPlugin;
+}

package/hooks.d.ts

@@ -0,0 +1,149 @@
+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.enrich(). */
+export interface MetadataEnricherContext {
+  /** Metadata freshly parsed from the file on disk (e.g., from ComicInfo.xml, OPF, etc.). */
+  parsedMetadata: {
+    title?: string;
+    subtitle?: string;
+    series?: string;
+    seriesNumber?: number;
+    description?: string;
+    publisher?: string;
+    imprint?: string;
+    url?: string;
+    dataSource?: string;
+    authors?: Array<{ name: string; role?: string }>;
+    narrators?: string[];
+    genres?: string[];
+    tags?: string[];
+    releaseDate?: string;
+    identifiers?: Array<{ type: string; value: string }>;
+  };
+  /** File information from the database. */
+  file: {
+    id?: number;
+    filepath?: string;
+    fileType?: string;
+    fileRole?: string;
+    filesizeBytes?: number;
+    name?: string;
+    url?: string;
+  };
+  /** Current book state from the database, including manually-edited fields. */
+  book: {
+    id?: number;
+    title?: string;
+    subtitle?: string;
+    description?: string;
+    series?: Array<{ name: string; number?: number }>;
+    authors?: Array<{ name: string; role?: string }>;
+    genres?: string[];
+    tags?: string[];
+    identifiers?: Array<{ type: string; value: string }>;
+    publisher?: string;
+  };
+}
+
+/** Result returned from metadataEnricher.enrich(). */
+export interface EnrichmentResult {
+  /** Whether metadata was modified. */
+  modified: boolean;
+  /** Updated metadata (only used if modified is true). */
+  metadata?: 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 {
+  enrich(context: MetadataEnricherContext): EnrichmentResult;
+}
+
+/** 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;
+}

package/host-api.d.ts

@@ -0,0 +1,140 @@
+/** 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. */
+export interface ShishoHTTP {
+  /** Fetch a URL. Domain must be declared in manifest httpAccess.domains. */
+  fetch(url: string, options?: FetchOptions): FetchResponse;
+}
+
+/** 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[];
+}
+
+/** Result from shisho.ffmpeg.run(). */
+export interface FFmpegResult {
+  /** Process exit code (0 = success). */
+  exitCode: number;
+  /** Standard output. */
+  stdout: string;
+  /** Standard error. */
+  stderr: string;
+}
+
+/** FFmpeg subprocess execution. */
+export interface ShishoFFmpeg {
+  /** Run FFmpeg with the given arguments. Requires ffmpegAccess capability. */
+  run(args: string[]): FFmpegResult;
+}
+
+/** Top-level host API object available as the global `shisho` variable. */
+export interface ShishoHostAPI {
+  log: ShishoLog;
+  config: ShishoConfig;
+  http: ShishoHTTP;
+  fs: ShishoFS;
+  archive: ShishoArchive;
+  xml: ShishoXML;
+  ffmpeg: ShishoFFmpeg;
+}

package/index.d.ts

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

package/manifest.d.ts

@@ -0,0 +1,133 @@
+/** 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[];
+}
+
+/** Metadata enricher capability declaration. */
+export interface MetadataEnricherCap {
+  description?: string;
+  /** File types this enricher applies to (e.g., ["epub", "cbz"]). */
+  fileTypes?: string[];
+}
+
+/** 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;
+}
+
+/** All plugin capabilities. */
+export interface Capabilities {
+  inputConverter?: InputConverterCap;
+  fileParser?: FileParserCap;
+  outputGenerator?: OutputGeneratorCap;
+  metadataEnricher?: MetadataEnricherCap;
+  identifierTypes?: IdentifierTypeCap[];
+  httpAccess?: HTTPAccessCap;
+  fileAccess?: FileAccessCap;
+  ffmpegAccess?: FFmpegAccessCap;
+}
+
+/** 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;
+  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,61 @@
+/** 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;
+  /** Cover image data as ArrayBuffer. */
+  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[];
+}

package/package.json

@@ -0,0 +1,11 @@
+{
+  "name": "@shisho/plugin-types",
+  "version": "0.0.0",
+  "description": "TypeScript type definitions for Shisho plugin development",
+  "homepage": "https://github.com/shishobooks/shisho/blob/master/packages/plugin-types/README.md",
+  "types": "index.d.ts",
+  "files": [
+    "*.d.ts"
+  ],
+  "license": "MIT"
+}