Lissin Billing — Implementation & Integration Status

2026-07-18 · updated 2026-07-20 · reconstructed directly from the code across the 6 open PRs — backend #514/#515, iOS #309/#311/#312, admin #163 — plus verified live dev-box state.

Where we are — at a glance

6 PRs across the three repos, 59 commits total, none merged — every one is observe-only, additive, and flag-gated (enforcement defaults OFF, fail-open). Every code-review comment has been fixed and pushed; the iOS #311 and #312 re-reviews came back COMPLETED/SUCCESS. Backend #514/#515 target dev, iOS #309/#311/#312 target develop, admin #163 targets dev.

How the integration works

Three components, one server-authoritative contract. RevenueCat sits between the App Store and the backend; the backend is the single source of truth for what tier a user has; iOS and admin both read that truth.

App Store  ──purchase──▶  RevenueCat  ──webhook (Authorization: <secret>)──▶  Backend
                              ▲                                              │
   iOS app ──logIn(userUUID)──┘                                   projects tier onto
      │                                                            billing_access row
      │  GET /billing/access (Firebase auth)                              │
      └──────────────────────────────────────────────────────────◀──────┘
          returns expanded AccessSnapshot {tier, phase, planVersion, capabilities, balances, trial, serverTime}

   Admin ──X-Admin-Secret──▶ /admin/billing/grants  ── writes billing_grants (overlay)

The load-bearing contract

Purchase happy path (signed-in Beta build)

Backend implementation

NestJS module at src/modules/billing/, global prefix /api/v1. Controllers, a service, a Prisma-backed store, and — as of #514 — a versioned plan contract (plan_versions), a usage ledger, and a QuotaService feeding the expanded snapshot. #515 layers grandfathering (cohorts + hand-picked users + campaign audit) on top.

Endpoints

AdminGuard checks header x-admin-secret == ADMIN_SECRET. Fine-grained billing.manage vs users.view permissions exist only in the admin app's RBAC layer — the backend route is a single admin gate.

RevenueCat webhook

Authentication

billing.service.ts:176-182: loads REVENUECAT_WEBHOOK_SECRET; if blank → 501; then an exact-string compare of the entire Authorization header (authorization !== secret → 401). No Bearer parsing, no HMAC — whatever string sits in RevenueCat's Authorization field must equal the env var byte-for-byte.

Idempotency & ordering

Every event is inserted into billing_events keyed on the globally-unique provider_event_id (createMany + skipDuplicates); a duplicate returns {duplicate:true, projected:false}. A stale-event guard compares the event's intrinsic moment (event_timestamp_ms ?? expiration_at_ms) against the stored last_event_at_ms; older events are recorded but not applied, and an EXPIRATION/CANCELLATION with no intrinsic timestamp is refused projection (so a delayed replay can't beat a newer renewal).

Handled events & user resolution

Projected types: INITIAL_PURCHASE, RENEWAL, CANCELLATION, UNCANCELLATION, EXPIRATION, PRODUCT_CHANGE, NON_RENEWING_PURCHASE, PROMOTIONAL, TRANSFER. User is resolved by matching app_user_id / original_app_user_id / aliases[] — filtered to valid UUIDs (anonymous $RCAnonymousID: ids are skipped) — against users.id. No match → recorded, not projected (grants nothing silently).

Trial-phase projection (#514, implemented). The webhook now projects the subscription phase and the trial{startsAt,endsAt} window onto billing_access, so the expanded snapshot can surface trial state to iOS. This is the load-bearing piece and is wired end-to-end; what remains on the RevenueCat side (the trial intro offer in the App Store / RC catalog, plus the default/save50/save65 offerings) is the user's part.

Tier / plan model

PlanTier = free | plus | pro. Tier is derived purely from RevenueCat entitlement identifiers by lowercase match ('pro'/'plus') — there are no App Store product IDs hard-coded on the backend. Capabilities and limits per tier are now served from a versioned plan contract (plan_versions, surfaced as planVersion in the snapshot), and the meter model is split into recurring generation, one-time generation, explore playback, and file uploads. The baseline limits (below, pending final product sign-off) are:

Access projection & admin grants

getAccessSnapshot runs in a repeatable-read transaction (retried once on serialization failure) so the access row, grants, and usage never straddle a concurrent commit. The snapshot resolves three recent fixes:

• Store-expiry honoured at read time — since the webhook is the sole writer and no sweeper runs, an expired expiresAt is treated as free on read, so a single lost EXPIRATION can't strand paid access forever.
• Grant is an overlay, not a replacement — a complimentary grant only applies if its rank ≥ the store tier (TIER_RANK[grant] >= TIER_RANK[store]), so a Plus grant never demotes a paying Pro subscriber.
• TRANSFER stands the sender down — closes the "access nobody is paying for that nothing would revoke" gap.

Admin grants live in a separate billing_grants table and never touch the store-projected tier — when a grant expires or is revoked, the underlying store tier cleanly re-appears. Grants are plus/pro only, per-user idempotent, and attributed to the operator (x-admin-actor header → grantedBy → shared admin user).

Grandfathering (#515). On top of individual grants, the backend now projects grandfather cohorts plus a list of hand-picked user IDs, each attributed to a campaign with an audit trail. The projection is idempotent, bounded, and overlay-safe — it applies the same rank rule as grants, so it never demotes a higher paid tier. Covered by 29/29 billing + grandfather tests.

Database schema

Migration 20260714120000_add_billing_contract. Enum BillingTier {FREE, PLUS, PRO} plus three tables:

• billing_events — immutable idempotency inbox; unique provider_event_id, jsonb payload. No FK to users (records unmatched events too).
• billing_grants — operator grants; FK→users, unique (user_id, idempotency_key), fields tier / starts_at / expires_at / revoked_at / reason / campaign / granted_by.
• billing_access — one row per user: revision, tier, access_source, will_renew, expires_at, management_platform, last_event_at_ms (ordering guard), grant_active, plus the trial-phase columns behind the expanded snapshot.
• + #514 adds 3 migrations — a plan_versions table (the versioned plan contract), a usage-ledger table (per-meter consumption events feeding QuotaService and the live balances), and the schema behind phase / trial on billing_access.

iOS implementation

Lives under Services/Billing/, Models/Billing/, Features/Subscription/. The manager is BillingService (not "SubscriptionManager"). The current iOS work is three stacked PRs on develop — #309 (plan contract, 9 commits), #311 (offer ladder, 6 commits, stacks on #309), #312 (Phase 4, 12 commits, stacks on #311) — 27 commits total, building on the earlier paywall work (PR #307). The full stack compiles and passes 356 tests under Xcode 26.5; the #311 and #312 re-reviews came back COMPLETED/SUCCESS.

RevenueCat wiring

• Lazy configure — Purchases.configure is called on first purchase-surface use, not at launch.
• Public key appl_XpLTTWDJZdTEnqTAYxrGYTXUBCk ships as a build setting on Release and Beta; only an appl_-prefixed key is accepted at runtime (a test_/sk_ key is rejected). DEBUG uses the RC Test Store key.
• Entitlements "pro" then "plus"; the offer ladder (#311) reads three offerings — default, save50, save65 — and falls back gracefully to the console current offering until save50/save65 exist in the RevenueCat catalog.
• Identity — logIn(authenticatedUser.id) ties RC's app_user_id to the Lissin UUID; money-moving paths throw a retryable error if RC is anonymous.

6 products: app.lissin.audio.{plus,pro}.{weekly,monthly,yearly} — Plus $3.99/$9.99/$69.99, Pro $6.99/$19.99/$199.99, each with an intro price.

Server-authoritative sync

GET /billing/access is fetched at launch, on foreground, and after purchase / restore. PR #309 decodes the expanded contract (phase, plan version, server time, trial window, per-meter balances) with a fallback plan for older/absent fields, and maps a server 402 to the right paywall placement. Server snapshots are stamped origin=.server (the field is excluded from the wire CodingKeys so it can't be spoofed); in any conflict, server wins over local. On a thrown error the access state stays .unknown and gates fail closed. 404/network/5xx/501/503 → fall back to the local RC projection; 401/400 → no fallback.

Paywall & gate trigger map

Every surface funnels through one component, PaywallHost(placement:onOutcome:), which renders either the RevenueCat-hosted paywall (default) or the custom PaywallView via a runtime toggle. The three "gate" sheets are explainer/upsell sheets that present a nested PaywallHost when the user taps the CTA. This is the real answer to "where and when is the paywall shown":

Full paywall — direct triggers

Contextual gate sheets — feature-limit triggers

Each gate sheet resumes the user's original intent after purchase (play the episode, send the generation, open the file picker, save the cadence) via a pending-action mechanism. Unresolved access fails closed everywhere (shows the gate rather than leaking the feature).

Offer ladder (rescue)

PR #311 adds an offer-stage rescue ladder: when a user declines, the next presentation escalates the offer standard → 50% off → 65% off, backed by the default / save50 / save65 RevenueCat offerings.

• The stage persists and resumes across sessions, and resets on purchase.
• It commits a stage only after the offering actually loads, so a missing offering never strands the user on a discount that can't render.
• It is re-entrancy-guarded and falls back gracefully to the standard offering until save50/save65 exist in the catalog (the user's remaining RevenueCat work). Covered by 13 tests.

Entitlement gating & free-tier limits

A single decision method, BillingService.can(capability), gates all UI (.explorePlayback is always free). Capabilities: explorePlayback, starterPersonalShow, personalGeneration, additionalPersonalShows, personalEpisodePlayback, dailyCadence, documentUpload, remix, sourceMonitoring, advancedTranscript, creatorExport, longFormGeneration. Client free-tier defaults (used for gate copy and when there's no server snapshot; server overrides): 1 show, 15 gen-min/7d, 0 docs, weekly-only, 15-min episodes.

Phase-4 gates, trial & live balances

PR #312 wires the expanded contract into the product surfaces:

• Phase-4 gates via a fail-open EntitlementGate — transcript, playback speed, soundscape, explore-time, and file size + count.
• Trial banner + usage nudges driven off the snapshot's trial window and per-meter balances.
• Plan & Billing now renders live per-meter balances rather than static copy.

Note: pro_sources is not wired — there is no such feature to gate. Fail-open means an unresolved snapshot never blocks the capability.

Beta / dev config

• Base URL — #if DEBUG || BETA → https://api.dev.lissin.com/api/v1; Release → prod. The widget mirrors this.
• Beta is a dedicated Xcode configuration + scheme (SWIFT_ACTIVE_COMPILATION_CONDITIONS … BETA). It uses real App Store sandbox purchases against the real RC products with the public appl_ key; DEBUG instead uses a local StoreKit config + test key.
• Scheme decides Archive — LissinApp archives Release (prod); LissinApp-Beta archives Beta (dev). Beta & Release share bundle id and version, so a dev-pointed build is indistinguishable in App Store Connect — never promote a Beta TestFlight build to the App Store.
• Offer-code redemption UI is currently disabled.

Admin implementation

PR #163 (11 commits) covers a per-user billing panel plus cohort and hand-picked grandfathering. Operators can:

• See current access — tier, source (complimentaryGrant/storePurchase/…), revision, ends date, will-renew, environment, and the live access-snapshot meters (now real per-meter balances).
• Grant / revoke complimentary access — tier (Plus/Pro only), end date with 30/60/90-day quick-picks, required reason + campaign, an editable idempotency "request key", and computed grant status (Active/Scheduled/Expired/Revoked) with the Granted by operator.
• Grandfather a cohort — a dedicated cohort-grandfathering UI, plus a Users-page multi-select → bulk "Grandfather selected (N)" for hand-picked users.
• Audit grandfathering — a dedicated grandfathering audit page showing what was applied, to whom, and under which campaign.

Calls go through backendFetch (injects X-Admin-Secret) to GET/POST /admin/billing/…, exactly matching the backend controller. Create sends the operator identity as X-Admin-Actor — the fix (6485987) that stopped every grant collapsing to the shared admin@lissin.internal identity. The whole surface is billing.manage-gated in the admin app's RBAC; the backend enforces only the single admin secret. The admin base branch is the dev environment, so merging #163 deploys it to admin-dev. tsc + next build clean.

Known gaps & risks

Release status & remaining steps

Enforcement stays observe-only / dark until the flags are flipped. All 6 PRs are code-complete, comment-clean, and unmerged.

Backend

• done #514 (17 commits, feat/billing-quota-foundation) + #515 (4 commits, feat/billing-grandfather-cohort) → dev; nest build clean; 29/29 billing + grandfather tests pass.
• done Metering observe-only; the RevenueCat webhook trial-phase projection is implemented; the 402 enforcement path is flag-gated OFF (fail-open). 3 migrations.
• to merge Merge the two PRs one at a time (no concurrency guard; each runs prisma migrate deploy). Populate the prod webhook secret before go-live.

iOS

• done #309 (9) → #311 (6) → #312 (12) on develop, 27 commits; full stack compiles + 356 tests; #311 & #312 re-reviews COMPLETED/SUCCESS.
• toolchain iOS builds require Xcode 26.5 — the default 16.4 toolchain can't compile the stack.
• to merge Merge in order #309 → #311 → #312.

Admin

• done #163 (11 commits, feat/billing-grants-admin) → dev; tsc + next build clean; grants + cohort & multi-select grandfathering + audit, billing.manage-gated.
• to merge Merge to dev to deploy to admin-dev (lets you grandfather a tier without a real purchase — the one server path that works without RevenueCat).

Remaining (user / non-code)

• Merge the 6 PRs (order + one-at-a-time as above).
• RevenueCat / App Store catalog — the default + save50 + save65 offerings, the trial intro offer, placements, and the prod webhook. The offer ladder falls back gracefully until save50/save65 exist.
• Product sign-offs on plan limits and copy.
• Flip enforcement on → QA the 402 path → ramp.

What to verify next

1. Merge in the right order — backend #514/#515 one at a time to dev; iOS #309 → #311 → #312 to develop; admin #163 to dev. Each backend merge runs prisma migrate deploy.
2. Stand up the RevenueCat / App Store catalog — entitlements named exactly plus/pro; the default, save50, and save65 offerings; the trial intro offer; placements; all products attached; and the webhook Authorization value equal to the secret byte-for-byte, pointed at the target backend's /billing/webhooks/revenuecat.
3. Run one real sandbox purchase through the offer ladder while signed in, then read that user's billing_access row and per-meter balances — true end-to-end proof that purchase → webhook → tier + trial-phase projection works.
4. When ready, flip enforcement on and confirm the 402 path maps to the right paywall placements before ramping.

Prepared from a fresh read of all three repositories on 2026-07-18, updated 2026-07-20 to the 6-PR state. Line-level citations are available in the working notes if you want them drilled into any specific claim.