# Plans and subscriptions ## What this builds Paid plans for an app. A person picks a plan and pays on the payment provider's own checkout page. The provider tells the app what happened, the app keeps its own copy of the subscription, and every part of the app asks one function what an account may use. Read `spekkr.inputs.json` first. `payer` says whether a user or a workspace subscribes. `provider` says which adapter is built. A trial lasts `trial_days` days, and access lasts `grace_days` days after a failed payment. `free_plan` changes R5. Use `app_name` on the pages. This spec needs the app to know who is signed in. It does not build sign-in. It never sees a card number: paying happens on the provider's pages. ## Out of scope - Charging by usage. `spekkr/usage-billing` builds that. - Tax. The provider's checkout handles it or it is not handled. - Coupons, seats and more than one subscription for one payer. ## Requirements Each requirement has an id. Tests name the id they cover. ### R1. Plans - Plans are a list in code: a key, a name, the price as shown, the provider's price id, and what the plan allows. - What a plan allows is a set of features, each on or off, and a set of limits, each a whole number or unlimited. - The list has a test: every plan names every feature and limit, so a new one cannot be forgotten on one plan. Accept when: the test fails when a plan misses a feature. ### R2. Check out - `POST /billing/checkout` with a plan starts the provider's hosted checkout and redirects to it. - A payer has one customer at the provider. It is created the first time and reused after, even when two requests arrive together. - A payer who already has a subscription that is not ended is sent to R7 instead. - Coming back from checkout changes nothing. The page says the payment is being confirmed, and shows the plan once R3 has stored it. Accept when: two checkouts started at once leave one customer, and a forged visit to the "success" address grants nothing. ### R3. Hear from the provider - `POST /billing/webhook` checks the provider's signature on the raw bytes before reading them. A bad signature gets status 400. - Each event is stored by its id and handled once. A repeat is answered with 200 and does nothing. - Events can arrive late or out of order. An event that is older than what the app already holds for that subscription is not applied. - When in doubt, the app asks the provider for the subscription as it is now and stores that. The provider is right and the app's copy follows. - An event of a kind the app does not use is stored and answered with 200. Accept when: the same event twice changes the subscription once, an older event arriving after a newer one changes nothing, and a bad signature changes nothing. ### R4. States - A subscription is in one state from the table in `design.md`: `trialing`, `active`, `past_due`, `canceled`. - "Cancel" from R7 does not end access at once. The subscription stays `active` with a mark that it ends when the paid period does. - Only R3 and R8 change the state. No page does. Accept when: every arrow in the table in `design.md` has a test, and no other change of state is possible. ### R5. What an account may use - `can(payer, feature)` answers yes or no. `limit(payer, name)` answers a number or unlimited. `plan_of(payer)` names the plan. - They read the app's own copy. They never call the provider. - A payer with no subscription, or an ended one, is on the free plan if `free_plan` is on, and otherwise can use nothing that needs a plan. - A subscription that is `past_due` keeps its plan for `grace_days` days from the first failed payment, and is treated as having none after that. Accept when: each state in the table gives the access listed there, including one second before and one second after the grace ends. ### R6. Trials - If `trial_days` is more than 0, a first subscription starts as `trialing` for that many days. - A payer gets one trial, ever. A second subscription starts as `active`. Accept when: a payer who cancels during a trial and subscribes again is charged at once. ### R7. Manage - "Manage billing" sends the payer to the provider's own portal for the card, the invoices, cancelling and changing plan. - With `payer` set to `workspace`, only people who may manage the workspace can check out or open the portal. Everyone in it can see the plan. Accept when: a member who may not manage the workspace gets 403 for both. ### R8. Catch what was missed - Once a day a job compares every subscription that is not ended with the provider, and stores the provider's version where they differ. Each difference is logged. Accept when: a subscription changed at the provider with no event sent is right after the job runs. ### R9. Pages - A pricing page made from the list in R1, with the payer's own plan marked. - A billing part of the settings: the plan, the state in words, the next payment date, and "Manage billing". - A banner for `past_due` that says when access ends, and one for the last 3 days of a trial. Accept when: each page works with a keyboard alone and at a 360 pixel wide screen. ## Definition of done - Every acceptance check above has an automated test, and all tests pass. Tests run against a stand-in provider and set the clock. - No log line holds a key or a webhook secret. - A README explains how to add a plan, how to ask `can` from code, how to set up the webhook at the provider, and how to run the tests.