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

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@ai-sdk/gateway",
   "private": false,
-  "version": "4.0.0-beta.11",
+  "version": "4.0.0-beta.110",
+  "type": "module",
   "license": "Apache-2.0",
   "sideEffects": false,
   "main": "./dist/index.js",
-  "module": "./dist/index.mjs",
   "types": "./dist/index.d.ts",
   "files": [
     "dist/**/*",
@@ -25,37 +25,39 @@
     "./package.json": "./package.json",
     ".": {
       "types": "./dist/index.d.ts",
-      "import": "./dist/index.mjs",
-      "require": "./dist/index.js"
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
     }
   },
   "dependencies": {
     "@vercel/oidc": "3.2.0",
-    "@ai-sdk/provider": "4.0.0-beta.1",
-    "@ai-sdk/provider-utils": "5.0.0-beta.2"
+    "@ai-sdk/provider": "4.0.0-beta.19",
+    "@ai-sdk/provider-utils": "5.0.0-beta.49"
   },
   "devDependencies": {
-    "@types/node": "18.15.11",
-    "tsup": "^8",
+    "@types/node": "22.19.19",
+    "tsup": "^8.5.1",
     "tsx": "4.19.2",
     "typescript": "5.8.3",
     "zod": "3.25.76",
-    "@ai-sdk/test-server": "2.0.0-beta.0",
+    "@ai-sdk/test-server": "2.0.0-beta.7",
     "@vercel/ai-tsconfig": "0.0.0"
   },
   "peerDependencies": {
     "zod": "^3.25.76 || ^4.1.8"
   },
   "engines": {
-    "node": ">=18"
+    "node": ">=22"
   },
   "publishConfig": {
-    "access": "public"
+    "access": "public",
+    "provenance": true
   },
   "homepage": "https://ai-sdk.dev/docs",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/vercel/ai.git"
+    "url": "https://github.com/vercel/ai",
+    "directory": "packages/gateway"
   },
   "bugs": {
     "url": "https://github.com/vercel/ai/issues"
@@ -68,9 +70,7 @@
     "build:watch": "pnpm clean && tsup --watch",
     "clean": "del-cli dist docs *.tsbuildinfo",
     "generate-model-settings": "tsx scripts/generate-model-settings.ts",
-    "lint": "eslint \"./**/*.ts*\"",
     "type-check": "tsc --build",
-    "prettier-check": "prettier --check \"./**/*.ts*\"",
     "test": "pnpm test:node && pnpm test:edge",
     "test:update": "pnpm test:node -u",
     "test:watch": "vitest --config vitest.node.config.js",

package/src/errors/as-gateway-error.ts

@@ -1,6 +1,7 @@
 import { APICallError } from '@ai-sdk/provider';
-import { extractApiCallResponse, GatewayError } from '.';
 import { createGatewayErrorFromResponse } from './create-gateway-error';
+import { extractApiCallResponse } from './extract-api-call-response';
+import { GatewayError } from './gateway-error';
 import { GatewayTimeoutError } from './gateway-timeout-error';
 
 /**

package/src/errors/create-gateway-error.ts

@@ -8,15 +8,15 @@ import {
   modelNotFoundParamSchema,
 } from './gateway-model-not-found-error';
 import { GatewayInternalServerError } from './gateway-internal-server-error';
+import { GatewayFailedDependencyError } from './gateway-failed-dependency-error';
+import { GatewayForbiddenError } from './gateway-forbidden-error';
 import { GatewayResponseError } from './gateway-response-error';
 import {
-  InferSchema,
   lazySchema,
   safeValidateTypes,
-  validateTypes,
   zodSchema,
+  type InferSchema,
 } from '@ai-sdk/provider-utils';
-
 export async function createGatewayErrorFromResponse({
   response,
   statusCode,
@@ -103,6 +103,20 @@ export async function createGatewayErrorFromResponse({
         cause,
         generationId,
       });
+    case 'failed_dependency':
+      return new GatewayFailedDependencyError({
+        message,
+        statusCode,
+        cause,
+        generationId,
+      });
+    case 'forbidden':
+      return new GatewayForbiddenError({
+        message,
+        statusCode,
+        cause,
+        generationId,
+      });
     default:
       return new GatewayInternalServerError({
         message,

package/src/errors/gateway-authentication-error.ts

@@ -37,7 +37,6 @@ export class GatewayAuthenticationError extends GatewayError {
   static createContextualError({
     apiKeyProvided,
     oidcTokenProvided,
-    message = 'Authentication failed',
     statusCode = 401,
     cause,
     generationId,
@@ -52,17 +51,18 @@ export class GatewayAuthenticationError extends GatewayError {
     let contextualMessage: string;
 
     if (apiKeyProvided) {
-      contextualMessage = `AI Gateway authentication failed: Invalid API key.
+      contextualMessage = `AI Gateway authentication failed: Invalid API key or token.
 
 Create a new API key: https://vercel.com/d?to=%2F%5Bteam%5D%2F%7E%2Fai%2Fapi-keys
 
-Provide via 'apiKey' option or 'AI_GATEWAY_API_KEY' environment variable.`;
+Provide an API key or Vercel access token via 'apiKey' option or 'AI_GATEWAY_API_KEY' environment variable.`;
     } else if (oidcTokenProvided) {
       contextualMessage = `AI Gateway authentication failed: Invalid OIDC token.
 
 Run 'npx vercel link' to link your project, then 'vc env pull' to fetch the token.
 
-Alternatively, use an API key: https://vercel.com/d?to=%2F%5Bteam%5D%2F%7E%2Fai%2Fapi-keys`;
+Alternatively, use an API key: https://vercel.com/d?to=%2F%5Bteam%5D%2F%7E%2Fai%2Fapi-keys
+or pass a Vercel access token via the 'apiKey' option.`;
     } else {
       contextualMessage = `AI Gateway authentication failed: No authentication provided.
 
@@ -70,7 +70,10 @@ Option 1 - API key:
 Create an API key: https://vercel.com/d?to=%2F%5Bteam%5D%2F%7E%2Fai%2Fapi-keys
 Provide via 'apiKey' option or 'AI_GATEWAY_API_KEY' environment variable.
 
-Option 2 - OIDC token:
+Option 2 - Vercel access token:
+Pass a Vercel personal access token or Vercel app access token via the 'apiKey' option.
+
+Option 3 - OIDC token:
 Run 'npx vercel link' to link your project, then 'vc env pull' to fetch the token.`;
     }
 

package/src/errors/gateway-error.ts

@@ -9,22 +9,30 @@ export abstract class GatewayError extends Error {
   readonly statusCode: number;
   readonly cause?: unknown;
   readonly generationId?: string;
+  readonly isRetryable: boolean;
 
   constructor({
     message,
     statusCode = 500,
     cause,
     generationId,
+    isRetryable = statusCode != null &&
+      (statusCode === 408 || // request timeout
+        statusCode === 409 || // conflict
+        statusCode === 429 || // too many requests
+        statusCode >= 500), // server error
   }: {
     message: string;
     statusCode?: number;
     cause?: unknown;
     generationId?: string;
+    isRetryable?: boolean;
   }) {
     super(generationId ? `${message} [${generationId}]` : message);
     this.statusCode = statusCode;
     this.cause = cause;
     this.generationId = generationId;
+    this.isRetryable = isRetryable;
   }
 
   /**

package/src/errors/gateway-failed-dependency-error.ts

@@ -0,0 +1,35 @@
+import { GatewayError } from './gateway-error';
+
+const name = 'GatewayFailedDependencyError';
+const marker = `vercel.ai.gateway.error.${name}`;
+const symbol = Symbol.for(marker);
+
+/**
+ * The request could not be fulfilled because a dependency it relied on was not
+ * available on the credentials or provider used to serve it (HTTP 424). Not
+ * retryable — the caller must change the request.
+ */
+export class GatewayFailedDependencyError extends GatewayError {
+  private readonly [symbol] = true; // used in isInstance
+
+  readonly name = name;
+  readonly type = 'failed_dependency';
+
+  constructor({
+    message = 'Failed dependency',
+    statusCode = 424,
+    cause,
+    generationId,
+  }: {
+    message?: string;
+    statusCode?: number;
+    cause?: unknown;
+    generationId?: string;
+  } = {}) {
+    super({ message, statusCode, cause, generationId });
+  }
+
+  static isInstance(error: unknown): error is GatewayFailedDependencyError {
+    return GatewayError.hasMarker(error) && symbol in error;
+  }
+}

package/src/errors/gateway-forbidden-error.ts

@@ -0,0 +1,34 @@
+import { GatewayError } from './gateway-error';
+
+const name = 'GatewayForbiddenError';
+const marker = `vercel.ai.gateway.error.${name}`;
+const symbol = Symbol.for(marker);
+
+/**
+ * Forbidden - the request was rejected by policy (e.g. a routing rule),
+ * not an authentication failure.
+ */
+export class GatewayForbiddenError extends GatewayError {
+  private readonly [symbol] = true; // used in isInstance
+
+  readonly name = name;
+  readonly type = 'forbidden';
+
+  constructor({
+    message = 'Forbidden',
+    statusCode = 403,
+    cause,
+    generationId,
+  }: {
+    message?: string;
+    statusCode?: number;
+    cause?: unknown;
+    generationId?: string;
+  } = {}) {
+    super({ message, statusCode, cause, generationId });
+  }
+
+  static isInstance(error: unknown): error is GatewayForbiddenError {
+    return GatewayError.hasMarker(error) && symbol in error;
+  }
+}

package/src/errors/gateway-response-error.ts

@@ -1,4 +1,4 @@
-import { TypeValidationError } from '@ai-sdk/provider';
+import type { TypeValidationError } from '@ai-sdk/provider';
 import { GatewayError } from './gateway-error';
 
 const name = 'GatewayResponseError';

package/src/errors/index.ts

@@ -6,6 +6,8 @@ export {
 export { extractApiCallResponse } from './extract-api-call-response';
 export { GatewayError } from './gateway-error';
 export { GatewayAuthenticationError } from './gateway-authentication-error';
+export { GatewayFailedDependencyError } from './gateway-failed-dependency-error';
+export { GatewayForbiddenError } from './gateway-forbidden-error';
 export { GatewayInternalServerError } from './gateway-internal-server-error';
 export { GatewayInvalidRequestError } from './gateway-invalid-request-error';
 export {

package/src/errors/parse-auth-method.ts

@@ -4,8 +4,7 @@ import {
   safeValidateTypes,
   zodSchema,
 } from '@ai-sdk/provider-utils';
-
-export const GATEWAY_AUTH_METHOD_HEADER = 'ai-gateway-auth-method' as const;
+import { GATEWAY_AUTH_METHOD_HEADER } from '../gateway-headers';
 
 export async function parseAuthMethod(
   headers: Record<string, string | undefined>,

package/src/gateway-config.ts

@@ -2,6 +2,6 @@ import type { FetchFunction, Resolvable } from '@ai-sdk/provider-utils';
 
 export type GatewayConfig = {
   baseURL: string;
-  headers: () => Resolvable<Record<string, string | undefined>>;
+  headers?: Resolvable<Record<string, string | undefined>>;
   fetch?: FetchFunction;
 };

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

@@ -5,6 +5,7 @@ export type GatewayEmbeddingModelId =
   | 'amazon/titan-embed-text-v2'
   | 'cohere/embed-v4.0'
   | 'google/gemini-embedding-001'
+  | 'google/gemini-embedding-2'
   | 'google/text-embedding-005'
   | 'google/text-multilingual-embedding-002'
   | 'mistral/codestral-embed'

package/src/gateway-embedding-model.ts

@@ -1,6 +1,6 @@
 import type {
-  EmbeddingModelV3,
-  SharedV3ProviderMetadata,
+  EmbeddingModelV4,
+  SharedV4ProviderMetadata,
 } from '@ai-sdk/provider';
 import {
   combineHeaders,
@@ -9,6 +9,9 @@ import {
   lazySchema,
   postJsonToApi,
   resolve,
+  serializeModelOptions,
+  WORKFLOW_SERIALIZE,
+  WORKFLOW_DESERIALIZE,
   zodSchema,
   type Resolvable,
 } from '@ai-sdk/provider-utils';
@@ -17,17 +20,33 @@ import { asGatewayError } from './errors';
 import { parseAuthMethod } from './errors/parse-auth-method';
 import type { GatewayConfig } from './gateway-config';
 
-export class GatewayEmbeddingModel implements EmbeddingModelV3 {
-  readonly specificationVersion = 'v3';
+type GatewayEmbeddingConfig = GatewayConfig & {
+  provider: string;
+  o11yHeaders: Resolvable<Record<string, string>>;
+};
+
+export class GatewayEmbeddingModel implements EmbeddingModelV4 {
+  readonly specificationVersion = 'v4';
   readonly maxEmbeddingsPerCall = 2048;
   readonly supportsParallelCalls = true;
 
+  static [WORKFLOW_SERIALIZE](model: GatewayEmbeddingModel) {
+    return serializeModelOptions({
+      modelId: model.modelId,
+      config: model.config,
+    });
+  }
+
+  static [WORKFLOW_DESERIALIZE](options: {
+    modelId: string;
+    config: GatewayEmbeddingConfig;
+  }) {
+    return new GatewayEmbeddingModel(options.modelId, options.config);
+  }
+
   constructor(
     readonly modelId: string,
-    private readonly config: GatewayConfig & {
-      provider: string;
-      o11yHeaders: Resolvable<Record<string, string>>;
-    },
+    private readonly config: GatewayEmbeddingConfig,
   ) {}
 
   get provider(): string {
@@ -39,10 +58,12 @@ export class GatewayEmbeddingModel implements EmbeddingModelV3 {
     headers,
     abortSignal,
     providerOptions,
-  }: Parameters<EmbeddingModelV3['doEmbed']>[0]): Promise<
-    Awaited<ReturnType<EmbeddingModelV3['doEmbed']>>
+  }: Parameters<EmbeddingModelV4['doEmbed']>[0]): Promise<
+    Awaited<ReturnType<EmbeddingModelV4['doEmbed']>>
   > {
-    const resolvedHeaders = await resolve(this.config.headers());
+    const resolvedHeaders = this.config.headers
+      ? await resolve(this.config.headers)
+      : undefined;
     try {
       const {
         responseHeaders,
@@ -75,12 +96,15 @@ export class GatewayEmbeddingModel implements EmbeddingModelV3 {
         embeddings: responseBody.embeddings,
         usage: responseBody.usage ?? undefined,
         providerMetadata:
-          responseBody.providerMetadata as unknown as SharedV3ProviderMetadata,
+          responseBody.providerMetadata as unknown as SharedV4ProviderMetadata,
         response: { headers: responseHeaders, body: rawValue },
-        warnings: [],
+        warnings: responseBody.warnings ?? [],
       };
     } catch (error) {
-      throw await asGatewayError(error, await parseAuthMethod(resolvedHeaders));
+      throw await asGatewayError(
+        error,
+        await parseAuthMethod(resolvedHeaders ?? {}),
+      );
     }
   }
 
@@ -90,17 +114,40 @@ export class GatewayEmbeddingModel implements EmbeddingModelV3 {
 
   private getModelConfigHeaders() {
     return {
-      'ai-embedding-model-specification-version': '3',
+      'ai-embedding-model-specification-version': '4',
       'ai-model-id': this.modelId,
     };
   }
 }
 
+const gatewayEmbeddingWarningSchema = 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 gatewayEmbeddingResponseSchema = lazySchema(() =>
   zodSchema(
     z.object({
       embeddings: z.array(z.array(z.number())),
       usage: z.object({ tokens: z.number() }).nullish(),
+      warnings: z.array(gatewayEmbeddingWarningSchema).optional(),
       providerMetadata: z
         .record(z.string(), z.record(z.string(), z.unknown()))
         .optional(),

package/src/gateway-fetch-metadata.ts

@@ -9,8 +9,11 @@ import {
 import { z } from 'zod/v4';
 import { asGatewayError } from './errors';
 import type { GatewayConfig } from './gateway-config';
-import type { GatewayLanguageModelEntry } from './gateway-model-entry';
-
+import {
+  KNOWN_MODEL_TYPES,
+  type GatewayLanguageModelEntry,
+  type KnownModelType,
+} from './gateway-model-entry';
 type GatewayFetchMetadataConfig = GatewayConfig;
 
 export interface GatewayFetchMetadataResponse {
@@ -31,7 +34,9 @@ export class GatewayFetchMetadata {
     try {
       const { value } = await getFromApi({
         url: `${this.config.baseURL}/config`,
-        headers: await resolve(this.config.headers()),
+        headers: this.config.headers
+          ? await resolve(this.config.headers)
+          : undefined,
         successfulResponseHandler: createJsonResponseHandler(
           gatewayAvailableModelsResponseSchema,
         ),
@@ -54,7 +59,9 @@ export class GatewayFetchMetadata {
 
       const { value } = await getFromApi({
         url: `${baseUrl.origin}/v1/credits`,
-        headers: await resolve(this.config.headers()),
+        headers: this.config.headers
+          ? await resolve(this.config.headers)
+          : undefined,
         successfulResponseHandler: createJsonResponseHandler(
           gatewayCreditsResponseSchema,
         ),
@@ -75,41 +82,47 @@ export class GatewayFetchMetadata {
 const gatewayAvailableModelsResponseSchema = lazySchema(() =>
   zodSchema(
     z.object({
-      models: z.array(
-        z.object({
-          id: z.string(),
-          name: z.string(),
-          description: z.string().nullish(),
-          pricing: z
-            .object({
-              input: z.string(),
-              output: z.string(),
-              input_cache_read: z.string().nullish(),
-              input_cache_write: z.string().nullish(),
-            })
-            .transform(
-              ({ input, output, input_cache_read, input_cache_write }) => ({
-                input,
-                output,
-                ...(input_cache_read
-                  ? { cachedInputTokens: input_cache_read }
-                  : {}),
-                ...(input_cache_write
-                  ? { cacheCreationInputTokens: input_cache_write }
-                  : {}),
-              }),
-            )
-            .nullish(),
-          specification: z.object({
-            specificationVersion: z.literal('v3'),
-            provider: z.string(),
-            modelId: z.string(),
+      models: z
+        .array(
+          z.object({
+            id: z.string(),
+            name: z.string(),
+            description: z.string().nullish(),
+            pricing: z
+              .object({
+                input: z.string(),
+                output: z.string(),
+                input_cache_read: z.string().nullish(),
+                input_cache_write: z.string().nullish(),
+              })
+              .transform(
+                ({ input, output, input_cache_read, input_cache_write }) => ({
+                  input,
+                  output,
+                  ...(input_cache_read
+                    ? { cachedInputTokens: input_cache_read }
+                    : {}),
+                  ...(input_cache_write
+                    ? { cacheCreationInputTokens: input_cache_write }
+                    : {}),
+                }),
+              )
+              .nullish(),
+            specification: z.object({
+              specificationVersion: z.literal('v4'),
+              provider: z.string(),
+              modelId: z.string(),
+            }),
+            modelType: z.string().nullish(),
           }),
-          modelType: z
-            .enum(['embedding', 'image', 'language', 'video'])
-            .nullish(),
-        }),
-      ),
+        )
+        .transform(models =>
+          models.filter(
+            (m): m is typeof m & { modelType?: KnownModelType | null } =>
+              m.modelType == null ||
+              KNOWN_MODEL_TYPES.includes(m.modelType as KnownModelType),
+          ),
+        ),
     }),
   ),
 );