@blamejs/blamejs-shop 0.4.54 → 0.4.56

package/CHANGELOG.md

@@ -8,6 +8,10 @@ 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.
 
 - v0.4.53 (2026-06-14) — **A signed-in customer's cookie choices and newsletter unsubscribe now land in the durable consent record.** The durable, per-customer consent ledger — the GDPR Article 7(1) record a controller keeps to demonstrate consent — is now written from the real consent events for identified customers. When a signed-in customer saves their cookie preferences, each category (functional, analytics, marketing, preferences) is recorded as granted or withdrawn in the durable ledger, alongside the existing session-level cookie record. When a newsletter unsubscribe resolves to a customer account, a marketing-email withdrawal is recorded there too. Anonymous visitors and email-only subscribers with no account are unchanged — their cookie choice stays in the session-level store and their unsubscribe in the email-suppression list, neither of which can be customer-keyed. The ledger writes are best-effort and never block the banner save or the unsubscribe. No migration to apply. **Added:** *Cookie-banner choices recorded in the durable consent ledger for signed-in customers* — When an authenticated customer saves their cookie preferences, each of the four optional categories is now mirrored into the durable per-customer consent ledger as a granted or withdrawn decision (source: cookie banner), so a supervisory-authority audit shows the identified individual's choice and not only the session-keyed record. The durable record reflects the consent the storefront actually enforces: a browser-level opt-out signal (Global Privacy Control or Do Not Track) collapses the analytics and marketing categories to withdrawn even if their boxes were ticked, matching the runtime gate, so the record never claims consent the app refuses to honor. The customer is resolved from the existing signed-in session (a revoked session is treated as signed-out); anonymous visitors carry no account and are written only to the session-level cookie record as before. · *Newsletter unsubscribe records a marketing withdrawal for account holders* — A newsletter unsubscribe that resolves to a customer account now records a marketing-email withdrawal in the durable consent ledger. The unsubscribed address is matched to an account by its hashed form; an email-only subscriber with no account is handled by the existing email-suppression path only, since the durable ledger is keyed by customer. The existing unsubscribe behavior — the suppression entry and the one-click RFC 8058 flow — is unchanged.

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.54",
+  "version": "0.4.56",
   "assets": {
     "css/admin.css": {
       "integrity": "sha384-imfe0otYErcB8rr2h6KLSGTtStirysptpXETSPY4zLv3bZoIT75Lo1dOvkOav+xL",