@deadair/plugin-sdk 0.2.0

package/dist/plugin.lifecycle.d.ts

@@ -0,0 +1,68 @@
+import type { ConfigFieldOption } from './plugin.config.fields.js';
+import type { PluginHost } from './plugin.host.js';
+/** Result of a "does this configuration actually work?" probe. */
+export interface PluginConnectionResult {
+    ok: boolean;
+    /** Short operator-facing explanation, shown in the settings UI either way. */
+    message?: string;
+}
+/**
+ * The part of a plugin every plugin implements, whatever its kind.
+ *
+ * The host calls `init` exactly once per instance, before any capability
+ * method. `dispose` is called on unload, config change, or shutdown.
+ */
+export interface PluginLifecycle {
+    init(host: PluginHost): Promise<void>;
+    /**
+     * Called from the settings UI's "Test connection" button.
+     *
+     * It is also how a quarantined plugin gets back on the station. The host
+     * runs it even while your plugin's breaker is open, and `ok: true` closes
+     * the breaker, so reach the provider with the saved credentials rather than
+     * checking that a setting is present. Report a failure as `ok: false` with a
+     * message: what the host counts as healthy is `ok`, not the call resolving.
+     *
+     * The host also calls it on its own while your plugin is quarantined by a
+     * failure retrying could end: after a minute, then on a backoff to one call
+     * every half hour. So keep it to one cheap request, and never to anything
+     * that changes state on the provider.
+     */
+    testConnection?(): Promise<PluginConnectionResult>;
+    /**
+     * Live choices for your config fields, keyed by field key.
+     *
+     * The settings form asks once when it opens, and again when the operator hits
+     * refresh. A field that comes back with options is rendered as a picker: a
+     * `string` or `url` becomes free text WITH suggestions, so a value you could
+     * not enumerate is still typeable, and a `select` or `multiselect` has its
+     * declared options replaced by these.
+     *
+     * ## Why this exists
+     *
+     * `ConfigField.options` is fixed when the manifest is written, which is fine
+     * for a closed set and useless for anything the operator's own server decides.
+     * Without it the only way to learn what a server offers is to read it out of a
+     * "Test connection" message and type it back in, which is a setup loop with no
+     * way in: the address cannot be tested before it is saved, so a field that
+     * requires one of those values cannot be filled before the address is.
+     *
+     * ## Notes
+     *
+     * Implementing this IS the opt-in; there is nothing to declare on the field.
+     * Return a map rather than answering per field so the form costs one call
+     * however many fields you have, and omit a key you have nothing to say about
+     * rather than returning an empty array for it.
+     *
+     * It runs against your SAVED config, like `testConnection` does, because that
+     * is the config your instance was loaded with. So the shape of a first-time
+     * setup is: save what you can, refresh, choose from what comes back.
+     *
+     * Answer with what you have rather than throwing when an upstream is
+     * unreachable: a field with no suggestions is still a field somebody can type
+     * into, and a throw costs them the whole form.
+     */
+    suggestConfigOptions?(): Promise<Record<string, ConfigFieldOption[]>>;
+    dispose?(): Promise<void>;
+}
+//# sourceMappingURL=plugin.lifecycle.d.ts.map

package/dist/plugin.lifecycle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.lifecycle.d.ts","sourceRoot":"","sources":["../src/plugin.lifecycle.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AACnE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAEnD,kEAAkE;AAClE,MAAM,WAAW,sBAAsB;IACnC,EAAE,EAAE,OAAO,CAAC;IACZ,8EAA8E;IAC9E,OAAO,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC5B,IAAI,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEtC;;;;;;;;;;;;;OAaG;IACH,cAAc,CAAC,IAAI,OAAO,CAAC,sBAAsB,CAAC,CAAC;IAEnD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAgCG;IACH,oBAAoB,CAAC,IAAI,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,iBAAiB,EAAE,CAAC,CAAC,CAAC;IAEtE,OAAO,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC7B"}

package/dist/plugin.manifest.d.ts

@@ -0,0 +1,282 @@
+import { z } from 'zod';
+import { type ConfigField } from './plugin.config.fields.js';
+import { type PluginPermissions } from './plugin.permissions.js';
+/**
+ * What a plugin can do, and the only thing the host ever dispatches on.
+ *
+ * There is no second axis. A manifest used to also carry a `kind`
+ * (`music-provider`, `enrichment`, `tts`) which nothing checked: every call
+ * site asked the capability list, because a plugin that declares a kind and
+ * forgets the method is a `TypeError` mid-request. So the label went and this
+ * is what is left.
+ */
+export declare const PLUGIN_CAPABILITY_CATALOG = "catalog";
+/**
+ * The plugin can get the station audio to play (`resolveStreamUrl`). Separate
+ * from {@link PLUGIN_CAPABILITY_CATALOG} so a manifest can say it: "will fetch
+ * audio from your server" is a thing an operator should read before installing,
+ * and it used to be invisible.
+ */
+export declare const PLUGIN_CAPABILITY_STREAM = "stream";
+/**
+ * The plugin owns its own audio output and deadair only tells it what to do.
+ * The opposite of deadair's `playout` module, which is why it is not called
+ * that.
+ */
+export declare const PLUGIN_CAPABILITY_STEER = "steer";
+export declare const PLUGIN_CAPABILITY_OAUTH = "oauth";
+export declare const PLUGIN_CAPABILITY_ENRICHMENT = "enrichment";
+/** The plugin can say something out loud: text in, audio out. */
+export declare const PLUGIN_CAPABILITY_SPEECH = "speech";
+/**
+ * The plugin can produce words: a conversation in, text out.
+ *
+ * A transport rather than a writer. What to say is the station's business, which
+ * is why this capability knows nothing about breaks, shows or running orders.
+ */
+export declare const PLUGIN_CAPABILITY_LLM = "llm";
+/**
+ * The plugin can measure a track's audio: bytes in, offsets out.
+ *
+ * Separate from {@link PLUGIN_CAPABILITY_ENRICHMENT} because the two answer
+ * different kinds of question. Enrichment asks an upstream what it knows and
+ * merges several answers; this computes one answer from the samples, and no
+ * upstream sells it.
+ */
+export declare const PLUGIN_CAPABILITY_ANALYSIS = "analysis";
+/**
+ * The plugin can make one piece of audio out of several: parts in, audio out.
+ *
+ * Separate from {@link PLUGIN_CAPABILITY_ANALYSIS}, and NOT because the work is
+ * different: both need decoded PCM, and the bundled adapter serves both off one
+ * sidecar. It is separate because **a capability is the unit of SELECTION**. The
+ * host picks one plugin per capability, so a joiner carried as an optional method
+ * on the analyzer is the analyzer the operator chose to MEASURE with — install
+ * one that measures better and cannot join, name it, and joining stops with
+ * nothing to do about it but choose a worse analyzer. Two keys is what lets a
+ * station measure with one engine and mix with another.
+ *
+ * One plugin may of course declare both, and the bundled one does.
+ */
+export declare const PLUGIN_CAPABILITY_MIXER = "mixer";
+/**
+ * The plugin can say what is popular: a chart id in, an ordered list of names
+ * out.
+ *
+ * Separate from {@link PLUGIN_CAPABILITY_ENRICHMENT} because it is not a fact
+ * about a record the station holds — it is an opinion about records in general,
+ * most of which the library has never seen. And separate from
+ * {@link PLUGIN_CAPABILITY_CATALOG} because a chart is not a source of audio:
+ * naming a record is the whole of what it does.
+ */
+export declare const PLUGIN_CAPABILITY_CHARTS = "charts";
+/**
+ * The plugin can say what happened outside the station: a feed in, published
+ * entries out.
+ *
+ * Separate from {@link PLUGIN_CAPABILITY_CHARTS} even though both read somebody
+ * else's document, because what comes back is not about records at all. A chart
+ * entry is a name the pick path can turn into something that airs; a news item
+ * is a fact, and the only thing that can be done with it is say it.
+ */
+export declare const PLUGIN_CAPABILITY_NEWS = "news";
+/**
+ * The plugin can say who else sounds like this: an artist in, artists out.
+ *
+ * Separate from {@link PLUGIN_CAPABILITY_ENRICHMENT} for the reason
+ * `capabilities/similarity.ts` gives at length: enrichment describes rows the
+ * catalog holds, and the artists worth asking about here are the ones it does
+ * not.
+ */
+export declare const PLUGIN_CAPABILITY_SIMILARITY = "similarity";
+/**
+ * The plugin can ask the open web a question: words in, pages out.
+ *
+ * Separate from {@link PLUGIN_CAPABILITY_NEWS}, which is the other capability
+ * that answers about the world, because the two are asked different things. News
+ * serves a MENU an operator assembled and answers "what happened"; this is given
+ * a subject the caller chose and answers "what does the web say about it", with
+ * nothing stable to de-duplicate against because no two calls ask the same
+ * question.
+ *
+ * And separate from {@link PLUGIN_CAPABILITY_CATALOG} for the reason
+ * {@link PLUGIN_CAPABILITY_CHARTS} is: a result is a page, and a page cannot be
+ * played. Looking for something to PLAY is `searchTracks` on the catalog.
+ */
+export declare const PLUGIN_CAPABILITY_SEARCH = "search";
+/**
+ * The plugin can say what it is like outside: a place in, measurements out.
+ *
+ * The third capability that answers about the world, and separate from both of
+ * the others because it is asked a different question. News serves a menu
+ * somebody assembled and answers "what happened"; search takes words a caller
+ * made up and answers "what does the web say". This is asked about one PLACE,
+ * and what comes back is numbers rather than sentences — the station does
+ * arithmetic on them and then decides what to say, where a headline is already
+ * the words.
+ *
+ * A capability rather than a general-purpose tool the model calls, which was the
+ * older plan: a plugin answering a question the STATION has is a capability, and
+ * this station wants a reading for the moment it is playing into as well as for
+ * the presenter to mention. See [tool-plugins](https://github.com/robert-dean/deadair/discussions/44).
+ */
+export declare const PLUGIN_CAPABILITY_WEATHER = "weather";
+/**
+ * The plugin can report what the station played to somebody else's service.
+ *
+ * The only capability that SENDS. Everything else here reads an upstream; this
+ * publishes the operator's own listening to an account they hold, which is why
+ * the SDK gives it a way to be declined per installation rather than assuming
+ * that installing a plugin is consent to broadcast from it.
+ */
+export declare const PLUGIN_CAPABILITY_SCROBBLE = "scrobble";
+export declare const KNOWN_PLUGIN_CAPABILITIES: readonly ["catalog", "stream", "steer", "oauth", "enrichment", "speech", "llm", "analysis", "mixer", "charts", "news", "similarity", "search", "weather", "scrobble"];
+export type KnownPluginCapability = (typeof KNOWN_PLUGIN_CAPABILITIES)[number];
+/**
+ * Known capabilities get autocomplete; the type stays open so a plugin built
+ * against a newer host can declare one this SDK has never heard of without
+ * failing manifest validation.
+ */
+export type PluginCapability = KnownPluginCapability | (string & Record<never, never>);
+/**
+ * A zod schema instance. Typed loosely so a plugin can hand over any schema
+ * shape (object, union, refined object) without fighting the compiler.
+ */
+export type PluginConfigSchema = z.ZodType;
+/**
+ * Duck-typed "is this a zod schema?". Deliberately not a bare `instanceof`:
+ * a plugin may resolve its own copy of zod, and `instanceof` fails across
+ * module instances.
+ */
+export declare function isZodSchema(value: unknown): value is PluginConfigSchema;
+/**
+ * Everything the host needs to know about a plugin before it runs any of the
+ * plugin's code: who it is, what it can do, what it needs permission for, and
+ * what to ask the operator for.
+ */
+export interface PluginManifest {
+    /** Reverse-DNS identifier, e.g. `deadair.spotify`. Globally unique, stable across versions. */
+    id: string;
+    /** Display name, e.g. `Spotify`. */
+    name: string;
+    /** Semver version of the plugin itself. */
+    version: string;
+    /** Which capability interfaces the factory result actually implements. */
+    capabilities: PluginCapability[];
+    /**
+     * Semver RANGE of the plugin API this plugin works against, e.g. `^1.0.0`.
+     * Compared against {@link PLUGIN_API_VERSION} at load time.
+     */
+    apiVersion: string;
+    description?: string;
+    homepage?: string;
+    /** Data URI or absolute https URL of a small square icon. */
+    icon?: string;
+    permissions: PluginPermissions;
+    /** Declarative settings form. */
+    configFields: ConfigField[];
+    /**
+     * Server-side validation of the submitted config. The host parses the
+     * operator's submission with this before storing it, so a plugin never
+     * has to defend against malformed config at runtime.
+     */
+    configSchema: PluginConfigSchema;
+}
+/**
+ * Validates everything in a manifest except the contents of `configSchema`,
+ * which is only checked to be a zod schema instance.
+ */
+export declare const pluginManifestSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    version: z.ZodString;
+    capabilities: z.ZodArray<z.ZodString>;
+    apiVersion: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    homepage: z.ZodOptional<z.ZodString>;
+    icon: z.ZodOptional<z.ZodString>;
+    permissions: z.ZodObject<{
+        network: z.ZodArray<z.ZodType<import("./plugin.permissions.js").NetworkPermission, unknown, z.core.$ZodTypeInternals<import("./plugin.permissions.js").NetworkPermission, unknown>>>;
+        storage: z.ZodBoolean;
+        oauth: z.ZodBoolean;
+        trackFetcher: z.ZodOptional<z.ZodBoolean>;
+        grants: z.ZodOptional<z.ZodArray<z.ZodType<import("./plugin.permissions.js").PluginGrantRequest, unknown, z.core.$ZodTypeInternals<import("./plugin.permissions.js").PluginGrantRequest, unknown>>>>;
+    }, z.core.$strip>;
+    configFields: z.ZodArray<z.ZodObject<{
+        key: z.ZodString;
+        label: z.ZodString;
+        type: z.ZodEnum<{
+            string: "string";
+            number: "number";
+            boolean: "boolean";
+            text: "text";
+            url: "url";
+            secret: "secret";
+            select: "select";
+            multiselect: "multiselect";
+            list: "list";
+            note: "note";
+        }>;
+        required: z.ZodOptional<z.ZodBoolean>;
+        default: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>;
+        unit: z.ZodOptional<z.ZodEnum<{
+            bytes: "bytes";
+            fraction: "fraction";
+        }>>;
+        control: z.ZodOptional<z.ZodEnum<{
+            slider: "slider";
+            tags: "tags";
+        }>>;
+        step: z.ZodOptional<z.ZodNumber>;
+        min: z.ZodOptional<z.ZodNumber>;
+        max: z.ZodOptional<z.ZodNumber>;
+        placeholder: z.ZodOptional<z.ZodString>;
+        help: z.ZodOptional<z.ZodString>;
+        options: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            value: z.ZodString;
+            label: z.ZodString;
+        }, z.core.$strip>>>;
+        optionsFrom: z.ZodOptional<z.ZodEnum<{
+            "station.newsCategories": "station.newsCategories";
+            "station.newsFeeds": "station.newsFeeds";
+            "intl.timeZones": "intl.timeZones";
+            "plugins.speech": "plugins.speech";
+            "plugins.llm": "plugins.llm";
+            "plugins.mixer": "plugins.mixer";
+            "plugins.analysis": "plugins.analysis";
+            "llm.models": "llm.models";
+        }>>;
+        columns: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            key: z.ZodString;
+            label: z.ZodString;
+            type: z.ZodEnum<{
+                string: "string";
+                url: "url";
+                secret: "secret";
+                select: "select";
+            }>;
+            required: z.ZodOptional<z.ZodBoolean>;
+            placeholder: z.ZodOptional<z.ZodString>;
+            options: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                value: z.ZodString;
+                label: z.ZodString;
+            }, z.core.$strip>>>;
+            optionsFrom: z.ZodOptional<z.ZodEnum<{
+                "station.newsCategories": "station.newsCategories";
+                "station.newsFeeds": "station.newsFeeds";
+                "intl.timeZones": "intl.timeZones";
+                "plugins.speech": "plugins.speech";
+                "plugins.llm": "plugins.llm";
+                "plugins.mixer": "plugins.mixer";
+                "plugins.analysis": "plugins.analysis";
+                "llm.models": "llm.models";
+            }>>;
+            dependsOn: z.ZodOptional<z.ZodString>;
+            dependsOnValues: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        }, z.core.$strip>>>;
+        dependsOn: z.ZodOptional<z.ZodString>;
+        rangeWith: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    configSchema: z.ZodCustom<PluginConfigSchema, PluginConfigSchema>;
+}, z.core.$strip>;
+//# sourceMappingURL=plugin.manifest.d.ts.map

package/dist/plugin.manifest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.manifest.d.ts","sourceRoot":"","sources":["../src/plugin.manifest.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAqB,KAAK,WAAW,EAAE,MAAM,2BAA2B,CAAC;AAChF,OAAO,EAA2B,KAAK,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAE1F;;;;;;;;GAQG;AACH,eAAO,MAAM,yBAAyB,YAAY,CAAC;AAEnD;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB,WAAW,CAAC;AAEjD;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,UAAU,CAAC;AAC/C,eAAO,MAAM,uBAAuB,UAAU,CAAC;AAC/C,eAAO,MAAM,4BAA4B,eAAe,CAAC;AAEzD,iEAAiE;AACjE,eAAO,MAAM,wBAAwB,WAAW,CAAC;AAEjD;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,QAAQ,CAAC;AAE3C;;;;;;;GAOG;AACH,eAAO,MAAM,0BAA0B,aAAa,CAAC;AAErD;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,uBAAuB,UAAU,CAAC;AAE/C;;;;;;;;;GASG;AACH,eAAO,MAAM,wBAAwB,WAAW,CAAC;AAEjD;;;;;;;;GAQG;AACH,eAAO,MAAM,sBAAsB,SAAS,CAAC;AAE7C;;;;;;;GAOG;AACH,eAAO,MAAM,4BAA4B,eAAe,CAAC;AAEzD;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,wBAAwB,WAAW,CAAC;AAEjD;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,yBAAyB,YAAY,CAAC;AAEnD;;;;;;;GAOG;AACH,eAAO,MAAM,0BAA0B,aAAa,CAAC;AAErD,eAAO,MAAM,yBAAyB,uKAgB5B,CAAC;AAEX,MAAM,MAAM,qBAAqB,GAAG,CAAC,OAAO,yBAAyB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE/E;;;;GAIG;AACH,MAAM,MAAM,gBAAgB,GAAG,qBAAqB,GAAG,CAAC,MAAM,GAAG,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC;AAEvF;;;GAGG;AACH,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,OAAO,CAAC;AAE3C;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,kBAAkB,CAKvE;AAED;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC3B,+FAA+F;IAC/F,EAAE,EAAE,MAAM,CAAC;IAEX,oCAAoC;IACpC,IAAI,EAAE,MAAM,CAAC;IAEb,2CAA2C;IAC3C,OAAO,EAAE,MAAM,CAAC;IAEhB,0EAA0E;IAC1E,YAAY,EAAE,gBAAgB,EAAE,CAAC;IAEjC;;;OAGG;IACH,UAAU,EAAE,MAAM,CAAC;IAEnB,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB,6DAA6D;IAC7D,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd,WAAW,EAAE,iBAAiB,CAAC;IAE/B,iCAAiC;IACjC,YAAY,EAAE,WAAW,EAAE,CAAC;IAE5B;;;;OAIG;IACH,YAAY,EAAE,kBAAkB,CAAC;CACpC;AAKD;;;GAGG;AACH,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAY/B,CAAC"}

package/dist/plugin.permissions.d.ts

@@ -0,0 +1,186 @@
+import { z } from 'zod';
+/** The pacing knobs, shared by both kinds of entry. */
+interface NetworkPermissionPacing {
+    /**
+     * Requests per second the host will let through to this entry, capped by
+     * the host's own ceiling. You can ask to be slower, never faster.
+     *
+     * Omit it and the host's default applies. Set it and `host.fetch` paces you
+     * automatically, parking each call until there is headroom rather than
+     * failing it, so there is nothing left for the plugin to implement. The
+     * wait is spent from the call's budget, so see `host.remainingMs()` for
+     * deciding whether the work still fits.
+     */
+    ratePerSecond?: number;
+    /**
+     * Name of the rate-limit bucket this entry draws from. Entries sharing a
+     * bucket share one limiter; the default is the hostname the entry resolves
+     * to.
+     *
+     * For when a published limit covers a service rather than a hostname.
+     * `musicbrainz.org` and `*.musicbrainz.org` are two entries against one
+     * 1 req/s policy, and without a shared bucket declaring both would quietly
+     * buy 2 req/s and get the station blocked.
+     */
+    bucket?: string;
+}
+/**
+ * One upstream a plugin may reach, named outright.
+ *
+ * The bare string shorthand means exactly this with no pacing set. Reach for
+ * the object form when the upstream publishes a limit of its own: MusicBrainz
+ * allows roughly one request per second to anonymous clients, a tenth of what
+ * the host would otherwise let through.
+ */
+export interface NetworkPermissionHost extends NetworkPermissionPacing {
+    /**
+     * Bare hostname (`api.spotify.com`), no scheme and no path. A leading `*.`
+     * marks a wildcard subdomain match (`*.example.com`) and does NOT match the
+     * bare apex.
+     */
+    host: string;
+}
+/**
+ * One upstream the operator names, not the plugin: the hostname comes from one
+ * of your own config fields, resolved when the plugin is initialized.
+ *
+ * For anything self-hosted or mirrored, where there is no hostname to write
+ * down at authoring time. A MusicBrainz mirror, a Navidrome server, an internal
+ * API: the plugin declares which setting holds the address and the host reads
+ * the hostname out of it.
+ *
+ * The value is read as a URL, or as a bare hostname if it does not look like
+ * one. Empty, unparseable, or wildcard-bearing values simply contribute no
+ * entry, so an unconfigured plugin is refused exactly as if it had asked for
+ * an undeclared host. Because it resolves at init, changing the setting
+ * reinitializes the plugin and the new address takes effect with it.
+ *
+ * ## One setting, several addresses
+ *
+ * A setting holding SEVERAL addresses contributes one entry each. That is for
+ * the plugin whose upstreams are a list the operator pasted rather than one
+ * server they run — a reader of feeds — where there is no honest number of
+ * `url` fields to offer.
+ *
+ * The shape is one address per line (a `text` field), or the JSON array a
+ * `multiselect` stores. Where a line carries more than the address, the address
+ * is its last `|`-separated field, so `world|World news|https://…/feed.xml`
+ * resolves to that host: a list wants labels, and fixing where they go keeps
+ * the hostnames readable out of the operator's own text instead of out of a
+ * plugin's private parser.
+ *
+ * Every rule above is applied per address rather than to the value as a whole,
+ * so one mistyped line costs its own upstream and not the rest, and a wildcard
+ * still cannot arrive from data. Repeats collapse: two feeds at one publisher
+ * are one entry, or the second would install a limiter that doubles the rate
+ * this entry asked to be paced at.
+ */
+export interface NetworkPermissionFromConfig extends NetworkPermissionPacing {
+    /** Key of the config field holding the address, e.g. `baseUrl`. */
+    fromConfig: string;
+}
+/** A hostname at the host's default rate, or an entry that says more. */
+export type NetworkPermission = string | NetworkPermissionHost | NetworkPermissionFromConfig;
+/**
+ * Something a plugin needs that only the OPERATOR can say yes to.
+ *
+ * The rest of {@link PluginPermissions} is disclosure: a manifest states what it
+ * reaches and the host holds it to that, with nobody asked anything. A grant is
+ * the other kind — a capability wide enough that a person should decide, per
+ * install, with the plugin's own reason in front of them.
+ *
+ * ## The manifest is the request, and it is the only record of one
+ *
+ * Nothing is stored when a plugin asks. The host reads this on every discovery
+ * and stores only the ANSWER, keyed by plugin and capability, so a plugin whose
+ * manifest stops asking simply stops appearing and cannot be re-enabled by a row
+ * nobody can see. A plugin that has not been answered is refused: undecided and
+ * denied differ on the operator's page and nowhere else.
+ *
+ * There is no runtime ask. A `host.requestPermission()` would have to block a
+ * plugin mid-work on a person who may be asleep, and a plugin that never runs
+ * would never appear to be asked about.
+ *
+ * ## The vocabulary is the host's
+ *
+ * {@link capability} is one of a fixed list the HOST publishes, because a
+ * capability only means something where the host enforces it. An id nothing
+ * recognises is ignored with a warning rather than becoming a row that gates
+ * nothing — a permission for a door that does not exist is worse than no
+ * permission, since it reads on the page as though it were protecting something.
+ */
+export interface PluginGrantRequest extends NetworkPermissionPacing {
+    /** A capability id the host publishes, e.g. `network.open`. */
+    capability: string;
+    /**
+     * Why this plugin needs it, in one sentence, addressed to the operator.
+     *
+     * Required, and the field this whole shape exists to carry. It is what the
+     * console shows beside the Allow control, and a manifest that cannot say why
+     * it wants something does not get to ask for it: the alternative is an
+     * operator deciding on a capability id alone, which is a decision nobody can
+     * actually make.
+     */
+    reason: string;
+}
+/**
+ * What a plugin is allowed to do. Declared up front in the manifest so the
+ * host (and the operator installing the plugin) can see the full blast radius
+ * before any plugin code runs.
+ */
+export interface PluginPermissions {
+    /**
+     * Hostname allowlist for `host.fetch()`: any request to a host not listed
+     * here is rejected before it leaves the process.
+     *
+     * This describes what a plugin says it needs, and it is enforced on every
+     * call (and every redirect hop) that goes through `host.fetch`. It is not
+     * yet enforced against a plugin that reaches for global `fetch` instead,
+     * because the host still imports plugin code into its own realm. Read this
+     * field as a disclosure an operator can weigh before installing, not as a
+     * containment guarantee.
+     *
+     * Entries are bare hostnames, {@link NetworkPermissionHost} objects when
+     * the upstream needs pacing, or {@link NetworkPermissionFromConfig} when
+     * the operator is the one who names it. Order matters only for pacing: the
+     * first entry a hostname matches supplies its rate and bucket.
+     */
+    network: NetworkPermission[];
+    /** Whether the plugin may use `host.storage` (namespaced key/value state). */
+    storage: boolean;
+    /** Whether the plugin may use `host.oauth` (redirect URI + token vault). */
+    oauth: boolean;
+    /**
+     * Whether the plugin may use `host.trackFetcher` (lend the station's
+     * fetcher a login, get back a URL).
+     *
+     * Optional, unlike the two above, because almost no plugin wants it: a
+     * provider whose audio can be fetched with a URL mints one itself. Making
+     * it required would put a `false` in every manifest to disclaim something
+     * only one provider has ever needed.
+     */
+    trackFetcher?: boolean;
+    /**
+     * Capabilities this plugin is ASKING for, each with the reason an operator
+     * reads before deciding. See {@link PluginGrantRequest}.
+     *
+     * Optional and usually absent: almost every plugin does its whole job inside
+     * what it declares above, and a manifest that asks for nothing is the normal
+     * case rather than a modest one.
+     *
+     * Nothing here is granted by declaring it. Until the operator answers, the
+     * capability behaves exactly as it does for a plugin that never asked.
+     */
+    grants?: PluginGrantRequest[];
+}
+export declare const networkPermissionSchema: z.ZodType<NetworkPermission>;
+export declare const grantRequestSchema: z.ZodType<PluginGrantRequest>;
+export declare const pluginPermissionsSchema: z.ZodObject<{
+    network: z.ZodArray<z.ZodType<NetworkPermission, unknown, z.core.$ZodTypeInternals<NetworkPermission, unknown>>>;
+    storage: z.ZodBoolean;
+    oauth: z.ZodBoolean;
+    trackFetcher: z.ZodOptional<z.ZodBoolean>;
+    grants: z.ZodOptional<z.ZodArray<z.ZodType<PluginGrantRequest, unknown, z.core.$ZodTypeInternals<PluginGrantRequest, unknown>>>>;
+}, z.core.$strip>;
+export {};
+//# sourceMappingURL=plugin.permissions.d.ts.map

package/dist/plugin.permissions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.permissions.d.ts","sourceRoot":"","sources":["../src/plugin.permissions.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,uDAAuD;AACvD,UAAU,uBAAuB;IAC7B;;;;;;;;;OASG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IAEvB;;;;;;;;;OASG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,qBAAsB,SAAQ,uBAAuB;IAClE;;;;OAIG;IACH,IAAI,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,MAAM,WAAW,2BAA4B,SAAQ,uBAAuB;IACxE,mEAAmE;IACnE,UAAU,EAAE,MAAM,CAAC;CACtB;AAED,yEAAyE;AACzE,MAAM,MAAM,iBAAiB,GAAG,MAAM,GAAG,qBAAqB,GAAG,2BAA2B,CAAC;AAE7F;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,WAAW,kBAAmB,SAAQ,uBAAuB;IAC/D,+DAA+D;IAC/D,UAAU,EAAE,MAAM,CAAC;IACnB;;;;;;;;OAQG;IACH,MAAM,EAAE,MAAM,CAAC;CAClB;AAED;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAC9B;;;;;;;;;;;;;;;OAeG;IACH,OAAO,EAAE,iBAAiB,EAAE,CAAC;IAE7B,8EAA8E;IAC9E,OAAO,EAAE,OAAO,CAAC;IAEjB,4EAA4E;IAC5E,KAAK,EAAE,OAAO,CAAC;IAEf;;;;;;;;OAQG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IAEvB;;;;;;;;;;OAUG;IACH,MAAM,CAAC,EAAE,kBAAkB,EAAE,CAAC;CACjC;AASD,eAAO,MAAM,uBAAuB,EAAE,CAAC,CAAC,OAAO,CAAC,iBAAiB,CAI/D,CAAC;AAEH,eAAO,MAAM,kBAAkB,EAAE,CAAC,CAAC,OAAO,CAAC,kBAAkB,CAO3D,CAAC;AAEH,eAAO,MAAM,uBAAuB;;;;;;iBAMlC,CAAC"}

package/dist/testing/fake.plugin.host.d.ts

@@ -0,0 +1,85 @@
+import type { HostFetchInit, HostFetchMethod, PluginHost, ProviderStream } from '../index.js';
+/**
+ * Shipped from the SDK rather than copied into each plugin, which three of them
+ * were doing — two of those carrying a comment saying the copy was deliberate
+ * because plugins do not depend on each other.
+ *
+ * That reasoning held for the copies and does not hold for this: every plugin
+ * already depends on the SDK, and `PluginHost` is the SDK's own contract, so its
+ * test double belongs beside the interface it doubles. A plugin importing this
+ * gains no dependency on any other plugin. It also means a host method added to
+ * the contract turns up in one fake rather than being added to three and
+ * forgotten in the other three.
+ *
+ * Reached as `@deadair/plugin-sdk/testing`, which is kept out of the runtime
+ * entry so nothing ships a dependency on vitest.
+ */
+/** One `host.fetch` call, recorded with only the fields tests care about. */
+export interface RecordedFetchCall {
+    url: string;
+    method: HostFetchMethod | undefined;
+    headers: Record<string, string> | undefined;
+    body: string | undefined;
+}
+/**
+ * A `PluginHost` for tests. `fetch` replays a queue of scripted
+ * `Response`s (FIFO, one per call) — or a custom handler installed
+ * with `setFetchImpl`, for call-count-driven scenarios like a 401-then-200
+ * retry — and records every call it received in `calls`. `storage`, `config`,
+ * `secrets` and the `oauth` vault are in-memory and can be seeded or read
+ * directly, bypassing the `PluginHost` methods, so a test can assert on state
+ * without going through the code under test twice.
+ */
+export interface FakePluginHost extends PluginHost {
+    /** Every `host.fetch` call so far, in call order. */
+    readonly calls: RecordedFetchCall[];
+    /** Set what `host.remainingMs()` reports, for testing budget shedding. */
+    seedRemainingMs(ms: number): void;
+    /** Push one scripted response onto the back of the reply queue. */
+    queueResponse(response: FakeResponseInit): void;
+    /** Replace the fetch handler outright; overrides the queue while set. */
+    setFetchImpl(impl: (url: string, init?: HostFetchInit) => Promise<Response>): void;
+    /** Seed the value `host.config.get()` resolves to. */
+    seedConfig(config: Record<string, unknown>): void;
+    /** Seed a value `host.secrets.get(key)` resolves to. */
+    seedSecret(key: string, value: string): void;
+    /** Seed a storage entry directly, bypassing `host.storage.set`. */
+    seedStorage(key: string, value: unknown): void;
+    /** Read a storage entry directly, bypassing `host.storage.get`. */
+    getStorageEntry(key: string): unknown;
+    /** All storage keys currently set, unfiltered. */
+    storageKeys(): string[];
+    /** Seed the oauth vault directly, bypassing `host.oauth.saveTokens`. */
+    seedTokens(tokens: Record<string, string>): void;
+    /** Read the oauth vault directly, bypassing `host.oauth.getTokens`. */
+    getVaultTokens(): Record<string, string> | undefined;
+    /** Set what `host.trackFetcher.serve()` answers with; `undefined` means "this station has no fetcher". */
+    seedFetchedTrack(stream: ProviderStream | undefined): void;
+}
+/**
+ * What a test says a scripted reply should be.
+ *
+ * Not `ResponseInit`, because `url` is not on it: `host.fetch` reports the last
+ * hop of the redirect chain there, and a `Response` built by hand has an empty
+ * one unless it is defined in.
+ */
+export interface FakeResponseInit {
+    status?: number;
+    statusText?: string;
+    headers?: Record<string, string>;
+    /**
+     * Text for a JSON or error reply, bytes for a binary one.
+     *
+     * `Uint8Array<ArrayBuffer>` rather than a bare `Uint8Array`: the DOM lib's
+     * `BodyInit` accepts a view over a real `ArrayBuffer`, and the unparameterized
+     * form widens to `ArrayBufferLike`, which includes `SharedArrayBuffer` and is
+     * not something `Response` will take. `new Uint8Array([...])` already has the
+     * narrow type, so no test has to say so.
+     */
+    body?: string | Uint8Array<ArrayBuffer>;
+    url?: string;
+}
+/** Builds a default 200 `Response`, overridable field by field. */
+export declare function fakeHostFetchResponse(init?: FakeResponseInit): Response;
+export declare function createFakePluginHost(): FakePluginHost;
+//# sourceMappingURL=fake.plugin.host.d.ts.map

package/dist/testing/fake.plugin.host.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fake.plugin.host.d.ts","sourceRoot":"","sources":["../../src/testing/fake.plugin.host.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAE,eAAe,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAE9F;;;;;;;;;;;;;;GAcG;AAEH,6EAA6E;AAC7E,MAAM,WAAW,iBAAiB;IAC9B,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,eAAe,GAAG,SAAS,CAAC;IACpC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,CAAC;IAC5C,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;CAC5B;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,cAAe,SAAQ,UAAU;IAC9C,qDAAqD;IACrD,QAAQ,CAAC,KAAK,EAAE,iBAAiB,EAAE,CAAC;IACpC,0EAA0E;IAC1E,eAAe,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,mEAAmE;IACnE,aAAa,CAAC,QAAQ,EAAE,gBAAgB,GAAG,IAAI,CAAC;IAChD,yEAAyE;IACzE,YAAY,CAAC,IAAI,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,aAAa,KAAK,OAAO,CAAC,QAAQ,CAAC,GAAG,IAAI,CAAC;IACnF,sDAAsD;IACtD,UAAU,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAClD,wDAAwD;IACxD,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7C,mEAAmE;IACnE,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI,CAAC;IAC/C,mEAAmE;IACnE,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;IACtC,kDAAkD;IAClD,WAAW,IAAI,MAAM,EAAE,CAAC;IACxB,wEAAwE;IACxE,UAAU,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CAAC;IACjD,uEAAuE;IACvE,cAAc,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,CAAC;IACrD,0GAA0G;IAC1G,gBAAgB,CAAC,MAAM,EAAE,cAAc,GAAG,SAAS,GAAG,IAAI,CAAC;CAC9D;AASD;;;;;;GAMG;AACH,MAAM,WAAW,gBAAgB;IAC7B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC;;;;;;;;OAQG;IACH,IAAI,CAAC,EAAE,MAAM,GAAG,UAAU,CAAC,WAAW,CAAC,CAAC;IACxC,GAAG,CAAC,EAAE,MAAM,CAAC;CAChB;AAKD,mEAAmE;AACnE,wBAAgB,qBAAqB,CAAC,IAAI,GAAE,gBAAqB,GAAG,QAAQ,CAa3E;AAED,wBAAgB,oBAAoB,IAAI,cAAc,CAqFrD"}

package/dist/testing/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Test doubles for the plugin contract.
+ *
+ * A separate entry point (`@deadair/plugin-sdk/testing`) rather than part of the
+ * package's main export, because this imports `vitest`: anything here would
+ * otherwise be a runtime dependency of every plugin the station loads in
+ * process.
+ */
+export * from './fake.plugin.host.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/testing/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/testing/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,cAAc,uBAAuB,CAAC"}