fix(billing): short-cache planless customers to end post-checkout onboarding lockout

[JeremyFunk]

Problem

On the PR-preview deploy, a user who completed Stripe checkout (test card) was permanently bounced to /quick-start onboarding on every navigation, despite having a valid trial.

The root cause is a stale negative cache, not the checkout itself. After checkout, Autumn records the new subscription asynchronously. A customer with no active plan was cached for the full 5 minutes at two layers — the API per-org edge cache (getOrCreateCustomer) and the client react-query layer. The post-checkout return is a fresh page load, and the attach mutation that invalidates the cache already ran before the redirect to Stripe, so nothing re-invalidates on return. If the first post-return getOrCreateCustomer landed before Autumn finished syncing, the "no plan" snapshot stuck for 5 minutes and the __root.tsx plan gate re-bounced the user on every navigation.

This is pre-existing behavior, unrelated to the recharts upgrade, and it affects real paying customers — not just preview.

Fix

Treat a planless customer as an unsettled state that's cheap to re-check, at both layers:

• API edge cache (autumn.http.ts): getOrCompute now accepts a content-dependent TTL. A confirmed active-plan customer keeps the full 300s; a planless or error-shaped 200 is cached for just 5s (CUSTOMER_CACHE_UNSETTLED_TTL_SECONDS).
• Client (use-maple-customer.ts): dynamic staleTime (5 min when settled, 5s when planless) plus a self-stopping refetchInterval while planless, so the gate auto-recovers within seconds with no manual refresh. Polling stops the moment a plan is active and pauses while the tab is backgrounded.

Avoiding drift

The gate rule ("is this an actively selected paid plan?") would now live in two places — the web redirect gate and the API cache TTL. Extracted it into a single source of truth, @maple/domain/billing isActivePlanSubscription, structurally typed so autumn-js stays out of @maple/domain. Both plan-gating.ts (web) and autumn.http.ts (api) delegate to it.

Verification

• bun typecheck — 23/23
• Tests: domain billing (3), web plan-gating (19), api autumn (11), query-engine edge-cache (8)

🤖 Generated with Claude Code

[pullfrog]

ℹ️ No critical issues — one informational observation below; mergeable as-is.

Reviewed changes — a fix for the post-checkout onboarding lockout where a stale "no plan" customer snapshot, cached for 5 min at both the API edge cache and the client react-query layers, kept bouncing a just-subscribed user to /quick-start until Autumn finished its async Stripe→subscription sync.

• Content-dependent edge-cache TTL — getOrCompute's ttlSeconds now accepts number | ((value) => number), resolved once on write; autumn.http.ts gives active-plan 200s the full 300s and planless/error-shaped 200s just 5s (CUSTOMER_CACHE_UNSETTLED_TTL_SECONDS).
• Self-stopping client poll — use-maple-customer.ts switches to function-form staleTime (5 min settled / 5s planless) plus a refetchInterval that polls every 5s while planless and returns false once a plan is active.
• Shared anti-drift gate — extracted isActivePlanSubscription into @maple/domain/billing (structurally typed via PlanGatingSubscription so autumn-js stays out of @maple/domain); both web plan-gating.ts and api responseHasActivePlan delegate to it.
• Tests — domain billing, api autumn (TTL policy via a recording backend), and edge-cache (function-form TTL resolves per computed value) all covered.

I verified the mechanism end-to-end against the actual dependency: autumn-js@1.2.29 bundles @tanstack/query-core@5.85.6, which honors function-form staleTime and refetchInterval and pauses the interval while the tab is unfocused, and its useCustomer spreads queryOptions straight into useQuery. The TTL function runs only on write, not on cache hits, and the API and web gates now share one predicate over the same structural shape — no drift. Implementation is sound.

ℹ️ Planless cohort now re-checks indefinitely, not just during the post-checkout window

The 5s unsettled TTL plus the client poll are exactly right for the brief Stripe→Autumn sync window. But the same path also catches every genuinely planless org — legacy-free tiers (isActivePlanSubscription returns false for free) and orgs that simply never subscribe. Those are now treated as permanently "unsettled": the client polls getOrCreateCustomer every 5s while foregrounded and the API edge cache holds them at a 5s TTL forever, versus the prior 5-min window.

In practice this is bounded — the root gate parks planless orgs on /quick-start, and the poll pauses when the tab is backgrounded — so it is not a correctness problem, just a sustained cost worth being aware of for any cohort expected to dwell in-app without a paid plan.

Technical details

# Planless cohort re-checks indefinitely

## Affected sites
- `apps/web/src/hooks/use-maple-customer.ts:30-32` — `staleTime`/`refetchInterval` key off `hasSelectedPlan`, which is `false` for legacy-`free` and never-subscribing orgs, so they poll every 5s indefinitely (foreground only).
- `apps/api/src/routes/autumn.http.ts:81-84` — same cohort caches at the 5s unsettled TTL forever, so each >5s client refetch that misses also re-hits upstream Autumn.

## Required outcome
- None required for correctness. Optionally confirm the never-subscribing / legacy-free cohort isn't expected to sit in-app long enough for the sustained 5s re-check (client + upstream) to matter.

## Open questions for the human
- Are legacy-`free` orgs a live cohort that dwells inside the app, or are they always redirected to `/select-plan` / `/quick-start` and effectively transient? If the former, a longer unsettled TTL (e.g. 15–30s) would cut the steady-state load while still resolving the post-checkout window fast.

  ^{｜ ⚠️ this action is pinned to a commit SHA, which freezes the cleanup step — switch to @v0 or keep the SHA fresh with Dependabot ｜ Fix it ➔ ｜ View workflow run ｜ Using Claude Opus ｜ 𝕏}

[pullfrog]

✅ No new issues found.

Reviewed changes — since the prior pullfrog review (ee3e57f9), this run covers the new signup-flash fix (MAP-45) that gates the __root.tsx optimistic dashboard render behind a per-org localStorage flag.

• Per-org "seen a plan" flag — new selected-plan-cache.ts exposes hasKnownSelectedPlan / rememberSelectedPlan (keyed maple:billing:selected-plan:<orgId>), try/catch-wrapped and fail-closed on SSR / disabled / quota errors, with 8 covering tests.
• Flag-writing effect — __root.tsx records the flag only on a settled, usable customer payload (skips while loading / on error / on unusable), so a transient blip can't flip it.
• Loading-branch gate rework — while the customer query is loading, the dashboard renders only for ALLOWED_WITHOUT_PLAN paths or when hasKnownSelectedPlan(orgId) is set; otherwise it waits (return null) instead of flashing the dashboard before bouncing a fresh signup to /quick-start. The flag is cleared on settled-planless, so unsubscribe flashes exactly once.
• Module-scope ALLOWED_WITHOUT_PLAN — hoisted out of the inner block (de-duped, no shadowing).

I traced the full gate: the fix #1 safety invariant is preserved — the loading branch never redirects, so the /quick-start bounce still fires only after the query settles (__root.tsx:166-167) and a paying user is never bounced before their plan is known. The quotaPreview path falls through to AppFrame unchanged, returning null from ClerkReverseRedirects is safe (Clerk providers live above; AppFrame only wraps AttributesProvider+Outlet), and the unsubscribe case flashes once then reverts to the wait path as documented. The prior review's lone informational observation (planless cohort re-checks indefinitely) is unchanged by these commits and remains mergeable as-is.

  ^{｜ ⚠️ this action is pinned to a commit SHA, which freezes the cleanup step — switch to @v0 or keep the SHA fresh with Dependabot ｜ View workflow run ｜ Using Claude Opus ｜ 𝕏}

[JeremyFunk]

@pullfrog pls merge main into this

[pullfrog]

Merged main into jeremy/fix-onboarding-lockout-after-checkout and pushed. Main had landed the typed /api/billing migration (retiring autumn.http.ts for billing.http.ts + the effect-atom billingCustomerAtom), which conflicted with this PR's autumn-js-based fix. Resolution:

• billing.http.ts — ported this PR's content-dependent customer-cache TTL onto main's new file: responseHasActivePlan + CUSTOMER_CACHE_UNSETTLED_TTL_SECONDS (5s for planless/error-shaped 200s, full 300s once an active plan is confirmed), delegating to @maple/domain/billing isActivePlanSubscription. This preserves the core onboarding-lockout fix.
• autumn.http.ts / autumn.http.test.ts — accepted main's deletion; the TTL-policy + responseHasActivePlan tests were re-pointed to billing.http.test.ts.
• use-maple-customer.ts — took main's thin billingCustomerAtom accessor. The autumn-js per-hook retry/poll no longer exists post-migration; post-checkout recovery now rides the 5s API TTL on the next gate-driven refetch.
• plan-gating.ts — merged imports (kept isActivePlanSubscription + main's typed @maple/domain/http types and isLegacyPlan helpers).

Verified: bun typecheck passes for all billing packages (the only failure is pre-existing, unrelated examples/effect-todo). Tests green — billing.http (9), plan-gating (30), domain billing (3).

Task list (4/4 completed)

• Checkout PR branch and identify base branch
• Fetch base branch and attempt merge
• Resolve conflicts if any
• Push and report

  ^{｜ ⚠️ this action is pinned to a commit SHA, which freezes the cleanup step — switch to @v0 or keep the SHA fresh with Dependabot ｜ View workflow run ｜ via Pullfrog ｜ Using Claude Opus ｜ 𝕏}

[pullfrog]

ℹ️ No critical issues — the lockout fix survives the merge intact; one behavior-drift observation below worth a look before merging.

Reviewed changes — since the prior pullfrog review (ee3e57f9), two main merges (bb71914, e5b82fc) reconciled this PR with the typed /api/billing migration (#125). The reconciliation re-homed the Fix #1 API logic and moved the client hook onto an atom; I re-reviewed that reconciliation.

• Ported the customer-cache TTL onto billing.http.ts — #125 renamed autumn.http.ts → billing.http.ts, so the merge re-applied responseHasActivePlan + the content-dependent getOrCompute TTL (300s active / 5s planless via CUSTOMER_CACHE_UNSETTLED_TTL_SECONDS) onto the new file. Logic is functionally identical to what was reviewed at ee3e57f9, and the retired autumn.http.ts proxy is fully gone.
• Re-homed the client hook onto billingCustomerAtom — use-maple-customer.ts is now a thin accessor over the effect-atom billingCustomerAtom; the function-form staleTime / self-stopping refetchInterval that previously lived in this hook are no longer present.
• Unchanged from the prior review — the shared @maple/domain/billing isActivePlanSubscription gate, plan-gating.ts delegation, and the edge-cache.ts function-form ttlSeconds (resolved once on write) are byte-identical and re-covered by their tests.

ℹ️ The client half of the fix was dropped in the merge — only the API-cache half remains

The original fix worked at two layers: the API edge cache (5s TTL on a planless snapshot) and a client-side self-stopping poll in use-maple-customer.ts that re-fetched every 5s while planless, so a just-subscribed user parked on /quick-start auto-advanced the moment Autumn finished syncing — no refresh, no navigation. The merge that re-homed the hook onto billingCustomerAtom (which has no refetchInterval and no short staleTime) removed that client poll.

The titular lockout is still fixed — the 5s API TTL plus effect-atom's refetch-on-remount means the next navigation after Autumn syncs recovers, so the permanent loop is broken. What's gone is the passive auto-recovery: a user who lands on /quick-start and simply waits will not advance until they navigate or refresh.

This leaves the PR description out of step with what ships — it still claims a use-maple-customer.ts refetchInterval that "auto-recovers within seconds with no manual refresh." Worth either restoring a poll/short-staleTime on billingCustomerAtom or updating the description and the "Avoiding drift" / two-layer framing so the next reader isn't misled.

Technical details

# Client-side post-checkout auto-recovery dropped during the #125 reconciliation

## Affected sites
- `apps/web/src/hooks/use-maple-customer.ts` — now a thin accessor over `billingCustomerAtom`; the prior function-form `staleTime` (5min settled / 5s planless) and self-stopping `refetchInterval` (5s while planless, `false` once active, paused backgrounded) are gone.
- `apps/web/src/lib/services/atoms/billing-atoms.ts:15-17` — `billingCustomerAtom = MapleApiAtomClient.query("billing", "getCustomer", { reactivityKeys: [...] })`; no `refetchInterval`, no short/unsettled `staleTime`. Its comment claims recovery via "refetches on remount + reactivity invalidation" — neither fires on a post-checkout *wait* (the `attach` invalidation already ran before the Stripe redirect; the return is a fresh load with no subsequent remount until the user navigates).
- `apps/web/src/routes/__root.tsx:182-183` — a planless settle still `Navigate`s to `/quick-start`; with no client poll there's no force that re-evaluates the gate while the user idles there.
- PR description ("Fix" → Client bullet, and "Avoiding drift" two-layer framing) — describes a client `refetchInterval` that no longer exists.

## Required outcome
- Decide whether passive post-checkout auto-recovery is still a requirement. If yes, the client must re-check while planless (the API `5s` TTL alone only helps a request that actually fires). If no, the PR description and two-layer framing should be corrected so the shipped behavior is documented accurately.

## Suggested approach (optional)
- Restore the unsettled poll at the atom layer: give `billingCustomerAtom` a short idle-TTL / `refetchInterval` (≈5s) that applies while the customer is planless and stops once a plan is active — mirroring the dropped `use-maple-customer.ts` logic but expressed in the effect-atom idiom (e.g. an `Atom.setIdleTTL` / interval-refresh wrapper gated on `isActivePlanSubscription`). Confirm it pauses while backgrounded, as the original did.
- Or, if recovery-on-next-navigation is deemed sufficient, drop the client-poll claims from the PR body and note that the fix is now API-cache-only.

## Open questions for the human
- Is a planless user expected to *sit* on `/quick-start` post-checkout (needing passive recovery), or do they reliably navigate/refresh within seconds (making remount-refetch enough)? This determines whether the client poll needs restoring or the description just needs correcting.

  ^{｜ ⚠️ this action is pinned to a commit SHA, which freezes the cleanup step — switch to @v0 or keep the SHA fresh with Dependabot ｜ Fix it ➔ ｜ View workflow run ｜ Using Claude Opus ｜ 𝕏}