@macpaw/ai-sdk

Thin Vercel AI SDK extension for MacPaw AI Gateway: OpenAI-compatible providers (createAIGatewayProvider, createGatewayProvider), a createGatewayFetch bridge for any HTTP client, createVideoClient / createVoiceClient / createSpeechClient for video generation, voice listing, and text-to-speech, a createCreditBalanceClient for querying AI credit balances, shared auth / retry / middleware / errors, and optional NestJS wiring.

Core generation APIs stay on upstream ai and @ai-sdk/*. This package only adds Gateway-specific construction and the fetch pipeline.

Package entry points

Import	Use for
@macpaw/ai-sdk	Canonical — providers, createGatewayFetch, createVideoClient, createVoiceClient, createSpeechClient, createCreditBalanceClient, errors, config types
@macpaw/ai-sdk/provider	Alias of the root entry (same dist; for older snippets)
@macpaw/ai-sdk/nestjs	AIGatewayModule, @InjectAIGateway(), AIGatewayExceptionFilter

Upstream ai, @ai-sdk/openai, @ai-sdk/react (or ai/react) remain the home for Vercel primitives and React hooks.

There is no published @macpaw/ai-sdk/client, @macpaw/ai-sdk/runtime, @macpaw/ai-sdk/types, or @macpaw/ai-sdk/testing in this version — use createGatewayFetch + fetch (or the OpenAI SDK with custom fetch) for raw HTTP and multipart. See MIGRATION.md.

Install

pnpm add @macpaw/ai-sdk
# or
npm install @macpaw/ai-sdk

Also install upstream packages you call directly, for example ai, @ai-sdk/openai, @ai-sdk/react.

This package does not pin or wrap the upstream UI/hooks API from ai / @ai-sdk/react. Follow the versioned upstream docs for the exact major version you install there. If your chosen upstream version requires version-specific imports or patterns (for example schema helpers), use the upstream guidance for those APIs.

Quick start (Vercel AI SDK)

import { generateText, streamText } from 'ai';
import { createAIGatewayProvider, ErrorCode } from '@macpaw/ai-sdk';

const gateway = createAIGatewayProvider({
  env: 'production',
  getAuthToken: async () => (await getSetappSession()).accessToken,
});

const { text } = await generateText({
  model: gateway('openai/gpt-4.1-nano'),
  prompt: 'Hello from AI Gateway',
});

const result = streamText({
  model: gateway('openai/gpt-4.1-nano'),
  prompt: 'Write a poem',
});
for await (const delta of result.textStream) {
  process.stdout.write(delta);
}

Features

• Vercel-first — OpenAIProvider from @ai-sdk/openai + custom fetch
• Auth — getAuthToken(forceRefresh?); one automatic retry on 401 with forceRefresh === true
• Retry — exponential backoff for 429 and 5xx (and some network errors); not for 401/402
• Middleware — (config, next) => Promise<Response> chain before fetch
• Errors — Gateway JSON and OpenAI-shaped bodies → AIGatewayError subclasses + ErrorCode
• Request ID — X-Request-ID on Gateway requests when missing
• Timeout — per attempt, combined with caller AbortSignal
• Video generation — createVideoClient wraps the Gateway video endpoints (create job, poll status, fetch content)
• Voices — createVoiceClient lists voices from Gateway providers (paginated GET /v1/voices)
• Speech (text-to-speech) — createSpeechClient generates streaming speech audio (POST /v1/audio/speech)
• Credit balances — createCreditBalanceClient fetches active AI credit balances for the authenticated user
• Tree-shakeable — ESM + CJS

Configuration (GatewayProviderSettings)

Used by createAIGatewayProvider, createGatewayProvider, createGatewayFetch, createVideoClient, createVoiceClient, createSpeechClient, createCreditBalanceClient, and Nest AIGatewayModule.

Field	Purpose
getAuthToken	Required — Promise<string | null>; true = refresh after 401
env	'production' → default base URL https://api.macpaw.com/ai
baseURL	Override gateway root (staging, etc.)
headers	Extra headers (do not set Authorization here)
retry	RetryConfig or false
timeout	ms per attempt (default 60000)
middleware	Interceptor stack
fetch	Custom fetch implementation

Internal resolution: resolveConfig() in gateway-config.ts.

createGatewayFetch — raw HTTP / multipart

Same auth, retry, middleware, and error normalization as the provider path. The base already includes /ai, so use relative URLs under it (e.g. '/v1/images/edits', which resolves to https://api.macpaw.com/ai/v1/images/edits) or absolute URLs that stay under the same gateway origin.

import { createGatewayFetch, resolveGatewayBaseURL } from '@macpaw/ai-sdk';

const baseURL = resolveGatewayBaseURL(undefined, 'production', 'gatewayFetch');
const gatewayFetch = createGatewayFetch({
  baseURL,
  getAuthToken: async () => token,
});

const form = new FormData();
form.append('image', imageBlob, 'photo.png');
form.append('prompt', 'Add a hat');
form.append('model', 'openai/dall-e-2');

const res = await gatewayFetch('/v1/images/edits', { method: 'POST', body: form });

Non-gateway absolute URLs are passed through without injecting Bearer auth (placeholder key is stripped). See gateway-fetch.ts.

createGatewayFetch requires a resolved baseURL. Use the exported resolveGatewayBaseURL() helper if you want the same 'production' shortcut that provider factories support.

createGatewayProvider — prefixed model IDs

Bare model IDs get a default Gateway prefix per provider constant; IDs that already contain / are unchanged.

Constant	Default prefix
GATEWAY_PROVIDERS.ANTHROPIC	anthropic
GATEWAY_PROVIDERS.GOOGLE	google
GATEWAY_PROVIDERS.XAI	xai
GATEWAY_PROVIDERS.GROQ	groq
GATEWAY_PROVIDERS.MISTRAL	mistral
GATEWAY_PROVIDERS.AMAZON_BEDROCK	bedrock
GATEWAY_PROVIDERS.AZURE	azure
GATEWAY_PROVIDERS.COHERE	cohere
GATEWAY_PROVIDERS.PERPLEXITY	perplexity
GATEWAY_PROVIDERS.DEEPSEEK	deepseek
GATEWAY_PROVIDERS.TOGETHERAI	togetherai
GATEWAY_PROVIDERS.OPENAI_COMPATIBLE	requires modelPrefix in options

import { generateText } from 'ai';
import { createGatewayProvider, GATEWAY_PROVIDERS } from '@macpaw/ai-sdk';

const anthropic = createGatewayProvider(GATEWAY_PROVIDERS.ANTHROPIC, {
  env: 'production',
  getAuthToken: async () => token,
});

await generateText({
  model: anthropic('claude-sonnet-4-20250514'),
  prompt: 'Hello',
});

Provider options (AIGatewayProviderOptions)

Extends GatewayProviderSettings plus OpenAI provider settings (without apiKey / baseURL / fetch, which are wired by the SDK):

• normalizeErrors — default true; non-OK Gateway responses throw typed errors
• createOpenAI — optional override of createOpenAI from @ai-sdk/openai (tests/advanced)

Use normalizeErrors: false only when you intentionally want to inspect raw failed Response objects in provider-driven tests or adapters. Auth refresh and retry behavior still stay on; only typed non-OK error throwing is relaxed.

createVideoClient — video generation

Wraps three Gateway endpoints: create a job, poll its status, and fetch binary content. Same auth and error normalization as the other clients.

import { createVideoClient } from '@macpaw/ai-sdk';

const videos = createVideoClient({
  env: 'production',
  getAuthToken: async () => (await getSetappSession()).accessToken,
});

const job = await videos.create({
  model: 'veo-2',
  prompt: 'A sunset over the ocean',
  seconds: '5',
  size: '1280x720',
});

let current = job;
while (current.status !== 'completed' && current.status !== 'failed') {
  await new Promise((r) => setTimeout(r, 3000));
  current = await videos.get(job.id);
}

const res = await videos.getContent(job.id, 'video');
const buffer = await res.arrayBuffer();

getContent returns the raw Response so callers can consume .arrayBuffer(), .blob(), or .body as a stream — the Content-Type is provider-dependent (video/mp4, image/jpeg, etc.). Pass 'thumbnail' or 'spritesheet' as the second argument to fetch those variants instead.

create does not retry on 5xx — POST video jobs are non-idempotent. Auth retry (401 → fresh token) still applies.

createVoiceClient — list voices

Wraps GET /v1/voices. Same auth, retry, and error normalization as the other clients. provider is required; "elevenlabs" is the only Gateway provider today, but any future provider id can be passed as a string.

import { createVoiceClient } from '@macpaw/ai-sdk';

const voices = createVoiceClient({
  env: 'production',
  getAuthToken: async () => (await getSetappSession()).accessToken,
});

const first = await voices.list({ provider: 'elevenlabs' });
for (const voice of first.voices) {
  console.log(voice.voice_id);
}

if (first.has_more) {
  const next = await voices.list({
    provider: 'elevenlabs',
    next_page_token: first.next_page_token,
  });
  console.log(next.voices.length);
}

Each Voice always has voice_id; other fields are provider-specific and passed through as-is. list() is a GET, so config-level retries on 429 / 5xx still apply. Auth retry (401 → fresh token) also applies.

createSpeechClient — text-to-speech

Wraps POST /v1/audio/speech. Streaming only — the response is always Server-Sent Events (or the provider's own raw stream when raw_provider_response: true), never a single buffered file, so create() returns the raw Response for callers to consume as a stream. model (provider/model), input, and voice are required; every other parameter is validated per model by the Gateway, so response_format and any additional model-specific fields are passed straight through.

import { createSpeechClient } from '@macpaw/ai-sdk';

const speech = createSpeechClient({
  env: 'production',
  getAuthToken: async () => (await getSetappSession()).accessToken,
});

const response = await speech.create({
  model: 'openai/gpt-4o-mini-tts',
  input: 'Today is a wonderful day to build something people love!',
  voice: 'alloy',
  response_format: 'mp3',
});

// response.body is a ReadableStream of `text/event-stream` bytes by default —
// parse it as SSE to read `speech.audio.delta` / `speech.audio.done` events.

create() disables config-level retries (POST is non-idempotent — retrying on 5xx risks duplicate provider-side generation and credit charges). Auth retry (401 → fresh token) still applies. Set raw_provider_response: true to receive the selected provider's own stream unmodified (for ElevenLabs, its native JSON stream including alignment data the normalized events cannot carry).

createCreditBalanceClient — AI credit balances

Fetches all active AI credit balances for the user identified by the Bearer token. Balances are ordered FEFO (First Expiring, First Out) and include optional membership metadata.

import { createCreditBalanceClient } from '@macpaw/ai-sdk';

const balance = createCreditBalanceClient({
  env: 'production',
  getAuthToken: async () => (await getSetappSession()).accessToken,
});

const { data } = await balance.getBalances();

console.log(data.totalAvailable.amount); // e.g. "1000000"
console.log(data.totalAvailable.currency); // "MACPAW_CREDITS"

for (const b of data.balances) {
  console.log(b.id, b.currentValue.amount, b.expiresAt);
}

getBalances calls GET /entitlement/v1/ai/credits/balances on the gateway's root domain (derived from your baseURL origin). The response shape mirrors the API spec exactly — data.balances, data.totalAvailable, and data.totalInitialAmount.

Middleware

import type { Middleware } from '@macpaw/ai-sdk';

const loggingMiddleware: Middleware = async (config, next) => {
  const response = await next(config);
  console.log(config.method, config.url, response.status);
  return response;
};

Error handling

ErrorCode	Typical HTTP	Meaning
AuthRequired	401	Token missing / expired
InsufficientCredits / SubscriptionExpired	402	Billing / subscription
ModelNotAllowed	403	Model denied
RateLimited	429	Rate limit (retryAfter when present)
Validation	422	Validation body
…	…	See gateway-errors.ts

import { AIGatewayError, ErrorCode, isAIGatewayError } from '@macpaw/ai-sdk';

try {
  // ...
} catch (e) {
  if (isAIGatewayError(e) && e.code === ErrorCode.InsufficientCredits) {
    // e.metadata.paymentUrl, e.requestId, etc.
  }
}

NestJS

pnpm add @macpaw/ai-sdk @nestjs/common rxjs

Register once (global by default):

import { AIGatewayModule } from '@macpaw/ai-sdk/nestjs';

AIGatewayModule.forRoot({
  env: 'production',
  getAuthToken: async () => process.env.SETAPP_TOKEN!,
});

If your Nest app uses TypeScript subpath exports strictly, make sure its tsconfig uses a modern resolver such as moduleResolution: "Node16", "NodeNext", or "bundler" so @macpaw/ai-sdk/nestjs resolves correctly.

Inject GatewayProviderSettings (not an HTTP client) and build providers in the service:

import { Injectable } from '@nestjs/common';
import { InjectAIGateway } from '@macpaw/ai-sdk/nestjs';
import type { GatewayProviderSettings } from '@macpaw/ai-sdk';
import { createAIGatewayProvider } from '@macpaw/ai-sdk';
import { generateText } from 'ai';

@Injectable()
export class ChatService {
  constructor(@InjectAIGateway() private readonly config: GatewayProviderSettings) {}

  async complete(prompt: string) {
    const gateway = createAIGatewayProvider(this.config);
    const { text } = await generateText({
      model: gateway('openai/gpt-4.1-nano'),
      prompt,
    });
    return text;
  }
}

AIGatewayExceptionFilter maps AIGatewayError to JSON HTTP responses. See examples/nestjs/ for a copy-paste skeleton.

Only documented root exports are public API. Source-level helpers such as parseErrorResponseFromResponse and parseStreamErrorPayload may exist internally, but they are not supported import targets unless exported from @macpaw/ai-sdk.

Examples

From the repo root:

pnpm build
pnpm example:provider

Set AI_GATEWAY_TOKEN or SETAPP_TOKEN. Optional: AI_GATEWAY_BASE_URL, AI_GATEWAY_MODEL.

See examples/README.md.

Release & quality

• CI: typecheck, lint, test, coverage, build on Node 18 / 20 / 22
• pnpm verify:release — full local gate before publish
• pnpm size:pack — dry-run npm pack

AI assistant setup

Templates for Cursor (.cursor/skills/), Claude Code (CLAUDE.md), and OpenAI Codex (AGENTS.md) ship under templates/. After installing the package:

pnpm exec macpaw-ai-setup
# or: npx macpaw-ai-setup

Use macpaw-ai-setup cursor, claude, or codex to install only one target. Existing root CLAUDE.md / AGENTS.md files get Gateway sections appended, not replaced.

The installed instructions enforce the current package surface and the main auth guardrails:

• prefer @macpaw/ai-sdk / @macpaw/ai-sdk/nestjs
• keep generation primitives on upstream ai / @ai-sdk/*
• do not use removed subpaths such as client, runtime, types, or testing
• do not invent a token source or expose gateway tokens to browser-only code
• use baseURL for staging/custom hosts; env supports only 'production'

Versioning

Semantic Versioning. Releases via semantic-release and Conventional Commits.

License

MIT © 2026 MacPaw Way Ltd. See LICENSE.