@ai-sdk/gateway 0.0.0-1c33ba03-20260114162300 → 0.0.0-4115c213-20260122152721

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

@@ -0,0 +1,33 @@
+import { APICallError } from '@ai-sdk/provider';
+import { extractApiCallResponse, GatewayError } from '.';
+import { createGatewayErrorFromResponse } from './create-gateway-error';
+
+export function asGatewayError(
+  error: unknown,
+  authMethod?: 'api-key' | 'oidc',
+) {
+  if (GatewayError.isInstance(error)) {
+    return error;
+  }
+
+  if (APICallError.isInstance(error)) {
+    return createGatewayErrorFromResponse({
+      response: extractApiCallResponse(error),
+      statusCode: error.statusCode ?? 500,
+      defaultMessage: 'Gateway request failed',
+      cause: error,
+      authMethod,
+    });
+  }
+
+  return createGatewayErrorFromResponse({
+    response: {},
+    statusCode: 500,
+    defaultMessage:
+      error instanceof Error
+        ? `Gateway request failed: ${error.message}`
+        : 'Unknown Gateway error',
+    cause: error,
+    authMethod,
+  });
+}

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

@@ -0,0 +1,132 @@
+import { z } from 'zod/v4';
+import type { GatewayError } from './gateway-error';
+import { GatewayAuthenticationError } from './gateway-authentication-error';
+import { GatewayInvalidRequestError } from './gateway-invalid-request-error';
+import { GatewayRateLimitError } from './gateway-rate-limit-error';
+import {
+  GatewayModelNotFoundError,
+  modelNotFoundParamSchema,
+} from './gateway-model-not-found-error';
+import { GatewayInternalServerError } from './gateway-internal-server-error';
+import { GatewayResponseError } from './gateway-response-error';
+import {
+  InferSchema,
+  lazySchema,
+  safeValidateTypes,
+  validateTypes,
+  zodSchema,
+} from '@ai-sdk/provider-utils';
+
+export async function createGatewayErrorFromResponse({
+  response,
+  statusCode,
+  defaultMessage = 'Gateway request failed',
+  cause,
+  authMethod,
+}: {
+  response: unknown;
+  statusCode: number;
+  defaultMessage?: string;
+  cause?: unknown;
+  authMethod?: 'api-key' | 'oidc';
+}): Promise<GatewayError> {
+  const parseResult = await safeValidateTypes({
+    value: response,
+    schema: gatewayErrorResponseSchema,
+  });
+
+  if (!parseResult.success) {
+    // Try to extract generationId even if validation failed
+    const rawGenerationId =
+      typeof response === 'object' &&
+      response !== null &&
+      'generationId' in response
+        ? (response as { generationId?: string }).generationId
+        : undefined;
+
+    return new GatewayResponseError({
+      message: `Invalid error response format: ${defaultMessage}`,
+      statusCode,
+      response,
+      validationError: parseResult.error,
+      cause,
+      generationId: rawGenerationId,
+    });
+  }
+
+  const validatedResponse: GatewayErrorResponse = parseResult.value;
+  const errorType = validatedResponse.error.type;
+  const message = validatedResponse.error.message;
+  const generationId = validatedResponse.generationId ?? undefined;
+
+  switch (errorType) {
+    case 'authentication_error':
+      return GatewayAuthenticationError.createContextualError({
+        apiKeyProvided: authMethod === 'api-key',
+        oidcTokenProvided: authMethod === 'oidc',
+        statusCode,
+        cause,
+        generationId,
+      });
+    case 'invalid_request_error':
+      return new GatewayInvalidRequestError({
+        message,
+        statusCode,
+        cause,
+        generationId,
+      });
+    case 'rate_limit_exceeded':
+      return new GatewayRateLimitError({
+        message,
+        statusCode,
+        cause,
+        generationId,
+      });
+    case 'model_not_found': {
+      const modelResult = await safeValidateTypes({
+        value: validatedResponse.error.param,
+        schema: modelNotFoundParamSchema,
+      });
+
+      return new GatewayModelNotFoundError({
+        message,
+        statusCode,
+        modelId: modelResult.success ? modelResult.value.modelId : undefined,
+        cause,
+        generationId,
+      });
+    }
+    case 'internal_server_error':
+      return new GatewayInternalServerError({
+        message,
+        statusCode,
+        cause,
+        generationId,
+      });
+    default:
+      return new GatewayInternalServerError({
+        message,
+        statusCode,
+        cause,
+        generationId,
+      });
+  }
+}
+
+const gatewayErrorResponseSchema = lazySchema(() =>
+  zodSchema(
+    z.object({
+      error: z.object({
+        message: z.string(),
+        type: z.string().nullish(),
+        param: z.unknown().nullish(),
+        code: z.union([z.string(), z.number()]).nullish(),
+      }),
+      generationId: z.string().nullish(),
+    }),
+  ),
+);
+
+export type GatewayErrorResponse = InferSchema<
+  typeof gatewayErrorResponseSchema
+>;

package/src/errors/extract-api-call-response.ts

@@ -0,0 +1,15 @@
+import type { APICallError } from '@ai-sdk/provider';
+
+export function extractApiCallResponse(error: APICallError): unknown {
+  if (error.data !== undefined) {
+    return error.data;
+  }
+  if (error.responseBody != null) {
+    try {
+      return JSON.parse(error.responseBody);
+    } catch {
+      return error.responseBody;
+    }
+  }
+  return {};
+}

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

@@ -0,0 +1,84 @@
+import { GatewayError } from './gateway-error';
+
+const name = 'GatewayAuthenticationError';
+const marker = `vercel.ai.gateway.error.${name}`;
+const symbol = Symbol.for(marker);
+
+/**
+ * Authentication failed - invalid API key or OIDC token
+ */
+export class GatewayAuthenticationError extends GatewayError {
+  private readonly [symbol] = true; // used in isInstance
+
+  readonly name = name;
+  readonly type = 'authentication_error';
+
+  constructor({
+    message = 'Authentication failed',
+    statusCode = 401,
+    cause,
+    generationId,
+  }: {
+    message?: string;
+    statusCode?: number;
+    cause?: unknown;
+    generationId?: string;
+  } = {}) {
+    super({ message, statusCode, cause, generationId });
+  }
+
+  static isInstance(error: unknown): error is GatewayAuthenticationError {
+    return GatewayError.hasMarker(error) && symbol in error;
+  }
+
+  /**
+   * Creates a contextual error message when authentication fails
+   */
+  static createContextualError({
+    apiKeyProvided,
+    oidcTokenProvided,
+    message = 'Authentication failed',
+    statusCode = 401,
+    cause,
+    generationId,
+  }: {
+    apiKeyProvided: boolean;
+    oidcTokenProvided: boolean;
+    message?: string;
+    statusCode?: number;
+    cause?: unknown;
+    generationId?: string;
+  }): GatewayAuthenticationError {
+    let contextualMessage: string;
+
+    if (apiKeyProvided) {
+      contextualMessage = `AI Gateway authentication failed: Invalid API key.
+
+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.`;
+    } 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`;
+    } else {
+      contextualMessage = `AI Gateway authentication failed: No authentication provided.
+
+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:
+Run 'npx vercel link' to link your project, then 'vc env pull' to fetch the token.`;
+    }
+
+    return new GatewayAuthenticationError({
+      message: contextualMessage,
+      statusCode,
+      cause,
+      generationId,
+    });
+  }
+}

package/src/errors/gateway-error.ts

@@ -0,0 +1,47 @@
+const marker = 'vercel.ai.gateway.error';
+const symbol = Symbol.for(marker);
+
+export abstract class GatewayError extends Error {
+  private readonly [symbol] = true; // used in isInstance
+
+  abstract readonly name: string;
+  abstract readonly type: string;
+  readonly statusCode: number;
+  readonly cause?: unknown;
+  readonly generationId?: string;
+
+  constructor({
+    message,
+    statusCode = 500,
+    cause,
+    generationId,
+  }: {
+    message: string;
+    statusCode?: number;
+    cause?: unknown;
+    generationId?: string;
+  }) {
+    super(generationId ? `${message} [${generationId}]` : message);
+    this.statusCode = statusCode;
+    this.cause = cause;
+    this.generationId = generationId;
+  }
+
+  /**
+   * Checks if the given error is a Gateway Error.
+   * @param {unknown} error - The error to check.
+   * @returns {boolean} True if the error is a Gateway Error, false otherwise.
+   */
+  static isInstance(error: unknown): error is GatewayError {
+    return GatewayError.hasMarker(error);
+  }
+
+  static hasMarker(error: unknown): error is GatewayError {
+    return (
+      typeof error === 'object' &&
+      error !== null &&
+      symbol in error &&
+      (error as any)[symbol] === true
+    );
+  }
+}

package/src/errors/gateway-internal-server-error.ts

@@ -0,0 +1,33 @@
+import { GatewayError } from './gateway-error';
+
+const name = 'GatewayInternalServerError';
+const marker = `vercel.ai.gateway.error.${name}`;
+const symbol = Symbol.for(marker);
+
+/**
+ * Internal server error from the Gateway
+ */
+export class GatewayInternalServerError extends GatewayError {
+  private readonly [symbol] = true; // used in isInstance
+
+  readonly name = name;
+  readonly type = 'internal_server_error';
+
+  constructor({
+    message = 'Internal server error',
+    statusCode = 500,
+    cause,
+    generationId,
+  }: {
+    message?: string;
+    statusCode?: number;
+    cause?: unknown;
+    generationId?: string;
+  } = {}) {
+    super({ message, statusCode, cause, generationId });
+  }
+
+  static isInstance(error: unknown): error is GatewayInternalServerError {
+    return GatewayError.hasMarker(error) && symbol in error;
+  }
+}

package/src/errors/gateway-invalid-request-error.ts

@@ -0,0 +1,33 @@
+import { GatewayError } from './gateway-error';
+
+const name = 'GatewayInvalidRequestError';
+const marker = `vercel.ai.gateway.error.${name}`;
+const symbol = Symbol.for(marker);
+
+/**
+ * Invalid request - missing headers, malformed data, etc.
+ */
+export class GatewayInvalidRequestError extends GatewayError {
+  private readonly [symbol] = true; // used in isInstance
+
+  readonly name = name;
+  readonly type = 'invalid_request_error';
+
+  constructor({
+    message = 'Invalid request',
+    statusCode = 400,
+    cause,
+    generationId,
+  }: {
+    message?: string;
+    statusCode?: number;
+    cause?: unknown;
+    generationId?: string;
+  } = {}) {
+    super({ message, statusCode, cause, generationId });
+  }
+
+  static isInstance(error: unknown): error is GatewayInvalidRequestError {
+    return GatewayError.hasMarker(error) && symbol in error;
+  }
+}

package/src/errors/gateway-model-not-found-error.ts

@@ -0,0 +1,47 @@
+import { z } from 'zod/v4';
+import { GatewayError } from './gateway-error';
+import { lazySchema, zodSchema } from '@ai-sdk/provider-utils';
+
+const name = 'GatewayModelNotFoundError';
+const marker = `vercel.ai.gateway.error.${name}`;
+const symbol = Symbol.for(marker);
+
+export const modelNotFoundParamSchema = lazySchema(() =>
+  zodSchema(
+    z.object({
+      modelId: z.string(),
+    }),
+  ),
+);
+
+/**
+ * Model not found or not available
+ */
+export class GatewayModelNotFoundError extends GatewayError {
+  private readonly [symbol] = true; // used in isInstance
+
+  readonly name = name;
+  readonly type = 'model_not_found';
+  readonly modelId?: string;
+
+  constructor({
+    message = 'Model not found',
+    statusCode = 404,
+    modelId,
+    cause,
+    generationId,
+  }: {
+    message?: string;
+    statusCode?: number;
+    modelId?: string;
+    cause?: unknown;
+    generationId?: string;
+  } = {}) {
+    super({ message, statusCode, cause, generationId });
+    this.modelId = modelId;
+  }
+
+  static isInstance(error: unknown): error is GatewayModelNotFoundError {
+    return GatewayError.hasMarker(error) && symbol in error;
+  }
+}

package/src/errors/gateway-rate-limit-error.ts

@@ -0,0 +1,33 @@
+import { GatewayError } from './gateway-error';
+
+const name = 'GatewayRateLimitError';
+const marker = `vercel.ai.gateway.error.${name}`;
+const symbol = Symbol.for(marker);
+
+/**
+ * Rate limit exceeded.
+ */
+export class GatewayRateLimitError extends GatewayError {
+  private readonly [symbol] = true; // used in isInstance
+
+  readonly name = name;
+  readonly type = 'rate_limit_exceeded';
+
+  constructor({
+    message = 'Rate limit exceeded',
+    statusCode = 429,
+    cause,
+    generationId,
+  }: {
+    message?: string;
+    statusCode?: number;
+    cause?: unknown;
+    generationId?: string;
+  } = {}) {
+    super({ message, statusCode, cause, generationId });
+  }
+
+  static isInstance(error: unknown): error is GatewayRateLimitError {
+    return GatewayError.hasMarker(error) && symbol in error;
+  }
+}

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

@@ -0,0 +1,42 @@
+import { TypeValidationError } from '@ai-sdk/provider';
+import { GatewayError } from './gateway-error';
+
+const name = 'GatewayResponseError';
+const marker = `vercel.ai.gateway.error.${name}`;
+const symbol = Symbol.for(marker);
+
+/**
+ * Gateway response parsing error
+ */
+export class GatewayResponseError extends GatewayError {
+  private readonly [symbol] = true; // used in isInstance
+
+  readonly name = name;
+  readonly type = 'response_error';
+  readonly response?: unknown;
+  readonly validationError?: TypeValidationError;
+
+  constructor({
+    message = 'Invalid response from Gateway',
+    statusCode = 502,
+    response,
+    validationError,
+    cause,
+    generationId,
+  }: {
+    message?: string;
+    statusCode?: number;
+    response?: unknown;
+    validationError?: TypeValidationError;
+    cause?: unknown;
+    generationId?: string;
+  } = {}) {
+    super({ message, statusCode, cause, generationId });
+    this.response = response;
+    this.validationError = validationError;
+  }
+
+  static isInstance(error: unknown): error is GatewayResponseError {
+    return GatewayError.hasMarker(error) && symbol in error;
+  }
+}

package/src/errors/index.ts

@@ -0,0 +1,16 @@
+export { asGatewayError } from './as-gateway-error';
+export {
+  createGatewayErrorFromResponse,
+  type GatewayErrorResponse,
+} from './create-gateway-error';
+export { extractApiCallResponse } from './extract-api-call-response';
+export { GatewayError } from './gateway-error';
+export { GatewayAuthenticationError } from './gateway-authentication-error';
+export { GatewayInternalServerError } from './gateway-internal-server-error';
+export { GatewayInvalidRequestError } from './gateway-invalid-request-error';
+export {
+  GatewayModelNotFoundError,
+  modelNotFoundParamSchema,
+} from './gateway-model-not-found-error';
+export { GatewayRateLimitError } from './gateway-rate-limit-error';
+export { GatewayResponseError } from './gateway-response-error';

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

@@ -0,0 +1,23 @@
+import { z } from 'zod/v4';
+import {
+  lazySchema,
+  safeValidateTypes,
+  zodSchema,
+} from '@ai-sdk/provider-utils';
+
+export const GATEWAY_AUTH_METHOD_HEADER = 'ai-gateway-auth-method' as const;
+
+export async function parseAuthMethod(
+  headers: Record<string, string | undefined>,
+) {
+  const result = await safeValidateTypes({
+    value: headers[GATEWAY_AUTH_METHOD_HEADER],
+    schema: gatewayAuthMethodSchema,
+  });
+
+  return result.success ? result.value : undefined;
+}
+
+const gatewayAuthMethodSchema = lazySchema(() =>
+  zodSchema(z.union([z.literal('api-key'), z.literal('oidc')])),
+);

package/src/gateway-config.ts

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

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

@@ -0,0 +1,22 @@
+export type GatewayEmbeddingModelId =
+  | 'alibaba/qwen3-embedding-0.6b'
+  | 'alibaba/qwen3-embedding-4b'
+  | 'alibaba/qwen3-embedding-8b'
+  | 'amazon/titan-embed-text-v2'
+  | 'cohere/embed-v4.0'
+  | 'google/gemini-embedding-001'
+  | 'google/text-embedding-005'
+  | 'google/text-multilingual-embedding-002'
+  | 'mistral/codestral-embed'
+  | 'mistral/mistral-embed'
+  | 'openai/text-embedding-3-large'
+  | 'openai/text-embedding-3-small'
+  | 'openai/text-embedding-ada-002'
+  | 'voyage/voyage-3-large'
+  | 'voyage/voyage-3.5'
+  | 'voyage/voyage-3.5-lite'
+  | 'voyage/voyage-code-2'
+  | 'voyage/voyage-code-3'
+  | 'voyage/voyage-finance-2'
+  | 'voyage/voyage-law-2'
+  | (string & {});

package/src/gateway-embedding-model.ts

@@ -0,0 +1,109 @@
+import type {
+  EmbeddingModelV3,
+  SharedV3ProviderMetadata,
+} 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 GatewayEmbeddingModel implements EmbeddingModelV3 {
+  readonly specificationVersion = 'v3';
+  readonly maxEmbeddingsPerCall = 2048;
+  readonly supportsParallelCalls = true;
+
+  constructor(
+    readonly modelId: string,
+    private readonly config: GatewayConfig & {
+      provider: string;
+      o11yHeaders: Resolvable<Record<string, string>>;
+    },
+  ) {}
+
+  get provider(): string {
+    return this.config.provider;
+  }
+
+  async doEmbed({
+    values,
+    headers,
+    abortSignal,
+    providerOptions,
+  }: Parameters<EmbeddingModelV3['doEmbed']>[0]): Promise<
+    Awaited<ReturnType<EmbeddingModelV3['doEmbed']>>
+  > {
+    const resolvedHeaders = await resolve(this.config.headers());
+    try {
+      const {
+        responseHeaders,
+        value: responseBody,
+        rawValue,
+      } = await postJsonToApi({
+        url: this.getUrl(),
+        headers: combineHeaders(
+          resolvedHeaders,
+          headers ?? {},
+          this.getModelConfigHeaders(),
+          await resolve(this.config.o11yHeaders),
+        ),
+        body: {
+          values,
+          ...(providerOptions ? { providerOptions } : {}),
+        },
+        successfulResponseHandler: createJsonResponseHandler(
+          gatewayEmbeddingResponseSchema,
+        ),
+        failedResponseHandler: createJsonErrorResponseHandler({
+          errorSchema: z.any(),
+          errorToMessage: data => data,
+        }),
+        ...(abortSignal && { abortSignal }),
+        fetch: this.config.fetch,
+      });
+
+      return {
+        embeddings: responseBody.embeddings,
+        usage: responseBody.usage ?? undefined,
+        providerMetadata:
+          responseBody.providerMetadata as unknown as SharedV3ProviderMetadata,
+        response: { headers: responseHeaders, body: rawValue },
+        warnings: [],
+      };
+    } catch (error) {
+      throw await asGatewayError(error, await parseAuthMethod(resolvedHeaders));
+    }
+  }
+
+  private getUrl() {
+    return `${this.config.baseURL}/embedding-model`;
+  }
+
+  private getModelConfigHeaders() {
+    return {
+      'ai-embedding-model-specification-version': '3',
+      'ai-model-id': this.modelId,
+    };
+  }
+}
+
+const gatewayEmbeddingResponseSchema = lazySchema(() =>
+  zodSchema(
+    z.object({
+      embeddings: z.array(z.array(z.number())),
+      usage: z.object({ tokens: z.number() }).nullish(),
+      providerMetadata: z
+        .record(z.string(), z.record(z.string(), z.unknown()))
+        .optional(),
+    }),
+  ),
+);