modeldispatcher-client 0.6.0

package/dist/client.d.ts

@@ -0,0 +1,57 @@
+/**
+ * {@link GatewayClient}: the facade a Vercel frontend calls.
+ *
+ * It composes the interceptor chain once (App Check → Auth → retry → timeout →
+ * fetch), then `dispatch` runs a request through it and hands the final
+ * response to the {@link decodeOutcome} decoder. Every transport failure is
+ * normalised into a `{ kind: "network" }` outcome, so callers only ever
+ * `switch` on {@link DispatchOutcome.kind} — no thrown errors escape `dispatch`.
+ */
+import { GatewayEventBus } from "./events.js";
+import { type RetryOptions } from "./interceptors/retry.js";
+import type { AppCheckTokenProvider, AuthTokenProvider, DispatchOutcome, GatewayResult } from "./types.js";
+/** Construction options for {@link GatewayClient}. */
+export interface GatewayClientOptions {
+    /** Endpoint the wrapper is deployed at. Defaults to `"/api/gateway"`. */
+    endpoint?: string;
+    /** Per-attempt timeout in milliseconds. Defaults to `15000`. */
+    timeoutMs?: number;
+    /** Firebase App Check token supplier. Omit to disable the header (dev). */
+    appCheckTokenProvider?: AppCheckTokenProvider;
+    /**
+     * Firebase Auth ID token supplier. Omit to disable the header (dev only —
+     * the wrapper's default `MD_AUTH_MODE=enforce` will reject every request
+     * with `401` without it; see `_lib/auth.py`).
+     */
+    authTokenProvider?: AuthTokenProvider;
+    /** Retry/backoff tuning and injected clock (for tests). */
+    retry?: RetryOptions;
+    /** Shared event bus; a fresh one is created when omitted. */
+    bus?: GatewayEventBus;
+    /** Injectable `fetch` (defaults to the global). */
+    fetchImpl?: typeof fetch;
+}
+/** Per-call overrides for {@link GatewayClient.dispatch}. */
+export interface DispatchOptions {
+    /** Caller cancellation, merged with the internal timeout. */
+    signal?: AbortSignal;
+    /** Extra headers to merge onto this request. */
+    headers?: Record<string, string>;
+}
+/** Resilient client for the ModelDispatcher gateway endpoint. */
+export declare class GatewayClient {
+    #private;
+    /** Event bus other subscribers (e.g. the wizard host) can listen on. */
+    readonly bus: GatewayEventBus;
+    constructor(options?: GatewayClientOptions);
+    /**
+     * Dispatch a request body to the gateway and return a typed outcome.
+     *
+     * Never rejects: transport failures surface as `{ kind: "network" }`.
+     *
+     * @typeParam T - Expected success shape (defaults to {@link GatewayResult}).
+     */
+    dispatch<T = GatewayResult>(body: unknown, options?: DispatchOptions): Promise<DispatchOutcome<T>>;
+}
+/** Convenience factory mirroring the constructor. */
+export declare function createGatewayClient(options?: GatewayClientOptions): GatewayClient;

package/dist/client.js

@@ -0,0 +1,90 @@
+/**
+ * {@link GatewayClient}: the facade a Vercel frontend calls.
+ *
+ * It composes the interceptor chain once (App Check → Auth → retry → timeout →
+ * fetch), then `dispatch` runs a request through it and hands the final
+ * response to the {@link decodeOutcome} decoder. Every transport failure is
+ * normalised into a `{ kind: "network" }` outcome, so callers only ever
+ * `switch` on {@link DispatchOutcome.kind} — no thrown errors escape `dispatch`.
+ */
+import { GatewayEventBus } from "./events.js";
+import { appCheckInterceptor } from "./interceptors/appcheck.js";
+import { authInterceptor } from "./interceptors/auth.js";
+import { decodeOutcome } from "./interceptors/handoff.js";
+import { compose, } from "./interceptors/interceptor.js";
+import { retryInterceptor } from "./interceptors/retry.js";
+import { TimeoutError, timeoutInterceptor } from "./interceptors/timeout.js";
+const DEFAULT_ENDPOINT = "/api/gateway";
+const DEFAULT_TIMEOUT_MS = 15_000;
+function classifyNetworkError(error) {
+    if (error instanceof TimeoutError) {
+        return { kind: "timeout", message: error.message, cause: error };
+    }
+    // `fetch` throws a TypeError for DNS/connection failures (offline).
+    if (error instanceof TypeError) {
+        return { kind: "offline", message: error.message, cause: error };
+    }
+    const kind = "unknown";
+    const message = error instanceof Error ? error.message : String(error);
+    return { kind, message, cause: error };
+}
+/** Resilient client for the ModelDispatcher gateway endpoint. */
+export class GatewayClient {
+    /** Event bus other subscribers (e.g. the wizard host) can listen on. */
+    bus;
+    #endpoint;
+    #timeoutMs;
+    #send;
+    constructor(options = {}) {
+        this.bus = options.bus ?? new GatewayEventBus();
+        this.#endpoint = options.endpoint ?? DEFAULT_ENDPOINT;
+        this.#timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        const fetchImpl = options.fetchImpl ?? globalThis.fetch;
+        const chain = [];
+        if (options.appCheckTokenProvider) {
+            chain.push(appCheckInterceptor(options.appCheckTokenProvider));
+        }
+        if (options.authTokenProvider) {
+            chain.push(authInterceptor(options.authTokenProvider));
+        }
+        chain.push(retryInterceptor(options.retry ?? {}));
+        chain.push(timeoutInterceptor());
+        const terminal = (config) => fetchImpl(config.url, {
+            method: config.method,
+            headers: config.headers,
+            body: JSON.stringify(config.body),
+            ...(config.signal ? { signal: config.signal } : {}),
+        });
+        this.#send = compose(chain, terminal);
+    }
+    /**
+     * Dispatch a request body to the gateway and return a typed outcome.
+     *
+     * Never rejects: transport failures surface as `{ kind: "network" }`.
+     *
+     * @typeParam T - Expected success shape (defaults to {@link GatewayResult}).
+     */
+    async dispatch(body, options = {}) {
+        const config = {
+            url: this.#endpoint,
+            method: "POST",
+            headers: { "content-type": "application/json", ...options.headers },
+            body,
+            timeoutMs: this.#timeoutMs,
+            ...(options.signal ? { signal: options.signal } : {}),
+        };
+        let response;
+        try {
+            response = await this.#send(config);
+        }
+        catch (error) {
+            return { kind: "network", error: classifyNetworkError(error) };
+        }
+        return decodeOutcome(response, this.bus);
+    }
+}
+/** Convenience factory mirroring the constructor. */
+export function createGatewayClient(options = {}) {
+    return new GatewayClient(options);
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

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

package/dist/events.d.ts

@@ -0,0 +1,44 @@
+/**
+ * A tiny, strongly-typed event bus (Observer pattern).
+ *
+ * It exists to decouple *detecting* a Stage-2 handoff (deep inside the response
+ * pipeline) from *reacting* to it (a wizard component that may live anywhere in
+ * the tree). The interceptor publishes; {@link GatewayEventBus} fans the event
+ * out to every subscriber without either side knowing about the other.
+ */
+import type { Handoff } from "./types.js";
+/** Payload emitted whenever the gateway returns a structured handoff. */
+export interface HandoffEvent {
+    /** HTTP status the gateway chose: `402` (budget wall) or `429` (rate window). */
+    readonly status: number;
+    /** The decoded handoff instruction. */
+    readonly handoff: Handoff;
+}
+/** The map of event names to their payload types. */
+export interface GatewayEventMap {
+    handoff: HandoffEvent;
+}
+/** Unsubscribe handle returned by {@link GatewayEventBus.on}. */
+export type Unsubscribe = () => void;
+/** Listener signature for a given event. */
+export type Listener<E extends keyof GatewayEventMap> = (event: GatewayEventMap[E]) => void;
+/**
+ * Synchronous, in-memory pub/sub for gateway events.
+ *
+ * Listener exceptions are swallowed (and forwarded to `onListenerError` when
+ * provided) so one bad subscriber can never break delivery to the others.
+ */
+export declare class GatewayEventBus {
+    #private;
+    constructor(onListenerError?: (error: unknown) => void);
+    /**
+     * Subscribe to an event.
+     *
+     * @returns A function that removes this exact listener when called.
+     */
+    on<E extends keyof GatewayEventMap>(event: E, listener: Listener<E>): Unsubscribe;
+    /** Publish an event to every current subscriber. */
+    emit<E extends keyof GatewayEventMap>(event: E, payload: GatewayEventMap[E]): void;
+    /** Remove all listeners (useful in test teardown). */
+    clear(): void;
+}

package/dist/events.js

@@ -0,0 +1,48 @@
+/**
+ * A tiny, strongly-typed event bus (Observer pattern).
+ *
+ * It exists to decouple *detecting* a Stage-2 handoff (deep inside the response
+ * pipeline) from *reacting* to it (a wizard component that may live anywhere in
+ * the tree). The interceptor publishes; {@link GatewayEventBus} fans the event
+ * out to every subscriber without either side knowing about the other.
+ */
+/**
+ * Synchronous, in-memory pub/sub for gateway events.
+ *
+ * Listener exceptions are swallowed (and forwarded to `onListenerError` when
+ * provided) so one bad subscriber can never break delivery to the others.
+ */
+export class GatewayEventBus {
+    #listeners = { handoff: new Set() };
+    #onListenerError;
+    constructor(onListenerError = () => { }) {
+        this.#onListenerError = onListenerError;
+    }
+    /**
+     * Subscribe to an event.
+     *
+     * @returns A function that removes this exact listener when called.
+     */
+    on(event, listener) {
+        this.#listeners[event].add(listener);
+        return () => {
+            this.#listeners[event].delete(listener);
+        };
+    }
+    /** Publish an event to every current subscriber. */
+    emit(event, payload) {
+        for (const listener of this.#listeners[event]) {
+            try {
+                listener(payload);
+            }
+            catch (error) {
+                this.#onListenerError(error);
+            }
+        }
+    }
+    /** Remove all listeners (useful in test teardown). */
+    clear() {
+        this.#listeners.handoff.clear();
+    }
+}
+//# sourceMappingURL=events.js.map

package/dist/events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.js","sourceRoot":"","sources":["../src/events.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAyBH;;;;;GAKG;AACH,MAAM,OAAO,eAAe;IACjB,UAAU,GAEf,EAAE,OAAO,EAAE,IAAI,GAAG,EAAE,EAAE,CAAC;IAElB,gBAAgB,CAA2B;IAEpD,YAAY,kBAA4C,GAAG,EAAE,GAAE,CAAC;QAC9D,IAAI,CAAC,gBAAgB,GAAG,eAAe,CAAC;IAC1C,CAAC;IAED;;;;OAIG;IACH,EAAE,CAAkC,KAAQ,EAAE,QAAqB;QACjE,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QACrC,OAAO,GAAG,EAAE;YACV,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;QAC1C,CAAC,CAAC;IACJ,CAAC;IAED,oDAAoD;IACpD,IAAI,CAAkC,KAAQ,EAAE,OAA2B;QACzE,KAAK,MAAM,QAAQ,IAAI,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,EAAE,CAAC;YAC9C,IAAI,CAAC;gBACH,QAAQ,CAAC,OAAO,CAAC,CAAC;YACpB,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,IAAI,CAAC,gBAAgB,CAAC,KAAK,CAAC,CAAC;YAC/B,CAAC;QACH,CAAC;IACH,CAAC;IAED,sDAAsD;IACtD,KAAK;QACH,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;IAClC,CAAC;CACF"}

package/dist/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * `modeldispatcher-client` — resilient TypeScript client for the
+ * ModelDispatcher AI gateway.
+ *
+ * Public surface: construct a {@link GatewayClient} with
+ * {@link createGatewayClient}, `dispatch` request bodies, and `switch` on the
+ * returned {@link DispatchOutcome}. React apps use `useGateway` from the
+ * `modeldispatcher-client/react` subpath. All resilience — timeouts, 5xx
+ * backoff, and 402/429 key-wizard handoff decoding — is built in.
+ */
+export { GatewayClient, createGatewayClient } from "./client.js";
+export type { GatewayClientOptions, DispatchOptions } from "./client.js";
+export { GatewayEventBus } from "./events.js";
+export type { GatewayEventMap, HandoffEvent, Listener, Unsubscribe, } from "./events.js";
+export { compose } from "./interceptors/interceptor.js";
+export type { GatewayRequestConfig, Interceptor, Send } from "./interceptors/interceptor.js";
+export { appCheckInterceptor, APP_CHECK_HEADER } from "./interceptors/appcheck.js";
+export { authInterceptor, AUTHORIZATION_HEADER } from "./interceptors/auth.js";
+export { timeoutInterceptor, TimeoutError } from "./interceptors/timeout.js";
+export { retryInterceptor, backoffDelayMs, DEFAULT_RETRY_POLICY, REAL_SCHEDULER, } from "./interceptors/retry.js";
+export type { RetryPolicy, RetryOptions } from "./interceptors/retry.js";
+export { decodeOutcome, isHandoffPayload, HANDOFF_ACTIONS, } from "./interceptors/handoff.js";
+export type { Attempt, AppCheckTokenProvider, AuthTokenProvider, DispatchOutcome, GatewayError, GatewayResult, Handoff, HandoffAction, NetworkError, NetworkErrorKind, Scheduler, Step, Usage, } from "./types.js";

package/dist/index.js

@@ -0,0 +1,19 @@
+/**
+ * `modeldispatcher-client` — resilient TypeScript client for the
+ * ModelDispatcher AI gateway.
+ *
+ * Public surface: construct a {@link GatewayClient} with
+ * {@link createGatewayClient}, `dispatch` request bodies, and `switch` on the
+ * returned {@link DispatchOutcome}. React apps use `useGateway` from the
+ * `modeldispatcher-client/react` subpath. All resilience — timeouts, 5xx
+ * backoff, and 402/429 key-wizard handoff decoding — is built in.
+ */
+export { GatewayClient, createGatewayClient } from "./client.js";
+export { GatewayEventBus } from "./events.js";
+export { compose } from "./interceptors/interceptor.js";
+export { appCheckInterceptor, APP_CHECK_HEADER } from "./interceptors/appcheck.js";
+export { authInterceptor, AUTHORIZATION_HEADER } from "./interceptors/auth.js";
+export { timeoutInterceptor, TimeoutError } from "./interceptors/timeout.js";
+export { retryInterceptor, backoffDelayMs, DEFAULT_RETRY_POLICY, REAL_SCHEDULER, } from "./interceptors/retry.js";
+export { decodeOutcome, isHandoffPayload, HANDOFF_ACTIONS, } from "./interceptors/handoff.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,aAAa,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAGjE,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAQ9C,OAAO,EAAE,OAAO,EAAE,MAAM,+BAA+B,CAAC;AAGxD,OAAO,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAC;AACnF,OAAO,EAAE,eAAe,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAC/E,OAAO,EAAE,kBAAkB,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAC7E,OAAO,EACL,gBAAgB,EAChB,cAAc,EACd,oBAAoB,EACpB,cAAc,GACf,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EACL,aAAa,EACb,gBAAgB,EAChB,eAAe,GAChB,MAAM,2BAA2B,CAAC"}

package/dist/interceptors/appcheck.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Firebase App Check interceptor (request side).
+ *
+ * Mints/attaches the attestation token the Vercel Python wrapper verifies before
+ * it will invoke the gateway. The token *provider* is injected rather than
+ * importing the Firebase SDK directly, so this package carries no hard Firebase
+ * dependency and stays trivially testable — the app wires
+ * `() => getToken(appCheck).then(r => r.token)` at construction time.
+ */
+import type { AppCheckTokenProvider } from "../types.js";
+import type { Interceptor } from "./interceptor.js";
+/** HTTP header the wrapper reads (matches `firebase_admin.app_check`). */
+export declare const APP_CHECK_HEADER = "X-Firebase-AppCheck";
+/**
+ * Build the interceptor that stamps every request with an App Check token.
+ *
+ * A `null` token (provider opted out, or dev bypass) is simply not attached;
+ * the wrapper then decides whether to reject based on its own environment.
+ */
+export declare function appCheckInterceptor(provider: AppCheckTokenProvider): Interceptor;

package/dist/interceptors/appcheck.js

@@ -0,0 +1,29 @@
+/**
+ * Firebase App Check interceptor (request side).
+ *
+ * Mints/attaches the attestation token the Vercel Python wrapper verifies before
+ * it will invoke the gateway. The token *provider* is injected rather than
+ * importing the Firebase SDK directly, so this package carries no hard Firebase
+ * dependency and stays trivially testable — the app wires
+ * `() => getToken(appCheck).then(r => r.token)` at construction time.
+ */
+/** HTTP header the wrapper reads (matches `firebase_admin.app_check`). */
+export const APP_CHECK_HEADER = "X-Firebase-AppCheck";
+/**
+ * Build the interceptor that stamps every request with an App Check token.
+ *
+ * A `null` token (provider opted out, or dev bypass) is simply not attached;
+ * the wrapper then decides whether to reject based on its own environment.
+ */
+export function appCheckInterceptor(provider) {
+    return {
+        async intercept(config, next) {
+            const token = await provider();
+            if (token) {
+                config.headers[APP_CHECK_HEADER] = token;
+            }
+            return next(config);
+        },
+    };
+}
+//# sourceMappingURL=appcheck.js.map

package/dist/interceptors/appcheck.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"appcheck.js","sourceRoot":"","sources":["../../src/interceptors/appcheck.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAKH,0EAA0E;AAC1E,MAAM,CAAC,MAAM,gBAAgB,GAAG,qBAAqB,CAAC;AAEtD;;;;;GAKG;AACH,MAAM,UAAU,mBAAmB,CAAC,QAA+B;IACjE,OAAO;QACL,KAAK,CAAC,SAAS,CAAC,MAA4B,EAAE,IAAU;YACtD,MAAM,KAAK,GAAG,MAAM,QAAQ,EAAE,CAAC;YAC/B,IAAI,KAAK,EAAE,CAAC;gBACV,MAAM,CAAC,OAAO,CAAC,gBAAgB,CAAC,GAAG,KAAK,CAAC;YAC3C,CAAC;YACD,OAAO,IAAI,CAAC,MAAM,CAAC,CAAC;QACtB,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/interceptors/auth.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Firebase Auth interceptor (request side).
+ *
+ * Mints/attaches the ID token the Vercel Python wrapper verifies to derive an
+ * *authoritative* tenant id (see `_lib/auth.py`). Mirrors
+ * {@link appCheckInterceptor} exactly: the token provider is injected rather
+ * than importing the Firebase SDK directly, so this package carries no hard
+ * Firebase dependency. Without this header, the wrapper's `MD_AUTH_MODE=enforce`
+ * default rejects the request with `401` before the gateway ever runs.
+ */
+import type { AuthTokenProvider } from "../types.js";
+import type { Interceptor } from "./interceptor.js";
+/** HTTP header the wrapper reads the bearer token from. */
+export declare const AUTHORIZATION_HEADER = "Authorization";
+/**
+ * Build the interceptor that stamps every request with a Firebase Auth ID token.
+ *
+ * A `null` token (provider opted out, or dev bypass) is simply not attached;
+ * the wrapper then decides whether to reject based on its own `MD_AUTH_MODE`.
+ */
+export declare function authInterceptor(provider: AuthTokenProvider): Interceptor;

package/dist/interceptors/auth.js

@@ -0,0 +1,30 @@
+/**
+ * Firebase Auth interceptor (request side).
+ *
+ * Mints/attaches the ID token the Vercel Python wrapper verifies to derive an
+ * *authoritative* tenant id (see `_lib/auth.py`). Mirrors
+ * {@link appCheckInterceptor} exactly: the token provider is injected rather
+ * than importing the Firebase SDK directly, so this package carries no hard
+ * Firebase dependency. Without this header, the wrapper's `MD_AUTH_MODE=enforce`
+ * default rejects the request with `401` before the gateway ever runs.
+ */
+/** HTTP header the wrapper reads the bearer token from. */
+export const AUTHORIZATION_HEADER = "Authorization";
+/**
+ * Build the interceptor that stamps every request with a Firebase Auth ID token.
+ *
+ * A `null` token (provider opted out, or dev bypass) is simply not attached;
+ * the wrapper then decides whether to reject based on its own `MD_AUTH_MODE`.
+ */
+export function authInterceptor(provider) {
+    return {
+        async intercept(config, next) {
+            const token = await provider();
+            if (token) {
+                config.headers[AUTHORIZATION_HEADER] = `Bearer ${token}`;
+            }
+            return next(config);
+        },
+    };
+}
+//# sourceMappingURL=auth.js.map

package/dist/interceptors/auth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.js","sourceRoot":"","sources":["../../src/interceptors/auth.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAKH,2DAA2D;AAC3D,MAAM,CAAC,MAAM,oBAAoB,GAAG,eAAe,CAAC;AAEpD;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAAC,QAA2B;IACzD,OAAO;QACL,KAAK,CAAC,SAAS,CAAC,MAA4B,EAAE,IAAU;YACtD,MAAM,KAAK,GAAG,MAAM,QAAQ,EAAE,CAAC;YAC/B,IAAI,KAAK,EAAE,CAAC;gBACV,MAAM,CAAC,OAAO,CAAC,oBAAoB,CAAC,GAAG,UAAU,KAAK,EAAE,CAAC;YAC3D,CAAC;YACD,OAAO,IAAI,CAAC,MAAM,CAAC,CAAC;QACtB,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/interceptors/handoff.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Response decoder: HTTP {@link Response} → {@link DispatchOutcome}.
+ *
+ * This is where the gateway's `to_payload()` contract is interpreted. A `2xx`
+ * body becomes `{ kind: "ok" }`; a non-OK body whose `action` names a known
+ * handoff becomes `{ kind: "handoff" }` *and* is published on the event bus so a
+ * decoupled wizard host can react; anything else becomes `{ kind: "error" }`.
+ * Runs after the retry interceptor, so only *final* responses reach it.
+ */
+import type { GatewayEventBus } from "../events.js";
+import type { DispatchOutcome, Handoff, HandoffAction } from "../types.js";
+/** The actions this client knows how to surface. */
+export declare const HANDOFF_ACTIONS: readonly HandoffAction[];
+/** Type guard: does an arbitrary parsed body match the {@link Handoff} shape? */
+export declare function isHandoffPayload(body: unknown): body is Handoff;
+/**
+ * Decode a final response into a typed outcome.
+ *
+ * @param response - The response emerging from the interceptor chain.
+ * @param bus - Event bus a handoff is published on before returning.
+ */
+export declare function decodeOutcome<T>(response: Response, bus: GatewayEventBus): Promise<DispatchOutcome<T>>;

package/dist/interceptors/handoff.js

@@ -0,0 +1,73 @@
+/**
+ * Response decoder: HTTP {@link Response} → {@link DispatchOutcome}.
+ *
+ * This is where the gateway's `to_payload()` contract is interpreted. A `2xx`
+ * body becomes `{ kind: "ok" }`; a non-OK body whose `action` names a known
+ * handoff becomes `{ kind: "handoff" }` *and* is published on the event bus so a
+ * decoupled wizard host can react; anything else becomes `{ kind: "error" }`.
+ * Runs after the retry interceptor, so only *final* responses reach it.
+ */
+/** The actions this client knows how to surface. */
+export const HANDOFF_ACTIONS = [
+    "trigger_key_wizard",
+    "upgrade_plan",
+    "retry_later",
+];
+function isRecord(value) {
+    return typeof value === "object" && value !== null;
+}
+/** Type guard: does an arbitrary parsed body match the {@link Handoff} shape? */
+export function isHandoffPayload(body) {
+    if (!isRecord(body))
+        return false;
+    return (typeof body["error"] === "string" &&
+        typeof body["provider"] === "string" &&
+        typeof body["action"] === "string" &&
+        HANDOFF_ACTIONS.includes(body["action"]));
+}
+/** Parse a JSON body without throwing; returns `undefined` on empty/invalid. */
+async function readJson(response) {
+    const text = await response.text();
+    if (!text)
+        return undefined;
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+}
+function toGatewayError(body, status) {
+    if (isRecord(body) && typeof body["error"] === "string") {
+        const detail = body["detail"];
+        return {
+            error: body["error"],
+            ...(typeof detail === "string" ? { detail } : {}),
+        };
+    }
+    return { error: "unexpected_response", detail: `HTTP ${status}` };
+}
+/**
+ * Decode a final response into a typed outcome.
+ *
+ * @param response - The response emerging from the interceptor chain.
+ * @param bus - Event bus a handoff is published on before returning.
+ */
+export async function decodeOutcome(response, bus) {
+    const body = await readJson(response);
+    if (response.ok) {
+        return { kind: "ok", result: body };
+    }
+    if (isHandoffPayload(body)) {
+        const handoff = {
+            error: body.error,
+            provider: body.provider,
+            action: body.action,
+            ...(body.detail !== undefined ? { detail: body.detail } : {}),
+        };
+        bus.emit("handoff", { status: response.status, handoff });
+        return { kind: "handoff", status: response.status, handoff };
+    }
+    return { kind: "error", status: response.status, error: toGatewayError(body, response.status) };
+}
+//# sourceMappingURL=handoff.js.map

package/dist/interceptors/handoff.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"handoff.js","sourceRoot":"","sources":["../../src/interceptors/handoff.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAUH,oDAAoD;AACpD,MAAM,CAAC,MAAM,eAAe,GAA6B;IACvD,oBAAoB;IACpB,cAAc;IACd,aAAa;CACd,CAAC;AAEF,SAAS,QAAQ,CAAC,KAAc;IAC9B,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,CAAC;AACrD,CAAC;AAED,iFAAiF;AACjF,MAAM,UAAU,gBAAgB,CAAC,IAAa;IAC5C,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC;QAAE,OAAO,KAAK,CAAC;IAClC,OAAO,CACL,OAAO,IAAI,CAAC,OAAO,CAAC,KAAK,QAAQ;QACjC,OAAO,IAAI,CAAC,UAAU,CAAC,KAAK,QAAQ;QACpC,OAAO,IAAI,CAAC,QAAQ,CAAC,KAAK,QAAQ;QACjC,eAAqC,CAAC,QAAQ,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAChE,CAAC;AACJ,CAAC;AAED,gFAAgF;AAChF,KAAK,UAAU,QAAQ,CAAC,QAAkB;IACxC,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC;IACnC,IAAI,CAAC,IAAI;QAAE,OAAO,SAAS,CAAC;IAC5B,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAY,CAAC;IACrC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC;AAED,SAAS,cAAc,CAAC,IAAa,EAAE,MAAc;IACnD,IAAI,QAAQ,CAAC,IAAI,CAAC,IAAI,OAAO,IAAI,CAAC,OAAO,CAAC,KAAK,QAAQ,EAAE,CAAC;QACxD,MAAM,MAAM,GAAG,IAAI,CAAC,QAAQ,CAAC,CAAC;QAC9B,OAAO;YACL,KAAK,EAAE,IAAI,CAAC,OAAO,CAAC;YACpB,GAAG,CAAC,OAAO,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAClD,CAAC;IACJ,CAAC;IACD,OAAO,EAAE,KAAK,EAAE,qBAAqB,EAAE,MAAM,EAAE,QAAQ,MAAM,EAAE,EAAE,CAAC;AACpE,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,QAAkB,EAClB,GAAoB;IAEpB,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,QAAQ,CAAC,CAAC;IAEtC,IAAI,QAAQ,CAAC,EAAE,EAAE,CAAC;QAChB,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,IAAS,EAAE,CAAC;IAC3C,CAAC;IAED,IAAI,gBAAgB,CAAC,IAAI,CAAC,EAAE,CAAC;QAC3B,MAAM,OAAO,GAAY;YACvB,KAAK,EAAE,IAAI,CAAC,KAAK;YACjB,QAAQ,EAAE,IAAI,CAAC,QAAQ;YACvB,MAAM,EAAE,IAAI,CAAC,MAAM;YACnB,GAAG,CAAC,IAAI,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAC9D,CAAC;QACF,GAAG,CAAC,IAAI,CAAC,SAAS,EAAE,EAAE,MAAM,EAAE,QAAQ,CAAC,MAAM,EAAE,OAAO,EAAE,CAAC,CAAC;QAC1D,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,CAAC,MAAM,EAAE,OAAO,EAAE,CAAC;IAC/D,CAAC;IAED,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,QAAQ,CAAC,MAAM,EAAE,KAAK,EAAE,cAAc,CAAC,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;AAClG,CAAC"}

package/dist/interceptors/interceptor.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Interceptor pipeline contracts (Chain of Responsibility).
+ *
+ * Each {@link Interceptor} receives the outgoing request config and a `next`
+ * continuation. It may mutate the config, short-circuit, wrap `next` with
+ * cross-cutting behaviour (timeout, retry), and inspect the resulting response
+ * before returning it. Interceptors are composed as an onion: the first in the
+ * list is the outermost layer.
+ */
+/** The in-flight request description handed down the interceptor chain. */
+export interface GatewayRequestConfig {
+    /** Absolute or app-relative endpoint, e.g. `"/api/gateway"`. */
+    url: string;
+    /** HTTP method; the gateway endpoint is `POST`. */
+    method: string;
+    /** Mutable header bag; interceptors add to it (App Check, content-type). */
+    headers: Record<string, string>;
+    /** JSON-serialisable request body. */
+    body: unknown;
+    /** Per-attempt timeout in milliseconds. */
+    timeoutMs: number;
+    /** Optional caller-supplied cancellation signal, merged with the timeout. */
+    signal?: AbortSignal;
+}
+/** Terminal continuation: performs exactly one transport attempt. */
+export type Send = (config: GatewayRequestConfig) => Promise<Response>;
+/** A single layer of the request/response pipeline. */
+export interface Interceptor {
+    /**
+     * Process the request and return a response.
+     *
+     * @param config - The (mutable) request configuration.
+     * @param next - Continuation invoking the remaining inner layers.
+     */
+    intercept(config: GatewayRequestConfig, next: Send): Promise<Response>;
+}
+/**
+ * Fold a list of interceptors around a terminal {@link Send} into one `Send`.
+ *
+ * The first interceptor becomes the outermost layer, so a list of
+ * `[appcheck, retry, timeout]` yields `appcheck(retry(timeout(fetch)))` — retry
+ * re-drives the timeout+transport on each attempt.
+ */
+export declare function compose(interceptors: readonly Interceptor[], terminal: Send): Send;

package/dist/interceptors/interceptor.js

@@ -0,0 +1,20 @@
+/**
+ * Interceptor pipeline contracts (Chain of Responsibility).
+ *
+ * Each {@link Interceptor} receives the outgoing request config and a `next`
+ * continuation. It may mutate the config, short-circuit, wrap `next` with
+ * cross-cutting behaviour (timeout, retry), and inspect the resulting response
+ * before returning it. Interceptors are composed as an onion: the first in the
+ * list is the outermost layer.
+ */
+/**
+ * Fold a list of interceptors around a terminal {@link Send} into one `Send`.
+ *
+ * The first interceptor becomes the outermost layer, so a list of
+ * `[appcheck, retry, timeout]` yields `appcheck(retry(timeout(fetch)))` — retry
+ * re-drives the timeout+transport on each attempt.
+ */
+export function compose(interceptors, terminal) {
+    return interceptors.reduceRight((next, interceptor) => (config) => interceptor.intercept(config, next), terminal);
+}
+//# sourceMappingURL=interceptor.js.map

package/dist/interceptors/interceptor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"interceptor.js","sourceRoot":"","sources":["../../src/interceptors/interceptor.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAgCH;;;;;;GAMG;AACH,MAAM,UAAU,OAAO,CAAC,YAAoC,EAAE,QAAc;IAC1E,OAAO,YAAY,CAAC,WAAW,CAC7B,CAAC,IAAI,EAAE,WAAW,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,WAAW,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,CAAC,EACtE,QAAQ,CACT,CAAC;AACJ,CAAC"}

package/dist/interceptors/retry.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Retry interceptor with exponential backoff (Policy object pattern).
+ *
+ * Re-issues the request when the response status is in
+ * {@link RetryPolicy.retryableStatuses} — the 5xx family — sleeping
+ * `min(maxDelayMs, baseDelayMs * 2 ** attempt)` between tries, optionally with
+ * full jitter to avoid a thundering herd. It deliberately does **not** retry
+ * `402`/`429`: those are structured quota handoffs that must reach the UI intact,
+ * not transient faults to paper over. Transport errors thrown by inner layers
+ * (e.g. a timeout) propagate unchanged so the client can classify them.
+ */
+import type { Scheduler } from "../types.js";
+import type { Interceptor } from "./interceptor.js";
+/** Tunable backoff parameters. */
+export interface RetryPolicy {
+    /** Maximum *additional* attempts after the first (e.g. `3`). */
+    readonly maxRetries: number;
+    /** Base delay in milliseconds (e.g. `250`). */
+    readonly baseDelayMs: number;
+    /** Upper bound on any single backoff sleep. */
+    readonly maxDelayMs: number;
+    /** Apply full jitter (`random(0, delay)`) when `true`. */
+    readonly jitter: boolean;
+    /** Statuses worth retrying. Never include `402`/`429`. */
+    readonly retryableStatuses: readonly number[];
+}
+/** Sensible defaults for a Vercel ↔ serverless-Python round trip. */
+export declare const DEFAULT_RETRY_POLICY: RetryPolicy;
+/** Real-time scheduler backing the default client. */
+export declare const REAL_SCHEDULER: Scheduler;
+/**
+ * Compute the backoff for a given zero-based attempt index.
+ *
+ * @param policy - The active {@link RetryPolicy}.
+ * @param attempt - Number of retries already performed (0 for the first retry).
+ * @param random - Source of `[0, 1)` randomness (injected for deterministic tests).
+ */
+export declare function backoffDelayMs(policy: RetryPolicy, attempt: number, random?: () => number): number;
+/** Options for {@link retryInterceptor}. */
+export interface RetryOptions {
+    readonly policy?: RetryPolicy;
+    readonly scheduler?: Scheduler;
+    readonly random?: () => number;
+}
+/** Build the backoff/retry {@link Interceptor}. */
+export declare function retryInterceptor(options?: RetryOptions): Interceptor;