modeldispatcher-client 0.6.0 → 0.6.7

package/src/index.ts

@@ -1,56 +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";
+/**
+ * `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/src/interceptors/appcheck.ts

@@ -1,33 +1,33 @@
-/**
- * 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 { GatewayRequestConfig, Interceptor, Send } from "./interceptor.js";
-
-/** 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: AppCheckTokenProvider): Interceptor {
-  return {
-    async intercept(config: GatewayRequestConfig, next: Send): Promise<Response> {
-      const token = await provider();
-      if (token) {
-        config.headers[APP_CHECK_HEADER] = token;
-      }
-      return next(config);
-    },
-  };
-}
+/**
+ * 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 { GatewayRequestConfig, Interceptor, Send } from "./interceptor.js";
+
+/** 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: AppCheckTokenProvider): Interceptor {
+  return {
+    async intercept(config: GatewayRequestConfig, next: Send): Promise<Response> {
+      const token = await provider();
+      if (token) {
+        config.headers[APP_CHECK_HEADER] = token;
+      }
+      return next(config);
+    },
+  };
+}

package/src/interceptors/auth.ts

@@ -1,34 +1,34 @@
-/**
- * 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 { GatewayRequestConfig, Interceptor, Send } from "./interceptor.js";
-
-/** 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: AuthTokenProvider): Interceptor {
-  return {
-    async intercept(config: GatewayRequestConfig, next: Send): Promise<Response> {
-      const token = await provider();
-      if (token) {
-        config.headers[AUTHORIZATION_HEADER] = `Bearer ${token}`;
-      }
-      return next(config);
-    },
-  };
-}
+/**
+ * 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 { GatewayRequestConfig, Interceptor, Send } from "./interceptor.js";
+
+/** 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: AuthTokenProvider): Interceptor {
+  return {
+    async intercept(config: GatewayRequestConfig, next: Send): Promise<Response> {
+      const token = await provider();
+      if (token) {
+        config.headers[AUTHORIZATION_HEADER] = `Bearer ${token}`;
+      }
+      return next(config);
+    },
+  };
+}

package/src/interceptors/handoff.ts

@@ -1,91 +1,91 @@
-/**
- * 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,
-  GatewayError,
-  Handoff,
-  HandoffAction,
-} from "../types.js";
-
-/** The actions this client knows how to surface. */
-export const HANDOFF_ACTIONS: readonly HandoffAction[] = [
-  "trigger_key_wizard",
-  "upgrade_plan",
-  "retry_later",
-];
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null;
-}
-
-/** Type guard: does an arbitrary parsed body match the {@link Handoff} shape? */
-export function isHandoffPayload(body: unknown): body is Handoff {
-  if (!isRecord(body)) return false;
-  return (
-    typeof body["error"] === "string" &&
-    typeof body["provider"] === "string" &&
-    typeof body["action"] === "string" &&
-    (HANDOFF_ACTIONS as readonly string[]).includes(body["action"])
-  );
-}
-
-/** Parse a JSON body without throwing; returns `undefined` on empty/invalid. */
-async function readJson(response: Response): Promise<unknown> {
-  const text = await response.text();
-  if (!text) return undefined;
-  try {
-    return JSON.parse(text) as unknown;
-  } catch {
-    return undefined;
-  }
-}
-
-function toGatewayError(body: unknown, status: number): GatewayError {
-  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<T>(
-  response: Response,
-  bus: GatewayEventBus,
-): Promise<DispatchOutcome<T>> {
-  const body = await readJson(response);
-
-  if (response.ok) {
-    return { kind: "ok", result: body as T };
-  }
-
-  if (isHandoffPayload(body)) {
-    const handoff: 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) };
-}
+/**
+ * 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,
+  GatewayError,
+  Handoff,
+  HandoffAction,
+} from "../types.js";
+
+/** The actions this client knows how to surface. */
+export const HANDOFF_ACTIONS: readonly HandoffAction[] = [
+  "trigger_key_wizard",
+  "upgrade_plan",
+  "retry_later",
+];
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}
+
+/** Type guard: does an arbitrary parsed body match the {@link Handoff} shape? */
+export function isHandoffPayload(body: unknown): body is Handoff {
+  if (!isRecord(body)) return false;
+  return (
+    typeof body["error"] === "string" &&
+    typeof body["provider"] === "string" &&
+    typeof body["action"] === "string" &&
+    (HANDOFF_ACTIONS as readonly string[]).includes(body["action"])
+  );
+}
+
+/** Parse a JSON body without throwing; returns `undefined` on empty/invalid. */
+async function readJson(response: Response): Promise<unknown> {
+  const text = await response.text();
+  if (!text) return undefined;
+  try {
+    return JSON.parse(text) as unknown;
+  } catch {
+    return undefined;
+  }
+}
+
+function toGatewayError(body: unknown, status: number): GatewayError {
+  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<T>(
+  response: Response,
+  bus: GatewayEventBus,
+): Promise<DispatchOutcome<T>> {
+  const body = await readJson(response);
+
+  if (response.ok) {
+    return { kind: "ok", result: body as T };
+  }
+
+  if (isHandoffPayload(body)) {
+    const handoff: 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) };
+}

package/src/interceptors/interceptor.ts

@@ -1,53 +1,53 @@
-/**
- * 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 function compose(interceptors: readonly Interceptor[], terminal: Send): Send {
-  return interceptors.reduceRight<Send>(
-    (next, interceptor) => (config) => interceptor.intercept(config, next),
-    terminal,
-  );
-}
+/**
+ * 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 function compose(interceptors: readonly Interceptor[], terminal: Send): Send {
+  return interceptors.reduceRight<Send>(
+    (next, interceptor) => (config) => interceptor.intercept(config, next),
+    terminal,
+  );
+}