@macpaw/ai-sdk 0.1.0

package/package.json

@@ -0,0 +1,128 @@
+{
+  "name": "@macpaw/ai-sdk",
+  "version": "0.1.0",
+  "description": "Vercel AI SDK extension layer for AI Gateway with MacPaw and Setapp auth flows",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./provider": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./nestjs": {
+      "import": {
+        "types": "./dist/nestjs/index.d.ts",
+        "default": "./dist/nestjs/index.js"
+      },
+      "require": {
+        "types": "./dist/nestjs/index.d.cts",
+        "default": "./dist/nestjs/index.cjs"
+      }
+    }
+  },
+  "bin": {
+    "macpaw-ai-setup": "./scripts/setup.mjs"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "MIGRATION.md",
+    "CHANGELOG.md",
+    "scripts",
+    "templates"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "publishConfig": {
+    "access": "restricted"
+  },
+  "keywords": [
+    "ai",
+    "ai-sdk-typescript",
+    "ai-sdk",
+    "gateway",
+    "macpaw",
+    "setapp",
+    "openai",
+    "streaming",
+    "sse",
+    "typescript",
+    "vercel-ai-sdk",
+    "nestjs"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/macpaw/ai-sdk-typescript.git"
+  },
+  "homepage": "https://github.com/macpaw/ai-sdk-typescript#readme",
+  "bugs": {
+    "url": "https://github.com/macpaw/ai-sdk-typescript/issues"
+  },
+  "devDependencies": {
+    "@ai-sdk/openai": "3.0.49",
+    "@ai-sdk/provider": "3.0.8",
+    "@eslint/js": "^10.0.1",
+    "@nestjs/common": "^11.1.17",
+    "@semantic-release/changelog": "^6.0.3",
+    "@semantic-release/git": "^10.0.1",
+    "@types/node": "^25.5.0",
+    "eslint": "^10.1.0",
+    "prettier": "^3.8.1",
+    "rxjs": "^7.8.2",
+    "semantic-release": "^25.0.3",
+    "tsup": "^8.5.1",
+    "typedoc": "^0.28.18",
+    "typescript": "^6.0.2",
+    "typescript-eslint": "^8.58.0",
+    "@vitest/coverage-v8": "^4.1.2",
+    "vitest": "^4.1.2"
+  },
+  "peerDependencies": {
+    "@ai-sdk/openai": "^3.0.0",
+    "@nestjs/common": ">=10.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@nestjs/common": {
+      "optional": true
+    }
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "docs": "typedoc",
+    "docs:watch": "typedoc --watch",
+    "size:pack": "npm pack --dry-run",
+    "verify:release": "pnpm typecheck && pnpm lint && pnpm test && pnpm build && pnpm size:pack",
+    "example:provider": "pnpm build && node examples/vercel-provider.mjs"
+  }
+}

package/scripts/setup.mjs

@@ -0,0 +1,90 @@
+#!/usr/bin/env node
+/**
+ * Sets up AI coding assistant integration for the current project.
+ * Supports Cursor (skill), Claude Code (CLAUDE.md), and OpenAI Codex (AGENTS.md).
+ *
+ * Usage:
+ *   pnpm exec macpaw-ai-setup          # set up all three
+ *   pnpm exec macpaw-ai-setup cursor   # Cursor skill only
+ *   pnpm exec macpaw-ai-setup claude   # Claude Code only
+ *   pnpm exec macpaw-ai-setup codex    # OpenAI Codex only
+ */
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+import fs from 'node:fs';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const pkgRoot = path.resolve(__dirname, '..');
+const projectRoot = process.cwd();
+
+if (fs.realpathSync(pkgRoot) === fs.realpathSync(projectRoot)) {
+  console.log('ℹ  Running inside the @macpaw/ai-sdk repo itself — nothing to copy.');
+  process.exit(0);
+}
+
+const tool = process.argv[2]?.toLowerCase();
+const validTools = ['cursor', 'claude', 'codex'];
+
+if (tool && !validTools.includes(tool)) {
+  console.error(`Unknown tool "${tool}". Valid options: ${validTools.join(', ')} (or omit to set up all).`);
+  process.exit(1);
+}
+
+const all = !tool;
+const results = [];
+
+// --- Cursor Skill ---
+if (all || tool === 'cursor') {
+  const packagedCursorSkill = path.join(pkgRoot, 'templates', 'cursor', 'skills', 'integrate-ai-gateway');
+  const repoCursorSkill = path.join(pkgRoot, '.cursor', 'skills', 'integrate-ai-gateway');
+  const src = fs.existsSync(packagedCursorSkill) ? packagedCursorSkill : repoCursorSkill;
+  const destDir = path.join(projectRoot, '.cursor', 'skills');
+  const dest = path.join(destDir, 'integrate-ai-gateway');
+
+  if (!fs.existsSync(src)) {
+    results.push('✗ Cursor skill source not found (is @macpaw/ai-sdk installed?)');
+  } else {
+    fs.mkdirSync(destDir, { recursive: true });
+    fs.cpSync(src, dest, { recursive: true });
+    results.push('✓ Cursor skill → .cursor/skills/integrate-ai-gateway/');
+  }
+}
+
+// --- Claude Code (CLAUDE.md) ---
+if (all || tool === 'claude') {
+  results.push(copyMarkdownTemplate('CLAUDE.md', 'Claude Code'));
+}
+
+// --- OpenAI Codex (AGENTS.md) ---
+if (all || tool === 'codex') {
+  results.push(copyMarkdownTemplate('AGENTS.md', 'OpenAI Codex'));
+}
+
+console.log('\n  @macpaw/ai-sdk — AI Assistant Setup\n');
+results.forEach((r) => console.log(`  ${r}`));
+console.log('\n  Now ask your AI assistant: "Integrate AI Gateway into this app"\n');
+
+// ---------------------------------------------------------------------------
+
+function copyMarkdownTemplate(filename, toolName) {
+  const src = path.join(pkgRoot, 'templates', filename);
+  const dest = path.join(projectRoot, filename);
+
+  if (!fs.existsSync(src)) {
+    return `✗ ${filename} template not found (is @macpaw/ai-sdk installed?)`;
+  }
+
+  const content = fs.readFileSync(src, 'utf8');
+
+  if (fs.existsSync(dest)) {
+    const existing = fs.readFileSync(dest, 'utf8');
+    if (existing.includes('@macpaw/ai-sdk')) {
+      return `· ${filename} already contains AI Gateway instructions — skipped`;
+    }
+    fs.appendFileSync(dest, '\n\n' + content);
+    return `✓ AI Gateway instructions appended to existing ${filename} (${toolName})`;
+  }
+
+  fs.writeFileSync(dest, content);
+  return `✓ ${filename} created (${toolName})`;
+}

package/templates/AGENTS.md

@@ -0,0 +1,51 @@
+# @macpaw/ai-sdk — AI Gateway Instructions
+
+Apply these rules when integrating MacPaw AI Gateway.
+
+## Use the correct package surface
+
+- `@macpaw/ai-sdk`: `createAIGatewayProvider`, `createGatewayProvider`, `createGatewayFetch`, errors, `GatewayProviderSettings`.
+- `@macpaw/ai-sdk/provider`: compatibility alias only.
+- `@macpaw/ai-sdk/nestjs`: NestJS module and decorators.
+- Install `@ai-sdk/openai` when using `createAIGatewayProvider` or `createGatewayProvider`.
+- Never use `createAIGatewayClient`, `@macpaw/ai-sdk/client`, `runtime`, `types`, or `testing`.
+
+## Choose one integration path
+
+- NestJS app: use `AIGatewayModule` and `@InjectAIGateway()`.
+- Next.js / Vercel AI SDK app: keep generation on `ai`, replace only the model provider.
+- Raw server or multipart HTTP flow: use `createGatewayFetch`.
+- Existing `openai` / `@ai-sdk/openai` / `@anthropic-ai/sdk` usage: treat as migration.
+
+## Guardrails
+
+- Do not invent a token source. Ask once if unclear.
+- Do not place gateway tokens in browser-only code.
+- `env` supports only `'production'`; use `baseURL` for staging/custom hosts.
+- `createGatewayFetch` requires `baseURL`.
+- Remove legacy imports and dependencies only after confirming all usages are migrated.
+
+## Canonical snippets
+
+```ts
+const gateway = createAIGatewayProvider({
+  env: 'production',
+  getAuthToken: async () => process.env.AI_GATEWAY_TOKEN ?? null,
+});
+```
+
+```ts
+const gatewayFetch = createGatewayFetch({
+  baseURL: process.env.AI_GATEWAY_BASE_URL ?? 'https://api.macpaw.com/ai',
+  getAuthToken: async () => process.env.AI_GATEWAY_TOKEN ?? null,
+});
+```
+
+## Error handling and verification
+
+- Use `isAIGatewayError(error)` with `ErrorCode`.
+- Prefer `AIGatewayExceptionFilter` in NestJS.
+- Read available scripts from `package.json` before running checks.
+- Run the relevant subset of `typecheck`, `lint`, `test`, and `build`.
+- Report the chosen path, changed files, token source, checks run, and remaining manual steps.
+- If env variables were added or required, name them explicitly, e.g. `AI_GATEWAY_TOKEN` and `AI_GATEWAY_BASE_URL`.

package/templates/CLAUDE.md

@@ -0,0 +1,55 @@
+# @macpaw/ai-sdk — AI Gateway Integration
+
+Use this guidance when integrating MacPaw AI Gateway into this project.
+
+## Rules
+
+- Use `@macpaw/ai-sdk` for `createAIGatewayProvider`, `createGatewayProvider`, `createGatewayFetch`, errors, and `GatewayProviderSettings`.
+- Use `@macpaw/ai-sdk/nestjs` for `AIGatewayModule`, `@InjectAIGateway()`, and `AIGatewayExceptionFilter`.
+- Keep generation primitives on upstream `ai` / `@ai-sdk/*`.
+- Install `@ai-sdk/openai` when using `createAIGatewayProvider` or `createGatewayProvider`; those paths depend on the OpenAI-compatible provider package.
+- Do not use `createAIGatewayClient`, `@macpaw/ai-sdk/client`, `runtime`, `types`, or `testing`; those surfaces do not exist.
+
+## Guardrails
+
+- Do not invent a token source. If server-side token retrieval is unclear, ask one concise question.
+- Do not put real gateway tokens in browser-only code.
+- Use `env: 'production'` only for the default MacPaw host. Use `baseURL` for staging or custom hosts.
+- `createGatewayFetch` requires a resolved `baseURL`; do not pass only `env`.
+- Remove old provider dependencies only after verifying there are no remaining usages.
+
+## Preferred paths
+
+- NestJS: register `AIGatewayModule.forRoot()` / `forRootAsync()`, inject `GatewayProviderSettings` via `@InjectAIGateway()`, build the provider inside services.
+- Next.js / Vercel AI SDK: keep `generateText`, `streamText`, hooks, and other Vercel APIs on `ai`; swap only the model provider to `createAIGatewayProvider`.
+- Raw server HTTP or multipart: use `createGatewayFetch`.
+
+## Minimal examples
+
+```ts
+const gateway = createAIGatewayProvider({
+  env: 'production',
+  getAuthToken: async () => process.env.AI_GATEWAY_TOKEN ?? null,
+});
+```
+
+```ts
+const gatewayFetch = createGatewayFetch({
+  baseURL: process.env.AI_GATEWAY_BASE_URL ?? 'https://api.macpaw.com/ai',
+  getAuthToken: async () => process.env.AI_GATEWAY_TOKEN ?? null,
+});
+```
+
+## Error handling
+
+- Prefer `isAIGatewayError(error)` and switch on `ErrorCode`.
+- For NestJS, prefer `AIGatewayExceptionFilter`.
+- Billing states are `InsufficientCredits` / `SubscriptionExpired`.
+
+## Verification
+
+- Read `package.json` scripts first.
+- Run the relevant subset of `typecheck`, `lint`, `test`, and `build`.
+- Add one focused smoke path when integrating.
+- Report: chosen integration path, files changed, token source, verification run, and any manual env steps left.
+- If env variables were added or required, name them explicitly, e.g. `AI_GATEWAY_TOKEN` and `AI_GATEWAY_BASE_URL`.

package/templates/cursor/skills/integrate-ai-gateway/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: integrate-ai-gateway
+description: Integrate applications with AI Gateway using @macpaw/ai-sdk. Use for NestJS, Next.js, Vercel AI SDK, raw fetch migrations, MacPaw AI, Setapp AI, createAIGatewayProvider, createGatewayFetch, and AI Gateway auth/error wiring.
+---
+
+# 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`, `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.
+
+## 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`.
+
+## 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.
+- Existing `openai`, `@ai-sdk/openai`, or `@anthropic-ai/sdk` usage -> treat as migration, not greenfield.
+
+## Canonical patterns
+
+```ts
+// 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 });
+```
+
+```ts
+// NestJS
+AIGatewayModule.forRootAsync({
+  useFactory: () => ({
+    env: 'production',
+    getAuthToken: async () => process.env.AI_GATEWAY_TOKEN ?? null,
+  }),
+});
+constructor(@InjectAIGateway() private readonly config: GatewayProviderSettings) {}
+```
+
+```ts
+// 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,
+});
+```
+
+## 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.