@blamejs/blamejs-shop 0.4.39 → 0.4.41

package/CHANGELOG.md

@@ -8,6 +8,10 @@ upgrading across more than a few patches at a time.
 
 ## v0.4.x
 
+- v0.4.41 (2026-06-13) — **Subscription billing no longer double-charges on a retried period close or a concurrent immediate plan change.** Two billing paths could invoice the same charge twice. A metered-usage period close is cron-driven and at-least-once, but it enqueued its roll-up invoice with no idempotency key, so a retried tick — a transient error mid-run, an at-least-once redelivery, or an operator re-running the close — wrote a second invoice for the same period and billed the customer twice. And an immediate plan change recorded its proration adjustment after a guard that only blocked a queued (pending) change, so two concurrent immediate executions both transitioned the subscription and both recorded the proration. The period close now stamps a deterministic per-period idempotency key so a replay returns the existing invoice, and the immediate plan change now transitions the subscription with a conditional update so only the one call that actually moves the plan records the proration. No migration to apply. **Fixed:** *A retried metered-usage period close no longer bills the period twice* — Rolling a usage period into an invoice now carries a deterministic idempotency key derived from the subscription, period window, and currency. A period close that runs more than once — a cron retry, an at-least-once redelivery, or a manual re-run — now returns the invoice already recorded for that period instead of enqueuing a duplicate, so the customer is billed for the period exactly once. · *Concurrent immediate plan changes charge proration once* — Executing an immediate plan change now transitions the subscription with a conditional update keyed on the current plan, and records the proration adjustment only when that update actually moves the plan. The prior guard only refused a queued change, so two immediate executions racing the same change — a double-submit or a retry — could both apply the transition and both record the proration. Now only the one call that wins the transition charges it.
+
+- v0.4.40 (2026-06-13) — **A payment webhook whose first delivery fails is reprocessed on redelivery instead of dropping the refund or capture.** The Stripe and PayPal webhook handlers claim an event id for replay suppression the moment the signature verifies — before processing — so a duplicate delivery can never apply a refund or a state change twice. But the claim was kept even when processing then FAILED: a transient database error, a garbled or unparseable refund amount, or an illegal state transition would make the handler return a 5xx so the provider redelivered — and the redelivery found the already-claimed id and was dropped as a replay, permanently losing the refund or the capture-to-paid transition. The claim is now released whenever processing throws, so the provider's redelivery (carrying a recovered payload, or arriving once a transient blip clears) is reprocessed and the refund or capture finally lands. A delivery that SUCCEEDS still keeps its claim, so genuine duplicate deliveries remain suppressed and a refund is never applied twice. No migration to apply. **Fixed:** *Webhook redelivery recovers a refund or capture a failed first delivery would have lost* — Replay suppression on the Stripe and PayPal webhook handlers now reserves the event id, commits the claim only when processing succeeds, and releases it when processing throws. Previously the id was claimed eagerly and kept regardless of outcome, so any first delivery that failed downstream — a transient store error, a refund amount that couldn't be parsed, an out-of-order event that hit an illegal transition — turned the provider's at-least-once redelivery into a silently dropped replay, and the refund or the move to paid never reached the order ledger. The provider's redelivery is now reprocessed, while a delivery that already succeeded still suppresses true duplicates so a refund is never double-applied.
+
 - v0.4.39 (2026-06-13) — **Account erasure severs sign-in first and no longer strands a half-erased account when one data domain fails.** Hardening the right-to-erasure flow, which fans a deletion out across every customer-keyed table. Two gaps are closed. The sign-in revocation — passkeys, OAuth links, the email-hash lookup key, and live portal sessions — ran last in the fan-out, so a failure partway through left the supposedly-erased account still able to authenticate. And any single domain handler that threw aborted the entire erasure, leaving every remaining domain untouched with no record of what failed. Now the access-cut runs first, so the account can no longer sign in even if a later step fails; each domain is isolated, so one failure no longer strands the rest; the run reports which domains failed and stays open for retry instead of reporting completion; and re-running converges once the transient clears, since every domain handler is idempotent. No migration to apply. **Fixed:** *Erasure cuts off account sign-in before deleting data* — An erasure request now revokes every sign-in path — passkeys, OAuth identities, the email-hash lookup key, and live portal sessions — as the first step of the fan-out, ahead of the per-table deletions. Previously this revocation ran last, so an erasure that failed partway through left the account's credentials intact and the customer still able to sign in to the anonymized profile. Severing access is erasure's first obligation; data removal follows. · *A single failing domain no longer aborts the whole erasure* — Each customer-keyed domain is now deleted in isolation: a handler that throws is recorded as a failure and the erasure continues to the remaining domains, instead of aborting and stranding everything after it half-erased. The request is marked fulfilled only when every domain succeeds — a partial run stays open and reports exactly which domains failed, so re-running retries just the failures and converges to a clean, complete erasure. The erasure console reflects an incomplete run as needing a re-run rather than reporting success, and every domain handler is idempotent, so the retry removes nothing twice.
 
 - v0.4.38 (2026-06-14) — **Close two refund-path money-creation defects: loyalty restoration over-minting across refund passes, and a double-submitted partial refund phantom-crediting gift card and loyalty.** Two confirmed money-creation bugs in the refund path, both surfaced by an adversarial review of the recent cash-first refund accounting. First, restoring redeemed loyalty points could mint more than the customer spent when an order was refunded across more than one pass (a partial slice then the terminal refund): the restore scan re-read the positive reversal rows it writes as if they were fresh redemptions and credited them again, compounding past the original spend. Second, a console partial-refund double-submit — a double-click, a retry, or a refund webhook arriving after a console refund — appended the refund ledger twice under the same payment-provider refund id; the provider moved the money once, but the duplicate ledger row double-counted the refunded total, which drove the cash-first accounting to re-credit gift-card and loyalty value the customer was never actually refunded. Both are fixed and covered by regression tests. No migration to apply. **Fixed:** *Loyalty restoration no longer over-mints across multiple refund passes* — When a refund runs in more than one pass — a partial cash refund followed by a terminal full refund — restoring redeemed points scanned every loyalty row tied to the order, including the positive reversal rows the restore itself writes (which share the same transaction type as a redemption). A later pass re-read a prior pass's reversal as a fresh redemption and credited it again, so the restored points exceeded the original spend. The scan now reads only the genuine burns, so the cumulative restored points converge exactly on the redeemed amount regardless of how many passes run. · *A double-submitted partial refund no longer phantom-credits gift card and loyalty* — Recording a partial refund now dedupes on the payment-provider refund id in a single conditional write, so the existence check and the ledger append are one atomic statement — two concurrent submits of the same refund (a double-click, a retry, or a refund webhook racing the console) can no longer both record. The Stripe refund webhook now stamps that same refund id alongside the cash share it mirrors, so a refund the webhook records before the console write is recognized and the console write becomes a no-op. Previously a duplicate row double-counted the order's refunded total, which on a split-tender order pushed the cumulative past the cash captured and re-credited the full gift-card and loyalty value the customer was never refunded.

package/lib/asset-manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.4.39",
+  "version": "0.4.41",
   "assets": {
     "css/admin.css": {
       "integrity": "sha384-imfe0otYErcB8rr2h6KLSGTtStirysptpXETSPY4zLv3bZoIT75Lo1dOvkOav+xL",

package/lib/checkout.js

@@ -312,6 +312,23 @@ function create(deps) {
     return _stripeReplayStore;
   }
 
+  // Release a claimed webhook event id (Stripe id, or the "paypal:"-namespaced
+  // id) so the provider's redelivery is reprocessed instead of dropped as a
+  // replay. The claim is taken eagerly — before processing — to win the
+  // concurrency race; but if processing then THROWS, the route returns 5xx and
+  // the provider redelivers, and the eager claim would suppress that
+  // redelivery as a replay, permanently losing the refund or capture. Releasing
+  // the id on a processing failure restores the at-least-once contract.
+  // Best-effort: a failed release leaves the claim in place (the redelivery is
+  // suppressed) but must never mask the original processing error. No-op when
+  // the store isn't wired.
+  async function _replayRelease(eventId) {
+    if (!webhookReplayQuery || typeof eventId !== "string" || !eventId.length) return;
+    try {
+      await webhookReplayQuery("DELETE FROM stripe_webhook_events WHERE event_id = ?1", [eventId]);
+    } catch (_e) { /* drop-silent — by design: see above */ }
+  }
+
   // Has a provider refund with this id already been mirrored into the
   // order's ledger? Scans the hydrated transition rows for a `refund` row
   // whose metadata carries the same provider refund id. This is what makes
@@ -1642,70 +1659,77 @@ function create(deps) {
       // not-fresh) — a replay is indistinguishable from a wiped store, so
       // refusing is the safe default. No-op when the store isn't wired.
       var replay = _stripeReplay();
+      var _claimedId = null;
       if (replay && event && typeof event.id === "string" && event.id.length > 0) {
         var fresh = await replay.checkAndInsert(event.id, Date.now() + STRIPE_REPLAY_TTL_MS);
         if (!fresh) {
           return { handled: true, event_type: eventType || null, skipped: "replay", event_id: event.id };
         }
+        // Claimed for this attempt. If the dispatch below THROWS, the claim is
+        // released (see catch) so the provider's redelivery is reprocessed
+        // rather than dropped as a replay — a normal return keeps the claim.
+        _claimedId = event.id;
       }
 
-      // Subscription events route to the subscriptions primitive
-      // (if wired). The one-time-order PaymentIntent path below
-      // stays unchanged.
-      if (eventType && Object.prototype.hasOwnProperty.call(STRIPE_SUB_EVENT_TYPES, eventType)) {
-        if (!subscriptions) {
-          return { handled: false, event_type: eventType, reason: "no-subscriptions-handler" };
+      try {
+        // Subscription events route to the subscriptions primitive
+        // (if wired). The one-time-order PaymentIntent path below
+        // stays unchanged.
+        if (eventType && Object.prototype.hasOwnProperty.call(STRIPE_SUB_EVENT_TYPES, eventType)) {
+          if (!subscriptions) {
+            return { handled: false, event_type: eventType, reason: "no-subscriptions-handler" };
+          }
+          return await subscriptions.handleStripeEvent(event);
         }
-        return await subscriptions.handleStripeEvent(event);
-      }
 
-      if (!eventType || !Object.prototype.hasOwnProperty.call(STRIPE_EVENT_MAP, eventType)) {
-        return { handled: false, event_type: eventType || null };
-      }
-      var fsmEvent = STRIPE_EVENT_MAP[eventType];
-      if (!fsmEvent) return { handled: false, event_type: eventType, reason: "no-state-change" };
-
-      // Extract payment_intent id from the event.
-      var pi = null;
-      if (event.data && event.data.object) {
-        var obj = event.data.object;
-        pi = obj.payment_intent || obj.id;
-      }
-      if (!pi) return { handled: false, event_type: eventType, reason: "no-payment-intent" };
+        if (!eventType || !Object.prototype.hasOwnProperty.call(STRIPE_EVENT_MAP, eventType)) {
+          return { handled: false, event_type: eventType || null };
+        }
+        var fsmEvent = STRIPE_EVENT_MAP[eventType];
+        if (!fsmEvent) return { handled: false, event_type: eventType, reason: "no-state-change" };
+
+        // Extract payment_intent id from the event.
+        var pi = null;
+        if (event.data && event.data.object) {
+          var obj = event.data.object;
+          pi = obj.payment_intent || obj.id;
+        }
+        if (!pi) return { handled: false, event_type: eventType, reason: "no-payment-intent" };
 
-      var o = await order.byPaymentIntent(pi);
-      if (!o) return { handled: false, event_type: eventType, reason: "order-not-found" };
+        var o = await order.byPaymentIntent(pi);
+        if (!o) return { handled: false, event_type: eventType, reason: "order-not-found" };
 
-      // Refund events are AMOUNT-AWARE — a partial dashboard refund must
-      // append a partial ledger row, never drive the terminal refund edge
-      // (which re-credits every gift-card/loyalty credit on the order).
-      if (eventType === "charge.refunded") {
-        return await _mirrorStripeRefund(o, event);
-      }
+        // Refund events are AMOUNT-AWARE — a partial dashboard refund must
+        // append a partial ledger row, never drive the terminal refund edge
+        // (which re-credits every gift-card/loyalty credit on the order).
+        if (eventType === "charge.refunded") {
+          return await _mirrorStripeRefund(o, event);
+        }
 
-      // Idempotency: if the order is already in a state the event
-      // would advance to, skip the transition (re-deliveries from
-      // Stripe are common).
-      var alreadyAdvanced = (
-        (fsmEvent === "mark_paid"  && o.status !== "pending") ||
-        (fsmEvent === "cancel"     && o.status === "cancelled") ||
-        (fsmEvent === "refund"     && o.status === "refunded")
-      );
-      if (alreadyAdvanced) {
-        return { handled: true, event_type: eventType, order: o, skipped: "already-advanced" };
-      }
+        // Idempotency: if the order is already in a state the event
+        // would advance to, skip the transition (re-deliveries from
+        // Stripe are common).
+        var alreadyAdvanced = (
+          (fsmEvent === "mark_paid"  && o.status !== "pending") ||
+          (fsmEvent === "cancel"     && o.status === "cancelled") ||
+          (fsmEvent === "refund"     && o.status === "refunded")
+        );
+        if (alreadyAdvanced) {
+          return { handled: true, event_type: eventType, order: o, skipped: "already-advanced" };
+        }
 
-      var updated;
-      try {
-        updated = await order.transition(o.id, fsmEvent, {
+        var updated = await order.transition(o.id, fsmEvent, {
           reason: "stripe:" + eventType,
           metadata: { stripe_event_id: event.id },
         });
+        return { handled: true, event_type: eventType, order: updated };
       } catch (e) {
-        // Illegal transition — bubble up.
+        // Processing failed after the eager claim — release the id so the
+        // provider's redelivery (driven by the 5xx this throw becomes)
+        // reprocesses the event instead of being suppressed as a replay.
+        if (_claimedId) await _replayRelease(_claimedId);
         throw e;
       }
-      return { handled: true, event_type: eventType, order: updated };
     },
 
     // ---- PayPal (Orders v2) ----------------------------------------------
@@ -1958,51 +1982,62 @@ function create(deps) {
       // the store isn't wired (the refund-id dedupe in the mirror still
       // covers sequential re-delivery).
       var replay = _stripeReplay();
+      var _claimedId = null;
       if (replay && typeof event.id === "string" && event.id.length > 0) {
         var fresh = await replay.checkAndInsert("paypal:" + event.id, Date.now() + PAYPAL_REPLAY_TTL_MS);
         if (!fresh) {
           return { handled: true, event_type: eventType, skipped: "replay", event_id: event.id };
         }
+        // Claimed for this attempt (namespaced). A throw below releases it so
+        // the redelivery reprocesses; a normal return keeps the claim.
+        _claimedId = "paypal:" + event.id;
       }
 
-      var fsmEvent = PAYPAL_EVENT_MAP[eventType];
-      if (!fsmEvent) return { handled: false, event_type: eventType, reason: "no-state-change" };
-      // The PayPal order id lives in the capture resource's related ids.
-      var ppOrderId = null;
-      try { ppOrderId = event.resource.supplementary_data.related_ids.order_id; } catch (_e) { ppOrderId = null; }
-      if (!ppOrderId) return { handled: false, event_type: eventType, reason: "no-order-id" };
-      var o = await order.byPaymentIntent(ppOrderId);
-      if (!o) return { handled: false, event_type: eventType, reason: "order-not-found" };
-
-      // Refund events are AMOUNT-AWARE — see _mirrorPaypalRefund: a partial
-      // dashboard refund appends a partial ledger row; only a
-      // balance-clearing slice drives the terminal refund edge.
-      if (eventType === "PAYMENT.CAPTURE.REFUNDED") {
-        return await _mirrorPaypalRefund(o, event, ppOrderId);
-      }
+      try {
+        var fsmEvent = PAYPAL_EVENT_MAP[eventType];
+        if (!fsmEvent) return { handled: false, event_type: eventType, reason: "no-state-change" };
+        // The PayPal order id lives in the capture resource's related ids.
+        var ppOrderId = null;
+        try { ppOrderId = event.resource.supplementary_data.related_ids.order_id; } catch (_e) { ppOrderId = null; }
+        if (!ppOrderId) return { handled: false, event_type: eventType, reason: "no-order-id" };
+        var o = await order.byPaymentIntent(ppOrderId);
+        if (!o) return { handled: false, event_type: eventType, reason: "order-not-found" };
+
+        // Refund events are AMOUNT-AWARE — see _mirrorPaypalRefund: a partial
+        // dashboard refund appends a partial ledger row; only a
+        // balance-clearing slice drives the terminal refund edge.
+        if (eventType === "PAYMENT.CAPTURE.REFUNDED") {
+          return await _mirrorPaypalRefund(o, event, ppOrderId);
+        }
 
-      if (fsmEvent === "mark_paid" && o.status !== "pending") {
-        return { handled: true, event_type: eventType, order: o, skipped: "already-advanced" };
-      }
-      // The COMPLETED resource is the capture itself — persist its id so
-      // refunds can run against the capture without re-dialing PayPal. The
-      // write is best-effort here (the metadata stamp below remains the
-      // recoverable source): a refused write must never block settling a
-      // real payment.
-      var ppCaptureId = (eventType === "PAYMENT.CAPTURE.COMPLETED" && event.resource &&
-                         typeof event.resource.id === "string" && event.resource.id.length)
-        ? event.resource.id : null;
-      if (ppCaptureId) {
-        try { await order.setPaypalCapture(o.id, ppCaptureId); }
-        catch (_e) { /* drop-silent — by design: capture-id persistence must not block mark_paid; the transition metadata keeps it recoverable */ }
+        if (fsmEvent === "mark_paid" && o.status !== "pending") {
+          return { handled: true, event_type: eventType, order: o, skipped: "already-advanced" };
+        }
+        // The COMPLETED resource is the capture itself — persist its id so
+        // refunds can run against the capture without re-dialing PayPal. The
+        // write is best-effort here (the metadata stamp below remains the
+        // recoverable source): a refused write must never block settling a
+        // real payment.
+        var ppCaptureId = (eventType === "PAYMENT.CAPTURE.COMPLETED" && event.resource &&
+                           typeof event.resource.id === "string" && event.resource.id.length)
+          ? event.resource.id : null;
+        if (ppCaptureId) {
+          try { await order.setPaypalCapture(o.id, ppCaptureId); }
+          catch (_e) { /* drop-silent — by design: capture-id persistence must not block mark_paid; the transition metadata keeps it recoverable */ }
+        }
+        var updated = await order.transition(o.id, fsmEvent, {
+          reason:   "paypal:" + eventType,
+          metadata: ppCaptureId
+            ? { paypal_event_id: event.id, paypal_order_id: ppOrderId, paypal_capture_id: ppCaptureId }
+            : { paypal_event_id: event.id, paypal_order_id: ppOrderId },
+        });
+        return { handled: true, event_type: eventType, order: updated };
+      } catch (e) {
+        // Processing failed after the eager claim — release the namespaced id
+        // so the provider's redelivery reprocesses instead of being dropped.
+        if (_claimedId) await _replayRelease(_claimedId);
+        throw e;
       }
-      var updated = await order.transition(o.id, fsmEvent, {
-        reason:   "paypal:" + eventType,
-        metadata: ppCaptureId
-          ? { paypal_event_id: event.id, paypal_order_id: ppOrderId, paypal_capture_id: ppCaptureId }
-          : { paypal_event_id: event.id, paypal_order_id: ppOrderId },
-      });
-      return { handled: true, event_type: eventType, order: updated };
     },
   };
 }

package/lib/metered-usage.js

@@ -624,12 +624,20 @@ function create(opts) {
       // Skip zero-charge currencies — a period that consumed only
       // included-floor units shouldn't enqueue a $0 invoice line.
       if (amountMinor <= 0) continue;
+      // Idempotency key. A period close is cron-driven and at-least-once: a
+      // tick that retries (transient error mid-run, redelivery, or an operator
+      // re-running the close) MUST NOT enqueue a second invoice for the same
+      // [period_start, period_end, currency] — that double-bills the customer.
+      // recordInvoice dedupes on processor_invoice_id, so stamp a deterministic
+      // id derived from the period identity; a re-run returns the existing row.
+      var dedupeId = "metered:" + subscriptionId + ":" + periodStart + ":" + periodEnd + ":" + currency;
       var invoice = await billingHandle.recordInvoice({
-        subscription_id: subscriptionId,
-        period_start:    periodStart,
-        period_end:      periodEnd,
-        amount_minor:    amountMinor,
-        currency:        currency,
+        subscription_id:     subscriptionId,
+        period_start:        periodStart,
+        period_end:          periodEnd,
+        amount_minor:        amountMinor,
+        currency:            currency,
+        processor_invoice_id: dedupeId,
       });
       invoices.push(invoice);
     }

package/lib/plan-changes.js

@@ -348,11 +348,20 @@ function create(opts) {
       );
 
       if (status === "executed") {
-        await query(
-          "UPDATE subscriptions SET plan_id = ?1, updated_at = ?2 WHERE id = ?3",
-          [newPlanId, ts, subscriptionId],
+        // Atomic transition claim. The plan update is conditional on the
+        // CURRENT plan id, so two concurrent executeChange calls for the same
+        // immediate change can't both apply it — only the call that observes
+        // the pre-change plan id transitions the row (rowCount 1); a racing
+        // second call sees rowCount 0. The _pendingFor guard above only blocks
+        // PENDING changes, so without this an immediate change executed twice
+        // (a double-submit or retry) would record the proration invoice twice
+        // and double-charge. The proration below is gated on winning the claim.
+        var planUpd = await query(
+          "UPDATE subscriptions SET plan_id = ?1, updated_at = ?2 WHERE id = ?3 AND plan_id = ?4",
+          [newPlanId, ts, subscriptionId, sub.plan_id],
         );
-        if (billingHandle && typeof billingHandle.recordInvoice === "function") {
+        var wonTransition = Number((planUpd && planUpd.rowCount) || 0) > 0;
+        if (wonTransition && billingHandle && typeof billingHandle.recordInvoice === "function") {
           // Queue the proration adjustment as a single invoice row.
           // The amount is the net (first_charge - credit); negative
           // nets clamp to zero (the credit covers the partial-period

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/blamejs-shop",
-  "version": "0.4.39",
+  "version": "0.4.41",
   "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": {