@blamejs/blamejs-shop 0.4.23 → 0.4.24

package/lib/operator-inbox.js

@@ -127,6 +127,25 @@
  *     - unreadCount({ operator_id, severity_min? })
  *         Cheap count for the navbar badge. Excludes archived.
  *
+ *     - inboxForRole({ role, severity_min?, unread_only?,
+ *                      include_archived?, limit?, cursor? })
+ *         Read the messages broadcast to a single role, newest-first.
+ *         Returns ONLY `role = ?` rows (never operator-id-addressed
+ *         ones), so it composes with `inboxForOperator` rather than
+ *         duplicating it — the read side for a console that addresses
+ *         notifications to a role and has no per-operator session to
+ *         fold role membership through.
+ *
+ *     - unreadCountForRole({ role, severity_min? })
+ *         Role-scoped navbar-badge count. Excludes archived + read.
+ *
+ *     - markReadForRole({ id, role }) / archiveForRole({ id, role })
+ *         Clear / retire a role-broadcast row by its role rather than
+ *         by an owning operator. Each asserts the row carries the
+ *         supplied role before mutating (a caller can't clear an
+ *         operator-id-addressed row, or another role's row, by
+ *         guessing its id). Idempotent.
+ *
  *     - cleanupOlderThan({ now?, age_ms })
  *         Delete rows whose `created_at < (now - age_ms)`. Used to
  *         keep the table bounded — the inbox is a feed, not an
@@ -771,6 +790,176 @@ function create(opts) {
     return Number(row.c || row.COUNT || 0);
   }
 
+  // ---- inboxForRole -----------------------------------------------------
+  //
+  // Read every message broadcast to a single role, newest-first. This is
+  // the read side for a console that addresses notifications to a role
+  // rather than to one owning operator — e.g. a single-credential admin
+  // where the "fulfillment" team is the audience but there's no per-
+  // operator session to fold role membership through. It returns ONLY
+  // `role = ?` rows (never operator-id-addressed rows), so it composes
+  // with `inboxForOperator` rather than duplicating it. Same severity_min
+  // / unread_only / include_archived / HMAC-cursor surface.
+  async function inboxForRole(input) {
+    if (!input || typeof input !== "object") {
+      throw new TypeError("operatorInbox.inboxForRole: input object required");
+    }
+    var role            = _role(input.role, "role");
+    var severityMin     = _severityMin(input.severity_min);
+    var unreadOnly      = _bool(input.unread_only,      "unread_only",      false);
+    var includeArchived = _bool(input.include_archived, "include_archived", false);
+    var limit           = _limit(input.limit);
+    var cursorState     = _decodeCursor(input.cursor, "inboxForRole");
+
+    var params = [];
+    var idx    = 1;
+    var pushP  = function (v) { params.push(v); var k = idx; idx += 1; return "?" + k; };
+
+    var where = "role = " + pushP(role);
+    if (!includeArchived) where += " AND archived_at IS NULL";
+    if (unreadOnly)       where += " AND read_at IS NULL";
+
+    if (severityMin) {
+      var minRank = SEVERITY_RANK[severityMin];
+      var allowed = [];
+      for (var si = 0; si < SEVERITIES.length; si += 1) {
+        if (SEVERITY_RANK[SEVERITIES[si]] >= minRank) {
+          allowed.push(pushP(SEVERITIES[si]));
+        }
+      }
+      where += " AND severity IN (" + allowed.join(", ") + ")";
+    }
+
+    if (cursorState) {
+      var caP = pushP(cursorState.created_at);
+      var idP = pushP(cursorState.id);
+      where  += " AND (created_at < " + caP +
+                " OR (created_at = " + caP + " AND id < " + idP + "))";
+    }
+
+    var limitPlace = pushP(limit);
+    var sql = "SELECT * FROM operator_inbox_messages WHERE " + where +
+              " ORDER BY created_at DESC, id DESC LIMIT " + limitPlace;
+    var r = await query(sql, params);
+    var rows = [];
+    for (var ki = 0; ki < r.rows.length; ki += 1) rows.push(_decodeRow(r.rows[ki]));
+    var nextCursor = rows.length === limit
+      ? b.pagination.encodeCursor({
+          orderKey: CURSOR_ORDER_KEY,
+          vals:     [rows[rows.length - 1].created_at, rows[rows.length - 1].id],
+          forward:  true,
+        }, cursorSecret)
+      : null;
+    return { rows: rows, next_cursor: nextCursor };
+  }
+
+  // ---- unreadCountForRole -----------------------------------------------
+  //
+  // Cheap navbar-badge count of unread, un-archived messages broadcast to
+  // one role. The role-scoped sibling of `unreadCount` — used by a
+  // role-addressed console where the badge audience is a role, not a
+  // single operator.
+  async function unreadCountForRole(input) {
+    if (!input || typeof input !== "object") {
+      throw new TypeError("operatorInbox.unreadCountForRole: input object required");
+    }
+    var role        = _role(input.role, "role");
+    var severityMin = _severityMin(input.severity_min);
+
+    var params = [];
+    var idx    = 1;
+    var pushP  = function (v) { params.push(v); var k = idx; idx += 1; return "?" + k; };
+
+    var where = "role = " + pushP(role) +
+                " AND read_at IS NULL AND archived_at IS NULL";
+
+    if (severityMin) {
+      var minRank = SEVERITY_RANK[severityMin];
+      var allowed = [];
+      for (var si = 0; si < SEVERITIES.length; si += 1) {
+        if (SEVERITY_RANK[SEVERITIES[si]] >= minRank) {
+          allowed.push(pushP(SEVERITIES[si]));
+        }
+      }
+      where += " AND severity IN (" + allowed.join(", ") + ")";
+    }
+
+    var sql = "SELECT COUNT(*) AS c FROM operator_inbox_messages WHERE " + where;
+    var r = await query(sql, params);
+    var row = r.rows[0] || {};
+    return Number(row.c || row.COUNT || 0);
+  }
+
+  // ---- markReadForRole / archiveForRole ---------------------------------
+  //
+  // The role-scoped write side. A console addressing notifications to a
+  // role (rather than to one owning operator) needs to clear a role-
+  // broadcast row WITHOUT a per-operator session to gate against — the
+  // role itself is the audience. Both assert the row carries the supplied
+  // role before mutating, so a caller can't clear an operator-id-addressed
+  // row (or a different role's row) by guessing its id. Idempotent.
+  async function _roleAddressableRow(messageId, role) {
+    var r = await query("SELECT * FROM operator_inbox_messages WHERE id = ?1", [messageId]);
+    if (!r.rows.length) return { row: null, reason: "not_found" };
+    var row = r.rows[0];
+    if (row.role != null && row.role === role) return { row: row, reason: null };
+    return { row: row, reason: "not_addressable" };
+  }
+
+  async function markReadForRole(input) {
+    if (!input || typeof input !== "object") {
+      throw new TypeError("operatorInbox.markReadForRole: input object required");
+    }
+    var id   = _messageId(input.id);
+    var role = _role(input.role, "role");
+    var gated = await _roleAddressableRow(id, role);
+    if (gated.reason === "not_found") {
+      var miss = new Error("operatorInbox.markReadForRole: message not found");
+      miss.code = "INBOX_MESSAGE_NOT_FOUND";
+      throw miss;
+    }
+    if (gated.reason === "not_addressable") {
+      var nope = new Error("operatorInbox.markReadForRole: message not addressed to this role");
+      nope.code = "INBOX_MESSAGE_NOT_ADDRESSABLE";
+      throw nope;
+    }
+    if (gated.row.read_at != null) return _decodeRow(gated.row);   // idempotent
+    var ts = _now();
+    await query(
+      "UPDATE operator_inbox_messages SET read_at = ?1 WHERE id = ?2 AND read_at IS NULL",
+      [ts, id],
+    );
+    var fresh = await query("SELECT * FROM operator_inbox_messages WHERE id = ?1", [id]);
+    return _decodeRow(fresh.rows[0]);
+  }
+
+  async function archiveForRole(input) {
+    if (!input || typeof input !== "object") {
+      throw new TypeError("operatorInbox.archiveForRole: input object required");
+    }
+    var id   = _messageId(input.id);
+    var role = _role(input.role, "role");
+    var gated = await _roleAddressableRow(id, role);
+    if (gated.reason === "not_found") {
+      var miss = new Error("operatorInbox.archiveForRole: message not found");
+      miss.code = "INBOX_MESSAGE_NOT_FOUND";
+      throw miss;
+    }
+    if (gated.reason === "not_addressable") {
+      var nope = new Error("operatorInbox.archiveForRole: message not addressed to this role");
+      nope.code = "INBOX_MESSAGE_NOT_ADDRESSABLE";
+      throw nope;
+    }
+    if (gated.row.archived_at != null) return _decodeRow(gated.row);   // idempotent
+    var ts = _now();
+    await query(
+      "UPDATE operator_inbox_messages SET archived_at = ?1 WHERE id = ?2 AND archived_at IS NULL",
+      [ts, id],
+    );
+    var fresh = await query("SELECT * FROM operator_inbox_messages WHERE id = ?1", [id]);
+    return _decodeRow(fresh.rows[0]);
+  }
+
   // ---- cleanupOlderThan -------------------------------------------------
 
   async function cleanupOlderThan(input) {
@@ -860,15 +1049,19 @@ function create(opts) {
     MAX_LIMIT:         MAX_LIMIT,
     MAX_BULK_IDS:      MAX_BULK_IDS,
 
-    enqueueMessage:    enqueueMessage,
-    inboxForOperator:  inboxForOperator,
-    markRead:          markRead,
-    markUnread:        markUnread,
-    archiveMessage:    archiveMessage,
-    bulkArchive:       bulkArchive,
-    unreadCount:       unreadCount,
-    cleanupOlderThan:  cleanupOlderThan,
-    metricsForKind:    metricsForKind,
+    enqueueMessage:     enqueueMessage,
+    inboxForOperator:   inboxForOperator,
+    inboxForRole:       inboxForRole,
+    markRead:           markRead,
+    markUnread:         markUnread,
+    markReadForRole:    markReadForRole,
+    archiveMessage:     archiveMessage,
+    archiveForRole:     archiveForRole,
+    bulkArchive:        bulkArchive,
+    unreadCount:        unreadCount,
+    unreadCountForRole: unreadCountForRole,
+    cleanupOlderThan:   cleanupOlderThan,
+    metricsForKind:     metricsForKind,
   };
 }
 

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