@blamejs/blamejs-shop 0.4.67 → 0.4.68

package/CHANGELOG.md

@@ -8,6 +8,8 @@ upgrading across more than a few patches at a time.
 
 ## v0.4.x
 
+- v0.4.68 (2026-06-20) — **Redeeming a loyalty reward no longer burns points on a failed mint or exceeds the per-customer cap under load.** Redeeming a reward for points debited the customer's balance, then checked the per-customer redemption cap with a separate count and minted the reward coupon as separate steps. Two problems followed. The cap was a read-then-act check: two redemptions arriving together both read a count under the cap and both succeeded, so a customer could exceed a lifetime cap (for example mint two of a once-ever coupon). And if the coupon mint failed after the points were debited — the coupons primitive erroring, or a transient fault — the points were gone with no redemption row recorded, so no refund path could return them; the customer was charged for a reward they never received. Redemption now claims the cap slot in a single conditional insert that recomputes the live count, so concurrent redemptions can't both exceed the cap, and it reverses the points debit (and removes the claimed row) if the coupon can't be minted, so a failed redemption always leaves the balance whole. No API change. **Fixed:** *Per-customer redemption cap is enforced atomically* — The redemption row is now inserted only if the customer's live active/consumed count for that reward is still under the cap, recomputed inside the insert. Two redemptions racing the last slot resolve to a single winner; the loser is refused with the same cap error and its points are returned. The cheap pre-check is kept as a fast path but is no longer the thing that enforces the limit. · *A failed coupon mint returns the points and leaves no row* — If the coupon can't be minted after the points were debited and the slot claimed, both are rolled back — the points debit is reversed and the claimed redemption row is removed — so the customer's balance is whole and no redemption is left recorded for a reward that was never issued. The points reversal rides the same idempotent restore the checkout path uses, so a retry credits exactly once.
+
 - v0.4.67 (2026-06-20) — **Subject-access exports now carry the customer's complete record, not just the first page.** A data-subject access export assembled each domain by reading a single page from that domain's reader. A customer with more than one page in any paginated domain — orders, the loyalty points ledger, product reviews, wishlist entries, survey invitations, or support tickets — silently received a truncated export, which is an incomplete response to a GDPR Article 15 request. Each of those domains is now drained to the end by following the reader's own cursor, so the export carries every row. Readers that already return the whole set in one read (addresses, the consent ledger, subscriptions) were already complete and are unchanged. As part of this, the support-ticket reader keyed on customer id (the one the export uses, since it holds no plaintext email) gained cursor pagination so it can be paged to completion. **Changed:** *supportTickets.listByCustomerId and customerSurveys.invitationsForCustomer return { rows, next_cursor }* — Both customer-scoped readers that the export uses now return a paginated envelope — { rows, next_cursor } — instead of a bare array, so a caller can page a customer's full history to the end. listByCustomerId pages on the (opened_at desc, id desc) tuple (matching the email-keyed listForCustomer); invitationsForCustomer pages on the invitation id. If you call either directly, read the rows off the .rows field and pass the previous next_cursor as the cursor option to continue where the last page ended. **Fixed:** *Access exports drain every paginated domain to completion* — The export now follows each reader's cursor to the end for orders, the loyalty points ledger, product reviews, wishlist entries, survey invitations, and support tickets, concatenating every page. A customer with hundreds of orders or ledger entries receives all of them rather than the most recent hundred. A page-count backstop far above any real per-customer record guards against a misbehaving cursor without ever truncating a genuine export.
 
 - v0.4.66 (2026-06-20) — **Inventory-audit finalization can no longer double-apply its stock adjustments.** Finalizing an inventory audit with apply_adjustments writes one shelf adjustment per counted line, then marks the audit finalized. Two failure modes could move a shelf twice. First, if a later line was refused mid-loop — most commonly a negative variance that would have pushed the shelf below its outstanding paid holds — the audit stayed open, but the lines already adjusted had moved; re-running the finalize re-applied those earlier adjustments on top of themselves. Second, two finalize calls overlapping on the same audit both applied every adjustment before either marked the audit finalized. Finalization now claims the audit's transition to finalized in a single conditional write BEFORE touching any shelf, so exactly one finalize applies the adjustments and a concurrent or duplicate call applies nothing. Each adjustment is applied as the difference between the counted variance and what this audit has already moved, so a retry lands only the not-yet-applied remainder and a recount made before the retry is reflected exactly. A finalize that is refused part-way re-opens the audit so the operator can clear the blocker and retry. No API change. **Fixed:** *Finalization claims the audit before moving any shelf* — The transition that marks an audit finalized now lands in one conditional write, gated on the audit still being open or in progress, BEFORE any stock adjustment is written. Two finalize calls racing the same audit — or a duplicate retry overlapping a still-running finalize — resolve to a single winner that applies the adjustments; the loser writes nothing and returns the computed totals. The claim also freezes the audit's scan lines, so the variances being applied can't change underneath the writer. · *Adjustments reconcile against what already landed* — Each shelf adjustment is applied as the counted variance minus what this audit has already moved for that SKU and location. A finalize refused part-way (a respect-holds floor on one line) re-opens the audit; the retry then applies only the remaining difference instead of re-applying lines that already succeeded, and a recount that changed a line's variance before the retry is corrected to the new value rather than left at the old one.

package/lib/asset-manifest.json

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

package/lib/loyalty-redemption.js

@@ -260,8 +260,14 @@ function create(opts) {
   }
 
   var loyalty = opts.loyalty;
-  if (!loyalty || typeof loyalty.redeem !== "function" || typeof loyalty.adjust !== "function") {
-    throw new TypeError("loyaltyRedemption: opts.loyalty handle required (must expose redeem + adjust)");
+  // reverseRedemptionById is REQUIRED, not optional: redeemForCustomer
+  // debits points before claiming the cap slot + minting the coupon, and
+  // reverses that debit if either fails. A handle that can't reverse a
+  // burn would silently strand the points on those failure paths, so the
+  // contract is enforced at wiring time rather than discovered at runtime.
+  if (!loyalty || typeof loyalty.redeem !== "function" || typeof loyalty.adjust !== "function" ||
+      typeof loyalty.reverseRedemptionById !== "function") {
+    throw new TypeError("loyaltyRedemption: opts.loyalty handle required (must expose redeem + adjust + reverseRedemptionById)");
   }
 
   // Optional coupons handle. When wired, expected shape is
@@ -448,6 +454,22 @@ function create(opts) {
     return Number(row.n || row.N || 0);
   }
 
+  // Best-effort reversal of a points debit when a redemption can't be
+  // completed (lost cap claim, or coupon mint failed). loyalty.redeem
+  // returns the burn's tx_id; reverseRedemptionById is idempotent (it
+  // claims `restored_points` 0 -> spent under a guarded UPDATE) and
+  // balance-only, so a double-fire credits exactly once and an unknown /
+  // already-reversed tx is a no-op. Its own failure is swallowed so the
+  // ORIGINAL error (cap / mint) is what surfaces — the reversal is the
+  // recovery, not the reported outcome.
+  async function _reverseBurn(burn) {
+    try {
+      if (burn && burn.tx_id) {
+        await loyalty.reverseRedemptionById(burn.tx_id);
+      }
+    } catch (_e) { /* drop-silent — reversal is best-effort recovery */ }
+  }
+
   async function redeemForCustomer(input) {
     if (!input || typeof input !== "object") {
       throw new TypeError("loyaltyRedemption.redeemForCustomer: input object required");
@@ -465,6 +487,11 @@ function create(opts) {
       throw nope;
     }
 
+    // Fast-fail cap pre-check — cheap, and avoids debiting points only to
+    // reverse them in the common already-capped case. NOT the real guard:
+    // two concurrent redeems both read a count under the cap here, so the
+    // atomic claim below (which recomputes the count inside the INSERT) is
+    // what actually serializes them.
     if (reward.max_per_customer != null) {
       var count = await _countActiveOrConsumedForCustomer(customerId, rewardSlug);
       if (count >= reward.max_per_customer) {
@@ -474,10 +501,12 @@ function create(opts) {
       }
     }
 
-    // Debit points via the composed loyalty primitive. The redeem
-    // call surfaces LOYALTY_INSUFFICIENT_BALANCE on its own when the
-    // customer can't afford the reward; that error propagates as-is.
-    await loyalty.redeem({
+    // Debit points via the composed loyalty primitive. The redeem call
+    // surfaces LOYALTY_INSUFFICIENT_BALANCE on its own when the customer
+    // can't afford the reward; that error propagates as-is (nothing to
+    // compensate — no points moved). Capture the burn so a later failure
+    // can give the points back.
+    var burn = await loyalty.redeem({
       customer_id: customerId,
       points:      reward.point_cost,
       notes:       "redeem:" + rewardSlug,
@@ -489,27 +518,68 @@ function create(opts) {
       ? null
       : ts + (reward.expires_days_after_redemption * MS_PER_DAY);
 
+    // Atomic per-customer cap claim — the serialization point on the D1
+    // bridge (no interactive transactions). Insert the redemption row ONLY
+    // if the live active/consumed count is STILL under the cap, recomputed
+    // inside the INSERT...SELECT so two concurrent redeems can't both land
+    // (the loser changes zero rows). A NULL cap means no limit, so the
+    // guard short-circuits true. coupon_code is filled in after the coupon
+    // is minted below.
+    var claim = await query(
+      "INSERT INTO loyalty_redemptions (id, customer_id, reward_slug, points_debited, coupon_code, " +
+      "status, redeemed_at, consumed_at, expires_at, order_id, cancel_reason) " +
+      "SELECT ?1, ?2, ?3, ?4, NULL, 'active', ?5, NULL, ?6, NULL, NULL " +
+      "WHERE ?7 IS NULL OR (SELECT COUNT(*) FROM loyalty_redemptions " +
+      "WHERE customer_id = ?2 AND reward_slug = ?3 AND status IN ('active','consumed')) < ?7",
+      [redemptionId, customerId, rewardSlug, reward.point_cost, ts, expiresAt, reward.max_per_customer],
+    );
+    if (Number(claim.rowCount || 0) !== 1) {
+      // Lost the cap claim — another redeem filled the last slot between
+      // the pre-check and here. Return the points and refuse, so a raced
+      // caller is never charged for a redemption it didn't get.
+      await _reverseBurn(burn);
+      var capRace = new Error("loyaltyRedemption.redeemForCustomer: customer has reached the per-customer redemption cap");
+      capRace.code = "REDEMPTION_CAP_REACHED";
+      throw capRace;
+    }
+
+    // Mint the reward coupon now that the slot is claimed. If minting fails
+    // (the coupons primitive throws, or returns a malformed code), roll
+    // back BOTH the points debit and the claim row — otherwise the customer
+    // is charged for a reward they never received and the burn is orphaned
+    // (no redemption row for any refund path to key on).
     var couponCode = null;
     if (coupons) {
-      var minted = await coupons.issueSingleUseFromReward({
-        customer_id: customerId,
-        reward_slug: rewardSlug,
-        value_json:  reward.value_json,
-        expires_at:  expiresAt,
-      });
-      if (!minted || typeof minted.code !== "string" || !minted.code.length) {
-        throw new TypeError("loyaltyRedemption.redeemForCustomer: coupons.issueSingleUseFromReward must return { code: string }");
+      try {
+        var minted = await coupons.issueSingleUseFromReward({
+          customer_id: customerId,
+          reward_slug: rewardSlug,
+          value_json:  reward.value_json,
+          expires_at:  expiresAt,
+        });
+        if (!minted || typeof minted.code !== "string" || !minted.code.length) {
+          throw new TypeError("loyaltyRedemption.redeemForCustomer: coupons.issueSingleUseFromReward must return { code: string }");
+        }
+        couponCode = minted.code;
+        // Link the minted coupon to the claimed row INSIDE the try, and
+        // confirm the write landed (rowCount === 1). A throw OR a silently
+        // lost update here rolls the redemption back like a mint failure —
+        // otherwise the customer is charged, the cap slot is consumed, and
+        // the redemption is left with a NULL coupon_code it can never use.
+        var upd = await query(
+          "UPDATE loyalty_redemptions SET coupon_code = ?1 WHERE id = ?2",
+          [couponCode, redemptionId],
+        );
+        if (Number(upd.rowCount || 0) !== 1) {
+          throw new Error("loyaltyRedemption.redeemForCustomer: failed to persist coupon_code on the claimed redemption");
+        }
+      } catch (mintErr) {
+        await _reverseBurn(burn);
+        await query("DELETE FROM loyalty_redemptions WHERE id = ?1", [redemptionId]);
+        throw mintErr;
       }
-      couponCode = minted.code;
     }
 
-    await query(
-      "INSERT INTO loyalty_redemptions (id, customer_id, reward_slug, points_debited, coupon_code, " +
-      "status, redeemed_at, consumed_at, expires_at, order_id, cancel_reason) " +
-      "VALUES (?1, ?2, ?3, ?4, ?5, 'active', ?6, NULL, ?7, NULL, NULL)",
-      [redemptionId, customerId, rewardSlug, reward.point_cost, couponCode, ts, expiresAt],
-    );
-
     return {
       redemption_id: redemptionId,
       coupon_code:   couponCode,

package/package.json

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