feat(checkout): let buyers choose Server capacity (#7782)

Adds the capacity step to self-hosted checkout. the field is ignored
until [#325
](Stirling-Tools/Stirling-PDF-SaaS#325) lands.
<img width="1262" height="487" alt="image"
src="https://github.com/user-attachments/assets/c22d0b15-103a-491a-bd98-df772e63c71b"
/>

## What it does

A capacity stage between billing period and payment, for the **Server
tier only**. Enterprise is priced per seat and Free has nothing to size,
so both go straight to payment exactly as before.

The stepper counts **servers**, because that is the unit we sell. Every
figure beside it is stated in **users**, because that is the unit an
admin measures. The line item does the translation, so a buyer picks "3
servers" and reads "300 users" without converting anything themselves.

`server_quantity` now rides `createCheckoutSession` through to the edge
function. Before this the base line item was always `quantity: 1`, and
the only way to buy more capacity was Stripe's own portal after the
fact.

## Two guards on the stepper

**It cannot go below current usage.** An installation running 240 users
cannot buy fewer than three servers. Reducing capacity is a renewal
conversation, not something checkout should do by stranding accounts
that already exist.

**At five servers, or a thousand users, it offers an enterprise quote**
beside the purchase. Deliberately an option and not a gate — self-serve
checkout still completes. `onContactSales` is optional, so the door only
appears where a caller wires it up.

## Review notes

- **`USERS_PER_SERVER = 100` is a frontend constant** in
`utils/capacity.ts`. The authoritative value lives on `pricing_policy`
and is resolved server-side at licence-issue time, but before a purchase
there is no licence to read it from and the packaging RPC is not
anon-callable. The comment says so. A follow-up could serve it from
`stripe-price-lookup`, which the plan page already calls; I kept it out
of scope so this PR stays inside one repo.
- The `SELF_SERVE_MAX_SERVERS` bound here is cosmetic. `create-checkout`
clamps server-side against the policy, so a crafted request cannot
exceed it regardless of what the stepper allows.
- No copy sweep needed — `plan.features.usersIncluded` already reads
"100 users included" on main.

## Testing

- 5 unit tests on the capacity arithmetic and the enterprise-door
threshold.
- 5 Storybook stories: single server, multiple servers monthly,
constrained by current users, below current usage (blocked), and the
enterprise door.

Author: ConnorYoh

frontend/editor/public/locales/en-US/translation.toml

@@ -6311,6 +6311,23 @@ upgradeSuccess = "Payment successful! Your subscription has been upgraded. The l
 upgradeTitle = "Upgrade to {{planName}}"
 yearly = "Yearly"
 
+[payment.capacityStage]
+continue = "Continue to payment"
+customHint = "Rounded up to the next block of {{users}}."
+customLabel = "Number of users"
+dueToday = "Due today"
+enterpriseQuote = "Get an enterprise quote"
+lineItem = "Team · {{price}}{{period}} per {{block}} users"
+minimumForCurrentUsers = "You have {{users}} users, so the plan must cover at least {{minimum}}."
+modalTitle = "Upgrade to {{planName}}"
+other = "Other"
+perMonth = "/mo"
+perYear = "/yr"
+renewalNote = "Renews at {{total}}{{period}}. Cancel any time in Usage & Billing."
+subheading = "Covers everyone you invite, in blocks of {{users}} users."
+usersLabel = "Users"
+userTotal = "{{users}} users"
+
 [payment.emailStage]
 continue = "Continue"
 description = "We'll use this to send your license key and receipts."

frontend/editor/src/proprietary/components/shared/stripeCheckout/StripeCheckout.tsx

@@ -18,6 +18,8 @@ import { useLicensePolling } from "@app/components/shared/stripeCheckout/hooks/u
 import { useCheckoutSession } from "@app/components/shared/stripeCheckout/hooks/useCheckoutSession";
 import { EmailStage } from "@app/components/shared/stripeCheckout/stages/EmailStage";
 import { PlanSelectionStage } from "@app/components/shared/stripeCheckout/stages/PlanSelectionStage";
+import { CapacityStage } from "@app/components/shared/stripeCheckout/stages/CapacityStage";
+import { blocksForUsers } from "@app/components/shared/stripeCheckout/utils/capacity";
 import { PaymentStage } from "@app/components/shared/stripeCheckout/stages/PaymentStage";
 import { SuccessStage } from "@app/components/shared/stripeCheckout/stages/SuccessStage";
 import { ErrorStage } from "@app/components/shared/stripeCheckout/stages/ErrorStage";
@@ -83,6 +85,7 @@ const StripeCheckout: React.FC<StripeCheckoutProps> = ({
     checkoutState.setCurrentLicenseKey,
     checkoutState.setPollingStatus,
     minimumSeats,
+    checkoutState.serverQuantity,
     polling.pollForLicenseKey,
     onSuccess,
     onError,
@@ -106,9 +109,19 @@ const StripeCheckout: React.FC<StripeCheckoutProps> = ({
     }
   };
 
+  // Only the Team tier is sold by capacity. Enterprise is priced per seat and free has nothing to
+  // size, so both go straight to payment.
+  const sellsCapacity = planGroup.tier === "server";
+
   // Plan selection handler
   const handlePlanSelect = (period: "monthly" | "yearly") => {
     checkoutState.setSelectedPeriod(period);
+    if (sellsCapacity) {
+      // Arrive on the capacity an installation already needs rather than on a blocked minimum.
+      checkoutState.setServerQuantity(blocksForUsers(minimumSeats));
+      navigation.goToStage("capacity");
+      return;
+    }
     navigation.goToStage("payment");
   };
 
@@ -234,6 +247,17 @@ const StripeCheckout: React.FC<StripeCheckoutProps> = ({
           />
         );
 
+      case "capacity":
+        return (
+          <CapacityStage
+            selectedPlan={checkoutState.selectedPlan}
+            serverQuantity={checkoutState.serverQuantity}
+            setServerQuantity={checkoutState.setServerQuantity}
+            currentUsers={minimumSeats}
+            onContinue={() => navigation.goToStage("payment")}
+          />
+        );
+
       case "payment":
         return (
           <PaymentStage

frontend/editor/src/proprietary/components/shared/stripeCheckout/hooks/useCheckoutSession.ts

@@ -19,6 +19,7 @@ export const useCheckoutSession = (
   setCurrentLicenseKey: React.Dispatch<React.SetStateAction<string | null>>,
   setPollingStatus: React.Dispatch<React.SetStateAction<PollingStatus>>,
   minimumSeats: number,
+  serverQuantity: number,
   pollForLicenseKey: (installId: string) => Promise<void>,
   onSuccess?: (sessionId: string) => void,
   onError?: (error: string) => void,
@@ -76,6 +77,7 @@ export const useCheckoutSession = (
         current_license_key: existingLicenseKey,
         requires_seats: selectedPlan.requiresSeats,
         seat_count: Math.max(1, Math.min(minimumSeats || 1, 10000)),
+        server_quantity: Math.max(1, serverQuantity || 1),
         email: state.email, // Pass collected email from Stage 1
       });
 
@@ -111,6 +113,7 @@ export const useCheckoutSession = (
     state.email,
     installationId,
     minimumSeats,
+    serverQuantity,
     setState,
     setInstallationId,
     setCurrentLicenseKey,

frontend/editor/src/proprietary/components/shared/stripeCheckout/hooks/useCheckoutState.ts

@@ -20,6 +20,8 @@ export const useCheckoutState = (planGroup: PlanTierGroup) => {
   const [selectedPeriod, setSelectedPeriod] = useState<"monthly" | "yearly">(
     planGroup.yearly ? "yearly" : "monthly",
   );
+  // Blocks of users to buy. Only the Team tier asks; every other tier stays at one.
+  const [serverQuantity, setServerQuantity] = useState<number>(1);
   const [installationId, setInstallationId] = useState<string | null>(null);
   const [currentLicenseKey, setCurrentLicenseKey] = useState<string | null>(
     null,
@@ -50,6 +52,7 @@ export const useCheckoutState = (planGroup: PlanTierGroup) => {
     setCurrentLicenseKey(null);
     setLicenseKey(null);
     setSelectedPeriod(planGroup.yearly ? "yearly" : "monthly");
+    setServerQuantity(1);
   }, [planGroup]);
 
   return {
@@ -64,6 +67,8 @@ export const useCheckoutState = (planGroup: PlanTierGroup) => {
     setEmailError,
     selectedPeriod,
     setSelectedPeriod,
+    serverQuantity,
+    setServerQuantity,
     installationId,
     setInstallationId,
     currentLicenseKey,

frontend/editor/src/proprietary/components/shared/stripeCheckout/stages/CapacityStage.stories.tsx

@@ -0,0 +1,80 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { useState } from "react";
+import { CapacityStage } from "@app/components/shared/stripeCheckout/stages/CapacityStage";
+import { PlanTier } from "@app/services/licenseService";
+
+/**
+ * The capacity step of the Stripe checkout, between billing period and payment. Only the Team tier
+ * reaches it: the buyer picks users, and the plan is priced per block of 100.
+ */
+const yearlyPlan: PlanTier = {
+  id: "server-yearly",
+  name: "Team",
+  price: 990,
+  currency: "$",
+  period: "/year",
+  features: [],
+  highlights: [],
+  lookupKey: "selfhosted:server:yearly",
+};
+
+const monthlyPlan: PlanTier = {
+  ...yearlyPlan,
+  id: "server-monthly",
+  price: 99,
+  period: "/month",
+};
+
+const meta = {
+  title: "StripeCheckout/CapacityStage",
+  component: CapacityStage,
+  args: {
+    selectedPlan: yearlyPlan,
+    serverQuantity: 1,
+    setServerQuantity: () => {},
+    onContinue: () => {},
+  },
+  // The stepper is the point of this stage, so stories own the quantity and let it move.
+  render: function Interactive(args) {
+    const [quantity, setQuantity] = useState(args.serverQuantity);
+    return (
+      <CapacityStage
+        {...args}
+        serverQuantity={quantity}
+        setServerQuantity={setQuantity}
+      />
+    );
+  },
+} satisfies Meta<typeof CapacityStage>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+/** A fresh purchase: the smallest block, 100 users. */
+export const SingleBlock: Story = {};
+
+/** 300 users on the monthly plan, so the total is three block prices. */
+export const ThreeBlocksMonthly: Story = {
+  args: { selectedPlan: monthlyPlan, serverQuantity: 3 },
+};
+
+/**
+ * An installation already running 240 users cannot buy cover for fewer than 300. Reducing capacity
+ * is a renewal conversation, not something checkout does by stranding accounts.
+ */
+export const ConstrainedByCurrentUsers: Story = {
+  args: { serverQuantity: 3, currentUsers: 240 },
+};
+
+/** Below the minimum the continue button is blocked and the reason is stated. */
+export const BelowCurrentUsage: Story = {
+  args: { serverQuantity: 1, currentUsers: 240 },
+};
+
+/**
+ * At the self-serve maximum the enterprise quote is offered beside the purchase. It is an option,
+ * never a wall: self-serve checkout still completes.
+ */
+export const OffersEnterpriseQuote: Story = {
+  args: { serverQuantity: 5, onContactSales: () => {} },
+};