@blamejs/blamejs-shop 0.4.20 → 0.4.21

package/lib/subscription-controls.js

@@ -242,6 +242,77 @@ function create(opts) {
   if (!subscriptionsHandle || typeof subscriptionsHandle.get !== "function") {
     throw new TypeError("subscriptionControls.create: opts.subscriptions handle required");
   }
+  // Optional payment handle (the shared Stripe adapter). When wired,
+  // quantity changes on a Stripe-backed subscription are pushed to
+  // Stripe BEFORE the local row is touched, so the row the shop shows
+  // and the quantity Stripe actually bills never diverge. Without it
+  // (a deploy with no payment processor, or a non-Stripe row), the
+  // controls stay local-only. The handle must expose
+  // `subscriptions.retrieve(id)` + `subscriptions.update(id, body)`.
+  var payment = opts.payment || null;
+  var hasStripe = !!(payment && payment.subscriptions &&
+    typeof payment.subscriptions.update === "function" &&
+    typeof payment.subscriptions.retrieve === "function");
+
+  // A row is Stripe-backed when the processor adapter is wired AND the
+  // row carries the upstream subscription id the webhook + billing
+  // mirror key on. Rows without one are shop-local (e.g. a manually
+  // seeded subscription on a deploy that never reached Stripe) and the
+  // controls mutate only local columns for them.
+  function _isStripeBacked(row) {
+    return hasStripe && row && typeof row.stripe_subscription_id === "string" && row.stripe_subscription_id.length > 0;
+  }
+
+  // Push a new line quantity to Stripe for a Stripe-backed subscription.
+  // Stripe models quantity on the subscription ITEM, not the
+  // subscription, so we retrieve the live subscription to find its
+  // (single) item id, then update that item's quantity. Every
+  // subscription this shop creates binds exactly one price
+  // (`items: [{ price }]`), so the first item is authoritative; if a
+  // subscription somehow carries no item we surface a structured error
+  // rather than silently writing a local-only change that diverges from
+  // Stripe. The idempotency key folds in the subscription id + target
+  // quantity so a retried call is a safe no-op at Stripe.
+  async function _pushQuantityToStripe(stripeSubscriptionId, newQuantity) {
+    var live;
+    try {
+      live = await payment.subscriptions.retrieve(stripeSubscriptionId);
+    } catch (e) {
+      var rErr = new Error(
+        "subscriptionControls.changeQuantity: could not reach Stripe to update the subscription — " + (e && e.message || e),
+      );
+      rErr.code = "SUBSCRIPTION_STRIPE_PUSH_FAILED";
+      rErr.cause = e;
+      throw rErr;
+    }
+    var items = live && live.items && Array.isArray(live.items.data) ? live.items.data : [];
+    if (!items.length || !items[0] || !items[0].id) {
+      var noItem = new Error(
+        "subscriptionControls.changeQuantity: Stripe subscription " + stripeSubscriptionId + " has no billable item to update",
+      );
+      noItem.code = "SUBSCRIPTION_STRIPE_NO_ITEM";
+      throw noItem;
+    }
+    var idemKey = "subctl:qty:" + stripeSubscriptionId + ":" + newQuantity;
+    try {
+      return await payment.subscriptions.update(
+        stripeSubscriptionId,
+        { items: [{ id: items[0].id, quantity: newQuantity }] },
+        idemKey,
+      );
+    } catch (e2) {
+      // The processor rejected or failed the quantity update. Wrap it in
+      // a stable code so the route can surface a "nothing changed, retry"
+      // notice; the local row is still untouched (this runs before the
+      // local write).
+      var uErr = new Error(
+        "subscriptionControls.changeQuantity: Stripe rejected the quantity update — " + (e2 && e2.message || e2),
+      );
+      uErr.code = "SUBSCRIPTION_STRIPE_PUSH_FAILED";
+      uErr.cause = e2;
+      throw uErr;
+    }
+  }
 
   // Fetch the raw subscription row + bound plan in one round-trip,
   // returning `null` if either is absent. The plan lookup feeds the
@@ -317,6 +388,14 @@ function create(opts) {
     MAX_SKIP_COUNT:     MAX_SKIP_COUNT,
     MAX_QUANTITY:       MAX_QUANTITY,
     REACTIVATE_GRACE_MS: REACTIVATE_GRACE_MS,
+    // True when this instance can push changes to Stripe (a payment
+    // handle with retrieve + update was wired). Callers use it to decide
+    // whether a row with a stripe_subscription_id is genuinely Stripe-
+    // backed — a frequency change is refused (immutable interval) and a
+    // quantity change round-trips Stripe. Without it, the controls are
+    // local-only even for a Stripe-shaped row, so the storefront keeps
+    // offering the frequency control.
+    stripeBacked:       hasStripe,
 
     pause: async function (input) {
       if (!input || typeof input !== "object") {
@@ -462,6 +541,18 @@ function create(opts) {
         throw cErr;
       }
 
+      // Stripe-backed: push the new quantity to Stripe BEFORE the local
+      // write. If the processor rejects the update, we throw and leave
+      // the local row untouched — the customer sees an honest error and
+      // the shop's `quantity` column never diverges from what Stripe
+      // actually bills (the divergence this control surface previously
+      // produced, writing a local "Quantity updated." while Stripe kept
+      // charging the old quantity). The local write only lands after the
+      // Stripe update succeeds.
+      if (_isStripeBacked(row)) {
+        await _pushQuantityToStripe(row.stripe_subscription_id, newQuantity);
+      }
+
       var before = _snapshot(row);
       var ts = _now();
       await query(
@@ -495,6 +586,28 @@ function create(opts) {
         throw cErr;
       }
 
+      // Stripe-backed: refuse. A Stripe Price's `recurring.interval` is
+      // IMMUTABLE — you cannot re-cadence an existing price, only swap
+      // the subscription item to a DIFFERENT price with the desired
+      // interval. This shop binds each subscription to a single
+      // `stripe_price_id` from its plan and carries no catalog of
+      // per-frequency prices to swap between, so the billing interval
+      // simply isn't expressible here. Writing the local `frequency`
+      // column anyway would tell the customer "Delivery frequency
+      // updated" while Stripe kept invoicing on the original cadence —
+      // exactly the divergence this surface must not create. Refuse with
+      // honest copy; the customer cancels + re-subscribes on a plan with
+      // the cadence they want. (A non-Stripe row falls through to the
+      // local-only recompute below — the shop's own cadence view.)
+      if (_isStripeBacked(row)) {
+        var fErr = new Error(
+          "subscriptionControls.changeFrequency: delivery frequency can't be changed on this subscription — " +
+          "cancel and start a new subscription on a plan with the cadence you want",
+        );
+        fErr.code = "SUBSCRIPTION_FREQUENCY_IMMUTABLE";
+        throw fErr;
+      }
+
       // next_billing_at is recomputed off the row's current cycle
       // anchor — `current_period_start` (Stripe-mirrored) if present,
       // otherwise the current next_billing_at, otherwise now. One

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/blamejs-shop",
-  "version": "0.4.20",
+  "version": "0.4.21",
   "description": "Open-source framework built on blamejs. Vendored stack, zero npm runtime deps, PQC-first crypto, security-on by default.",
   "main": "lib/index.js",
   "scripts": {