feat(payments): retry UX gaps — idempotency-key reuse, attempt counter + cooling, error categorization, offline banner, audit log (#43)

[TortoiseWolfe]

Summary

Closes 5 of 7 gaps in #43. The route itself shipped 2026-04-16 (commit `ffb33a1`); this PR closes the retry-UX gaps that were obscured by the original 'route missing' framing (corrected in #62).

Closes (gaps 1-5 of #43):

1. Retry button regenerates `idempotency_key`. `retryFailedPayment()` now reuses the parent's queued key, so a doubled click or a click that races a webhook becomes a server-side ON CONFLICT no-op instead of a duplicate charge. Same pattern as the offline-queue adapter that landed in PR fix(offline-queue): watchdog reclaim + idempotent payment INSERTs (#52) #59.
2. No retry attempt counter or cooling period. `payment_intents` gains `retry_count` + `parent_intent_id`. Service refuses past `RETRY_LIMIT=3` (FR-009); enforces a `COOLING_PERIOD_MS=30s` since parent.created_at (FR-010). New custom error classes carry `waitMs` for UI countdown (FR-008).
3. No error categorization. New `src/lib/payments/error-categorization.ts` maps Stripe + PayPal `error_code` to one of FR-002's 8 categories with non-technical user message + resolution hint + a `recoverable` flag that gates the retry button (FR-001/003/006/NFR-001).
4. No offline error banner. New `OfflineRetryBanner` 5-file component reads `useOfflineStatus` + `paymentQueue.getCount()`. Mounted on `/payment-result`; silent in the steady state.
5. No audit log on retry. `auth_audit_logs` CHECK extended with `payment_retry`. Every retry attempt is recorded with `{ original_intent_id, new_intent_id, retry_count, deduped }` so admin analytics can distinguish a fresh attempt from a server-side dedupe.

Bonus: An expiry guard rejects retry of a parent past its 24h provider session — `PaymentRetryExpiredError`. The same-key retry would have succeeded at the DB but failed at the provider redirect; refusing here gives a clear message instead of a confusing failure.

Deferred to a follow-up PR (gaps 6-7):

• User Story 3 (Update Payment Method, FR-011-FR-015) — has stripe.js + PCI surface considerations that warrant their own design pass.
• User Story 4 (Guided Recovery Wizard, FR-016-FR-019) — largest piece by far.

Commit shape

3 logical commits, easy to review independently:

1. `1bd6949` — schema + types + audit-event enum (~5 files)
2. `faadd2c` — retry service + audit + categorization libs + tests (~5 files, 750 LOC incl. tests)
3. `0653839` — UI surface: hook + status display + offline banner + page mount + e2e (~12 files, 928 LOC incl. tests)

Schema changes

Idempotent ALTERs to `supabase/migrations/20251006_complete_monolithic_setup.sql` (no new tables, no migration files):

• `payment_intents.retry_count INTEGER NOT NULL DEFAULT 0`
• `payment_intents.parent_intent_id UUID REFERENCES payment_intents(id) ON DELETE SET NULL` + partial index
• `auth_audit_logs.event_type` CHECK extended with `'payment_retry'` (DROP + ADD on existing DBs, inline on fresh)

Applied to local Supabase via psql as supabase_admin. Cloud application is the reviewer's call — the migration is idempotent so re-applying is safe; the new columns inherit existing RLS policies (no new policies needed). RLS verification: `pnpm test:rls` 55/55 green locally.

Test plan

• Schema applied locally + verified columns + CHECK constraint
• `pnpm run type-check` — clean
• `pnpm run lint` — clean
• `pnpm test` — 3249/3249 across 286 files (60 new tests for B1)
• `pnpm test:rls` — 55/55 (new columns inherit existing policies as expected)
• CI green on this PR
• Apply schema to Supabase cloud (reviewer judgment — idempotent, safe to re-apply)
• Manual smoke through `/payment-result?id=` once Stripe API keys are live (out of scope here — same prerequisite as [Eval-Backlog] PAYMENT-DASHBOARD: user-facing payment dashboard route #3/[Eval-Backlog] PAYMENT-OFFLINE-UI: UI layer for existing offline payment queue #4/[Eval-Backlog] SUBSCRIPTION-MGMT: subscription management route + 4 edge functions + grace-period wiring #5)

E2E — #53 progress

Un-skipped `should display offline error banner when offline` in `tests/e2e/payment/03-failed-payment-retry.spec.ts`. Closes one row of #53's skip index. The Stripe-Checkout-required skips remain pending those API keys.

Sharp edges

• Cooling period is enforced both client-side (button disabled + countdown) and server-side (thrown error). The hook is a UX hint; the service is the security boundary. A user who tampers with client state still hits the same checks.
• `payment_intents` is INSERT-only. `retry_count` is set on the new (child) row at INSERT time — the parent's count is never mutated. The 'Payment intents are immutable' UPDATE policy enforces this.
• Upsert with `ignoreDuplicates: true` returns null on conflict. The service surfaces that as 'the original intent is the truth' by returning the parent. No double-charge. This matches the offline-queue adapter pattern and the fix(offline-queue): watchdog reclaim + idempotent payment INSERTs (#52) #59 dedupe contract.

🤖 Generated with Claude Code