API Integration

Feature: [one-line name — e.g., "Stripe payment intent integration"]

## What and why

Problem
[What's currently broken or missing? Who is affected and when? What does failure look like today?]

Who this is for
[Specific user or system. "All users" is not specific enough — name the persona, role, or service that initiates or depends on this integration.]

In scope
- [What this integration does]
- [Which endpoints or events it handles]
- [Which environments it covers — sandbox and production, or production only]

Out of scope
- [API endpoints not being connected in this phase]
- [Data not being synced]
- [Error cases being deferred]

Key behaviors
- When [API call succeeds], [outcome for user or system]
- When [API returns error code X], [how the system responds]
- When [rate limit is hit], [retry behavior]
- When [webhook event arrives], [what the system does]

Edge cases
- What happens when the API is unavailable or returns a 5xx error?
- What happens when a webhook event arrives out of order or is duplicated?
- What happens when the token/key expires mid-session?
- What happens when the API returns an unexpected response shape?
- What happens when the same event is processed twice (idempotency)?

Open questions
- [Authentication method confirmed? OAuth, API key, bearer token?]
- [Sandbox credentials available for testing?]
- [Rate limits confirmed with the third-party provider?]
- [Webhook secret for signature verification?]

## Coding agent context

Tech stack
[e.g., "Next.js 14, Node.js backend, Prisma, PostgreSQL — API calls made server-side only"]

Reference files
[e.g., "See /lib/integrations/stripe.ts for existing Stripe setup; /hooks/useWebhook.ts for webhook handler pattern"]

Patterns to follow
- [e.g., "Use the existing retry utility in /lib/retry.ts — exponential backoff, 3 attempts max"]
- [e.g., "All API calls go through /lib/api-client.ts — do not make fetch calls directly from components"]
- [e.g., "Webhook handlers follow the pattern in /pages/api/webhooks/stripe.ts"]

Do not
- [ ] Do not hardcode API keys, secrets, or tokens — use environment variables only
- [ ] Do not log request bodies that may contain sensitive data (card numbers, tokens, PII)
- [ ] Do not skip rate limit handling — implement backoff before the API enforces it
- [ ] Do not assume webhook events arrive in order — handle out-of-order and duplicate events
- [ ] Do not store raw API responses indefinitely — define a retention policy or don't persist them
- [ ] Do not bypass idempotency — use idempotency keys on any write operation that may be retried

Acceptance criteria
- [ ] Integration works correctly in sandbox/test environment before production credentials are used
- [ ] All defined error codes return appropriate user-facing messages, not raw API errors
- [ ] Rate limit responses (429) trigger retry with exponential backoff, not immediate failure
- [ ] Webhook events are verified against the provider's signature before processing
- [ ] Duplicate webhook events are handled without creating duplicate records
- [ ] No credentials, tokens, or sensitive fields appear in application logs
- [ ] Existing tests pass without modification