@blamejs/blamejs-shop 0.4.80 → 0.4.82

package/CHANGELOG.md

@@ -8,6 +8,10 @@ upgrading across more than a few patches at a time.
 
 ## v0.4.x
 
+- v0.4.82 (2026-06-22) — **Return-authorization and shipping-label state transitions are exactly-once under concurrency.** Two fulfillment surfaces gain the atomic-claim discipline the refund path already uses. Approving, receiving, and rejecting a return authorization now gate the transition on the observed status inside the UPDATE, so two operators (or a double-clicked action) acting on the same return can no longer both apply — exactly one transition wins and the other is refused, instead of a read-then-write letting both pass last-write-wins. Likewise, recording a shipping label as purchased, voided, or used is now a single guarded claim, so two concurrent broker callbacks for the same label can't both record (which previously left conflicting tracking numbers and costs last-write-wins). The losing caller gets the same transition-refused error a sequential illegal transition already produced. No configuration changes; upgrade to pick them up. **Fixed:** *Return-authorization transitions are atomic claims* — returns approve, markReceived, and reject now fold the expected source status into the UPDATE (approve from pending, markReceived from approved, reject from pending or approved) and treat the row count as the claim signal, matching the refund path. Two concurrent transitions on the same return — two operators, or a double-submit — can no longer both write last-write-wins; exactly one wins and the loser is refused with the same transition-refused error, mapped to a 409. Sequential not-found and illegal-transition errors are unchanged. · *Shipping-label transitions are atomic claims* — shipping-labels markPurchased, voidLabel, and markUsed now gate on the observed status inside the UPDATE. Two concurrent broker callbacks marking the same pending label purchased (a worker-drain double-fire) can no longer both record, leaving conflicting tracking numbers and costs by last-write-wins — exactly one records and the other is refused. The void 30-day window and not-found / wrong-status refusals are unchanged.
+
+- v0.4.81 (2026-06-22) — **Notification transitions are atomic, a missing insurance policy no longer crashes claim approval, and a returns summary no longer zeroes its refund totals under a status filter.** Three correctness fixes on the fulfillment surface. Notification status transitions (mark-sent / mark-failed / mark-read) are now single atomic claims that fold the expected status into the write, so two concurrent delivery callbacks can't both stamp the row last-write-wins, a mark-failed can't clobber a mark-sent, and two concurrent mark-failed calls each count once (the retry counter is incremented in the database rather than read-then-written). Approving a shipping-insurance claim whose parent policy row is missing now returns a clear typed error instead of dereferencing null and throwing an opaque crash. And the operator returns summary builds its refund-value totals from a status-free base filter, so supplying a status filter (e.g. to view rejected returns) no longer collapses the refunded and pending payout totals to zero through a self-contradictory query. No configuration changes; upgrade to pick them up. **Fixed:** *Notification status transitions are atomic claims* — mark-sent, mark-failed, and mark-read now gate the transition on the observed status inside the UPDATE and treat the row count as the claim signal, instead of checking status in a prior read and writing unconditionally. Concurrent delivery callbacks therefore can't both transition one notification last-write-wins, a mark-failed can't overwrite a mark-sent, and the retry counter is incremented in the database (count + 1) so two simultaneous failures can't lose an increment. mark-sent now applies only to a pending notification: a failed delivery is a durable failure record (the scheduler only re-dispatches pending notifications), so a stale or duplicate success callback can no longer flip a failed notification to sent and clear its error — retrying a failed notification is an explicit re-queue. · *Approving an insurance claim with a missing parent policy fails cleanly* — shipping-insurance claim approval now refuses with a typed not-found error when the claim's parent insurance row can't be loaded, matching the null-guard the rest of the module already applies, instead of dereferencing a null row while computing the payout ceiling. · *A returns summary keeps its refund totals when a status filter is applied* — The operator returns summary computes its refunded and pending payout totals from a base filter scoped only to the date window, so they pin their own status independently of the caller's status filter. Previously, supplying a status filter grafted a second, conflicting status predicate onto the payout queries (for example status = 'rejected' AND status = 'refunded'), silently zeroing both rollups; the per-status counts were always correct and remain so.
+
 - v0.4.80 (2026-06-21) — **Recording an affiliate commission is idempotent under concurrency.** Recording an affiliate commission for an order now converges instead of failing when two attribution hooks fire for the same order at once. The recorder already returned the existing commission on a sequential repeat; under concurrency, both callers passed that pre-read and the second insert hit the (order_id, affiliate_id) uniqueness constraint and threw an unhandled error. The losing writer now catches the constraint violation and returns the committed row, so exactly one commission is recorded and both callers get it. No configuration changes; upgrade to pick it up. **Fixed:** *Concurrent affiliate-commission recording converges on one row* — recordCommissionEvent wraps its insert so that when a concurrent call for the same (order_id, affiliate_id) wins the race, the losing writer catches the uniqueness violation and returns the already-committed commission rather than throwing. The sequential idempotent behaviour is unchanged; this closes the gap where two simultaneous attribution events for one order surfaced an unhandled error instead of a single recorded commission.
 
 - v0.4.79 (2026-06-21) — **Reversing a receipt no longer mints phantom stock, and restock recommendations accept lowercase location codes.** Two inventory correctness fixes. Reversing an applied goods-receipt now rolls back exactly the quantity the reversal removed: when a SKU had already been decremented elsewhere to below the received quantity, the reversal's forward step removes only what's on hand, and a mid-reversal failure now compensates by that exact amount instead of adding back the full received quantity — which previously minted phantom stock. Separately, restock recommendations now accept lowercase and dotted location codes, matching the location-code format the rest of the inventory surface already accepts; a stricter uppercase-only pattern had been rejecting valid codes. No configuration changes; upgrade to pick them up. **Fixed:** *Reversing a goods-receipt rolls back the exact quantity removed* — Receipt reversal now records how many units each line's decrement actually removed (floored at the quantity on hand) and, if a later line in the same reversal fails, compensates the already-decremented lines by that exact amount. Previously the forward decrement clamped at zero while the compensation added back the full received quantity, so reversing a receipt for a SKU that had since been drawn down below the received amount could leave more stock on hand than before the reversal. · *Restock recommendations accept lowercase and dotted location codes* — smart-restocking now validates location codes against the same pattern the inventory-locations primitive uses (mixed case, with dot/underscore/hyphen), so a recommendation request for a location like "aisle-3.bin-2" is accepted. A divergent uppercase-only pattern had been rejecting valid location codes that every other inventory operation accepts.

package/lib/asset-manifest.json

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

package/lib/notifications.js

@@ -241,18 +241,29 @@ function create(opts) {
       _uuid(id, "notification id");
       options = options || {};
       var sentAt = options.sent_at == null ? _now() : _scheduledAt(options.sent_at, _now());
-      var existing = (await query("SELECT status FROM notifications WHERE id = ?1", [id])).rows[0];
-      if (!existing) return null;
-      if (existing.status !== "pending" && existing.status !== "failed") {
-        var err = new Error("notifications.markSent: cannot transition from " + existing.status + " to sent");
-        err.code = "NOTIFICATION_BAD_TRANSITION";
-        throw err;
-      }
-      await query(
-        "UPDATE notifications SET status = 'sent', sent_at = ?1, last_error = NULL, updated_at = ?1 WHERE id = ?2",
+      // Atomic claim, pending → sent ONLY. Folding the status into the UPDATE
+      // makes the transition a single serialized claim (no read-then-write
+      // last-write-wins). Crucially the claim does NOT match a 'failed' row: a
+      // delivery that failed is a durable failure record (the scheduler only
+      // re-dispatches 'pending', so retrying means an explicit re-queue), and
+      // accepting 'failed' here let a stale or duplicate success callback flip
+      // a failed notification to sent and clear its last_error — silently
+      // masking the failure. rowCount is the claim signal.
+      var upd = await query(
+        "UPDATE notifications SET status = 'sent', sent_at = ?1, last_error = NULL, updated_at = ?1 " +
+        "WHERE id = ?2 AND status = 'pending'",
         [sentAt, id],
       );
-      return (await query("SELECT * FROM notifications WHERE id = ?1", [id])).rows[0];
+      if (Number(upd.rowCount || 0) === 1) {
+        return (await query("SELECT * FROM notifications WHERE id = ?1", [id])).rows[0];
+      }
+      // Lost the claim: the row is gone or already left pending/failed. Report
+      // exactly as the prior JS guard did.
+      var row = (await query("SELECT status FROM notifications WHERE id = ?1", [id])).rows[0];
+      if (!row) return null;
+      var err = new Error("notifications.markSent: cannot transition from " + row.status + " to sent");
+      err.code = "NOTIFICATION_BAD_TRANSITION";
+      throw err;
     },
 
     markFailed: async function (id, options) {
@@ -266,26 +277,42 @@ function create(opts) {
       if (!Number.isInteger(increment) || increment < 0) {
         throw new TypeError("notifications.markFailed: retry_count_increment must be a non-negative integer");
       }
-      var existing = (await query("SELECT status, retry_count FROM notifications WHERE id = ?1", [id])).rows[0];
-      if (!existing) return null;
-      if (existing.status !== "pending" && existing.status !== "failed") {
-        var err = new Error("notifications.markFailed: cannot transition from " + existing.status + " to failed");
-        err.code = "NOTIFICATION_BAD_TRANSITION";
-        throw err;
-      }
-      var newCount = Number(existing.retry_count) + increment;
       var ts = _now();
-      await query(
-        "UPDATE notifications SET status = 'failed', retry_count = ?1, last_error = ?2, updated_at = ?3 WHERE id = ?4",
-        [newCount, errMsg, ts, id],
+      // Atomic claim with an in-SQL increment: the retry_count bump is computed
+      // in the UPDATE (retry_count + ?) and gated on the observed status, so two
+      // concurrent markFailed calls can't read the same retry_count and lose an
+      // increment, and a markFailed can't clobber a markSent. rowCount is the
+      // claim signal.
+      var upd = await query(
+        "UPDATE notifications SET status = 'failed', retry_count = retry_count + ?1, last_error = ?2, updated_at = ?3 " +
+        "WHERE id = ?4 AND status IN ('pending', 'failed')",
+        [increment, errMsg, ts, id],
       );
-      return (await query("SELECT * FROM notifications WHERE id = ?1", [id])).rows[0];
+      if (Number(upd.rowCount || 0) === 1) {
+        return (await query("SELECT * FROM notifications WHERE id = ?1", [id])).rows[0];
+      }
+      var row = (await query("SELECT status FROM notifications WHERE id = ?1", [id])).rows[0];
+      if (!row) return null;
+      var err = new Error("notifications.markFailed: cannot transition from " + row.status + " to failed");
+      err.code = "NOTIFICATION_BAD_TRANSITION";
+      throw err;
     },
 
     markRead: async function (id, options) {
       _uuid(id, "notification id");
       options = options || {};
       var readAt = options.read_at == null ? _now() : _scheduledAt(options.read_at, _now());
+      // Atomic claim: fold the in-app channel + observed-status predicate into
+      // the UPDATE so the read transition is a single serialized claim. rowCount
+      // is the claim signal; the loser re-reads to report the precise reason.
+      var upd = await query(
+        "UPDATE notifications SET status = 'read', read_at = ?1, updated_at = ?1 " +
+        "WHERE id = ?2 AND channel = 'in-app' AND status IN ('sent', 'pending')",
+        [readAt, id],
+      );
+      if (Number(upd.rowCount || 0) === 1) {
+        return (await query("SELECT * FROM notifications WHERE id = ?1", [id])).rows[0];
+      }
       var existing = (await query("SELECT status, channel FROM notifications WHERE id = ?1", [id])).rows[0];
       if (!existing) return null;
       if (existing.channel !== "in-app") {
@@ -293,16 +320,9 @@ function create(opts) {
         err.code = "NOTIFICATION_BAD_CHANNEL";
         throw err;
       }
-      if (existing.status !== "sent" && existing.status !== "pending") {
-        var err2 = new Error("notifications.markRead: cannot transition from " + existing.status + " to read");
-        err2.code = "NOTIFICATION_BAD_TRANSITION";
-        throw err2;
-      }
-      await query(
-        "UPDATE notifications SET status = 'read', read_at = ?1, updated_at = ?1 WHERE id = ?2",
-        [readAt, id],
-      );
-      return (await query("SELECT * FROM notifications WHERE id = ?1", [id])).rows[0];
+      var err2 = new Error("notifications.markRead: cannot transition from " + existing.status + " to read");
+      err2.code = "NOTIFICATION_BAD_TRANSITION";
+      throw err2;
     },
 
     dismiss: async function (id) {

package/lib/returns.js

@@ -335,17 +335,26 @@ function create(opts) {
       var refundCurrency = input.refund_currency == null ? "USD" : _currency(input.refund_currency);
       var operatorNotes  = _boundedString(input.operator_notes, "operator_notes", MAX_NOTE_LEN);
 
-      var current = await this._currentStatus(rmaId);
-      _assertTransition(current, "approve");
-
       var ts = _now();
-      await query(
+      // Atomic claim — `AND status = 'pending'` is the serialization point, so
+      // two concurrent approve/reject POSTs on the same RMA can't both write
+      // (the prior read-then-write let both pass). A zero-row result means the
+      // RMA isn't pending: the read below surfaces RMA_NOT_FOUND vs
+      // RMA_TRANSITION_REFUSED so the request layer's 404/409 mapping holds.
+      var upd = await query(
         "UPDATE return_authorizations SET status = 'approved', " +
         "refund_amount_minor = ?1, refund_currency = ?2, approved_at = ?3, " +
         "operator_notes = CASE WHEN ?4 = '' THEN operator_notes ELSE ?4 END, " +
-        "updated_at = ?3 WHERE id = ?5",
+        "updated_at = ?3 WHERE id = ?5 AND status = 'pending'",
         [input.refund_amount_minor, refundCurrency, ts, operatorNotes, rmaId],
       );
+      if (Number(upd.rowCount || 0) === 0) {
+        var current = await this._currentStatus(rmaId);
+        _assertTransition(current, "approve");
+        var raced = new Error("returns: approve already claimed for rma " + rmaId);
+        raced.code = "RMA_TRANSITION_REFUSED";
+        throw raced;
+      }
       return await this.get(rmaId);
     },
 
@@ -355,18 +364,25 @@ function create(opts) {
       var receivedAt    = _epochOrNull(input.received_at, "received_at");
       var operatorNotes = _boundedString(input.operator_notes, "operator_notes", MAX_NOTE_LEN);
 
-      var current = await this._currentStatus(rmaId);
-      _assertTransition(current, "markReceived");
-
       var ts = _now();
       var rxAt = receivedAt == null ? ts : receivedAt;
-      await query(
+      // Atomic claim — `AND status = 'approved'` serializes the transition so a
+      // concurrent markReceived/reject can't both write. Zero rows → re-read to
+      // surface RMA_NOT_FOUND vs RMA_TRANSITION_REFUSED unchanged.
+      var upd = await query(
         "UPDATE return_authorizations SET status = 'received', " +
         "received_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 = 'approved'",
         [rxAt, operatorNotes, ts, rmaId],
       );
+      if (Number(upd.rowCount || 0) === 0) {
+        var current = await this._currentStatus(rmaId);
+        _assertTransition(current, "markReceived");
+        var raced = new Error("returns: markReceived already claimed for rma " + rmaId);
+        raced.code = "RMA_TRANSITION_REFUSED";
+        throw raced;
+      }
       return await this.get(rmaId);
     },
 
@@ -442,17 +458,26 @@ function create(opts) {
       var rejectedReason = _boundedString(input.rejected_reason, "rejected_reason", MAX_DETAIL_LEN);
       var operatorNotes  = _boundedString(input.operator_notes,  "operator_notes",  MAX_NOTE_LEN);
 
-      var current = await this._currentStatus(rmaId);
-      _assertTransition(current, "reject");
-
       var ts = _now();
-      await query(
+      // Atomic claim — reject is legal from 'pending' OR 'approved', so the
+      // predicate is `AND status IN ('pending','approved')`; it serializes
+      // against a concurrent approve/markReceived/reject so they can't both
+      // write. Zero rows → re-read to surface RMA_NOT_FOUND vs
+      // RMA_TRANSITION_REFUSED unchanged.
+      var upd = await query(
         "UPDATE return_authorizations SET status = 'rejected', " +
         "rejected_at = ?1, rejected_reason = ?2, " +
         "operator_notes = CASE WHEN ?3 = '' THEN operator_notes ELSE ?3 END, " +
-        "updated_at = ?1 WHERE id = ?4",
+        "updated_at = ?1 WHERE id = ?4 AND status IN ('pending', 'approved')",
         [ts, rejectedReason, operatorNotes, rmaId],
       );
+      if (Number(upd.rowCount || 0) === 0) {
+        var current = await this._currentStatus(rmaId);
+        _assertTransition(current, "reject");
+        var raced = new Error("returns: reject already claimed for rma " + rmaId);
+        raced.code = "RMA_TRANSITION_REFUSED";
+        throw raced;
+      }
       return await this.get(rmaId);
     },
 
@@ -651,17 +676,30 @@ function create(opts) {
       // operator sees committed-payout vs pending-payout. Currency
       // mix is reported per-bucket so a multi-currency shop doesn't
       // collapse to a meaningless single number.
+      //
+      // These rollups pin their OWN status ('refunded' / approved+received), so
+      // they must build off a status-free base WHERE (from/to only). Grafting
+      // onto the caller-filtered whereSql produced a contradictory predicate
+      // (e.g. `status = 'pending' AND status = 'refunded'`) that silently
+      // summed to zero whenever an explicit status filter was supplied.
+      var valueWhere = [];
+      var valueParams = [];
+      var vidx = 1;
+      if (from != null) { valueWhere.push("created_at >= ?" + vidx); valueParams.push(from); vidx += 1; }
+      if (to   != null) { valueWhere.push("created_at <  ?" + vidx); valueParams.push(to);   vidx += 1; }
+      var valueWhereSql = valueWhere.length ? (" WHERE " + valueWhere.join(" AND ")) : "";
+
       var refundedRows = (await query(
         "SELECT refund_currency, SUM(refund_amount_minor) AS total FROM return_authorizations" +
-        (whereSql ? whereSql + " AND status = 'refunded'" : " WHERE status = 'refunded'") +
+        valueWhereSql + (valueWhereSql ? " AND " : " WHERE ") + "status = 'refunded'" +
         " GROUP BY refund_currency",
-        params,
+        valueParams,
       )).rows;
       var pendingRows = (await query(
         "SELECT refund_currency, SUM(refund_amount_minor) AS total FROM return_authorizations" +
-        (whereSql ? whereSql + " AND status IN ('approved','received')" : " WHERE status IN ('approved','received')") +
+        valueWhereSql + (valueWhereSql ? " AND " : " WHERE ") + "status IN ('approved','received')" +
         " GROUP BY refund_currency",
-        params,
+        valueParams,
       )).rows;
 
       function _byCurrency(rows) {

package/lib/shipping-insurance.js

@@ -597,6 +597,10 @@ function create(opts) {
         " is " + claim.status + ", only filed claims can move to approved");
     }
     var ins = await _getInsuranceRow(claim.insurance_id);
+    if (!ins) {
+      throw new TypeError("shippingInsurance.markClaimApproved: parent insurance " +
+        claim.insurance_id + " not found for claim " + claimId);
+    }
     if (input.payout_minor > Number(ins.declared_value_minor)) {
       throw new TypeError("shippingInsurance.markClaimApproved: payout_minor " +
         input.payout_minor + " exceeds declared_value_minor " +

package/lib/shipping-labels.js

@@ -373,12 +373,22 @@ function create(opts) {
       }
 
       var ts = _now();
-      await query(
+      // Atomic claim — `AND status = 'pending'` serializes the transition so
+      // two concurrent broker callbacks (worker-drain double-fire) can't both
+      // record, last-write-wins, conflicting tracking/cost. The JS check above
+      // gives the clean sequential not-found / wrong-status refusal; this
+      // rowCount guard catches the concurrent racer.
+      var upd = await query(
         "UPDATE shipping_labels SET status = 'purchased', tracking_number = ?1, " +
         "label_url = ?2, cost_minor = ?3, currency = ?4, purchased_via = ?5, " +
-        "purchased_at = ?6 WHERE id = ?7",
+        "purchased_at = ?6 WHERE id = ?7 AND status = 'pending'",
         [tracking, url, input.cost_minor, input.currency, input.purchased_via, ts, input.label_id],
       );
+      if (Number(upd.rowCount || 0) === 0) {
+        var raced = new Error("shipping-labels.markPurchased: refused — label already transitioned (concurrent claim)");
+        raced.code = "SHIPPING_LABELS_TRANSITION_REFUSED";
+        throw raced;
+      }
       return await _getLabelRow(input.label_id);
     },
 
@@ -409,10 +419,18 @@ function create(opts) {
         throw werr;
       }
 
-      await query(
-        "UPDATE shipping_labels SET status = 'voided', void_reason = ?1, voided_at = ?2 WHERE id = ?3",
+      var upd = await query(
+        "UPDATE shipping_labels SET status = 'voided', void_reason = ?1, voided_at = ?2 WHERE id = ?3 AND status = 'purchased'",
         [reason, ts, input.label_id],
       );
+      if (Number(upd.rowCount || 0) === 0) {
+        // Lost the claim to a concurrent void/markUsed — the label already left
+        // 'purchased'. (Sequential not-found / wrong-status / void-window are
+        // refused above.)
+        var raced = new Error("shipping-labels.voidLabel: refused — label already transitioned (concurrent claim)");
+        raced.code = "SHIPPING_LABELS_TRANSITION_REFUSED";
+        throw raced;
+      }
       return await _getLabelRow(input.label_id);
     },
 
@@ -439,10 +457,17 @@ function create(opts) {
         throw err;
       }
       var ts = _now();
-      await query(
-        "UPDATE shipping_labels SET status = 'used', used_at = ?1 WHERE id = ?2",
+      // Atomic claim — `AND status = 'purchased'` serializes against a
+      // concurrent void/markUsed so the parcel can't be both voided and used.
+      var upd = await query(
+        "UPDATE shipping_labels SET status = 'used', used_at = ?1 WHERE id = ?2 AND status = 'purchased'",
         [ts, labelId],
       );
+      if (Number(upd.rowCount || 0) === 0) {
+        var raced = new Error("shipping-labels.markUsed: refused — label already transitioned (concurrent claim)");
+        raced.code = "SHIPPING_LABELS_TRANSITION_REFUSED";
+        throw raced;
+      }
       return await _getLabelRow(labelId);
     },
 

package/package.json

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