@ai-sdk/gateway 0.0.0-02dba89b-20251009204516 → 0.0.0-4115c213-20260122152721

package/src/gateway-model-entry.ts

@@ -0,0 +1,58 @@
+import type { LanguageModelV3 } from '@ai-sdk/provider';
+
+export interface GatewayLanguageModelEntry {
+  /**
+   * The model id used by the remote provider in model settings and for specifying the
+   * intended model for text generation.
+   */
+  id: string;
+
+  /**
+   * The display name of the model for presentation in user-facing contexts.
+   */
+  name: string;
+
+  /**
+   * Optional description of the model.
+   */
+  description?: string | null;
+
+  /**
+   * Optional pricing information for the model.
+   */
+  pricing?: {
+    /**
+     * Cost per input token in USD.
+     */
+    input: string;
+    /**
+     * Cost per output token in USD.
+     */
+    output: string;
+    /**
+     * Cost per cached input token in USD.
+     * Only present for providers/models that support prompt caching.
+     */
+    cachedInputTokens?: string;
+    /**
+     * Cost per input token to create/write cache entries in USD.
+     * Only present for providers/models that support prompt caching.
+     */
+    cacheCreationInputTokens?: string;
+  } | null;
+
+  /**
+   * Additional AI SDK language model specifications for the model.
+   */
+  specification: GatewayLanguageModelSpecification;
+
+  /**
+   * Optional field to differentiate between model types.
+   */
+  modelType?: 'language' | 'embedding' | 'image' | null;
+}
+
+export type GatewayLanguageModelSpecification = Pick<
+  LanguageModelV3,
+  'specificationVersion' | 'provider' | 'modelId'
+>;

package/src/gateway-provider-options.ts

@@ -0,0 +1,66 @@
+import { InferSchema, lazySchema, zodSchema } from '@ai-sdk/provider-utils';
+import { z } from 'zod/v4';
+
+// https://vercel.com/docs/ai-gateway/provider-options
+const gatewayProviderOptions = lazySchema(() =>
+  zodSchema(
+    z.object({
+      /**
+       * Array of provider slugs that are the only ones allowed to be used.
+       *
+       * Example: `['azure', 'openai']` will only allow Azure and OpenAI to be used.
+       */
+      only: z.array(z.string()).optional(),
+      /**
+       * Array of provider slugs that specifies the sequence in which providers should be attempted.
+       *
+       * Example: `['bedrock', 'anthropic']` will try Amazon Bedrock first, then Anthropic as fallback.
+       */
+      order: z.array(z.string()).optional(),
+      /**
+       * The unique identifier for the end user on behalf of whom the request was made.
+       *
+       * Used for spend tracking and attribution purposes.
+       */
+      user: z.string().optional(),
+      /**
+       * User-specified tags for use in reporting and filtering usage.
+       *
+       * For example, spend tracking reporting by feature or prompt version.
+       *
+       * Example: `['chat', 'v2']`
+       */
+      tags: z.array(z.string()).optional(),
+      /**
+       * Array of model slugs specifying fallback models to use in order.
+       *
+       * Example: `['openai/gpt-5-nano', 'zai/glm-4.6']` will try `openai/gpt-5-nano` first, then `zai/glm-4.6` as fallback.
+       */
+      models: z.array(z.string()).optional(),
+      /**
+       * Request-scoped BYOK credentials to use instead of cached credentials.
+       *
+       * When provided, cached BYOK credentials are ignored entirely.
+       *
+       * Each provider can have multiple credentials (tried in order).
+       *
+       * Examples:
+       * - Simple: `{ 'anthropic': [{ apiKey: 'sk-ant-...' }] }`
+       * - Multiple: `{ 'vertex': [{ projectId: 'proj-1', privateKey: '...' }, { projectId: 'proj-2', privateKey: '...' }] }`
+       * - Multi-provider: `{ 'anthropic': [{ apiKey: '...' }], 'bedrock': [{ accessKeyId: '...', secretAccessKey: '...' }] }`
+       */
+      byok: z
+        .record(z.string(), z.array(z.record(z.string(), z.unknown())))
+        .optional(),
+      /**
+       * Whether to filter by only providers that state they have zero data
+       * retention with Vercel AI Gateway. When enabled, only providers that
+       * have agreements with Vercel AI Gateway for zero data retention will be
+       * used.
+       */
+      zeroDataRetention: z.boolean().optional(),
+    }),
+  ),
+);
+
+export type GatewayProviderOptions = InferSchema<typeof gatewayProviderOptions>;

package/src/gateway-provider.ts

@@ -0,0 +1,284 @@
+import {
+  loadOptionalSetting,
+  withoutTrailingSlash,
+  type FetchFunction,
+} from '@ai-sdk/provider-utils';
+import { asGatewayError, GatewayAuthenticationError } from './errors';
+import {
+  GATEWAY_AUTH_METHOD_HEADER,
+  parseAuthMethod,
+} from './errors/parse-auth-method';
+import {
+  GatewayFetchMetadata,
+  type GatewayFetchMetadataResponse,
+  type GatewayCreditsResponse,
+} from './gateway-fetch-metadata';
+import { GatewayLanguageModel } from './gateway-language-model';
+import { GatewayEmbeddingModel } from './gateway-embedding-model';
+import { GatewayImageModel } from './gateway-image-model';
+import type { GatewayEmbeddingModelId } from './gateway-embedding-model-settings';
+import type { GatewayImageModelId } from './gateway-image-model-settings';
+import { gatewayTools } from './gateway-tools';
+import { getVercelOidcToken, getVercelRequestId } from './vercel-environment';
+import type { GatewayModelId } from './gateway-language-model-settings';
+import type {
+  LanguageModelV3,
+  EmbeddingModelV3,
+  ImageModelV3,
+  ProviderV3,
+} from '@ai-sdk/provider';
+import { withUserAgentSuffix } from '@ai-sdk/provider-utils';
+import { VERSION } from './version';
+
+export interface GatewayProvider extends ProviderV3 {
+  (modelId: GatewayModelId): LanguageModelV3;
+
+  /**
+Creates a model for text generation.
+*/
+  languageModel(modelId: GatewayModelId): LanguageModelV3;
+
+  /**
+Returns available providers and models for use with the remote provider.
+ */
+  getAvailableModels(): Promise<GatewayFetchMetadataResponse>;
+
+  /**
+Returns credit information for the authenticated user.
+ */
+  getCredits(): Promise<GatewayCreditsResponse>;
+
+  /**
+Creates a model for generating text embeddings.
+*/
+  embeddingModel(modelId: GatewayEmbeddingModelId): EmbeddingModelV3;
+
+  /**
+   * @deprecated Use `embeddingModel` instead.
+   */
+  textEmbeddingModel(modelId: GatewayEmbeddingModelId): EmbeddingModelV3;
+
+  /**
+Creates a model for generating images.
+*/
+  imageModel(modelId: GatewayImageModelId): ImageModelV3;
+
+  /**
+Gateway-specific tools executed server-side.
+*/
+  tools: typeof gatewayTools;
+}
+
+export interface GatewayProviderSettings {
+  /**
+The base URL prefix for API calls. Defaults to `https://ai-gateway.vercel.sh/v1/ai`.
+   */
+  baseURL?: string;
+
+  /**
+API key that is being sent using the `Authorization` header.
+   */
+  apiKey?: string;
+
+  /**
+Custom headers to include in the requests.
+     */
+  headers?: Record<string, string>;
+
+  /**
+Custom fetch implementation. You can use it as a middleware to intercept requests,
+or to provide a custom fetch implementation for e.g. testing.
+    */
+  fetch?: FetchFunction;
+
+  /**
+How frequently to refresh the metadata cache in milliseconds.
+   */
+  metadataCacheRefreshMillis?: number;
+
+  /**
+   * @internal For testing purposes only
+   */
+  _internal?: {
+    currentDate?: () => Date;
+  };
+}
+
+const AI_GATEWAY_PROTOCOL_VERSION = '0.0.1';
+
+/**
+Create a remote provider instance.
+ */
+export function createGatewayProvider(
+  options: GatewayProviderSettings = {},
+): GatewayProvider {
+  let pendingMetadata: Promise<GatewayFetchMetadataResponse> | null = null;
+  let metadataCache: GatewayFetchMetadataResponse | null = null;
+  const cacheRefreshMillis =
+    options.metadataCacheRefreshMillis ?? 1000 * 60 * 5;
+  let lastFetchTime = 0;
+
+  const baseURL =
+    withoutTrailingSlash(options.baseURL) ??
+    'https://ai-gateway.vercel.sh/v3/ai';
+
+  const getHeaders = async () => {
+    try {
+      const auth = await getGatewayAuthToken(options);
+      return withUserAgentSuffix(
+        {
+          Authorization: `Bearer ${auth.token}`,
+          'ai-gateway-protocol-version': AI_GATEWAY_PROTOCOL_VERSION,
+          [GATEWAY_AUTH_METHOD_HEADER]: auth.authMethod,
+          ...options.headers,
+        },
+        `ai-sdk/gateway/${VERSION}`,
+      );
+    } catch (error) {
+      throw GatewayAuthenticationError.createContextualError({
+        apiKeyProvided: false,
+        oidcTokenProvided: false,
+        statusCode: 401,
+        cause: error,
+      });
+    }
+  };
+
+  const createO11yHeaders = () => {
+    const deploymentId = loadOptionalSetting({
+      settingValue: undefined,
+      environmentVariableName: 'VERCEL_DEPLOYMENT_ID',
+    });
+    const environment = loadOptionalSetting({
+      settingValue: undefined,
+      environmentVariableName: 'VERCEL_ENV',
+    });
+    const region = loadOptionalSetting({
+      settingValue: undefined,
+      environmentVariableName: 'VERCEL_REGION',
+    });
+
+    return async () => {
+      const requestId = await getVercelRequestId();
+      return {
+        ...(deploymentId && { 'ai-o11y-deployment-id': deploymentId }),
+        ...(environment && { 'ai-o11y-environment': environment }),
+        ...(region && { 'ai-o11y-region': region }),
+        ...(requestId && { 'ai-o11y-request-id': requestId }),
+      };
+    };
+  };
+
+  const createLanguageModel = (modelId: GatewayModelId) => {
+    return new GatewayLanguageModel(modelId, {
+      provider: 'gateway',
+      baseURL,
+      headers: getHeaders,
+      fetch: options.fetch,
+      o11yHeaders: createO11yHeaders(),
+    });
+  };
+
+  const getAvailableModels = async () => {
+    const now = options._internal?.currentDate?.().getTime() ?? Date.now();
+    if (!pendingMetadata || now - lastFetchTime > cacheRefreshMillis) {
+      lastFetchTime = now;
+
+      pendingMetadata = new GatewayFetchMetadata({
+        baseURL,
+        headers: getHeaders,
+        fetch: options.fetch,
+      })
+        .getAvailableModels()
+        .then(metadata => {
+          metadataCache = metadata;
+          return metadata;
+        })
+        .catch(async (error: unknown) => {
+          throw await asGatewayError(
+            error,
+            await parseAuthMethod(await getHeaders()),
+          );
+        });
+    }
+
+    return metadataCache ? Promise.resolve(metadataCache) : pendingMetadata;
+  };
+
+  const getCredits = async () => {
+    return new GatewayFetchMetadata({
+      baseURL,
+      headers: getHeaders,
+      fetch: options.fetch,
+    })
+      .getCredits()
+      .catch(async (error: unknown) => {
+        throw await asGatewayError(
+          error,
+          await parseAuthMethod(await getHeaders()),
+        );
+      });
+  };
+
+  const provider = function (modelId: GatewayModelId) {
+    if (new.target) {
+      throw new Error(
+        'The Gateway Provider model function cannot be called with the new keyword.',
+      );
+    }
+
+    return createLanguageModel(modelId);
+  };
+
+  provider.specificationVersion = 'v3' as const;
+  provider.getAvailableModels = getAvailableModels;
+  provider.getCredits = getCredits;
+  provider.imageModel = (modelId: GatewayImageModelId) => {
+    return new GatewayImageModel(modelId, {
+      provider: 'gateway',
+      baseURL,
+      headers: getHeaders,
+      fetch: options.fetch,
+      o11yHeaders: createO11yHeaders(),
+    });
+  };
+  provider.languageModel = createLanguageModel;
+  const createEmbeddingModel = (modelId: GatewayEmbeddingModelId) => {
+    return new GatewayEmbeddingModel(modelId, {
+      provider: 'gateway',
+      baseURL,
+      headers: getHeaders,
+      fetch: options.fetch,
+      o11yHeaders: createO11yHeaders(),
+    });
+  };
+  provider.embeddingModel = createEmbeddingModel;
+  provider.textEmbeddingModel = createEmbeddingModel;
+  provider.tools = gatewayTools;
+
+  return provider;
+}
+
+export const gateway = createGatewayProvider();
+
+export async function getGatewayAuthToken(
+  options: GatewayProviderSettings,
+): Promise<{ token: string; authMethod: 'api-key' | 'oidc' }> {
+  const apiKey = loadOptionalSetting({
+    settingValue: options.apiKey,
+    environmentVariableName: 'AI_GATEWAY_API_KEY',
+  });
+
+  if (apiKey) {
+    return {
+      token: apiKey,
+      authMethod: 'api-key',
+    };
+  }
+
+  const oidcToken = await getVercelOidcToken();
+  return {
+    token: oidcToken,
+    authMethod: 'oidc',
+  };
+}

package/src/gateway-tools.ts

@@ -0,0 +1,15 @@
+import { perplexitySearch } from './tool/perplexity-search';
+
+/**
+ * Gateway-specific provider-defined tools.
+ */
+export const gatewayTools = {
+  /**
+   * Search the web using Perplexity's Search API for real-time information,
+   * news, research papers, and articles.
+   *
+   * Provides ranked search results with advanced filtering options including
+   * domain, language, date range, and recency filters.
+   */
+  perplexitySearch,
+};

package/src/index.ts

@@ -0,0 +1,27 @@
+export type { GatewayModelId } from './gateway-language-model-settings';
+export type {
+  GatewayLanguageModelEntry,
+  GatewayLanguageModelSpecification,
+} from './gateway-model-entry';
+export type { GatewayCreditsResponse } from './gateway-fetch-metadata';
+export type { GatewayLanguageModelEntry as GatewayModelEntry } from './gateway-model-entry';
+export {
+  createGatewayProvider,
+  createGatewayProvider as createGateway,
+  gateway,
+} from './gateway-provider';
+export type {
+  GatewayProvider,
+  GatewayProviderSettings,
+} from './gateway-provider';
+export type { GatewayProviderOptions } from './gateway-provider-options';
+export {
+  GatewayError,
+  GatewayAuthenticationError,
+  GatewayInvalidRequestError,
+  GatewayRateLimitError,
+  GatewayModelNotFoundError,
+  GatewayInternalServerError,
+  GatewayResponseError,
+} from './errors';
+export type { GatewayErrorResponse } from './errors';