integrate-ai-gateway

AI Gateway Integration (@macpaw/ai-sdk)

Goal

Detect the app shape, choose one integration path, apply the smallest correct patch, add safe auth/error handling, run verification, and report exact changes.

Package surface

• Use @macpaw/ai-sdk for createAIGatewayProvider, createGatewayProvider, createGatewayFetch, createVideoClient, GATEWAY_PROVIDERS, errors, and GatewayProviderSettings.
• Use @macpaw/ai-sdk/provider only as a compatibility alias.
• Use @macpaw/ai-sdk/nestjs for AIGatewayModule, @InjectAIGateway(), and AIGatewayExceptionFilter.
• Do not use createAIGatewayClient, @macpaw/ai-sdk/client, runtime, types, or testing; they do not exist.
• For UI hooks or schema helpers, follow the versioned upstream docs for the installed ai / @ai-sdk/react major version; this package does not redefine those APIs.

Guardrails

• Do not invent a token source. If server-side token retrieval is unclear, ask one question.
• Do not place real tokens in browser-only code. Frontend-only apps need a backend/BFF token source.
• Do not remove direct OpenAI/Anthropic paths unless all usages are migrated or the user asked for it.
• Use baseURL for staging/custom hosts. env supports only 'production'.
• createGatewayFetch requires a resolved baseURL; do not pass only env. Prefer resolveGatewayBaseURL() when you want the default production host.

Choose one path

• NestJS markers: @nestjs/common, *.module.ts, decorators -> use @macpaw/ai-sdk/nestjs + @macpaw/ai-sdk.
• Next.js / Vercel markers: next, ai, @ai-sdk/* -> keep generation on ai, swap only the model provider.
• Express/Fastify/Hono/server scripts -> use createGatewayFetch, or ai + provider if already Vercel-shaped.
• Video generation (create job, poll status, fetch content) -> use createVideoClient.
• Existing openai, @ai-sdk/openai, or @anthropic-ai/sdk usage -> treat as migration, not greenfield.

Canonical patterns

// Vercel AI SDK
const gateway = createAIGatewayProvider({
  env: 'production',
  getAuthToken: async () => process.env.AI_GATEWAY_TOKEN ?? null,
});
const result = streamText({ model: gateway('openai/gpt-4o'), messages });