@blamejs/blamejs-shop 0.4.81 → 0.4.82

package/CHANGELOG.md

@@ -8,6 +8,8 @@ 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.

package/lib/asset-manifest.json

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

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);
     },
 

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.81",
+  "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": {