@ai-sdk/gateway 4.0.0-beta.11 → 4.0.0-beta.110

package/src/gateway-realtime-auth.ts

@@ -0,0 +1,126 @@
+/**
+ * Shared WebSocket subprotocol contract for AI Gateway realtime auth.
+ *
+ * The browser `WebSocket` API cannot set request headers, so the Gateway auth
+ * (bearer) token is carried through the `Sec-WebSocket-Protocol` handshake
+ * instead of an `Authorization` header — the same workaround OpenAI uses for
+ * `openai-insecure-api-key.<token>`.
+ *
+ * This module is the single source of truth for that contract so the client and
+ * the Gateway server can't drift: the client encodes values with
+ * `getGatewayRealtimeProtocols`, and the Gateway server decodes them with
+ * `getGatewayRealtimeAuthToken` / `getGatewayRealtimeTeamIdOrSlug`.
+ *
+ * WebSocket subprotocol values must fit the RFC token grammar. The auth token is
+ * sent as-is, so callers must use tokens that are valid subprotocol tokens; the
+ * optional team scope is base64url-encoded by this module. Keep the complete
+ * `Sec-WebSocket-Protocol` header compact (target under an 8 KiB safe header
+ * budget) because intermediaries may reject large upgrade headers.
+ */
+
+/**
+ * Marker subprotocol offered on every handshake so the Gateway can echo a
+ * negotiated subprotocol on the 101 response (some clients require the server to
+ * select one of the offered subprotocols).
+ */
+export const GATEWAY_REALTIME_SUBPROTOCOL = 'ai-gateway-realtime.v1';
+
+/** Subprotocol prefix that carries the Gateway auth (bearer) token. */
+export const GATEWAY_AUTH_SUBPROTOCOL_PREFIX = 'ai-gateway-auth.';
+
+/** Subprotocol prefix that carries optional Vercel team scoping. */
+export const GATEWAY_TEAM_SUBPROTOCOL_PREFIX = 'ai-gateway-team.';
+
+/**
+ * Client-side: build the WebSocket subprotocols that carry `token` to the
+ * Gateway. Pass the result as the second argument to `new WebSocket(url, ...)`.
+ */
+export function getGatewayRealtimeProtocols(
+  token: string,
+  options?: { teamIdOrSlug?: string },
+): string[] {
+  const protocols = [
+    GATEWAY_REALTIME_SUBPROTOCOL,
+    `${GATEWAY_AUTH_SUBPROTOCOL_PREFIX}${token}`,
+  ];
+
+  if (options?.teamIdOrSlug) {
+    protocols.push(
+      `${GATEWAY_TEAM_SUBPROTOCOL_PREFIX}${encodeSubprotocolValue(options.teamIdOrSlug)}`,
+    );
+  }
+
+  return protocols;
+}
+
+/**
+ * Server-side: extract the Gateway auth (bearer) token from a
+ * `Sec-WebSocket-Protocol` header value, or `undefined` when it is absent or
+ * empty. The Gateway upgrade handler turns this into an
+ * `Authorization: Bearer <token>` before its normal auth path.
+ *
+ * Accepts the raw header value (subprotocols are comma-separated and may carry
+ * surrounding whitespace).
+ */
+export function getGatewayRealtimeAuthToken(
+  secWebSocketProtocol: string | null | undefined,
+): string | undefined {
+  // `findProtocol` trims the protocol, so the sliced token needs no further
+  // trimming; `|| undefined` collapses the empty-token case.
+  return (
+    findProtocol(secWebSocketProtocol, GATEWAY_AUTH_SUBPROTOCOL_PREFIX)?.slice(
+      GATEWAY_AUTH_SUBPROTOCOL_PREFIX.length,
+    ) || undefined
+  );
+}
+
+/**
+ * Server-side: extract the optional Vercel team ID or slug from the
+ * `Sec-WebSocket-Protocol` header value. Team scoping is base64url-encoded so
+ * arbitrary team slugs stay within the WebSocket subprotocol token grammar.
+ */
+export function getGatewayRealtimeTeamIdOrSlug(
+  secWebSocketProtocol: string | null | undefined,
+): string | undefined {
+  const encoded = findProtocol(
+    secWebSocketProtocol,
+    GATEWAY_TEAM_SUBPROTOCOL_PREFIX,
+  )?.slice(GATEWAY_TEAM_SUBPROTOCOL_PREFIX.length);
+  if (!encoded) return undefined;
+
+  try {
+    return decodeSubprotocolValue(encoded) || undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function findProtocol(
+  secWebSocketProtocol: string | null | undefined,
+  prefix: string,
+): string | undefined {
+  return secWebSocketProtocol
+    ?.split(',')
+    .map(protocol => protocol.trim())
+    .find(protocol => protocol.startsWith(prefix));
+}
+
+function encodeSubprotocolValue(value: string): string {
+  const bytes = new TextEncoder().encode(value);
+  let binary = '';
+  for (const byte of bytes) {
+    binary += String.fromCharCode(byte);
+  }
+  return btoa(binary)
+    .replace(/\+/g, '-')
+    .replace(/\//g, '_')
+    .replace(/=+$/u, '');
+}
+
+function decodeSubprotocolValue(value: string): string {
+  const base64 = value.replace(/-/g, '+').replace(/_/g, '/');
+  const padding = '='.repeat((4 - (base64.length % 4)) % 4);
+  const binary = atob(`${base64}${padding}`);
+  const bytes = Uint8Array.from(binary, char => char.charCodeAt(0));
+  return new TextDecoder().decode(bytes);
+}

package/src/gateway-realtime-model-settings.ts

@@ -0,0 +1 @@
+export type GatewayRealtimeModelId = string & {};

package/src/gateway-realtime-model.ts

@@ -0,0 +1,118 @@
+import type {
+  Experimental_RealtimeModelV4 as RealtimeModelV4,
+  Experimental_RealtimeModelV4ClientEvent as RealtimeModelV4ClientEvent,
+  Experimental_RealtimeModelV4ClientSecretOptions as RealtimeModelV4ClientSecretOptions,
+  Experimental_RealtimeModelV4ClientSecretResult as RealtimeModelV4ClientSecretResult,
+  Experimental_RealtimeModelV4ServerEvent as RealtimeModelV4ServerEvent,
+  Experimental_RealtimeModelV4SessionConfig as RealtimeModelV4SessionConfig,
+} from '@ai-sdk/provider';
+import { getGatewayRealtimeProtocols } from './gateway-realtime-auth';
+
+export type GatewayRealtimeModelConfig = {
+  provider: string;
+  baseURL: string;
+  teamIdOrSlug?: string;
+  /**
+   * Mints a short-lived client secret (`vcst_`) for this model via the
+   * Gateway's `/v1/realtime/client-secrets` endpoint. Implemented by the
+   * provider because minting requires the long-lived Gateway credential
+   * (API key / OIDC) and must run server-side.
+   */
+  createClientSecret: (params: {
+    modelId: string;
+    expiresAfterSeconds?: number;
+  }) => PromiseLike<{ token: string; expiresAt?: number }>;
+};
+
+/**
+ * Realtime model backed by the AI Gateway.
+ *
+ * The Gateway normalizes realtime exactly like it normalizes every other
+ * modality: the client speaks the normalized AI SDK realtime protocol and the
+ * Gateway translates to and from the upstream provider server-side. This model
+ * is therefore a thin identity codec over that normalized protocol — only the
+ * connection and authentication are Gateway-specific.
+ */
+export class GatewayRealtimeModel implements RealtimeModelV4 {
+  readonly specificationVersion = 'v4' as const;
+  readonly provider: string;
+  readonly modelId: string;
+
+  private readonly config: GatewayRealtimeModelConfig;
+
+  constructor(modelId: string, config: GatewayRealtimeModelConfig) {
+    this.modelId = modelId;
+    this.provider = config.provider;
+    this.config = config;
+  }
+
+  /**
+   * Mints a single-use, short-lived client secret (`vcst_`) the browser uses to
+   * open the realtime WebSocket without ever holding the long-lived Gateway
+   * credential. The customer's server calls this (via
+   * `gateway.experimental_realtime.getToken`) and hands the returned token to
+   * the browser, which connects with it through the `ai-gateway-auth.<token>`
+   * subprotocol. `expiresAfterSeconds` is forwarded to the mint endpoint;
+   * `sessionConfig` is intentionally unused here — it is applied later via the
+   * normalized `session-update` event.
+   */
+  async doCreateClientSecret(
+    options?: RealtimeModelV4ClientSecretOptions,
+  ): Promise<RealtimeModelV4ClientSecretResult> {
+    const secret = await this.config.createClientSecret({
+      modelId: this.modelId,
+      ...(options?.expiresAfterSeconds != null && {
+        expiresAfterSeconds: options.expiresAfterSeconds,
+      }),
+    });
+    return {
+      token: secret.token,
+      url: toGatewayRealtimeUrl(this.config.baseURL, this.modelId),
+      ...(secret.expiresAt != null && { expiresAt: secret.expiresAt }),
+    };
+  }
+
+  getWebSocketConfig(options: { token: string; url: string }): {
+    url: string;
+    protocols?: string[];
+  } {
+    return {
+      url: options.url,
+      protocols: getGatewayRealtimeProtocols(options.token, {
+        teamIdOrSlug: this.config.teamIdOrSlug,
+      }),
+    };
+  }
+
+  parseServerEvent(raw: unknown): RealtimeModelV4ServerEvent {
+    // The Gateway emits normalized AI SDK realtime events, so no
+    // provider-specific mapping is needed on the client.
+    return raw as RealtimeModelV4ServerEvent;
+  }
+
+  serializeClientEvent(event: RealtimeModelV4ClientEvent): unknown {
+    // The Gateway accepts normalized AI SDK realtime events directly.
+    return event;
+  }
+
+  buildSessionConfig(config: RealtimeModelV4SessionConfig): unknown {
+    // The session config is already normalized; the Gateway maps it to the
+    // upstream provider's session payload server-side.
+    return config;
+  }
+}
+
+/**
+ * Build the Gateway realtime WebSocket URL. The HTTP(S) base URL is upgraded to
+ * WS(S) and the model id rides the `?ai-model-id=` query — the WS transport of
+ * the `ai-model-id` header the HTTP routes use, since a browser `WebSocket`
+ * cannot set headers. The model id is passed through verbatim; the Gateway owns
+ * resolution (including the bare → `openai/` qualification), exactly like the
+ * non-realtime routes. The query is slash-safe for qualified ids such as
+ * `openai/gpt-realtime-2`.
+ */
+function toGatewayRealtimeUrl(baseURL: string, modelId: string): string {
+  const url = new URL(`${baseURL.replace(/^http/, 'ws')}/realtime-model`);
+  url.searchParams.set('ai-model-id', modelId);
+  return url.toString();
+}

package/src/gateway-reranking-model-settings.ts

@@ -0,0 +1,7 @@
+export type GatewayRerankingModelId =
+  | 'cohere/rerank-v3.5'
+  | 'cohere/rerank-v4-fast'
+  | 'cohere/rerank-v4-pro'
+  | 'voyage/rerank-2.5'
+  | 'voyage/rerank-2.5-lite'
+  | (string & {});

package/src/gateway-reranking-model.ts

@@ -0,0 +1,142 @@
+import type {
+  RerankingModelV4,
+  SharedV4ProviderMetadata,
+} from '@ai-sdk/provider';
+import {
+  combineHeaders,
+  createJsonErrorResponseHandler,
+  createJsonResponseHandler,
+  lazySchema,
+  postJsonToApi,
+  resolve,
+  zodSchema,
+  type Resolvable,
+} from '@ai-sdk/provider-utils';
+import { z } from 'zod/v4';
+import { asGatewayError } from './errors';
+import { parseAuthMethod } from './errors/parse-auth-method';
+import type { GatewayConfig } from './gateway-config';
+
+export class GatewayRerankingModel implements RerankingModelV4 {
+  readonly specificationVersion = 'v4';
+
+  constructor(
+    readonly modelId: string,
+    private readonly config: GatewayConfig & {
+      provider: string;
+      o11yHeaders: Resolvable<Record<string, string>>;
+    },
+  ) {}
+
+  get provider(): string {
+    return this.config.provider;
+  }
+
+  async doRerank({
+    documents,
+    query,
+    topN,
+    headers,
+    abortSignal,
+    providerOptions,
+  }: Parameters<RerankingModelV4['doRerank']>[0]): Promise<
+    Awaited<ReturnType<RerankingModelV4['doRerank']>>
+  > {
+    const resolvedHeaders = this.config.headers
+      ? await resolve(this.config.headers)
+      : undefined;
+    try {
+      const {
+        responseHeaders,
+        value: responseBody,
+        rawValue,
+      } = await postJsonToApi({
+        url: this.getUrl(),
+        headers: combineHeaders(
+          resolvedHeaders,
+          headers ?? {},
+          this.getModelConfigHeaders(),
+          await resolve(this.config.o11yHeaders),
+        ),
+        body: {
+          documents,
+          query,
+          ...(topN != null ? { topN } : {}),
+          ...(providerOptions ? { providerOptions } : {}),
+        },
+        successfulResponseHandler: createJsonResponseHandler(
+          gatewayRerankingResponseSchema,
+        ),
+        failedResponseHandler: createJsonErrorResponseHandler({
+          errorSchema: z.any(),
+          errorToMessage: data => data,
+        }),
+        ...(abortSignal && { abortSignal }),
+        fetch: this.config.fetch,
+      });
+
+      return {
+        ranking: responseBody.ranking,
+        providerMetadata:
+          responseBody.providerMetadata as unknown as SharedV4ProviderMetadata,
+        response: { headers: responseHeaders, body: rawValue },
+        warnings: responseBody.warnings ?? [],
+      };
+    } catch (error) {
+      throw await asGatewayError(
+        error,
+        await parseAuthMethod(resolvedHeaders ?? {}),
+      );
+    }
+  }
+
+  private getUrl() {
+    return `${this.config.baseURL}/reranking-model`;
+  }
+
+  private getModelConfigHeaders() {
+    return {
+      'ai-reranking-model-specification-version': '4',
+      'ai-model-id': this.modelId,
+    };
+  }
+}
+
+const gatewayRerankingWarningSchema = z.discriminatedUnion('type', [
+  z.object({
+    type: z.literal('unsupported'),
+    feature: z.string(),
+    details: z.string().optional(),
+  }),
+  z.object({
+    type: z.literal('compatibility'),
+    feature: z.string(),
+    details: z.string().optional(),
+  }),
+  z.object({
+    type: z.literal('deprecated'),
+    setting: z.string(),
+    message: z.string(),
+  }),
+  z.object({
+    type: z.literal('other'),
+    message: z.string(),
+  }),
+]);
+
+const gatewayRerankingResponseSchema = lazySchema(() =>
+  zodSchema(
+    z.object({
+      ranking: z.array(
+        z.object({
+          index: z.number(),
+          relevanceScore: z.number(),
+        }),
+      ),
+      warnings: z.array(gatewayRerankingWarningSchema).optional(),
+      providerMetadata: z
+        .record(z.string(), z.record(z.string(), z.unknown()))
+        .optional(),
+    }),
+  ),
+);

package/src/gateway-speech-model-settings.ts

@@ -0,0 +1 @@
+export type GatewaySpeechModelId = string & {};

package/src/gateway-speech-model.ts

@@ -0,0 +1,145 @@
+import type {
+  SharedV4ProviderMetadata,
+  SharedV4Warning,
+  SpeechModelV4,
+} from '@ai-sdk/provider';
+import {
+  combineHeaders,
+  createJsonErrorResponseHandler,
+  createJsonResponseHandler,
+  postJsonToApi,
+  resolve,
+  type Resolvable,
+} from '@ai-sdk/provider-utils';
+import { z } from 'zod/v4';
+import { asGatewayError } from './errors';
+import { parseAuthMethod } from './errors/parse-auth-method';
+import type { GatewayConfig } from './gateway-config';
+
+export class GatewaySpeechModel implements SpeechModelV4 {
+  readonly specificationVersion = 'v4' as const;
+
+  constructor(
+    readonly modelId: string,
+    private readonly config: GatewayConfig & {
+      provider: string;
+      o11yHeaders: Resolvable<Record<string, string>>;
+    },
+  ) {}
+
+  get provider(): string {
+    return this.config.provider;
+  }
+
+  async doGenerate({
+    text,
+    voice,
+    outputFormat,
+    instructions,
+    speed,
+    language,
+    providerOptions,
+    headers,
+    abortSignal,
+  }: Parameters<SpeechModelV4['doGenerate']>[0]): Promise<
+    Awaited<ReturnType<SpeechModelV4['doGenerate']>>
+  > {
+    const resolvedHeaders = this.config.headers
+      ? await resolve(this.config.headers)
+      : undefined;
+    try {
+      const {
+        responseHeaders,
+        value: responseBody,
+        rawValue,
+      } = await postJsonToApi({
+        url: this.getUrl(),
+        headers: combineHeaders(
+          resolvedHeaders,
+          headers ?? {},
+          this.getModelConfigHeaders(),
+          await resolve(this.config.o11yHeaders),
+        ),
+        body: {
+          text,
+          ...(voice && { voice }),
+          ...(outputFormat && { outputFormat }),
+          ...(instructions && { instructions }),
+          ...(speed != null && { speed }),
+          ...(language && { language }),
+          ...(providerOptions && { providerOptions }),
+        },
+        successfulResponseHandler: createJsonResponseHandler(
+          gatewaySpeechResponseSchema,
+        ),
+        failedResponseHandler: createJsonErrorResponseHandler({
+          errorSchema: z.any(),
+          errorToMessage: data => data,
+        }),
+        ...(abortSignal && { abortSignal }),
+        fetch: this.config.fetch,
+      });
+
+      return {
+        audio: responseBody.audio,
+        warnings: (responseBody.warnings ?? []) as Array<SharedV4Warning>,
+        providerMetadata:
+          responseBody.providerMetadata as SharedV4ProviderMetadata,
+        response: {
+          timestamp: new Date(),
+          modelId: this.modelId,
+          headers: responseHeaders,
+          body: rawValue,
+        },
+      };
+    } catch (error) {
+      throw await asGatewayError(
+        error,
+        await parseAuthMethod(resolvedHeaders ?? {}),
+      );
+    }
+  }
+
+  private getUrl() {
+    return `${this.config.baseURL}/speech-model`;
+  }
+
+  private getModelConfigHeaders() {
+    return {
+      'ai-speech-model-specification-version': '4',
+      'ai-model-id': this.modelId,
+    };
+  }
+}
+
+const providerMetadataEntrySchema = z.object({}).catchall(z.unknown());
+
+const gatewaySpeechWarningSchema = z.discriminatedUnion('type', [
+  z.object({
+    type: z.literal('unsupported'),
+    feature: z.string(),
+    details: z.string().optional(),
+  }),
+  z.object({
+    type: z.literal('compatibility'),
+    feature: z.string(),
+    details: z.string().optional(),
+  }),
+  z.object({
+    type: z.literal('deprecated'),
+    setting: z.string(),
+    message: z.string(),
+  }),
+  z.object({
+    type: z.literal('other'),
+    message: z.string(),
+  }),
+]);
+
+const gatewaySpeechResponseSchema = z.object({
+  audio: z.string(),
+  warnings: z.array(gatewaySpeechWarningSchema).optional(),
+  providerMetadata: z
+    .record(z.string(), providerMetadataEntrySchema)
+    .optional(),
+});