@blamejs/blamejs-shop 0.4.18 → 0.4.20

package/lib/wishlist-alerts.js

@@ -550,16 +550,6 @@ function create(opts) {
 
   // ---- scanAndDispatch internals ----------------------------------------
 
-  async function _countAlertsThisWeek(customerId, now) {
-    var since = now - MS_PER_WEEK;
-    var r = await query(
-      "SELECT COUNT(*) AS n FROM wishlist_alerts_sent "
-      + "WHERE customer_id = ?1 AND occurred_at >= ?2",
-      [customerId, since],
-    );
-    return Number((r.rows[0] || {}).n || 0);
-  }
-
   async function _hasRecentFire(customerId, sku, policySlug, now) {
     var since = now - DEDUPE_WINDOW_MS;
     var r = await query(
@@ -571,6 +561,81 @@ function create(opts) {
     return r.rows.length > 0;
   }
 
+  // Last-observed state for a (customer, sku, policy) tuple — the memory
+  // that turns a current-state read into a transition read. NULL when the
+  // scanner has never seen this tuple.
+  async function _lastState(customerId, sku, policySlug) {
+    var r = await query(
+      "SELECT last_in_stock, last_alerted_bps FROM wishlist_alert_state "
+      + "WHERE customer_id = ?1 AND sku = ?2 AND policy_slug = ?3 LIMIT 1",
+      [customerId, sku, policySlug],
+    );
+    var row = r.rows[0];
+    if (!row) return { last_in_stock: null, last_alerted_bps: null };
+    return {
+      last_in_stock:    row.last_in_stock    == null ? null : Number(row.last_in_stock),
+      last_alerted_bps: row.last_alerted_bps == null ? null : Number(row.last_alerted_bps),
+    };
+  }
+
+  // Upsert the observed state for a tuple. Only the columns named in
+  // `patch` are written; the row's other column keeps its prior value
+  // (read once here so the UNIQUE-keyed REPLACE doesn't clobber the
+  // sibling column). `inStock` / `alertedBps` are 0/1/null and int/null.
+  async function _recordState(customerId, sku, policySlug, patch, now) {
+    var prior = await _lastState(customerId, sku, policySlug);
+    var inStock    = Object.prototype.hasOwnProperty.call(patch, "last_in_stock")
+      ? patch.last_in_stock
+      : prior.last_in_stock;
+    var alertedBps = Object.prototype.hasOwnProperty.call(patch, "last_alerted_bps")
+      ? patch.last_alerted_bps
+      : prior.last_alerted_bps;
+    // INSERT-or-UPDATE on the UNIQUE(customer_id, sku, policy_slug) key.
+    await query(
+      "INSERT INTO wishlist_alert_state "
+      + "(customer_id, sku, policy_slug, last_in_stock, last_alerted_bps, updated_at) "
+      + "VALUES (?1, ?2, ?3, ?4, ?5, ?6) "
+      + "ON CONFLICT (customer_id, sku, policy_slug) DO UPDATE SET "
+      + "last_in_stock = ?4, last_alerted_bps = ?5, updated_at = ?6",
+      [customerId, sku, policySlug, inStock, alertedBps, now],
+    );
+  }
+
+  // Atomic dedupe + weekly-cap CLAIM. Writes the sent-ledger row in a
+  // single conditional INSERT that refuses when (a) a fire for the same
+  // (customer, sku, policy) already landed inside the dedupe window, or
+  // (b) the customer is at/over the weekly cap. Because the guard and the
+  // write are one statement, two concurrent sweeps can't both pass the
+  // read and then both insert — the second's INSERT...SELECT sees the
+  // first's row and matches zero rows. Returns true when this call won
+  // the claim. Mirrors the conditional-UPDATE house pattern
+  // (catalog.inventory.adjustOnHand / hold).
+  async function _claimLedgerRow(id, customerId, policySlug, sku, now, weeklyCap) {
+    var dedupeSince = now - DEDUPE_WINDOW_MS;
+    var weekSince   = now - MS_PER_WEEK;
+    // `weeklyCap` null → no cap; encode as a sentinel the SQL treats as
+    // "always under cap" by comparing against a value the count can never
+    // reach when cap is absent.
+    var capActive = weeklyCap != null ? 1 : 0;
+    var capValue  = weeklyCap != null ? weeklyCap : 0;
+    var r = await query(
+      "INSERT INTO wishlist_alerts_sent (id, customer_id, policy_slug, sku, channel, occurred_at) "
+      + "SELECT ?1, ?2, ?3, ?4, 'email', ?5 "
+      + "WHERE NOT EXISTS ("
+      + "  SELECT 1 FROM wishlist_alerts_sent "
+      + "  WHERE customer_id = ?2 AND sku = ?4 AND policy_slug = ?3 AND occurred_at >= ?6"
+      + ") "
+      + "AND ("
+      + "  ?7 = 0 OR ("
+      + "    SELECT COUNT(*) FROM wishlist_alerts_sent "
+      + "    WHERE customer_id = ?2 AND occurred_at >= ?8"
+      + "  ) < ?9"
+      + ")",
+      [id, customerId, policySlug, sku, now, dedupeSince, capActive, weekSince, capValue],
+    );
+    return Number(r.rowCount || 0) === 1;
+  }
+
   // Walk every wishlist entry that has a non-null variant_id. Whole-
   // product (variant_id IS NULL) rows are skipped at v1 — the policy
   // evaluator can't resolve a single sku for them, and the operator-
@@ -596,9 +661,18 @@ function create(opts) {
     return defaultCurrency;
   }
 
-  // Evaluate a single (entry, policy) pair. Returns either:
-  //   { fire: true,  sku, payload }    — dispatch + ledger
-  //   { fire: false, reason }          — accounted as `skipped`
+  // Evaluate a single (entry, policy) pair against the TRANSITION from
+  // the last-observed state, not the current state in isolation. Returns:
+  //   { fire: true,  sku, payload, state }  — dispatch + ledger; `state`
+  //                                            is the observed-state patch
+  //                                            to persist (always applied,
+  //                                            fire or not).
+  //   { fire: false, reason, sku?, state? } — accounted as `skipped`; a
+  //                                            present `state` patch is
+  //                                            still persisted so the next
+  //                                            sweep reads a fresh baseline.
+  // The last-observed { last_in_stock, last_alerted_bps } for the tuple is
+  // loaded internally once the sku resolves (null fields when never seen).
   async function _evaluate(entry, policy, now) {
     // Map variant → sku.
     var variant;
@@ -608,12 +682,14 @@ function create(opts) {
     var sku = variant.sku;
     if (typeof sku !== "string" || !sku.length) return { fire: false, reason: "variant_has_no_sku" };
 
+    var prior = await _lastState(entry.customer_id, sku, policy.slug);
+
     if (policy.trigger === "price_drop") {
       var currency = await _resolveCurrency(entry.customer_id);
       var current;
       try { current = await catalog.prices.current(entry.variant_id, currency); }
       catch (_e) { current = null; }
-      if (!current) return { fire: false, reason: "no_current_price" };
+      if (!current) return { fire: false, reason: "no_current_price", sku: sku };
       var history;
       try { history = await catalog.prices.history(entry.variant_id, currency); }
       catch (_e) { history = []; }
@@ -624,16 +700,29 @@ function create(opts) {
         var h = history[i];
         if (h.effective_until != null) { baseline = h; break; }
       }
-      if (!baseline) return { fire: false, reason: "no_baseline_price" };
+      if (!baseline) return { fire: false, reason: "no_baseline_price", sku: sku };
       var baseAmt = Number(baseline.amount_minor);
       var curAmt  = Number(current.amount_minor);
       if (!(baseAmt > 0) || !(curAmt >= 0) || curAmt >= baseAmt) {
-        return { fire: false, reason: "no_drop" };
+        // No drop in effect — the price recovered to/above baseline. Clear
+        // the last-alerted level so a fresh drop later is a transition.
+        return { fire: false, reason: "no_drop", sku: sku, state: { last_alerted_bps: null } };
       }
       // Percent-off in basis points: ((base - cur) / base) * 10000.
       var bps = Math.floor(((baseAmt - curAmt) * 10000) / baseAmt);
       var threshold = Number(policy.threshold.percent_off_bps_min);
-      if (bps < threshold) return { fire: false, reason: "below_threshold" };
+      if (bps < threshold) {
+        // Below the policy gate — not an alertable drop. Don't touch the
+        // last-alerted level (a shallow dip after a deep alerted drop
+        // shouldn't reset the baseline and re-arm a re-fire).
+        return { fire: false, reason: "below_threshold", sku: sku };
+      }
+      // Transition gate: fire only on a NEW or DEEPER drop than the level
+      // we last alerted. A steady drop at the same depth must not re-fire,
+      // dedupe window or not.
+      if (prior.last_alerted_bps != null && bps <= prior.last_alerted_bps) {
+        return { fire: false, reason: "no_deeper_drop", sku: sku };
+      }
       return {
         fire: true,
         sku:  sku,
@@ -644,6 +733,12 @@ function create(opts) {
           new_amount_minor:  curAmt,
           discount_bps:      bps,
         },
+        // `state` is the always-record observation (none here — recording
+        // the alerted level happens only on a committed send, below).
+        // `alertedBps` is recorded post-send so a lost claim / failed
+        // mailer doesn't suppress a legitimate later re-fire.
+        state:      {},
+        alertedBps: bps,
       };
     }
 
@@ -651,9 +746,14 @@ function create(opts) {
       var inv;
       try { inv = await catalog.inventory.get(sku); }
       catch (_e) { inv = null; }
-      if (!inv) return { fire: false, reason: "inventory_unresolvable" };
+      if (!inv) return { fire: false, reason: "inventory_unresolvable", sku: sku };
       var available = Number(inv.stock_on_hand || 0) - Number(inv.stock_held || 0);
-      if (!(available > 0)) return { fire: false, reason: "still_out_of_stock" };
+      var inStockNow = available > 0 ? 1 : 0;
+      if (inStockNow === 0) {
+        // Out of stock — record the observed state so a later restock is a
+        // 0 -> 1 transition.
+        return { fire: false, reason: "still_out_of_stock", sku: sku, state: { last_in_stock: 0 } };
+      }
       // Optional dep — when wired, suppress if the customer is already
       // subscribed via the PDP "notify me" toggle. The dispatcher can
       // only know the customer's email when we know they're a logged-
@@ -668,7 +768,19 @@ function create(opts) {
         var sub;
         try { sub = await stockAlerts.isSubscribedByCustomer({ customer_id: entry.customer_id, sku: sku }); }
         catch (_e) { sub = null; }
-        if (sub && sub.subscribed === true) return { fire: false, reason: "duplicate_via_stock_alerts" };
+        // Still record the in-stock observation so the transition baseline
+        // tracks reality even when the stockAlerts path owns the send.
+        if (sub && sub.subscribed === true) {
+          return { fire: false, reason: "duplicate_via_stock_alerts", sku: sku, state: { last_in_stock: 1 } };
+        }
+      }
+      // Transition gate: fire only on the out -> in EDGE. A first
+      // observation (prior unknown) or a steady in-stock state records the
+      // observation but does not fire — there is no restock event to
+      // announce when we never saw the item go out.
+      var isRestock = prior.last_in_stock === 0;
+      if (!isRestock) {
+        return { fire: false, reason: "no_restock_transition", sku: sku, state: { last_in_stock: 1 } };
       }
       return {
         fire: true,
@@ -677,6 +789,7 @@ function create(opts) {
           variant_id: entry.variant_id,
           available:  available,
         },
+        state: { last_in_stock: 1 },
       };
     }
 
@@ -722,8 +835,10 @@ function create(opts) {
       no_baseline_price:            0,
       no_current_price:             0,
       no_drop:                      0,
+      no_deeper_drop:               0,
       below_threshold:              0,
       still_out_of_stock:           0,
+      no_restock_transition:        0,
       inventory_unresolvable:       0,
       variant_unresolvable:         0,
       variant_has_no_sku:           0,
@@ -738,19 +853,25 @@ function create(opts) {
       for (var pp = 0; pp < scannablePolicies.length; pp += 1) {
         var policy = scannablePolicies[pp];
 
-        // Cheapest cuts first.
+        // Cheapest cut first.
         var optedOut = await isUnsubscribedFromTrigger(entry.customer_id, policy.trigger);
         if (optedOut) { skipped += 1; skippedBy.unsubscribed += 1; continue; }
 
-        if (policy.max_alerts_per_week_per_customer != null) {
-          var weekN = await _countAlertsThisWeek(entry.customer_id, now);
-          if (weekN >= policy.max_alerts_per_week_per_customer) {
-            skipped += 1; skippedBy.weekly_cap_reached += 1; continue;
-          }
+        // Evaluate against the TRANSITION from the last-observed state —
+        // a steady in-stock / steady-depth-drop state never re-fires. The
+        // sku isn't known until the variant resolves inside _evaluate, so
+        // it loads the prior state for the resolved tuple itself.
+        var v = await _evaluate(entry, policy, now);
+
+        // Persist the always-record observation (current in-stock state /
+        // a cleared drop) regardless of fire, so the next sweep reads a
+        // fresh baseline even when this one didn't send. An empty patch
+        // (a price_drop fire — its alerted level is recorded only after a
+        // committed send) is a no-op, so skip the write.
+        if (v.sku && v.state && Object.keys(v.state).length > 0) {
+          await _recordState(entry.customer_id, v.sku, policy.slug, v.state, now);
         }
 
-        // Evaluate the policy condition.
-        var v = await _evaluate(entry, policy, now);
         if (!v.fire) {
           skipped += 1;
           if (skippedBy[v.reason] != null) skippedBy[v.reason] += 1;
@@ -758,13 +879,10 @@ function create(opts) {
           continue;
         }
 
-        // Per-(customer, sku, policy) recent-fire suppression.
-        var dup = await _hasRecentFire(entry.customer_id, v.sku, policy.slug, now);
-        if (dup) { skipped += 1; skippedBy.recent_dedupe += 1; continue; }
-
         candidates += 1;
 
-        // Resolve the customer's email. Absent → no_email, skipped.
+        // Resolve the customer's email. Absent → no_email, skipped — we
+        // never claim a ledger row we can't send.
         var customerEmail = null;
         if (emailForCustomer) {
           try { customerEmail = await emailForCustomer(entry.customer_id); }
@@ -774,6 +892,27 @@ function create(opts) {
           skipped += 1; skippedBy.no_email += 1; continue;
         }
 
+        // Atomic dedupe + weekly-cap CLAIM. The conditional INSERT is the
+        // serialization point: two concurrent sweeps can't both pass the
+        // dedupe/cap guard and then both write — the loser's INSERT...
+        // SELECT sees the winner's row and matches zero rows.
+        var id = b.uuid.v7();
+        var ts = _monotonicTs(now);
+        var claimed = await _claimLedgerRow(
+          id, entry.customer_id, policy.slug, v.sku, ts,
+          policy.max_alerts_per_week_per_customer,
+        );
+        if (!claimed) {
+          // Lost the claim — either a recent dedupe fire or the weekly
+          // cap. Distinguish for accurate accounting (read-only; the
+          // mutation already serialized at the INSERT).
+          var dup = await _hasRecentFire(entry.customer_id, v.sku, policy.slug, ts);
+          skipped += 1;
+          if (dup) skippedBy.recent_dedupe += 1;
+          else     skippedBy.weekly_cap_reached += 1;
+          continue;
+        }
+
         // Resolve a product title for the email. Best-effort — falls
         // through to the sku string when the catalog read fails.
         var productTitle = v.sku;
@@ -810,20 +949,20 @@ function create(opts) {
           dispatchOk = true;
         } catch (_e4) {
           // Drop-silent at the row level — a flapping mailer must not
-          // poison the rest of the scan. Account in skipped.
+          // poison the rest of the scan. Release the claimed ledger row
+          // so a later sweep retries instead of being suppressed by the
+          // dedupe window for a send that never happened.
+          await query("DELETE FROM wishlist_alerts_sent WHERE id = ?1", [id]);
           skipped += 1; skippedBy.email_dispatch_failed += 1; continue;
         }
         if (!dispatchOk) continue;
 
-        // Ledger write — the source of truth for "we already fired
-        // this alert" + the dedupe window.
-        var id = b.uuid.v7();
-        var ts = _monotonicTs(now);
-        await query(
-          "INSERT INTO wishlist_alerts_sent (id, customer_id, policy_slug, sku, channel, occurred_at) "
-          + "VALUES (?1, ?2, ?3, ?4, ?5, ?6)",
-          [id, entry.customer_id, policy.slug, v.sku, "email", ts],
-        );
+        // Committed send — record the alerted depth so the same drop
+        // depth is steady on the next sweep (price_drop only; the
+        // back_in_stock observation was already recorded above).
+        if (v.alertedBps != null) {
+          await _recordState(entry.customer_id, v.sku, policy.slug, { last_alerted_bps: v.alertedBps }, ts);
+        }
         sent += 1;
       }
     }

package/lib/wishlist-digest.js

@@ -972,7 +972,20 @@ function create(opts) {
         "VALUES (?1, ?2, ?3, ?4)",
         [sentId, enrollment.id, sentItemCount, sentAt],
       );
+      // Advance the cadence. The normal step is one period past the
+      // current next_dispatch_at — that keeps the schedule aligned to its
+      // target weekday / day-of-month when the tick fires on time. But a
+      // STALE enrollment (the cron was down, or the customer enrolled long
+      // ago) has a next_dispatch_at many periods in the past; advancing it
+      // one period at a time would leave it still due, so the very next
+      // tick re-fires, and a subscriber gets one digest per tick until the
+      // schedule catches up — a flood. Instead, when one period still
+      // doesn't clear `now`, snap straight to the next occurrence strictly
+      // after `now`. The catch-up costs at most ONE digest, never a storm.
       var nextDispatchAt = _advanceByOnePeriod(schedule, Number(enrollment.next_dispatch_at));
+      if (nextDispatchAt <= now) {
+        nextDispatchAt = _nextDispatchAt(schedule, now);
+      }
       await query(
         "UPDATE wishlist_digest_enrollments SET next_dispatch_at = ?1 WHERE id = ?2",
         [nextDispatchAt, enrollment.id],

package/package.json

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