workers-ai-provider 3.1.13 → 3.2.0

package/dist/gateway-delegate-BfaUTwDZ.d.mts

@@ -0,0 +1,385 @@
+import { LanguageModelV3 } from "@ai-sdk/provider";
+
+//#region src/gateway-providers.d.ts
+/**
+ * Registry of Cloudflare AI Gateway providers.
+ *
+ * One table drives both delegate surfaces:
+ *
+ *   - **Slug delegate** (`wai("openai/gpt-5")`): `resolverKey` is the slug prefix
+ *     the user types. `runCatalog` providers dispatch through the resumable run
+ *     path (`env.AI.run`, unified billing, `cf-aig-run-id`); the rest go through
+ *     the gateway path (`env.AI.gateway().run`, BYOK, no resume). `wireFormat`
+ *     selects the built-in `@ai-sdk/*` parser; absent ⇒ the provider is reachable
+ *     only via the bring-your-own-provider wrapper (it isn't chat/completions
+ *     shaped, e.g. audio/image providers).
+ *   - **Bring-your-own-provider** (`createGatewayProvider`): `hostPattern` +
+ *     `transformEndpoint` map a wrapped provider's request URL to the gateway
+ *     `provider` id + endpoint path.
+ *
+ * Slugs mirror the AI Gateway provider directory
+ * (developers.cloudflare.com/ai-gateway/usage/providers/); endpoint transforms
+ * mirror `ai-gateway-provider`'s provider table. `runCatalog` / `billing` flags
+ * follow the documented unified-billing list (OpenAI, Anthropic, Google AI
+ * Studio, Google Vertex, xAI/Grok, Groq) and are otherwise conservative — the
+ * e2e suite confirms them live, since resume is undocumented upstream.
+ */
+/** Response wire format the slug delegate can parse with a built-in `@ai-sdk/*` provider. */
+type WireFormat = "openai" | "anthropic" | "google";
+/** How a provider is billed + keyed when reached through the gateway. */
+type Billing = "unified" | "byok";
+interface GatewayProviderInfo {
+  /**
+   * Slug prefix the user types in `wai("<resolverKey>/<model>")`. For
+   * `runCatalog` providers this is also the run-catalog author (so
+   * `env.AI.run("<resolverKey>/<model>")` resolves).
+   */
+  resolverKey: string;
+  /** Provider id for the gateway universal endpoint (`env.AI.gateway().run([{ provider }])`). */
+  gatewayProviderId: string;
+  /**
+   * Built-in parser wire format. `openai` covers the whole OpenAI-compatible
+   * long tail (deepseek, grok, groq, mistral, perplexity, …). Absent ⇒ reachable
+   * only via the bring-your-own-provider wrapper (provider-native, non-chat, or a
+   * gateway-path URL shape we don't reproduce reliably from the slug delegate).
+   */
+  wireFormat?: WireFormat;
+  /**
+   * Wire format the unified-billing **run path** (`env.AI.run`) emits for this
+   * provider — which is NOT always the provider's native format. Cloudflare's
+   * unified catalog normalizes most providers to OpenAI chat-completions (so
+   * `google` is parsed with the `openai` plugin on the run path), but passes
+   * **Anthropic through natively** (`content[].text`, native tool shape), so
+   * anthropic must be parsed with the `anthropic` plugin. Defaults to `"openai"`
+   * for run-catalog providers when omitted. Only meaningful when `runCatalog`.
+   */
+  runWireFormat?: WireFormat;
+  /**
+   * Base URL the wire-format builder should target so the request URL it
+   * generates host-strips (via {@link transformEndpoint}) to the provider's
+   * gateway-native endpoint. Omit to use the `@ai-sdk` provider's default (the
+   * provider's own host — correct for `openai`/`anthropic`/`google`). Required
+   * for OpenAI-wire providers that share the `openai` plugin but live on a
+   * different host (deepseek, grok, groq, mistral, perplexity, …).
+   */
+  baseURL?: string;
+  /** On the unified-billing resumable run catalog (`env.AI.run`, `cf-aig-run-id`). */
+  runCatalog: boolean;
+  /**
+   * Whether the provider has a gateway path (`env.AI.gateway().run`). `false` ⇒
+   * **run-path only**: the provider is on the unified run catalog but is not a
+   * native gateway provider, so caching, server-side fallback, and
+   * `transport: "gateway"` are unavailable and the delegate rejects them with a
+   * clear error (rather than failing upstream). Defaults to `true`.
+   */
+  gatewayPath?: boolean;
+  /** Billing model when reached through the gateway. */
+  billing: Billing;
+  /** Header(s) carrying the upstream provider key (stripped on the gateway path unless BYOK-forwarded). */
+  authHeaders: string[];
+  /** Host matcher for bring-your-own-provider URL detection. */
+  hostPattern?: RegExp;
+  /** Strip the provider host, leaving the gateway endpoint path (+ query). */
+  transformEndpoint?: (url: string) => string;
+}
+/**
+ * The provider table. Order matters only for `detectProviderByUrl` (first match
+ * wins); slugs are looked up by `resolverKey`.
+ */
+declare const GATEWAY_PROVIDERS: GatewayProviderInfo[];
+/** Look up a provider by the slug prefix the user typed (honoring aliases). */
+declare function findProviderBySlug(resolverKey: string): GatewayProviderInfo | undefined;
+/** Detect the gateway provider from a wrapped provider's request URL (BYOG). */
+declare function detectProviderByUrl(url: string): GatewayProviderInfo | undefined;
+/** All slug keys with a built-in parser (auto-wireable by the slug delegate). */
+declare function wireableProviders(): GatewayProviderInfo[];
+//#endregion
+//#region src/resumable-stream.d.ts
+type ResumeExpiredPolicy = "error" | "accept-partial";
+interface ResumableStreamOptions {
+  /** Cloudflare AI binding (e.g. `env.AI`) — used for the resume fetch. */
+  binding: Ai;
+  /** Gateway id the run was issued under. */
+  gateway: string;
+  /** The `cf-aig-run-id` of the run to resume. */
+  runId: string;
+  /**
+   * Initial run-path response body. Omit for **cross-invocation re-attach**: the
+   * stream then starts by fetching `resume?from={fromEvent}` directly (e.g. a new
+   * Durable Object invocation re-attaching to a run after eviction).
+   */
+  initial?: ReadableStream<Uint8Array>;
+  /**
+   * SSE event index to (re-)attach from. Defaults to `0`. Used as the starting
+   * `from` when `initial` is omitted, and as the base offset for the event
+   * counter (so a later reconnect resumes from the correct absolute index).
+   */
+  fromEvent?: number;
+  /** What to do when the resume buffer has expired (404). Defaults to `"error"`. */
+  onResumeExpired?: ResumeExpiredPolicy;
+  /** Max reconnect attempts before giving up. Defaults to 5. */
+  maxReconnects?: number;
+  /** Fired before each reconnect with the resume `from` index and attempt number. */
+  onReconnect?: (fromEvent: number, attempt: number) => void;
+  /**
+   * Fired with the cumulative SSE event offset whenever complete events are
+   * emitted. Use it to persist `{ runId, eventOffset }` for cross-invocation
+   * re-attach (throttle your own writes — this can fire per chunk).
+   */
+  onProgress?: (eventOffset: number) => void;
+}
+declare function createResumableStream(options: ResumableStreamOptions): ReadableStream<Uint8Array>;
+//#endregion
+//#region src/errors.d.ts
+/**
+ * Typed errors for the gateway delegate.
+ *
+ *   - {@link WorkersAIGatewayError} — a single dispatch failed. Carries a coarse
+ *     {@link GatewayErrorCode}, a `recoverable` hint (whether a retry/fallback is
+ *     worth attempting), and the parsed gateway/provider envelope.
+ *   - {@link WorkersAIFallbackError} — every model in a client-side fallback chain
+ *     failed. Carries the per-attempt tree so callers can see exactly what was
+ *     tried and why each leg failed.
+ */
+/** Coarse classification of a gateway/provider failure. */
+type GatewayErrorCode = "auth" | "rate-limit" | "not-found" | "bad-request" | "provider-error" | "gateway-error" | "resume-expired" | "unknown";
+/** Context attached to a {@link WorkersAIGatewayError}. */
+interface GatewayErrorContext {
+  /** Gateway provider id (e.g. `"openai"`, `"google-ai-studio"`). */
+  provider?: string;
+  /** Provider-native model id. */
+  modelId?: string;
+  /** Transport the failed dispatch used. */
+  transport?: "run" | "gateway";
+  /** HTTP status, if any. */
+  status?: number | null;
+  /** `cf-aig-log-id` for cross-referencing in the dashboard. */
+  logId?: string | null;
+  /** `cf-aig-run-id`, if the run path issued one. */
+  runId?: string | null;
+}
+/** A single dispatch failure through AI Gateway (run or gateway path). */
+declare class WorkersAIGatewayError extends Error {
+  readonly code: GatewayErrorCode;
+  /** Whether a retry or fallback to another model is worth attempting. */
+  readonly recoverable: boolean;
+  readonly status: number | null;
+  readonly context: GatewayErrorContext;
+  /** Parsed gateway/provider error envelope (or raw text). */
+  readonly raw?: unknown;
+  readonly cause?: unknown;
+  constructor(code: GatewayErrorCode, message: string, opts?: {
+    recoverable?: boolean;
+    status?: number | null;
+    context?: GatewayErrorContext;
+    raw?: unknown;
+    cause?: unknown;
+  });
+  /**
+   * Classify an arbitrary thrown value. Understands AI SDK `APICallError`
+   * (reads `statusCode` / `responseBody` / `isRetryable`); falls back to a
+   * recoverable `gateway-error` for transport/connection failures so a fallback
+   * chain keeps trying.
+   */
+  static fromUnknown(e: unknown): WorkersAIGatewayError;
+  /** Build from an HTTP `Response` (reads the body for the envelope). */
+  static fromResponse(resp: Response, context?: GatewayErrorContext): Promise<WorkersAIGatewayError>;
+}
+/** One leg of a client-side fallback chain. */
+interface FallbackAttempt {
+  /** The model slug attempted. */
+  model: string;
+  /** Transport used for this attempt. */
+  transport: "run" | "gateway";
+  /** Whether this attempt succeeded. */
+  ok: boolean;
+  /** HTTP status, if any. */
+  status?: number | null;
+  /** The classified error, when the attempt failed. */
+  error?: WorkersAIGatewayError;
+}
+/** Every model in a client-side fallback chain failed. */
+declare class WorkersAIFallbackError extends Error {
+  /** The ordered attempt tree (primary first, then each fallback). */
+  readonly attempts: FallbackAttempt[];
+  constructor(attempts: FallbackAttempt[], message?: string);
+  /** The last (most recent) attempt's error, if any. */
+  get lastError(): WorkersAIGatewayError | undefined;
+}
+//#endregion
+//#region src/client-fallback.d.ts
+/** One model in a client-side fallback chain. */
+interface FallbackLeg {
+  /** The model slug this leg dispatches. */
+  slug: string;
+  /** The built AI SDK model. */
+  model: LanguageModelV3;
+  /** Transport the leg uses. */
+  transport: Transport;
+}
+/**
+ * Wrap a chain of models so a failed *pre-stream* dispatch falls through to the
+ * next model, preserving resume on each leg's own transport. If every leg fails,
+ * throws a {@link WorkersAIFallbackError} carrying the full attempt tree.
+ *
+ * Fallback triggers on `doGenerate`/`doStream` rejection (the dispatch never
+ * produced a stream). Errors that surface *mid-stream* — after content has
+ * already been emitted — are not recoverable here and propagate as-is.
+ */
+declare function createClientFallbackModel(legs: FallbackLeg[]): LanguageModelV3;
+//#endregion
+//#region src/gateway-delegate.d.ts
+/**
+ * Gateway delegate — route AI SDK catalog models through Cloudflare AI Gateway,
+ * with capability-driven transport selection.
+ *
+ * Two transports back the same model, chosen from the requested options:
+ *
+ *   - **Run path** `env.AI.run(slug, body, { returnRawResponse })` — resumable
+ *     streaming (`cf-aig-run-id`). The default.
+ *   - **Gateway path** `env.AI.gateway(id).run([entry, …fallback])` — server-side
+ *     fallback and caching. Does not surface `cf-aig-run-id`, so resume is off.
+ *
+ * The SAME `@ai-sdk/*` provider parses the response on either path, so there is no
+ * per-provider or per-path response parsing here. Provider plugins (which import
+ * `@ai-sdk/openai`, `@ai-sdk/anthropic`, …) are injected from sub-path modules
+ * (`workers-ai-provider/openai`, …) so those AI SDK packages stay OPTIONAL peer
+ * dependencies — you only install the ones you use.
+ *
+ * @example
+ * ```ts
+ * import { createGatewayDelegate } from "workers-ai-provider/gateway-delegate";
+ * import { openai } from "workers-ai-provider/openai";
+ * import { streamText } from "ai";
+ *
+ * const wai = createGatewayDelegate({
+ *   binding: env.AI,
+ *   gateway: "my-gateway",
+ *   providers: [openai],
+ * });
+ *
+ * const result = streamText({ model: wai("openai/gpt-5"), prompt: "Hello" });
+ * // result.response.headers["cf-aig-run-id"] is set — resume from there.
+ * ```
+ */
+interface ParsedSlug {
+  /** First path segment — the registry resolver key (selects provider + wire format). */
+  resolverKey: string;
+  /** Remaining segments — the provider-native model id. */
+  modelId: string;
+}
+/**
+ * Parse a `vendor/model` slug. The first segment is the resolver key (which
+ * registry entry handles it); the rest is the provider-native model id. Routing
+ * providers keep multi-segment model ids, e.g. `openrouter/anthropic/claude`.
+ */
+declare function parseSlug(slug: string): ParsedSlug;
+/**
+ * Adapts a `@ai-sdk/*` provider to the delegate, keyed by the response wire
+ * format it parses. Imported from a sub-path module (e.g.
+ * `workers-ai-provider/openai`) so the AI SDK package stays an optional peer
+ * dependency. One plugin serves every registry provider of that wire format —
+ * the `openai` plugin covers the whole OpenAI-compatible long tail (deepseek,
+ * grok, groq, mistral, perplexity, openrouter, …).
+ */
+interface ProviderPlugin {
+  /** The response wire format this builder parses. */
+  readonly wireFormat: WireFormat;
+  /**
+   * Build the AI SDK model, wiring the gateway-dispatching `fetch`. `baseURL`
+   * (when provided by the registry) targets the provider's host so the request
+   * URL host-strips to its gateway-native endpoint — pass it to the underlying
+   * `@ai-sdk` provider.
+   */
+  create(args: {
+    modelId: string;
+    fetch: typeof globalThis.fetch;
+    baseURL?: string;
+  }): LanguageModelV3;
+}
+type Transport = "run" | "gateway";
+interface FallbackOptions {
+  /** `"client"` keeps resume (sequential run-path attempts); `"server"` uses the gateway path. */
+  mode: "client" | "server";
+  /** Ordered model slugs to try after the primary. */
+  models: string[];
+}
+interface DispatchInfo {
+  transport: Transport;
+  resumeEnabled: boolean;
+  warnings: string[];
+  runId: string | null;
+  status: number | null;
+  cfStep: string | null;
+  cacheStatus: string | null;
+  logId: string | null;
+}
+interface DelegateCallOptions {
+  /** Resumable streaming (run path). Defaults to the delegate's `resume` (true). */
+  resume?: boolean;
+  /** Cross-model fallback. `"server"` mode uses the gateway path (disables resume). */
+  fallback?: FallbackOptions;
+  /** Gateway-path response caching (seconds). Forces the gateway path. */
+  cacheTtl?: number;
+  /** Bypass gateway cache. Forces the gateway path. */
+  skipCache?: boolean;
+  /** Escape hatch: force a transport. */
+  transport?: Transport;
+  /**
+   * Run path only: behavior when the resume buffer has expired (404) after a
+   * mid-stream drop. `"error"` (default) surfaces a `GatewayDelegateError`;
+   * `"accept-partial"` ends the stream cleanly with whatever was delivered.
+   */
+  onResumeExpired?: ResumeExpiredPolicy;
+  /** Extra request headers (run path: `extraHeaders`; gateway path: entry headers). */
+  extraHeaders?: Record<string, string>;
+  /**
+   * Gateway path only: forward the upstream provider key instead of stripping it.
+   * Required for BYOK providers (not on unified billing). Supply the key via
+   * `extraHeaders` (e.g. `{ authorization: "Bearer …" }`); without `byok` the
+   * delegate strips provider auth headers so unified billing applies.
+   */
+  byok?: boolean;
+  /** Override the delegate's gateway for this model. */
+  gateway?: GatewayOptions | string;
+  /**
+   * Custom metadata attached to the gateway log for this request (spend
+   * attribution, tenant ids, etc.). Merges over any `metadata` already set via
+   * `gateway: { metadata }`. Applied on both transports (run path: gateway
+   * options; gateway path: `cf-aig-metadata` header). `bigint` values are
+   * coerced to strings for the header form.
+   */
+  metadata?: Record<string, number | string | boolean | null | bigint>;
+  /** Force gateway log collection on/off for this request (both transports). */
+  collectLog?: boolean;
+  /** Called once per dispatch with the resolved transport + gateway headers. */
+  onDispatch?: (info: DispatchInfo) => void;
+  /**
+   * Run path only: fired with the cumulative SSE event offset as the resumable
+   * stream advances. Pair with `onDispatch` (for `runId`) to persist
+   * `{ runId, eventOffset }` for cross-invocation re-attach after eviction.
+   * Throttle your own writes — this can fire per chunk.
+   */
+  onProgress?: (eventOffset: number) => void;
+}
+interface Selection {
+  transport: Transport;
+  resumeEnabled: boolean;
+  warnings: string[];
+}
+/**
+ * Resolve the transport from the requested options. Gateway-only features (server
+ * fallback, caching) force the gateway path and disable resume — with a loud
+ * warning if resume was merely defaulted, or a thrown error if it was explicitly
+ * requested.
+ */
+declare function selectTransport(opts: DelegateCallOptions, resumeExplicitlyTrue: boolean, runCatalog?: boolean, gatewayAvailable?: boolean): Selection;
+type GatewayDelegateErrorKind = "config" | "dispatch" | "provider" | "resume-expired";
+declare class GatewayDelegateError extends Error {
+  readonly kind: GatewayDelegateErrorKind;
+  readonly cause?: unknown;
+  constructor(kind: GatewayDelegateErrorKind, message: string, cause?: unknown);
+}
+//#endregion
+export { WireFormat as C, wireableProviders as E, GatewayProviderInfo as S, findProviderBySlug as T, ResumableStreamOptions as _, ParsedSlug as a, Billing as b, parseSlug as c, createClientFallbackModel as d, FallbackAttempt as f, WorkersAIGatewayError as g, WorkersAIFallbackError as h, GatewayDelegateError as i, selectTransport as l, GatewayErrorContext as m, DispatchInfo as n, ProviderPlugin as o, GatewayErrorCode as p, FallbackOptions as r, Transport as s, DelegateCallOptions as t, FallbackLeg as u, ResumeExpiredPolicy as v, detectProviderByUrl as w, GATEWAY_PROVIDERS as x, createResumableStream as y };
+//# sourceMappingURL=gateway-delegate-BfaUTwDZ.d.mts.map