modeldispatcher-client 0.6.0 → 0.6.7

package/package.json

@@ -1,52 +1,57 @@
-{
-  "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"
-  }
-}
+{
+  "name": "modeldispatcher-client",
+  "version": "0.6.7",
+  "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",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/joka-7/ModelDispatcher.git",
+    "directory": "clients/typescript"
+  },
+  "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

@@ -1,148 +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);
-}
+/**
+ * {@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

@@ -1,77 +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();
-  }
-}
+/**
+ * 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();
+  }
+}