macpaw/ai-sdk-typescript/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, createVoiceClient, createSpeechClient, createCreditBalanceClient, 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.
• Voice listing (paginated GET /v1/voices) -> use createVoiceClient.
• Speech generation (streaming text-to-speech, POST /v1/audio/speech) -> use createSpeechClient.
• Credit balance queries (active balances, totals) -> use createCreditBalanceClient.
• 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 });

// NestJS
AIGatewayModule.forRootAsync({
  useFactory: () => ({
    env: 'production',
    getAuthToken: async () => process.env.AI_GATEWAY_TOKEN ?? null,
  }),
});
constructor(@InjectAIGateway() private readonly config: GatewayProviderSettings) {}

// Raw fetch / multipart
const baseURL = process.env.AI_GATEWAY_BASE_URL ?? 'https://api.macpaw.com/ai';
const gatewayFetch = createGatewayFetch({
  baseURL,
  getAuthToken: async () => process.env.AI_GATEWAY_TOKEN ?? null,
});

// Video generation
const videos = createVideoClient({
  env: 'production',
  getAuthToken: async () => process.env.AI_GATEWAY_TOKEN ?? null,
});
const job = await videos.create({ model: 'veo-2', prompt: 'A sunset over the ocean' });

// Voice listing
const voices = createVoiceClient({
  env: 'production',
  getAuthToken: async () => process.env.AI_GATEWAY_TOKEN ?? null,
});
const page = await voices.list({ provider: 'elevenlabs' });

// Speech generation (streaming only — never a single buffered audio file)
const speech = createSpeechClient({
  env: 'production',
  getAuthToken: async () => process.env.AI_GATEWAY_TOKEN ?? null,
});
const response = await speech.create({ model: 'openai/gpt-4o-mini-tts', input: 'Hello', voice: 'alloy' });

// Credit balance
const balance = createCreditBalanceClient({
  env: 'production',
  getAuthToken: async () => process.env.AI_GATEWAY_TOKEN ?? null,
});
const { data } = await balance.getBalances();
console.log(data.totalAvailable.amount); // e.g. "1000000"

Error handling

• Prefer isAIGatewayError(error) and switch on ErrorCode.
• Use AIGatewayExceptionFilter in NestJS.
• Treat InsufficientCredits / SubscriptionExpired as the billing states; there is no PaymentRequired.

Migration rules

• Keep generateText, streamText, embed, React hooks, and upstream primitives on ai / @ai-sdk/*.
• Replace direct gateway-bound provider construction with createAIGatewayProvider or createGatewayProvider.
• Replace raw HTTP gateway calls with createGatewayFetch.
• Remove old dependencies only after verifying there are no remaining imports/usages.

Verification

• Read package.json scripts before running commands.
• Prefer typecheck, lint, test, and build when available.
• Add one focused smoke path: provider call, route handler, or fetch stub.
• Do not claim success without reporting which verification commands actually ran.

Output contract

• State the chosen path: NestJS, Vercel, or raw fetch.
• List files changed.
• State where the token now comes from.
• State verification run and any manual env step left.