@blamejs/blamejs-shop 0.4.22 → 0.4.24

package/lib/order.js

@@ -209,6 +209,22 @@ function create(opts) {
   // fire-and-forget on the same detached-promise discipline as the
   // loyalty fan-out: the transition has already persisted.
   var referrals = opts.referrals || null;
+  // Optional new-order observer — a `function (order)` the FSM calls,
+  // fire-and-forget, the moment an order reaches `paid` (pending →
+  // paid). It's how the operator console learns a sale settled without
+  // polling: the application points the slot at an adapter that drops
+  // an operator-inbox entry (and a navbar badge ticks up). Late-bound
+  // via `setNewOrderObserver` because the operator-ping adapter is
+  // constructed AFTER the order primitive (it composes the same order
+  // handle to read the customer/total), so the slot is assigned once
+  // the wiring is complete. Opt-in like the other fan-outs; absent it
+  // the paid edge is a clean no-op. The call is detached on the same
+  // discipline as the loyalty / referral fan-outs — the transition has
+  // already persisted, so an observer read/write must never add latency
+  // to (or fail) the order transition.
+  var newOrderObserver = (typeof opts.newOrderObserver === "function")
+    ? opts.newOrderObserver
+    : null;
   // Optional inventory handle — when present, the order FSM converts the
   // confirm-time stock holds into real shelf movements as the order
   // changes state. On `mark_paid` (pending → paid) each shippable line's
@@ -258,6 +274,18 @@ function create(opts) {
   // balance is authoritative; the ledger is the audit trail surfaced in the
   // admin console).
   var giftCardLedger = opts.giftCardLedger || null;
+  // Optional loyalty handle — when present, the FSM restores loyalty points
+  // a customer SPENT as a checkout tender when the order is refunded /
+  // cancelled, symmetric with the gift-card-spend restore above. The points
+  // were debited at checkout via loyalty.redeem against this order; a refund
+  // returns the buyer's money, so the points they tendered have to come back
+  // to their balance or the refund silently burns them (inconsistent with the
+  // gift-card spend, which IS restored). Distinct from `loyaltyEarnRules`
+  // (which reverses points EARNED on the purchase) — this restores points
+  // SPENT on it. Restore is proportional to the refunded amount + idempotent
+  // (restoreRedemption tracks cumulative restored per redeem row). Opt-in;
+  // absent it, a deploy without loyalty-as-tender runs unchanged.
+  var loyalty = opts.loyalty || null;
   // Pagination cursors for listForCustomer are HMAC-tagged via
   // b.pagination so an operator can't hand-craft one to skip past a
   // hidden order or replay across deployments. The secret defaults
@@ -328,13 +356,29 @@ function create(opts) {
   // so a reversal failure is caught, NOT re-thrown, and surfaced loudly (an
   // `order.giftcard.reversal.error` audit event plus, when the error-log
   // handle is wired, a durable /admin/errors row) for manual reconciliation.
-  async function _settleGiftCards(orderId) {
+  async function _settleGiftCards(orderId, refundedMinor, orderTotalMinor) {
     if (!giftCards) return;
     try {
-      var reversed = await giftCards.reverseRedemption(orderId);
+      var reversed;
+      if (typeof giftCards.reverseRedemptionProRata === "function"
+          && Number.isInteger(orderTotalMinor) && orderTotalMinor > 0) {
+        // Proportional reversal — re-mint only the share the refund covers.
+        // reversed_minor tracks the cumulative already credited per
+        // redemption, so a partial-then-final refund sequence converges
+        // exactly on the original spend and never over-credits.
+        reversed = await giftCards.reverseRedemptionProRata(orderId, {
+          refunded_minor:    refundedMinor,
+          order_total_minor: orderTotalMinor,
+        });
+      } else {
+        // Fallback — a giftCards handle without the pro-rata method, or a
+        // zero-total order: all-or-nothing reversal of the full spend.
+        reversed = await giftCards.reverseRedemption(orderId);
+      }
       if (giftCardLedger && typeof giftCardLedger.credit === "function") {
         for (var i = 0; i < reversed.length; i += 1) {
           var rev = reversed[i];
+          if (!rev || !(Number(rev.amount_minor) > 0)) continue;
           try {
             // allow:money-binding-currency-without-catalog-check — this is a REVERSAL credit of an existing redemption: it replays the exact amount already debited from an already-issued card (whose currency was ISO-4217-validated at giftcards.issue time). No currency is supplied or chosen here — the ledger credit carries no currency field; it inherits the card's. There is no new currency surface to catalog-check.
             await giftCardLedger.credit({
@@ -584,32 +628,58 @@ function create(opts) {
       // transition has already persisted and the webhook must return 2xx, so
       // a reversal failure surfaces loudly for reconciliation rather than
       // 500ing the request.
+      // Death-edge value reversal. A cancel (pending-abandon or post-paid)
+      // or a balance-clearing refund returns EVERY credit the order consumed
+      // or earned, in full: refundedMinor = the order's grand total. The
+      // pro-rata reversers track the cumulative already reversed (per
+      // redemption / award / redeem row), so when partial refunds preceded
+      // this edge they credit only the remaining delta — a partial-then-final
+      // sequence converges exactly on the order total, never over-crediting.
       if (result.to === "cancelled" || result.to === "refunded") {
-        await _settleGiftCards(orderId);
-      }
-      // Loyalty earn-reversal fan-out — fire-and-forget, same discipline
-      // as the earn-on-purchase block below. On a cancel / refund edge for
-      // an order carrying a customer_id, the points awarded when the order
-      // went paid are clawed back off the balance (floored at zero), or a
-      // buy-then-refund mints free rewards. reverseForEvent claims the
-      // earn-log rows with an unreversed predicate, so it is idempotent (a
-      // re-delivered cancel webhook or the reaper racing a refund reverses
-      // exactly once) and a natural no-op for an order that never earned
-      // (a guest order, or one that never reached paid — the never-awarded
-      // earn-log is empty). The award is detached so a loyalty failure
-      // lives in the loyalty ledger's own audit trail, never as an
-      // unhandledRejection and never on the transition's latency.
-      if (loyaltyEarnRules && typeof loyaltyEarnRules.reverseForEvent === "function"
-          && (result.to === "cancelled" || result.to === "refunded")
-          && refreshed && refreshed.customer_id) {
-        var _revCustomer = refreshed.customer_id;
-        var _revOrderId  = refreshed.id;
-        Promise.resolve().then(function () {
-          return loyaltyEarnRules.reverseForEvent({
-            customer_id:       _revCustomer,
-            trigger_event_ref: "order:" + _revOrderId,
-          });
-        }).catch(function () { /* drop-silent — loyalty ledger holds its own audit trail */ });
+        var _refTotal = Number(refreshed && refreshed.grand_total_minor) || 0;
+        // Gift-card spend — SYNCHRONOUS (the customer's own money), idempotent,
+        // drop-silent-with-capture (see _settleGiftCards).
+        await _settleGiftCards(orderId, _refTotal, _refTotal);
+        if (refreshed && refreshed.customer_id && _refTotal > 0) {
+          var _revCustomer = refreshed.customer_id;
+          var _revOrderId  = refreshed.id;
+          // Loyalty points SPENT as a checkout tender — restored to the
+          // balance. Detached + drop-silent (loyalty ledger holds its own
+          // audit trail); restoreRedemption claims each redeem row's slice so
+          // a re-delivered webhook can't double-restore.
+          if (loyalty && typeof loyalty.restoreRedemption === "function") {
+            Promise.resolve().then(function () {
+              return loyalty.restoreRedemption(_revOrderId, {
+                refunded_minor:    _refTotal,
+                order_total_minor: _refTotal,
+              });
+            }).catch(function () { /* drop-silent — loyalty ledger holds its own audit trail */ });
+          }
+          // Loyalty points EARNED on the purchase — clawed back proportionally
+          // (full, on a death edge). Detached + drop-silent; clawed_points
+          // makes the claw idempotent and convergent across partial slices.
+          if (loyaltyEarnRules && typeof loyaltyEarnRules.reverseForEventProRata === "function") {
+            Promise.resolve().then(function () {
+              return loyaltyEarnRules.reverseForEventProRata({
+                customer_id:       _revCustomer,
+                trigger_event_ref: "order:" + _revOrderId,
+                refunded_minor:    _refTotal,
+                order_total_minor: _refTotal,
+              });
+            }).catch(function () { /* drop-silent — loyalty ledger holds its own audit trail */ });
+          }
+        }
+        // Referral funnel — the qualifying first order being voided rolls back
+        // the both-rewarded completion and decrements the referrer's count.
+        // Terminal edge only (a partial refund doesn't void the order).
+        // Detached + drop-silent; reverseForOrder claims the invitation with an
+        // unreversed predicate so a re-delivered webhook reverses exactly once.
+        if (referrals && typeof referrals.reverseForOrder === "function" && refreshed) {
+          var _refrOrderId = refreshed.id;
+          Promise.resolve().then(function () {
+            return referrals.reverseForOrder(_refrOrderId);
+          }).catch(function () { /* drop-silent — referral funnel holds its own audit trail */ });
+        }
       }
       // Fan-out to merchant webhook subscribers is fire-and-forget. The
       // transition has already persisted; the request must not wait on
@@ -688,9 +758,139 @@ function create(opts) {
           return referrals.trackPurchase({ customer_id: _refCustomer, order_id: _refOrderId });
         }).catch(function () { /* drop-silent — referral funnel holds its own audit trail */ });
       }
+      // New-order operator ping — fire-and-forget, same discipline as the
+      // loyalty / referral fan-outs above. Only on the paid transition
+      // (pending → paid is the edge that owns inventory debit, so this
+      // fires exactly once per real sale — a re-delivered mark_paid is
+      // collapsed to a no-op transition upstream). Guest orders fire too:
+      // the operator wants to know a sale settled regardless of whether
+      // the buyer has an account. The observer is detached so a slow /
+      // failing inbox write never adds latency to (or fails) the order
+      // transition; the inbox enqueue holds its own durable audit trail.
+      if (newOrderObserver && result.to === "paid" && refreshed) {
+        var _pingOrder = refreshed;
+        Promise.resolve().then(function () {
+          return newOrderObserver(_pingOrder);
+        }).catch(function () { /* drop-silent — the observer owns its own failure trail */ });
+      }
       return refreshed;
     },
 
+    // Late-bind the new-order observer (see the `newOrderObserver` slot
+    // in the factory). The operator-ping adapter is constructed AFTER
+    // this primitive (it composes the same order handle), so the wiring
+    // assigns the slot once both halves exist. A non-function is refused
+    // at the boundary so a typo surfaces at boot, not as a silent
+    // never-firing ping. Pass `null` to detach.
+    setNewOrderObserver: function (fn) {
+      if (fn != null && typeof fn !== "function") {
+        throw new TypeError("order.setNewOrderObserver: observer must be a function or null");
+      }
+      newOrderObserver = fn || null;
+    },
+
+    // Sum of every refund recorded against this order, in minor units.
+    // Both the FSM `refund` transition (full / balance-clearing refund →
+    // `refunded`) and a partial-refund record (recordPartialRefund — a
+    // same-state self-loop) write an `order_transitions` row whose
+    // metadata carries `amount_minor`, so the running refunded total is
+    // the SUM of `amount_minor` across every `on_event = 'refund'` row.
+    // Rows with no amount in metadata (a legacy full refund that recorded
+    // none) contribute 0 here — the partial-refund console always records
+    // the amount, so a mixed history still totals correctly going forward.
+    // Integer minor-unit arithmetic throughout (never a float): the values
+    // are exact minor-unit integers from the order totals + provider refund
+    // amounts, so the sum is exact.
+    refundedTotalMinor: async function (orderId) {
+      _uuid(orderId, "order id");
+      var rows = (await query(
+        "SELECT metadata_json FROM order_transitions " +
+        "WHERE order_id = ?1 AND on_event = 'refund'",
+        [orderId],
+      )).rows;
+      var total = 0;
+      for (var i = 0; i < rows.length; i += 1) {
+        var meta;
+        try { meta = JSON.parse(rows[i].metadata_json || "{}"); }
+        catch (_e) { meta = {}; }
+        var amt = meta && meta.amount_minor;
+        if (Number.isInteger(amt) && amt > 0) total += amt;
+      }
+      return total;
+    },
+
+    // Record a PARTIAL refund that does NOT clear the order's balance — the
+    // money has already moved at the payment provider; this appends the
+    // audit row WITHOUT changing the order's FSM state (a same-state
+    // self-loop `refund` transition). A partial refund leaves the order in
+    // its current lifecycle state (a paid / fulfilling / shipped order keeps
+    // moving) — only a balance-clearing refund drives the FSM `refund` edge
+    // to the terminal `refunded` state via `transition`. The caller (the
+    // admin refund console) is responsible for choosing partial-vs-final:
+    // it issues the provider refund first, then calls this for a partial or
+    // `transition('refund')` for the final slice. `amount_minor` is a
+    // positive integer in minor units (validated here as a config/entry
+    // contract — a bad amount throws so the caller surfaces a 4xx, never a
+    // silently-wrong ledger row). Returns the refreshed order.
+    recordPartialRefund: async function (orderId, opts2) {
+      _uuid(orderId, "order id");
+      opts2 = opts2 || {};
+      _positiveInt(opts2.amount_minor, "amount_minor");
+      var current = (await query("SELECT * FROM orders WHERE id = ?1", [orderId])).rows[0];
+      if (!current) throw new TypeError("order.recordPartialRefund: order " + orderId + " not found");
+      var meta = Object.assign({}, opts2.metadata || {});
+      meta.amount_minor = opts2.amount_minor;
+      meta.partial = true;
+      var ts = _now();
+      await query(
+        "INSERT INTO order_transitions (id, order_id, from_state, to_state, on_event, reason, metadata_json, occurred_at) " +
+        "VALUES (?1, ?2, ?3, ?3, 'refund', ?4, ?5, ?6)",
+        [
+          b.uuid.v7(), orderId, current.status,
+          opts2.reason || null,
+          JSON.stringify(meta),
+          ts,
+        ],
+      );
+      // updated_at is bumped so the order surfaces at the top of the
+      // operator recent-orders list after a partial refund, matching how a
+      // real FSM transition touches it.
+      await query("UPDATE orders SET updated_at = ?1 WHERE id = ?2", [ts, orderId]);
+      // Return the credits this refund covers, in proportion to the refunded
+      // total SO FAR (this slice included). Gift-card spend is re-minted and
+      // loyalty (redeemed + earned) restored / clawed against the cumulative
+      // refunded amount, so a partial-then-final refund sequence converges
+      // exactly on the order total. Referral funnel reversal waits for the
+      // terminal refund edge — a partial refund doesn't void the order.
+      var _ptTotal = Number(current.grand_total_minor) || 0;
+      if (_ptTotal > 0) {
+        var _ptRefunded = await this.refundedTotalMinor(orderId);
+        await _settleGiftCards(orderId, _ptRefunded, _ptTotal);
+        if (current.customer_id) {
+          var _ptCust = current.customer_id;
+          if (loyalty && typeof loyalty.restoreRedemption === "function") {
+            Promise.resolve().then(function () {
+              return loyalty.restoreRedemption(orderId, {
+                refunded_minor:    _ptRefunded,
+                order_total_minor: _ptTotal,
+              });
+            }).catch(function () { /* drop-silent — loyalty ledger holds its own audit trail */ });
+          }
+          if (loyaltyEarnRules && typeof loyaltyEarnRules.reverseForEventProRata === "function") {
+            Promise.resolve().then(function () {
+              return loyaltyEarnRules.reverseForEventProRata({
+                customer_id:       _ptCust,
+                trigger_event_ref: "order:" + orderId,
+                refunded_minor:    _ptRefunded,
+                order_total_minor: _ptTotal,
+              });
+            }).catch(function () { /* drop-silent — loyalty ledger holds its own audit trail */ });
+          }
+        }
+      }
+      return await this.get(orderId);
+    },
+
     // Paginated history for a single customer. Tuple cursor
     // (updated_at, id) ordered DESC so the customer's most-recent
     // activity surfaces first. Mirrors the cursor shape used by

package/lib/payment.js

@@ -8,9 +8,15 @@
  *   verification (HMAC-SHA256 over `<timestamp>.<body>` with
  *   `whsec_...` secret, ±5 min tolerance, constant-time compare) and
  *   outbound API calls (PaymentIntent create / retrieve / confirm /
- *   cancel + Refund) composed on `b.httpClient` (SSRF-gated, retried,
- *   circuit-broken, ALPN HTTP/2). No `stripe` npm dep — every byte is
- *   either node built-in or vendored blamejs primitive.
+ *   cancel + Refund) on `b.httpClient` (SSRF-gated, response-capped,
+ *   ALPN HTTP/2). Each adapter instance wraps its dials in a per-upstream
+ *   `b.circuitBreaker` plus a bounded `b.retry` (the latter only on
+ *   idempotent dials — GET reads + idempotency-keyed writes — so a
+ *   transient blip never re-sends a one-shot charge). While the breaker is
+ *   open the dial fast-fails with `code: "CIRCUIT_OPEN"` BEFORE the
+ *   request, so checkout renders the recoverable payment-unavailable page
+ *   rather than stranding an order mid-charge. No `stripe` npm dep — every
+ *   byte is either node built-in or vendored blamejs primitive.
  *
  *   Future Adyen / Mollie / Paddle adapters land as additional
  *   factory functions returning the same `{ verifyWebhook,
@@ -48,6 +54,59 @@ var STRIPE_WEBHOOK_TOLERANCE = 300;   // ± 5 minutes (Stripe default)
 var STRIPE_HTTP_TIMEOUT_MS   = 15000;
 var CURRENCY_RE              = /^[a-z]{3}$/;   // Stripe wants lowercase ISO 4217
 
+// ---- PSP dial resilience (circuit breaker + bounded retry) ----------------
+//
+// b.httpClient does NOT itself circuit-break or retry — it SSRF-gates, caps,
+// and pools, but the failure-threshold breaker + backoff retry are separate
+// primitives a consumer composes around it. Each adapter instance owns ONE
+// breaker per upstream (Stripe / PayPal): per-target is the only correct
+// scope — sharing a breaker across unrelated peers defeats the
+// failure-threshold semantic.
+//
+// Open-circuit posture: while the breaker is open every dial fast-fails with
+// a plain Error carrying `code: "CIRCUIT_OPEN"` (NOT a TypeError), so the
+// storefront's checkout handler renders it through the existing recoverable
+// "checkout didn't go through" page — the same structured payment-unavailable
+// surface a raw upstream 5xx already produces — rather than charging or
+// 400-ing a field. Nothing is captured: the breaker fails BEFORE the dial, so
+// no order is stranded mid-charge.
+//
+// Retry rides ONLY on idempotent dials — GET reads and writes carrying an
+// idempotency key (Stripe Idempotency-Key / PayPal-Request-Id). A
+// keyless POST is sent exactly once: re-driving it could double-charge.
+var BREAKER_FAILURE_THRESHOLD = 5;                 // consecutive failures before opening
+var BREAKER_COOLDOWN_MS       = C.TIME.seconds(30); // open → half-open probe delay
+var BREAKER_SUCCESS_THRESHOLD = 2;                 // half-open probes to re-close
+var DIAL_RETRY_MAX_ATTEMPTS   = 3;                 // total tries incl. first (idempotent only)
+var DIAL_RETRY_BASE_DELAY_MS  = 200;
+var DIAL_RETRY_MAX_DELAY_MS   = C.TIME.seconds(2);
+
+// One breaker per adapter instance. `idempotent` selects whether the dial
+// also rides the bounded backoff retry — the breaker counts the retry loop's
+// FINAL outcome as a single call (b.retry.withBreaker), so a transient blip
+// that the retry rides out never inflates the failure counter.
+function _makeBreaker(name) {
+  return b.circuitBreaker.create({
+    name:             name,
+    failureThreshold: BREAKER_FAILURE_THRESHOLD,
+    cooldownMs:       BREAKER_COOLDOWN_MS,
+    successThreshold: BREAKER_SUCCESS_THRESHOLD,
+  });
+}
+
+function _dial(breaker, idempotent, fn) {
+  if (!breaker) return fn();
+  if (!idempotent) return breaker.wrap(fn);
+  return b.retry.withBreaker(fn, {
+    breaker: breaker,
+    retry:   {
+      maxAttempts: DIAL_RETRY_MAX_ATTEMPTS,
+      baseDelayMs: DIAL_RETRY_BASE_DELAY_MS,
+      maxDelayMs:  DIAL_RETRY_MAX_DELAY_MS,
+    },
+  });
+}
+
 // Stripe holds idempotency keys for 24h, so the local cache row
 // expires on the same window — operators who run `cleanupExpired()`
 // on a daily schedule keep the table small without ever shortening
@@ -196,33 +255,47 @@ async function _stripeCall(opts, method, path, params, idempotencyKey) {
     headers["idempotency-key"] = idempotencyKey;
   }
   var httpClient = opts.httpClient || b.httpClient;
-  var res = await httpClient.request({
-    method:    method,
-    url:       url,
-    headers:   headers,
-    body:      body || undefined,
-    timeoutMs: opts.timeoutMs || STRIPE_HTTP_TIMEOUT_MS,
-    agent:     _PSP_TLS_AGENT,
+  // A GET read is always idempotent; a write is idempotent only when it
+  // carries an Idempotency-Key (Stripe dedupes a replay of the SAME key
+  // server-side). A keyless POST rides the breaker but NOT the retry, so
+  // a transient blip never re-sends it (double-charge guard).
+  var idempotent = method === "GET" || !!idempotencyKey;
+  // The HTTP request AND the non-2xx → throw both run INSIDE the dialed
+  // closure so the breaker counts a 5xx / transport error as a failure
+  // (and the idempotent-path retry retries it). A 4xx is the request's
+  // fault, not the peer's health — `err.statusCode` makes the retry
+  // classifier skip it, and a 4xx still increments the breaker, which is
+  // acceptable since a sustained stream of 4xx is itself a degraded state.
+  var json = await _dial(opts._breaker, idempotent, async function () {
+    var res = await httpClient.request({
+      method:    method,
+      url:       url,
+      headers:   headers,
+      body:      body || undefined,
+      timeoutMs: opts.timeoutMs || STRIPE_HTTP_TIMEOUT_MS,
+      agent:     _PSP_TLS_AGENT,
+    });
+    var text = res.body && res.body.toString ? res.body.toString("utf8") : "";
+    var parsed = null;
+    try { parsed = text.length ? JSON.parse(text) : {}; } catch (_e) { parsed = { _raw: text }; }
+    if (res.statusCode < 200 || res.statusCode >= 300) {
+      var err = new Error("stripe: " + method + " " + path + " → HTTP " + res.statusCode +
+                          (parsed && parsed.error && parsed.error.message ? " — " + parsed.error.message : ""));
+      err.code = (parsed && parsed.error && parsed.error.code) || "STRIPE_HTTP_" + res.statusCode;
+      err.statusCode = res.statusCode;
+      err.stripe = parsed && parsed.error || null;
+      err._stripeRawText   = text;
+      err._stripeStatus    = res.statusCode;
+      throw err;
+    }
+    // Carry the raw status + serialised body alongside the parsed JSON
+    // so the idempotency layer can persist them verbatim for replay
+    // without re-stringifying (preserves byte-for-byte fidelity with
+    // what Stripe returned, including field ordering).
+    Object.defineProperty(parsed, "_stripeStatus",  { value: res.statusCode, enumerable: false });
+    Object.defineProperty(parsed, "_stripeRawText", { value: text,           enumerable: false });
+    return parsed;
   });
-  var text = res.body && res.body.toString ? res.body.toString("utf8") : "";
-  var json = null;
-  try { json = text.length ? JSON.parse(text) : {}; } catch (_e) { json = { _raw: text }; }
-  if (res.statusCode < 200 || res.statusCode >= 300) {
-    var err = new Error("stripe: " + method + " " + path + " → HTTP " + res.statusCode +
-                        (json && json.error && json.error.message ? " — " + json.error.message : ""));
-    err.code = (json && json.error && json.error.code) || "STRIPE_HTTP_" + res.statusCode;
-    err.statusCode = res.statusCode;
-    err.stripe = json && json.error || null;
-    err._stripeRawText   = text;
-    err._stripeStatus    = res.statusCode;
-    throw err;
-  }
-  // Carry the raw status + serialised body alongside the parsed JSON
-  // so the idempotency layer can persist them verbatim for replay
-  // without re-stringifying (preserves byte-for-byte fidelity with
-  // what Stripe returned, including field ordering).
-  Object.defineProperty(json, "_stripeStatus",  { value: res.statusCode, enumerable: false });
-  Object.defineProperty(json, "_stripeRawText", { value: text,           enumerable: false });
   return json;
 }
 
@@ -330,6 +403,13 @@ function stripe(opts) {
     throw new TypeError("payment: now must be a function returning current epoch ms");
   }
 
+  // One circuit breaker per adapter instance, guarding every Stripe dial.
+  // Stashed on opts so the module-level `_stripeCall` reaches it without a
+  // signature change. Skippable in tests via `breaker: false`.
+  if (opts._breaker === undefined) {
+    opts._breaker = opts.breaker === false ? null : _makeBreaker("psp-stripe");
+  }
+
   // Idempotency state shared across every mutating call. When `query`
   // is not supplied the primitive runs in legacy mode — every
   // mutating call goes straight to Stripe, no cache writes, no
@@ -349,6 +429,11 @@ function stripe(opts) {
   return {
     name: "stripe",
 
+    // The per-adapter circuit breaker (or null when disabled). Exposed so
+    // an operator dashboard can read `breaker.getState()` ("closed" /
+    // "open" / "half") and reset it after a confirmed recovery.
+    breaker: opts._breaker,
+
     verifyWebhook: function (headers, rawBody, vOpts) {
       return _verifyWebhook(headers, rawBody, opts.webhookSecret, vOpts);
     },
@@ -648,28 +733,33 @@ async function _paypalToken(opts, state) {
   if (state.token && now < state.tokenExpiresAt) return state.token;
   var httpClient = opts.httpClient || b.httpClient;
   var basic = Buffer.from(opts.clientId + ":" + opts.secret).toString("base64");
-  var res = await httpClient.request({
-    method:  "POST",
-    url:     _paypalApiBase(opts) + "/v1/oauth2/token",
-    headers: {
-      "authorization":  "Basic " + basic,
-      "accept":         "application/json",
-      "content-type":   "application/x-www-form-urlencoded",
-      "user-agent":     "blamejs-shop (zero-dep)",
-    },
-    body:      "grant_type=client_credentials",
-    timeoutMs: opts.timeoutMs || PAYPAL_HTTP_TIMEOUT_MS,
-    agent:     _PSP_TLS_AGENT,
+  // The client-credentials token exchange is idempotent (re-asking for a
+  // token is always safe), so it rides the breaker AND the bounded retry.
+  var json = await _dial(opts._breaker, true, async function () {
+    var res = await httpClient.request({
+      method:  "POST",
+      url:     _paypalApiBase(opts) + "/v1/oauth2/token",
+      headers: {
+        "authorization":  "Basic " + basic,
+        "accept":         "application/json",
+        "content-type":   "application/x-www-form-urlencoded",
+        "user-agent":     "blamejs-shop (zero-dep)",
+      },
+      body:      "grant_type=client_credentials",
+      timeoutMs: opts.timeoutMs || PAYPAL_HTTP_TIMEOUT_MS,
+      agent:     _PSP_TLS_AGENT,
+    });
+    var text = res.body && res.body.toString ? res.body.toString("utf8") : "";
+    var parsed; try { parsed = text.length ? JSON.parse(text) : {}; } catch (_e) { parsed = {}; }
+    if (res.statusCode < 200 || res.statusCode >= 300 || !parsed.access_token) {
+      var err = new Error("paypal: OAuth2 token exchange failed → HTTP " + res.statusCode +
+                          (parsed && parsed.error_description ? " — " + parsed.error_description : ""));
+      err.code = "PAYPAL_AUTH_" + res.statusCode;
+      err.statusCode = res.statusCode;
+      throw err;
+    }
+    return parsed;
   });
-  var text = res.body && res.body.toString ? res.body.toString("utf8") : "";
-  var json; try { json = text.length ? JSON.parse(text) : {}; } catch (_e) { json = {}; }
-  if (res.statusCode < 200 || res.statusCode >= 300 || !json.access_token) {
-    var err = new Error("paypal: OAuth2 token exchange failed → HTTP " + res.statusCode +
-                        (json && json.error_description ? " — " + json.error_description : ""));
-    err.code = "PAYPAL_AUTH_" + res.statusCode;
-    err.statusCode = res.statusCode;
-    throw err;
-  }
   state.token = json.access_token;
   var ttlMs = (typeof json.expires_in === "number" ? json.expires_in : 0) * 1000; // allow:raw-time-literal — PayPal expires_in is a runtime seconds value; *1000 → ms
   state.tokenExpiresAt = now + Math.max(0, ttlMs - PAYPAL_TOKEN_SKEW_MS);
@@ -688,26 +778,34 @@ async function _paypalCall(opts, state, method, path, bodyObj, requestId) {
   var body = bodyObj != null ? JSON.stringify(bodyObj) : undefined;
   if (body) headers["content-length"] = Buffer.byteLength(body, "utf8");
   var httpClient = opts.httpClient || b.httpClient;
-  var res = await httpClient.request({
-    method:    method,
-    url:       _paypalApiBase(opts) + path,
-    headers:   headers,
-    body:      body,
-    timeoutMs: opts.timeoutMs || PAYPAL_HTTP_TIMEOUT_MS,
-    agent:     _PSP_TLS_AGENT,
+  // A GET is idempotent; a write is idempotent only when it carries a
+  // PayPal-Request-Id (PayPal dedupes a replay of the SAME id, and the
+  // same id rides every retry attempt within one call). A keyless write
+  // rides the breaker but not the retry.
+  var idempotent = method === "GET" || !!requestId;
+  var json = await _dial(opts._breaker, idempotent, async function () {
+    var res = await httpClient.request({
+      method:    method,
+      url:       _paypalApiBase(opts) + path,
+      headers:   headers,
+      body:      body,
+      timeoutMs: opts.timeoutMs || PAYPAL_HTTP_TIMEOUT_MS,
+      agent:     _PSP_TLS_AGENT,
+    });
+    var text = res.body && res.body.toString ? res.body.toString("utf8") : "";
+    var parsed; try { parsed = text.length ? JSON.parse(text) : {}; } catch (_e) { parsed = { _raw: text }; }
+    if (res.statusCode < 200 || res.statusCode >= 300) {
+      var detail = parsed && (parsed.message || (parsed.details && parsed.details[0] && parsed.details[0].description)) || "";
+      var err = new Error("paypal: " + method + " " + path + " → HTTP " + res.statusCode + (detail ? " — " + detail : ""));
+      err.code = (parsed && parsed.name) || "PAYPAL_HTTP_" + res.statusCode;
+      err.statusCode = res.statusCode;
+      err.paypal = parsed || null;
+      throw err;
+    }
+    Object.defineProperty(parsed, "_paypalStatus",  { value: res.statusCode, enumerable: false });
+    Object.defineProperty(parsed, "_paypalRawText", { value: text,           enumerable: false });
+    return parsed;
   });
-  var text = res.body && res.body.toString ? res.body.toString("utf8") : "";
-  var json; try { json = text.length ? JSON.parse(text) : {}; } catch (_e) { json = { _raw: text }; }
-  if (res.statusCode < 200 || res.statusCode >= 300) {
-    var detail = json && (json.message || (json.details && json.details[0] && json.details[0].description)) || "";
-    var err = new Error("paypal: " + method + " " + path + " → HTTP " + res.statusCode + (detail ? " — " + detail : ""));
-    err.code = (json && json.name) || "PAYPAL_HTTP_" + res.statusCode;
-    err.statusCode = res.statusCode;
-    err.paypal = json || null;
-    throw err;
-  }
-  Object.defineProperty(json, "_paypalStatus",  { value: res.statusCode, enumerable: false });
-  Object.defineProperty(json, "_paypalRawText", { value: text,           enumerable: false });
   return json;
 }
 
@@ -721,6 +819,13 @@ function paypal(opts) {
   if (opts.now != null && typeof opts.now !== "function") {
     throw new TypeError("payment: now must be a function returning current epoch ms");
   }
+  // One circuit breaker per adapter instance, guarding every PayPal dial
+  // (the token exchange + every Orders-v2 call). Skippable in tests via
+  // `breaker: false`.
+  if (opts._breaker === undefined) {
+    opts._breaker = opts.breaker === false ? null : _makeBreaker("psp-paypal");
+  }
+
   var state = {
     query:          opts.query || null,
     now:            typeof opts.now === "function" ? opts.now : function () { return Date.now(); },
@@ -744,6 +849,10 @@ function paypal(opts) {
   return {
     name: "paypal",
 
+    // The per-adapter circuit breaker (or null when disabled). Same
+    // operator-dashboard surface as the Stripe adapter's.
+    breaker: opts._breaker,
+
     // Create an Orders-v2 order (intent CAPTURE). The returned `id` is the
     // PayPal order id the buyer approves; `captureOrder` finalizes it.
     createOrder: function (input, idempotencyKey) {