@blamejs/blamejs-shop 0.4.15 → 0.4.16

package/lib/quotes.js

@@ -42,6 +42,12 @@
  *   It is NULL until the operator has responded.
  *
  *   Composes:
+ *     - b.fsm            — the quote lifecycle machine. Every status
+ *                          change replays the machine from the row's
+ *                          current status and asks it whether the edge
+ *                          is legal before touching the database, so an
+ *                          illegal transition is refused the same way
+ *                          regardless of which surface fired it.
  *     - b.uuid.v7        — quote + line PKs (sortable; B-tree locality)
  *     - b.guardUuid      — strict UUID validation on every quote_id +
  *                          customer_id read
@@ -56,6 +62,14 @@
  *                          status flip + the converted_order_id the
  *                          caller supplies, leaving the actual order
  *                          creation to the caller.
+ *     - inventory (opt)  — when injected alongside `order`,
+ *                          `convertToOrder` reserves shelf stock per
+ *                          quote line BEFORE creating the pending order
+ *                          (the same atomic hold checkout.confirm
+ *                          takes), so a quote can't oversell against a
+ *                          concurrent cart checkout. The pending order
+ *                          owns the holds and settles them on its own
+ *                          paid / cancelled edge.
  *
  *   Surface:
  *     requestQuote({ customer_id, lines?, cart?, message?,
@@ -77,7 +91,7 @@
  *     + `quote_lines`. ON DELETE CASCADE from quote -> lines.
  *
  * @primitive quotes
- * @related   b.uuid, b.guardUuid, shop.cart, shop.order
+ * @related   b.fsm, b.uuid, b.guardUuid, shop.cart, shop.order
  */
 
 var MAX_LINES              = 1000;
@@ -98,6 +112,14 @@ var MAX_LIMIT              = 500;
 var SKU_RE      = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
 var CURRENCY_RE = /^[A-Z]{3}$/;
 
+// View-token material for the customer-facing quote page (/quote/:token).
+// 32 random bytes -> 43-char base64url plaintext, stored only as its SHA3-512
+// namespace hash (never the plaintext) so a read of the quotes table never
+// yields a working link. Mirrors the survey-invitation token discipline.
+var VIEW_TOKEN_BYTE_LEN  = 32;
+var VIEW_TOKEN_NAMESPACE = "shop.quotes.view-token:v1";
+var VIEW_TOKEN_RE        = /^[A-Za-z0-9_-]{43}$/;
+
 // Control bytes + zero-width / direction-override family. Operator-
 // rendered text fields refuse these to keep the downstream dashboard /
 // printout safe from header-injection + visual-spoofing attacks. CR/LF
@@ -120,6 +142,86 @@ var TERMINAL_STATUSES = Object.freeze([
 
 var b = require("./vendor/blamejs");
 
+// The quote lifecycle, modelled on b.fsm — the same composition the order
+// primitive uses (lib/order.js#_getOrderFsm). The FSM is the single source of
+// truth for which (status, event) pairs are legal: every status-changing verb
+// below replays the machine from the row's current status and asks it whether
+// the edge is allowed before it touches the database, so an illegal transition
+// is refused identically whether it arrives via the customer surface, the
+// operator console, or the cron. Each event name maps 1:1 to the verb that
+// fires it:
+//
+//   respond   requested            -> responded   (operator prices the quote)
+//   accept    responded            -> accepted    (customer accepts)
+//   reject    responded            -> rejected    (customer declines)
+//   cancel    requested|responded  -> cancelled   (either side pulls it)
+//   expire    responded            -> expired     (valid_until elapsed)
+//   convert   accepted             -> converted   (lands a pending order)
+//
+// Terminal states declare no outgoing edge, so the machine itself refuses a
+// double-accept / convert-after-cancel without a hand-written status check.
+var QUOTE_TRANSITIONS = Object.freeze([
+  { from: "requested", to: "responded", on: "respond" },
+  { from: "requested", to: "cancelled", on: "cancel" },
+  { from: "responded", to: "accepted",  on: "accept" },
+  { from: "responded", to: "rejected",  on: "reject" },
+  { from: "responded", to: "cancelled", on: "cancel" },
+  { from: "responded", to: "expired",   on: "expire" },
+  { from: "accepted",  to: "converted", on: "convert" },
+]);
+
+var _quoteFsm = null;
+function _getQuoteFsm() {
+  if (_quoteFsm) return _quoteFsm;
+  // b.fsm emits audit events under the 'fsm' namespace — register it
+  // (idempotent) so the audit sink keeps the events instead of dropping them
+  // with a noisy warning, exactly as the order FSM does.
+  try { b.audit.registerNamespace("fsm"); } catch (_e) { /* idempotent; ignore */ }
+  _quoteFsm = b.fsm.define({
+    name:    "quote",
+    initial: "requested",
+    states: {
+      requested: {}, responded: {}, accepted: {},
+      rejected:  {}, expired:   {}, cancelled: {}, converted: {},
+    },
+    transitions: QUOTE_TRANSITIONS.map(function (t) {
+      return { from: t.from, to: t.to, on: t.on };
+    }),
+  });
+  return _quoteFsm;
+}
+
+// Resolve the to-status for a legal (from, event) pair off the transition
+// table — the FSM's `can()` only answers yes/no, so the destination comes from
+// the declaration the machine was built from (one source of truth).
+function _toStatus(fromStatus, event) {
+  for (var i = 0; i < QUOTE_TRANSITIONS.length; i += 1) {
+    var t = QUOTE_TRANSITIONS[i];
+    if (t.from === fromStatus && t.on === event) return t.to;
+  }
+  return null;
+}
+
+// Validate one status-changing edge through the FSM. `event` is the verb name
+// above; `fromStatus` is the row's CURRENT status. Returns the resolved
+// to-status on success. Throws a coded QUOTE_TRANSITION_REFUSED Error when the
+// machine refuses the edge (terminal state, wrong source state, or unknown
+// event) so the caller maps it to a uniform 409 regardless of which guard
+// tripped — the same shape the hand-rolled status checks used to throw. The
+// machine's synchronous `can()` is the gate (no guards declared, so it never
+// awaits); the destination is read back off the transition table.
+function _assertTransition(fromStatus, event, verbLabel) {
+  var fsm = _getQuoteFsm();
+  var instance = fsm.restore({ state: fromStatus, history: [], context: {} });
+  if (!instance.can(event)) {
+    var refused = new Error("quotes." + verbLabel + ": refused — quote is " +
+      fromStatus + ", cannot " + event);
+    refused.code = "QUOTE_TRANSITION_REFUSED";
+    throw refused;
+  }
+  return _toStatus(fromStatus, event);
+}
+
 // ---- validators ---------------------------------------------------------
 
 function _id(s, label) {
@@ -246,6 +348,26 @@ function _status(s) {
 
 function _now() { return Date.now(); }
 
+// Mint a fresh view-token plaintext. Routes through b.crypto's linear-time
+// base64url encoder (no ReDoS-shaped padding strip), like the survey tokens.
+function _mintViewToken() {
+  return b.crypto.toBase64Url(b.crypto.generateBytes(VIEW_TOKEN_BYTE_LEN));
+}
+
+// Canonicalize + shape-check a presented token before it ever touches the
+// database. Returns the canonical string; throws on a malformed token so a
+// garbage value can't widen the hash lookup.
+function _canonicalViewToken(input) {
+  if (typeof input !== "string" || !VIEW_TOKEN_RE.test(input)) {
+    throw new TypeError("quotes: view token must be 43 base64url characters");
+  }
+  return input;
+}
+
+function _hashViewToken(canonical) {
+  return b.crypto.namespaceHash(VIEW_TOKEN_NAMESPACE, canonical);
+}
+
 // Validate + normalize the requested-lines array. Refuses duplicate
 // SKUs — the same SKU twice is a quantity-merge concern, not a
 // per-line decision; the customer should send a single line at the
@@ -383,6 +505,23 @@ function create(opts) {
   if (orderHandle && typeof orderHandle.createFromCart !== "function") {
     throw new TypeError("quotes.create: opts.order must expose createFromCart when provided");
   }
+  // Optional inventory handle — when wired ALONGSIDE the order handle,
+  // `convertToOrder` reserves shelf stock for each quote line BEFORE
+  // creating the pending order, exactly as checkout.confirm does: the
+  // pending order then OWNS those holds and settles them on its own
+  // paid / cancelled FSM edges (decrement on paid, release on cancel),
+  // so a quote-driven order can't oversell against a concurrent cart
+  // checkout. Insufficient stock on any line rolls back every hold the
+  // pass placed and refuses the conversion with a coded
+  // QUOTE_INSUFFICIENT_STOCK error. Must expose hold(sku, qty) +
+  // release(sku, qty), the same shape catalog.inventory exposes. Absent
+  // it (or absent the order handle) conversion lands no holds — the
+  // in-house-pipeline posture where the operator owns stock truth.
+  var inventoryHandle = opts.inventory || null;
+  if (inventoryHandle && (typeof inventoryHandle.hold !== "function" ||
+                          typeof inventoryHandle.release !== "function")) {
+    throw new TypeError("quotes.create: opts.inventory must expose hold + release when provided");
+  }
 
   async function _getQuoteRaw(id) {
     var r = await query("SELECT * FROM quotes WHERE id = ?1", [id]);
@@ -406,6 +545,51 @@ function create(opts) {
     return out;
   }
 
+  // Reserve shelf stock for every quote line before the conversion creates
+  // the pending order — the same atomic conditional-UPDATE hold checkout uses
+  // (`inventory.hold(sku, qty)`). An un-tracked SKU (hold → null) is unlimited
+  // and passes through; a `held:false` result means the line oversells, so we
+  // roll back every hold this pass already placed and refuse the conversion
+  // with a coded error. Returns the placed-holds list and a per-sku held-qty
+  // map so the order lines can record `stock_held_qty` (the order's paid edge
+  // debits exactly those units; its cancel edge releases them). No-op (empty)
+  // when no inventory handle is wired.
+  async function _placeQuoteHolds(lines) {
+    var placed = [];
+    var heldBySku = Object.create(null);
+    if (!inventoryHandle) return { placed: placed, heldBySku: heldBySku };
+    for (var i = 0; i < lines.length; i += 1) {
+      var sku = lines[i].sku;
+      var qty = Number(lines[i].quantity);
+      var res = await inventoryHandle.hold(sku, qty);
+      if (res == null) continue;            // un-tracked SKU — unlimited
+      if (res.held) {
+        heldBySku[sku] = (heldBySku[sku] || 0) + qty;
+        placed.push({ sku: sku, qty: qty });
+        continue;
+      }
+      await _releaseQuoteHolds(placed);
+      var refused = new Error("quotes.convertToOrder: refused — sku " + sku +
+        " does not have " + qty + " unit(s) available to fulfil the quote");
+      refused.code = "QUOTE_INSUFFICIENT_STOCK";
+      refused.sku  = sku;
+      throw refused;
+    }
+    return { placed: placed, heldBySku: heldBySku };
+  }
+
+  // Best-effort release of a set of placed holds — the rollback path. Drop-
+  // silent per hold so a release failure never masks the error that triggered
+  // the rollback. Runs ONLY when no pending order was created; once the order
+  // exists it owns its holds (settled on its own paid / cancel edge).
+  async function _releaseQuoteHolds(holds) {
+    if (!inventoryHandle || !Array.isArray(holds)) return;
+    for (var i = 0; i < holds.length; i += 1) {
+      try { await inventoryHandle.release(holds[i].sku, holds[i].qty); }
+      catch (_e) { /* drop-silent — rollback best-effort */ }
+    }
+  }
+
   return {
     QUOTE_STATUSES:    QUOTE_STATUSES.slice(),
     TERMINAL_STATUSES: TERMINAL_STATUSES.slice(),
@@ -484,6 +668,12 @@ function create(opts) {
 
       var id = b.uuid.v7();
       var ts = _now();
+      // Mint the customer-facing view token up front so the request flow can
+      // hand the customer their link immediately (and an operator console
+      // detail can re-issue it). Only the hash lands in the row; the plaintext
+      // rides back on the return value and is never stored.
+      var viewTokenPlain = _mintViewToken();
+      var viewTokenHash  = _hashViewToken(viewTokenPlain);
       try {
         await query(
           "INSERT INTO quotes " +
@@ -491,10 +681,10 @@ function create(opts) {
           " operator_notes, shipping_minor, tax_minor, total_minor, currency, " +
           " valid_until, accepted_at, accepted_by_customer, rejected_at, reject_reason, " +
           " converted_at, converted_order_id, cancelled_at, cancel_reason, " +
-          " created_at, updated_at) " +
+          " view_token_hash, created_at, updated_at) " +
           "VALUES (?1, ?2, 'requested', ?3, ?4, ?5, NULL, NULL, NULL, NULL, NULL, " +
-          " NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, ?6, ?6)",
-          [id, customerId, delivery, payment, message, ts],
+          " NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, ?7, ?6, ?6)",
+          [id, customerId, delivery, payment, message, ts, viewTokenHash],
         );
         for (var j = 0; j < lines.length; j += 1) {
           var l = lines[j];
@@ -513,7 +703,11 @@ function create(opts) {
         catch (_e2) { /* drop-silent — the original error is what the caller needs */ }
         throw e;
       }
-      return await _hydrated(id);
+      var hydrated = await _hydrated(id);
+      // Surface the plaintext token once on the create result so the caller
+      // can build the /quote/:token link without a second round-trip.
+      if (hydrated) hydrated.view_token = viewTokenPlain;
+      return hydrated;
     },
 
     // FSM: requested -> responded. Operator prices every quote line,
@@ -542,12 +736,7 @@ function create(opts) {
         miss.code = "QUOTE_NOT_FOUND";
         throw miss;
       }
-      if (current.status !== "requested") {
-        var refused = new Error("quotes.respondToQuote: refused — quote is " + current.status +
-          ", only requested quotes can be responded to");
-        refused.code = "QUOTE_TRANSITION_REFUSED";
-        throw refused;
-      }
+      _assertTransition(current.status, "respond", "respondToQuote");
 
       var lines = await _getLinesRaw(quoteId);
       var lineSkus = lines.map(function (r) { return r.sku; });
@@ -613,12 +802,7 @@ function create(opts) {
         miss.code = "QUOTE_NOT_FOUND";
         throw miss;
       }
-      if (current.status !== "responded") {
-        var refused = new Error("quotes.customerAccept: refused — quote is " + current.status +
-          ", only responded quotes can be accepted");
-        refused.code = "QUOTE_TRANSITION_REFUSED";
-        throw refused;
-      }
+      _assertTransition(current.status, "accept", "customerAccept");
       var ts = _now();
       if (current.valid_until != null && Number(current.valid_until) <= ts) {
         var expired = new Error("quotes.customerAccept: refused — quote expired at " +
@@ -649,12 +833,7 @@ function create(opts) {
         miss.code = "QUOTE_NOT_FOUND";
         throw miss;
       }
-      if (current.status !== "responded") {
-        var refused = new Error("quotes.customerReject: refused — quote is " + current.status +
-          ", only responded quotes can be rejected");
-        refused.code = "QUOTE_TRANSITION_REFUSED";
-        throw refused;
-      }
+      _assertTransition(current.status, "reject", "customerReject");
       var ts = _now();
       await query(
         "UPDATE quotes SET status = 'rejected', rejected_at = ?1, " +
@@ -682,12 +861,7 @@ function create(opts) {
         miss.code = "QUOTE_NOT_FOUND";
         throw miss;
       }
-      if (current.status !== "requested" && current.status !== "responded") {
-        var refused = new Error("quotes.cancelQuote: refused — quote is " + current.status +
-          ", only requested or responded quotes can be cancelled");
-        refused.code = "QUOTE_TRANSITION_REFUSED";
-        throw refused;
-      }
+      _assertTransition(current.status, "cancel", "cancelQuote");
       var ts = _now();
       await query(
         "UPDATE quotes SET status = 'cancelled', cancelled_at = ?1, " +
@@ -714,12 +888,7 @@ function create(opts) {
         miss.code = "QUOTE_NOT_FOUND";
         throw miss;
       }
-      if (current.status !== "accepted") {
-        var refused = new Error("quotes.convertToOrder: refused — quote is " + current.status +
-          ", only accepted quotes can be converted");
-        refused.code = "QUOTE_TRANSITION_REFUSED";
-        throw refused;
-      }
+      _assertTransition(current.status, "convert", "convertToOrder");
 
       var lines = await _getLinesRaw(quoteId);
       var ts = _now();
@@ -738,48 +907,69 @@ function create(opts) {
         var cartId    = _id(input.cart_id    || quoteId, "cart_id");
         var sessionId = _id(input.session_id || quoteId, "session_id");
 
-        var subtotal = 0;
-        var orderLines = [];
-        for (var i = 0; i < lines.length; i += 1) {
-          var line = lines[i];
-          var qty   = Number(line.quantity);
-          var price = Number(line.unit_price_minor);
-          subtotal += qty * price;
-          orderLines.push({
-            // The order primitive validates variant_id as a UUID.
-            // The quote primitive doesn't track variant_id (a quote
-            // is SKU-grained, not variant-grained), so synthesize a
-            // deterministic UUID per (quote, line) tuple. The
-            // operator's variant resolution happens upstream of the
-            // quote surface; the order line snapshots the sku +
-            // qty + price the customer accepted.
-            variant_id:        line.id,
-            sku:               line.sku,
-            qty:               qty,
-            unit_amount_minor: price,
-            unit_currency:     current.currency,
+        // Reserve shelf stock for the whole quote before the order lands.
+        // Throws QUOTE_INSUFFICIENT_STOCK (after rolling back its own holds)
+        // if any line oversells — no order is created, no holds strand. A
+        // no-op returning empty maps when no inventory handle is wired.
+        var holdResult = await _placeQuoteHolds(lines);
+        var placedHolds = holdResult.placed;
+        var heldBySku   = holdResult.heldBySku;
+        // From here until the order is committed, any throw must release the
+        // holds this conversion placed — once createFromCart succeeds the
+        // pending order owns them (its paid/cancel edge settles them) and a
+        // blanket release would double-free / eat a concurrent shopper's hold.
+        var orderCreated = false;
+        try {
+          var subtotal = 0;
+          var orderLines = [];
+          for (var i = 0; i < lines.length; i += 1) {
+            var line = lines[i];
+            var qty   = Number(line.quantity);
+            var price = Number(line.unit_price_minor);
+            subtotal += qty * price;
+            orderLines.push({
+              // The order primitive validates variant_id as a UUID.
+              // The quote primitive doesn't track variant_id (a quote
+              // is SKU-grained, not variant-grained), so synthesize a
+              // deterministic UUID per (quote, line) tuple. The
+              // operator's variant resolution happens upstream of the
+              // quote surface; the order line snapshots the sku +
+              // qty + price the customer accepted.
+              variant_id:        line.id,
+              sku:               line.sku,
+              qty:               qty,
+              unit_amount_minor: price,
+              unit_currency:     current.currency,
+              // Units this line reserved above (0 for an un-tracked SKU) so
+              // the pending order settles exactly the holds it owns.
+              stock_held_qty:    heldBySku[line.sku] ? qty : 0,
+            });
+          }
+          var shipping = current.shipping_minor == null ? 0 : Number(current.shipping_minor);
+          var tax      = current.tax_minor      == null ? 0 : Number(current.tax_minor);
+          var grand    = subtotal + shipping + tax;
+
+          var createdOrder = await orderHandle.createFromCart({
+            cart_id:           cartId,
+            session_id:        sessionId,
+            customer_id:       current.customer_id,
+            currency:          current.currency,
+            subtotal_minor:    subtotal,
+            discount_minor:    0,
+            tax_minor:         tax,
+            shipping_minor:    shipping,
+            grand_total_minor: grand,
+            ship_to:           input.ship_to,
+            lines:             orderLines,
           });
-        }
-        var shipping = current.shipping_minor == null ? 0 : Number(current.shipping_minor);
-        var tax      = current.tax_minor      == null ? 0 : Number(current.tax_minor);
-        var grand    = subtotal + shipping + tax;
-
-        var createdOrder = await orderHandle.createFromCart({
-          cart_id:           cartId,
-          session_id:        sessionId,
-          customer_id:       current.customer_id,
-          currency:          current.currency,
-          subtotal_minor:    subtotal,
-          discount_minor:    0,
-          tax_minor:         tax,
-          shipping_minor:    shipping,
-          grand_total_minor: grand,
-          ship_to:           input.ship_to,
-          lines:             orderLines,
-        });
-        orderId = createdOrder && createdOrder.id;
-        if (!orderId) {
-          throw new Error("quotes.convertToOrder: order handle did not return an order id");
+          orderCreated = true;
+          orderId = createdOrder && createdOrder.id;
+          if (!orderId) {
+            throw new Error("quotes.convertToOrder: order handle did not return an order id");
+          }
+        } catch (e) {
+          if (!orderCreated) await _releaseQuoteHolds(placedHolds);
+          throw e;
         }
       } else {
         // Caller supplies converted_order_id when no order handle is
@@ -808,6 +998,45 @@ function create(opts) {
       return await _hydrated(id);
     },
 
+    // Mint (or rotate) the customer-facing view token for a quote and return
+    // the PLAINTEXT once — the caller renders it into the link / email and
+    // never persists it. Only the SHA3-512 hash lands in the row, so the
+    // plaintext is unrecoverable from storage. Idempotent-by-rotation: each
+    // call mints a fresh token, invalidating any prior link. Returns null on
+    // an unknown quote so the caller maps to 404.
+    issueViewToken: async function (quoteId) {
+      var id = _id(quoteId, "quote_id");
+      var current = await _getQuoteRaw(id);
+      if (!current) return null;
+      var plaintext = _mintViewToken();
+      var ts = _now();
+      await query(
+        "UPDATE quotes SET view_token_hash = ?1, updated_at = ?2 WHERE id = ?3",
+        [_hashViewToken(plaintext), ts, id],
+      );
+      return { quote_id: id, plaintext_token: plaintext };
+    },
+
+    // Resolve a quote by its presented view token. Shape-checks the token,
+    // hashes it, looks up the row by hash, then constant-time-compares the
+    // stored hash before returning the hydrated quote — so a malformed or
+    // non-matching token yields null (the route maps that to 404,
+    // indistinguishable from a missing quote). Never accepts a quote id here:
+    // the token is the only key this path honours.
+    getByViewToken: async function (token) {
+      var canon;
+      try { canon = _canonicalViewToken(token); }
+      catch (_e) { return null; }
+      var hash = _hashViewToken(canon);
+      var r = await query("SELECT * FROM quotes WHERE view_token_hash = ?1", [hash]);
+      var row = r.rows[0];
+      if (!row || row.view_token_hash == null) return null;
+      if (!b.crypto.timingSafeEqual(row.view_token_hash, hash)) return null;
+      var out = _hydrateQuote(row);
+      out.lines = (await _getLinesRaw(row.id)).map(_hydrateLine);
+      return out;
+    },
+
     // List quotes for a given customer. Optional `status` narrows the
     // result; `limit` caps the page size. Sorted by updated_at DESC
     // so the customer's freshest activity surfaces first.
@@ -909,12 +1138,7 @@ function create(opts) {
         miss.code = "QUOTE_NOT_FOUND";
         throw miss;
       }
-      if (current.status !== "responded") {
-        var refused = new Error("quotes.markExpired: refused — quote is " + current.status +
-          ", only responded quotes can expire");
-        refused.code = "QUOTE_TRANSITION_REFUSED";
-        throw refused;
-      }
+      _assertTransition(current.status, "expire", "markExpired");
       if (current.valid_until == null || Number(current.valid_until) > asOf) {
         var notYet = new Error("quotes.markExpired: refused — quote " + quoteId +
           " has not yet expired (valid_until=" + current.valid_until + ", as_of=" + asOf + ")");