Convert first clinic wins into subscriptions

[evangauer]

What changed

• Add server-owned subscription Checkout source evidence from registration, in-app, first-visit email, and trial-ending email entry points, then persist the signed Stripe echo in an additive migration.
• Add a dedicated first-real-visit → billing-connected report for the supported US Cloud population, with one 72-hour-mature opportunity denominator and 24/72-hour conversion rates. Self-hosted and non-US clinics are excluded from opportunities they cannot enter.
• Add a default-off, hourly first-clinic-win campaign derived from committed non-demo visit closeout evidence. It requires an explicit prospective launch boundary and an exact active verified-admin match for the saved practice email.
• Add a platform-admin, read-only campaign preflight that shows the staged cutoff, exact eligible count, send state, and 100-recipient sweep cap without claiming a recipient or sending email.
• Segment trial-ending email so already-connected trials receive reassurance, unconnected trials receive Add billing, and contradictory evidence is suppressed rather than guessed.
• Harden optional lifecycle email with final unsubscribe serialization, recipient-bound ambiguous retries, Resend idempotency, redacted alerts/logs, and analytics stripping for signed attribution tokens.
• Make billing setup truth server-owned: a Stripe customer alone no longer counts as completed setup, Checkout return query parameters never prove success, and Settings polls signed webhook state before enabling billing actions.
• Make pricing copy explicit about the included product/staff scope and the $0.03/text and $0.05/AI-action overages after the monthly allowances.
• Fail hosted readiness and every optional lifecycle marketing send when EMAIL_COMPANY_ADDRESS is missing or structurally not a physical postal address. The check is PHI/secret-safe and occurs before rendering or provider contact.

Why

A completed real clinic visit is OpenVPM's strongest validated product-use signal. This release turns that signal into a measurable, privacy-safe subscription opportunity while preventing false Add billing messages, duplicate/stale promotional sends, and promotional email with a non-postal footer identity.

Safety and rollout

• FIRST_CLINIC_WIN_EMAIL_ENABLED defaults to false.
• Enabling without a valid FIRST_CLINIC_WIN_EMAIL_LAUNCH_AT makes hosted health fail.
• Operators can stage the launch boundary with sending off, inspect the aggregate preflight, and enable only after reviewing the exact candidate count.
• Only visits at or after the reviewed UTC boundary qualify; no retrospective backfill is implicit.
• Eligibility is rechecked under the practice recovery lock and recipient preference lock immediately before provider delivery.
• Campaign content, dedupe keys, logs, alerts, reporting, and preflight contain no client, patient, appointment, closeout, invoice, recipient, or practice identity.
• Production currently has a non-postal EMAIL_COMPANY_ADDRESS; set and operator-verify the real physical US postal address before deploying this stack. The value is never exposed by health responses or logs.
• No production emails, Stripe calls, or environment changes were made while developing this PR.

Validation

• pnpm --filter @openpims/web test — 378 files passed, 3 skipped; 3,937 tests passed, 6 skipped.
• pnpm --filter @openpims/web type-check
• pnpm --filter @openpims/db type-check
• pnpm --filter @openpims/email type-check
• pnpm --filter @openpims/web build
• pnpm --filter @openpims/db db:generate — no schema changes after committed migration/snapshot.
• Focused health, email, lifecycle, migration, schema-drift, schema-index, webhook, cron, attribution, reporting, admin-auth, preflight, and UI contracts all pass.
• git diff --check

Stack

This is intentionally stacked on codex/subscription-conversion-reliability / PR #202. Merge and validate that base first; do not merge this PR directly to main before the stack is resolved.

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
openvpm-app	Ready	Preview	Aug 11, 2026 7:42pm

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
openvpm	Ignored	Preview	Aug 11, 2026 7:42pm