Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 7 additions & 5 deletions telemetry-worker/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -557,8 +557,10 @@ app with a subscription of its own) opens up to three popups: a warning that the
stay (15% off for 6 months, the coupon `genclass_stay_15`; never more than that, once per customer, never on top of
another discount such as a promotion code's free months: `src/stripe.ts` retentionOffer), and a last confirmation.
A cancel ends the plan that day (the owner, 2026-11-18), a trial and a paid plan alike: a trial is charged nothing
(the owner, 2026-11-15), a paid plan gets no refund for the days left, and a discount or a promotion code's free
months end with it; the popups say so. A plan set to end later some other way (by hand in the Stripe dashboard) can
(the owner, 2026-11-15), and a discount or a promotion code's free months end with it. A cancel within 3 days of a
renewal (the charge at the end of the trial and each month's after it, never the charge that starts a subscription)
gives that payment back to the card in full (`src/stripe.ts` refundableOnCancel; the owner, 2026-11-18); any later,
nothing is refunded for the days left. A plan set to end later some other way (by hand in the Stripe dashboard) can
be resumed until then ("Resume plan"). The owner gets `plan_cancelled`
and `retention_offer_taken` notices. A trial set to cancel any other way (by hand in the Stripe dashboard) is still
ended at once by the webhook (`src/stripe.ts` trialCancelled).
Expand Down Expand Up @@ -834,7 +836,7 @@ does about it.
cannot be changed through the API for these subscriptions, only by the buyer in the portal
([how it works](https://docs.stripe.com/payments/managed-payments/how-it-works)). GenClass's portal keeps card,
invoices, email and tax id; cancelling is on GenClass's own billing page (the plan ends that day, trial or paid,
with no refund: `src/billing.ts` cancelPlan). Cancelling with `prorate` and `invoice_now` would put the credit
refunded within 3 days of a renewal: `src/billing.ts` cancelPlan). Cancelling with `prorate` and `invoice_now` would put the credit
for unused time on the customer's balance for future invoices; both default to false
([cancel](https://docs.stripe.com/billing/subscriptions/cancel)), and GenClass sends neither: it refunds the unused
time to the card instead (a refund can be partial and goes to the payment method charged:
Expand Down Expand Up @@ -873,9 +875,9 @@ does about it.
| `POST /api/billing/checkout` | `{ plan: "<id>", quantity? }` (a plan priced above 0: `team`; `quantity` (or `seats`, read the same) 1 to 200 for a plan sold by quantity becomes the subscription's quantity, which the buyer can change on Stripe's page: the apps for Team, default the apps the account owns, or the seats of a per-seat plan, default 1; Checkout takes promotion codes; Enterprise has no Checkout), browser session and our `Origin` (403 otherwise, also for a CLI token). Creates the account's own Stripe customer once (email, description `GenClass account`, metadata `genclass=1` and `genclass_account`); never looks one up by email. A stored customer is checked first (`GET /v1/customers/<id>`): its metadata must name the account, and every subscription on it must be GenClass's, else 409 with the contact address, nothing opened, and a `shared_customer` notice ("Stripe object ownership" below). Then it asks Stripe, not the database, whether that customer already has a GenClass subscription: one on this plan is a 409, one whose last payment failed (`past_due`, `unpaid`) is a 409 pointing to Manage billing, two at once (a switch still going through) or a paused one is a 409, and an active one on another paid plan is a switch: after the same invoice check as Manage billing, `{ url, switch: true }` of a Checkout for the new plan whose session and subscription carry `genclass_switch_from=<the current subscription>` (success URL `...?done=1&to=<plan>`). Otherwise `{ url }` of a Checkout Session in subscription mode for that customer and the plan's lookup key (metadata `genclass=1`, `genclass_account`, `genclass_plan`; the subscription gets `genclass` and `genclass_account` and flexible billing mode; `client_reference_id` = account id; success `https://genclass.dev/account/billing?done=1`), with `managed_payments[enabled]=true` for a plan marked `managed_payments` (none today) when `MANAGED_PAYMENTS` is `on`. GenClass's open Checkout page of the account for the same plan (and the same switch) is reused, its other open pages are closed first, and any other open page is left alone. 503 unless the account can buy (above). |
| `POST /api/billing/portal` | browser session and `Origin`; `{ url }` of a Billing Portal session (card, email and tax id, invoices; no plan switch, which is a new Checkout) on GenClass's own portal configuration: the one whose id `STRIPE_PORTAL_CONFIGURATION` (live) or `STRIPE_PORTAL_CONFIGURATION_TEST` (test) names, fetched by that id and checked (metadata `genclass=1`, active, not the default; cached 10 minutes), never the account's default one: without it, 503 ("run scripts/stripe-setup.mjs"). The portal acts on everything on the customer, so first the customer must be the account's (metadata), every subscription on it GenClass's, and each of its latest 100 invoices for a GenClass subscription; otherwise 409 with the contact address, no session, and a `shared_customer` notice. 409 before a first purchase, and when Stripe no longer has the customer (the stored ids are then cleared). |
| `GET /api/billing/pro` | browser session or the genclass command's token; `{ ok, pro, via, trial_days }`: `pro` with the account's own plan, its trial or GenClass's grant (`via: "plan"`), a seat on a paying team (`"team"`), or where nothing is sold (`"open"`), the same answer as the command's own gate; `trial_days` the days free its first Pro would start with (null with Pro or none left). The page check (genclass-scan) asks it over its `ACCOUNTS` service binding for each report it shows: the score and the whole report are Pro's since 2026-11-15. 401 when not signed in. A Checkout with `next` (`/scan?url=...`, the page check's "Start 3 days free") returns there: success `/account/billing?done=1&next=...` (the plan page waits for the payment, then goes to the report), cancel to the report; `GET /account/billing?next=...` keeps it through the sign-in and sends an account that has Pro straight back. |
| `GET /api/billing/cancel[?project=<id>]` | browser session: what the cancel popups say, `{ ok, plan, trial, ends, discount, offer }` (the plan would end that day; `trial`: nothing was charged; `ends`: the day the paid month would have run to; `discount`: a discount or free months end with it; `offer`: `{ percent_off, months }` or null); nothing changes |
| `GET /api/billing/cancel[?project=<id>]` | browser session: what the cancel popups say, `{ ok, plan, trial, ends, refund, discount, offer }` (the plan would end that day; `trial`: nothing was charged; `ends`: the day the paid month would have run to; `refund`: the last payment as text when a cancel now gives it back, else null; `discount`: a discount or free months end with it; `offer`: `{ percent_off, months }` or null); nothing changes |
| `POST /api/billing/cancel/offer` | browser session and `Origin`, `{ project_id? }`: the person stays and the offer's coupon goes on the subscription; 409 when it cannot have it |
| `POST /api/billing/cancel` | browser session and `Origin`, `{ project_id? }`: the plan ends that day, trial or paid, with no refund; `{ ok, ended: true, ends: null }` |
| `POST /api/billing/cancel` | browser session and `Origin`, `{ project_id? }`: the plan ends that day, trial or paid; a cancel within 3 days of a renewal is refunded first; `{ ok, ended: true, ends: null, refunded }` |
| `POST /api/billing/resume` | browser session and `Origin`, `{ project_id? }`: a plan set to end goes on |
| `POST /api/billing/webhook` | Stripe only. The raw body must carry a valid `Stripe-Signature` (HMAC-SHA256 of `t.body`, any `v1`, within 5 minutes) under `STRIPE_WEBHOOK_SECRET` with a live key or `STRIPE_WEBHOOK_SECRET_TEST` with a test key; else 400. An event signed with the other mode's secret, or whose `livemode` is not the key's mode, is answered 200 and ignored (a test endpoint left over after going live). Handles `customer.subscription.created`, `.updated` and `.deleted`, `invoice.paid`, `charge.refunded` and `charge.dispute.created`, and subscribes to nothing else: they arrive for the whole Stripe account, so first, with no Stripe call, the customer must be in `accounts.stripe_customer_id`, and the subscription must look like GenClass's (the one recorded for the account, metadata `genclass=1` on it or copied onto the invoice, or a `genclass_` lookup key on a price). From an invoice only its subscription id is read; a refund or dispute of a GenClass customer's charge sends the owner `charge_refunded` or `charge_disputed` (ids and amounts; a dispute names no customer, so its charge is read first). Then it fetches the subscription (its prices' products, its customer and its latest invoice expanded), which must be provably GenClass's (every price a `genclass_` lookup key on a `genclass_plan` product, or the subscription already recorded for the account) and the account's (its customer's `genclass_account` names the account), and writes the plan, status, `past_due_since`, period end (when it ended, for one cancelled at once), cancel flag and mode. A subscription the account has not been granted yet is written only once its latest invoice is paid (or asks for nothing), never on `active` alone; another subscription than the account's current one never overwrites a live plan unless it was chosen as below. When a subscription starts billing (`created`, `updated` with a status change, or `invoice.paid`), if the customer has two GenClass subscriptions that bill and are paid for (a switch, or two tabs paid), the account keeps one (a switch's new plan; otherwise a live one, then the plan listed later in `billing/plans.json`, then the newest): it is written to the account first, then each other one is refunded to its payment method (a switch's old plan: its unused time; a duplicate: its latest payment in full; once, by the metadata `genclass_refund`) and cancelled at once with no proration, and `NOTIFY_WEBHOOK` gets `plan_switch` or `duplicate_subscription` with the refunds. A new subscription that is never paid (`incomplete`, `incomplete_expired`, or `active` with its invoice unpaid) changes nothing. The end of the subscription recorded for the account is applied even when its customer's metadata is gone (Stripe erasing a buyer's data on request). A purchase of a plan with `custom_model` (Individual) is recorded (`custom_requests`, `NOTIFY_WEBHOOK`, naming the plan) only when Stripe reports that plan's price paid: the subscription's latest invoice is paid and has a positive line on it (a first invoice, a switch included, seen on `invoice.paid` or the subscription's own events). Every other event (another business's subscriptions, in a shared account) is answered 200, logged as `stripe webhook: <type> <id> ignored: <reason>`, not stored, and nothing about it is fetched. The ids of events about GenClass customers are kept 30 days (`billing_events`), so a redelivery changes nothing; a failure answers 500 and Stripe retries. |
| `GET /api/billing` | browser session: `{ plan, subscription_status, current_period_end, cancel_at_period_end, on_sale, access, seats }` (`on_sale`: a plan is sold and this account can buy it); `access` is `paid`, `comp` (GenClass's grant), `open` (this server's `PLAN_GATES`) or null (Free); `seats`: the people the account holds, null for no limit |
Expand Down
10 changes: 5 additions & 5 deletions telemetry-worker/src/billing-pages.ts
Original file line number Diff line number Diff line change
Expand Up @@ -190,7 +190,6 @@ function gcCancel(project){
var body = project ? { project_id: project } : {};
function show(d){ if (d.showModal) d.showModal(); else d.setAttribute("open", ""); }
function hide(d){ if (!d.open) return; if (d.close) d.close(); else d.removeAttribute("open"); }
function day(iso){ var d = new Date(iso); return !iso || isNaN(d) ? "the end of your paid month" : d.toLocaleDateString(undefined, { day: "numeric", month: "long", year: "numeric" }); }
function text(id, t){ document.getElementById(id).textContent = t; }
if (resume) resume.addEventListener("click", function(e){
e.preventDefault(); err.textContent = ""; gcBusy(resume, true, "Resuming...");
Expand All @@ -203,16 +202,17 @@ function gcCancel(project){
e.preventDefault(); err.textContent = ""; gcBusy(open, true, "One moment...");
gcPost("/api/billing/cancel" + (project ? "?project=" + encodeURIComponent(project) : ""), undefined, "GET").then(function(j){
gcBusy(open, false); info = j;
var plan = j.plan || "paid", when = day(j.ends);
var lost = j.discount ? " Your discount or free months end today too and do not come back." : "";
text("cx1p", j.trial ? "Your " + plan + " trial ends today, as soon as you cancel. Nothing is charged." + lost : plan + " ends today, as soon as you cancel, not on " + when + ". Nothing is refunded for the days left." + lost);
var plan = j.plan || "paid";
var lost = j.discount ? " Your discount or free months end too and do not come back." : "";
var back = j.refund ? " Your last payment (" + j.refund + ") is refunded." : "";
text("cx1p", (j.trial ? "Your " + plan + " trial ends as soon as you cancel. Nothing is charged." : plan + " ends as soon as you cancel.") + back + lost);
if (j.offer) {
text("cx2h", "Stay and pay " + j.offer.percent_off + "% less");
text("cx2p", "Keep " + plan + " and get " + j.offer.percent_off + "% off your next " + j.offer.months + " months. Nothing else changes.");
document.getElementById("cx2take").lastChild.textContent = "Take " + j.offer.percent_off + "% off";
}
text("cx3h", "Cancel " + plan + " today?");
text("cx3p", j.trial ? "This is the last step. Your trial ends now." + lost : "This is the last step. " + plan + " ends now, with no refund." + lost);
text("cx3p", j.trial ? "This is the last step. Your trial ends now." : "This is the last step. " + plan + " ends now.");
show(d1);
}, function(x){ err.textContent = gcWhy(x); gcBusy(open, false); });
});
Expand Down
Loading
Loading