Merge pull request #62 from MacPaw/feat/update-migration

feat: update migration

Author: algolj

MIGRATION.md

@@ -2,6 +2,8 @@
 
 This package is a **small Vercel AI SDK extension** for MacPaw AI Gateway. Upstream **`ai`**, **`@ai-sdk/openai`**, **`@ai-sdk/react`** (or **`ai/react`**) stay the source for core APIs and hooks.
 
+That also means upstream UI/hooks/version migrations stay upstream. If your installed `ai` / `@ai-sdk/react` version changes hook or schema APIs, follow the upstream versioned docs for those packages rather than expecting `@macpaw/ai-sdk` to redefine them.
+
 ## Entry points
 
 | Path                      | Role                                                                                                                                            |
@@ -26,10 +28,14 @@ Replace `createAIGatewayClient` with:
 
 Types for request/response bodies can come from your app, from OpenAI SDK types, or from gateway OpenAPI — they are not re-exported from this package today.
 
+If you want the default production Gateway URL in fetch-only flows, use the public `resolveGatewayBaseURL()` helper and pass the resolved value into `createGatewayFetch()`.
+
 ## If you used `@macpaw/ai-sdk/runtime`
 
 Internals (`executeRequestPipeline`, etc.) are not part of the public API. Prefer `createGatewayFetch` or provider options (`middleware`, `retry`, `timeout`, `fetch`).
 
+The same applies to source-only error helpers: if a helper is not exported from `@macpaw/ai-sdk`, treat it as internal even if you see it in the repository source.
+
 ## Quick import cheatsheet
 
 ```ts

README.md

@@ -30,6 +30,8 @@ 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)
 
 ```ts
@@ -88,9 +90,9 @@ Internal resolution: `resolveConfig()` in `gateway-config.ts`.
 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.
 
 ```ts
-import { createGatewayFetch } from '@macpaw/ai-sdk';
+import { createGatewayFetch, resolveGatewayBaseURL } from '@macpaw/ai-sdk';
 
-const baseURL = 'https://api.macpaw.com/ai'; // or resolve via env: 'production'
+const baseURL = resolveGatewayBaseURL(undefined, 'production', 'gatewayFetch');
 const gatewayFetch = createGatewayFetch({
   baseURL,
   getAuthToken: async () => token,
@@ -106,6 +108,8 @@ const res = await gatewayFetch('/api/v1/images/edits', { method: 'POST', body: f
 
 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.
@@ -147,6 +151,8 @@ Extends `GatewayProviderSettings` plus OpenAI provider settings (without `apiKey
 - `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
 
 ```ts
@@ -199,6 +205,8 @@ AIGatewayModule.forRoot({
 });
 ```
 
+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:
 
 ```ts
@@ -225,6 +233,8 @@ export class ChatService {
 
 `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:

package.json

@@ -56,7 +56,7 @@
   },
   "packageManager": "pnpm@10.15.1",
   "publishConfig": {
-    "access": "restricted"
+    "access": "public"
   },
   "scripts": {
     "build": "tsup",

src/__tests__/gateway-fetch.spec.ts

@@ -353,6 +353,35 @@ describe('createGatewayFetch', () => {
     expect(headers.get('Authorization')).toBe('Bearer secret-bearer');
   });
 
+  it('strips placeholder Authorization before middleware on gateway requests', async () => {
+    let headersSeenByMiddleware: Record<string, string> = {};
+
+    const customFetch = createGatewayFetch({
+      baseURL: 'https://api.macpaw.com/ai',
+      getAuthToken: async () => 'secret-bearer',
+      middleware: [
+        async (request, next) => {
+          headersSeenByMiddleware = { ...request.headers };
+          return next(request);
+        },
+      ],
+    });
+
+    await customFetch(
+      new Request('https://api.macpaw.com/ai/api/v1/chat/completions', {
+        method: 'POST',
+        headers: { Authorization: 'Bearer ai-gateway-auth-via-fetch,' },
+      }),
+    );
+
+    const authHeader = Object.keys(headersSeenByMiddleware).find((k) => k.toLowerCase() === 'authorization');
+    expect(authHeader).toBeUndefined();
+
+    const fetchCall = (globalThis.fetch as ReturnType<typeof vi.fn>).mock.calls[0];
+    const headers = new Headers(fetchCall[1].headers);
+    expect(headers.get('Authorization')).toBe('Bearer secret-bearer');
+  });
+
   it('smoke: retries on 429 with Retry-After header and succeeds on second attempt', async () => {
     // Verifies Retry-After code path executes (retryAfterSeconds > 0).
     // Timing precision is not asserted — see withRetry unit tests for that.

src/__tests__/package-exports.spec.ts

@@ -37,6 +37,8 @@ describe('package exports', () => {
 
   it('publishes the folders required for built code', () => {
     expect(packageJson.files).toContain('dist');
+    expect(packageJson.files).toContain('scripts');
+    expect(packageJson.files).toContain('templates');
     expect(packageJson.files).not.toContain('shims');
   });
 });

src/__tests__/root-entry.spec.ts

@@ -9,6 +9,8 @@ describe('root entry', () => {
     expect(root.createGatewayProvider).toBeDefined();
     expect(root.GATEWAY_PROVIDERS).toBeDefined();
     expect(root.createGatewayFetch).toBeDefined();
+    expect(root.resolveGatewayBaseURL).toBeDefined();
+    expect(root.DEFAULT_BASE_URLS).toBeDefined();
     expect(root.GATEWAY_PLACEHOLDER_API_KEY).toBeDefined();
   });
 

src/gateway-fetch.ts

@@ -117,9 +117,10 @@ export function createGatewayFetch(
       }
     }
 
-    if (!isGatewayRequest) {
-      stripPlaceholderAuthorization(headers, GATEWAY_PLACEHOLDER_API_KEY);
-    }
+    // Always strip the OpenAI placeholder before entering the shared pipeline.
+    // For gateway requests the real Bearer is injected later via getAuthToken();
+    // for non-gateway requests we also avoid leaking the sentinel downstream.
+    stripPlaceholderAuthorization(headers, GATEWAY_PLACEHOLDER_API_KEY);
 
     return executeRequestPipeline(
       resolvedConfig,

src/index.ts

@@ -42,4 +42,5 @@ export type {
 } from './gateway-errors';
 
 // Config types (consumers need these to configure the SDK)
-export type { GatewayProviderSettings, Middleware, RetryConfig } from './gateway-config';
+export { DEFAULT_BASE_URLS, resolveGatewayBaseURL } from './gateway-config';
+export type { Environment, GatewayProviderSettings, Middleware, RetryConfig } from './gateway-config';

templates/AGENTS.md

@@ -9,6 +9,7 @@ Apply these rules when integrating MacPaw AI Gateway.
 - `@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`.
+- 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.
 
 ## Choose one integration path
 
@@ -22,7 +23,7 @@ Apply these rules when integrating MacPaw AI Gateway.
 - 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`.
+- `createGatewayFetch` requires a resolved `baseURL`; prefer `resolveGatewayBaseURL()` when you want the default production host.
 - Remove legacy imports and dependencies only after confirming all usages are migrated.
 
 ## Canonical snippets

templates/CLAUDE.md

@@ -9,13 +9,14 @@ Use this guidance when integrating MacPaw AI Gateway into this project.
 - 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.
+- 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 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`.
+- `createGatewayFetch` requires a resolved `baseURL`; do not pass only `env`. Prefer `resolveGatewayBaseURL()` when you want the default production host.
 - Remove old provider dependencies only after verifying there are no remaining usages.
 
 ## Preferred paths