Improve Stripe webhook reconciliation, logging, and launch diagnostics

[SaltProphet]

Motivation

• Payment fulfillment sometimes returned to the app before the webhook had applied credits; this change adds a bounded client-side reconciliation loop to avoid confusing UI state.
• Webhook processing needed better observability at failure and decision points to troubleshoot signature, metadata, and ledger transitions.
• Operators needed a minimal diagnostics/runbook to inspect payments rows by transaction_id for live troubleshooting without introducing a new admin endpoint.

Description

• Added a guarded, bounded post-checkout reconciliation loop in src/app/page.tsx that only runs for payment=success returns, introduces PAYMENT_RECONCILE_MAX_ATTEMPTS and PAYMENT_RECONCILE_INTERVAL_MS, and refreshes tokens, plan, and last_payment_at from the profiles row.
• Instrumented src/app/api/webhooks/stripe/route.ts with structured logs for missing signature, signature verification failures, missing checkout metadata, and payment ledger transitions (transitions to received, fulfilled, replayed, and failure states).
• Extended src/app/api/webhooks/stripe.test.ts to assert replay idempotency, rejection of paid sessions with missing metadata, and behavior when profile updates fail (ensuring ledger is transitioned to a failure state).
• Added live webhook validation checklist and admin SQL for inspecting payments by transaction_id to STRIPE_CHECKLIST.md and added a webhook diagnostics runbook to docs/launch/PRODUCTION_LAUNCH_GUIDE.md.

Testing

• Ran the webhook unit tests with npm test -- src/app/api/webhooks/stripe.test.ts and all tests passed (6 passed, 0 failed).
• The added tests exercise signature rejection, successful grant + ledger insert/fulfill, replay handling, missing-metadata rejection, and profile-update failure reconciliation behavior, and they succeeded in the test run.

---

Codex Task

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
secpriva	Ready	Preview, Comment	Mar 6, 2026 1:52am

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.