feat(billing): bill free and committed seats from arrangements

Merged
ET
9d ago
+607-112

What

  • One billed seats rule: max(committed, members - free), which can be 0. Seat sync and every subscription update use it.
  • Seat changes are immediate on every workspace: an increase is billed right away, a decrease applies right away with a prorated credit. Seat sync never creates a Stripe schedule. If a pending downgrade already has one, the new count is carried into its next phase, as before. Trials are unchanged.
  • At each renewal, workspaces with seat arrangements get a seat sync, so an arrangement that started or ended without a member change is applied from the new period.
  • Hard cap: every way of joining goes through addUserToWorkspaceIfUserNotInWorkspace, which now refuses a new member at the cap. The check and the join run under a per-workspace lock, so two joins can't both take the last seat. Sign-up also checks the cap before creating the user. Skipped when billing is off.

Also changes for every paid workspace

  • Subscription updates (seats, plan, interval, credit price) run under a per-workspace lock, so a seat job and a plan switch can't rewrite the same Stripe schedule at the same time.
  • The period end used for schedule phases is read from the Stripe subscription instead of our database copy, which can be stale until the renewal webhook is processed.
  • Plan, interval and credit price changes compute seats with the rule above instead of the raw member count. Without seat arrangements, that's the same number.

To confirm

  • With free seats on top of a hard cap, the cap is committed + free, so the customer is never billed above the commitment.
  • A commitment ending exactly at renewal is billed at the old count on the renewal invoice, then credited on the next one. Staff can set the end date a day before renewal to avoid it.

Not in this PR

  • Admin actions to create and end seat arrangements.

Testing

  • 11 new unit tests on the seat rule and the hard cap. The billing, billing webhook, user-workspace and auth suites pass (533 tests). Lint and format clean. Typecheck passes except for modules missing from a local install (MCP SDK, twenty-sdk renderer build).
  • An earlier version, which held decreases in a Stripe schedule until renewal, was QA'd against Stripe test mode on a local lane. Its failures (lost decreases and lost plan downgrades when the schedule was rewritten) led to this simpler rule. This version has not run against Stripe yet.