API Integration Builder

---
name: api-integration-builder
description: |
  Trigger when the user asks to integrate a third-party API, wire up an SDK,
  or build a client wrapper. Phrases: "integrate API", "connect to", "add
  SDK", "wrap this API", "call their endpoint", "build a client".
allowed-tools:
  - Read
  - Write
  - Edit
  - Bash(pnpm add *)
  - Bash(npm install *)
---

# API Integration Builder

Wrap a third-party HTTP API in a clean, typed client with auth, retries,
rate limit handling, and observability. Prevents vendor calls from leaking
through the whole codebase.

## Prerequisites

- API docs URL and an API key in a secret manager (never in code)
- HTTP client chosen (fetch, undici, axios, ky)
- Typed schema source (OpenAPI spec, hand-written Zod, or vendor SDK types)

## Steps

1. **One module owns the vendor.** All calls to `vendor.com` go through
   `src/integrations/vendor/client.ts`. No component or route calls
   `fetch('https://api.vendor.com/...')` directly. This is the only way
   to migrate off the vendor later without grep archaeology.

2. **Typed request and response.** Validate responses at the boundary with
   Zod (or equivalent). Vendors lie, break contracts, and ship inconsistent
   nulls. Parse, do not trust:
   ```ts
   const User = z.object({ id: z.string(), email: z.string().email() });
   const res = await fetch(url, { headers });
   return User.parse(await res.json());
   ```

3. **Auth handled once.** Inject the token in a single `request()`
   wrapper. Rotate via env var. If the vendor uses OAuth, cache the
   access token and refresh on 401, exactly once.

4. **Retries with jittered backoff.** Retry on 429, 502, 503, 504, and
   network errors. Do not retry on 4xx validation errors. Cap at 3
   retries, full jitter, and honor `Retry-After` headers.

5. **Rate limit awareness.** Read `X-RateLimit-Remaining` and proactively
   slow down before hitting the wall. Token bucket or leaky bucket in
   memory is fine for a single instance; use Redis for horizontally
   scaled workers.

6. **Idempotency for writes.** Pass an `Idempotency-Key` header on every
   POST so safe retries do not double-charge, double-send, or double-create.

7. **Timeouts on every call.** No infinite waits. A 30-second timeout is
   the default; tune per endpoint.

8. **Observability.** Log method, path, status, duration, request ID from
   the vendor, and a correlation ID from your side. Do not log bodies
   (PII and secrets).

9. **Mock in tests.** Use nock, MSW, or a fake server. Never hit the real
   API in CI.

## Patterns that work

- One `Client` class per vendor with methods per endpoint
- Separate `types.ts` for public request/response shapes
- `errors.ts` mapping vendor errors to your domain errors
- A `__fixtures__` folder with real captured responses for tests

## Anti-patterns

- Calling the vendor in React components or route handlers
- Retrying 4xx errors (makes bugs invisible)
- Swallowing errors into `null` so callers cannot distinguish "not found"
  from "the API is down"
- Storing API keys in .env.example with real values

## Output

- `src/integrations/<vendor>/client.ts` with typed methods
- Zod schemas for every response
- Retry, timeout, and rate-limit handling in the wrapper
- MSW or nock fixtures for tests
- README section documenting required env vars