PAYG prepaid usage bundles (#7032)

# Prepaid usage bundles

Teams on pay‑as‑you‑go can **buy a year of PDF processing up front, at a
discount** — *"12 months for the price of 10."* You pre‑buy a pool of
credits; they're spent **before** any metered billing and sit
**outside** the monthly spend limit; unused capacity expires after 12
months.

---

## What this PR delivers

**Buy → quote → invoice → pay (Stripe‑Quotes‑native).**
- A team lead sizes the pool in the calculator (persisted as a quote
row), which doubles as the quote page with a **"Download quote (PDF)"**
— the PDF is **Stripe's own rendered quote** (same mechanism procurement
uses), not an app‑generated document.
- **Finalise** turns the accepted quote into an invoice; the lead can
**download the invoice** or **pay online** (Stripe hosted invoice).
**Card and bank‑transfer / PO** are both supported (payment‑method
fork), on net terms.
- The billing page loads the in‑flight quote/invoice on open, so the CTA
resumes the right step (**View quote** / **Pay invoice to complete**)
and offers **Cancel purchase** (voids the invoice + quote and restarts).

**Prepaid is usable on its own — no subscription required.** The
entitlement gate honours a live prepaid pool in both cases:
- *Unsubscribed*: once the one‑time free grant is spent, a live pool
keeps the team **fully entitled** (all feature gates) rather than
degraded.
- *Subscribed*: a team **at/over its metered cap** but holding a live
pool stays fully entitled — prepaid draws are netted out of metered
spend, so the pool genuinely sits outside the cap.

Only when the free grant **and** the prepaid pool are both empty do
billable categories stop.

**Coordinated SaaS change (ships with this — `Stirling-PDF-SaaS` `v3`
branch):** the `invoice.paid` webhook credits the pool idempotently
(keyed on the invoice id) and settles the quote. Metered‑subscription
provisioning is best‑effort and **classified** — a permanent Stripe 4xx
(the single‑use hosted‑invoice card can't be attached) is a claimed
no‑op (HTTP 200, no retry) so Stripe doesn't redeliver forever; only
transient errors (5xx / connection / rate‑limit) retry. A failed credit
now retries rather than silently dropping a paid bundle.

### Flow

1. Lead sizes the pool and agrees to the terms → the browser sends team
+ capacity + consent, **never a price**.
2. A leader‑gated server function looks up the price and creates a
Stripe **quote** (line quantity = capacity).
3. Lead **finalises** → the quote becomes a Stripe **invoice**; download
it or pay online (card or bank transfer).
4. On `invoice.paid`, the webhook **credits the prepaid pool**
(idempotent) and settles the quote.
5. Usage then draws **free grant → prepaid pool → meter**; the pool is
usable with no subscription.

<img width="1280" height="920" alt="01-activation-fork"
src="https://github.com/user-attachments/assets/e8981dc7-809d-4fc5-bfde-71e619096b7b"
/>
<img width="1280" height="920" alt="02-calculator"
src="https://github.com/user-attachments/assets/81f6b886-1797-4c54-ba18-97d126be78e2"
/>
<img width="1120" height="600" alt="03-free-plan"
src="https://github.com/user-attachments/assets/c4057fde-d965-47dd-93e8-f2f0f612aa73"
/>
<img width="1105" height="1285" alt="04-subscribed-prepaid"
src="https://github.com/user-attachments/assets/9d1d0ef1-29d0-4bd4-9c17-ac5f68f88ca8"
/>


---

## In a follow‑up (not this PR)

1. **Authoritative price via an inline fixed‑amount coupon** *(in
progress in a separate PR).* Replace the percentage 12‑for‑10 coupon
with an edge‑function‑computed **`amount_off`** coupon: the invoice
shows a concrete "−$X.00" discount line, the total is deterministic (no
percentage‑rounding drift), and the persisted price becomes
**server‑authoritative**. Money‑mechanism change — needs validation
against the Stripe test env, so it warrants its own testable PR.
2. **Metered auto‑resume when the pool empties.** Save the paying card
at invoice time (`setup_future_usage`) for card payers → real
`charge_automatically`; a cardless `send_invoice` subscription for
bank‑transfer / PO. This makes the "processing continues at the metered
rate" promise true for everyone.
3. **Provisioning idempotency hardening** (SaaS repo). Idempotency key
on subscription creation + a conditional link RPC, so a webhook
redelivery or link‑RPC failure can't create duplicate or orphaned
subscriptions.
4. **Repo‑wide "credits" copy** across *all* of usage & billing (this PR
only makes its own additions consistent).

---

## Known edges (current state)

- **Cardless teams degrade when the pool empties.** An unsubscribed
bundle team that runs the pool dry hits DEGRADED (metered paused), not
automatic metered continuation — because no metered subscription gets
provisioned off a hosted‑invoice card. The consent copy states
processing "continues at the metered rate"; that promise is
intentionally **ahead of the mechanism** (follow‑up 2), and the 12‑month
term is the runway to deliver it. The prepaid capacity itself stays
fully usable in the meantime.
- **In‑app total vs charge can differ by ≤1¢** until follow‑up 1 lands.
The **shared approval document (the Stripe quote PDF) and the actual
invoice are already Stripe‑authoritative**; the persisted price shown
in‑app is still a front‑end estimate (percentage‑coupon rounding), so it
can differ from Stripe by a rounding cent. Resume‑time drift is fixed
(frozen to persisted); exact‑to‑the‑penny parity arrives with the
authoritative‑price follow‑up.
- **Provisioning idempotency is latent, not live.** The
duplicate/orphan‑subscription window only becomes reachable once
card‑linking (follow‑up 2) makes provisioning actually run; hardening is
tracked as follow‑up 3.
- **One job can overshoot the spend cap via a near‑empty pool.** A
subscribed team that has hit its metered cap but still holds a
*nearly‑exhausted* pool is let through (the pool overrides the cap
gate); if a job needs more than the pool has left, the pool drains to
zero and the **remainder meters**, so that single job's remainder can
bill just past the "never past your spend limit" ceiling. Bounded to one
job's overshoot and only at the pool's tail; the alternative — blocking
the job — would strand paid‑for capacity, so this is a deliberate trade.

---

## Testing

- **Java** — `EntitlementServiceTest` (18) incl.
unsubscribed‑live‑pool‑stays‑FULL,
subscribed‑over‑cap‑with‑pool‑stays‑FULL, and lazy‑read guards.
- **Frontend** — `useBundleFlowState` + `Usage` render tests; portal &
SaaS `tsc`; i18n audit; `lint:colors`; toml‑sort; prettier.
- **SaaS webhook** (`v3`) — Deno tests for terminal‑vs‑transient
provisioning classification (rate‑limit treated as retryable),
credit‑error‑retries, and an end‑to‑end no‑storm assertion on the
unusable‑card path.

*Preview:* the checkout runs in a Supabase function in
`Stirling-PDF-SaaS` (`v3`); a live V2 preview is linked in the
auto‑deploy comment below. Screenshots to be refreshed — the checkout
modal changed since the originals.

Author: ConnorYoh

app/saas/src/main/java/stirling/software/saas/config/SaasJpaConfig.java

@@ -19,6 +19,7 @@
             "stirling.software.saas.billing.repository",
             "stirling.software.saas.ai.repository",
             "stirling.software.saas.payg.repository",
+            "stirling.software.saas.payg.bundle",
             "stirling.software.saas.procurement.repository"
         })
 @EntityScan({

app/saas/src/main/java/stirling/software/saas/payg/api/PaygWalletController.java

@@ -41,6 +41,7 @@
 import stirling.software.saas.payg.api.WalletSnapshotResponse.MemberRow;
 import stirling.software.saas.payg.billing.TeamBillingContext;
 import stirling.software.saas.payg.billing.TeamBillingService;
+import stirling.software.saas.payg.bundle.PrepaidBundleService;
 import stirling.software.saas.payg.entitlement.EntitlementService;
 import stirling.software.saas.payg.entitlement.EntitlementSnapshot;
 import stirling.software.saas.payg.model.BillingCategory;
@@ -86,6 +87,8 @@ public class PaygWalletController {
     static final String STATUS_SUBSCRIBED = "subscribed";
     static final String ROLE_LEADER = "leader";
     static final String ROLE_MEMBER = "member";
+    static final String BILLING_MODE_PREPAID = "prepaid";
+    static final String BILLING_MODE_PAYG = "payg";
 
     /**
      * Placeholder ceiling for the team-less empty snapshot only (authenticated caller without a
@@ -104,6 +107,7 @@ public class PaygWalletController {
     private final WalletLedgerRepository ledgerRepo;
     private final PaygShadowChargeRepository shadowRepo;
     private final UserRepository userRepository;
+    private final PrepaidBundleService prepaidBundleService;
 
     public PaygWalletController(
             EntitlementService entitlementService,
@@ -113,7 +117,8 @@ public PaygWalletController(
             WalletPolicyRepository policyRepo,
             WalletLedgerRepository ledgerRepo,
             PaygShadowChargeRepository shadowRepo,
-            UserRepository userRepository) {
+            UserRepository userRepository,
+            PrepaidBundleService prepaidBundleService) {
         this.entitlementService = Objects.requireNonNull(entitlementService, "entitlementService");
         this.billingService = Objects.requireNonNull(billingService, "billingService");
         this.memberRepo = Objects.requireNonNull(memberRepo, "memberRepo");
@@ -122,6 +127,8 @@ public PaygWalletController(
         this.ledgerRepo = Objects.requireNonNull(ledgerRepo, "ledgerRepo");
         this.shadowRepo = Objects.requireNonNull(shadowRepo, "shadowRepo");
         this.userRepository = Objects.requireNonNull(userRepository, "userRepository");
+        this.prepaidBundleService =
+                Objects.requireNonNull(prepaidBundleService, "prepaidBundleService");
     }
 
     // ---------------------------------------------------------------------------------------
@@ -187,6 +194,18 @@ public ResponseEntity<WalletSnapshotResponse> getWallet(Authentication auth) {
                         ? buildMemberRows(teamId, snap.periodStart(), snap.periodEnd())
                         : List.of();
 
+        // Prepaid bundles, aggregated across the team's in-term pools. Drawn ahead of the meter and
+        // kept out of the spend cap, so they're a separate dimension from the metered spend above.
+        PrepaidBundleService.PrepaidSummary prepaid = prepaidBundleService.summarize(teamId);
+        long prepaidRemaining = prepaid == null ? 0L : prepaid.unitsRemaining();
+        long prepaidTotal = prepaid == null ? 0L : prepaid.unitsTotal();
+        String prepaidExpiresAt =
+                prepaid == null || prepaid.expiresAt() == null
+                        ? null
+                        : ISO_DATE.format(prepaid.expiresAt().toLocalDate());
+        // Prepaid while pools still have units to draw; once exhausted the meter is live again.
+        String billingMode = prepaidRemaining > 0 ? BILLING_MODE_PREPAID : BILLING_MODE_PAYG;
+
         WalletSnapshotResponse body =
                 new WalletSnapshotResponse(
                         teamId,
@@ -211,7 +230,11 @@ public ResponseEntity<WalletSnapshotResponse> getWallet(Authentication auth) {
                         breakdowns.docs(),
                         analytics.docsProcessed(),
                         analytics.uniquePdfs(),
-                        analytics.sizeMultiplierPdfs());
+                        analytics.sizeMultiplierPdfs(),
+                        prepaidRemaining,
+                        prepaidTotal,
+                        prepaidExpiresAt,
+                        billingMode);
         return ResponseEntity.ok(body);
     }
 
@@ -485,6 +508,10 @@ private WalletSnapshotResponse emptySnapshot() {
                 new CategoryBreakdown(0, 0, 0),
                 0,
                 0,
-                0);
+                0,
+                0L,
+                0L,
+                null,
+                BILLING_MODE_PAYG);
     }
 }

app/saas/src/main/java/stirling/software/saas/payg/api/WalletSnapshotResponse.java

@@ -79,7 +79,20 @@ public record WalletSnapshotResponse(
         CategoryBreakdown categoryDocs,
         int docsProcessedThisPeriod,
         int uniquePdfsThisPeriod,
-        int sizeMultiplierPdfsThisPeriod) {
+        int sizeMultiplierPdfsThisPeriod,
+        long prepaidUnitsRemaining,
+        long prepaidUnitsTotal,
+        String prepaidExpiresAt,
+        String billingMode) {
+
+    // Prepaid usage bundles, aggregated across the team's in-term pools (drawn ahead of the meter,
+    // outside the spend cap):
+    //   prepaidUnitsRemaining — Σ units left across active pools (0 when exhausted / none)
+    //   prepaidUnitsTotal     — Σ capacity of in-term pools (the "X of Y used" denominator; 0 = no
+    //                           bundle this term, so the FE hides the prepaid card)
+    //   prepaidExpiresAt      — soonest term end (ISO date) for the countdown; null when no bundle
+    //   billingMode           — "prepaid" while prepaid units remain, else "payg" (the meter is
+    // live)
 
     // The count dimension, kept distinct from units (which now scale with file size):
     //   categoryDocs                — per-category INPUT-file counts (parallel to

app/saas/src/main/java/stirling/software/saas/payg/bundle/PrepaidBundle.java

@@ -0,0 +1,105 @@
+package stirling.software.saas.payg.bundle;
+
+import java.io.Serializable;
+import java.time.LocalDateTime;
+
+import org.hibernate.annotations.CreationTimestamp;
+
+import jakarta.persistence.Column;
+import jakarta.persistence.Entity;
+import jakarta.persistence.GeneratedValue;
+import jakarta.persistence.GenerationType;
+import jakarta.persistence.Id;
+import jakarta.persistence.Index;
+import jakarta.persistence.Table;
+
+import lombok.Getter;
+import lombok.NoArgsConstructor;
+import lombok.Setter;
+
+/**
+ * A prepaid, expiring pool of PDF-process units bought up-front at a discount ("12 months for the
+ * price of 10"). Consumed after the team's free grant and before the meter (free -> prepaid ->
+ * metered); draws are booked to the {@code BOUGHT} ledger bucket, so a bundle never counts toward
+ * the spend cap or the Stripe meter.
+ *
+ * <p>Carries only capacity + term + the Stripe link. The one-time amount and currency live on the
+ * Stripe Checkout Session / PaymentIntent referenced by {@link #stripeRef}; how many units a PDF
+ * costs comes from the team's pricing policy at charge time, not from the bundle. Status is
+ * derived, never stored (see {@link #isDrawable}).
+ *
+ * <p>A team may hold several pools at once (top-ups); they are drawn FIFO by soonest {@link
+ * #expiresAt}. Unused units forfeit at expiry (no roll-over).
+ */
+@Entity
+@Table(
+        name = "payg_prepaid_bundle",
+        // Declared here for ddl-auto (fresh schemas) and to document intent. The authoritative creator
+        // in production is the Supabase CLI migration 20260720000000_payg_prepaid_bundle, which builds
+        // the partial forms (WHERE units_remaining > 0 / WHERE stripe_ref IS NOT NULL). Flyway was
+        // retired for SaaS (#7100), so there is no migration twin — names match the CLI migration.
+        indexes = {
+            // Hot-path FIFO draw lookup — findDrawableForUpdate runs a locked read on every billable
+            // charge past the free grant; without it that degrades to a locked scan as the table grows.
+            @Index(
+                    name = "idx_payg_prepaid_bundle_team_expiry",
+                    columnList = "team_id, expires_at"),
+            // One pool per Stripe payment — the idempotency guard so a redelivered invoice.paid can't
+            // credit the same purchase twice.
+            @Index(
+                    name = "uq_payg_prepaid_bundle_stripe_ref",
+                    columnList = "stripe_ref",
+                    unique = true),
+        })
+@NoArgsConstructor
+@Getter
+@Setter
+public class PrepaidBundle implements Serializable {
+
+    private static final long serialVersionUID = 1L;
+
+    @Id
+    @GeneratedValue(strategy = GenerationType.IDENTITY)
+    @Column(name = "bundle_id")
+    private Long id;
+
+    @Column(name = "team_id", nullable = false)
+    private Long teamId;
+
+    /** Capacity granted at purchase — the denominator of the "X of Y used" meter. */
+    @Column(name = "units_total", nullable = false)
+    private long unitsTotal;
+
+    /** Live balance; pessimistic-locked on draw. */
+    @Column(name = "units_remaining", nullable = false)
+    private long unitsRemaining;
+
+    @Column(name = "purchased_at", nullable = false)
+    private LocalDateTime purchasedAt;
+
+    /** {@code purchasedAt + 12 months}. Unused units forfeit after this instant. */
+    @Column(name = "expires_at", nullable = false)
+    private LocalDateTime expiresAt;
+
+    /**
+     * Stripe Checkout Session / PaymentIntent id for the one-time payment that created this pool.
+     * The amount + currency + receipt live on that object; a unique index makes the webhook credit
+     * idempotent. {@code null} only for pools seeded outside the purchase flow (tests/backfill).
+     */
+    @Column(name = "stripe_ref", length = 128)
+    private String stripeRef;
+
+    @CreationTimestamp
+    @Column(name = "created_at", nullable = false, updatable = false)
+    private LocalDateTime createdAt;
+
+    /** In-term (not yet expired) as of {@code now} — regardless of remaining balance. */
+    public boolean isInTerm(LocalDateTime now) {
+        return expiresAt.isAfter(now);
+    }
+
+    /** Has units left AND is still in term — i.e. a charge may draw from it. */
+    public boolean isDrawable(LocalDateTime now) {
+        return unitsRemaining > 0 && isInTerm(now);
+    }
+}

app/saas/src/main/java/stirling/software/saas/payg/bundle/PrepaidBundleRepository.java

@@ -0,0 +1,55 @@
+package stirling.software.saas.payg.bundle;
+
+import java.time.LocalDateTime;
+import java.util.List;
+
+import org.springframework.data.jpa.repository.JpaRepository;
+import org.springframework.data.jpa.repository.Lock;
+import org.springframework.data.jpa.repository.Query;
+import org.springframework.data.repository.query.Param;
+import org.springframework.stereotype.Repository;
+
+import jakarta.persistence.LockModeType;
+
+@Repository
+public interface PrepaidBundleRepository extends JpaRepository<PrepaidBundle, Long> {
+
+    /**
+     * A team's still-drawable pools (units left, not expired), soonest-expiring first, locked for
+     * the draw transaction. Mirrors {@code PaygTeamExtensionsRepository.findByIdForUpdate}: the
+     * PESSIMISTIC_WRITE lock serialises concurrent charges for the same team so two jobs can't both
+     * draw the same remaining unit, keeping the per-job {@code bundle_units_consumed} split exact.
+     * Drawn FIFO — the caller depletes the earliest-expiring pool first so capacity is used before
+     * it lapses. Filters on {@code expires_at} so an expired pool is never drawn even if the expiry
+     * sweep hasn't run (lazy expiry).
+     */
+    @Lock(LockModeType.PESSIMISTIC_WRITE)
+    @Query(
+            "SELECT b FROM PrepaidBundle b WHERE b.teamId = :teamId AND b.unitsRemaining > 0"
+                    + " AND b.expiresAt > :now ORDER BY b.expiresAt ASC")
+    List<PrepaidBundle> findDrawableForUpdate(
+            @Param("teamId") Long teamId, @Param("now") LocalDateTime now);
+
+    /**
+     * A team's in-term pools (not yet expired), soonest-expiring first — read-only, for the wallet
+     * snapshot. Includes exhausted-but-in-term pools so the "X of Y used" meter keeps the right
+     * denominator for the current term. Small per team; the service aggregates in Java.
+     */
+    @Query(
+            "SELECT b FROM PrepaidBundle b WHERE b.teamId = :teamId AND b.expiresAt > :now"
+                    + " ORDER BY b.expiresAt ASC")
+    List<PrepaidBundle> findInTerm(@Param("teamId") Long teamId, @Param("now") LocalDateTime now);
+
+    /**
+     * A team's in-term pools (not yet expired), soonest-expiring first, locked — for the refund
+     * restore path. Unlike {@link #findDrawableForUpdate} this includes pools already drawn to zero
+     * (that's exactly where a just-drawn charge's units go back), capped at {@code units_total} by
+     * the caller.
+     */
+    @Lock(LockModeType.PESSIMISTIC_WRITE)
+    @Query(
+            "SELECT b FROM PrepaidBundle b WHERE b.teamId = :teamId AND b.expiresAt > :now"
+                    + " ORDER BY b.expiresAt ASC")
+    List<PrepaidBundle> findInTermForUpdate(
+            @Param("teamId") Long teamId, @Param("now") LocalDateTime now);
+}