@blamejs/blamejs-shop 0.4.55 → 0.4.56

package/CHANGELOG.md

@@ -8,6 +8,8 @@ upgrading across more than a few patches at a time.
 
 ## v0.4.x
 
+- v0.4.56 (2026-06-14) — **Win-back campaigns: re-engage lapsed customers with an escalating sequence of offers.** A new operator console defines win-back campaigns that re-engage customers who have not ordered in a while. A campaign sets a lapse window and an escalating sequence of steps, each with its own delay and an optional coupon. A scheduled pass enrols customers who cross the lapse window and sends each due step through the store's email transport, minting the step's coupon. The send is gated for consent and deliverability: a customer who has withdrawn marketing-email consent or sits on the marketing suppression list is never emailed, and an opted-out customer is removed from the sequence so no later step reaches them — and if the suppression check itself is unavailable the send is held rather than risked. Each step is sent at most once even if two scheduled passes overlap. Campaigns are inert until an operator creates and activates one and the store's email transport is configured. No migration to apply. **Added:** *Win-back campaign console + scheduled send* — Operators can create, list, activate, pause, and archive win-back campaigns from a new loyalty/marketing console screen: a lapse window plus an escalating sequence of steps, each with a delay and an optional coupon (a single-use, per-customer discount code minted when the step sends). A scheduled pass scans for lapsed customers, enrols them, advances each enrolment through the sequence, sends the due step via the store's email transport, and records a delivery log and per-campaign metrics. Every send is consent- and suppression-gated: a customer who withdrew marketing-email consent or is on the marketing suppression list is never emailed and is dropped from the sequence; a suppression-check outage holds the send rather than risking an unwanted message. The scheduled pass is idempotent — a step is sent at most once even if two passes overlap. The feature is inert until a campaign is created and activated and the email transport is configured.
+
 - v0.4.55 (2026-06-14) — **Refresh the vendored blamejs framework to 0.15.12.** Refreshes the vendored blamejs framework from 0.15.11 to 0.15.12, a sweep of defense-in-depth hardening the shop picks up by composing the framework. The body parser no longer echoes a caught exception's internal detail (a filesystem errno and temp path, or a parse hook's thrown message) to the HTTP client — the client gets a generic status phrase while the full detail stays on the server-side audit chain. Filename guarding now strips every reserved character rather than only the first. The boot-time logger escapes bidirectional and control characters on every sink, closing a terminal log-forging and line-reordering vector. Structured-field string values (used by HTTP Message Signatures, Client Hints, and Cache-Control) are now decoded in a single conformant pass, the HTTP Message Signature content-digest check matches in constant time against the exact digest member, and any outbound TLS connection that runs with certificate validation disabled now emits an audit event so the degraded posture is visible. This refresh carries no shop-facing API change and applies no migration; it keeps the bundled framework current and the security posture aligned with the latest release. **Changed:** *Vendored blamejs refreshed to 0.15.12* — The bundled framework is updated to blamejs 0.15.12. It redacts internal error detail from body-parser error responses (the client gets a generic status phrase; full diagnostics stay on the audit chain), strips every reserved character in filename guarding instead of only the first, escapes bidirectional and control characters in the boot logger on every sink (Trojan-Source / log-forging defense), decodes RFC 8941 structured-field strings in a single conformant pass, verifies the HTTP Message Signature content-digest by exact constant-time member match, and emits an audit event whenever an outbound TLS connection is configured to skip certificate validation. No shop API change; the framework's PQC-first crypto, security middleware, and request lifecycle are carried forward as-is.
 
 - v0.4.54 (2026-06-14) — **The rewards page now shows what a customer's loyalty tier includes and their progress to the next tier.** A signed-in customer's rewards page now shows their current loyalty tier, how many points remain to reach the next tier (with a progress bar), and the perks their tier includes. Operators author the per-tier perks from a new console screen — free shipping over a threshold, a percent discount, early or exclusive access, priority support, or a birthday bonus. The perks are presented to customers as what their tier includes and that the shop honours them; they are not applied automatically at checkout, so the wording never promises an automatic discount the store doesn't yet apply. No migration to apply. **Added:** *Loyalty tier perks and next-tier progress on the rewards page* — The /account rewards page gains two sections: a tier-progress panel naming the customer's current tier and the points still needed to reach the next one (with a labelled progress bar, or a top-tier acknowledgement), and a list of the perks the customer's tier includes. The tier is resolved from the customer's own loyalty balance; the perks come from the operator-authored tier-benefit definitions. The perks are framed as tier inclusions the shop honours — the copy directs the customer to ask at checkout or contact support to have a perk applied — rather than implying an automatic discount. · *Tier-benefit authoring in the loyalty console* — A new admin screen under the loyalty console lets operators define the perks each tier includes: free shipping (optionally over a minimum order), a percent discount, early access (hours before general release), priority support (an SLA in minutes), exclusive access to a collection, or a birthday bonus. Benefits are created and archived from the screen, each change recorded to the audit trail under the loyalty permission. The screen states that these perks are shown to customers as tier inclusions the shop honours and are not applied automatically at checkout.

package/lib/admin.js

@@ -155,7 +155,7 @@ var _ACTION_PERMISSION = Object.freeze({
   gift: "catalog.write", preorder: "catalog.write", quantity_discount: "catalog.write",
   auto_discount: "catalog.write", coupon_policy: "catalog.write",
   promo_banner: "catalog.write", announcement: "catalog.write", blog: "catalog.write",
-  email_campaign: "catalog.write", suggestion: "catalog.write", sidebar_widget: "catalog.write",
+  email_campaign: "catalog.write", winback_campaign: "catalog.write", suggestion: "catalog.write", sidebar_widget: "catalog.write",
   page: "catalog.write", help: "catalog.write", survey: "catalog.write",
   hours: "catalog.write", delivery_holiday: "catalog.write",
   delivery_transit: "catalog.write", tax_rate: "catalog.write",
@@ -889,6 +889,7 @@ function mount(router, deps) {
   var convertQuoteToOrder = deps.convertQuoteToOrder || null; // quote → pending-order converter (server.js composition); the console convert action disabled when absent
   var emailCampaigns     = deps.emailCampaigns     || null; // consent-gated broadcast/campaign console disabled when absent
   var mailingAudiences   = deps.mailingAudiences   || null; // audience picker for the campaign console (target-an-audience dropdown)
+  var winback            = deps.winback            || null; // win-back lapsed-customer campaign console (define/list/activate/archive + metrics + delivery log) disabled when absent
   // Read-only activity log at /admin/audit. Defaults ON — the framework
   // audit chain is always booted by createApp, so the screen always has a
   // data source (unlike the optional primitives above, which default off).
@@ -937,7 +938,7 @@ function mount(router, deps) {
   // `reports` is always present in the nav (read-only sales summary needs no
   // extra dep); its route mounts unconditionally and renders an unconfigured
   // notice when the salesReports primitive isn't wired.
-  var navAvailable = { analytics: !!deps.analytics, returns: !!returns, reviews: !!reviews, productQa: !!productQa, subscriptions: !!deps.subscriptions, preorder: !!deps.preorder, webhooks: !!deps.webhooks, collections: !!deps.collections, customers: !!deps.customers, customerSegments: !!customerSegments, giftcards: !!deps.giftcards, announcementBar: !!deps.announcementBar, promoBanners: !!deps.promoBanners, suggestionBox: !!deps.suggestionBox, sidebarWidgets: !!deps.sidebarWidgets, blog: !!deps.blog, knowledgeBase: !!deps.knowledgeBase, customerSurveys: !!deps.customerSurveys, storefrontPages: !!deps.storefrontPages, businessHours: !!deps.businessHours, taxRates: !!deps.taxRates, shippingZones: !!deps.shippingZones, deliveryEstimate: !!deps.deliveryEstimate, autoDiscount: !!deps.autoDiscount, discountAllocation: !!deps.discountAllocation, quantityDiscounts: !!deps.quantityDiscounts, loyalty: !!deps.loyalty, pickLists: !!pickLists, salesTaxFilings: !!salesTaxFilings, shippingLabels: !!shippingLabels, supportTickets: !!supportTickets, complianceExport: !!complianceExport, orderExchanges: !!orderExchanges, orderRatings: !!orderRatings, clickAndCollect: !!clickAndCollect, giftOptions: !!giftOptions, searchRanking: !!searchRanking, searchSuggestions: !!searchSuggestions, trustBadges: !!trustBadges, orderExport: !!orderExport, auditLog: auditLog, errorLog: !!errorLog, carts: !!cart, inventoryLocations: !!inventoryLocations, inventoryReceive: !!inventoryReceive, stockTransfers: !!stockTransfers, inventoryWriteoffs: !!inventoryWriteoffs, quotes: !!deps.quotes, emailCampaigns: !!emailCampaigns, operators: !!operatorAccounts, inbox: !!operatorInbox };
+  var navAvailable = { analytics: !!deps.analytics, returns: !!returns, reviews: !!reviews, productQa: !!productQa, subscriptions: !!deps.subscriptions, preorder: !!deps.preorder, webhooks: !!deps.webhooks, collections: !!deps.collections, customers: !!deps.customers, customerSegments: !!customerSegments, giftcards: !!deps.giftcards, announcementBar: !!deps.announcementBar, promoBanners: !!deps.promoBanners, suggestionBox: !!deps.suggestionBox, sidebarWidgets: !!deps.sidebarWidgets, blog: !!deps.blog, knowledgeBase: !!deps.knowledgeBase, customerSurveys: !!deps.customerSurveys, storefrontPages: !!deps.storefrontPages, businessHours: !!deps.businessHours, taxRates: !!deps.taxRates, shippingZones: !!deps.shippingZones, deliveryEstimate: !!deps.deliveryEstimate, autoDiscount: !!deps.autoDiscount, discountAllocation: !!deps.discountAllocation, quantityDiscounts: !!deps.quantityDiscounts, loyalty: !!deps.loyalty, pickLists: !!pickLists, salesTaxFilings: !!salesTaxFilings, shippingLabels: !!shippingLabels, supportTickets: !!supportTickets, complianceExport: !!complianceExport, orderExchanges: !!orderExchanges, orderRatings: !!orderRatings, clickAndCollect: !!clickAndCollect, giftOptions: !!giftOptions, searchRanking: !!searchRanking, searchSuggestions: !!searchSuggestions, trustBadges: !!trustBadges, orderExport: !!orderExport, auditLog: auditLog, errorLog: !!errorLog, carts: !!cart, inventoryLocations: !!inventoryLocations, inventoryReceive: !!inventoryReceive, stockTransfers: !!stockTransfers, inventoryWriteoffs: !!inventoryWriteoffs, quotes: !!deps.quotes, emailCampaigns: !!emailCampaigns, winback: !!winback, operators: !!operatorAccounts, inbox: !!operatorInbox };
 
   try { b.audit.registerNamespace(AUDIT_NAMESPACE); } catch (_e) { /* idempotent */ }
 
@@ -6868,6 +6869,220 @@ function mount(router, deps) {
     ));
   }
 
+  // ---- win-back campaigns ---------------------------------------------
+  //
+  // Escalating re-engagement sequences for customers who've gone quiet —
+  // the last paid order is N days in the past. The operator defines a
+  // campaign (lapse window + ordered steps, each with an optional
+  // per-step coupon), and the campaign-send-tick cron scans the order
+  // history, enrolls the eligible, and sends the due step through the
+  // SAME suppression + marketing-consent gate every marketing flow uses.
+  // This console is the author/list/activate/archive + metrics/delivery-
+  // log side; the send itself rides the cron (server.js + worker).
+  //
+  // Steps are authored one-per-line as `delay_days | template_slug |
+  // coupon_kind | coupon_value` (the last two optional). defineCampaign
+  // validates the whole shape and THROWS a TypeError on anything bad,
+  // which the create route maps to a 400 / err redirect — no partial
+  // write. Every operator-authored field rendered back is esc()'d in the
+  // render functions below.
+  if (winback) {
+    // Parse the textarea step lines into the steps array the primitive
+    // expects. A blank line is skipped; a malformed line surfaces as a
+    // TypeError so the create route's catch redirects with `?err=steps`
+    // rather than silently dropping a step. `delay_days` is a
+    // non-negative int; `coupon_value` is parsed only when a kind is
+    // present (free_shipping carries no value).
+    function _winbackStepsFromBody(raw) {
+      if (typeof raw !== "string") {
+        throw new TypeError("winback: steps required");
+      }
+      var lines = raw.split(/\r?\n/);
+      var steps = [];
+      for (var i = 0; i < lines.length; i += 1) {
+        var line = lines[i].trim();
+        if (!line) continue;
+        var parts = line.split("|").map(function (p) { return p.trim(); });
+        var delayRaw = parts[0];
+        var delay = parseInt(delayRaw, 10);
+        if (String(delay) !== delayRaw || !Number.isInteger(delay) || delay < 0) {
+          throw new TypeError("winback: step line " + (i + 1) + " — delay_days must be a non-negative integer");
+        }
+        var step = { delay_days: delay, template_slug: parts[1] };
+        if (parts[2]) {
+          step.coupon_kind = parts[2];
+          if (parts[2] !== "free_shipping") {
+            var val = parseInt(parts[3], 10);
+            if (String(val) !== (parts[3] || "") || !Number.isInteger(val)) {
+              throw new TypeError("winback: step line " + (i + 1) + " — coupon_value must be an integer for a " + parts[2] + " coupon");
+            }
+            step.coupon_value = val;
+          }
+        }
+        steps.push(step);
+      }
+      return steps;
+    }
+
+    function _winbackInput(body) {
+      var input = {
+        slug:           body.slug,
+        lapse_days_min: body.lapse_days_min != null && body.lapse_days_min !== "" ? parseInt(body.lapse_days_min, 10) : body.lapse_days_min,
+        steps:          _winbackStepsFromBody(body.steps),
+      };
+      if (body.lapse_days_max != null && body.lapse_days_max !== "") {
+        input.lapse_days_max = parseInt(body.lapse_days_max, 10);
+      }
+      // Optional audience narrowing — a minimum lifetime order count
+      // keeps a "we miss you" sequence off one-time buyers. Parsed only
+      // when supplied; an empty field clears the predicate.
+      var audience = {};
+      if (body.lifetime_orders_min != null && body.lifetime_orders_min !== "") {
+        audience.lifetime_orders_min = parseInt(body.lifetime_orders_min, 10);
+      }
+      if (Object.keys(audience).length) input.audience_filter = audience;
+      return input;
+    }
+
+    // List — every campaign (active + archived), newest-first.
+    router.get("/admin/winback", _pageOrApi(true,
+      R(async function (_req, res) {
+        _json(res, 200, { campaigns: await winback.listCampaigns({}) });
+      }),
+      async function (req, res) {
+        var url = req.url ? new URL(req.url, "http://localhost") : null;
+        _sendHtml(res, 200, renderAdminWinbackList({
+          shop_name: deps.shop_name, nav_available: navAvailable,
+          rows:    await winback.listCampaigns({}),
+          can_send: !!winback._deps && !!winback._deps.email,
+          saved:   url && url.searchParams.get("saved"),
+          notice:  (url && url.searchParams.get("err")) ? _winbackErrNotice(url.searchParams.get("err")) : null,
+        }));
+      },
+    ));
+
+    // New-campaign form — its own GET so a bad submit's err redirect
+    // keeps the operator's context.
+    router.get("/admin/winback/new", _pageOrApi(true,
+      R(async function (_req, res) {
+        _json(res, 200, { coupon_kinds: winback.COUPON_KINDS });
+      }),
+      async function (req, res) {
+        var url = req.url ? new URL(req.url, "http://localhost") : null;
+        _sendHtml(res, 200, renderAdminWinbackNew({
+          shop_name: deps.shop_name, nav_available: navAvailable,
+          notice: (url && url.searchParams.get("err")) ? _winbackErrNotice(url.searchParams.get("err")) : null,
+        }));
+      },
+    ));
+
+    // Create / redefine — composes defineCampaign (validates slug,
+    // lapse window, steps, coupons, audience filter; throws TypeError →
+    // 400 / err redirect). Config-time tier: a bad shape never writes.
+    router.post("/admin/winback", _pageOrApi(false,
+      W("winback_campaign.create", async function (req, res) {
+        var c;
+        try { c = await winback.defineCampaign(_winbackInput(req.body || {})); }
+        catch (e) { if (e instanceof TypeError) return _problem(res, 400, "bad-request", e.message); throw e; }
+        _json(res, 201, c);
+        return { id: c.slug };
+      }),
+      async function (req, res) {
+        var input;
+        try { input = _winbackInput(req.body || {}); }
+        catch (e) { if (e instanceof TypeError) return _redirect(res, "/admin/winback/new?err=steps"); throw e; }
+        try { await winback.defineCampaign(input); }
+        catch (e) {
+          var n = _safeNotice(e, "winback_campaign.create");
+          if (n.status >= 500) throw e;
+          return _redirect(res, "/admin/winback/new?err=bad");
+        }
+        b.audit.safeEmit({ action: AUDIT_NAMESPACE + ".winback_campaign.create", outcome: "success" });
+        _redirect(res, "/admin/winback?saved=1");
+      },
+    ));
+
+    // Detail — the campaign config + recovery metrics over a trailing
+    // window + the recent delivery log. Content-negotiated.
+    function _winbackMetricsWindow() {
+      var to = Date.now();
+      // 90-day trailing window — wide enough to capture a full
+      // escalation sequence plus the recovery tail.
+      return { from: to - C.TIME.days(90), to: to };
+    }
+    router.get("/admin/winback/:slug", _pageOrApi(true,
+      R(async function (req, res) {
+        var c = await winback.getCampaign(req.params.slug);
+        if (!c) return _problem(res, 404, "winback-campaign-not-found");
+        var win = _winbackMetricsWindow();
+        var metrics = null;
+        try { metrics = await winback.metricsForCampaign({ slug: req.params.slug, from: win.from, to: win.to }); }
+        catch (_e) { metrics = null; }
+        var deliveries = await winback.recentDeliveriesForCampaign({ slug: req.params.slug, limit: 100 });
+        _json(res, 200, Object.assign({}, c, { metrics: metrics, recent_deliveries: deliveries }));
+      }),
+      async function (req, res) {
+        var url = req.url ? new URL(req.url, "http://localhost") : null;
+        var c = await winback.getCampaign(req.params.slug);
+        if (!c) return _sendHtml(res, 404, renderAdminWinbackList({
+          shop_name: deps.shop_name, nav_available: navAvailable, rows: [],
+          can_send: !!winback._deps && !!winback._deps.email, notice: "Campaign not found.",
+        }));
+        var win = _winbackMetricsWindow();
+        var metrics = null;
+        try { metrics = await winback.metricsForCampaign({ slug: req.params.slug, from: win.from, to: win.to }); }
+        catch (_e) { metrics = null; }
+        var deliveries = await winback.recentDeliveriesForCampaign({ slug: req.params.slug, limit: 100 });
+        _sendHtml(res, 200, renderAdminWinback({
+          shop_name: deps.shop_name, nav_available: navAvailable,
+          campaign: c, metrics: metrics, deliveries: deliveries,
+          can_send: !!winback._deps && !!winback._deps.email,
+          saved:  url && url.searchParams.get("saved"),
+          notice: (url && url.searchParams.get("err")) ? _winbackErrNotice(url.searchParams.get("err")) : null,
+        }));
+      },
+    ));
+
+    // Pause — archives the campaign out of the scan path. Active
+    // enrollments still complete their sequence (the operator told
+    // those customers they'd hear back); only NEW enrollments stop.
+    router.post("/admin/winback/:slug/pause", _pageOrApi(false,
+      W("winback_campaign.pause", async function (req, res) {
+        var c;
+        try { c = await winback.archiveCampaign(req.params.slug); }
+        catch (e) { if (e instanceof TypeError) return _problem(res, 400, "bad-request", e.message); throw e; }
+        _json(res, 200, c);
+        return { id: req.params.slug };
+      }),
+      async function (req, res) {
+        var enc = encodeURIComponent(req.params.slug);
+        try { await winback.archiveCampaign(req.params.slug); }
+        catch (e) { if (!(e instanceof TypeError)) throw e; return _redirect(res, "/admin/winback/" + enc + "?err=pause"); }
+        b.audit.safeEmit({ action: AUDIT_NAMESPACE + ".winback_campaign.pause", outcome: "success", metadata: { slug: req.params.slug } });
+        _redirect(res, "/admin/winback/" + enc + "?saved=1");
+      },
+    ));
+
+    // Activate — clears the archive flag so the scan path picks the
+    // campaign back up.
+    router.post("/admin/winback/:slug/activate", _pageOrApi(false,
+      W("winback_campaign.activate", async function (req, res) {
+        var c;
+        try { c = await winback.activateCampaign(req.params.slug); }
+        catch (e) { if (e instanceof TypeError) return _problem(res, 400, "bad-request", e.message); throw e; }
+        _json(res, 200, c);
+        return { id: req.params.slug };
+      }),
+      async function (req, res) {
+        var enc = encodeURIComponent(req.params.slug);
+        try { await winback.activateCampaign(req.params.slug); }
+        catch (e) { if (!(e instanceof TypeError)) throw e; return _redirect(res, "/admin/winback/" + enc + "?err=activate"); }
+        b.audit.safeEmit({ action: AUDIT_NAMESPACE + ".winback_campaign.activate", outcome: "success", metadata: { slug: req.params.slug } });
+        _redirect(res, "/admin/winback/" + enc + "?saved=1");
+      },
+    ));
+  }
+
   // ---- gift wraps -----------------------------------------------------
   //
   // The operator-defined gift-wrap catalog: define / update / archive a wrap
@@ -14709,6 +14924,7 @@ var ADMIN_NAV_ITEMS = [
   { key: "suggestions",  href: "/admin/suggestions",  label: "Suggestion box", requires: "suggestionBox" },
   { key: "sidebar-widgets", href: "/admin/sidebar-widgets", label: "Sidebar widgets", requires: "sidebarWidgets" },
   { key: "campaigns",    href: "/admin/campaigns",    label: "Email campaigns", requires: "emailCampaigns" },
+  { key: "winback",      href: "/admin/winback",      label: "Win-back",     requires: "winback" },
   { key: "blog",         href: "/admin/blog",         label: "Blog",         requires: "blog" },
   { key: "help",         href: "/admin/help",         label: "Help center",  requires: "knowledgeBase" },
   { key: "pages",        href: "/admin/pages",        label: "Pages",        requires: "storefrontPages" },
@@ -18089,6 +18305,173 @@ function renderAdminCampaign(opts) {
   return _spliceRaw(html, "RAW_PREVIEW_BODY", previewBody);
 }
 
+// ---- win-back campaign console renders --------------------------------
+
+function _winbackErrNotice(code) {
+  if (code === "bad")      return "Check the campaign — a slug, a lapse window (days), and at least one step are all required.";
+  if (code === "steps")    return "Check the steps — each line is `days | template | coupon_kind | coupon_value`; days must be a whole number and a percent/fixed coupon needs a value.";
+  if (code === "pause")    return "That campaign can't be paused from its current state.";
+  if (code === "activate") return "That campaign can't be activated from its current state.";
+  return "That action couldn't be completed.";
+}
+
+function _winbackStatusPill(archivedAt) {
+  return archivedAt == null
+    ? "<span class=\"status-pill status-pill--ok\">active</span>"
+    : "<span class=\"status-pill status-pill--muted\">paused</span>";
+}
+
+// Render the steps array as a readable column — "0d · we-miss-you",
+// "7d · 10% off", "14d · free shipping". Every authored field escaped.
+function _winbackStepsSummary(steps) {
+  if (!Array.isArray(steps) || !steps.length) return "<span class=\"meta\">—</span>";
+  var parts = steps.map(function (s) {
+    var label = _htmlEscape(String(s.delay_days)) + "d · " + _htmlEscape(String(s.template_slug));
+    if (s.coupon_kind === "percent")       label += " (" + _htmlEscape(String(s.coupon_value)) + "% off)";
+    else if (s.coupon_kind === "fixed")    label += " (" + _htmlEscape(String(s.coupon_value)) + " off)";
+    else if (s.coupon_kind === "free_shipping") label += " (free shipping)";
+    return label;
+  });
+  return parts.join("<br>");
+}
+
+function renderAdminWinbackList(opts) {
+  opts = opts || {};
+  var rows = opts.rows || [];
+  var saved  = opts.saved  ? "<div class=\"banner banner--ok\">Campaign saved.</div>" : "";
+  var notice = opts.notice ? "<div class=\"banner banner--err\">" + _htmlEscape(opts.notice) + "</div>" : "";
+
+  // Honesty banner — win-back only emails when a deliverable-address
+  // source is wired. Customer email is hash-only, so the default deploy
+  // sends nothing: the sequence runs (enrolls, advances, logs) but no
+  // mail leaves until the operator wires an address lookup + SMTP.
+  var sendBanner = opts.can_send
+    ? ""
+    : "<div class=\"banner banner--warn\">Sending is dormant on this deployment: customer email is stored hash-only, so no win-back mail is sent until an SMTP transport and a customer-address lookup are wired. " +
+      "Campaigns can still be authored, activated, and tracked — and the sequence enrolls + advances — but no email leaves until then.</div>";
+
+  var tableRows = rows.map(function (c) {
+    var enc = encodeURIComponent(c.slug);
+    var window = _htmlEscape(String(c.lapse_days_min)) + (c.lapse_days_max == null ? "+" : "–" + _htmlEscape(String(c.lapse_days_max))) + " days";
+    return "<tr>" +
+      "<td><a href=\"/admin/winback/" + enc + "\"><code>" + _htmlEscape(c.slug) + "</code></a></td>" +
+      "<td>" + window + "</td>" +
+      "<td>" + _htmlEscape(String((c.steps || []).length)) + "</td>" +
+      "<td>" + _winbackStatusPill(c.archived_at) + "</td>" +
+      "</tr>";
+  }).join("");
+
+  var list = rows.length
+    ? "<div class=\"panel\">" + _tableWrap("<table><thead><tr><th scope=\"col\">Slug</th><th scope=\"col\">Lapse window</th><th scope=\"col\">Steps</th><th scope=\"col\">Status</th></tr></thead><tbody>" + tableRows + "</tbody></table>") + "</div>"
+    : "<p class=\"empty\">No win-back campaigns yet. Create one to re-engage customers who've gone quiet.</p>";
+
+  var body =
+    "<section><h2>Win-back campaigns</h2>" +
+      "<p class=\"meta\">Re-engage customers whose last paid order is N days old with an escalating sequence of offers. " +
+      "The cron scans the order history, enrolls the eligible, and sends each step to ONLY marketing-consented, non-suppressed addresses — consent is re-checked at send time.</p>" +
+      saved + notice + sendBanner +
+      "<div class=\"actions-row\"><a class=\"btn\" href=\"/admin/winback/new\">New campaign</a></div>" +
+      list +
+    "</section>";
+  return _renderAdminShell(opts.shop_name, "Win-back campaigns", body, "winback", opts.nav_available);
+}
+
+function renderAdminWinbackNew(opts) {
+  opts = opts || {};
+  var notice = opts.notice ? "<div class=\"banner banner--err\">" + _htmlEscape(opts.notice) + "</div>" : "";
+  var placeholder = "0 | we-miss-you\n7 | ten-pct-off | percent | 10\n14 | last-call | percent | 20";
+
+  var body =
+    "<section class=\"mw-42\"><h2>New win-back campaign</h2>" + notice +
+      "<form method=\"post\" action=\"/admin/winback\">" +
+        _setupField("Campaign slug", "slug", "", "text", "Lowercase id, e.g. we-miss-you.", " maxlength=\"64\" required") +
+        _setupField("Lapse window — minimum days", "lapse_days_min", "", "number", "Only customers whose last paid order is at least this many days old qualify.", " min=\"1\" required") +
+        _setupField("Lapse window — maximum days", "lapse_days_max", "", "number", "Optional ceiling — skip customers gone longer than this. Leave blank for no ceiling.", " min=\"1\"") +
+        _setupField("Minimum lifetime orders", "lifetime_orders_min", "", "number", "Optional — only target repeat buyers with at least this many paid orders.", " min=\"1\"") +
+        "<label class=\"form-field\"><span>Steps</span>" +
+          "<textarea name=\"steps\" rows=\"6\" maxlength=\"4000\" placeholder=\"" + _htmlEscape(placeholder) + "\" required></textarea>" +
+          "<small>One step per line: <code>days | template_slug | coupon_kind | coupon_value</code>. " +
+          "Coupon is optional; kinds are <code>percent</code>, <code>fixed</code>, <code>free_shipping</code> " +
+          "(free_shipping carries no value). Days are the offset from enrollment and must not decrease.</small></label>" +
+        "<div class=\"actions-row\"><button type=\"submit\" class=\"btn\">Create campaign</button>" +
+          "<a class=\"btn btn--ghost\" href=\"/admin/winback\">Cancel</a></div>" +
+      "</form>" +
+    "</section>";
+  return _renderAdminShell(opts.shop_name, "New win-back campaign", body, "winback", opts.nav_available);
+}
+
+function renderAdminWinback(opts) {
+  opts = opts || {};
+  var c = opts.campaign;
+  var enc = encodeURIComponent(c.slug);
+  var saved  = opts.saved  ? "<div class=\"banner banner--ok\">Campaign updated.</div>" : "";
+  var notice = opts.notice ? "<div class=\"banner banner--err\">" + _htmlEscape(opts.notice) + "</div>" : "";
+
+  var window = _htmlEscape(String(c.lapse_days_min)) + (c.lapse_days_max == null ? "+" : "–" + _htmlEscape(String(c.lapse_days_max))) + " days";
+  var aud = c.audience_filter || {};
+  var audLine = aud.lifetime_orders_min != null
+    ? "<p class=\"meta\">Audience: at least " + _htmlEscape(String(aud.lifetime_orders_min)) + " lifetime paid order(s).</p>"
+    : "";
+
+  var stepsPanel = "<div class=\"panel\"><h3 class=\"subhead\">Steps</h3>" +
+    "<p>" + _winbackStepsSummary(c.steps) + "</p></div>";
+
+  // Recovery metrics over the trailing window. recovery_rate is a 0..1
+  // fraction; render it as a one-decimal percentage.
+  var m = opts.metrics;
+  var ratePct = m ? (Number(m.recovery_rate) * 100).toFixed(1) : "0.0";
+  var metricsPanel = m
+    ? "<div class=\"panel\"><h3 class=\"subhead\">Recovery (last 90 days)</h3>" +
+        "<ul class=\"kv-list\">" +
+          "<li><span>Enrolled</span><strong>" + _htmlEscape(String(m.total)) + "</strong></li>" +
+          "<li><span>Recovered</span><strong>" + _htmlEscape(String(m.counts.recovered)) + "</strong></li>" +
+          "<li><span>Active</span><strong>" + _htmlEscape(String(m.counts.active)) + "</strong></li>" +
+          "<li><span>Exhausted</span><strong>" + _htmlEscape(String(m.counts.exhausted)) + "</strong></li>" +
+          "<li><span>Cancelled</span><strong>" + _htmlEscape(String(m.counts.cancelled)) + "</strong></li>" +
+          "<li><span>Recovery rate</span><strong>" + _htmlEscape(ratePct) + "%</strong></li>" +
+          "<li><span>Deliveries</span><strong>" + _htmlEscape(String(m.total_deliveries)) + "</strong></li>" +
+        "</ul></div>"
+    : "<div class=\"panel\"><p class=\"meta\">Metrics unavailable.</p></div>";
+
+  // Recent delivery log — which customer received which step + coupon
+  // at which time. customer_id + coupon_code are escaped.
+  var deliveries = opts.deliveries || [];
+  var logRows = deliveries.map(function (d) {
+    return "<tr>" +
+      "<td>" + _htmlEscape(new Date(d.delivered_at).toISOString()) + "</td>" +
+      "<td><code>" + _htmlEscape(String(d.customer_id)) + "</code></td>" +
+      "<td>" + _htmlEscape(String(d.step_index)) + "</td>" +
+      "<td>" + (d.coupon_code ? "<code>" + _htmlEscape(d.coupon_code) + "</code>" : "<span class=\"meta\">—</span>") + "</td>" +
+      "</tr>";
+  }).join("");
+  var logPanel = deliveries.length
+    ? "<div class=\"panel\"><h3 class=\"subhead\">Recent deliveries</h3>" +
+        _tableWrap("<table><thead><tr><th scope=\"col\">Sent</th><th scope=\"col\">Customer</th><th scope=\"col\">Step</th><th scope=\"col\">Coupon</th></tr></thead><tbody>" + logRows + "</tbody></table>") + "</div>"
+    : "<div class=\"panel\"><h3 class=\"subhead\">Recent deliveries</h3><p class=\"empty\">No deliveries yet.</p></div>";
+
+  // Pause / activate toggle on the campaign's archive state.
+  var toggle = c.archived_at == null
+    ? "<form method=\"post\" action=\"/admin/winback/" + enc + "/pause\" class=\"form-inline\">" +
+        "<button class=\"btn btn--ghost\" type=\"submit\">Pause campaign</button></form>"
+    : "<form method=\"post\" action=\"/admin/winback/" + enc + "/activate\" class=\"form-inline\">" +
+        "<button class=\"btn\" type=\"submit\">Activate campaign</button></form>";
+
+  var sendNote = opts.can_send
+    ? ""
+    : "<p class=\"meta\">Sending is dormant: no deliverable-address source is wired, so the sequence enrolls and advances but no mail leaves.</p>";
+
+  var meta = "<p class=\"meta\">Lapse window " + window + " · " + _winbackStatusPill(c.archived_at) + "</p>";
+
+  var body =
+    "<section><h2><code>" + _htmlEscape(c.slug) + "</code></h2>" + meta + audLine +
+      saved + notice +
+      stepsPanel + metricsPanel + logPanel +
+      "<div class=\"panel\"><h3 class=\"subhead\">Status</h3>" + toggle + sendNote + "</div>" +
+      "<div class=\"actions-row mt\"><a class=\"btn btn--ghost\" href=\"/admin/winback\">&larr; All campaigns</a></div>" +
+    "</section>";
+  return _renderAdminShell(opts.shop_name, c.slug, body, "winback", opts.nav_available);
+}
+
 // Location→location transfer console: the open form + the open-transfer
 // queue with the FSM action legal from each row's status. Reasons,
 // carriers, and tracking numbers are operator free text — escaped.

package/lib/asset-manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.4.55",
+  "version": "0.4.56",
   "assets": {
     "css/admin.css": {
       "integrity": "sha384-imfe0otYErcB8rr2h6KLSGTtStirysptpXETSPY4zLv3bZoIT75Lo1dOvkOav+xL",

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.56",
   "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": {