@shisho/plugin-sdk 0.0.49 → 0.0.50

package/hooks.d.ts

@@ -62,46 +62,47 @@ export interface SearchResponse {
   results: ParsedMetadata[];
 }
 
+/** Book metadata passed to output-generator hooks. */
+export interface OutputBookContext {
+  id?: number;
+  title?: string;
+  subtitle?: string;
+  description?: string;
+  authors?: Array<{ name: string; role?: string }>;
+  series?: Array<{ name: string; number?: number }>;
+  genres?: string[];
+  tags?: string[];
+}
+
+/** File metadata passed to output-generator hooks. */
+export interface OutputFileContext {
+  id?: number;
+  filepath?: string;
+  fileType?: string;
+  fileRole?: string;
+  filesizeBytes?: number;
+  name?: string;
+  url?: string;
+  publisher?: string;
+  releaseDate?: string;
+  narrators?: string[];
+  identifiers?: Array<{ type: string; value: string }>;
+}
+
 /** 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;
-  };
+  book: OutputBookContext;
+  file: OutputFileContext;
 }
 
 /** 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;
-  };
+  book: OutputBookContext;
+  file: OutputFileContext;
 }
 
 /** Input converter hook. */
@@ -126,7 +127,7 @@ export interface OutputGeneratorHook {
   fingerprint(context: FingerprintContext): string;
 }
 
-/** The plugin object exported by main.js via IIFE. */
+/** The global plugin object created by main.js. */
 export interface ShishoPlugin {
   inputConverter?: InputConverterHook;
   fileParser?: FileParserHook;

package/metadata.d.ts

@@ -35,7 +35,14 @@ export interface ParsedMetadata {
   authors?: ParsedAuthor[];
   narrators?: string[];
   series?: string;
+  /**
+   * Series position. Must be finite. An optional seriesNumberEnd must also be
+   * finite and greater than this value. If the start, end, or unit is invalid,
+   * Shisho discards the complete series-number group.
+   */
   seriesNumber?: number;
+  /** Optional inclusive end for an omnibus series range. Requires seriesNumber. */
+  seriesNumberEnd?: number;
   /** Whether the series number refers to a volume or a chapter. CBZ only. */
   seriesNumberUnit?: "volume" | "chapter";
   genres?: string[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shisho/plugin-sdk",
-  "version": "0.0.49",
+  "version": "0.0.50",
   "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",
@@ -17,7 +17,7 @@
     "testing/"
   ],
   "scripts": {
-    "build": "cd testing && npx tsc -p tsconfig.json"
+    "build": "cd testing && npx tsc -p tsconfig.json && npx tsc -p type-contract.tsconfig.json"
   },
   "license": "MIT",
   "repository": {
@@ -26,8 +26,8 @@
     "directory": "packages/plugin-sdk"
   },
   "dependencies": {
-    "fast-xml-parser": "^5.8.0",
-    "linkedom": "^0.18.12",
+    "fast-xml-parser": "^5.10.1",
+    "linkedom": "^0.18.13",
     "yaml": "^2.9.0"
   }
 }

package/testing/type-contract.ts

@@ -0,0 +1,30 @@
+import type { OutputGeneratorContext, ParsedMetadata } from "../index";
+
+type Equal<Left, Right> =
+  (<Type>() => Type extends Left ? 1 : 2) extends <Type>() => Type extends Right
+    ? 1
+    : 2
+    ? true
+    : false;
+type Expect<Type extends true> = Type;
+
+type SeriesNumberEndContract = Expect<
+  Equal<ParsedMetadata["seriesNumberEnd"], number | undefined>
+>;
+
+type OutputSeriesContract = Expect<
+  Equal<
+    OutputGeneratorContext["book"]["series"],
+    Array<{ name: string; number?: number }> | undefined
+  >
+>;
+
+type OutputFilepathContract = Expect<
+  Equal<OutputGeneratorContext["file"]["filepath"], string | undefined>
+>;
+
+export type {
+  OutputFilepathContract,
+  OutputSeriesContract,
+  SeriesNumberEndContract,
+};

package/testing/type-contract.tsconfig.json

@@ -0,0 +1,7 @@
+{
+  "extends": "../tsconfig.json",
+  "compilerOptions": {
+    "noEmit": true
+  },
+  "files": ["type-contract.ts"]
+}