@deadair/plugin-sdk 0.2.0

package/dist/plugin.config.read.d.ts

@@ -0,0 +1,52 @@
+import type { PluginHost } from './plugin.host.js';
+/**
+ * Reading an operator's typed-in config field.
+ *
+ * `host.config.get()` answers `Record<string, unknown>`, because the values came
+ * out of a database column an operator edits through a text box. Every plugin
+ * therefore narrows each field itself, and every plugin was narrowing it the
+ * same two ways: "a string, and blank counts as unset", and "a base URL with no
+ * trailing slash".
+ *
+ * Blank counting as unset is the important half. A cleared text box stores `''`
+ * rather than removing the row, so a plugin comparing against `undefined` alone
+ * sees an empty string, treats it as a real value, and sends it upstream.
+ */
+/**
+ * A config field as a trimmed string, or `undefined` when it is not set.
+ *
+ * Whitespace-only is unset for the same reason blank is: an operator who
+ * selected a value and deleted it has said "none", and a space is not a model
+ * name.
+ */
+export declare function configString(value: unknown): string | undefined;
+/**
+ * A base URL with no trailing slash, so a path can be appended with one.
+ *
+ * Answers `''` rather than `undefined` for a field that is not set, which is
+ * deliberate and is what every caller already expected: a plugin holds its base
+ * URL as a plain `string` and reports "not configured" by testing whether it is
+ * empty, in a sentence of its own naming the thing it cannot reach ("No
+ * analyzer URL set."). Making this optional would push a `?? ''` to every use
+ * and change nothing else.
+ */
+export declare function configBaseUrl(value: unknown): string;
+/**
+ * The credential one ROW of a `list` field holds, or `undefined` when the operator has not set it.
+ *
+ * The whole of what a plugin has to know about secret cells. A `secret` column is never in the row
+ * that {@link parseRows} hands back — that is what makes it a secret rather than a JSON string with
+ * a password in it — so this is how the value is reached, and the key it is stored under is nobody's
+ * business but this function's.
+ *
+ * Answers `undefined` for a row the host has never saved, which is the honest answer: a row with no
+ * {@link ROW_ID_KEY} has never been stored, so there is nothing under it.
+ *
+ * ```ts
+ * for (const row of parseRows(config.providers)) {
+ *     const apiKey = await readRowSecret(this.host, 'providers', row, 'apiKey');
+ * }
+ * ```
+ */
+export declare function readRowSecret(host: PluginHost, fieldKey: string, row: Record<string, string>, columnKey: string): Promise<string | undefined>;
+//# sourceMappingURL=plugin.config.read.d.ts.map

package/dist/plugin.config.read.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.config.read.d.ts","sourceRoot":"","sources":["../src/plugin.config.read.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAEnD;;;;;;;;;;;;GAYG;AAEH;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAK/D;AAED;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAEpD;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,aAAa,CAAC,IAAI,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAKnJ"}

package/dist/plugin.error.d.ts

@@ -0,0 +1,177 @@
+/**
+ * The one error shape that means the same thing on both sides of the plugin
+ * boundary.
+ *
+ * Deliberately NOT a subclass of the API's `ServerkitError`: that class lives
+ * in `@maroonedsoftware/errors`, a server dependency, and inheriting from it
+ * here would pull the host's framework into every plugin's dependency tree,
+ * which is exactly what this package exists to avoid. So a plugin says what
+ * went wrong in its own vocabulary and the host decides what that means over
+ * HTTP (see `plugin.error.http.ts` in the API).
+ *
+ * The classification fields (`code`, `retryable`, `retryAfterMs`,
+ * `upstreamStatus`, `message`) are all JSON-safe on purpose: nothing here
+ * crosses the boundary as a live object today, but the day plugins move out of
+ * process, what has to change is how this is transported, not what it says.
+ * `cause` is the exception, and is in-process debugging detail only.
+ */
+/**
+ * Why a plugin call failed, in terms the host can act on.
+ *
+ * These are semantic, not HTTP: an upstream's status code is a diagnostic
+ * (`upstreamStatus`), never the answer to what this API should respond. A
+ * provider's 404 and "no plugin by that id" are not the same 404.
+ */
+export type PluginErrorCode = 
+/** Credentials are missing, expired or rejected. The operator has to reauthorize. */
+'auth'
+/** The plugin's stored settings are wrong or incomplete. The operator has to fix the form. */
+ | 'config'
+/** The upstream has no such resource. Often not an error at all to the caller. */
+ | 'not_found'
+/**
+ * The upstream understood, and refused for this specific resource. Distinct
+ * from `auth`: the credentials are fine and the next call for something
+ * else will succeed.
+ */
+ | 'forbidden'
+/** The upstream is throttling. Honour `retryAfterMs` when it is set. */
+ | 'rate_limited'
+/** The call did not finish in time. */
+ | 'timeout'
+/** The plugin or its upstream is temporarily out of service. */
+ | 'unavailable'
+/** The plugin does not implement what was asked of it. */
+ | 'unsupported'
+/** The upstream answered, and what it said was a failure. */
+ | 'upstream'
+/** Anything else, including a bug in the plugin. */
+ | 'internal';
+/** Every {@link PluginErrorCode}, for validating a code that arrived from third-party code. */
+export declare const PLUGIN_ERROR_CODES: readonly ["auth", "config", "not_found", "forbidden", "rate_limited", "timeout", "unavailable", "unsupported", "upstream", "internal"];
+/**
+ * Whether this failure is about the requested resource rather than the plugin.
+ *
+ * See {@link RESOURCE_SCOPED_CODES}. Hosts use this to decide whether a
+ * failure counts against a plugin's health.
+ */
+export declare function isResourceScopedCode(code: PluginErrorCode): boolean;
+/**
+ * Marker that survives a plugin carrying its own copy of this module.
+ *
+ * `Symbol.for` reads from the global symbol registry, which is shared by every
+ * realm in the agent, so a second copy of this file computes the *identical*
+ * symbol rather than a private one. That is the whole trick: `instanceof`
+ * compares class identity and a second copy has its own class, while this
+ * compares a value two copies independently agree on.
+ *
+ * A symbol rather than a string property because it then stays out of
+ * `JSON.stringify`, `Object.keys` and log output, and because a plain object
+ * decoded off the wire cannot carry one by accident the way a well-guessed
+ * string field could.
+ *
+ * Only {@link toPluginError} reads it. See the note on {@link isPluginError}
+ * for why recognition and adoption are deliberately different questions.
+ */
+declare const PLUGIN_ERROR_BRAND: unique symbol;
+/**
+ * A failure a plugin can describe well enough for the host to answer properly.
+ *
+ * Throwing a bare `Error` stays perfectly legal; the host treats it as
+ * `internal` and behaves exactly as it did before this class existed. Reach
+ * for `PluginError` when the caller can do something different with the answer:
+ * reauthorize, wait, fix a setting, or give up.
+ *
+ * The classification is applied with the `with*` builders rather than through
+ * the constructor, so a subclass only has to forward `(message, options)` to
+ * `super` and can then say what it means on its own terms:
+ *
+ * ```ts
+ * throw new PluginError('slow down').withCode('rate_limited').withUpstreamStatus(429).withRetry(30_000);
+ * ```
+ *
+ * Call {@link withCode} first: it resets `retryable` to the default for the
+ * code, so a later `withCode` would undo an earlier {@link withRetry}.
+ */
+export declare class PluginError extends Error {
+    /** @internal Recognition marker for a foreign copy. See {@link PLUGIN_ERROR_BRAND}. */
+    readonly [PLUGIN_ERROR_BRAND] = true;
+    /** What went wrong, in host vocabulary. Defaults to `internal`; set it with {@link withCode}. */
+    code: PluginErrorCode;
+    /** Whether repeating the call could plausibly succeed. See {@link RETRYABLE_BY_CODE}. */
+    retryable: boolean;
+    /** How long to wait before retrying, when the upstream said so (`Retry-After`). */
+    retryAfterMs?: number;
+    /**
+     * The upstream's HTTP status, for logs and for plugin-internal branching.
+     * Diagnostic only: the host never forwards it as its own response status.
+     */
+    upstreamStatus?: number;
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+    /** Classifies the failure, and resets `retryable` to the default for that code. */
+    withCode(code: PluginErrorCode): this;
+    /**
+     * Attaches the upstream's retry advice. Saying "wait this long and try
+     * again" is itself a statement that a retry is worth making, so this marks
+     * the failure retryable regardless of what the code defaults to.
+     */
+    withRetry(retryAfterMs: number): this;
+    withUpstreamStatus(upstreamStatus: number): this;
+}
+/**
+ * Whether `value` is one of ours: an error this copy of the module built.
+ *
+ * Deliberately `instanceof`, and deliberately NOT the same question
+ * {@link toPluginError} answers. Almost every caller asking this is host code
+ * downstream of the invoker, where the error has already been adopted and the
+ * honest question is "did we make this", to which `instanceof` is the exact,
+ * unforgeable answer. It also keeps subclasses (`SpotifyRequestError`) working
+ * for the plugin's own branching, via the constructor's `new.target` fix-up.
+ *
+ * Tolerating a foreign copy is the boundary's job, and the boundary is one
+ * function wide. Making this guard structural instead would spread that
+ * laxness across every call site that only ever sees host-built errors.
+ */
+export declare const isPluginError: (error: unknown) => error is PluginError;
+/**
+ * Whatever a plugin threw, as a {@link PluginError} this copy owns.
+ *
+ * This is the boundary function, and the only place tolerant recognition
+ * belongs: the host funnels every call into plugin code through one door
+ * (`PluginInvoker.invoke`), so a foreign error is adopted exactly once and
+ * everything downstream deals only with errors the host itself constructed.
+ *
+ * Three cases, in order of how much is trusted:
+ *
+ * 1. Ours: passed straight through, keeping its identity so a `catch` further
+ *    up can still recognize the specific subclass that was thrown.
+ * 2. Branded but from another copy: rebuilt here, field by field, with the
+ *    code checked against {@link PLUGIN_ERROR_CODES}. An unrecognized code
+ *    degrades to `fallback` rather than leaking a made-up string into the
+ *    host's HTTP mapping, and a non-numeric `retryAfterMs` is dropped rather
+ *    than turned into a `Retry-After` header of `NaN`.
+ * 3. Anything else: adopted under `fallback`, original kept as the `cause`.
+ *
+ * The rebuild in case 2 is the same operation that will be needed when plugins
+ * move out of process and a failure arrives as JSON rather than as a live
+ * object: what changes then is how it is transported, not what it says.
+ */
+export declare function toPluginError(error: unknown, fallback?: PluginErrorCode): PluginError;
+/**
+ * A caught `unknown` as a sentence, for a message a person reads.
+ *
+ * `catch` binds `unknown`, so every plugin reporting a failure narrows it before
+ * it can say anything — five sites here did, four of them inline. The fallback
+ * is not padding: a rejected fetch, a thrown string and an aborted signal all
+ * arrive here and only some of them are `Error`.
+ *
+ * This is NOT error handling and is not a substitute for {@link toPluginError}.
+ * It produces a string for a log line or a `testConnection` result, deliberately
+ * losing the code, the cause and the retry advice. Anything deciding what to DO
+ * about a failure wants the error itself.
+ */
+export declare const errorText: (error: unknown) => string;
+export {};
+//# sourceMappingURL=plugin.error.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.error.d.ts","sourceRoot":"","sources":["../src/plugin.error.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH;;;;;;GAMG;AACH,MAAM,MAAM,eAAe;AACvB,qFAAqF;AACnF,MAAM;AACR,8FAA8F;GAC5F,QAAQ;AACV,kFAAkF;GAChF,WAAW;AACb;;;;GAIG;GACD,WAAW;AACb,wEAAwE;GACtE,cAAc;AAChB,uCAAuC;GACrC,SAAS;AACX,gEAAgE;GAC9D,aAAa;AACf,0DAA0D;GACxD,aAAa;AACf,6DAA6D;GAC3D,UAAU;AACZ,oDAAoD;GAClD,UAAU,CAAC;AAEjB,+FAA+F;AAC/F,eAAO,MAAM,kBAAkB,wIAWrB,CAAC;AAoBX;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,eAAe,GAAG,OAAO,CAEnE;AAwBD;;;;;;;;;;;;;;;;GAgBG;AACH,QAAA,MAAM,kBAAkB,eAAwC,CAAC;AAEjE;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,WAAY,SAAQ,KAAK;IAClC,uFAAuF;IACvF,QAAQ,CAAC,CAAC,kBAAkB,CAAC,QAAQ;IAErC,iGAAiG;IACjG,IAAI,EAAE,eAAe,CAAc;IACnC,yFAAyF;IACzF,SAAS,EAAE,OAAO,CAA8B;IAChD,mFAAmF;IACnF,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;gBAEZ,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE;IAW1D,mFAAmF;IACnF,QAAQ,CAAC,IAAI,EAAE,eAAe;IAM9B;;;;OAIG;IACH,SAAS,CAAC,YAAY,EAAE,MAAM;IAM9B,kBAAkB,CAAC,cAAc,EAAE,MAAM;CAI5C;AAED;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,aAAa,GAAI,OAAO,OAAO,KAAG,KAAK,IAAI,WAEvD,CAAC;AAcF;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,GAAE,eAA4B,GAAG,WAAW,CAgBjG;AAED;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,SAAS,GAAI,OAAO,OAAO,KAAG,MAAkE,CAAC"}

package/dist/plugin.host.d.ts

@@ -0,0 +1,220 @@
+/**
+ * What the host lends a plugin. Everything here is an ordinary in-process call: the host and the
+ * plugin share a realm, permanently, so `fetch` hands back a real `Response` and `signal` is a real
+ * `AbortSignal`. See `packages/plugin-sdk/CLAUDE.md` § "Trust and egress".
+ *
+ * The JSON-safe rule that used to govern this file has not gone away, it has
+ * moved to where it pays for itself: `boundary.json.safe.ts` still asserts it
+ * over every payload that is stored in Postgres or sent over HTTP, which is
+ * most of `capabilities/` plus the manifest. What is no longer asserted is the
+ * arguments and return values of the methods below, because nothing serializes
+ * them. `TrackFetchSession` and `TrackFetchRequest` are the exceptions in this
+ * file: they go over HTTP to the track fetcher, so they stay asserted.
+ */
+import type { ProviderStream } from './capabilities/music.provider.js';
+/** Structured logging. Goes to the host's logger, tagged with the plugin id. */
+export interface PluginLogger {
+    debug(message: string, meta?: Record<string, unknown>): void;
+    info(message: string, meta?: Record<string, unknown>): void;
+    warn(message: string, meta?: Record<string, unknown>): void;
+    error(message: string, meta?: Record<string, unknown>): void;
+}
+export type HostFetchMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD';
+/** JSON-safe subset of `RequestInit`. */
+export interface HostFetchInit {
+    method?: HostFetchMethod;
+    headers?: Record<string, string>;
+    /** Already-serialised body. Set `content-type` yourself. */
+    body?: string;
+    /**
+     * Budget in ms for the WHOLE call, clamped to the host's ceiling: waiting
+     * for rate-limit headroom, the request, any `Retry-After` back-off and the
+     * retry all come out of this one number. The ceiling is the host's own
+     * deadline for a call into plugin code, so asking for more buys nothing.
+     */
+    timeoutMs?: number;
+    /**
+     * Your own reason to give up, on top of the host's.
+     *
+     * Composed with the host's deadline rather than replacing it: whichever
+     * fires first ends the request, and {@link PluginHost.signal} is already
+     * watched for you. Pass one when the plugin has a cancellation of its own,
+     * such as a caller that walked away or a race between two upstreams.
+     */
+    signal?: AbortSignal;
+}
+/**
+ * Namespaced key/value store, private to this plugin. Values must be
+ * JSON-serialisable. Requires the `storage` permission.
+ */
+export interface PluginStorage {
+    get(key: string): Promise<unknown>;
+    set(key: string, value: unknown): Promise<void>;
+    delete(key: string): Promise<void>;
+    /** Keys, optionally filtered to those starting with `prefix`. */
+    list(prefix?: string): Promise<string[]>;
+}
+/** Read access to this plugin's own decrypted secret config values. */
+export interface PluginSecrets {
+    /** Resolves to `undefined` when the operator never set the value. */
+    get(key: string): Promise<string | undefined>;
+}
+/** Read access to this plugin's validated non-secret config values. */
+export interface PluginConfigAccess {
+    get(): Promise<Record<string, unknown>>;
+}
+/**
+ * OAuth token vault. The host owns the redirect endpoint and the encryption;
+ * the plugin only builds the authorize URL and exchanges the code.
+ * Requires the `oauth` permission.
+ */
+export interface PluginOAuth {
+    /** The host-owned redirect URI to register with the provider. */
+    getRedirectUri(): Promise<string>;
+    saveTokens(tokens: Record<string, string>): Promise<void>;
+    /** Resolves to `undefined` when the plugin has never completed a flow. */
+    getTokens(): Promise<Record<string, string> | undefined>;
+}
+/** Fire-and-forget notifications onto the host's event bus. */
+export interface PluginEvents {
+    emit(event: string, payload?: Record<string, unknown>): Promise<void>;
+}
+/**
+ * A login the station's track fetcher opens its own session with.
+ *
+ * Handed to {@link PluginTrackFetcher.serve} and nowhere else: it is not
+ * persisted, not written to config, and not readable back out of the host. The
+ * plugin still owns the account and the refresh.
+ */
+export interface TrackFetchSession {
+    /** The account the fetcher should log in as. */
+    username: string;
+    /** A currently-valid access token. */
+    accessToken: string;
+    /** Unix epoch millis after which `accessToken` stops working. */
+    expiresAt?: number;
+}
+export interface TrackFetchRequest {
+    /** Provider-scoped track id, exactly as the plugin's own catalog reports it. */
+    trackId: string;
+    session: TrackFetchSession;
+}
+/**
+ * The station's own track fetcher: a helper process, running beside the audio
+ * player, that speaks a provider's protocol and re-serves the result as plain
+ * audio over HTTP.
+ *
+ * This exists for one shape of provider: the audio is reachable, but only to a
+ * process speaking a protocol the plugin does not. Spotify is the reason —
+ * its tracks come off the CDN encrypted and are fetched by a separate binary
+ * beside Liquidsoap. Without this, such a provider could not implement
+ * `MusicProviderStream.resolveStreamUrl` at all, because there is no URL for it
+ * to mint. Named in backticks rather than linked: importing that type solely to
+ * make a doc reference clickable leaves an import nothing uses, which is a lint
+ * failure in a package whose gate is zero warnings.
+ *
+ * Do NOT reach for this when your provider's audio can simply be fetched. Mint
+ * the URL yourself and keep your credentials to yourself, which is both simpler
+ * and narrower. Requires the `trackFetcher` permission.
+ */
+export interface PluginTrackFetcher {
+    /**
+     * Lend the fetcher a login and get back a URL for one track.
+     *
+     * Resolves to `undefined` when this station has no fetcher configured,
+     * which a plugin should pass straight through as "cannot resolve this
+     * item" rather than treat as an error: an operator who never set the
+     * stream side up is a normal state, not a fault.
+     */
+    serve(request: TrackFetchRequest): Promise<ProviderStream | undefined>;
+}
+/**
+ * The single object handed to a plugin at init, and the sanctioned way to get
+ * at the outside world: network, persistence, secrets, tokens.
+ *
+ * NOT A SANDBOX, and never going to be one. The host imports plugins into its own realm,
+ * permanently (`packages/plugin-sdk/CLAUDE.md` § "Trust and egress"), so global `fetch`, `fs`, and
+ * `process.env` are all reachable and nothing stops a plugin from using them. What this interface
+ * buys is a manifest that honestly describes a well-behaved plugin's blast radius, plus a set of
+ * guarantees (rate limiting, timeouts, SSRF-safe redirects) that no plugin has to reimplement.
+ * Containment is not among them, and the console says so before an operator enables anything.
+ */
+export interface PluginHost {
+    logger: PluginLogger;
+    /**
+     * The sanctioned network egress. Enforces the manifest's hostname
+     * allowlist, a timeout, a rate limit, and `Retry-After` back-off, and
+     * re-checks the allowlist on every redirect hop so an upstream cannot
+     * bounce a plugin somewhere its manifest never asked for. Rejects if
+     * `url`'s hostname is not in `permissions.network`.
+     *
+     * The allowlist is advisory against a plugin that simply calls global
+     * `fetch` instead (see the note on {@link PluginHost}). It is not advisory
+     * against a hostile *server*: the redirect and credential-stripping rules
+     * protect an honest plugin, and it gains nothing by going around them.
+     *
+     * A real `Response`, so `await response.json()` is how you read JSON and
+     * `response.body` is how you stream audio. There is no second egress for
+     * bytes: a body you do not buffer is one you read off `response.body`, and
+     * a body you never read at all should be `response.body?.cancel()`-ed
+     * rather than dropped.
+     *
+     * `timeoutMs` bounds getting the response: connect, headers and the whole
+     * redirect chain. It does NOT bound reading the body, because a large body
+     * legitimately outlives the call that asked for it. The body is bounded
+     * instead by an idle deadline between chunks, a total byte cap and a
+     * lifetime cap, all host-enforced. Exceeding any of them fails the read
+     * rather than truncating it, so bytes you get are always bytes the server
+     * actually sent.
+     */
+    fetch(url: string, init?: HostFetchInit): Promise<Response>;
+    /**
+     * Aborts when the host gives up on the call you are currently inside.
+     *
+     * The same signal the host itself races the call against, not a copy, so
+     * honouring it and being abandoned are the same moment rather than two
+     * clocks that nearly agree. `host.fetch` already watches it; pass it on to
+     * anything else of yours that takes one.
+     *
+     * Outside any host call (from a timer you set yourself) this is a signal
+     * that never aborts, because nothing is waiting on that work.
+     */
+    signal: AbortSignal;
+    /**
+     * Milliseconds left before the host abandons the call you are currently
+     * inside, so work that does not fit can be dropped deliberately instead of
+     * being cut off halfway.
+     *
+     * The number behind {@link PluginHost.signal}, for deciding whether to
+     * START something rather than for being interrupted during it. The signal
+     * tells you the call is over; this tells you it is nearly over, which is
+     * the only one of the two that can save a partial result.
+     *
+     * The host gives every call into your code a deadline, and it is not a
+     * constant: a background job may run on a far longer budget than a request
+     * a person is waiting on, and the same method of yours can be called both
+     * ways. Guessing at it is how a plugin ends up either quitting early on a
+     * budget it had, or being killed mid-flight with nothing useful to return.
+     *
+     * The pattern this exists for is a sequence where the later steps are
+     * optional:
+     *
+     * ```ts
+     * const core = await this.lookup(ref);
+     * if (host.remainingMs() < 2_000) return core;  // good enough, out of time
+     * return { ...core, ...(await this.enrich(core)) };
+     * ```
+     *
+     * Not a budget you are given: it is the host's, spent by everything the
+     * call does, and `host.fetch` already caps its own timeout by it. Treat a
+     * small number as advice to wrap up, not as permission to run that long.
+     */
+    remainingMs(): number;
+    storage: PluginStorage;
+    secrets: PluginSecrets;
+    config: PluginConfigAccess;
+    oauth: PluginOAuth;
+    events: PluginEvents;
+    trackFetcher: PluginTrackFetcher;
+}
+//# sourceMappingURL=plugin.host.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.host.d.ts","sourceRoot":"","sources":["../src/plugin.host.ts"],"names":[],"mappings":"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"}

package/dist/plugin.host.response.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Sugar over the `Response` that `host.fetch` hands back.
+ *
+ * Free functions rather than a `Response` subclass with methods, because
+ * `host.fetch` returns the platform's own `Response` and a plugin has to be
+ * able to pass it to any library that takes one. Anything that made it a
+ * special response would take that away for the sake of dot notation.
+ *
+ * What they buy over `await response.json()` is the error. The common failure
+ * is an API answering 200 with an HTML error page or a rate-limit notice, and
+ * `Unexpected token < in JSON at position 0` says nothing about which call did
+ * it.
+ */
+/**
+ * The body parsed as JSON.
+ *
+ * Throws when it is not JSON, with the status, the URL and the start of the
+ * body in the message. That detail is the point, and it is why this reads the
+ * body as text and parses that rather than calling `response.json()`: the text
+ * is what names what the server actually sent.
+ *
+ * A body that fails to READ rather than to parse (over the host's byte cap, a
+ * socket that went quiet) rejects with the host's own `PluginError` untouched.
+ * That is a different failure from a body that arrived and was not JSON, and
+ * relabelling it would lose the code the caller branches on.
+ *
+ * Note this does not check `response.ok`. A 4xx with a JSON error body is worth
+ * parsing, so deciding what a bad status means is left to the caller.
+ */
+export declare function jsonBody<T>(response: Response): Promise<T>;
+/**
+ * {@link jsonBody}, but `undefined` instead of a throw when the body will not
+ * parse. For the callers that treat an unparseable body the same as a missing
+ * one and have nothing useful to add to the error.
+ *
+ * A body that fails to read still rejects, for the reason above: the host
+ * refusing an oversized body is not the same event as a server answering with
+ * something that is not JSON, and swallowing the first would report a
+ * misconfiguration as an empty result.
+ */
+export declare function tryJsonBody<T>(response: Response): Promise<T | undefined>;
+//# sourceMappingURL=plugin.host.response.d.ts.map

package/dist/plugin.host.response.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.host.response.d.ts","sourceRoot":"","sources":["../src/plugin.host.response.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAWH;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,QAAQ,CAAC,CAAC,EAAE,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,CAAC,CAAC,CAQhE;AAED;;;;;;;;;GASG;AACH,wBAAsB,WAAW,CAAC,CAAC,EAAE,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,CAO/E"}

package/dist/plugin.http.d.ts

@@ -0,0 +1,80 @@
+import type { HostFetchMethod } from './plugin.host.js';
+import type { PluginErrorCode } from './plugin.error.js';
+/**
+ * An upstream's sentence, bounded.
+ *
+ * An error body is untrusted text that ends up in a log line and on a settings
+ * card, so its length is not the upstream's decision to make. Three clients cut
+ * it at the same 200 characters with the same ellipsis.
+ */
+export declare function truncateUpstreamMessage(message: string): string;
+/**
+ * A string field out of a JSON error body, or `undefined`.
+ *
+ * Defensive on purpose, and in a specific way: the body is whatever the edge
+ * happened to send — an HTML page from a proxy, an empty 429, a truncated
+ * response — so a failed parse has to read as "said nothing" rather than throw
+ * inside the code that was already handling a failure. An empty string is also
+ * nothing, since it would otherwise print as a blank reason.
+ *
+ * @param body - The raw response body. `undefined` when it was never read.
+ * @param pick - Reaches the field. Runs on `unknown`, so it casts; anything it
+ *   returns that is not a non-empty string is discarded.
+ */
+export declare function upstreamField(body: string | undefined, pick: (parsed: unknown) => unknown): string | undefined;
+/**
+ * `Retry-After` in whole seconds, as milliseconds.
+ *
+ * Only the seconds form is read. The HTTP-date form is legal and no upstream
+ * here sends it, and guessing wrong would tell the host to sit out a wait that
+ * was never asked for. Anything unparseable or negative means "no advice
+ * given", which is different from "wait zero".
+ *
+ * Takes `null` as well as `undefined` because one caller reads it off a
+ * `Headers` (which answers `null`) and another off a record (which answers
+ * `undefined`).
+ */
+export declare function retryAfterMs(header: string | null | undefined): number | undefined;
+/**
+ * The rows of the status ladder that mean the same thing at every upstream.
+ *
+ * A plugin layers its own service's readings in FRONT of this rather than
+ * replacing it, because the deviations are the interesting part and each one is
+ * a decision worth writing down beside the plugin it belongs to. Spotify reads
+ * 401 as `auth` and 403 as `forbidden`; MusicBrainz reads a 503 carrying a
+ * `Retry-After` as `rate_limited`; the two token-authenticated services read
+ * 401 as `config`, because a pasted token is a setting. None of those belongs
+ * here.
+ *
+ * What does belong here is the part nobody disagrees about: a 404 is a missing
+ * thing, a 429 is going too fast, any other 5xx is the upstream being down, and
+ * everything else is the upstream saying something unhelpful.
+ */
+export declare function pluginCodeForStatus(status: number): PluginErrorCode;
+/**
+ * A one-line summary of a failed response, for a message a human reads.
+ *
+ * The status is always there; the other two often are not, and an upstream that
+ * sent neither should not produce a line with holes in it.
+ */
+export declare function upstreamDetail(status: number, statusText?: string, reason?: string): string;
+/** The methods `host.fetch` will carry. */
+export declare const HOST_FETCH_METHODS: readonly HostFetchMethod[];
+/**
+ * A method name as one `host.fetch` accepts, or `undefined` if it is not one.
+ *
+ * Answers rather than throws, because the two callers refuse in different words
+ * and to different audiences — one is telling a plugin author that the AI SDK
+ * asked for something impossible, the other is a bridge reporting its own bug —
+ * and a shared throw would have flattened both into one message.
+ */
+export declare function hostFetchMethod(method: string | undefined): HostFetchMethod | undefined;
+/**
+ * Headers as the plain lower-cased record `HostFetchInit.headers` takes.
+ *
+ * A `Headers` instance has already lower-cased its names and joined repeats,
+ * which is the behaviour to want: the host's header handling carries one value
+ * per name. Lower-casing again is free and makes the guarantee local.
+ */
+export declare function headersToRecord(headers: Headers): Record<string, string>;
+//# sourceMappingURL=plugin.http.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.http.d.ts","sourceRoot":"","sources":["../src/plugin.http.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AACxD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAqBzD;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAE/D;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,EAAE,IAAI,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,OAAO,GAAG,MAAM,GAAG,SAAS,CAW9G;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAOlF;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,eAAe,CAMnE;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAE3F;AAED,2CAA2C;AAC3C,eAAO,MAAM,kBAAkB,EAAE,SAAS,eAAe,EAAsD,CAAC;AAEhH;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,eAAe,GAAG,SAAS,CAIvF;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAQxE"}