@macpaw/ai-sdk

Thin Vercel AI SDK extension for MacPaw AI Gateway: OpenAI-compatible providers (createAIGatewayProvider, createGatewayProvider), a createGatewayFetch bridge for any HTTP client, 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, 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
• Tree-shakeable — ESM + CJS

Configuration (GatewayProviderSettings)

Used by createAIGatewayProvider, createGatewayProvider, createGatewayFetch, 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. Use relative URLs under the gateway root (e.g. '/api/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('/api/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.

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.