@ai-sdk/gateway 0.0.0-64aae7dd-20260114144918 → 0.0.0-98261322-20260122142521

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';

package/src/tool/perplexity-search.ts

@@ -0,0 +1,294 @@
+import {
+  createProviderToolFactoryWithOutputSchema,
+  lazySchema,
+  zodSchema,
+} from '@ai-sdk/provider-utils';
+import { z } from 'zod';
+
+export interface PerplexitySearchConfig {
+  /**
+   * Default maximum number of search results to return (1-20, default: 10).
+   */
+  maxResults?: number;
+
+  /**
+   * Default maximum tokens to extract per search result page (256-2048, default: 2048).
+   */
+  maxTokensPerPage?: number;
+
+  /**
+   * Default maximum total tokens across all search results (default: 25000, max: 1000000).
+   */
+  maxTokens?: number;
+
+  /**
+   * Default two-letter ISO 3166-1 alpha-2 country code for regional search results.
+   * Examples: 'US', 'GB', 'FR'
+   */
+  country?: string;
+
+  /**
+   * Default list of domains to include or exclude from search results (max 20).
+   * To include: ['nature.com', 'science.org']
+   * To exclude: ['-example.com', '-spam.net']
+   */
+  searchDomainFilter?: string[];
+
+  /**
+   * Default list of ISO 639-1 language codes to filter results (max 10, lowercase).
+   * Examples: ['en', 'fr', 'de']
+   */
+  searchLanguageFilter?: string[];
+
+  /**
+   * Default recency filter for results.
+   * Cannot be combined with searchAfterDate/searchBeforeDate at runtime.
+   */
+  searchRecencyFilter?: 'day' | 'week' | 'month' | 'year';
+}
+
+export interface PerplexitySearchResult {
+  /** Title of the search result */
+  title: string;
+  /** URL of the search result */
+  url: string;
+  /** Text snippet/preview of the content */
+  snippet: string;
+  /** Publication date of the content */
+  date?: string;
+  /** Last updated date of the content */
+  lastUpdated?: string;
+}
+
+export interface PerplexitySearchResponse {
+  /** Array of search results */
+  results: PerplexitySearchResult[];
+  /** Unique identifier for this search request */
+  id: string;
+}
+
+export interface PerplexitySearchError {
+  /** Error type */
+  error: 'api_error' | 'rate_limit' | 'timeout' | 'invalid_input' | 'unknown';
+  /** HTTP status code if applicable */
+  statusCode?: number;
+  /** Human-readable error message */
+  message: string;
+}
+
+export interface PerplexitySearchInput {
+  /**
+   * Search query (string) or multiple queries (array of up to 5 strings).
+   * Multi-query searches return combined results from all queries.
+   */
+  query: string | string[];
+
+  /**
+   * Maximum number of search results to return (1-20, default: 10).
+   */
+  max_results?: number;
+
+  /**
+   * Maximum number of tokens to extract per search result page (256-2048, default: 2048).
+   */
+  max_tokens_per_page?: number;
+
+  /**
+   * Maximum total tokens across all search results (default: 25000, max: 1000000).
+   */
+  max_tokens?: number;
+
+  /**
+   * Two-letter ISO 3166-1 alpha-2 country code for regional search results.
+   * Examples: 'US', 'GB', 'FR'
+   */
+  country?: string;
+
+  /**
+   * List of domains to include or exclude from search results (max 20).
+   * To include: ['nature.com', 'science.org']
+   * To exclude: ['-example.com', '-spam.net']
+   */
+  search_domain_filter?: string[];
+
+  /**
+   * List of ISO 639-1 language codes to filter results (max 10, lowercase).
+   * Examples: ['en', 'fr', 'de']
+   */
+  search_language_filter?: string[];
+
+  /**
+   * Include only results published after this date.
+   * Format: 'MM/DD/YYYY' (e.g., '3/1/2025')
+   * Cannot be used with search_recency_filter.
+   */
+  search_after_date?: string;
+
+  /**
+   * Include only results published before this date.
+   * Format: 'MM/DD/YYYY' (e.g., '3/15/2025')
+   * Cannot be used with search_recency_filter.
+   */
+  search_before_date?: string;
+
+  /**
+   * Include only results last updated after this date.
+   * Format: 'MM/DD/YYYY' (e.g., '3/1/2025')
+   * Cannot be used with search_recency_filter.
+   */
+  last_updated_after_filter?: string;
+
+  /**
+   * Include only results last updated before this date.
+   * Format: 'MM/DD/YYYY' (e.g., '3/15/2025')
+   * Cannot be used with search_recency_filter.
+   */
+  last_updated_before_filter?: string;
+
+  /**
+   * Filter results by relative time period.
+   * Cannot be used with search_after_date or search_before_date.
+   */
+  search_recency_filter?: 'day' | 'week' | 'month' | 'year';
+}
+
+export type PerplexitySearchOutput =
+  | PerplexitySearchResponse
+  | PerplexitySearchError;
+
+const perplexitySearchInputSchema = lazySchema(() =>
+  zodSchema(
+    z.object({
+      query: z
+        .union([z.string(), z.array(z.string())])
+        .describe(
+          'Search query (string) or multiple queries (array of up to 5 strings). Multi-query searches return combined results from all queries.',
+        ),
+
+      max_results: z
+        .number()
+        .optional()
+        .describe(
+          'Maximum number of search results to return (1-20, default: 10)',
+        ),
+
+      max_tokens_per_page: z
+        .number()
+        .optional()
+        .describe(
+          'Maximum number of tokens to extract per search result page (256-2048, default: 2048)',
+        ),
+
+      max_tokens: z
+        .number()
+        .optional()
+        .describe(
+          'Maximum total tokens across all search results (default: 25000, max: 1000000)',
+        ),
+
+      country: z
+        .string()
+        .optional()
+        .describe(
+          "Two-letter ISO 3166-1 alpha-2 country code for regional search results (e.g., 'US', 'GB', 'FR')",
+        ),
+
+      search_domain_filter: z
+        .array(z.string())
+        .optional()
+        .describe(
+          "List of domains to include or exclude from search results (max 20). To include: ['nature.com', 'science.org']. To exclude: ['-example.com', '-spam.net']",
+        ),
+
+      search_language_filter: z
+        .array(z.string())
+        .optional()
+        .describe(
+          "List of ISO 639-1 language codes to filter results (max 10, lowercase). Examples: ['en', 'fr', 'de']",
+        ),
+
+      search_after_date: z
+        .string()
+        .optional()
+        .describe(
+          "Include only results published after this date. Format: 'MM/DD/YYYY' (e.g., '3/1/2025'). Cannot be used with search_recency_filter.",
+        ),
+
+      search_before_date: z
+        .string()
+        .optional()
+        .describe(
+          "Include only results published before this date. Format: 'MM/DD/YYYY' (e.g., '3/15/2025'). Cannot be used with search_recency_filter.",
+        ),
+
+      last_updated_after_filter: z
+        .string()
+        .optional()
+        .describe(
+          "Include only results last updated after this date. Format: 'MM/DD/YYYY' (e.g., '3/1/2025'). Cannot be used with search_recency_filter.",
+        ),
+
+      last_updated_before_filter: z
+        .string()
+        .optional()
+        .describe(
+          "Include only results last updated before this date. Format: 'MM/DD/YYYY' (e.g., '3/15/2025'). Cannot be used with search_recency_filter.",
+        ),
+
+      search_recency_filter: z
+        .enum(['day', 'week', 'month', 'year'])
+        .optional()
+        .describe(
+          'Filter results by relative time period. Cannot be used with search_after_date or search_before_date.',
+        ),
+    }),
+  ),
+);
+
+const perplexitySearchOutputSchema = lazySchema(() =>
+  zodSchema(
+    z.union([
+      // Success response
+      z.object({
+        results: z.array(
+          z.object({
+            title: z.string(),
+            url: z.string(),
+            snippet: z.string(),
+            date: z.string().optional(),
+            lastUpdated: z.string().optional(),
+          }),
+        ),
+        id: z.string(),
+      }),
+      // Error response
+      z.object({
+        error: z.enum([
+          'api_error',
+          'rate_limit',
+          'timeout',
+          'invalid_input',
+          'unknown',
+        ]),
+        statusCode: z.number().optional(),
+        message: z.string(),
+      }),
+    ]),
+  ),
+);
+
+export const perplexitySearchToolFactory =
+  createProviderToolFactoryWithOutputSchema<
+    PerplexitySearchInput,
+    PerplexitySearchOutput,
+    PerplexitySearchConfig
+  >({
+    id: 'gateway.perplexity_search',
+    inputSchema: perplexitySearchInputSchema,
+    outputSchema: perplexitySearchOutputSchema,
+  });
+
+export const perplexitySearch = (
+  config: PerplexitySearchConfig = {},
+): ReturnType<typeof perplexitySearchToolFactory> =>
+  perplexitySearchToolFactory(config);

package/src/vercel-environment.test.ts

@@ -0,0 +1,65 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { getVercelOidcToken, getVercelRequestId } from './vercel-environment';
+
+const SYMBOL_FOR_REQ_CONTEXT = Symbol.for('@vercel/request-context');
+
+describe('getVercelRequestId', () => {
+  const originalSymbolValue = (globalThis as any)[SYMBOL_FOR_REQ_CONTEXT];
+
+  beforeEach(() => {
+    (globalThis as any)[SYMBOL_FOR_REQ_CONTEXT] = undefined;
+  });
+
+  afterEach(() => {
+    if (originalSymbolValue) {
+      (globalThis as any)[SYMBOL_FOR_REQ_CONTEXT] = originalSymbolValue;
+    } else {
+      (globalThis as any)[SYMBOL_FOR_REQ_CONTEXT] = undefined;
+    }
+  });
+
+  it('should get request ID from request headers when available', async () => {
+    (globalThis as any)[SYMBOL_FOR_REQ_CONTEXT] = {
+      get: () => ({
+        headers: {
+          'x-vercel-id': 'req_1234567890abcdef',
+        },
+      }),
+    };
+
+    const requestId = await getVercelRequestId();
+    expect(requestId).toBe('req_1234567890abcdef');
+  });
+
+  it('should return undefined when request ID header is not available', async () => {
+    (globalThis as any)[SYMBOL_FOR_REQ_CONTEXT] = {
+      get: () => ({ headers: {} }),
+    };
+
+    const requestId = await getVercelRequestId();
+    expect(requestId).toBeUndefined();
+  });
+
+  it('should return undefined when no headers are available', async () => {
+    (globalThis as any)[SYMBOL_FOR_REQ_CONTEXT] = {
+      get: () => ({}),
+    };
+
+    const requestId = await getVercelRequestId();
+    expect(requestId).toBeUndefined();
+  });
+
+  it('should handle missing request context gracefully', async () => {
+    (globalThis as any)[SYMBOL_FOR_REQ_CONTEXT] = undefined;
+
+    const requestId = await getVercelRequestId();
+    expect(requestId).toBeUndefined();
+  });
+
+  it('should handle missing get method in request context', async () => {
+    (globalThis as any)[SYMBOL_FOR_REQ_CONTEXT] = {};
+
+    const requestId = await getVercelRequestId();
+    expect(requestId).toBeUndefined();
+  });
+});

package/src/vercel-environment.ts

@@ -0,0 +1,6 @@
+import { getContext } from '@vercel/oidc';
+export { getVercelOidcToken } from '@vercel/oidc';
+
+export async function getVercelRequestId(): Promise<string | undefined> {
+  return getContext().headers?.['x-vercel-id'];
+}

package/src/version.ts

@@ -0,0 +1,6 @@
+// Version string of this package injected at build time.
+declare const __PACKAGE_VERSION__: string | undefined;
+export const VERSION: string =
+  typeof __PACKAGE_VERSION__ !== 'undefined'
+    ? __PACKAGE_VERSION__
+    : '0.0.0-test';