modeldispatcher-client 0.6.0

package/dist/interceptors/retry.js

@@ -0,0 +1,56 @@
+/**
+ * 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.
+ */
+/** Sensible defaults for a Vercel ↔ serverless-Python round trip. */
+export const DEFAULT_RETRY_POLICY = {
+    maxRetries: 3,
+    baseDelayMs: 250,
+    maxDelayMs: 4_000,
+    jitter: true,
+    retryableStatuses: [500, 502, 503, 504],
+};
+/** Real-time scheduler backing the default client. */
+export const REAL_SCHEDULER = {
+    sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+    now: () => Date.now(),
+};
+/**
+ * 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 function backoffDelayMs(policy, attempt, random = Math.random) {
+    const uncapped = policy.baseDelayMs * 2 ** attempt;
+    const capped = Math.min(policy.maxDelayMs, uncapped);
+    return policy.jitter ? Math.floor(random() * capped) : capped;
+}
+/** Build the backoff/retry {@link Interceptor}. */
+export function retryInterceptor(options = {}) {
+    const policy = options.policy ?? DEFAULT_RETRY_POLICY;
+    const scheduler = options.scheduler ?? REAL_SCHEDULER;
+    const random = options.random ?? Math.random;
+    return {
+        async intercept(config, next) {
+            let response = await next(config);
+            let attempt = 0;
+            while (policy.retryableStatuses.includes(response.status) &&
+                attempt < policy.maxRetries) {
+                await scheduler.sleep(backoffDelayMs(policy, attempt, random));
+                attempt += 1;
+                response = await next(config);
+            }
+            return response;
+        },
+    };
+}
+//# sourceMappingURL=retry.js.map

package/dist/interceptors/retry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry.js","sourceRoot":"","sources":["../../src/interceptors/retry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAmBH,qEAAqE;AACrE,MAAM,CAAC,MAAM,oBAAoB,GAAgB;IAC/C,UAAU,EAAE,CAAC;IACb,WAAW,EAAE,GAAG;IAChB,UAAU,EAAE,KAAK;IACjB,MAAM,EAAE,IAAI;IACZ,iBAAiB,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC;CACxC,CAAC;AAEF,sDAAsD;AACtD,MAAM,CAAC,MAAM,cAAc,GAAc;IACvC,KAAK,EAAE,CAAC,EAAU,EAAE,EAAE,CAAC,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;IACxE,GAAG,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE;CACtB,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,UAAU,cAAc,CAC5B,MAAmB,EACnB,OAAe,EACf,SAAuB,IAAI,CAAC,MAAM;IAElC,MAAM,QAAQ,GAAG,MAAM,CAAC,WAAW,GAAG,CAAC,IAAI,OAAO,CAAC;IACnD,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,UAAU,EAAE,QAAQ,CAAC,CAAC;IACrD,OAAO,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC;AAChE,CAAC;AASD,mDAAmD;AACnD,MAAM,UAAU,gBAAgB,CAAC,UAAwB,EAAE;IACzD,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,oBAAoB,CAAC;IACtD,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,cAAc,CAAC;IACtD,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,IAAI,CAAC,MAAM,CAAC;IAE7C,OAAO;QACL,KAAK,CAAC,SAAS,CAAC,MAA4B,EAAE,IAAU;YACtD,IAAI,QAAQ,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,CAAC;YAClC,IAAI,OAAO,GAAG,CAAC,CAAC;YAEhB,OACE,MAAM,CAAC,iBAAiB,CAAC,QAAQ,CAAC,QAAQ,CAAC,MAAM,CAAC;gBAClD,OAAO,GAAG,MAAM,CAAC,UAAU,EAC3B,CAAC;gBACD,MAAM,SAAS,CAAC,KAAK,CAAC,cAAc,CAAC,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC,CAAC;gBAC/D,OAAO,IAAI,CAAC,CAAC;gBACb,QAAQ,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,CAAC;YAChC,CAAC;YAED,OAAO,QAAQ,CAAC;QAClB,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/interceptors/timeout.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Timeout interceptor.
+ *
+ * Arms an {@link AbortController} that fires after `config.timeoutMs`, and also
+ * forwards any caller-supplied `config.signal`, so a slow serverless cold-start
+ * cannot hang the UI. When the deadline trips it re-labels the resulting
+ * `AbortError` as a {@link TimeoutError} (an external cancellation keeps its
+ * original error), which the client maps to a `{ kind: "network" }` outcome.
+ */
+import type { Interceptor } from "./interceptor.js";
+/** Thrown when a single transport attempt exceeds its deadline. */
+export declare class TimeoutError extends Error {
+    constructor(timeoutMs: number);
+}
+/** Build the {@link Interceptor} that enforces a per-attempt deadline. */
+export declare function timeoutInterceptor(): Interceptor;

package/dist/interceptors/timeout.js

@@ -0,0 +1,48 @@
+/**
+ * Timeout interceptor.
+ *
+ * Arms an {@link AbortController} that fires after `config.timeoutMs`, and also
+ * forwards any caller-supplied `config.signal`, so a slow serverless cold-start
+ * cannot hang the UI. When the deadline trips it re-labels the resulting
+ * `AbortError` as a {@link TimeoutError} (an external cancellation keeps its
+ * original error), which the client maps to a `{ kind: "network" }` outcome.
+ */
+/** Thrown when a single transport attempt exceeds its deadline. */
+export class TimeoutError extends Error {
+    constructor(timeoutMs) {
+        super(`request exceeded ${timeoutMs}ms timeout`);
+        this.name = "TimeoutError";
+    }
+}
+/** Build the {@link Interceptor} that enforces a per-attempt deadline. */
+export function timeoutInterceptor() {
+    return {
+        async intercept(config, next) {
+            const controller = new AbortController();
+            let timedOut = false;
+            const timer = setTimeout(() => {
+                timedOut = true;
+                controller.abort();
+            }, config.timeoutMs);
+            const external = config.signal;
+            if (external) {
+                if (external.aborted)
+                    controller.abort();
+                else
+                    external.addEventListener("abort", () => controller.abort(), { once: true });
+            }
+            try {
+                return await next({ ...config, signal: controller.signal });
+            }
+            catch (error) {
+                if (timedOut)
+                    throw new TimeoutError(config.timeoutMs);
+                throw error;
+            }
+            finally {
+                clearTimeout(timer);
+            }
+        },
+    };
+}
+//# sourceMappingURL=timeout.js.map

package/dist/interceptors/timeout.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"timeout.js","sourceRoot":"","sources":["../../src/interceptors/timeout.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,mEAAmE;AACnE,MAAM,OAAO,YAAa,SAAQ,KAAK;IACrC,YAAY,SAAiB;QAC3B,KAAK,CAAC,oBAAoB,SAAS,YAAY,CAAC,CAAC;QACjD,IAAI,CAAC,IAAI,GAAG,cAAc,CAAC;IAC7B,CAAC;CACF;AAED,0EAA0E;AAC1E,MAAM,UAAU,kBAAkB;IAChC,OAAO;QACL,KAAK,CAAC,SAAS,CAAC,MAA4B,EAAE,IAAU;YACtD,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;YACzC,IAAI,QAAQ,GAAG,KAAK,CAAC;YACrB,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE;gBAC5B,QAAQ,GAAG,IAAI,CAAC;gBAChB,UAAU,CAAC,KAAK,EAAE,CAAC;YACrB,CAAC,EAAE,MAAM,CAAC,SAAS,CAAC,CAAC;YAErB,MAAM,QAAQ,GAAG,MAAM,CAAC,MAAM,CAAC;YAC/B,IAAI,QAAQ,EAAE,CAAC;gBACb,IAAI,QAAQ,CAAC,OAAO;oBAAE,UAAU,CAAC,KAAK,EAAE,CAAC;;oBACpC,QAAQ,CAAC,gBAAgB,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,UAAU,CAAC,KAAK,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;YACpF,CAAC;YAED,IAAI,CAAC;gBACH,OAAO,MAAM,IAAI,CAAC,EAAE,GAAG,MAAM,EAAE,MAAM,EAAE,UAAU,CAAC,MAAM,EAAE,CAAC,CAAC;YAC9D,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,IAAI,QAAQ;oBAAE,MAAM,IAAI,YAAY,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;gBACvD,MAAM,KAAK,CAAC;YACd,CAAC;oBAAS,CAAC;gBACT,YAAY,CAAC,KAAK,CAAC,CAAC;YACtB,CAAC;QACH,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/react/useGateway.d.ts

@@ -0,0 +1,34 @@
+/**
+ * React binding for {@link GatewayClient}.
+ *
+ * Subscribes to the client's event bus and lifts any `trigger_key_wizard`
+ * handoff into local state, so a component can render the API-key wizard
+ * declaratively without threading the dispatch outcome down through props. The
+ * `dispatch` it returns still yields the typed {@link DispatchOutcome} for
+ * call-site handling — both paths, one decode.
+ */
+import type { GatewayClient, DispatchOptions } from "../client.js";
+import type { DispatchOutcome, GatewayResult, HandoffAction } from "../types.js";
+/** UI-facing snapshot of an active key-wizard handoff. */
+export interface WizardState {
+    readonly provider: string;
+    readonly status: number;
+    readonly action: HandoffAction;
+    readonly detail?: string;
+}
+/** Return value of {@link useGateway}. */
+export interface UseGatewayResult<T> {
+    /** Dispatch a request; resolves to a typed outcome (never rejects). */
+    dispatch: (body: unknown, options?: DispatchOptions) => Promise<DispatchOutcome<T>>;
+    /** Non-null when the gateway asked the UI to open the key wizard. */
+    wizard: WizardState | null;
+    /** Dismiss the wizard (e.g. after the user saves a key). */
+    dismissWizard: () => void;
+}
+/**
+ * Bind a {@link GatewayClient} to React state.
+ *
+ * @param client - A stable client instance (create it once, e.g. in a module or
+ *   a context provider, not inside render).
+ */
+export declare function useGateway<T = GatewayResult>(client: GatewayClient): UseGatewayResult<T>;

package/dist/react/useGateway.js

@@ -0,0 +1,36 @@
+/**
+ * React binding for {@link GatewayClient}.
+ *
+ * Subscribes to the client's event bus and lifts any `trigger_key_wizard`
+ * handoff into local state, so a component can render the API-key wizard
+ * declaratively without threading the dispatch outcome down through props. The
+ * `dispatch` it returns still yields the typed {@link DispatchOutcome} for
+ * call-site handling — both paths, one decode.
+ */
+import { useCallback, useEffect, useState } from "react";
+/**
+ * Bind a {@link GatewayClient} to React state.
+ *
+ * @param client - A stable client instance (create it once, e.g. in a module or
+ *   a context provider, not inside render).
+ */
+export function useGateway(client) {
+    const [wizard, setWizard] = useState(null);
+    useEffect(() => {
+        const unsubscribe = client.bus.on("handoff", ({ status, handoff }) => {
+            if (handoff.action === "trigger_key_wizard") {
+                setWizard({
+                    provider: handoff.provider,
+                    status,
+                    action: handoff.action,
+                    ...(handoff.detail !== undefined ? { detail: handoff.detail } : {}),
+                });
+            }
+        });
+        return unsubscribe;
+    }, [client]);
+    const dispatch = useCallback((body, options) => client.dispatch(body, options), [client]);
+    const dismissWizard = useCallback(() => setWizard(null), []);
+    return { dispatch, wizard, dismissWizard };
+}
+//# sourceMappingURL=useGateway.js.map

package/dist/react/useGateway.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useGateway.js","sourceRoot":"","sources":["../../src/react/useGateway.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AAuBzD;;;;;GAKG;AACH,MAAM,UAAU,UAAU,CACxB,MAAqB;IAErB,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,GAAG,QAAQ,CAAqB,IAAI,CAAC,CAAC;IAE/D,SAAS,CAAC,GAAG,EAAE;QACb,MAAM,WAAW,GAAG,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,SAAS,EAAE,CAAC,EAAE,MAAM,EAAE,OAAO,EAAE,EAAE,EAAE;YACnE,IAAI,OAAO,CAAC,MAAM,KAAK,oBAAoB,EAAE,CAAC;gBAC5C,SAAS,CAAC;oBACR,QAAQ,EAAE,OAAO,CAAC,QAAQ;oBAC1B,MAAM;oBACN,MAAM,EAAE,OAAO,CAAC,MAAM;oBACtB,GAAG,CAAC,OAAO,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;iBACpE,CAAC,CAAC;YACL,CAAC;QACH,CAAC,CAAC,CAAC;QACH,OAAO,WAAW,CAAC;IACrB,CAAC,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC;IAEb,MAAM,QAAQ,GAAG,WAAW,CAC1B,CAAC,IAAa,EAAE,OAAyB,EAAE,EAAE,CAAC,MAAM,CAAC,QAAQ,CAAI,IAAI,EAAE,OAAO,CAAC,EAC/E,CAAC,MAAM,CAAC,CACT,CAAC;IAEF,MAAM,aAAa,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,EAAE,CAAC,CAAC;IAE7D,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,aAAa,EAAE,CAAC;AAC7C,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Public type surface for the ModelDispatcher client.
+ *
+ * These interfaces are the strict, versioned contract between a Vercel frontend
+ * and the packaged Python gateway. The response-side types intentionally mirror
+ * the gateway's `to_payload()` output (see `src/model_dispatcher/exceptions.py`
+ * and `onboarding/handoff.py`): the discriminated {@link DispatchOutcome} is the
+ * TypeScript view of "either a run result, a structured onboarding handoff, a
+ * mapped HTTP error, or a transport failure".
+ */
+/** A handoff action the gateway can instruct the UI to take. */
+export type HandoffAction = "trigger_key_wizard" | "upgrade_plan" | "retry_later";
+/**
+ * The structured Stage-2 onboarding instruction returned by the gateway.
+ *
+ * Serialised form (from the Python `HandoffResponse.to_payload`):
+ * `{"error": "quota_exceeded", "provider": "openai", "action": "trigger_key_wizard"}`.
+ */
+export interface Handoff {
+    /** Machine-readable error code, e.g. `"quota_exceeded"`. */
+    readonly error: string;
+    /** Provider whose limit was hit, so the wizard can pre-select it. */
+    readonly provider: string;
+    /** What the client UI should do next. */
+    readonly action: HandoffAction;
+    /** Optional human-readable explanation for display/logging. */
+    readonly detail?: string;
+}
+/** A non-handoff error body mapped from a `ModelDispatcherError`. */
+export interface GatewayError {
+    /** Stable machine-readable slug, e.g. `"perimeter_violation"`. */
+    readonly error: string;
+    /** Human-readable description, when the backend supplies one. */
+    readonly detail?: string;
+}
+/** Kinds of transport failure that never reached a well-formed HTTP response. */
+export type NetworkErrorKind = "timeout" | "offline" | "retries_exhausted" | "unknown";
+/** A failure to obtain any HTTP response (before status interpretation). */
+export interface NetworkError {
+    readonly kind: NetworkErrorKind;
+    /** Human-readable summary for logging/telemetry. */
+    readonly message: string;
+    /** The underlying thrown value, when one is available. */
+    readonly cause?: unknown;
+}
+/**
+ * The result of a dispatch, as a discriminated union.
+ *
+ * `T` is the shape of a successful gateway run (default {@link GatewayResult}).
+ * Callers narrow on `kind`; there is no other legal way to read the payload.
+ */
+export type DispatchOutcome<T = GatewayResult> = {
+    readonly kind: "ok";
+    readonly result: T;
+} | {
+    readonly kind: "handoff";
+    readonly status: number;
+    readonly handoff: Handoff;
+} | {
+    readonly kind: "error";
+    readonly status: number;
+    readonly error: GatewayError;
+} | {
+    readonly kind: "network";
+    readonly error: NetworkError;
+};
+/** Token usage reported by a completed run. */
+export interface Usage {
+    readonly prompt: number;
+    readonly completion: number;
+    readonly total: number;
+}
+/** One provider attempt within a run step (mirrors the demo trace shape). */
+export interface Attempt {
+    readonly provider: string;
+    readonly error: string | null;
+}
+/** One turn of the agent loop. */
+export interface Step {
+    readonly message: string | null;
+    readonly usage: number;
+    readonly attempts: readonly Attempt[];
+}
+/** Default success shape returned by the reference `/api/gateway` wrapper. */
+export interface GatewayResult {
+    readonly final: string | null;
+    readonly stop_reason: string;
+    readonly complexity: string;
+    readonly usage: Usage;
+    readonly steps: readonly Step[];
+}
+/** Zero-argument async supplier of a Firebase App Check token. */
+export type AppCheckTokenProvider = () => Promise<string | null>;
+/**
+ * Zero-argument async supplier of a Firebase Auth ID token.
+ *
+ * Distinct from {@link AppCheckTokenProvider}: App Check attests the *app*,
+ * this attests the *end user* — the wrapper derives the authoritative tenant
+ * id (and thus quota isolation) from this token's verified `uid`, not from
+ * anything in the request body. See `_lib/auth.py`.
+ */
+export type AuthTokenProvider = () => Promise<string | null>;
+/** Injectable clock/timer seam so retry backoff is deterministic under test. */
+export interface Scheduler {
+    /** Resolve after `ms` milliseconds. */
+    sleep(ms: number): Promise<void>;
+    /** Current epoch milliseconds. */
+    now(): number;
+}

package/dist/types.js

@@ -0,0 +1,12 @@
+/**
+ * Public type surface for the ModelDispatcher client.
+ *
+ * These interfaces are the strict, versioned contract between a Vercel frontend
+ * and the packaged Python gateway. The response-side types intentionally mirror
+ * the gateway's `to_payload()` output (see `src/model_dispatcher/exceptions.py`
+ * and `onboarding/handoff.py`): the discriminated {@link DispatchOutcome} is the
+ * TypeScript view of "either a run result, a structured onboarding handoff, a
+ * mapped HTTP error, or a transport failure".
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG"}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "modeldispatcher-client",
+  "version": "0.6.0",
+  "description": "Resilient TypeScript client for the ModelDispatcher AI gateway: interceptor pipeline with request timeouts, exponential backoff on 5xx, and structured 402/429 key-wizard handoff decoding.",
+  "license": "MIT",
+  "type": "module",
+  "types": "./dist/index.d.ts",
+  "module": "./dist/index.js",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./react": {
+      "types": "./dist/react/useGateway.d.ts",
+      "import": "./dist/react/useGateway.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  },
+  "keywords": [
+    "llm",
+    "gateway",
+    "interceptor",
+    "retry",
+    "backoff",
+    "firebase-app-check",
+    "react"
+  ],
+  "peerDependencies": {
+    "react": ">=18"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/react": "^18.3.0",
+    "react": "^18.3.1",
+    "typescript": "^5.5.0",
+    "vitest": "^2.0.0"
+  }
+}

package/src/client.ts

@@ -0,0 +1,148 @@
+/**
+ * {@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,
+  type GatewayRequestConfig,
+  type Interceptor,
+  type Send,
+} from "./interceptors/interceptor.js";
+import { type RetryOptions, retryInterceptor } from "./interceptors/retry.js";
+import { TimeoutError, timeoutInterceptor } from "./interceptors/timeout.js";
+import type {
+  AppCheckTokenProvider,
+  AuthTokenProvider,
+  DispatchOutcome,
+  GatewayResult,
+  NetworkError,
+  NetworkErrorKind,
+} 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>;
+}
+
+const DEFAULT_ENDPOINT = "/api/gateway";
+const DEFAULT_TIMEOUT_MS = 15_000;
+
+function classifyNetworkError(error: unknown): NetworkError {
+  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: NetworkErrorKind = "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. */
+  readonly bus: GatewayEventBus;
+
+  readonly #endpoint: string;
+  readonly #timeoutMs: number;
+  readonly #send: Send;
+
+  constructor(options: GatewayClientOptions = {}) {
+    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: Interceptor[] = [];
+    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: Send = (config: GatewayRequestConfig) =>
+      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<T = GatewayResult>(
+    body: unknown,
+    options: DispatchOptions = {},
+  ): Promise<DispatchOutcome<T>> {
+    const config: GatewayRequestConfig = {
+      url: this.#endpoint,
+      method: "POST",
+      headers: { "content-type": "application/json", ...options.headers },
+      body,
+      timeoutMs: this.#timeoutMs,
+      ...(options.signal ? { signal: options.signal } : {}),
+    };
+
+    let response: Response;
+    try {
+      response = await this.#send(config);
+    } catch (error) {
+      return { kind: "network", error: classifyNetworkError(error) };
+    }
+    return decodeOutcome<T>(response, this.bus);
+  }
+}
+
+/** Convenience factory mirroring the constructor. */
+export function createGatewayClient(options: GatewayClientOptions = {}): GatewayClient {
+  return new GatewayClient(options);
+}

package/src/events.ts

@@ -0,0 +1,77 @@
+/**
+ * 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 class GatewayEventBus {
+  readonly #listeners: {
+    [E in keyof GatewayEventMap]: Set<Listener<E>>;
+  } = { handoff: new Set() };
+
+  readonly #onListenerError: (error: unknown) => void;
+
+  constructor(onListenerError: (error: unknown) => void = () => {}) {
+    this.#onListenerError = onListenerError;
+  }
+
+  /**
+   * 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 {
+    this.#listeners[event].add(listener);
+    return () => {
+      this.#listeners[event].delete(listener);
+    };
+  }
+
+  /** Publish an event to every current subscriber. */
+  emit<E extends keyof GatewayEventMap>(event: E, payload: GatewayEventMap[E]): void {
+    for (const listener of this.#listeners[event]) {
+      try {
+        listener(payload);
+      } catch (error) {
+        this.#onListenerError(error);
+      }
+    }
+  }
+
+  /** Remove all listeners (useful in test teardown). */
+  clear(): void {
+    this.#listeners.handoff.clear();
+  }
+}

package/src/index.ts

@@ -0,0 +1,56 @@
+/**
+ * `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";