@blamejs/blamejs-shop 0.4.13 → 0.4.15

package/lib/asset-manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.4.13",
+  "version": "0.4.15",
   "assets": {
     "css/admin.css": {
       "integrity": "sha384-6k53cvkRrxMgmeStLIoLjVXZQHqIJgTmv1Izd8TYhh1HOC4POgE6GCvx1bsalyEP",

package/lib/catalog.js

@@ -11,7 +11,7 @@
  *   - `variants`   — create, get, listForProduct, update, delete
  *   - `prices`     — set (versioned), current, history
  *   - `inventory`  — create, get, list, hold, decrement, release,
- *                    restock, setThreshold, checkLowStock
+ *                    restock, adjustOnHand, setThreshold, checkLowStock
  *   - `media`      — attach, get, listForProduct, listForVariant, delete,
  *                    reorder, setPrimary
  *
@@ -706,6 +706,56 @@ function _inventoryModule(query, opts) {
       return await this.get(sku);
     },
 
+    // Signed-delta adjustment of the storefront aggregate, fired by the
+    // inventory-ops back-office when a per-location move changes the
+    // total a single-bucket storefront sells against (a receive credits
+    // the aggregate, a write-off / shrinkage debits it). `restock` only
+    // grows on-hand and `decrement` only consumes a matching hold;
+    // neither expresses "the warehouse count just dropped by 5 because a
+    // pallet was damaged." A positive delta is an unconditional credit.
+    // A negative delta is an atomic conditional UPDATE — the
+    // `stock_on_hand - stock_held >= need` guard refuses (zero rows →
+    // `{ adjusted: false }`) when the debit would eat into stock that is
+    // already held for in-flight orders, so a write-off can never
+    // oversell a paid-but-unfulfilled line. Returns `{ adjusted, sku,
+    // delta }`; `null` when the SKU has no inventory row at all
+    // (un-tracked SKUs are unlimited everywhere in the storefront, so an
+    // aggregate adjustment simply doesn't apply). Fires the low-stock
+    // observer on success so a debit that crosses the threshold alerts.
+    adjustOnHand: async function (sku, delta) {
+      _sku(sku);
+      if (!Number.isInteger(delta) || delta === 0) {
+        throw new TypeError("catalog.inventory.adjustOnHand: delta must be a non-zero integer");
+      }
+      var ts = _now();
+      if (delta > 0) {
+        var rUp = await query(
+          "UPDATE inventory SET stock_on_hand = stock_on_hand + ?1, updated_at = ?2 WHERE sku = ?3",
+          [delta, ts, sku],
+        );
+        if (rUp.rowCount === 0) return null;
+        await _afterMutation(sku);
+        return { adjusted: true, sku: sku, delta: delta };
+      }
+      var need = -delta;
+      var rDown = await query(
+        "UPDATE inventory SET stock_on_hand = stock_on_hand - ?1, updated_at = ?2 " +
+        "WHERE sku = ?3 AND (stock_on_hand - stock_held) >= ?1",
+        [need, ts, sku],
+      );
+      if (rDown.rowCount === 1) {
+        await _afterMutation(sku);
+        return { adjusted: true, sku: sku, delta: delta };
+      }
+      // Zero rows: either no inventory row (un-tracked SKU) or the debit
+      // would eat into held stock. Distinguish so the caller can let an
+      // un-tracked SKU through while refusing a tracked-but-insufficient
+      // one.
+      var existing = await this.get(sku);
+      if (!existing) return null;
+      return { adjusted: false, sku: sku, delta: delta };
+    },
+
     release: async function (sku, qty) {
       _sku(sku);
       _positiveInt(qty, "qty");

package/lib/inventory-locations.js

@@ -32,12 +32,20 @@
  *                              duplicate code, invalid type, etc).
  *     listLocations / getLocation / updateLocation / deactivateLocation
  *                            — operator CRUD over the location set.
- *     setStock               — absolute set (overwrite).
- *     adjustStock            — relative delta with audit row.
- *     transferStock          — atomic two-row write moving qty
- *                              from one location to another; if
- *                              the source doesn't have enough, the
- *                              whole transfer refuses (no money
+ *     setStock               — absolute set (overwrite) via an
+ *                              atomic upsert.
+ *     adjustStock            — relative delta with audit row. Debits
+ *                              run as a single conditional UPDATE
+ *                              (`quantity >= need`); credits as an
+ *                              upsert. No read-then-write window — a
+ *                              debit that would drive the row below
+ *                              zero matches no rows and refuses.
+ *     transferStock          — moves qty from one location to
+ *                              another; the source debit is the same
+ *                              conditional UPDATE guard, so a transfer
+ *                              racing a checkout debit (or another
+ *                              transfer) for the last unit can't
+ *                              oversell — the loser refuses (no money
  *                              created, no row half-committed).
  *     stockForSku            — `{ total, by_location: [...] }`.
  *     totalForSku            — sum across every location.
@@ -521,20 +529,21 @@ function create(opts) {
         throw new TypeError("inventory-locations.setStock: location_code " +
           JSON.stringify(input.location_code) + " not found");
       }
+      // Absolute set is last-writer-wins by contract — the operator is
+      // declaring the authoritative count, not applying a relative
+      // change. The prior value is read only to record the signed
+      // delta on the audit row; the upsert itself is a single atomic
+      // statement so a first-touch insert and an overwrite never
+      // collide on the composite PK.
       var prev = await _getStockRow(input.sku, input.location_code);
       var prevQty = prev ? prev.quantity : 0;
       var ts = _now();
-      if (prev) {
-        await query(
-          "UPDATE inventory_stock SET quantity = ?1, updated_at = ?2 WHERE sku = ?3 AND location_code = ?4",
-          [input.quantity, ts, input.sku, input.location_code],
-        );
-      } else {
-        await query(
-          "INSERT INTO inventory_stock (sku, location_code, quantity, updated_at) VALUES (?1, ?2, ?3, ?4)",
-          [input.sku, input.location_code, input.quantity, ts],
-        );
-      }
+      await query(
+        "INSERT INTO inventory_stock (sku, location_code, quantity, updated_at) " +
+        "VALUES (?1, ?2, ?3, ?4) " +
+        "ON CONFLICT(sku, location_code) DO UPDATE SET quantity = ?3, updated_at = ?4",
+        [input.sku, input.location_code, input.quantity, ts],
+      );
       var delta = input.quantity - prevQty;
       await _audit(input.sku, input.location_code, delta, _reason(input.reason));
       return { sku: input.sku, location_code: input.location_code, quantity: input.quantity, delta: delta };
@@ -545,6 +554,18 @@ function create(opts) {
     // row below zero refuses the whole operation. Inserts a row
     // at quantity 0 + delta if the (sku, location_code) pair has
     // never been touched before (and delta is positive).
+    //
+    // Concurrency: the negative-delta path is a single atomic
+    // conditional UPDATE — `SET quantity = quantity + delta WHERE
+    // quantity + delta >= 0` — mirroring the catalog hold/decrement
+    // guards. D1 evaluates the predicate and applies the write inside
+    // one statement, so two racing debits against the last unit can't
+    // both succeed: the second racer's predicate sees the first's
+    // decrement and matches zero rows. The positive-delta path is an
+    // upsert (ON CONFLICT DO UPDATE) so a credit and a fresh-row
+    // insert never collide. Both paths re-read the post-write quantity
+    // for the audit row + return value rather than trusting a stale
+    // pre-read.
     adjustStock: async function (input) {
       if (!input || typeof input !== "object") {
         throw new TypeError("inventory-locations.adjustStock: input object required");
@@ -560,28 +581,42 @@ function create(opts) {
         throw new TypeError("inventory-locations.adjustStock: location_code " +
           JSON.stringify(input.location_code) + " not found");
       }
-      var prev = await _getStockRow(input.sku, input.location_code);
-      var prevQty = prev ? prev.quantity : 0;
-      var next = prevQty + input.delta;
-      if (next < 0) {
-        throw new TypeError("inventory-locations.adjustStock: delta " + input.delta +
-          " would drive stock below zero (current=" + prevQty + ", sku=" + input.sku +
-          ", location=" + input.location_code + ")");
-      }
       var ts = _now();
-      if (prev) {
+      if (input.delta > 0) {
+        // Credit: upsert in one atomic statement. A concurrent credit
+        // + first-touch insert serialize on the composite PK.
         await query(
-          "UPDATE inventory_stock SET quantity = ?1, updated_at = ?2 WHERE sku = ?3 AND location_code = ?4",
-          [next, ts, input.sku, input.location_code],
+          "INSERT INTO inventory_stock (sku, location_code, quantity, updated_at) " +
+          "VALUES (?1, ?2, ?3, ?4) " +
+          "ON CONFLICT(sku, location_code) DO UPDATE SET " +
+          "quantity = quantity + ?3, updated_at = ?4",
+          [input.sku, input.location_code, input.delta, ts],
         );
       } else {
-        await query(
-          "INSERT INTO inventory_stock (sku, location_code, quantity, updated_at) VALUES (?1, ?2, ?3, ?4)",
-          [input.sku, input.location_code, next, ts],
+        // Debit: atomic conditional UPDATE. The WHERE predicate is the
+        // serialization point — it refuses the write (zero rows) when
+        // the shelf lacks enough to cover the debit, so the row never
+        // goes negative even under concurrent debits. A SKU with no
+        // row at this location can't be debited (no negative
+        // first-touch); zero rows there is the insufficient case too.
+        var need = -input.delta;
+        var r = await query(
+          "UPDATE inventory_stock SET quantity = quantity + ?1, updated_at = ?2 " +
+          "WHERE sku = ?3 AND location_code = ?4 AND quantity >= ?5",
+          [input.delta, ts, input.sku, input.location_code, need],
         );
+        if (r.rowCount === 0) {
+          var cur = await _getStockRow(input.sku, input.location_code);
+          var have = cur ? cur.quantity : 0;
+          throw new TypeError("inventory-locations.adjustStock: delta " + input.delta +
+            " would drive stock below zero (current=" + have + ", sku=" + input.sku +
+            ", location=" + input.location_code + ")");
+        }
       }
+      var after = await _getStockRow(input.sku, input.location_code);
+      var nextQty = after ? after.quantity : 0;
       await _audit(input.sku, input.location_code, input.delta, _reason(input.reason));
-      return { sku: input.sku, location_code: input.location_code, quantity: next, delta: input.delta };
+      return { sku: input.sku, location_code: input.location_code, quantity: nextQty, delta: input.delta };
     },
 
     // Atomic two-row move. Reads the source quantity; if
@@ -612,44 +647,44 @@ function create(opts) {
           JSON.stringify(input.to_location) + " not found");
       }
 
-      var fromRow = await _getStockRow(input.sku, input.from_location);
-      var fromQty = fromRow ? fromRow.quantity : 0;
-      if (fromQty < input.quantity) {
-        throw new TypeError("inventory-locations.transferStock: insufficient stock at " +
-          input.from_location + " (have " + fromQty + ", need " + input.quantity + ")");
-      }
-      var toRow = await _getStockRow(input.sku, input.to_location);
-      var toQty = toRow ? toRow.quantity : 0;
-
       var ts = _now();
-      // Decrement source first. If the destination upsert below
-      // fails for any reason, the rollback path re-increments the
-      // source so the invariant (total quantity unchanged) holds.
-      await query(
-        "UPDATE inventory_stock SET quantity = ?1, updated_at = ?2 WHERE sku = ?3 AND location_code = ?4",
-        [fromQty - input.quantity, ts, input.sku, input.from_location],
+      // Debit the source with a single atomic conditional UPDATE. The
+      // `quantity >= need` predicate is the serialization point: two
+      // racing transfers (or a transfer racing a checkout debit)
+      // against the last unit can't both succeed — the second sees the
+      // first's decrement and matches zero rows, which we surface as
+      // the insufficient-stock refusal. No read-then-write window.
+      var srcDebit = await query(
+        "UPDATE inventory_stock SET quantity = quantity - ?1, updated_at = ?2 " +
+        "WHERE sku = ?3 AND location_code = ?4 AND quantity >= ?1",
+        [input.quantity, ts, input.sku, input.from_location],
       );
+      if (srcDebit.rowCount === 0) {
+        var fromRow = await _getStockRow(input.sku, input.from_location);
+        var fromHave = fromRow ? fromRow.quantity : 0;
+        throw new TypeError("inventory-locations.transferStock: insufficient stock at " +
+          input.from_location + " (have " + fromHave + ", need " + input.quantity + ")");
+      }
       try {
-        if (toRow) {
-          await query(
-            "UPDATE inventory_stock SET quantity = ?1, updated_at = ?2 WHERE sku = ?3 AND location_code = ?4",
-            [toQty + input.quantity, ts, input.sku, input.to_location],
-          );
-        } else {
-          await query(
-            "INSERT INTO inventory_stock (sku, location_code, quantity, updated_at) VALUES (?1, ?2, ?3, ?4)",
-            [input.sku, input.to_location, input.quantity, ts],
-          );
-        }
+        // Credit the destination via an atomic upsert. A concurrent
+        // credit + first-touch insert serialize on the composite PK.
+        await query(
+          "INSERT INTO inventory_stock (sku, location_code, quantity, updated_at) " +
+          "VALUES (?1, ?2, ?3, ?4) " +
+          "ON CONFLICT(sku, location_code) DO UPDATE SET " +
+          "quantity = quantity + ?3, updated_at = ?4",
+          [input.sku, input.to_location, input.quantity, ts],
+        );
       } catch (e) {
-        // Best-effort compensating restore on the source so the
-        // pair stays balanced. If THIS write also fails the
-        // operator will see two adjacent audit rows with no
-        // counterpart — the caller can replay or reconcile.
+        // Best-effort compensating restore on the source so the pair
+        // stays balanced. The restore is itself an atomic increment
+        // (no read-then-write), so it can't clobber a concurrent
+        // mutation that landed between the debit and this catch.
         try {
           await query(
-            "UPDATE inventory_stock SET quantity = ?1, updated_at = ?2 WHERE sku = ?3 AND location_code = ?4",
-            [fromQty, _now(), input.sku, input.from_location],
+            "UPDATE inventory_stock SET quantity = quantity + ?1, updated_at = ?2 " +
+            "WHERE sku = ?3 AND location_code = ?4",
+            [input.quantity, _now(), input.sku, input.from_location],
           );
         } catch (_e2) { /* drop-silent — the original error is what the caller needs to fix */ }
         throw e;
@@ -659,13 +694,15 @@ function create(opts) {
       await _audit(input.sku, input.from_location, -input.quantity, reason);
       await _audit(input.sku, input.to_location,    input.quantity, reason);
 
+      var fromAfterRow = await _getStockRow(input.sku, input.from_location);
+      var toAfterRow   = await _getStockRow(input.sku, input.to_location);
       return {
         sku:           input.sku,
         from_location: input.from_location,
         to_location:   input.to_location,
         quantity:      input.quantity,
-        from_after:    fromQty - input.quantity,
-        to_after:      toQty + input.quantity,
+        from_after:    fromAfterRow ? fromAfterRow.quantity : 0,
+        to_after:      toAfterRow ? toAfterRow.quantity : 0,
       };
     },
 

package/lib/security-middleware.js

@@ -561,10 +561,21 @@ function globalRateLimitOpts() {
  * are machine-to-machine and authenticate with the shared
  * D1_BRIDGE_SECRET, so on those paths the secret gate — not a browser
  * fingerprint — is the deciding check (see INTERNAL_BRIDGE_PATHS).
+ *
+ * `/admin` is skipped HERE but re-guarded in tag mode inside
+ * `mountRouteGuards`: every admin route is gated on the timing-safe
+ * bearer-key check, and the documented way to drive the admin JSON
+ * surface is curl — whose User-Agent is on the vendored deny list, and
+ * the UA check fires before auth is ever consulted. In block mode the
+ * README / onboarding curl examples answer 403 "Forbidden" instead of
+ * reaching the 401/200 bearer gate; in tag mode automation is audited
+ * (`system.botguard.tag` + `req.suspectedBot`) while the bearer key
+ * stays the deciding check. The regex matches `/admin` and
+ * `/admin/...` only — not other `/admin…`-prefixed names.
  */
 function botGuardOpts() {
   return {
-    skipPaths: INTERNAL_BRIDGE_PATHS.slice(),
+    skipPaths: INTERNAL_BRIDGE_PATHS.slice().concat([/^\/admin(\/|$)/]),
   };
 }
 
@@ -584,6 +595,22 @@ function _hasPrefix(pathname, prefixes) {
  * @param r  the blamejs Router passed to createApp's routes(r) callback.
  */
 function mountRouteGuards(r) {
+  // --- bot-guard, tag mode, /admin only -------------------------------
+  //
+  // The app-level bot-guard (block mode) skips /admin — see
+  // botGuardOpts: curl is the documented admin client and the UA
+  // deny-list check fires before the bearer gate, so block mode turns
+  // every documented example into a 403. The surface still wants the
+  // signal, though: this tag-mode instance audits automation
+  // (system.botguard.tag + req.suspectedBot) without refusing it, and
+  // the timing-safe bearer key stays the deciding check.
+  var adminBotTag = b.middleware.botGuard({ mode: "tag" });
+  r.use(function adminBotTagGuard(req, res, next) {
+    var pathname = req.pathname || req.url || "/";
+    if (!/^\/admin(\/|$)/.test(pathname)) return next();
+    return adminBotTag(req, res, next);
+  });
+
   // --- CSRF: double-submit token on authenticated state-changing POSTs ---
   //
   // The vendored createApp enforces CSRF by default; the entry points pass

package/lib/storefront.js

@@ -8085,9 +8085,18 @@ function _cartGiftBlock(opts) {
         (w.wrap_sku === current ? " selected" : "") + ">" +
         esc(String(w.title)) + " (" + esc(feeStr) + ")</option>";
     }).join("");
+  // Over-limit (or any rejected /cart/gift apply) renders an inline error
+  // banner. The message carries the operator-authored wrap title, so it is
+  // escaped at the sink — the cap value the route interpolates is a plain
+  // integer, but escaping the whole string is the safe default. `role=alert`
+  // so a screen reader announces the rejection.
+  var giftError = (typeof opts.gift_error === "string" && opts.gift_error)
+    ? "<p class=\"cart-gift__error\" role=\"alert\">" + esc(opts.gift_error) + "</p>"
+    : "";
   return "<section class=\"cart-gift\">" +
-    "<details class=\"cart-gift__details\"" + (current ? " open" : "") + ">" +
+    "<details class=\"cart-gift__details\"" + (current || giftError ? " open" : "") + ">" +
       "<summary class=\"cart-gift__summary\">Add a gift wrap</summary>" +
+      giftError +
       "<form method=\"post\" action=\"/cart/gift\" class=\"cart-gift__form\">" +
         "<label class=\"form-field\"><span>Gift wrap</span>" +
           "<select name=\"wrap_sku\">" + options + "</select>" +
@@ -10023,11 +10032,13 @@ function renderAddPaymentMethod(opts) {
 // ---- profile edit ------------------------------------------------------
 //
 // Display-name edit for the signed-in customer. Email is stored hash-only
-// and is the OAuth account-linking key, so it's shown read-only (masked)
-// and cannot be changed here — the primitive refuses an email patch until
-// a verification ceremony exists. The form is a plain server-rendered
-// POST with a PRG `?ok=updated` success notice, matching the addresses
-// pattern.
+// (a one-way hash, never the plaintext) and is the OAuth account-linking
+// key, so it is shown read-only and genuinely cannot be changed — there is
+// no readable address to edit. The field's hint tells the customer what to
+// do instead (sign in with the registered address; create a new account to
+// use a different one; contact support to move order history). The form is
+// a plain server-rendered POST with a PRG `?ok=updated` success notice,
+// matching the addresses pattern.
 function renderProfile(opts) {
   opts = opts || {};
   var esc = b.template.escapeHtml;
@@ -10054,7 +10065,7 @@ function renderProfile(opts) {
         "<div class=\"form-row\"><label class=\"form-field\"><span class=\"form-field__label\">Email</span>" +
           "<input type=\"text\" value=\"Hidden for privacy — stored as a one-way hash\" disabled aria-describedby=\"email-note\"></label></div>" +
         "<p id=\"email-note\" class=\"form-field__hint\">Your email address is never stored in readable form, so it can't be changed or shown here. " +
-          "Sign in with the address you registered.</p>" +
+          "Sign in with the address you registered. To use a different address, create a new account with it, or contact support if you need help moving your order history.</p>" +
         "<div class=\"form-actions\"><button type=\"submit\" class=\"btn-primary\">Save changes</button> " +
           "<a class=\"btn-ghost\" href=\"/account\">Cancel</a></div>" +
       "</form>" +
@@ -13088,38 +13099,27 @@ function mount(router, deps) {
     return res.end ? res.end(payload) : res.send(payload);
   });
 
-  router.get("/cart", async function (req, res) {
+  // Assemble the full cart-page render and emit it at `status`. Shared by
+  // GET /cart and by POST /cart/gift's over-limit rejection (a 4xx that must
+  // still show the customer their cart, with a gift error banner), so the two
+  // surfaces never drift. `extraOpts` overlays render flags the caller knows
+  // (the post-add banner, the coupon PRG notices, a gift_error message).
+  async function _renderCartResponse(req, res, status, extraOpts) {
+    extraOpts = extraOpts || {};
     var ccy = await _currencyForReq(req);
     var sid = _readSidCookie(req);
-    // `?added=1` after a POST /cart/lines redirect — drives the
-    // "Added to cart" status banner. Read from the parsed query when the
-    // router populated it, else from the raw URL.
-    var cartUrl = req.url ? new URL(req.url, "http://localhost") : null;
-    var added = (req.query && req.query.added === "1") ||
-      (cartUrl && cartUrl.searchParams.get("added") === "1") || false;
-    // Coupon-entry PRG outcomes (set by POST /cart/coupon[/remove]). One of
-    // applied / removed / err so the cart shows an inline notice. `?code_err`
-    // carries no detail beyond "couldn't apply" — a uniform message, no
-    // code-existence oracle.
-    function _cartQp(name) {
-      return (req.query && req.query[name] === "1") ||
-        (cartUrl && cartUrl.searchParams.get(name) === "1") || false;
-    }
-    var codeApplied = _cartQp("code_applied");
-    var codeRemoved = _cartQp("code_removed");
-    var codeErr     = _cartQp("code_err");
     if (!sid) {
-      return _send(res, 200, renderCart(Object.assign({
+      return _send(res, status, renderCart(Object.assign({
         lines: [], totals: { subtotal_minor: 0, grand_total_minor: 0, currency: "USD" },
         shop_name: shopName, theme: theme,
-      }, ccy)));
+      }, ccy, extraOpts)));
     }
     var c = await deps.cart.bySession(sid);
     if (!c) {
-      return _send(res, 200, renderCart(Object.assign({
+      return _send(res, status, renderCart(Object.assign({
         lines: [], totals: { subtotal_minor: 0, grand_total_minor: 0, currency: "USD" },
         shop_name: shopName, theme: theme,
-      }, ccy)));
+      }, ccy, extraOpts)));
     }
     var rawLines = await deps.cart.listLines(c.id);
     // Reapply the active quantity-break for each line at its current
@@ -13197,7 +13197,7 @@ function mount(router, deps) {
     // the primitive falls back to its weight-agnostic transit rows. Drop-
     // silent → null, and the summary renders no estimate.
     var cartEstimate = await _resolveDeliveryEstimate(req, { dest: estimateDest });
-    _send(res, 200, renderCart(Object.assign({
+    _send(res, status, renderCart(Object.assign({
       lines:           lines,
       totals:          totals,
       totals_detail:   totalsDetail,
@@ -13208,19 +13208,38 @@ function mount(router, deps) {
       checkout_available: !!(deps.checkout && deps.order),
       gift_wraps:      giftWraps,
       gift_wrap_in_cart: giftWrapInCart,
-      added:           added,
       // Coupon entry: surfaced only when the discount engine is wired (the
       // POST routes mount on the same condition). `applied_codes` echoes the
       // typed codes so each gets a remove control; the *_notice flags drive
       // the inline PRG banner.
       coupon_enabled:  !!(deps.autoDiscount && typeof deps.cart.listDiscountCodes === "function"),
       applied_codes:   appliedCodes,
-      code_applied:    codeApplied,
-      code_removed:    codeRemoved,
-      code_err:        codeErr,
       shop_name:       shopName,
       theme:           theme,
-    }, ccy)));
+    }, ccy, extraOpts)));
+  }
+
+  router.get("/cart", async function (req, res) {
+    // `?added=1` after a POST /cart/lines redirect — drives the
+    // "Added to cart" status banner. Read from the parsed query when the
+    // router populated it, else from the raw URL.
+    var cartUrl = req.url ? new URL(req.url, "http://localhost") : null;
+    var added = (req.query && req.query.added === "1") ||
+      (cartUrl && cartUrl.searchParams.get("added") === "1") || false;
+    // Coupon-entry PRG outcomes (set by POST /cart/coupon[/remove]). One of
+    // applied / removed / err so the cart shows an inline notice. `?code_err`
+    // carries no detail beyond "couldn't apply" — a uniform message, no
+    // code-existence oracle.
+    function _cartQp(name) {
+      return (req.query && req.query[name] === "1") ||
+        (cartUrl && cartUrl.searchParams.get(name) === "1") || false;
+    }
+    return await _renderCartResponse(req, res, 200, {
+      added:        added,
+      code_applied: _cartQp("code_applied"),
+      code_removed: _cartQp("code_removed"),
+      code_err:     _cartQp("code_err"),
+    });
   });
 
   // ---- checkout flow -------------------------------------------------
@@ -15393,9 +15412,10 @@ function mount(router, deps) {
     }
 
     // Profile edit — display-name only. Email is hash-only + the OAuth
-    // linking key, so the primitive refuses an email change without a
-    // verification ceremony; the form shows it read-only. PRG with a
-    // ?ok=updated success notice, matching the addresses pattern.
+    // linking key, so it genuinely can't be changed (no readable address to
+    // edit); the form shows it read-only and the route never accepts an email
+    // field. PRG with a ?ok=updated success notice, matching the addresses
+    // pattern.
     async function _renderProfilePage(req, res, auth, customer, notice, code) {
       var cartCount = await _cartCountForReq(req);
       var url = req.url ? new URL(req.url, "http://localhost") : null;
@@ -19007,21 +19027,59 @@ function mount(router, deps) {
   // a REAL cart line so its fee flows through pricing.totals and is charged
   // by checkout.confirm (NEVER a post-commit hook — that would mis-charge).
   // Selecting "No gift wrap" removes any wrap line. Selecting a wrap removes
-  // any prior wrap line then adds the chosen one (qty 1, capped by
-  // max_per_order). The message / recipient are collected at checkout (they
-  // need the order id). Mounts only when the gift-options primitive is wired.
+  // any prior wrap line then adds the chosen one.
+  //
+  // Authoritative fee: the wrap line's price snapshot is the operator-
+  // configured gift_wraps.fee_minor — NOT the wrap variant's catalog price.
+  // fee_minor is the single source the admin sets and the cart selector
+  // displays, so the charge must read it too (an explicit unit_amount_minor
+  // snapshot on cart.addLine), or the displayed fee and the charged fee would
+  // silently diverge whenever the catalog price differs from the wrap fee.
+  //
+  // Cap: gift_wraps.max_per_order bounds how many of that wrap one order may
+  // carry. The request quantity (defensive reader, default 1) is checked
+  // against it BEFORE any mutation — over the cap is rejected with a 422 and
+  // the cart re-rendered with a customer-readable error, the cart unchanged.
+  //
+  // The message / recipient are collected at checkout (they need the order
+  // id). Mounts only when the gift-options primitive is wired.
   if (deps.giftOptions) {
     router.post("/cart/gift", async function (req, res) {
       var body = req.body || {};
       var wrapSku = typeof body.wrap_sku === "string" ? body.wrap_sku.trim() : "";
+      // Defensive request-shape reader: qty defaults to 1, and any non-
+      // positive-integer field (blank, garbage, fractional, negative) falls
+      // back to 1 rather than throwing — the cap check below is the only gate
+      // that rejects, and it rejects on "too many", never on a malformed qty.
+      var reqQty = 1;
+      var rawQty = body.qty;
+      if (rawQty != null && rawQty !== "") {
+        var s = String(rawQty).trim();
+        if (/^\d+$/.test(s)) {
+          var n = Number(s);
+          if (Number.isInteger(n) && n > 0) reqQty = n;
+        }
+      }
       var resolved = await _getOrCreateCart(req, res, "USD");
-      var cartId = resolved.cart.id;
+      var cart = resolved.cart;
+      var cartId = cart.id;
       try {
         // Resolve the active wrap catalog so we know every wrap sku (to
-        // remove a stale wrap line) and the selected wrap's cap.
+        // remove a stale wrap line) and the selected wrap's fee + cap.
         var wraps = await deps.giftOptions.listWraps({ active_only: true });
         var wrapBySku = {};
         for (var i = 0; i < wraps.length; i += 1) wrapBySku[wraps[i].wrap_sku] = wraps[i];
+        var chosen = (wrapSku && wrapBySku[wrapSku]) ? wrapBySku[wrapSku] : null;
+        // Enforce max_per_order before mutating anything. A null cap means
+        // "no limit"; a set cap rejects a request for more wraps than the
+        // order may carry. The cart is left untouched so the customer can
+        // resubmit with a smaller quantity.
+        if (chosen && chosen.max_per_order != null && reqQty > chosen.max_per_order) {
+          return await _renderCartResponse(req, res, 422, {
+            gift_error: "You can add at most " + chosen.max_per_order + " of “" +
+              chosen.title + "” to one order. Please choose a smaller quantity.",
+          });
+        }
         // Remove any existing wrap line first (every active wrap's sku).
         var existingLines = await deps.cart.listLines(cartId);
         for (var li = 0; li < existingLines.length; li += 1) {
@@ -19030,13 +19088,19 @@ function mount(router, deps) {
           }
         }
         // Add the selected wrap (when one was chosen + it's a real active
-        // wrap). The wrap_sku is a real catalog variant; resolve its variant
-        // id and add it as a line — the price snapshot comes from the catalog
-        // price, so the fee is charged through the normal quote path.
-        if (wrapSku && wrapBySku[wrapSku]) {
+        // wrap). The wrap_sku is a real catalog variant — resolve its variant
+        // id, then add it as a line whose unit price is the AUTHORITATIVE
+        // gift_wraps.fee_minor (the configured + displayed wrap fee), pinned
+        // via an explicit price snapshot so the charge matches the display.
+        if (chosen) {
           var variant = await deps.catalog.variants.bySku(wrapSku);
           if (variant) {
-            await deps.cart.addLine(cartId, { variant_id: variant.id, qty: 1 });
+            await deps.cart.addLine(cartId, {
+              variant_id:        variant.id,
+              qty:               reqQty,
+              unit_amount_minor: chosen.fee_minor,
+              unit_currency:     cart.currency || "USD",
+            });
           }
         }
       } catch (e) {

package/lib/webhooks.js

@@ -18,8 +18,9 @@
  *   `events` is either the wildcard `*` or a comma-separated allowlist
  *   of recognized event types — `order.mark_paid`,
  *   `order.start_fulfillment`, `order.mark_shipped`,
- *   `order.mark_delivered`, `order.cancel`, `order.refund`. Endpoints
- *   only receive event types they subscribed to.
+ *   `order.mark_delivered`, `order.cancel`, `order.refund`,
+ *   `inventory.low_stock`. Endpoints only receive event types they
+ *   subscribed to.
  *
  *   `send(eventType, payload)` is fire-and-flag-failure: every active
  *   endpoint subscribed to the event gets a delivery row before the
@@ -65,6 +66,7 @@ var KNOWN_EVENTS = Object.freeze([
   "order.mark_delivered",
   "order.cancel",
   "order.refund",
+  "inventory.low_stock",
 ]);
 
 var SECRET_BYTES = 32;

package/package.json

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