Add freemium access economy and token store

2026-07-27 22:20:21 -05:00
parent 1d5d03a4f6
commit 4bbac27b84
40 changed files with 1807 additions and 37 deletions
@@ -0,0 +1,82 @@
+# Access economy
+
+RanaZe is free to install and use on the public web client and on Steam. An
+account is required. The server is authoritative for quotas, credits, token
+inventory, prices, and grants.
+
+## QBank limits and credits
+
+- Standard QBank use includes 20 completed questions in a rolling 24-hour
+  window. An answer or skip consumes one slot.
+- An eligible first answer in the current QBank cycle earns one credit,
+  regardless of correctness. Skips and repeat answers earn no credit.
+- A user can earn at most 20 credits in a rolling 24-hour window, including
+  while an unlimited pass is active.
+- 100 earned credits can be redeemed for 24 hours of unlimited standard QBank
+  use. Credits cannot be purchased.
+- Paid access tokens stay in inventory until manually activated. Activation
+  extends from the later of the current time or the current pass expiration.
+
+Other study tools remain free. An unlimited QBank pass changes only the standard
+QBank completion limit.
+
+## Product catalog
+
+| SKU | Grant | Price |
+| --- | --- | ---: |
+| `access_day_1` | one manually activated 24-hour QBank token | $1.00 |
+| `access_week_1` | one manually activated 168-hour QBank token | $5.00 |
+| `access_month_1` | one manually activated 720-hour QBank token | $20.00 |
+| `exam_token_1` | one exam simulation | $1.99 |
+| `qbank_reset_1` | one QBank reset | $4.99 |
+
+A reset requires explicit confirmation and is blocked while an exam simulation
+is active. It starts a new personal QBank cycle, resets personal QBank rating
+and current-cycle performance, and makes questions eligible as new samples.
+Existing global aggregate samples are not removed. Bookmarks, notes, and review
+content remain.
+
+Existing accounts begin with zero credits and no tokens. Historical attempts
+are not backfilled into credits.
+
+## Web checkout
+
+Web purchases use Stripe-hosted Checkout. Configure:
+
+```text
+Stripe__SecretKey
+Stripe__AccessWebhookSecret
+Stripe__AccessSuccessUrl
+Stripe__AccessCancelUrl
+```
+
+Create separate access webhook endpoints:
+
+- UAT test mode: `https://us3q.ranaze.com/api/access/stripe-webhook`
+- production live mode: `https://s3q.ranaze.com/api/access/stripe-webhook`
+
+Each endpoint has a distinct signing secret. Store them as
+`UAT_STRIPE_ACCESS_WEBHOOK_SECRET` and
+`PRD_STRIPE_ACCESS_WEBHOOK_SECRET` in Gitea. Subscribe both endpoints to
+`checkout.session.completed`, `checkout.session.async_payment_succeeded`,
+`checkout.session.async_payment_failed`, and `checkout.session.expired`.
+
+Prices and grants are selected from the API catalog; the client never supplies
+an amount. Webhook signatures, expected amount, currency, session, and purchase
+ownership are verified before an idempotent grant is applied.
+
+## Steam checkout
+
+The Windows Steam export has the `steam` feature flag and routes purchase
+requests to the disabled Steam checkout endpoint. It does not expose Stripe
+checkout. The endpoint intentionally returns 503 until the Steamworks AppID,
+Microtransactions product catalog, server credentials, callbacks,
+reconciliation, refund handling, and sandbox tests are implemented.
+
+## Operational checks
+
+Before release, verify all products in Stripe test mode and then live mode.
+Exercise duplicate webhook delivery and concurrent quota submissions. Confirm
+that data export/deletion includes `UserAccessAccounts` and `AccessPurchases`.
+Monitor rejected checkouts, webhook verification failures, unmatched payments,
+grant failures, and quota conflicts.