feat(billing): detect API customers near/over plan caps and notify them with a self-serve upgrade CTA

[koala73]

Part of the plan-limit upgrade lifecycle epic (#4635). This is the detect + notify half (its sibling #4634 is the upgrade mechanism).

Problem

When an API customer approaches or exceeds their plan caps (per-minute burst / daily allowance), we currently do nothing customer-facing — they'd be silently throttled once #3199 enforcement flips on, or (worse) surprised. We must notify them first and point them at a self-serve upgrade, so they can choose to upgrade or reduce traffic. No auto-charge, no silent throttle.

Scope

• Detect near/over-limit per account from existing usage telemetry (wm_api_usage / the fix(api): P1 — enforce per-tier API limits (Phase 1: per-account burst + usage meter + safety ceiling) #3199 daily meter). Thresholds TBD in planning (e.g., 80% and 100% of allowance; sustained burst over cap).
• Notify the account owner — email (Resend; reuse convex/payments/subscriptionEmails.ts patterns) and/or in-app banner — with a clear upgrade CTA linking to the gap: no self-serve plan upgrade/change flow for existing subscribers (Starter→Business; blocks #3199 enforce + misses revenue) #4634 flow.
• Anti-spam / cadence — don't re-notify every request; dedupe per account per window.
• Message honesty — explain current usage vs plan cap, the upgrade option, and that reducing traffic is a valid alternative.

Relationships

• Precedes / is the humane alternative to fix(api): P1 — enforce per-tier API limits (Phase 1: per-account burst + usage meter + safety ceiling) #3199 hard-429 enforcement (notify before you throttle).
• On-ramp to epic: usage-based overage billing on Dodo (Phase 2 of #3199) #4560 overage billing (notify → upgrade is the pre-billing consent layer; if overage billing lands, the notification becomes "you're in overage" instead).
• Needs the upgrade mechanism gap: no self-serve plan upgrade/change flow for existing subscribers (Starter→Business; blocks #3199 enforce + misses revenue) #4634 to give the CTA somewhere to go.

Open product decisions (resolve in planning)

Thresholds & sustained-vs-spike logic; channels (email / in-app / both); cadence & anti-spam; copy; and sequencing vs #3199 enforce and #4560 overage billing.

[koala73]

Planned as U3 in docs/plans/2026-07-02-001-feat-api-plan-limit-upgrade-lifecycle-plan.md (implementation-ready).

• Convex daily cron enumerates api-access accounts from entitlements, then GETs each {getKeyPrefix()}rl:apikey:day:{userId}:{today} (Convex has Upstash creds — no meter SCAN); email via subscriptionEmails.ts (Resend) + in-app banner; upgrade CTA → U2.
• Must-fix (from doc review, in the plan): warn on BOTH axes (~80% daily AND per-minute burst pressure — the cited over-cap customers' pain is per-minute, which a daily-only threshold misses); resolve the recipient via the per-userId subscription path (not the race-prone shared-customer row); 'sustained-over 2-of-3-days' isn't computable from the 48h-TTL meter → add a small Convex daily-snapshot table or drop it.

[koala73]

Implemented by PR #4648 (codex/api-plan-limit-lifecycle) — the detect+notify half. Reviewed vs the #4635 plan (U3): well-aligned (both-axes daily+per-minute burst, sold-cap thresholds, per-userId recipient, no IDOR, hourly scan). Adopt after 6 fixes (posted on #4648): detection reads Axiom not the enforcement Redis meter; CTA billing_portal branch can't change plans; P1 in-app duplicate accumulation; P1 burst emails bypass 6h cadence; P2 unbounded table growth; P3 null-vs-(-1) unlimited sentinel. Does NOT include the upgrade/charge (#4634) or 429/enforcement (U4/U5).