@deadair/plugin-sdk 0.2.0

package/dist/testing/index.js

@@ -0,0 +1,141 @@
+import {
+  __name
+} from "../chunk-7QVYU63E.js";
+
+// src/testing/fake.plugin.host.ts
+import { vi } from "vitest";
+var DEFAULT_REMAINING_MS = 15e3;
+var NULL_BODY_STATUSES = /* @__PURE__ */ new Set([
+  101,
+  204,
+  205,
+  304
+]);
+function fakeHostFetchResponse(init = {}) {
+  const status = init.status ?? 200;
+  const response = new Response(NULL_BODY_STATUSES.has(status) ? null : init.body ?? "", {
+    status,
+    statusText: init.statusText ?? "OK",
+    headers: init.headers ?? {
+      "content-type": "application/json"
+    }
+  });
+  Object.defineProperty(response, "url", {
+    value: init.url ?? "https://example.test/"
+  });
+  return response;
+}
+__name(fakeHostFetchResponse, "fakeHostFetchResponse");
+function createFakePluginHost() {
+  const calls = [];
+  const queue = [];
+  let customImpl;
+  const storageData = /* @__PURE__ */ new Map();
+  let configData = {};
+  const secretsData = /* @__PURE__ */ new Map();
+  let tokens;
+  let remainingMs = DEFAULT_REMAINING_MS;
+  let fetchedTrack = {
+    url: "http://127.0.0.1:3679/track/song-1?t=signed",
+    expiresAt: 1893456e6
+  };
+  const fetchImpl = vi.fn(async (url, init) => {
+    calls.push({
+      url,
+      method: init?.method,
+      headers: init?.headers,
+      body: init?.body
+    });
+    if (customImpl) return customImpl(url, init);
+    const next = queue.shift();
+    if (!next) throw new Error(`fake plugin host: no response queued for ${init?.method ?? "GET"} ${url}`);
+    return next;
+  });
+  const host = {
+    logger: {
+      debug: vi.fn(),
+      info: vi.fn(),
+      warn: vi.fn(),
+      error: vi.fn()
+    },
+    fetch: fetchImpl,
+    // Never aborts: these tests are about what a plugin does with a reply,
+    // not about being cancelled half way through one.
+    signal: new AbortController().signal,
+    remainingMs: vi.fn(() => remainingMs),
+    storage: {
+      get: vi.fn(async (key) => storageData.get(key)),
+      set: vi.fn(async (key, value) => {
+        storageData.set(key, value);
+      }),
+      delete: vi.fn(async (key) => {
+        storageData.delete(key);
+      }),
+      list: vi.fn(async (prefix) => [
+        ...storageData.keys()
+      ].filter((key) => !prefix || key.startsWith(prefix)))
+    },
+    secrets: {
+      get: vi.fn(async (key) => secretsData.get(key))
+    },
+    config: {
+      get: vi.fn(async () => configData)
+    },
+    oauth: {
+      getRedirectUri: vi.fn(async () => "https://example.test/callback"),
+      saveTokens: vi.fn(async (next) => {
+        tokens = next;
+      }),
+      getTokens: vi.fn(async () => tokens)
+    },
+    events: {
+      emit: vi.fn()
+    },
+    trackFetcher: {
+      serve: vi.fn(async () => fetchedTrack)
+    },
+    calls,
+    seedRemainingMs(ms) {
+      remainingMs = ms;
+    },
+    queueResponse(response) {
+      queue.push(fakeHostFetchResponse(response));
+    },
+    setFetchImpl(impl) {
+      customImpl = impl;
+    },
+    seedConfig(config) {
+      configData = config;
+    },
+    seedSecret(key, value) {
+      secretsData.set(key, value);
+    },
+    seedStorage(key, value) {
+      storageData.set(key, value);
+    },
+    getStorageEntry(key) {
+      return storageData.get(key);
+    },
+    storageKeys() {
+      return [
+        ...storageData.keys()
+      ];
+    },
+    seedTokens(next) {
+      tokens = next;
+    },
+    getVaultTokens() {
+      return tokens;
+    },
+    seedFetchedTrack(stream) {
+      fetchedTrack = stream;
+    }
+  };
+  return host;
+}
+__name(createFakePluginHost, "createFakePluginHost");
+export {
+  createFakePluginHost,
+  fakeHostFetchResponse
+};
+//# sourceMappingURL=index.js.map

package/dist/testing/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/testing/fake.plugin.host.ts"],"sourcesContent":["import { vi } from 'vitest';\n\nimport type { HostFetchInit, HostFetchMethod, PluginHost, ProviderStream } from '../index.js';\n\n/**\n * Shipped from the SDK rather than copied into each plugin, which three of them\n * were doing — two of those carrying a comment saying the copy was deliberate\n * because plugins do not depend on each other.\n *\n * That reasoning held for the copies and does not hold for this: every plugin\n * already depends on the SDK, and `PluginHost` is the SDK's own contract, so its\n * test double belongs beside the interface it doubles. A plugin importing this\n * gains no dependency on any other plugin. It also means a host method added to\n * the contract turns up in one fake rather than being added to three and\n * forgotten in the other three.\n *\n * Reached as `@deadair/plugin-sdk/testing`, which is kept out of the runtime\n * entry so nothing ships a dependency on vitest.\n */\n\n/** One `host.fetch` call, recorded with only the fields tests care about. */\nexport interface RecordedFetchCall {\n    url: string;\n    method: HostFetchMethod | undefined;\n    headers: Record<string, string> | undefined;\n    body: string | undefined;\n}\n\n/**\n * A `PluginHost` for tests. `fetch` replays a queue of scripted\n * `Response`s (FIFO, one per call) — or a custom handler installed\n * with `setFetchImpl`, for call-count-driven scenarios like a 401-then-200\n * retry — and records every call it received in `calls`. `storage`, `config`,\n * `secrets` and the `oauth` vault are in-memory and can be seeded or read\n * directly, bypassing the `PluginHost` methods, so a test can assert on state\n * without going through the code under test twice.\n */\nexport interface FakePluginHost extends PluginHost {\n    /** Every `host.fetch` call so far, in call order. */\n    readonly calls: RecordedFetchCall[];\n    /** Set what `host.remainingMs()` reports, for testing budget shedding. */\n    seedRemainingMs(ms: number): void;\n    /** Push one scripted response onto the back of the reply queue. */\n    queueResponse(response: FakeResponseInit): void;\n    /** Replace the fetch handler outright; overrides the queue while set. */\n    setFetchImpl(impl: (url: string, init?: HostFetchInit) => Promise<Response>): void;\n    /** Seed the value `host.config.get()` resolves to. */\n    seedConfig(config: Record<string, unknown>): void;\n    /** Seed a value `host.secrets.get(key)` resolves to. */\n    seedSecret(key: string, value: string): void;\n    /** Seed a storage entry directly, bypassing `host.storage.set`. */\n    seedStorage(key: string, value: unknown): void;\n    /** Read a storage entry directly, bypassing `host.storage.get`. */\n    getStorageEntry(key: string): unknown;\n    /** All storage keys currently set, unfiltered. */\n    storageKeys(): string[];\n    /** Seed the oauth vault directly, bypassing `host.oauth.saveTokens`. */\n    seedTokens(tokens: Record<string, string>): void;\n    /** Read the oauth vault directly, bypassing `host.oauth.getTokens`. */\n    getVaultTokens(): Record<string, string> | undefined;\n    /** Set what `host.trackFetcher.serve()` answers with; `undefined` means \"this station has no fetcher\". */\n    seedFetchedTrack(stream: ProviderStream | undefined): void;\n}\n\n/**\n * What `host.remainingMs()` reports unless a test says otherwise. Matches the\n * host's default per-call deadline, so a plugin that only sheds work when the\n * budget is tight behaves in tests the way it does on a healthy station.\n */\nconst DEFAULT_REMAINING_MS = 15_000;\n\n/**\n * What a test says a scripted reply should be.\n *\n * Not `ResponseInit`, because `url` is not on it: `host.fetch` reports the last\n * hop of the redirect chain there, and a `Response` built by hand has an empty\n * one unless it is defined in.\n */\nexport interface FakeResponseInit {\n    status?: number;\n    statusText?: string;\n    headers?: Record<string, string>;\n    /**\n     * Text for a JSON or error reply, bytes for a binary one.\n     *\n     * `Uint8Array<ArrayBuffer>` rather than a bare `Uint8Array`: the DOM lib's\n     * `BodyInit` accepts a view over a real `ArrayBuffer`, and the unparameterized\n     * form widens to `ArrayBufferLike`, which includes `SharedArrayBuffer` and is\n     * not something `Response` will take. `new Uint8Array([...])` already has the\n     * narrow type, so no test has to say so.\n     */\n    body?: string | Uint8Array<ArrayBuffer>;\n    url?: string;\n}\n\n/** Statuses whose `Response` must carry a null body, or the constructor throws. */\nconst NULL_BODY_STATUSES = new Set([101, 204, 205, 304]);\n\n/** Builds a default 200 `Response`, overridable field by field. */\nexport function fakeHostFetchResponse(init: FakeResponseInit = {}): Response {\n    const status = init.status ?? 200;\n\n    const response = new Response(NULL_BODY_STATUSES.has(status) ? null : (init.body ?? ''), {\n        status,\n        statusText: init.statusText ?? 'OK',\n        headers: init.headers ?? { 'content-type': 'application/json' },\n    });\n\n    // Read-only on a constructed response, and part of what the host promises.\n    Object.defineProperty(response, 'url', { value: init.url ?? 'https://example.test/' });\n\n    return response;\n}\n\nexport function createFakePluginHost(): FakePluginHost {\n    const calls: RecordedFetchCall[] = [];\n    const queue: Response[] = [];\n    let customImpl: ((url: string, init?: HostFetchInit) => Promise<Response>) | undefined;\n\n    const storageData = new Map<string, unknown>();\n    let configData: Record<string, unknown> = {};\n    const secretsData = new Map<string, string>();\n    let tokens: Record<string, string> | undefined;\n    let remainingMs = DEFAULT_REMAINING_MS;\n    let fetchedTrack: ProviderStream | undefined = { url: 'http://127.0.0.1:3679/track/song-1?t=signed', expiresAt: 1_893_456_000_000 };\n\n    const fetchImpl = vi.fn(async (url: string, init?: HostFetchInit): Promise<Response> => {\n        calls.push({ url, method: init?.method, headers: init?.headers, body: init?.body });\n        if (customImpl) return customImpl(url, init);\n        const next = queue.shift();\n        if (!next) throw new Error(`fake plugin host: no response queued for ${init?.method ?? 'GET'} ${url}`);\n        return next;\n    });\n\n    const host: FakePluginHost = {\n        logger: { debug: vi.fn(), info: vi.fn(), warn: vi.fn(), error: vi.fn() },\n        fetch: fetchImpl,\n        // Never aborts: these tests are about what a plugin does with a reply,\n        // not about being cancelled half way through one.\n        signal: new AbortController().signal,\n        remainingMs: vi.fn(() => remainingMs),\n        storage: {\n            get: vi.fn(async (key: string) => storageData.get(key)),\n            set: vi.fn(async (key: string, value: unknown) => {\n                storageData.set(key, value);\n            }),\n            delete: vi.fn(async (key: string) => {\n                storageData.delete(key);\n            }),\n            list: vi.fn(async (prefix?: string) => [...storageData.keys()].filter(key => !prefix || key.startsWith(prefix))),\n        },\n        secrets: { get: vi.fn(async (key: string) => secretsData.get(key)) },\n        config: { get: vi.fn(async () => configData) },\n        oauth: {\n            getRedirectUri: vi.fn(async () => 'https://example.test/callback'),\n            saveTokens: vi.fn(async (next: Record<string, string>) => {\n                tokens = next;\n            }),\n            getTokens: vi.fn(async () => tokens),\n        },\n        events: { emit: vi.fn() },\n        trackFetcher: { serve: vi.fn(async () => fetchedTrack) },\n        calls,\n        seedRemainingMs(ms) {\n            remainingMs = ms;\n        },\n        queueResponse(response: FakeResponseInit) {\n            queue.push(fakeHostFetchResponse(response));\n        },\n        setFetchImpl(impl) {\n            customImpl = impl;\n        },\n        seedConfig(config) {\n            configData = config;\n        },\n        seedSecret(key, value) {\n            secretsData.set(key, value);\n        },\n        seedStorage(key, value) {\n            storageData.set(key, value);\n        },\n        getStorageEntry(key) {\n            return storageData.get(key);\n        },\n        storageKeys() {\n            return [...storageData.keys()];\n        },\n        seedTokens(next) {\n            tokens = next;\n        },\n        getVaultTokens() {\n            return tokens;\n        },\n        seedFetchedTrack(stream) {\n            fetchedTrack = stream;\n        },\n    };\n\n    return host;\n}\n"],"mappings":"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","names":["vi","DEFAULT_REMAINING_MS","NULL_BODY_STATUSES","Set","fakeHostFetchResponse","init","status","response","Response","has","body","statusText","headers","Object","defineProperty","value","url","createFakePluginHost","calls","queue","customImpl","storageData","Map","configData","secretsData","tokens","remainingMs","fetchedTrack","expiresAt","fetchImpl","vi","fn","push","method","next","shift","Error","host","logger","debug","info","warn","error","fetch","signal","AbortController","storage","get","key","set","delete","list","prefix","keys","filter","startsWith","secrets","config","oauth","getRedirectUri","saveTokens","getTokens","events","emit","trackFetcher","serve","seedRemainingMs","ms","queueResponse","setFetchImpl","impl","seedConfig","seedSecret","seedStorage","getStorageEntry","storageKeys","seedTokens","getVaultTokens","seedFetchedTrack","stream"]}

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "@deadair/plugin-sdk",
+  "version": "0.2.0",
+  "description": "The contract a deadair plugin is written against: the manifest, the capabilities, the host it is handed, and a fake host for its tests.",
+  "keywords": [
+    "deadair",
+    "plugin",
+    "radio",
+    "sdk"
+  ],
+  "homepage": "https://deadair.radio/docs/plugin-development",
+  "bugs": {
+    "url": "https://github.com/robert-dean/deadair/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/robert-dean/deadair.git",
+    "directory": "packages/plugin-sdk"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./testing": {
+      "types": "./dist/testing/index.d.ts",
+      "default": "./dist/testing/index.js"
+    }
+  },
+  "license": "MIT",
+  "files": [
+    "dist/**",
+    "LICENSE"
+  ],
+  "peerDependencies": {
+    "vitest": "^4.0.0",
+    "zod": "^4.0.0"
+  },
+  "peerDependenciesMeta": {
+    "vitest": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "vitest": "^4.1.11",
+    "zod": "^4.5.4",
+    "@repo/config-eslint": "0.0.0",
+    "@repo/config-typescript": "0.0.0"
+  },
+  "dependencies": {
+    "fast-xml-parser": "^5.10.1"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts src/testing/index.ts --format esm --sourcemap && tsc --emitDeclarationOnly --declaration",
+    "build:ci": "eslint --max-warnings=0 && pnpm run build",
+    "lint": "eslint --fix",
+    "format": "prettier --write . --ignore-path ../../.prettierignore",
+    "test": "vitest run"
+  }
+}