Lissin Monetization — Implementation Final Report

2026-07-18 · updated 2026-07-20 · base branch = dev everywhere · 59 commits across six PRs · build + tests green

The build, end to end

Backend — PR #514 (17 commits)

Branch feat/billing-quota-foundation → dev. Exposes QuotaService (reserve/consume/release/observe/peekBalance); enforcement uses a fail-open peek. Flags BILLING_ENFORCE[_DOMAIN] default OFF.

Plus 3 review-fix commits addressing Greptile P1/P2 feedback: an optimistic-lock reserve, rollover-aware limit checks, @IsDefined DTO filters, and rejecting a past expiresAt. Ships 3 migrations (plan_versions, usage_ledger + usage_accounts, billing_access phase/trial).

Backend — PR #515 — grandfathering (4 commits)

Branch feat/billing-grandfather-cohort → dev, stacking on #514. A single GrandfatherService that mass-applies a plan tier to existing users so a pricing change never regresses them. It supports two selection modes over one shared grantToUsers core:

• Cohort selection — preview + idempotent bulk apply over an allow-listed filter set: signup-date and last-active windows, with excludes for banned / deleted / specific email domains. No free-form query surface.
• Hand-picked selection — preview-users / apply-users take an explicit list of user IDs for surgical grants.
• Campaign audit — list campaigns + drill into per-campaign grants. The grant rows are the audit, so there is no migration.

Safety properties: idempotent (keyed on campaign:userId, re-running an apply is a no-op), bounded (soft cap 1,000 / hard cap 5,000 per run), and overlay-safe — a grant only ever lifts a user and never demotes an existing payer. 29/29 grandfather + billing tests pass.

iOS — PR #309 (9 commits)

Branch feat/billing-plan-contract → develop. Client robustness: phase and unknown denial codes decode leniently (never fail); new access fields are optional (old responses still decode); the 402 handler gates on error == "billing_denied" so non-billing 402s keep prior behavior. The typed error + placement mapping this PR exposes is what #311 (rescue ladder) and #312 (gates) build the presentation layer on, below.

iOS — PR #311 — offer-stage rescue ladder (6 commits)

Branch feat/billing-offer-ladder → develop, stacking on #309. A discount downsell ladder that escalates when a user walks away from the paywall, turning a dismiss into a rescue offer rather than a lost conversion.

• Stages — OfferStage runs standard → save50 → save65, driven by an OfferLadderCoordinator that persists the highest stage reached in UserDefaults, resumes it on reopen, and resets it on a successful purchase.
• Escalation — dismissing the paywall (custom PaywallView + RevenueCatPaywallHost) escalates to the next discount. A stage is committed only after its offering actually loads (peek → load → commit), and dismissal is re-entrancy-guarded so a fast double-dismiss can't skip a rung.
• RevenueCat wiring — loadPackages(offeringIdentifier:) via the provider, backed by RC offerings default / save50 / save65, degrading gracefully to the prior offering if one is missing.

13 OfferLadderTests pass; the Greptile re-review came back green.

iOS — PR #312 — Phase-4 gates, trial & live balances (12 commits)

Branch feat/billing-phase4 → develop, stacking on #311. The client-side enforcement surface — every gate built on a fail-open EntitlementGate helper so a decode miss or missing balance never wrongly blocks a paying user.

On top of the gates: a trial countdown banner and usage nudges on the MainTabView home overlay, and the Plan & Billing screen now reads live per-meter balances (falling back to the legacy display). The pro_sources placement is intentionally not wired — there is no pro-sources feature to gate yet.

Full iOS stack compiles + 356 unit tests pass (Xcode 26.5); the Greptile re-review came back green.

Admin — PR #163 — grants, grandfathering & audit (11 commits)

Branch feat/billing-grants-admin → dev. The operator console for the whole system, with every mutation behind a billing.manage-gated server action in lib/actions.ts.

• Per-user grants — grant / revoke / history with operator attribution, plus the expanded /billing/access contract rendered inline.
• Cohort grandfathering page — a builder → preview → two-click apply flow over the backend cohort endpoints.
• Users-page multi-select — select rows → "Grandfather selected (N)" dialog (preview → confirm → apply) for hand-picked grants.
• Audit page — /billing/campaigns with per-campaign grant drill-down, wired into nav.

tsc + next build both clean; all admin security review comments fixed & pushed.

Enforcement model & flags

BillingService.enforce() is a single pre-flight run before each paid action. It checks, in order: capability (e.g. documentUpload, remix), file size (per-file byte cap), episode duration (plan cap), and the metered allowance (read-only peek). Behaviour is governed by flags:

A per-domain flag overrides the master (including an explicit false to carve a domain out). With a domain off, enforce() only logs would-deny — never blocks.

The 402 denial contract

When a domain is enforced, the action returns HTTP 402 with a structured body that the iOS client decodes to route to the right paywall:

{
  "error": "billing_denied",
  "code": "CAPABILITY_REQUIRED" | "QUOTA_EXHAUSTED" | "DURATION_LIMIT"
        | "FILE_LIMIT" | "ACCESS_UNKNOWN",
  "message": "…",
  "requiredTier": "plus" | "pro" | null,
  "meter": "recurringGeneration | oneTimeGeneration | explorePlayback | fileUploads" | null,
  "remaining": Int | null,   "limit": Int | null,   "resetAt": ISO8601 | null,
  "maxMinutes": Int | null,  "maxBytes": Int | null,
  "placement": "generationAllowance | higherRecurringAllowance | documentAttach | remix | …"
}

iOS maps this to a paywall placement in priority order: backend placement hint → code → meter. SSE create endpoints surface the same denial as a stream error (not an HTTP status) — client-side SSE handling of that is a follow-up.

Live vs observe-only vs dark

Verification

• Backend (#514 + #515): nest build clean; 29/29 billing + grandfather tests pass.
• iOS (#309 + #311 + #312): the full stack compiles and 356 unit tests pass (Xcode 26.5), including the 13 OfferLadderTests and the expanded access-contract / gate suites.
• Admin (#163): tsc + next build both clean.
• Reviews: every code-review comment (Greptile P1/P2 + admin security) is fixed & pushed; the iOS #311 and #312 re-reviews came back green.
• Safety: everything is observe-only / additive / flag-gated — metering is fire-and-forget and non-fatal; enforcement is off by default; client gates fail open; grandfather grants only ever lift a user; all new access/response fields are optional and backward-compatible.

How to turn enforcement on (when ready)

1. Confirm real usage looks right by reading the ledger / would-deny logs while still in observe-only.
2. Set one domain flag on dev, e.g. BILLING_ENFORCE_CAPABILITIES=true, and verify 402s + the iOS paywall route.
3. Ramp the remaining domains (FILES, GENERATION) one at a time.
4. Only enable in prod after the webhook secret is set and a real sandbox purchase projects a tier end to end.

Deferred follow-ups (deliberately separate)

• Explore-playback signed-URL denial — the backend PLAYBACK flag is reserved; denying playback URLs mid-session is UX-sensitive and deserves its own change (metering is observing it, and #312 already gates client-side listening-time via the meter balance).
• Scheduler per-episode recurring metering — user-initiated recurring creates are metered; the scheduler's automated episode generation is a separate hook.
• Atomic reserve/consume lifecycle — enforcement uses a fail-open peek (small concurrency window); #514 now ships an optimistic-lock reserve/consume/release, ready to wire the atomic reserve-before-enqueue path for strict "at most one credit" guarantees.
• SSE-stream denials on iOS — HTTP 402s decode + present a paywall (#309/#311/#312); the create endpoints surface the same denial as a stream error, and client-side handling of that is next.
• pro_sources paywall placement — intentionally not wired; there is no pro-sources feature to gate yet.
• Admin editor for plan_versions — per-user grants, cohort + multi-select grandfathering, and the campaign audit all shipped in #163; the dashboard UI to edit the plan_versions numbers themselves is a later admin task (the DB is already the runtime source of truth).

Action items for you

All 59 commits are pushed across six open PRs, awaiting review. Every code-review comment is fixed & pushed and the iOS #311/#312 re-reviews are green — but nothing is merged yet.