@blamejs/blamejs-shop 0.4.18 → 0.4.20

package/lib/giftcards.js

@@ -346,6 +346,66 @@ function create(opts) {
       };
     },
 
+    // Credit a card's spend back when the order that redeemed it never
+    // completed (abandoned / cancelled / refunded). `redeem` debited the
+    // card row's balance at checkout; if the order dies, that money must
+    // return to the card or the customer's balance is silently gone.
+    //
+    // Keyed on the ORDER id — the order FSM drives this on its cancel /
+    // refund edges (the same transitions that release inventory holds), so
+    // reversal is transition-driven, not a separate operator action. Every
+    // unreversed redemption against the order is restored.
+    //
+    // Idempotent + concurrency-safe: each redemption is claimed with
+    // `WHERE id = ? AND reversed_at IS NULL` and the rowCount checked, so a
+    // double-fire (the stale-order reaper racing a payment-failed webhook,
+    // or a re-delivered cancel) credits the balance back exactly once. The
+    // balance restore is itself bounded by the card's issued_minor CHECK, so
+    // it can never push the card above its original face value. A card that
+    // had drained to `redeemed` is reactivated since it now carries balance
+    // again. Returns the list of reversed redemptions (empty when there was
+    // nothing to reverse — an order that used no gift card, or one already
+    // fully reversed).
+    reverseRedemption: async function (orderId) {
+      _uuid(orderId, "order_id");
+      var rows = (await query(
+        "SELECT id, giftcard_id, amount_minor FROM giftcard_redemptions " +
+        "WHERE order_id = ?1 AND reversed_at IS NULL",
+        [orderId],
+      )).rows;
+      var reversed = [];
+      for (var i = 0; i < rows.length; i += 1) {
+        var red = rows[i];
+        var ts = _now();
+        // Claim the redemption first — the unreversed predicate is the
+        // serialization point so two concurrent reversals can't both credit.
+        var claim = await query(
+          "UPDATE giftcard_redemptions SET reversed_at = ?1 WHERE id = ?2 AND reversed_at IS NULL",
+          [ts, red.id],
+        );
+        if (Number(claim.rowCount || 0) === 0) continue;   // lost the claim
+        // Restore the spendable balance on the card row. Capped at the card's
+        // issued_minor by the schema CHECK; the amount restored is exactly
+        // what this redemption debited, so it can't exceed the face value.
+        // Reactivate a card that had drained to `redeemed` — it carries
+        // balance again. A `voided`/`expired` card stays in its terminal
+        // status (the balance is restored on the row for reconciliation, but
+        // a voided/expired card isn't spendable regardless).
+        await query(
+          "UPDATE giftcards SET balance_minor = balance_minor + ?1, " +
+          "status = CASE WHEN status = 'redeemed' THEN 'active' ELSE status END, " +
+          "updated_at = ?2 WHERE id = ?3",
+          [red.amount_minor, ts, red.giftcard_id],
+        );
+        reversed.push({
+          redemption_id: red.id,
+          gift_card_id:  red.giftcard_id,
+          amount_minor:  red.amount_minor,
+        });
+      }
+      return reversed;
+    },
+
     "void": async function (id, opts2) {
       opts2 = opts2 || {};
       _uuid(id, "giftcard id");

package/lib/order.js

@@ -58,6 +58,25 @@ var ORDER_TRANSITIONS = Object.freeze([
   { from: "delivered",  to: "refunded",   on: "refund",            label: "Refund" },
 ]);
 
+// Pickup (BOPIS) edges. An in-store collection has no carrier ship leg:
+// the goods sit on the hold shelf and the customer walks in. So a pickup
+// order goes straight from `paid` (or `fulfilling`, if the picker started
+// staging) to `delivered` on a single `mark_picked_up` event — driving it
+// through mark_shipped would record a carrier handoff that never happened.
+// These edges are kept OUT of ORDER_TRANSITIONS (and therefore out of
+// transitionsFrom) so the operator order-detail page doesn't sprout a
+// "mark picked up" button on every paid order — the click-and-collect
+// primitive fires the event when the front-counter operator captures the
+// pickup. They ARE merged into the FSM definition below so the transition
+// is legal: previously markPickedUp tried `mark_delivered` from `paid`,
+// which the FSM refused (delivered is only reachable from shipped) and the
+// caller swallowed — leaving the pickup schedule `picked_up` while the
+// parent order stayed stuck at paid/fulfilling.
+var PICKUP_TRANSITIONS = Object.freeze([
+  { from: "paid",       to: "delivered",  on: "mark_picked_up" },
+  { from: "fulfilling", to: "delivered",  on: "mark_picked_up" },
+]);
+
 function _getOrderFsm() {
   if (_orderFsm) return _orderFsm;
   // b.fsm emits audit events under the 'fsm' namespace —
@@ -76,7 +95,7 @@ function _getOrderFsm() {
       refunded:   {},
       cancelled:  {},
     },
-    transitions: ORDER_TRANSITIONS.map(function (t) {
+    transitions: ORDER_TRANSITIONS.concat(PICKUP_TRANSITIONS).map(function (t) {
       return { from: t.from, to: t.to, on: t.on };
     }),
   });
@@ -217,6 +236,28 @@ function create(opts) {
   // settlement failures still surface to the audit sink (b.audit.safeEmit
   // below), just not the durable error feed.
   var errorLog = opts.errorLog || null;
+  // Optional gift-card handle — when present, the order FSM credits a
+  // gift-card spend back when the order dies without completing. A checkout
+  // that partially covers payment with a gift card debits the card's balance
+  // at confirm; if the order is then cancelled (the stale-pending reaper, an
+  // explicit cancel) or refunded (a payment-failed / refund webhook), that
+  // debit must return to the card or the customer's balance is silently
+  // burned. This mirrors the inventory-hold release: it's transition-driven
+  // on the same cancel / refund edges, runs synchronously before the
+  // fire-and-forget fan-outs, and is idempotent (reverseRedemption claims
+  // each redemption with an unreversed predicate) so a re-delivered webhook
+  // can't double-credit. Opt-in like the other handles; absent it, an
+  // unwired deploy (or a test with no gift cards) runs unchanged.
+  var giftCards = opts.giftCards || null;
+  if (giftCards && typeof giftCards.reverseRedemption !== "function") {
+    throw new TypeError("order.create: opts.giftCards must expose a reverseRedemption(order_id) method");
+  }
+  // Optional gift-card ledger handle — when present alongside giftCards, a
+  // reversal also writes a refund_to_giftcard credit so the append-only
+  // ledger history records the money returning to the card (the card row's
+  // balance is authoritative; the ledger is the audit trail surfaced in the
+  // admin console).
+  var giftCardLedger = opts.giftCardLedger || 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
@@ -273,6 +314,60 @@ function create(opts) {
     }
   }
 
+  // Credit back any gift-card spend on an order that died without
+  // completing — the cancel / refund edge releasing the customer's money,
+  // mirroring how _settleSku releases an inventory hold. reverseRedemption
+  // is idempotent (each redemption claimed with an unreversed predicate), so
+  // a re-delivered webhook or the reaper racing the cancel can't double-
+  // credit. For each restored redemption a refund_to_giftcard ledger credit
+  // is written when the ledger is wired so the audit trail records the money
+  // returning.
+  //
+  // drop-silent-with-capture — same discipline as _settleSku: the cancel /
+  // refund has already persisted and the webhook driving it MUST return 2xx,
+  // 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) {
+    if (!giftCards) return;
+    try {
+      var reversed = await giftCards.reverseRedemption(orderId);
+      if (giftCardLedger && typeof giftCardLedger.credit === "function") {
+        for (var i = 0; i < reversed.length; i += 1) {
+          var rev = reversed[i];
+          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({
+              gift_card_id: rev.gift_card_id,
+              amount_minor: rev.amount_minor,
+              source:       "refund_to_giftcard",
+              source_ref:   orderId,
+            });
+          } catch (_ledgerErr) { /* drop-silent — the card-row balance restore above is authoritative; the ledger credit is the audit trail */ }
+        }
+      }
+    } catch (e) {
+      var message = "order.giftcard-reversal failed — order=" + orderId + ": " + (e && e.message || e);
+      try {
+        b.audit.safeEmit({
+          action:   "order.giftcard.reversal.error",
+          outcome:  "failure",
+          metadata: { order_id: orderId, message: (e && e.message) || String(e) },
+        });
+      } catch (_auditErr) { /* drop-silent — the capture below is the durable record */ }
+      if (errorLog && typeof errorLog.captureServerError === "function") {
+        try {
+          await errorLog.captureServerError({
+            route:   "/order/" + orderId + "/giftcard-reversal",
+            method:  "POST",
+            status:  500,
+            message: message,
+          });
+        } catch (_logErr) { /* drop-silent — never let the error-feed write mask the original failure */ }
+      }
+    }
+  }
+
   return {
     TERMINAL_STATES: TERMINAL_STATES,
 
@@ -477,6 +572,21 @@ function create(opts) {
           }
         }
       }
+      // Gift-card settlement — SYNCHRONOUS, alongside the inventory release.
+      // An order that reaches a terminal state WITHOUT completing the sale
+      // (cancelled — pending-abandon or post-paid; refunded — payment failed
+      // or a refund issued) must return any gift-card spend to the card.
+      // Unlike inventory (where a refund deliberately doesn't auto-restock a
+      // physical good), the gift-card credit is the customer's own money, so
+      // it's released on every death edge. reverseRedemption is idempotent,
+      // so a re-delivered webhook or the reaper racing a cancel credits back
+      // exactly once. Drop-silent-with-capture (see _settleGiftCards): the
+      // transition has already persisted and the webhook must return 2xx, so
+      // a reversal failure surfaces loudly for reconciliation rather than
+      // 500ing the request.
+      if (result.to === "cancelled" || result.to === "refunded") {
+        await _settleGiftCards(orderId);
+      }
       // Fan-out to merchant webhook subscribers is fire-and-forget. The
       // transition has already persisted; the request must not wait on
       // outbound HTTP, or a slow / unreachable endpoint would block the

package/lib/returns.js

@@ -376,21 +376,61 @@ function create(opts) {
       var refundedAt    = _epochOrNull(input.refunded_at, "refunded_at");
       var operatorNotes = _boundedString(input.operator_notes, "operator_notes", MAX_NOTE_LEN);
 
-      var current = await this._currentStatus(rmaId);
-      _assertTransition(current, "refund");
-
       var ts = _now();
       var rfAt = refundedAt == null ? ts : refundedAt;
-      await query(
+      // Atomic claim: the `AND status = 'received'` predicate is the
+      // serialization point. Two concurrent refund POSTs (an operator
+      // double-click, two operators on the same RMA) both read 'received'
+      // up the stack, but on D1 a single UPDATE is atomic — exactly one
+      // matches the row and writes 'refunded'; the loser matches zero rows
+      // and is refused. Without this the read-then-write let both pass and
+      // both moved the RMA to refunded (and, on the provider-backed path,
+      // both issued a refund). A zero-row result distinguishes "already
+      // refunded / not received" — surfaced as RMA_TRANSITION_REFUSED so
+      // the request layer maps it to 409, the same shape the prior
+      // _assertTransition refusal produced.
+      var upd = await query(
         "UPDATE return_authorizations SET status = 'refunded', " +
         "refunded_at = ?1, " +
         "operator_notes = CASE WHEN ?2 = '' THEN operator_notes ELSE ?2 END, " +
-        "updated_at = ?3 WHERE id = ?4",
+        "updated_at = ?3 WHERE id = ?4 AND status = 'received'",
         [rfAt, operatorNotes, ts, rmaId],
       );
+      if (Number(upd.rowCount || 0) === 0) {
+        // Either the RMA doesn't exist or it isn't in 'received'. Read the
+        // current status to surface the right typed refusal (RMA_NOT_FOUND
+        // vs RMA_TRANSITION_REFUSED) so the caller's mapping is unchanged.
+        var current = await this._currentStatus(rmaId);
+        _assertTransition(current, "refund");
+        // _assertTransition throws for any non-'received' state; reaching
+        // here means the RMA was 'received' a moment ago but a concurrent
+        // claim won the row first. Refuse with the transition-refused shape.
+        var raced = new Error("returns: refund already claimed for rma " + rmaId);
+        raced.code = "RMA_TRANSITION_REFUSED";
+        throw raced;
+      }
       return await this.get(rmaId);
     },
 
+    // Revert a refund claim back to 'received'. The provider-backed refund
+    // flow claims the RMA (refund() above) BEFORE moving money so a
+    // concurrent racer is locked out; if the provider call then fails, the
+    // caller releases the claim so a retry can run. Atomic + self-targeting:
+    // the `AND status = 'refunded'` predicate makes a double-release (or a
+    // release of an RMA a webhook already advanced) a no-op, never an
+    // underflow. Returns true when the claim was released, false when there
+    // was nothing to release.
+    releaseRefundClaim: async function (rmaId) {
+      _uuid(rmaId, "rma id");
+      var ts = _now();
+      var upd = await query(
+        "UPDATE return_authorizations SET status = 'received', refunded_at = NULL, " +
+        "updated_at = ?1 WHERE id = ?2 AND status = 'refunded'",
+        [ts, rmaId],
+      );
+      return Number(upd.rowCount || 0) === 1;
+    },
+
     reject: async function (rmaId, input) {
       _uuid(rmaId, "rma id");
       if (!input || typeof input !== "object") {

package/lib/storefront.js

@@ -13999,6 +13999,16 @@ function mount(router, deps) {
         // fat-fingered value re-prompts rather than 500-ing checkout.
         var code = (e && typeof e.code === "string") ? e.code : "";
         var msg = (e && e.message) || "checkout failed";
+        // Lost the single-charge claim: another POST for this cart (a double-
+        // click / second tab) is already converting it. The winner created
+        // (or is creating) the one order; bounce this loser to the cart so it
+        // can't start a second checkout. The winner's redirect carries the
+        // shopper to /pay or /orders — this branch just refuses the duplicate.
+        if (code === "CHECKOUT_IN_PROGRESS") {
+          res.status(303);
+          res.setHeader && res.setHeader("location", "/cart");
+          return res.end ? res.end() : res.send("");
+        }
         // A coded gift-card / loyalty / out-of-stock error is something the
         // shopper can fix in place — re-render the checkout form with the
         // message inline (preserving the cart + their prefilled fields where
@@ -17968,6 +17978,18 @@ function mount(router, deps) {
         var auth = _returnsAuth(req, res); if (!auth) return;
         var order = await _ownedOrder(req, res, auth); if (!order) return;
         var cartCount = await _cartCountForReq(req);
+        // An ineligible order (unpaid, cancelled, or already refunded) never
+        // gets the open-return form — the same window the return button is
+        // gated on. Without this the form renders on, say, a refunded order
+        // and the POST below would mint an RMA the operator could then refund
+        // a SECOND time through the provider.
+        if (!_orderEligibleForReturn(order.status)) {
+          return _send(res, 400, renderReturnForm({
+            order: order, lines: order.lines || [],
+            notice: "This order isn't eligible for a return.",
+            shop_name: shopName, cart_count: cartCount,
+          }));
+        }
         _send(res, 200, renderReturnForm({ order: order, lines: order.lines || [], shop_name: shopName, cart_count: cartCount }));
       });
 
@@ -17976,6 +17998,21 @@ function mount(router, deps) {
         var order = await _ownedOrder(req, res, auth); if (!order) return;
         var body = req.body || {};
         var cartCount = await _cartCountForReq(req);
+        // Server-side eligibility gate — the load-bearing check. A return is
+        // only openable while the goods are in the customer's hands and paid
+        // for (paid / fulfilling / shipped / delivered); an unpaid pending
+        // order, a cancelled one, or an already-refunded one is refused. The
+        // form/button gate on the same predicate, but a forged direct POST —
+        // or an order that changed state between the GET and this POST — must
+        // not slip an RMA onto an ineligible order (which would enable a
+        // second provider refund downstream).
+        if (!_orderEligibleForReturn(order.status)) {
+          return _send(res, 400, renderReturnForm({
+            order: order, lines: order.lines || [],
+            notice: "This order isn't eligible for a return.",
+            shop_name: shopName, cart_count: cartCount,
+          }));
+        }
         // Build the return lines from the order's own lines (authoritative
         // sku/qty), keyed by the checkboxes the customer ticked — never
         // trust a client-supplied sku.

package/lib/webhooks.js

@@ -214,27 +214,59 @@ function create(opts) {
     return await _attempt(deliveryId, endpointRow, eventType, payloadJson);
   }
 
+  // The marker a refusal row carries in `last_error`. Rows bearing it are
+  // EXCLUDED from the rate-limit count — a refusal is the gate's own
+  // output, not a real delivery, so counting it would let the gate
+  // perpetuate its own throttle: once tripped, the refusal rows alone keep
+  // the window "full" and every subsequent send is refused forever even
+  // after the real deliveries age out.
+  var RATE_LIMITED_MARKER = "rate-limited";
+
   async function _checkRateLimit(endpointRow) {
     var limit = endpointRow.rate_limit_per_minute;
     if (typeof limit !== "number" || !isFinite(limit) || limit <= 0) return true;
     var windowStart = nowFn() - RATE_WINDOW_MS;
     var r = await query(
-      "SELECT count(*) AS n FROM webhook_deliveries WHERE endpoint_id = ?1 AND created_at > ?2",
-      [endpointRow.id, windowStart],
+      "SELECT count(*) AS n FROM webhook_deliveries " +
+      "WHERE endpoint_id = ?1 AND created_at > ?2 " +
+      "AND (last_error IS NULL OR last_error != ?3)",
+      [endpointRow.id, windowStart, RATE_LIMITED_MARKER],
     );
     var n = (r.rows[0] && (r.rows[0].n != null ? r.rows[0].n : r.rows[0]["count(*)"])) || 0;
     return n < limit;
   }
 
+  // Surface a single refusal row per endpoint per window so the operator
+  // sees the throttle in the admin feed — but DON'T grow the table by one
+  // row per suppressed attempt. A flood of suppressed events against a
+  // wedged receiver would otherwise write unbounded refusal rows. When a
+  // recent refusal row already exists for this endpoint, refresh its
+  // last_attempted_at (collapse) instead of inserting another.
   async function _persistRateLimited(endpointRow, eventType, payloadJson) {
-    var deliveryId = b.uuid.v7();
     var ts = nowFn();
+    var windowStart = ts - RATE_WINDOW_MS;
+    var existing = await query(
+      "SELECT id FROM webhook_deliveries " +
+      "WHERE endpoint_id = ?1 AND last_error = ?2 AND created_at > ?3 " +
+      "ORDER BY created_at DESC LIMIT 1",
+      [endpointRow.id, RATE_LIMITED_MARKER, windowStart],
+    );
+    if (existing.rows[0]) {
+      var existingId = existing.rows[0].id;
+      await query(
+        "UPDATE webhook_deliveries SET last_attempted_at = ?1, event_type = ?2, payload_json = ?3 " +
+        "WHERE id = ?4",
+        [ts, eventType, payloadJson, existingId],
+      );
+      return await _getDelivery(existingId);
+    }
+    var deliveryId = b.uuid.v7();
     await query(
       "INSERT INTO webhook_deliveries " +
       "(id, endpoint_id, event_type, payload_json, attempts, last_status, last_error, " +
       " last_attempted_at, created_at) " +
       "VALUES (?1, ?2, ?3, ?4, 0, NULL, ?5, ?6, ?7)",
-      [deliveryId, endpointRow.id, eventType, payloadJson, "rate-limited", ts, ts],
+      [deliveryId, endpointRow.id, eventType, payloadJson, RATE_LIMITED_MARKER, ts, ts],
     );
     return await _getDelivery(deliveryId);
   }
@@ -311,6 +343,13 @@ function create(opts) {
     // per-endpoint feed still surfaces the failure. The DLQ row
     // carries the full payload so replayFromDlq can re-queue
     // without consulting the original delivery.
+    //
+    // Idempotent per delivery: the INSERT...SELECT writes only when no
+    // dead-letter row already exists for this delivery_id. Without it, a
+    // manual retry of an already-exhausted delivery dropped a duplicate
+    // DLQ row on every click. The migration 0215 UNIQUE(delivery_id) is
+    // the schema backstop; this guard avoids relying on a swallowed
+    // constraint error.
     var dlqId = b.uuid.v7();
     var firstAttemptedAt;
     var r = await query(
@@ -322,7 +361,8 @@ function create(opts) {
       "INSERT INTO webhook_dlq " +
       "(id, endpoint_id, delivery_id, event_type, payload_json, attempts, " +
       " last_status, last_error, first_attempted_at, last_attempted_at, dropped_at) " +
-      "VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?9, ?10, ?11)",
+      "SELECT ?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?9, ?10, ?11 " +
+      "WHERE NOT EXISTS (SELECT 1 FROM webhook_dlq WHERE delivery_id = ?3)",
       [dlqId, endpointRow.id, deliveryId, eventType, payloadJson, attempts,
        lastStatus, lastError, firstAttemptedAt, ts, ts],
     );
@@ -443,6 +483,16 @@ function create(opts) {
         _uuid(deliveryId, "delivery id");
         var d = await _getDelivery(deliveryId);
         if (!d) return null;
+        // An exhausted delivery (attempts at/over the max) has already
+        // moved to the DLQ — re-attempting it would push attempts past the
+        // max and drop a DUPLICATE DLQ row on every click. Answer a no-op
+        // (return the row unchanged) so the operator UI shows the existing
+        // state; re-queuing an exhausted delivery is `replayFromDlq`, not
+        // `retry`. A successfully-delivered row is likewise a no-op.
+        var attempts = Number(d.attempts || 0);
+        if (attempts >= MAX_ATTEMPTS || d.delivered_at != null) {
+          return d;
+        }
         var endpoint = await _getEndpoint(d.endpoint_id);
         if (!endpoint) return null;
         return await _attempt(deliveryId, endpoint, d.event_type, d.payload_json);