@shisho/plugin-sdk 0.0.26 → 0.0.28

package/host-api.d.ts

@@ -395,6 +395,28 @@ export interface ShishoShell {
 export interface ShishoHostAPI {
   /** Persistent data directory for this plugin. Created lazily on first access. */
   readonly dataDir: string;
+  /**
+   * Block the plugin for the given number of milliseconds.
+   *
+   * Goja has no Promise/setTimeout support, so this is a synchronous delay
+   * backed by Go's `time.Sleep`. Use it to implement exponential backoff
+   * between retries when calling rate-limited APIs. The sleep honors the
+   * hook's deadline: if the ctx is cancelled while the plugin is sleeping,
+   * the call unblocks immediately and the hook throws.
+   *
+   * @param ms Finite non-negative milliseconds. Throws on negative, NaN, or
+   * Infinity.
+   * @example
+   * // Exponential backoff: 1s, 2s, 4s
+   * var resp;
+   * for (var attempt = 0; attempt < 3; attempt++) {
+   *   resp = shisho.http.fetch(url, {});
+   *   if (resp.status !== 503) return resp;
+   *   shisho.sleep(1000 * Math.pow(2, attempt));
+   * }
+   * return resp; // retries exhausted — return the last 503
+   */
+  sleep(ms: number): void;
   log: ShishoLog;
   config: ShishoConfig;
   http: ShishoHTTP;

package/manifest.d.ts

@@ -45,7 +45,9 @@ export type MetadataField =
   | "url"
   | "releaseDate"
   | "cover"
-  | "identifiers";
+  | "identifiers"
+  | "language"
+  | "abridged";
 
 /** Metadata enricher capability declaration. */
 export interface MetadataEnricherCap {

package/metadata.d.ts

@@ -42,6 +42,10 @@ export interface ParsedMetadata {
   publisher?: string;
   imprint?: string;
   url?: string;
+  /** BCP 47 language tag (e.g., "en", "en-US", "zh-Hans"). */
+  language?: string;
+  /** Whether this is an abridged edition. true=abridged, false=unabridged, undefined=unknown. */
+  abridged?: boolean;
   /** ISO 8601 date string (e.g., "2023-06-15T00:00:00Z"). */
   releaseDate?: string;
   /** MIME type of cover image (e.g., "image/jpeg"). */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shisho/plugin-sdk",
-  "version": "0.0.26",
+  "version": "0.0.28",
   "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",
@@ -26,7 +26,7 @@
     "directory": "packages/plugin-sdk"
   },
   "dependencies": {
-    "fast-xml-parser": "^5.5.9",
+    "fast-xml-parser": "^5.5.11",
     "linkedom": "^0.18.12"
   }
 }

package/testing/index.d.ts

@@ -17,10 +17,21 @@ export interface MockShishoOptions {
     /**
      * Path-based filesystem mock.
      * - string values are returned by readTextFile/readFile
-     * - Buffer values are returned by readFile (as ArrayBuffer)
+     * - Uint8Array (or Buffer) values are returned by readFile (as ArrayBuffer)
      * - string[] values are returned by listDir
      */
-    fs?: Record<string, string | Buffer | string[]>;
+    fs?: Record<string, string | Uint8Array | string[]>;
+    /**
+     * Override the `sleep` implementation. Defaults to a no-op so tests asserting
+     * exponential backoff with e.g. `shisho.sleep(1000 * Math.pow(2, attempt))`
+     * don't actually block for the cumulative wall-clock time. Wrap with your
+     * test framework's spy helper (e.g. `vi.fn()`) if you want to assert the
+     * arguments each retry passed.
+     *
+     * The override is still subject to the same validation rules as production
+     * (no NaN/Infinity/negative).
+     */
+    sleep?: (ms: number) => void;
 }
 /**
  * Create a mock `shisho` host API object for testing plugins.

package/testing/index.js

@@ -361,7 +361,6 @@ export function createMockShisho(options = {}) {
                 const encoder = new TextEncoder();
                 return encoder.encode(entry).buffer;
             }
-            // Buffer
             return entry.buffer.slice(entry.byteOffset, entry.byteOffset + entry.byteLength);
         },
         readTextFile(path) {
@@ -379,7 +378,6 @@ export function createMockShisho(options = {}) {
             if (typeof entry === "string") {
                 return entry;
             }
-            // Buffer -> string
             const decoder = new TextDecoder();
             return decoder.decode(entry);
         },
@@ -418,8 +416,24 @@ export function createMockShisho(options = {}) {
         throw new Error(`Mock ${api}: not implemented. Use MockShishoOptions to configure the APIs you need, ` +
             `or provide your own mock for ${api}.`);
     };
+    // --- sleep: validate like production, then delegate ---
+    // Defaults to a no-op because plugin tests asserting exponential backoff
+    // (`shisho.sleep(1000 * Math.pow(2, attempt))`) would otherwise add several
+    // seconds of wall-clock per retry path. Authors who want a real wait or
+    // call tracking can pass `options.sleep` (e.g. a `vi.fn()` spy).
+    const sleepImpl = options.sleep ?? (() => { });
+    const sleep = (ms) => {
+        if (typeof ms !== "number" ||
+            Number.isNaN(ms) ||
+            !Number.isFinite(ms) ||
+            ms < 0) {
+            throw new Error("shisho.sleep: ms must be a finite non-negative number");
+        }
+        sleepImpl(ms);
+    };
     return {
         dataDir: "/tmp/shisho-mock-data",
+        sleep,
         log,
         config,
         http,

package/testing/index.ts

@@ -34,10 +34,21 @@ export interface MockShishoOptions {
   /**
    * Path-based filesystem mock.
    * - string values are returned by readTextFile/readFile
-   * - Buffer values are returned by readFile (as ArrayBuffer)
+   * - Uint8Array (or Buffer) values are returned by readFile (as ArrayBuffer)
    * - string[] values are returned by listDir
    */
-  fs?: Record<string, string | Buffer | string[]>;
+  fs?: Record<string, string | Uint8Array | string[]>;
+  /**
+   * Override the `sleep` implementation. Defaults to a no-op so tests asserting
+   * exponential backoff with e.g. `shisho.sleep(1000 * Math.pow(2, attempt))`
+   * don't actually block for the cumulative wall-clock time. Wrap with your
+   * test framework's spy helper (e.g. `vi.fn()`) if you want to assert the
+   * arguments each retry passed.
+   *
+   * The override is still subject to the same validation rules as production
+   * (no NaN/Infinity/negative).
+   */
+  sleep?: (ms: number) => void;
 }
 
 function statusText(status: number): string {
@@ -481,7 +492,6 @@ export function createMockShisho(
         const encoder = new TextEncoder();
         return encoder.encode(entry).buffer as ArrayBuffer;
       }
-      // Buffer
       return entry.buffer.slice(
         entry.byteOffset,
         entry.byteOffset + entry.byteLength,
@@ -508,7 +518,6 @@ export function createMockShisho(
       if (typeof entry === "string") {
         return entry;
       }
-      // Buffer -> string
       const decoder = new TextDecoder();
       return decoder.decode(entry);
     },
@@ -562,8 +571,27 @@ export function createMockShisho(
     );
   };
 
+  // --- sleep: validate like production, then delegate ---
+  // Defaults to a no-op because plugin tests asserting exponential backoff
+  // (`shisho.sleep(1000 * Math.pow(2, attempt))`) would otherwise add several
+  // seconds of wall-clock per retry path. Authors who want a real wait or
+  // call tracking can pass `options.sleep` (e.g. a `vi.fn()` spy).
+  const sleepImpl = options.sleep ?? (() => {});
+  const sleep: ShishoHostAPI["sleep"] = (ms: number): void => {
+    if (
+      typeof ms !== "number" ||
+      Number.isNaN(ms) ||
+      !Number.isFinite(ms) ||
+      ms < 0
+    ) {
+      throw new Error("shisho.sleep: ms must be a finite non-negative number");
+    }
+    sleepImpl(ms);
+  };
+
   return {
     dataDir: "/tmp/shisho-mock-data",
+    sleep,
     log,
     config,
     http,