feat(billing): add monthly billing cycle for Team and Enterprise seats

[jeanduplessis]

Summary

This PR implements seat-based billing enforcement, membership audit tracking, and enterprise model restrictions, then applies a comprehensive KISS refactoring pass across the billing/subscription codebase.

Seat Billing Enforcement

• All new organizations now default to require_seats: true (migration 0064)
• Trial middleware and member invitation flows gate on seat availability
• Seat-change, resubscribe, and billing-cycle-change logic hardened to correctly handle mixed paid/free subscription items (uses unit_amount > 0 on client, KNOWN_SEAT_PRICE_IDS on server)

Membership Audit Tombstones

• New organization_membership_removals table (migration 0065) tracks who was removed, when, by whom, and their previous role
• Tombstone records prevent webhook-driven re-addition of intentionally removed members
• GDPR: softDeleteUser updated to delete/anonymize tombstone records

Enterprise Model Restrictions

• getEffectiveModelRestrictions() enforces model/provider deny lists only for enterprise orgs
• Defaults route returns appropriate errors when all models are blocked

KISS Refactoring

• Replaced 8 individual price constants + inferPlanFromUnitAmount() with SEAT_PRICING lookup table and seatPrice(plan, cycle) helper
• Extracted shared helpers: canManageBilling(), findPaidSeatItem(), paidSeatQuantity(), detectPendingCycleChange()
• Unified billingCycleFromDb and billingCycleFromStripeInterval into toBillingCycle()
• Renamed organizationOwnerProcedure → organizationBillingProcedure (14 files) to reflect actual role permissions
• Simplified BillingCycleChangeDialog.getPricing() from 28 lines to 5
• Tightened Stripe error detection: removed loose .includes('already') fallback
• Removed unused useOrganizationWithMembers dependency from UpgradeTrialDialog

Review Fixes (from automated review pass)

• Fixed GDPR gap: new organization_membership_removals not in softDeleteUser
• Fixed billing-cycle detection reading free items instead of paid items
• Renamed misleading paidSeatCount → defaultSeatCount in resubscribe-defaults API
• Fixed removed_by not passed in member removal router

Verification

• pnpm typecheck — passes with zero errors
• pnpm test — 3343 tests pass; 3 test failures caused by branch changes were identified and fixed:
  • stripe-3ds.test.ts: Updated mock items to include price.id for KNOWN_SEAT_PRICE_IDS
  • organization-subscription-event.test.ts: Mocked retrieveSubscription for H1 guard test
  • defaults/route.test.ts: Set plan: 'enterprise' on mock orgs that test deny-list enforcement
• Remaining 1 failure (kiloclaw-billing-router.test.ts timeout) is pre-existing/flaky
• Full manual verification against Stripe test env.

Manual Verification Plan

# Manual Verification Plan: Monthly Billing for Teams & Enterprise

Prerequisites (All Journeys)

• Dev server running (read port from .dev-port)
• Stripe test mode enabled with test card 4242 4242 4242 4242 (any future expiry, any CVC)
• Access to the database to verify records
• Access to Stripe dashboard (test mode) to verify subscription objects

---

Part A: Teams Subscription Paths

Journey A1: New Org → Teams Monthly Subscription

Pre-setup: None (fresh user).

Steps:

1. Log in as a new fake user.
2. Navigate to /organizations/new.
3. Fill in organization name and submit. You will be redirected to /organizations/{orgId}/welcome?firstTime=1.
4. Navigate to the subscription page at /organizations/{orgId}/subscription.
5. Observe the "No Active Subscription" state. Click the upgrade CTA (or trigger the upgrade dialog from a trial banner).
6. In the Upgrade Dialog:
   • Verify the billing cycle toggle defaults to Annual.
   • Click the Monthly toggle button.
   • Verify the "Save 17%" badge becomes faded/dim.
   • Select the Teams plan card.
   • Verify the price shown is $18/seat/month.
   • Set seat count to 3.
   • Verify the button reads "Purchase Teams Plan".
7. Click "Purchase Teams Plan". You should be redirected to Stripe Checkout.
8. On Stripe Checkout:
   • Verify the line item shows 3 seats at $18/seat/month = $54/month.
   • Verify billing address collection is required.
   • Complete payment with test card.
9. After successful payment, you are redirected back to the app.

End-state validation:

Check	Expected
UI: Subscription page	Status badge: "Active". Billing Cycle: "Monthly". Seats Used: 1/3. Next Payment: $54.00. Days Until Renewal: ~30.
UI: Quick Actions	"Change Seats", "Switch to Annual", "Update Payment Method", "View Payment History", "Cancel Subscription" all visible.
DB: organizations table	plan = 'teams', seat_count = 3.
DB: organization_seats_purchases	One row: subscription_status = 'active', seat_count = 3, billing_cycle = 'monthly', amount_usd = 5400 (cents).
Stripe Dashboard	Subscription active, interval = month, price = Teams Monthly price ID, quantity = 3. Metadata: type=seats, planType=teams.

---

Journey A2: New Org → Teams Annual Subscription

Pre-setup: None (fresh user).

Steps:

1. Log in as a new fake user.
2. Create a new organization via /organizations/new.
3. Navigate to /organizations/{orgId}/subscription and trigger the upgrade dialog.
4. In the Upgrade Dialog:
   • Leave the billing cycle toggle on Annual (default).
   • Select the Teams plan card.
   • Verify the price shown is $15/seat/month (billed as $180/seat/year).
   • Set seat count to 5.
5. Click "Purchase Teams Plan" and complete Stripe Checkout.
   • Verify the Stripe checkout shows 5 seats at $180/seat/year = $900/year.

End-state validation:

Check	Expected
UI: Subscription page	Billing Cycle: "Yearly". Seats Used: 1/5. Next Payment reflects annual amount.
UI: Quick Actions	"Switch to Monthly" button visible.
DB: organizations	plan = 'teams', seat_count = 5.
DB: organization_seats_purchases	billing_cycle = 'yearly', seat_count = 5, amount_usd = 90000.
Stripe	Subscription interval = year, Teams Annual price ID.

---

Journey A3: Teams Monthly → Switch to Annual Billing

Pre-setup: Complete Journey A1 (active Teams Monthly subscription with 3 seats).

Steps:

1. Navigate to /organizations/{orgId}/subscription.
2. In Quick Actions, click "Switch to Annual".
3. In the Billing Cycle Change Dialog:
   • Verify "Now" row shows: Monthly billing — $18/seat/month.
   • Verify "New" row shows: Annual billing — $15/seat/month.
   • Verify total cost comparison: $54/mo → $45/mo (billed as $540/yr).
   • Verify the effective date annotation shows the current period end date.
   • No amber "cost increase" warning should appear (switching to annual is a discount).
4. Click "Switch to Annual". Observe success toast.

End-state validation:

Check	Expected
UI: Subscription page	Billing Cycle shows: "Monthly → Yearly". Amber banner: "Switching to Annual billing on {date}." with a "Cancel Change" button. Next Payment shows "Changes at renewal".
UI: Quick Actions	"Switch to Annual/Monthly" button is hidden (pending schedule blocks further changes).
Stripe	A subscription schedule exists with 2 phases. Phase 1: current monthly price. Phase 2: Teams Annual price, starting at current period end.

---

Journey A4: Teams Annual → Switch to Monthly Billing

Pre-setup: Complete Journey A2 (active Teams Annual subscription with 5 seats).

Steps:

1. Navigate to /organizations/{orgId}/subscription.
2. In Quick Actions, click "Switch to Monthly".
3. In the Billing Cycle Change Dialog:
   • Verify "Now" row: Annual billing — $15/seat/month.
   • Verify "New" row: Monthly billing — $18/seat/month.
   • Verify total: $75/mo → $90/mo.
   • Verify the amber cost warning appears: "Switching to monthly billing will increase your per-seat cost from $15 to $18 per month."
4. Click "Switch to Monthly". Observe success toast.

End-state validation:

Check	Expected
UI	Billing Cycle: "Yearly → Monthly". Amber pending-change banner visible.
Stripe	Schedule phase 2 uses Teams Monthly price ID.

---

Journey A5: Cancel Pending Billing Cycle Change (Teams)

Pre-setup: Complete Journey A3 or A4 (pending billing cycle change exists).

Steps:

1. On the subscription page, locate the amber banner: "Switching to {target} billing on {date}."
2. Click "Cancel Change".
3. Observe success toast.

End-state validation:

Check	Expected
UI	Amber banner gone. Billing Cycle reverts to original value (no arrow). "Switch to Annual/Monthly" button reappears in Quick Actions.
Stripe	Subscription schedule released (status = canceled or removed).

---

Journey A6: Teams Monthly → Cancel → Resubscribe (Preserves Monthly)

Pre-setup: Active Teams Monthly subscription (e.g., from Journey A1).

Steps:

1. On subscription page, click "Cancel Subscription" in Quick Actions.
2. In the cancel modal, confirm cancellation.
3. Observe: amber banner "Subscription will be canceled" with "Stop Pending Cancellation" button. Status still "Active".
4. Wait for the subscription to reach its period end (or use Stripe dashboard to advance the test clock). Once ended:
   • Page shows red banner: "Subscription has been canceled" with "Resubscribe" button.
5. Click "Resubscribe". You should be redirected to Stripe Checkout.
6. On Stripe Checkout, verify:
   • The billing interval is monthly (preserved from previous subscription).
   • Seat count matches the previous paid seat quantity.

End-state validation:

Check	Expected
Stripe Checkout	Monthly billing pre-selected, correct seat count from ended subscription.
After completing checkout: DB	New organization_seats_purchases row with billing_cycle = 'monthly'. Organization seat_count restored.

---

Journey A7: Teams Monthly → Mid-Subscription Seat Increase

Pre-setup: Active Teams Monthly subscription with 3 seats.

Steps:

1. On subscription page, click "Change Seats" in Quick Actions.
2. In the Seat Change Modal:
   • Current seat count shown: 3.
   • Increase to 5.
   • Verify the prorated amount preview.
3. Confirm the change.

End-state validation:

Check	Expected
UI	Seats Used: 1/5. Next Payment updated to reflect 5 seats.
DB: organizations	seat_count = 5.
DB: organization_seats_purchases	New row with seat_count = 5, billing_cycle = 'monthly'.
Stripe	Prorated invoice generated. Subscription quantity = 5.

---

Journey A8: Teams Monthly → Mid-Subscription Seat Decrease

Pre-setup: Active Teams Monthly subscription with 5 seats, 2 seats in use.

Steps:

1. Click "Change Seats" → decrease to 3.
2. Confirm the change.

End-state validation:

Check	Expected
UI	Seats Used: 2/5 (NOT 2/3 — downgrade deferred to next period). Seat Count Change Notification appears: "Next billing cycle your total seats will drop from 5 to 3".
DB: organizations	seat_count = 5 (unchanged until next period).
Stripe	Subscription quantity = 3 with proration_behavior: none. Change effective at period end.

---

Part B: Enterprise Subscription Paths

Journey B1: New Org → Enterprise Monthly Subscription

Pre-setup: None (fresh user).

Steps:

1. Log in as a new fake user and create a new organization.
2. Navigate to /organizations/{orgId}/subscription and trigger the upgrade dialog.
3. In the Upgrade Dialog:
   • Click the Monthly toggle.
   • The Enterprise plan card should already be selected (org starts on Enterprise plan, so currentPlan = enterprise and the dialog initializes selectedPlan to currentPlan).
   • Verify the price shown is $72/seat/month.
   • Set seat count to 2.
4. Click "Purchase Enterprise Plan" and complete Stripe Checkout.
   • Verify Stripe shows: 2 seats at $72/seat/month = $144/month.

End-state validation:

Check	Expected
UI: Subscription page	Status: "Active". Billing Cycle: "Monthly". Seats Used: 1/2. Next Payment: $144.00.
UI: Quick Actions	"Switch to Annual" visible.
DB: organizations	plan = 'enterprise', seat_count = 2.
DB: organization_seats_purchases	billing_cycle = 'monthly', seat_count = 2, amount_usd = 14400.
Stripe	Interval = month, Enterprise Monthly price ID, quantity = 2.

---

Journey B2: New Org → Enterprise Annual Subscription

Pre-setup: None (fresh user).

Steps:

1. Log in, create org, trigger upgrade dialog.
2. Leave billing cycle on Annual (default).
3. Enterprise plan should be pre-selected.
4. Verify price: $60/seat/month (billed as $720/seat/year).
5. Set seat count to 10.
6. Complete checkout.
   • Verify Stripe shows: 10 seats at $720/seat/year = $7,200/year.

End-state validation:

Check	Expected
UI	Billing Cycle: "Yearly". Seats Used: 1/10.
DB	plan = 'enterprise', seat_count = 10, purchase billing_cycle = 'yearly', amount_usd = 720000.

---

Journey B3: Enterprise Monthly → Switch to Annual Billing

Pre-setup: Active Enterprise Monthly subscription (e.g., Journey B1, 2 seats).

Steps:

1. Click "Switch to Annual" in Quick Actions.
2. In dialog:
   • "Now": Monthly — $72/seat/month
   • "New": Annual — $60/seat/month
   • Total: $144/mo → $120/mo (billed $1,440/yr)
   • No cost-increase warning.
3. Confirm switch.

End-state validation:

Check	Expected
UI	Billing Cycle: "Monthly → Yearly". Pending change banner with effective date.
Stripe	Schedule phase 2: Enterprise Annual price ID.

---

Journey B4: Enterprise Annual → Switch to Monthly Billing

Pre-setup: Active Enterprise Annual subscription (Journey B2, 10 seats).

Steps:

1. Click "Switch to Monthly".
2. In dialog:
   • "Now": Annual — $60/seat/month
   • "New": Monthly — $72/seat/month
   • Total: $600/mo → $720/mo
   • Amber warning: "Switching to monthly billing will increase your per-seat cost from $60 to $72 per month."
3. Confirm.

End-state validation:

Check	Expected
UI	Billing Cycle: "Yearly → Monthly". Pending change banner.
Stripe	Schedule phase 2: Enterprise Monthly price ID.

---

Journey B5: Cancel Pending Billing Cycle Change (Enterprise)

Pre-setup: Complete Journey B3 or B4.

Identical steps and validation as Journey A5 but for Enterprise pricing.

---

Journey B6: Enterprise Monthly → Cancel → Resubscribe (Preserves Monthly)

Pre-setup: Active Enterprise Monthly subscription.

Steps:

1. Cancel subscription via Quick Actions.
2. After subscription ends (advance test clock or wait), click "Resubscribe".
3. Verify Stripe Checkout defaults to monthly billing and previous paid seat count.
4. Complete checkout.

End-state validation:

Check	Expected
DB	New purchase with billing_cycle = 'monthly'. Org plan = 'enterprise', seat_count restored.

---

Journey B7: Enterprise Monthly → Mid-Subscription Seat Increase

Pre-setup: Active Enterprise Monthly, 2 seats.

Steps:

1. "Change Seats" → increase to 5.
2. Confirm.

End-state validation:

Check	Expected
UI	Seats Used: 1/5.
DB	seat_count = 5. New purchase row.
Stripe	Prorated invoice for 3 additional seats at $72/seat/month.

---

Journey B8: Enterprise Monthly → Mid-Subscription Seat Decrease

Pre-setup: Active Enterprise Monthly, 5 seats, 2 in use.

Steps:

1. "Change Seats" → decrease to 3.
2. Confirm.

End-state validation:

Check	Expected
UI	Seats still 2/5. "Seat Count Change Scheduled" notification: "Next billing cycle your total seats will drop from 5 to 3".
Stripe	Quantity = 3, no proration.

---

Part C: Cross-Plan Journeys (Monthly-Specific)

Journey C1: Enterprise Trial → Choose Teams Monthly at Checkout

Pre-setup: New org (starts on Enterprise trial).

Steps:

1. Trigger upgrade dialog.
2. Select Monthly toggle, then select the Teams plan card.
3. Note the plan card should show "Downgrade" badge on Teams (since current plan is Enterprise).
4. Verify price is $18/seat/month.
5. Complete checkout.

End-state validation:

Check	Expected
DB: organizations	plan = 'teams' (changed from enterprise).
Stripe metadata	planType = 'teams'.
UI	Enterprise-only settings (model deny lists, provider deny lists) no longer visible in org settings.

---

Journey C2: Upgrade Dialog Defaults — Verify Resubscribe Seeding

Pre-setup: Org that previously had a Teams Monthly subscription (now ended) with 5 paid seats.

Steps:

1. Trigger upgrade dialog.
2. Verify:
   • Billing cycle toggle is pre-set to Monthly (seeded from last ended subscription).
   • Seat count is pre-filled with max(previousPaidSeats, currentUsedSeats).

End-state validation: Visual confirmation only — the dialog correctly seeds from getResubscribeDefaults.

---

Part D: Access Control Verification (Applies to Both Plans)

Journey D1: Billing Manager Can Manage Monthly Subscription

Pre-setup: Active monthly subscription. Invite a user with billing_manager role.

Steps:

1. Log in as the billing manager.
2. Navigate to /organizations/{orgId}/subscription.
3. Verify Quick Actions are visible: Change Seats, Switch to Annual/Monthly, Cancel Subscription.
4. Verify the billing manager does NOT count toward seat usage.

---

Journey D2: Regular Member Cannot Manage Subscription

Pre-setup: Active monthly subscription. Invite a user with member role.

Steps:

1. Log in as the member.
2. Navigate to /organizations/{orgId}/subscription.
3. Verify: Can see subscription status and seat usage, but Quick Actions (Change Seats, Cancel, Change Billing Cycle) are NOT available.

---

Database Queries for Validation

-- Check organization plan, seat count
SELECT id, name, plan, seat_count, require_seats, free_trial_end_at
FROM organizations WHERE id = '<org_id>';

-- Check seat purchases
SELECT id, subscription_stripe_id, seat_count, amount_usd,
       subscription_status, billing_cycle, starts_at, expires_at
FROM organization_seats_purchases
WHERE organization_id = '<org_id>'
ORDER BY created_at DESC;

-- Check seat usage (members excluding billing managers)
SELECT u.email, om.role
FROM organization_memberships om
JOIN users u ON u.id = om.user_id
WHERE om.organization_id = '<org_id>'
  AND om.removed_at IS NULL;

---

Summary Matrix

Journey	Plan	Billing Cycle	Action
A1	Teams	Monthly	New subscription
A2	Teams	Annual	New subscription
A3	Teams	Monthly → Annual	Billing cycle change
A4	Teams	Annual → Monthly	Billing cycle change
A5	Teams	Any	Cancel pending cycle change
A6	Teams	Monthly	Cancel → Resubscribe
A7	Teams	Monthly	Mid-sub seat increase
A8	Teams	Monthly	Mid-sub seat decrease
B1	Enterprise	Monthly	New subscription
B2	Enterprise	Annual	New subscription
B3	Enterprise	Monthly → Annual	Billing cycle change
B4	Enterprise	Annual → Monthly	Billing cycle change
B5	Enterprise	Any	Cancel pending cycle change
B6	Enterprise	Monthly	Cancel → Resubscribe
B7	Enterprise	Monthly	Mid-sub seat increase
B8	Enterprise	Monthly	Mid-sub seat decrease
C1	Enterprise → Teams	Monthly	Plan downgrade at checkout
C2	Any	Monthly	Resubscribe default seeding
D1	Any	Monthly	Billing manager access
D2	Any	Monthly	Member access denied

Visual Changes

Recording: https://cln.sh/WXNR7wNZ

Reviewer Notes

• Legacy price constant exports are preserved as derived values from SEAT_PRICING for backward compatibility — no external consumers need updating
• organizationBillingProcedure rename is purely cosmetic (same ['owner', 'billing_manager'] role check) but touches 14 router files
• The require_seats DB default change (migration 0064) only affects code paths that omit the column on insert; all production insert paths explicitly set the value
• toBillingCycle accepts the union of DB ('yearly') and Stripe ('year') values; old function names are retained as typed aliases

[kilo-code-bot]

Code Review Summary

Status: 5 Issues Found | Recommendation: Address before merge

Overview

Severity	Count
CRITICAL	1
WARNING	4
SUGGESTION	0

Issue Details (click to expand)

CRITICAL

File	Line	Issue
src/routers/organizations/organization-members-router.ts	49	Billing managers can still invite/remove members and promote accounts to owner.

WARNING

File	Line	Issue
src/routers/organizations/organization-subscription-router.ts	93	Ended subscriptions still surface an Update Payment Method action that the portal endpoint rejects.
src/lib/organizations/organization-seats.ts	199	Stripe lookup failures still fail open in the duplicate-subscription guard.
src/lib/stripe.ts	1293	The cancel fallback still releases an attached schedule after any cancel error, so transient Stripe failures can drop a pending billing-cycle change.
src/routers/organizations/organization-settings-router.ts	187	Billing managers can still edit non-billing organization settings.

Other Observations (not in diff)

None.

Files Reviewed (52 files)

• src/routers/organizations/organization-members-router.ts - 1 issue persists
• src/routers/organizations/organization-subscription-router.ts - 1 issue persists
• src/routers/organizations/organization-settings-router.ts - 1 issue persists
• src/lib/organizations/organization-seats.ts - 1 issue persists
• src/lib/stripe.ts - 1 issue persists
• 47 additional changed non-generated files reviewed - no new issues

Fix these issues in Kilo Cloud

---

_{Reviewed by gpt-5.4-20260305 · 5,572,415 tokens}

[jrf0110]

How has this been tested? I don't see any new products in test mode in stripe