@blamejs/blamejs-shop 0.4.55 → 0.4.57

package/lib/winback-campaigns.js

@@ -592,6 +592,93 @@ function create(opts) {
       return _rowToCampaign(await _getCampaignRow(slug));
     },
 
+    // Re-activate an archived campaign — clears `archived_at` so the
+    // scan path picks it up again. The inverse of `archiveCampaign`.
+    // Idempotent: re-activating an already-active campaign is a no-op
+    // that returns the current shape. Throws when the campaign doesn't
+    // exist (config-time tier — an operator acting on a typo'd slug
+    // should hear about it).
+    activateCampaign: async function (slug, activateOpts) {
+      _validateSlug(slug, "slug");
+      activateOpts = activateOpts || {};
+      var now = activateOpts.now == null ? _now() : activateOpts.now;
+      _validateNonNegInt(now, "now");
+      var existing = await _getCampaignRow(slug);
+      if (!existing) {
+        throw new TypeError(
+          "winbackCampaigns.activateCampaign: campaign '" + slug + "' not found"
+        );
+      }
+      if (existing.archived_at == null) {
+        return _rowToCampaign(existing);
+      }
+      await query(
+        "UPDATE winback_campaigns SET archived_at = NULL, updated_at = ?1 WHERE slug = ?2",
+        [now, slug],
+      );
+      return _rowToCampaign(await _getCampaignRow(slug));
+    },
+
+    // List every campaign, newest-first, with an optional status
+    // filter ("active" | "archived"). The operator console reads this
+    // for the campaign table; absent a filter every campaign returns.
+    listCampaigns: async function (listOpts) {
+      listOpts = listOpts || {};
+      var status = listOpts.status;
+      var sql = "SELECT * FROM winback_campaigns";
+      if (status === "active") {
+        sql += " WHERE archived_at IS NULL";
+      } else if (status === "archived") {
+        sql += " WHERE archived_at IS NOT NULL";
+      } else if (status != null) {
+        throw new TypeError(
+          "winbackCampaigns.listCampaigns: status must be 'active' or 'archived' when supplied"
+        );
+      }
+      sql += " ORDER BY created_at DESC";
+      var rows = (await query(sql, [])).rows;
+      var out = [];
+      for (var i = 0; i < rows.length; i += 1) out.push(_rowToCampaign(rows[i]));
+      return out;
+    },
+
+    // Read the most-recent deliveries across a campaign's enrollments,
+    // newest-first, bounded by `limit` (default 100). Joins each
+    // delivery to its enrollment so the console can show which
+    // customer received which step + coupon at which time. The
+    // operator-facing delivery-log panel reads this.
+    recentDeliveriesForCampaign: async function (input) {
+      if (!input || typeof input !== "object") {
+        throw new TypeError("winbackCampaigns.recentDeliveriesForCampaign: input object required");
+      }
+      var slug = _validateSlug(input.slug, "slug");
+      var limit = input.limit == null ? 100 : input.limit;
+      _validatePositiveInt(limit, "limit");
+      if (limit > 500) limit = 500;
+      var rows = (await query(
+        "SELECT d.id AS id, d.enrollment_id AS enrollment_id, " +
+        "       d.step_index AS step_index, d.coupon_code AS coupon_code, " +
+        "       d.delivered_at AS delivered_at, e.customer_id AS customer_id " +
+        "FROM winback_deliveries d " +
+        "JOIN winback_enrollments e ON e.id = d.enrollment_id " +
+        "WHERE e.campaign_slug = ?1 " +
+        "ORDER BY d.delivered_at DESC, d.step_index DESC LIMIT ?2",
+        [slug, limit],
+      )).rows;
+      var out = [];
+      for (var i = 0; i < rows.length; i += 1) {
+        out.push({
+          id:            rows[i].id,
+          enrollment_id: rows[i].enrollment_id,
+          customer_id:   rows[i].customer_id,
+          step_index:    Number(rows[i].step_index),
+          coupon_code:   rows[i].coupon_code || null,
+          delivered_at:  Number(rows[i].delivered_at),
+        });
+      }
+      return out;
+    },
+
     // Scan the operator's order history for customers whose last
     // paid order landed inside the lapse window for each active
     // campaign + who aren't already enrolled. Returns a flat array
@@ -869,8 +956,12 @@ function create(opts) {
               suppressionReason = sup.suppression_type || "suppressed";
             }
           } catch (_e) {
-            // drop-silent — suppressions outage errs toward sending
-            // (the operator's mailer is the next gate).
+            // FAIL-CLOSED — a suppression-list outage must NOT let a
+            // marketing send slip past. Treat the unavailable check as a
+            // hit and cancel the enrollment rather than email an address
+            // that may have opted out.
+            suppressed = true;
+            suppressionReason = "suppression-check-unavailable";
           }
         }
 
@@ -887,11 +978,45 @@ function create(opts) {
           continue;
         }
 
-        // Mint a coupon for the step when applicable + route the
-        // send through the operator's email primitive. The actual
-        // send is a best-effort hook; failure here doesn't block the
-        // delivery row (the operator's worker can retry from the
-        // enrollment row).
+        // ATOMIC CLAIM — advance the FSM FIRST, so the conditional UPDATE
+        // is the single point that decides which of two overlapping ticks
+        // owns this step. The send + coupon mint happen ONLY after a
+        // winning claim (changes === 1), so a step is at-most-once: a
+        // marketing message is better missed than doubled, and a
+        // concurrent tick can't double-send or double-mint. The loser
+        // (changes === 0) skips — the winner already owns the step.
+        var nextIdx = stepIdx + 1;
+        var claim;
+        if (nextIdx >= steps.length) {
+          claim = await query(
+            "UPDATE winback_enrollments SET " +
+            "status = 'exhausted', current_step_index = ?1, " +
+            "next_step_at = NULL, updated_at = ?2 " +
+            "WHERE id = ?3 AND status = 'active' AND current_step_index = ?4",
+            [nextIdx, now, enr.id, stepIdx],
+          );
+        } else {
+          var createdAt = Number(enr.created_at);
+          var nextAt    = _nextStepAt(steps, createdAt, nextIdx);
+          claim = await query(
+            "UPDATE winback_enrollments SET " +
+            "current_step_index = ?1, next_step_at = ?2, updated_at = ?3 " +
+            "WHERE id = ?4 AND status = 'active' AND current_step_index = ?5",
+            [nextIdx, nextAt, now, enr.id, stepIdx],
+          );
+        }
+        var claimed = Number((claim && (claim.changes != null ? claim.changes : claim.rowCount)) || 0);
+        if (claimed !== 1) {
+          // A concurrent tick already advanced this step — it owns the
+          // send; skip without re-sending or re-minting.
+          continue;
+        }
+
+        // Claimed. Mint the per-step coupon (the primitive's core step
+        // action, independent of whether an address resolved — the
+        // delivery row records the coupon for a mailer retry), then route
+        // the send through the operator's email primitive. The send is
+        // best-effort: a failure doesn't roll back the claim.
         var couponCode = await _resolveCouponForStep(step, customerId);
         if (
           email &&
@@ -910,22 +1035,15 @@ function create(opts) {
               },
             });
           } catch (_e) {
-            // drop-silent — the delivery row + FSM advance still
-            // commit; the operator's mailer retries from the
-            // delivery row's coupon_code if it minted one.
+            // drop-silent — the claim already committed; the operator's
+            // mailer retries from the delivery row's coupon_code if any.
           }
         }
 
-        // Idempotency: if a delivery row already exists for this
-        // (enrollment, step_index) pair we don't write a second
-        // one. The UNIQUE index on (enrollment_id, step_index)
-        // backstops this with a hard constraint at the storage
-        // layer.
-        var prior = await query(
-          "SELECT id FROM winback_deliveries WHERE enrollment_id = ?1 AND step_index = ?2 LIMIT 1",
-          [enr.id, stepIdx],
-        );
-        if (!prior.rows[0]) {
+        // Record the delivery. Only the claiming tick reaches here, so the
+        // UNIQUE(enrollment_id, step_index) index can't collide; the
+        // try/catch is a defensive backstop that never strands the batch.
+        try {
           var deliveryId = b.uuid.v7();
           await query(
             "INSERT INTO winback_deliveries " +
@@ -933,28 +1051,7 @@ function create(opts) {
             "VALUES (?1, ?2, ?3, ?4, ?5)",
             [deliveryId, enr.id, stepIdx, couponCode, now],
           );
-        }
-
-        // Advance the FSM.
-        var nextIdx = stepIdx + 1;
-        if (nextIdx >= steps.length) {
-          await query(
-            "UPDATE winback_enrollments SET " +
-            "status = 'exhausted', current_step_index = ?1, " +
-            "next_step_at = NULL, updated_at = ?2 " +
-            "WHERE id = ?3 AND status = 'active' AND current_step_index = ?4",
-            [nextIdx, now, enr.id, stepIdx],
-          );
-        } else {
-          var createdAt = Number(enr.created_at);
-          var nextAt    = _nextStepAt(steps, createdAt, nextIdx);
-          await query(
-            "UPDATE winback_enrollments SET " +
-            "current_step_index = ?1, next_step_at = ?2, updated_at = ?3 " +
-            "WHERE id = ?4 AND status = 'active' AND current_step_index = ?5",
-            [nextIdx, nextAt, now, enr.id, stepIdx],
-          );
-        }
+        } catch (_e) { /* drop-silent — the claim already owns the step; an audit-row collision cannot cause a double-send */ }
 
         deliveries.push({
           enrollment_id: enr.id,
@@ -1274,6 +1371,69 @@ function create(opts) {
       };
     },
 
+    // One bounded cron pass over the already-wired instance: scan the
+    // order history for lapsed customers, enroll the eligible ones,
+    // then dispatch every due step through the suppression/consent-
+    // gated send path. Composes `scanForLapsedCustomers` +
+    // `enrollCustomer` + `dispatchTick` so the operator's worker fires
+    // a single call per tick rather than re-deriving the loop.
+    //
+    // Drop-silent per recipient: the dispatch loop already swallows a
+    // single send / resolver / coupon failure so one bad address never
+    // strands the batch; enroll failures are caught per-candidate here
+    // (a UNIQUE-collision from a concurrent tick is a no-op, not a
+    // batch-killer). The whole pass is idempotent — re-running it (or
+    // an overlapping tick) cannot double-enroll a customer (UNIQUE
+    // (customer_id, campaign_slug) + the existing-row return) nor
+    // double-send a step (UNIQUE (enrollment_id, step_index) + the
+    // conditional FSM advance).
+    runTick: async function (runTickOpts) {
+      runTickOpts = runTickOpts || {};
+      var now = runTickOpts.now == null ? _now() : runTickOpts.now;
+      _validateNonNegInt(now, "now");
+      var batchSize = runTickOpts.batch_size == null ? 500 : runTickOpts.batch_size;
+      _validatePositiveInt(batchSize, "batch_size");
+      var resolveEmail = runTickOpts.resolveEmail || null;
+      if (resolveEmail != null && typeof resolveEmail !== "function") {
+        throw new TypeError(
+          "winbackCampaigns.runTick: resolveEmail must be a function (enrollment) => Promise<string|null>"
+        );
+      }
+
+      var candidates = await this.scanForLapsedCustomers({
+        as_of:     now,
+        max_batch: batchSize,
+      });
+      var enrolledN = 0;
+      for (var i = 0; i < candidates.length; i += 1) {
+        try {
+          await this.enrollCustomer({
+            campaign_slug: candidates[i].campaign_slug,
+            customer_id:   candidates[i].customer_id,
+            now:           now,
+          });
+          enrolledN += 1;
+        } catch (_e) {
+          // drop-silent — a concurrent tick that already enrolled this
+          // (customer, campaign) loses the UNIQUE race; the row exists,
+          // so this pass simply moves on. Any other per-candidate fault
+          // (a vanished campaign mid-scan) likewise must not strand the
+          // rest of the batch.
+        }
+      }
+      var dispatch = await this.dispatchTick({
+        now:          now,
+        batch_size:   batchSize,
+        resolveEmail: resolveEmail,
+      });
+      return {
+        now:        now,
+        candidates: candidates.length,
+        enrolled:   enrolledN,
+        dispatched: dispatch.dispatched,
+      };
+    },
+
     // Expose the optional deps so a wiring sanity check can assert
     // they reached the factory.
     _deps: {

package/package.json

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