fix(checkout): preserve server validation errors on contact field blur

[detail-app]

Detail bug report: View on Detail

Summary

Related Issue: polarsource/feedback#381

Fixes a regression where server-side validation errors on checkout contact fields (email/name) were immediately cleared after being set, preventing buyers from seeing inline feedback when blurring those fields.

What

• captureContact in CheckoutForm.tsx now clears field errors before the update request and does not clear them on failure, matching the pattern already used by addTaxID and the address watcher in the same file.
• Added two regression tests in CheckoutForm.test.tsx covering: server validation errors remaining visible after a rejected update, and stale errors being cleared while new server errors appear on retry.

Why

captureContact called update({...}).catch(() => clearErrors(name)). The CheckoutFormProvider's update sets validation errors via setError/setValidationErrors and then throws. The .catch handler wiped the just-set errors, so buyers never saw onBlur server validation feedback — notably email deliverability checks that only the API can perform. Errors still appeared at checkout confirmation, but the immediate field-level feedback was defeated.

How

Switched captureContact to the clearErrors-before / no-clear-on-failure idiom used by every other update caller in the component (addTaxID, clearTaxID, the address watcher, updateBusinessCustomer, onPaymentElementChange):

clearErrors(name)
try {
  await update({ [name]: contact })
} catch {
  /* API errors handled by provider */
}

Testing

• Unit tests (29 in CheckoutForm.test.tsx, 382 across the @polar-sh/checkout package), typecheck, lint, and format all pass. The two new regression tests fail against the original buggy code and pass with the fix.
• The provider-level error-flow contract (provider sets errors via setValidationErrors before throwing) is covered by CheckoutFormProvider.test.tsx and confirmed live: PATCH /v1/checkouts/client/<cs> with an undeliverable email returns HTTP 422 with the validation detail.
• End-to-end browser verification against the local Docker stack: drove the real checkout with Playwright, entered an email the API rejects (test@example.com), blurred the field, and confirmed the validation error appears and stays visible. Correcting to a valid email cleared the error. Reverting the fix reproduced the bug (error cleared immediately), confirming the test catches the regression. No unhandled promise rejections occurred.
• A live Stripe purchase and the downstream DB order verification could not be run — the local stack had no Stripe test-mode keys configured (placeholder publishable key; dev stripe requires interactive OAuth to a personal sandbox). This is a credential precondition unrelated to the fix; the contact-field validation behavior is independent of Stripe and was fully verified end-to-end.

Checklist

• This PR addresses a single concern (one bug fix, one feature, one refactor)
• The diff is reasonably sized and easy to review
• New functionality is covered by tests
• Linting and type checking pass (uv run task lint && uv run task lint_types)
• No unrelated changes or drive-by fixes are included

---

Automatic Fixes PRs can be configured here.

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
orbit	Ready	Preview	Aug 14, 2026 1:54pm
polar	Ready	Preview	Aug 14, 2026 1:54pm
polar-sandbox	Ready	Preview	Aug 14, 2026 1:54pm
polar-test	Ready	Preview	Aug 14, 2026 1:54pm

[github-actions]

Preview Environment
URL: https://polar-preview-vm.taildbff7b.ts.net/pr-13730
API: https://polar-preview-vm.taildbff7b.ts.net/pr-13730/v1/
Logs: backend
SHA: dc353ff2aeca5057c796c64e25156779d0a9f697