@blamejs/blamejs-shop 0.4.25 → 0.4.27

package/lib/compliance-export.js

@@ -11,9 +11,10 @@
  *   The primitive owns the request lifecycle + composes per-domain
  *   readers (customers, order, order-notes, subscriptions,
  *   addresses, payment-methods, support-tickets, loyalty, reviews,
- *   consent ledger, wishlist, surveys, recently-viewed) to assemble
- *   the bundle — every table that keys a row by the customer, so the
- *   export holds the whole record, not just the order/identity core.
+ *   consent ledger, wishlist, surveys, recently-viewed, suggestion
+ *   box, save-for-later, store credit) to assemble the bundle —
+ *   every table that keys a row by the customer, so the export holds
+ *   the whole record, not just the order/identity core.
  *   Delivery (email / signed URL / secure
  *   download portal) is the operator worker's concern — this
  *   primitive returns the bundle as structured JSON and stamps
@@ -83,7 +84,8 @@
  *                          orders, subscriptions, addresses, payment
  *                          methods, support tickets, loyalty, reviews,
  *                          consent ledger, wishlist, surveys,
- *                          recently-viewed).
+ *                          recently-viewed, suggestion box,
+ *                          save-for-later, store credit).
  *     - `orders_only`    — only `order` + `orderNotes` contribute;
  *                          identity / loyalty / subscriptions /
  *                          addresses / payment methods / support
@@ -101,7 +103,7 @@
  * @related    customers, order, orderNotes, subscriptions, addresses,
  *             paymentMethods, supportTickets, loyalty, reviews,
  *             consentLedger, wishlist, customerSurveys, recentlyViewed,
- *             orderExport
+ *             suggestionBox, saveForLater, storeCredit, orderExport
  */
 
 var b = require("./vendor/blamejs");
@@ -188,6 +190,11 @@ var SCOPE_SECTIONS = Object.freeze({
     "customers", "addresses", "order", "orderNotes",
     "subscriptions", "paymentMethods", "supportTickets", "loyalty",
     "reviews", "consentLedger", "wishlist", "surveys", "recentlyViewed",
+    // Customer-authored feedback (ideas + complaints, keyed by id or a
+    // hashed email), the save-for-later holdover list, and the store-
+    // credit wallet ledger — each keys a row by the customer, so a
+    // subject-access export holds them too.
+    "suggestionBox", "saveForLater", "storeCredit",
   ]),
   orders_only: Object.freeze(["order", "orderNotes"]),
   identity_only: Object.freeze(["customers", "addresses"]),
@@ -361,6 +368,9 @@ function create(opts) {
     wishlist:       opts.wishlist       || null,
     surveys:        opts.surveys        || null,
     recentlyViewed: opts.recentlyViewed || null,
+    suggestionBox:  opts.suggestionBox  || null,
+    saveForLater:   opts.saveForLater   || null,
+    storeCredit:    opts.storeCredit    || null,
   };
 
   // ---- requestExport -------------------------------------------------
@@ -609,9 +619,10 @@ function create(opts) {
     }
 
     var domainOrder = [
-      "recentlyViewed", "wishlist", "surveys", "reviews", "consentLedger",
+      "recentlyViewed", "wishlist", "saveForLater", "suggestionBox",
+      "surveys", "reviews", "consentLedger",
       "supportTickets", "orderNotes", "order", "subscriptions",
-      "paymentMethods", "loyalty", "addresses", "customers",
+      "paymentMethods", "loyalty", "storeCredit", "addresses", "customers",
     ];
     var perDomain     = [];
     var domainsAbsent = [];

package/lib/order.js

@@ -110,6 +110,14 @@ var ORDER_STATES = Object.freeze([
   "pending", "paid", "fulfilling", "shipped", "delivered", "refunded", "cancelled",
 ]);
 
+// The proof routes a guest-order reconciliation can be attributed to.
+// "verified-email" = an OIDC sign-in whose provider verified the address;
+// "magic-link" = the buyer clicked a sign-in link emailed to the address.
+// Both prove control of the email — the trust anchor for the attach. An
+// unknown linked_via falls back to "verified-email" so a typo can't write
+// an unfiltered audit string.
+var RECONCILE_LINKED_VIA = Object.freeze(["verified-email", "magic-link"]);
+
 // Cursor key for listForCustomer — paginates by (updated_at DESC, id
 // DESC) so a newly transitioned order surfaces at the top of the
 // customer's order history without a stable-id tie-break flake.
@@ -1051,22 +1059,98 @@ function create(opts) {
 
     // Claim guest orders into a customer account by matching the
     // recorded buyer-email hash. The CALLER must only pass a hash for an
-    // email the identity provider VERIFIED — this method does not (and
-    // cannot) re-verify; linking an unverified email would be account
-    // takeover. Only touches orders with no owner yet (customer_id IS
-    // NULL), so it never re-assigns another customer's order. Returns
-    // the count linked.
-    linkGuestOrdersByEmailHash: async function (customerId, emailHash) {
+    // email the identity provider VERIFIED (an OIDC email_verified claim)
+    // or the buyer has otherwise proven control of (clicking an emailed
+    // magic-link) — this method does not (and cannot) re-verify; linking
+    // an unverified email would be account takeover. Only touches orders
+    // with no owner yet (customer_id IS NULL), so it never re-assigns
+    // another customer's order.
+    //
+    // Each newly-attached order also gets one append-only row in
+    // guest_order_reconciliations recording WHEN it was attached, to WHICH
+    // customer, by WHICH proof (linked_via), and the email_hash matched —
+    // so a disputed link is traceable and an operator/DSR review can replay
+    // it without inferring it from a customer_id that was overwritten. The
+    // audit row is the verified linking key only (the plaintext address is
+    // never stored anywhere).
+    //
+    // Idempotent at BOTH layers: the per-order claim-guard UPDATE only
+    // flips a still-unowned order (so a re-run links nothing new), and the
+    // audit INSERT is INSERT-OR-IGNORE against a UNIQUE (order_id,
+    // customer_id) index (so even a forced re-write records nothing new).
+    // The audit table is optional — when the migration hasn't run (a
+    // partial-schema test, or a deploy mid-migration) the INSERT throws and
+    // is swallowed so reconciliation never fails on the audit write; the
+    // attach (the load-bearing effect) still lands.
+    //
+    // `linkedVia` names the proof route — defaulted + constrained to a known
+    // token so a typo can't write an unfiltered string; an unknown value
+    // falls back to "verified-email". Returns the count linked.
+    linkGuestOrdersByEmailHash: async function (customerId, emailHash, opts2) {
       _uuid(customerId, "customer id");
       if (typeof emailHash !== "string" || !emailHash.length) {
         throw new TypeError("order.linkGuestOrdersByEmailHash: emailHash must be a non-empty string");
       }
-      var r = await query(
-        "UPDATE orders SET customer_id = ?1, updated_at = ?2 " +
-        "WHERE customer_id IS NULL AND customer_email_hash = ?3",
-        [customerId, _now(), emailHash],
-      );
-      return Number(r.rowCount || 0);
+      var linkedVia = (opts2 && opts2.linked_via) || "verified-email";
+      if (RECONCILE_LINKED_VIA.indexOf(linkedVia) === -1) linkedVia = "verified-email";
+
+      // The candidate set: every still-unowned order placed under this
+      // verified email. Claiming per-id (not one bulk UPDATE) is what lets
+      // the audit trail name the exact orders attached AND keeps the attach
+      // race-safe — a concurrent reconciliation for the same email can't
+      // double-claim because each UPDATE re-checks customer_id IS NULL.
+      var candidates = (await query(
+        "SELECT id FROM orders WHERE customer_id IS NULL AND customer_email_hash = ?1",
+        [emailHash],
+      )).rows;
+      var linked = 0;
+      for (var i = 0; i < candidates.length; i += 1) {
+        var orderId = candidates[i].id;
+        var ts = _now();
+        // Claim-guard: only flip an order STILL unowned at write time.
+        var upd = await query(
+          "UPDATE orders SET customer_id = ?1, updated_at = ?2 " +
+          "WHERE id = ?3 AND customer_id IS NULL",
+          [customerId, ts, orderId],
+        );
+        if (Number(upd.rowCount || 0) === 0) continue; // lost the race — another writer claimed it.
+        linked += 1;
+        // Append-only audit row. INSERT OR IGNORE against the UNIQUE
+        // (order_id, customer_id) index, so a re-run records nothing new.
+        // Swallowed on a missing-table error so the attach never fails on
+        // the audit write (the attach already landed above).
+        try {
+          await query(
+            "INSERT OR IGNORE INTO guest_order_reconciliations " +
+            "(id, order_id, customer_id, email_hash, linked_via, occurred_at) " +
+            "VALUES (?1, ?2, ?3, ?4, ?5, ?6)",
+            [b.uuid.v7(), orderId, customerId, emailHash, linkedVia, ts],
+          );
+        } catch (_e) { /* drop-silent — audit table optional; the attach is the load-bearing effect */ }
+      }
+      return linked;
+    },
+
+    // Every guest order reconciled into a customer account, newest first —
+    // the operator/DSR "how did this order get attached?" view. Returns the
+    // append-only audit rows (order_id, email_hash, linked_via, occurred_at)
+    // for the customer; an account that never claimed a guest order returns
+    // []. Defensive: when the audit table hasn't been migrated yet the read
+    // throws and is collapsed to [] (the feature degrades to "no trail",
+    // never a 500).
+    reconciliationsForCustomer: async function (customerId) {
+      _uuid(customerId, "customer id");
+      try {
+        var rows = (await query(
+          "SELECT id, order_id, customer_id, email_hash, linked_via, occurred_at " +
+          "FROM guest_order_reconciliations WHERE customer_id = ?1 " +
+          "ORDER BY occurred_at DESC, id DESC",
+          [customerId],
+        )).rows;
+        return rows;
+      } catch (_e) {
+        return [];
+      }
     },
 
     // Has this customer purchased this product? True iff an order

package/lib/quotes.js

@@ -22,6 +22,7 @@
  *
  *     requested -> responded -> accepted -> converted   (happy path)
  *                          |
+ *                          +-> responded              (reprice — operator revises the offer)
  *                          +-> rejected               (customer says no)
  *                          +-> expired                (valid_until passed)
  *                          +-> cancelled              (cancelled before accept)
@@ -34,8 +35,17 @@
  *     expired    -> *                                 (terminal)
  *
  *   `valid_until` is the operator-set expiry timestamp (ms). After
- *   it elapses, `listExpired({ as_of })` surfaces the row so a
- *   cron / dunning job can transition it to `expired`.
+ *   it elapses, `listExpired({ as_of })` surfaces the row and
+ *   `expireDue({ as_of })` — driven by the worker cron's
+ *   `/_/quote-expiry-tick` — transitions each due row to `expired`
+ *   through the same atomic status claim every other verb uses, so
+ *   a concurrent accept / reprice and the sweep can never both win.
+ *
+ *   `response_version` counts the operator's pricing passes:
+ *   `respondToQuote` stamps 1, each `repriceQuote` on a
+ *   still-responded quote increments it. The customer's view-token
+ *   link is NOT rotated by a reprice — the link they already hold
+ *   resolves the same row and renders the new pricing.
  *
  *   `total_minor` is the operator-quoted grand total — the sum of
  *   the quote_lines line-totals plus `shipping_minor` + `tax_minor`.
@@ -78,6 +88,10 @@
  *                      tax_minor?, valid_until, currency,
  *                      operator_notes?, delivery_terms?,
  *                      payment_terms? })
+ *     repriceQuote({ quote_id, line_prices, shipping_minor?,
+ *                    tax_minor?, valid_until, currency,
+ *                    operator_notes?, delivery_terms?,
+ *                    payment_terms? })
  *     customerAccept({ quote_id, accepted_by_customer })
  *     customerReject({ quote_id, reject_reason? })
  *     cancelQuote({ quote_id, cancel_reason })
@@ -85,10 +99,15 @@
  *     getQuote(quote_id)
  *     quotesForCustomer(customer_id, { status?, limit? })
  *     pendingResponse({ limit? })
- *     listExpired({ as_of })
+ *     listByStatus({ status, limit? })
+ *     listExpired({ as_of, limit? })
+ *     expireDue({ as_of, limit? })
+ *     markExpired({ quote_id, as_of })
  *
  *   Storage: `migrations-d1/0102_quotes.sql` — two tables, `quotes`
  *     + `quote_lines`. ON DELETE CASCADE from quote -> lines.
+ *     `0227_quote_response_version.sql` adds the response_version
+ *     revision counter.
  *
  * @primitive quotes
  * @related   b.fsm, b.uuid, b.guardUuid, shop.cart, shop.order
@@ -152,6 +171,7 @@ var b = require("./vendor/blamejs");
 // fires it:
 //
 //   respond   requested            -> responded   (operator prices the quote)
+//   reprice   responded            -> responded   (operator revises the offer)
 //   accept    responded            -> accepted    (customer accepts)
 //   reject    responded            -> rejected    (customer declines)
 //   cancel    requested|responded  -> cancelled   (either side pulls it)
@@ -163,6 +183,7 @@ var b = require("./vendor/blamejs");
 var QUOTE_TRANSITIONS = Object.freeze([
   { from: "requested", to: "responded", on: "respond" },
   { from: "requested", to: "cancelled", on: "cancel" },
+  { from: "responded", to: "responded", on: "reprice" },
   { from: "responded", to: "accepted",  on: "accept" },
   { from: "responded", to: "rejected",  on: "reject" },
   { from: "responded", to: "cancelled", on: "cancel" },
@@ -454,6 +475,7 @@ function _hydrateQuote(row) {
     tax_minor:            row.tax_minor            == null ? null : Number(row.tax_minor),
     total_minor:          row.total_minor          == null ? null : Number(row.total_minor),
     currency:             row.currency == null ? null : row.currency,
+    response_version:     row.response_version == null ? null : Number(row.response_version),
     valid_until:          row.valid_until == null ? null : Number(row.valid_until),
     accepted_at:          row.accepted_at == null ? null : Number(row.accepted_at),
     accepted_by_customer: row.accepted_by_customer == null ? null : row.accepted_by_customer,
@@ -590,6 +612,101 @@ function create(opts) {
     }
   }
 
+  // Shared body of respondToQuote (event "respond", requested -> responded)
+  // and repriceQuote (event "reprice", responded -> responded). Validates the
+  // full pricing payload, asks the FSM whether the edge is legal for the
+  // row's CURRENT status, recomputes the totals server-side, then claims the
+  // transition atomically (`AND status = <the legal from-state>`) so a
+  // concurrent accept / reject / cancel / expire sweep and this write can
+  // never both commit. respond stamps response_version = 1; reprice
+  // increments it (COALESCE'd so a row priced before the column shipped
+  // lands on 2). Neither path touches view_token_hash — the customer's
+  // existing link keeps working and renders the latest pricing.
+  async function _applyQuoteResponse(input, event, verbLabel) {
+    if (!input || typeof input !== "object") {
+      throw new TypeError("quotes." + verbLabel + ": input object required");
+    }
+    var quoteId = _id(input.quote_id, "quote_id");
+    var currency = _currency(input.currency);
+    var shipping = input.shipping_minor == null ? 0 : input.shipping_minor;
+    var tax      = input.tax_minor      == null ? 0 : input.tax_minor;
+    _moneyMinor(shipping, "shipping_minor");
+    _moneyMinor(tax,      "tax_minor");
+    var validUntil    = _ts(input.valid_until, "valid_until");
+    var operatorNotes = _optLongText(input.operator_notes, "operator_notes", MAX_OPERATOR_NOTES_LEN);
+    var delivery      = _optShortText(input.delivery_terms, "delivery_terms", MAX_TERMS_LEN);
+    var payment       = _optShortText(input.payment_terms,  "payment_terms",  MAX_TERMS_LEN);
+
+    var current = await _getQuoteRaw(quoteId);
+    if (!current) {
+      var miss = new Error("quotes." + verbLabel + ": quote " + quoteId + " not found");
+      miss.code = "QUOTE_NOT_FOUND";
+      throw miss;
+    }
+    _assertTransition(current.status, event, verbLabel);
+    // The FSM only declares this event from one source state (respond:
+    // requested, reprice: responded); having passed the assert, the row's
+    // current status IS that state — it pins the atomic claim below.
+    var fromStatus = current.status;
+
+    var lines = await _getLinesRaw(quoteId);
+    var lineSkus = lines.map(function (r) { return r.sku; });
+    var pricesBySku = _validateLinePrices(input.line_prices, lineSkus);
+
+    // valid_until must be strictly in the future. A past expiry on
+    // a fresh response / revision is operator error — the quote would
+    // be expired the moment it lands.
+    var ts = _now();
+    if (validUntil <= ts) {
+      throw new TypeError("quotes." + verbLabel + ": valid_until must be in the future");
+    }
+
+    // Compute totals from the priced lines + shipping + tax. Math
+    // is integer-only; sum is bounded by MAX_LINES *
+    // MAX_QUANTITY * MAX_UNIT_PRICE_MINOR which fits Number.
+    var subtotal = 0;
+    for (var i = 0; i < lines.length; i += 1) {
+      var qty = Number(lines[i].quantity);
+      var price = pricesBySku[lines[i].sku];
+      subtotal += qty * price;
+    }
+    var total = subtotal + shipping + tax;
+    _moneyMinor(total, "total_minor");
+
+    // Update header + each line. The line update sets unit_price_minor +
+    // currency per-line. The header UPDATE claims the transition atomically
+    // (`AND status = ?`) so a concurrent settle can't both commit against
+    // the same row — for reprice that same clause also means an accept that
+    // lands first wins and the revision refuses instead of clobbering the
+    // accepted price.
+    var versionSql = event === "respond" ? "1" : "COALESCE(response_version, 1) + 1";
+    var claim = await query(
+      "UPDATE quotes SET status = 'responded', shipping_minor = ?1, " +
+      "tax_minor = ?2, total_minor = ?3, currency = ?4, valid_until = ?5, " +
+      "operator_notes = ?6, " +
+      "response_version = " + versionSql + ", " +
+      "delivery_terms = COALESCE(?7, delivery_terms), " +
+      "payment_terms  = COALESCE(?8, payment_terms),  " +
+      "updated_at = ?9 WHERE id = ?10 AND status = ?11",
+      [shipping, tax, total, currency, validUntil, operatorNotes,
+       delivery, payment, ts, quoteId, fromStatus],
+    );
+    if (Number(claim.rowCount || 0) !== 1) {
+      var raced = new Error("quotes." + verbLabel + ": refused — quote " + quoteId +
+        " is no longer in the " + fromStatus + " state (settled by a concurrent call)");
+      raced.code = "QUOTE_TRANSITION_REFUSED";
+      throw raced;
+    }
+    for (var j = 0; j < lines.length; j += 1) {
+      var line = lines[j];
+      await query(
+        "UPDATE quote_lines SET unit_price_minor = ?1, currency = ?2 WHERE id = ?3",
+        [pricesBySku[line.sku], currency, line.id],
+      );
+    }
+    return await _hydrated(quoteId);
+  }
+
   return {
     QUOTE_STATUSES:    QUOTE_STATUSES.slice(),
     TERMINAL_STATUSES: TERMINAL_STATUSES.slice(),
@@ -714,84 +831,25 @@ function create(opts) {
     // sets shipping + tax + grand total currency, and stamps an
     // expiry. The total_minor is computed from the priced lines +
     // shipping_minor + tax_minor; the caller doesn't pass it (and
-    // can't override it — the math is the contract).
+    // can't override it — the math is the contract). Stamps
+    // response_version = 1 (the first pricing pass).
     respondToQuote: async function (input) {
-      if (!input || typeof input !== "object") {
-        throw new TypeError("quotes.respondToQuote: input object required");
-      }
-      var quoteId = _id(input.quote_id, "quote_id");
-      var currency = _currency(input.currency);
-      var shipping = input.shipping_minor == null ? 0 : input.shipping_minor;
-      var tax      = input.tax_minor      == null ? 0 : input.tax_minor;
-      _moneyMinor(shipping, "shipping_minor");
-      _moneyMinor(tax,      "tax_minor");
-      var validUntil   = _ts(input.valid_until, "valid_until");
-      var operatorNotes = _optLongText(input.operator_notes, "operator_notes", MAX_OPERATOR_NOTES_LEN);
-      var delivery     = _optShortText(input.delivery_terms, "delivery_terms", MAX_TERMS_LEN);
-      var payment      = _optShortText(input.payment_terms,  "payment_terms",  MAX_TERMS_LEN);
-
-      var current = await _getQuoteRaw(quoteId);
-      if (!current) {
-        var miss = new Error("quotes.respondToQuote: quote " + quoteId + " not found");
-        miss.code = "QUOTE_NOT_FOUND";
-        throw miss;
-      }
-      _assertTransition(current.status, "respond", "respondToQuote");
-
-      var lines = await _getLinesRaw(quoteId);
-      var lineSkus = lines.map(function (r) { return r.sku; });
-      var pricesBySku = _validateLinePrices(input.line_prices, lineSkus);
-
-      // valid_until must be strictly in the future. A past expiry on
-      // a fresh response is operator error — the quote would be
-      // expired the moment it lands.
-      var ts = _now();
-      if (validUntil <= ts) {
-        throw new TypeError("quotes.respondToQuote: valid_until must be in the future");
-      }
+      return await _applyQuoteResponse(input, "respond", "respondToQuote");
+    },
 
-      // Compute totals from the priced lines + shipping + tax. Math
-      // is integer-only; sum is bounded by MAX_LINES *
-      // MAX_QUANTITY * MAX_UNIT_PRICE_MINOR which fits Number.
-      var subtotal = 0;
-      for (var i = 0; i < lines.length; i += 1) {
-        var qty = Number(lines[i].quantity);
-        var price = pricesBySku[lines[i].sku];
-        subtotal += qty * price;
-      }
-      var total = subtotal + shipping + tax;
-      _moneyMinor(total, "total_minor");
-
-      // Update header + each line. The line update sets
-      // unit_price_minor + currency per-line so a future single-line
-      // re-quote (out of scope here) has a place to land. The header
-      // UPDATE claims the requested -> responded transition atomically
-      // (`AND status = 'requested'`) so a concurrent cancel/respond can't
-      // both commit against the same row.
-      var claim = await query(
-        "UPDATE quotes SET status = 'responded', shipping_minor = ?1, " +
-        "tax_minor = ?2, total_minor = ?3, currency = ?4, valid_until = ?5, " +
-        "operator_notes = ?6, " +
-        "delivery_terms = COALESCE(?7, delivery_terms), " +
-        "payment_terms  = COALESCE(?8, payment_terms),  " +
-        "updated_at = ?9 WHERE id = ?10 AND status = 'requested'",
-        [shipping, tax, total, currency, validUntil, operatorNotes,
-         delivery, payment, ts, quoteId],
-      );
-      if (Number(claim.rowCount || 0) !== 1) {
-        var raced = new Error("quotes.respondToQuote: refused — quote " + quoteId +
-          " is no longer in the requested state (settled by a concurrent call)");
-        raced.code = "QUOTE_TRANSITION_REFUSED";
-        throw raced;
-      }
-      for (var j = 0; j < lines.length; j += 1) {
-        var line = lines[j];
-        await query(
-          "UPDATE quote_lines SET unit_price_minor = ?1, currency = ?2 WHERE id = ?3",
-          [pricesBySku[line.sku], currency, line.id],
-        );
-      }
-      return await _hydrated(quoteId);
+    // FSM: responded -> responded (the reprice edge). Operator revises
+    // a quote the customer hasn't settled yet — improved line prices,
+    // fresh shipping / tax / validity window, an updated note. Same
+    // payload contract as respondToQuote (every line re-priced; the
+    // math is the contract), refused with QUOTE_TRANSITION_REFUSED on
+    // any other state so a settled (accepted / declined / expired /
+    // withdrawn) quote can never be silently re-opened. Increments
+    // response_version so the revision is visible on the row, and
+    // deliberately leaves view_token_hash untouched — the link the
+    // customer already holds keeps resolving and renders the new
+    // pricing.
+    repriceQuote: async function (input) {
+      return await _applyQuoteResponse(input, "reprice", "repriceQuote");
     },
 
     // FSM: responded -> accepted. Customer accepts the operator's
@@ -1176,12 +1234,39 @@ function create(opts) {
       return out;
     },
 
+    // List quotes in one lifecycle state, newest activity first — the
+    // operator console's status filter (e.g. the expired view that shows
+    // what the cron sweep transitioned). Validated against QUOTE_STATUSES
+    // so a garbage status throws rather than silently matching nothing.
+    listByStatus: async function (listOpts) {
+      if (!listOpts || typeof listOpts !== "object") {
+        throw new TypeError("quotes.listByStatus: input object required");
+      }
+      var status = _status(listOpts.status);
+      var limit = listOpts.limit == null ? DEFAULT_LIMIT : listOpts.limit;
+      if (!Number.isInteger(limit) || limit <= 0 || limit > MAX_LIMIT) {
+        throw new TypeError("quotes.listByStatus: limit must be 1..." + MAX_LIMIT);
+      }
+      var r = await query(
+        "SELECT * FROM quotes WHERE status = ?1 " +
+        "ORDER BY updated_at DESC, id DESC LIMIT ?2",
+        [status, limit],
+      );
+      var out = [];
+      for (var i = 0; i < r.rows.length; i += 1) {
+        var hydrated = _hydrateQuote(r.rows[i]);
+        hydrated.lines = (await _getLinesRaw(r.rows[i].id)).map(_hydrateLine);
+        out.push(hydrated);
+      }
+      return out;
+    },
+
     // List responded quotes whose `valid_until` has elapsed. A cron
     // job walks the result and either fires `customerAccept` (rare —
     // requires the customer-side timing) or transitions each row to
-    // expired via an operator-side step (out of scope here; the
-    // operator updates the row directly to expired via
-    // `markExpired` when they own the cron).
+    // expired via an operator-side step (`expireDue` is that sweep;
+    // `markExpired` is the single-row flip when the operator owns the
+    // cron).
     listExpired: async function (input) {
       if (!input || typeof input !== "object") {
         throw new TypeError("quotes.listExpired: input object required");
@@ -1206,6 +1291,55 @@ function create(opts) {
       return out;
     },
 
+    // One bounded expiry sweep — the worker cron's `/_/quote-expiry-tick`
+    // drives this once a minute. Scans up to `limit` responded quotes whose
+    // valid_until has elapsed as of `as_of` and flips each to expired
+    // through an atomic conditional UPDATE that re-checks BOTH the status
+    // AND the elapsed expiry, so:
+    //   - two overlapping ticks can't double-transition a row (the loser's
+    //     UPDATE matches nothing and is counted as skipped, not an error);
+    //   - a customer accept / reject / operator cancel that lands between
+    //     the scan and the flip wins — the flip refuses;
+    //   - a reprice that lands in that window and pushes valid_until back
+    //     into the future also wins — the `valid_until <= as_of` re-check
+    //     keeps a freshly revised quote alive.
+    // Per-row failures never abort the pass; the summary reports what
+    // happened. Input validation throws (a cron caller with a bad clock /
+    // batch size is a config bug to surface, not to swallow).
+    expireDue: async function (input) {
+      if (!input || typeof input !== "object") {
+        throw new TypeError("quotes.expireDue: input object required");
+      }
+      var asOf = _ts(input.as_of, "as_of");
+      var limit = input.limit == null ? DEFAULT_LIMIT : input.limit;
+      if (!Number.isInteger(limit) || limit <= 0 || limit > MAX_LIMIT) {
+        throw new TypeError("quotes.expireDue: limit must be 1..." + MAX_LIMIT);
+      }
+      // The machine is the single source of truth for the expire edge — the
+      // sweep's `status = 'responded'` claims below encode the same source
+      // state, and this assert keeps them honest if the FSM ever changes.
+      _assertTransition("responded", "expire", "expireDue");
+      var r = await query(
+        "SELECT id FROM quotes WHERE status = 'responded' " +
+        "AND valid_until IS NOT NULL AND valid_until <= ?1 " +
+        "ORDER BY valid_until ASC, id ASC LIMIT ?2",
+        [asOf, limit],
+      );
+      var expired = 0;
+      var skipped = 0;
+      for (var i = 0; i < r.rows.length; i += 1) {
+        var claim = await query(
+          "UPDATE quotes SET status = 'expired', updated_at = ?1 " +
+          "WHERE id = ?2 AND status = 'responded' " +
+          "AND valid_until IS NOT NULL AND valid_until <= ?3",
+          [asOf, r.rows[i].id, asOf],
+        );
+        if (Number(claim.rowCount || 0) === 1) expired += 1;
+        else skipped += 1;
+      }
+      return { scanned: r.rows.length, expired: expired, skipped: skipped };
+    },
+
     // Operator-side expiry flip. Walks a single quote whose
     // valid_until has elapsed and moves it from responded -> expired.
     // Refuses if the quote is not in the responded state or if the

package/lib/save-for-later.js

@@ -56,6 +56,12 @@
  *       current; returns the count of rows actually changed.
  *     - `expireOlderThan(days)` — operator-scheduler entry point
  *       that prunes saves older than the supplied age.
+ *     - `exportForCustomer(customer_id)` — DSR export reader: the
+ *       subject's saved rows.
+ *     - `eraseForCustomer(customer_id, { dry_run? })` — DSR erasure:
+ *       deletes the subject's saved rows (pure personalization, no
+ *       retention basis). Returns the `{ table, deleted }` reader
+ *       contract.
  *
  *   Storage:
  *     - `save_for_later` (migration `0041_save_for_later.sql`).
@@ -641,6 +647,46 @@ function create(opts) {
       return { changed: changed };
     },
 
+    // ---- exportForCustomer / eraseForCustomer (DSR) -----------------
+    //
+    // Subject-access-request hooks consumed by complianceExport. A
+    // save-for-later row keys directly on `customer_id` — there is no
+    // hashed-identity branch (every row is account-bound).
+    //
+    // exportForCustomer(customer_id) — the subject's saved rows. Pure
+    // read; capped at MAX_LIMIT so one customer can't unbounded-stream
+    // the export.
+    exportForCustomer: async function (customerId) {
+      var cid = _uuid(customerId, "customer_id");
+      var rows = (await query(
+        "SELECT * FROM save_for_later WHERE customer_id = ?1 " +
+        "ORDER BY saved_at DESC, id DESC LIMIT ?2",
+        [cid, MAX_LIMIT],
+      )).rows;
+      return rows;
+    },
+
+    // eraseForCustomer(customer_id, { dry_run }) — GDPR Art. 17
+    // erasure. A save-for-later list is pure personalization with no
+    // retention basis, so erasure DELETES every row for the customer
+    // (the same effect as `clear`, returned in the complianceExport
+    // reader contract shape `{ table, deleted }`). dry_run counts the
+    // rows it WOULD remove without mutating. A re-run finds none
+    // (idempotent).
+    eraseForCustomer: async function (customerId, opts) {
+      var cid = _uuid(customerId, "customer_id");
+      var dryRun = !!(opts && opts.dry_run);
+      if (dryRun) {
+        var c = (await query(
+          "SELECT COUNT(*) AS n FROM save_for_later WHERE customer_id = ?1",
+          [cid],
+        )).rows[0];
+        return { table: "save_for_later", deleted: c ? Number(c.n) : 0 };
+      }
+      var r = await query("DELETE FROM save_for_later WHERE customer_id = ?1", [cid]);
+      return { table: "save_for_later", deleted: Number(r.rowCount || 0) };
+    },
+
     // Operator scheduler entry point: remove every save older than
     // the supplied age. Returns the count of removed rows so the
     // cron / scheduled-worker layer can emit a metric.