@blamejs/blamejs-shop 0.4.16 → 0.4.18

package/lib/email-campaigns.js

@@ -92,8 +92,46 @@
  *   the audience factory was wired with `emailSuppressions`);
  *   `email.send`-shaped mailer handles the per-recipient send.
  *
+ *   ## Consent-gated broadcast (`broadcast` / `broadcastTick`)
+ *
+ *   Customer email is stored HASH-ONLY in this store; the only place a
+ *   DELIVERABLE plaintext address lives is the `newsletter` subscriber
+ *   list (which persists the plaintext alongside the hash + an
+ *   `unsubscribed_at` opt-out flag). `broadcast` is the honest send
+ *   path: it resolves the deliverable plaintext address from the
+ *   audience (which resolves over `newsletter_signups`), and mails ONLY
+ *   marketing-consented, reachable recipients. Wire it with a
+ *   `newsletter` handle + an `unsubscribeBaseUrl` (https) and the send
+ *   path lights up; without them `canBroadcast()` is false and the
+ *   console says so plainly (a campaign can still be authored +
+ *   previewed, but Send refuses).
+ *
+ *   Consent is resolved AT THE SEND MOMENT, per recipient — not at
+ *   creation time. Two independent opt-out checks gate every recipient:
+ *   the newsletter `unsubscribed_at` flag (the marketing-consent state)
+ *   AND the `emailSuppressions` `marketing` scope. A recipient who
+ *   unsubscribes after the broadcast starts is honored mid-send. Every
+ *   recipient's send-time decision lands in `email_campaign_sends`
+ *   (sent / failed / skipped_unsubscribed / skipped_suppressed), keyed
+ *   UNIQUE per (campaign, recipient) so a resumed broadcast never
+ *   re-mails. `reachability(slug)` computes the true reachable count
+ *   live so the console shows "send to N" as the real number.
+ *
+ *   Every broadcast carries an RFC 8058 one-click `List-Unsubscribe` /
+ *   `List-Unsubscribe-Post` header pair (composed + shape-validated
+ *   through `b.guardListUnsubscribe`) plus an in-body unsubscribe link
+ *   minted through the newsletter one-shot token flow, and an optional
+ *   RFC 2919 `List-Id` (`b.guardListId`). The operator-authored body is
+ *   treated as hostile: `renderBody` is escape-by-default Markdown (raw
+ *   `<` lands as `&lt;`; links pass the https-only `b.safeUrl` gate) so
+ *   a compromised admin key can't get script into mail or stored XSS
+ *   into the console. Sends are rate-bound on a rolling window
+ *   (reserve-before-await); one bad address is counted, never fatal.
+ *
  * @primitive emailCampaigns
- * @related   shop.email, shop.mailingAudiences, shop.emailSuppressions, b.fsm
+ * @related   shop.email, shop.mailingAudiences, shop.emailSuppressions,
+ *            shop.newsletter, b.guardListUnsubscribe, b.guardListId,
+ *            b.safeUrl, b.template.escapeHtml, b.fsm
  */
 
 // ---- constants ----------------------------------------------------------
@@ -107,11 +145,195 @@ var MAX_BATCH_SIZE       = 1000;
 var DEFAULT_BATCH_SIZE   = 100;
 var RESOLVE_PAGE_LIMIT   = 500;          // matches mailingAudiences MAX_LIST_LIMIT
 
+var b = require("./vendor/blamejs");
+// Framework duration constants (C.TIME.minutes(n) etc.). The index entry
+// point exposes `framework` before the require cascade, so resolving this
+// at module-eval is safe — same pattern lib/admin.js / lib/cart.js use.
+var C = b.constants;
+
+// Broadcast send rate bound — recipients per minute. The drain reserves
+// a slot in this rolling window BEFORE awaiting the mailer (the
+// resend-confirmation reserve-before-await shape) so a slow SMTP host
+// can't let a burst sail past the bound while sends are in flight. When
+// the window is full the drain stops for this pass; the cron tick picks
+// the campaign back up on the next fire and resumes past the recipients
+// already in the send ledger.
+var DEFAULT_SEND_RATE_PER_MIN = 60;
+var SEND_RATE_WINDOW_MS       = C.TIME.minutes(1);
+
+// Per-recipient broadcast outcomes recorded in email_campaign_sends.
+var SEND_OUTCOMES = ["sent", "failed", "skipped_unsubscribed", "skipped_suppressed"];
+
+var CONTROL_BYTE_LINE_RE = /[\u0000-\u001f\u007f]/;
+var ZERO_WIDTH_RE        = /[\u200b-\u200f\u2028\u2029\ufeff]/;
+
 var STATUSES   = ["draft", "scheduled", "sending", "sent", "paused", "cancelled"];
 var EVENT_TYPES = ["delivered", "opened", "clicked", "bounced", "unsubscribed"];
 var TERMINAL   = ["sent", "cancelled"];
 
-var b = require("./vendor/blamejs");
+// ---- escape-by-default body renderer ------------------------------------
+//
+// The operator-authored body is HOSTILE at render time — a compromised
+// admin key must not get script into a recipient's mail client or
+// stored XSS into the console preview / list. Every byte of the body is
+// HTML-escaped before it reaches the rendered output; the only HTML the
+// renderer ever emits is the fixed tag set it produces itself from the
+// Markdown structure. Raw `<` in the body lands as `&lt;`. Link targets
+// pass `b.safeUrl.parse` (https-only) or an allow-list for `/`-rooted
+// absolute paths; anything else degrades to inert escaped text. This is
+// the same defense lib/blog-articles.js renders operator post bodies
+// with — kept byte-identical so the audited posture carries over.
+
+function _esc(s) {
+  return b.template.escapeHtml(String(s == null ? "" : s));
+}
+
+function _mdSafeLinkUrl(url) {
+  if (typeof url !== "string" || !url.length || url.length > 2048) return null;
+  if (CONTROL_BYTE_LINE_RE.test(url) || ZERO_WIDTH_RE.test(url)) return null;
+  if (url.charCodeAt(0) === 47 /* "/" */) {
+    if (url.length > 1 && url.charCodeAt(1) === 47) return null;
+    if (url.indexOf("..") !== -1) return null;
+    return url;
+  }
+  try {
+    b.safeUrl.parse(url, { allowedProtocols: ["https:"] });
+  } catch (_e) {
+    return null;
+  }
+  return url;
+}
+
+function _mdInline(line) {
+  var out = "";
+  var i = 0;
+  while (i < line.length) {
+    var ch = line.charAt(i);
+    if (ch === "`") {
+      var end = line.indexOf("`", i + 1);
+      if (end !== -1) {
+        out += "<code>" + _esc(line.slice(i + 1, end)) + "</code>";
+        i = end + 1;
+        continue;
+      }
+    }
+    if (ch === "[") {
+      var closeBracket = line.indexOf("]", i + 1);
+      if (closeBracket !== -1 && line.charAt(closeBracket + 1) === "(") {
+        var closeParen = line.indexOf(")", closeBracket + 2);
+        if (closeParen !== -1) {
+          var text = line.slice(i + 1, closeBracket);
+          var url  = line.slice(closeBracket + 2, closeParen);
+          var safe = _mdSafeLinkUrl(url);
+          if (safe) {
+            out += '<a href="' + _esc(safe) + '">' + _mdInline(text) + "</a>";
+          } else {
+            out += _mdInline(text);
+          }
+          i = closeParen + 1;
+          continue;
+        }
+      }
+    }
+    if (ch === "*" && line.charAt(i + 1) === "*") {
+      var endBold = line.indexOf("**", i + 2);
+      if (endBold !== -1) {
+        out += "<strong>" + _mdInline(line.slice(i + 2, endBold)) + "</strong>";
+        i = endBold + 2;
+        continue;
+      }
+    }
+    if (ch === "*" || ch === "_") {
+      var endItalic = line.indexOf(ch, i + 1);
+      if (endItalic !== -1 && endItalic !== i + 1) {
+        out += "<em>" + _mdInline(line.slice(i + 1, endItalic)) + "</em>";
+        i = endItalic + 1;
+        continue;
+      }
+    }
+    out += _esc(ch);
+    i += 1;
+  }
+  return out;
+}
+
+// Render the operator body (Markdown) to escape-by-default HTML. Returns
+// the body fragment only — callers wrap it in the surrounding mail /
+// preview chrome. Used at PREVIEW + at SEND so the recipient and the
+// operator see byte-identical output.
+function renderBody(body) {
+  var normalized = String(body == null ? "" : body).replace(/\r\n/g, "\n").replace(/\r/g, "\n");
+  var lines = normalized.split("\n");
+  var out = [];
+  var i = 0;
+  while (i < lines.length) {
+    var line = lines[i];
+    if (line.trim() === "") { i += 1; continue; }
+    if (/^-{3,}\s*$/.test(line)) { out.push("<hr />"); i += 1; continue; }
+    var hMatch = /^(#{1,6})\s+(.*)$/.exec(line);
+    if (hMatch) {
+      var level = hMatch[1].length;
+      out.push("<h" + level + ">" + _mdInline(hMatch[2].trim()) + "</h" + level + ">");
+      i += 1;
+      continue;
+    }
+    if (/^>\s?/.test(line)) {
+      var quoteLines = [];
+      while (i < lines.length && /^>\s?/.test(lines[i])) {
+        quoteLines.push(lines[i].replace(/^>\s?/, ""));
+        i += 1;
+      }
+      out.push("<blockquote><p>" + _mdInline(quoteLines.join(" ")) + "</p></blockquote>");
+      continue;
+    }
+    if (/^[-*]\s+/.test(line)) {
+      var ulItems = [];
+      while (i < lines.length && /^[-*]\s+/.test(lines[i])) {
+        ulItems.push(lines[i].replace(/^[-*]\s+/, ""));
+        i += 1;
+      }
+      out.push("<ul>" + ulItems.map(function (it) { return "<li>" + _mdInline(it) + "</li>"; }).join("") + "</ul>");
+      continue;
+    }
+    if (/^\d+\.\s+/.test(line)) {
+      var olItems = [];
+      while (i < lines.length && /^\d+\.\s+/.test(lines[i])) {
+        olItems.push(lines[i].replace(/^\d+\.\s+/, ""));
+        i += 1;
+      }
+      out.push("<ol>" + olItems.map(function (it) { return "<li>" + _mdInline(it) + "</li>"; }).join("") + "</ol>");
+      continue;
+    }
+    var paraLines = [line];
+    i += 1;
+    while (
+      i < lines.length &&
+      lines[i].trim() !== "" &&
+      !/^#{1,6}\s+/.test(lines[i]) &&
+      !/^[-*]\s+/.test(lines[i]) &&
+      !/^\d+\.\s+/.test(lines[i]) &&
+      !/^>\s?/.test(lines[i]) &&
+      !/^-{3,}\s*$/.test(lines[i])
+    ) {
+      paraLines.push(lines[i]);
+      i += 1;
+    }
+    out.push("<p>" + _mdInline(paraLines.join(" ")) + "</p>");
+  }
+  return out.join("\n");
+}
+
+// Plain-text rendering of the body — the multipart text/plain alt for
+// the mail. Strips Markdown markers but keeps the visible text; never
+// emits HTML. The `[text](url)` link renders as `text (url)` when the
+// URL is safe, `text` otherwise.
+function renderBodyText(body) {
+  var normalized = String(body == null ? "" : body).replace(/\r\n/g, "\n").replace(/\r/g, "\n");
+  return normalized.replace(/\[([^\]]*)\]\(([^)]*)\)/g, function (_m, text, url) {
+    var safe = _mdSafeLinkUrl(url);
+    return safe ? (text + " (" + safe + ")") : text;
+  }).replace(/[*_`#>]/g, "");
+}
 
 // ---- FSM definition -----------------------------------------------------
 
@@ -352,6 +574,76 @@ function create(opts) {
   var audiences   = opts.mailingAudiences;
   var suppressions = opts.emailSuppressions || null;
 
+  // The newsletter handle is the deliverable-address + marketing-consent
+  // source. Customer email is stored HASH-ONLY in this store; the
+  // newsletter signup table is the one place a deliverable plaintext
+  // address lives, alongside the `unsubscribed_at` opt-out flag that IS
+  // the marketing-consent state. `broadcast` needs it for three things:
+  // the per-recipient consent re-check at the send moment, the plaintext
+  // address to mint a one-shot unsubscribe token, and the resubscribe /
+  // signup lookup. Without it the consent-gated broadcast path is
+  // unavailable (the dispatcher / sendNow hash-only paths still work).
+  var newsletter = opts.newsletter || null;
+
+  // Absolute origin the in-body + RFC 8058 unsubscribe links resolve
+  // against (e.g. "https://shop.example"). Required for `broadcast`:
+  // Gmail / Yahoo one-click unsubscribe demands an https URI, and the
+  // in-body link has to be clickable from the recipient's mail client.
+  // The value must be https — b.guardListUnsubscribe refuses anything
+  // else at compose time, which would silently strip the unsubscribe
+  // headers + in-body link from every message while the console's Send
+  // stayed enabled. Refusing HERE keeps the gate honest: a non-https
+  // value leaves `canBroadcast()` false and the console shows the
+  // unconfigured notice instead of broadcasting without an unsubscribe
+  // path. The trailing-slash strip is a character loop, not a regex, so
+  // a slash-heavy value can't make the parse crawl.
+  var unsubscribeBaseUrl = null;
+  if (typeof opts.unsubscribeBaseUrl === "string" && opts.unsubscribeBaseUrl) {
+    var unsubRaw = opts.unsubscribeBaseUrl;
+    while (unsubRaw.length && unsubRaw.charAt(unsubRaw.length - 1) === "/") {
+      unsubRaw = unsubRaw.slice(0, -1);
+    }
+    try {
+      if (b.safeUrl.parse(unsubRaw).protocol === "https:") unsubscribeBaseUrl = unsubRaw;
+    } catch (_eUnsubBase) { /* not a parseable URL — broadcast stays disabled */ }
+  }
+
+  // RFC 2919 List-Id phrase (e.g. "marketing.shop.example"). Stamped on
+  // every broadcast so mailbox providers group + thread the list and the
+  // recipient's per-list unsubscribe machinery engages. Optional — when
+  // absent the List-Id header is omitted (the List-Unsubscribe pair is
+  // what the one-click machinery actually keys off).
+  var listId = typeof opts.listId === "string" && opts.listId.length ? opts.listId : null;
+
+  var sendRatePerMin = DEFAULT_SEND_RATE_PER_MIN;
+  if (opts.sendRatePerMin != null) {
+    if (!Number.isInteger(opts.sendRatePerMin) || opts.sendRatePerMin <= 0) {
+      throw new TypeError("emailCampaigns.create: sendRatePerMin must be a positive integer");
+    }
+    sendRatePerMin = opts.sendRatePerMin;
+  }
+
+  // Rolling send-rate window — timestamps of recent broadcast sends.
+  // Reserve-before-await: a slot is pushed BEFORE the mailer await so
+  // concurrent broadcast passes for two campaigns can't both read the
+  // same pre-send count and blow past the bound together. A failed send
+  // releases its reservation so a bad address doesn't consume budget.
+  var _sendWindow = [];
+  function _sendBudgetAvailable(now) {
+    var cutoff = now - SEND_RATE_WINDOW_MS;
+    var keep = [];
+    for (var i = 0; i < _sendWindow.length; i += 1) {
+      if (_sendWindow[i] > cutoff) keep.push(_sendWindow[i]);
+    }
+    _sendWindow = keep;
+    return _sendWindow.length < sendRatePerMin;
+  }
+  function _reserveSendSlot(now) { _sendWindow.push(now); }
+  function _releaseSendSlot(now) {
+    var idx = _sendWindow.indexOf(now);
+    if (idx !== -1) _sendWindow.splice(idx, 1);
+  }
+
   // ---- internal helpers (closed over factory state) --------------------
 
   async function _getRow(slug) {
@@ -458,10 +750,250 @@ function create(opts) {
     return { resolved_count: resolvedTotal, sent_count: sentTotal };
   }
 
+  // ---- consent-gated broadcast send ------------------------------------
+  //
+  // The honest send path. Where _drainSend mails the audience HASH (a
+  // namespaced digest, NOT a deliverable mailbox — that path predates a
+  // plaintext address source and only works against an ESP that
+  // translates the hash), `_broadcastDrain` resolves the deliverable
+  // PLAINTEXT address from newsletter_signups, re-checks marketing
+  // consent AT THE SEND MOMENT, attaches RFC 8058 one-click unsubscribe
+  // headers + an in-body unsubscribe link, and records a per-recipient
+  // row in email_campaign_sends (the dedupe + consent-decision ledger).
+  //
+  // Consent is resolved at SEND time, never at creation time: a
+  // recipient who unsubscribes after the broadcast starts is honored
+  // mid-send. Two independent opt-out checks gate every recipient — the
+  // newsletter `unsubscribed_at` flag (the marketing-consent state) AND
+  // the email_suppressions `marketing` scope. A recipient already in the
+  // send ledger is skipped, so a cron-resumed broadcast never re-mails.
+
+  // Build the RFC 8058 List-Unsubscribe header pair + the in-body link
+  // for one recipient. Mints a one-shot unsubscribe token through the
+  // newsletter flow (the plaintext leaves the token mint exactly once;
+  // the DB stores only its hash). Returns null when no signup row backs
+  // the address (it can't be in the audience without one) or the
+  // unsubscribe base URL isn't configured.
+  async function _unsubscribeHeadersFor(emailNormalized) {
+    if (!newsletter || !unsubscribeBaseUrl) return null;
+    var emailHash;
+    try {
+      emailHash = b.crypto.namespaceHash(newsletter.EMAIL_NAMESPACE, emailNormalized);
+    } catch (_e) { return null; }
+    var signup = await newsletter.byEmailHash(emailHash);
+    if (!signup || !signup.id) return null;
+    var issued = await newsletter.issueUnsubscribeToken(signup.id);
+    var url = unsubscribeBaseUrl + "/newsletter/unsubscribe?token=" + encodeURIComponent(issued.token);
+    // Validate the header SHAPE through the vendored RFC 2369 + RFC 8058
+    // guard so a malformed link (non-https, control byte) never reaches
+    // the wire — Gmail / Yahoo refuse mail that carries a broken pair.
+    var listUnsub = "<" + url + ">";
+    var headers = {
+      "List-Unsubscribe":      listUnsub,
+      "List-Unsubscribe-Post": b.guardListUnsubscribe.ONE_CLICK_POST_VALUE,
+    };
+    var verdict = b.guardListUnsubscribe.validate({
+      listUnsubscribe:     listUnsub,
+      listUnsubscribePost: headers["List-Unsubscribe-Post"],
+    }, { profile: "strict" });
+    if (!verdict || verdict.action !== "accept") return null;
+    if (listId) {
+      var liVerdict = b.guardListId.validate("<" + listId + ">", { profile: "strict" });
+      if (liVerdict && liVerdict.action === "accept") {
+        headers["List-Id"] = "<" + listId + ">";
+      }
+    }
+    return { headers: headers, url: url, email_hash: emailHash };
+  }
+
+  // Has this recipient already been attempted for this campaign? The
+  // UNIQUE (campaign_slug, email_hash) on email_campaign_sends is the
+  // hard guarantee; this read lets the drain skip cheaply on a resume.
+  async function _alreadyAttempted(slug, emailHash) {
+    var r = await query(
+      "SELECT 1 FROM email_campaign_sends WHERE campaign_slug = ?1 AND email_hash = ?2 LIMIT 1",
+      [slug, emailHash],
+    );
+    return r.rows.length > 0;
+  }
+
+  async function _recordSend(slug, emailHash, outcome, failReason) {
+    // INSERT OR IGNORE so a same-millisecond double-walk (concurrent
+    // cron tick) collapses onto the UNIQUE constraint rather than
+    // throwing — the first writer wins, the second no-ops. Used for the
+    // SKIP outcomes only; the send path claims first (_claimRecipient).
+    await query(
+      "INSERT OR IGNORE INTO email_campaign_sends " +
+      "(id, campaign_slug, email_hash, outcome, fail_reason, attempted_at) " +
+      "VALUES (?1, ?2, ?3, ?4, ?5, ?6)",
+      [b.uuid.v7(), slug, emailHash, outcome, failReason || null, Date.now()],
+    );
+  }
+
+  // Atomically CLAIM a recipient BEFORE the mailer await. Two drains can
+  // overlap — an operator Send racing the cron tick, or two ticks reading
+  // the same `sending` row — and both pass the _alreadyAttempted read, so
+  // a read alone cannot stop a double mail. The UNIQUE (campaign_slug,
+  // email_hash) makes exactly one INSERT the winner; the loser writes
+  // zero rows and skips the recipient. The claim is finalized to its real
+  // outcome once the mailer answers; a crash between claim and send
+  // leaves the row at `claimed`, which is never re-mailed — at-most-once
+  // is the deliberate stance for marketing mail.
+  async function _claimRecipient(slug, emailHash) {
+    var r = await query(
+      "INSERT OR IGNORE INTO email_campaign_sends " +
+      "(id, campaign_slug, email_hash, outcome, fail_reason, attempted_at) " +
+      "VALUES (?1, ?2, ?3, 'claimed', NULL, ?4)",
+      [b.uuid.v7(), slug, emailHash, Date.now()],
+    );
+    return r.rowCount === 1;
+  }
+
+  async function _finalizeSend(slug, emailHash, outcome, failReason) {
+    await query(
+      "UPDATE email_campaign_sends SET outcome = ?3, fail_reason = ?4, attempted_at = ?5 " +
+      "WHERE campaign_slug = ?1 AND email_hash = ?2 AND outcome = 'claimed'",
+      [slug, emailHash, outcome, failReason || null, Date.now()],
+    );
+  }
+
+  // Drain one campaign's audience as a consent-gated broadcast. Returns
+  // the per-outcome tallies for this pass. `more` is true when the rate
+  // budget stopped the drain before the audience was exhausted — the
+  // caller leaves the campaign in `sending` so the next cron tick
+  // resumes it past the recipients already in the send ledger.
+  async function _broadcastDrain(row) {
+    var tally = { sent: 0, failed: 0, skipped_unsubscribed: 0, skipped_suppressed: 0, resolved: 0 };
+    var cursor = null;
+    var more = false;
+    while (true) {
+      var page = await audiences.resolve({
+        slug:              row.audience_slug,
+        limit:             RESOLVE_PAGE_LIMIT,
+        cursor:            cursor,
+        include_plaintext: true,
+        skip_suppressed:   true,
+      });
+      var emails = page.emails_normalised || [];
+      var hashes = page.emails_hashed || [];
+      for (var i = 0; i < emails.length; i += 1) {
+        var emailNormalized = emails[i];
+        var emailHash = hashes[i];
+        if (!emailNormalized) continue;
+        tally.resolved += 1;
+        if (emailHash && await _alreadyAttempted(row.slug, emailHash)) continue;
+
+        // Consent re-check AT THE SEND MOMENT — the newsletter opt-out
+        // flag is the marketing-consent state; a recipient who
+        // unsubscribed after the send started is honored here, never
+        // mailed. byEmailHash returns the signup row incl.
+        // `unsubscribed_at`.
+        var consentHash = emailHash;
+        if (newsletter) {
+          try { consentHash = b.crypto.namespaceHash(newsletter.EMAIL_NAMESPACE, emailNormalized); }
+          catch (_e) { consentHash = emailHash; }
+          var signup = consentHash ? await newsletter.byEmailHash(consentHash) : null;
+          if (!signup || signup.unsubscribed_at != null) {
+            tally.skipped_unsubscribed += 1;
+            await _recordSend(row.slug, consentHash || emailHash, "skipped_unsubscribed");
+            continue;
+          }
+        }
+        // Second-line marketing-suppression check — catches a
+        // suppression that landed between the audience recompute and
+        // this drain (the audience-side filter is the first line).
+        if (suppressions && typeof suppressions.isSuppressed === "function") {
+          try {
+            var ss = await suppressions.isSuppressed({ email: emailNormalized, scope: "marketing" });
+            if (ss && ss.suppressed) {
+              tally.skipped_suppressed += 1;
+              await _recordSend(row.slug, consentHash || emailHash, "skipped_suppressed");
+              continue;
+            }
+          } catch (_eSupp) { /* drop-silent — fall through to send; the per-recipient gate already passed consent */ }
+        }
+
+        // Rate bound — reserve a slot BEFORE the mailer await. When the
+        // budget is exhausted, stop the drain for this pass and signal
+        // `more` so the cron tick resumes the campaign.
+        var now = Date.now();
+        if (!_sendBudgetAvailable(now)) { more = true; break; }
+        _reserveSendSlot(now);
+
+        // Claim BEFORE the send — when a concurrent drain already claimed
+        // this recipient, give the budget slot back and move on; the
+        // winner's send is the only one that happens.
+        if (!(await _claimRecipient(row.slug, consentHash || emailHash))) {
+          _releaseSendSlot(now);
+          continue;
+        }
+
+        var unsub = await _unsubscribeHeadersFor(emailNormalized);
+        // The stored body is the operator's SOURCE (Markdown/plaintext),
+        // not trusted HTML — the broadcast renders it through the same
+        // escape-by-default renderer the preview and test-send use, so
+        // what the operator approved is exactly what recipients get.
+        var bodyHtml = renderBody(row.body_html);
+        var bodyText = renderBodyText(row.body_text);
+        if (unsub) {
+          bodyHtml += "\n<hr />\n<p style=\"font-size:12px;color:#888\">" +
+            "You're receiving this because you subscribed to updates. " +
+            "<a href=\"" + _esc(unsub.url) + "\">Unsubscribe</a>.</p>";
+          bodyText += "\n\n---\nUnsubscribe: " + unsub.url;
+        }
+        var msg = {
+          to:        emailNormalized,
+          subject:   row.subject,
+          html:      bodyHtml,
+          text:      bodyText,
+          from:      row.from_address,
+          from_name: row.from_name,
+        };
+        if (row.reply_to) msg.replyTo = row.reply_to;
+        if (unsub && unsub.headers) msg.headers = unsub.headers;
+
+        try {
+          await mailer.send(msg);
+        } catch (sendErr) {
+          // One bad address must not abort the campaign. Release the
+          // reserved budget slot (the send didn't land), record the
+          // failure with a scrubbed reason, keep draining.
+          _releaseSendSlot(now);
+          tally.failed += 1;
+          // Scrub the failure reason for the operator-facing ledger:
+          // strip control bytes (no CRLF / NUL into the stored row) and
+          // cap length. The recipient address is never echoed into the
+          // reason — only the mailer's own message.
+          var reason = String(sendErr && sendErr.message || sendErr).replace(CONTROL_BYTE_LINE_RE, " ").slice(0, 280);
+          await _finalizeSend(row.slug, consentHash || emailHash, "failed", reason);
+          continue;
+        }
+        tally.sent += 1;
+        await _finalizeSend(row.slug, consentHash || emailHash, "sent");
+        // Mirror a `delivered` engagement event so metricsForCampaign's
+        // rollup reflects the broadcast send (the ESP webhook backfills
+        // opened / clicked / bounced on top).
+        await query(
+          "INSERT INTO email_campaign_events " +
+          "(id, campaign_slug, recipient_hash, event_type, occurred_at) " +
+          "VALUES (?1, ?2, ?3, 'delivered', ?4)",
+          [b.uuid.v7(), row.slug, consentHash || emailHash, Date.now()],
+        );
+      }
+      if (more) break;
+      if (!page.next_cursor) break;
+      cursor = page.next_cursor;
+    }
+    return { tally: tally, more: more };
+  }
+
   return {
-    STATUSES:    STATUSES,
-    EVENT_TYPES: EVENT_TYPES,
-    TERMINAL:    TERMINAL,
+    STATUSES:      STATUSES,
+    EVENT_TYPES:   EVENT_TYPES,
+    SEND_OUTCOMES: SEND_OUTCOMES,
+    TERMINAL:      TERMINAL,
+    renderBody:    renderBody,
+    renderBodyText: renderBodyText,
 
     // Define (or upsert) a campaign in `draft`. Re-defining an
     // existing slug rewrites the body / sender / audience and bumps
@@ -829,12 +1361,270 @@ function create(opts) {
         unsubscribe_rate:     _rate(counts.unsubscribed, delivered),
       };
     },
+
+    // Whether the consent-gated broadcast path is wired. The console
+    // gates its Send button on this — without a deliverable-address
+    // source (newsletter) + an https unsubscribe origin, the campaign
+    // can be authored but not sent, and the screen says so plainly.
+    canBroadcast: function () {
+      return !!(newsletter && unsubscribeBaseUrl);
+    },
+
+    // Resolved reachable count + breakdown, computed AT THE SEND-DECISION
+    // moment (not at creation). Walks the campaign's audience, resolves
+    // the deliverable plaintext address, and counts who is actually
+    // marketing-consented + not suppressed right now. The console shows
+    // this before the operator confirms a send so "send to N recipients"
+    // is the true reachable count, never the raw membership. Read-only:
+    // no token is minted, no mail is sent.
+    reachability: async function (slug) {
+      _validateSlug(slug, "slug");
+      var row = await _getRow(slug);
+      if (!row) {
+        throw new TypeError("emailCampaigns.reachability: campaign '" + slug + "' not found");
+      }
+      var out = { slug: slug, audience_slug: row.audience_slug, resolved: 0, reachable: 0, unsubscribed: 0, suppressed: 0, no_address: 0 };
+      if (!newsletter) {
+        // No deliverable-address source — honestly report zero reachable
+        // rather than implying the raw membership can be mailed.
+        return out;
+      }
+      var cursor = null;
+      while (true) {
+        var page = await audiences.resolve({
+          slug:              row.audience_slug,
+          limit:             RESOLVE_PAGE_LIMIT,
+          cursor:            cursor,
+          include_plaintext: true,
+          skip_suppressed:   false,
+        });
+        var emails = page.emails_normalised || [];
+        for (var i = 0; i < emails.length; i += 1) {
+          var emailNormalized = emails[i];
+          out.resolved += 1;
+          if (!emailNormalized) { out.no_address += 1; continue; }
+          var hash;
+          try { hash = b.crypto.namespaceHash(newsletter.EMAIL_NAMESPACE, emailNormalized); }
+          catch (_e) { out.no_address += 1; continue; }
+          var signup = await newsletter.byEmailHash(hash);
+          if (!signup) { out.no_address += 1; continue; }
+          if (signup.unsubscribed_at != null) { out.unsubscribed += 1; continue; }
+          if (suppressions && typeof suppressions.isSuppressed === "function") {
+            try {
+              var ss = await suppressions.isSuppressed({ email: emailNormalized, scope: "marketing" });
+              if (ss && ss.suppressed) { out.suppressed += 1; continue; }
+            } catch (_eSupp) { /* drop-silent — treat as reachable; the send-time gate re-checks */ }
+          }
+          out.reachable += 1;
+        }
+        if (!page.next_cursor) break;
+        cursor = page.next_cursor;
+      }
+      return out;
+    },
+
+    // Per-recipient send-ledger rollup for a campaign — sent / failed /
+    // skipped_unsubscribed / skipped_suppressed. The console renders
+    // this as the per-campaign delivery counts.
+    sendCounts: async function (slug) {
+      _validateSlug(slug, "slug");
+      var rows = (await query(
+        "SELECT outcome, COUNT(*) AS n FROM email_campaign_sends WHERE campaign_slug = ?1 GROUP BY outcome",
+        [slug],
+      )).rows;
+      var counts = {};
+      for (var i = 0; i < SEND_OUTCOMES.length; i += 1) counts[SEND_OUTCOMES[i]] = 0;
+      for (var j = 0; j < rows.length; j += 1) counts[rows[j].outcome] = Number(rows[j].n || 0);
+      return counts;
+    },
+
+    // Operator preview — the rendered (escape-by-default) body + a
+    // re-rendered subject, exactly as a recipient would see it. Never
+    // sends; mints no token. Throws on an unknown slug so the console
+    // 404s rather than rendering an empty shell.
+    previewCampaign: async function (slug) {
+      _validateSlug(slug, "slug");
+      var row = await _getRow(slug);
+      if (!row) {
+        throw new TypeError("emailCampaigns.previewCampaign: campaign '" + slug + "' not found");
+      }
+      return {
+        slug:         slug,
+        subject:      row.subject,
+        from_address: row.from_address,
+        from_name:    row.from_name,
+        reply_to:     row.reply_to,
+        body_html:    renderBody(row.body_html),
+        body_text:    renderBodyText(row.body_text),
+      };
+    },
+
+    // Test-send — render + mail the campaign to ONE operator-supplied
+    // address, bypassing the audience + consent gate (it's the
+    // operator's own inbox, not a customer broadcast). Still carries the
+    // RFC 8058 unsubscribe pair so the operator sees the real message.
+    // The address is validated through the same strict guard the sender
+    // identity uses. Returns `{ to }`. Rate-bound on the shared window.
+    testSend: async function (slug, toRaw) {
+      _validateSlug(slug, "slug");
+      var to = _validateEmail(toRaw, "test recipient");
+      var row = await _getRow(slug);
+      if (!row) {
+        throw new TypeError("emailCampaigns.testSend: campaign '" + slug + "' not found");
+      }
+      var now = Date.now();
+      if (!_sendBudgetAvailable(now)) {
+        var rl = new TypeError("emailCampaigns.testSend: send rate limit reached — try again shortly");
+        rl.code = "EMAIL_CAMPAIGN_RATE_LIMITED";
+        throw rl;
+      }
+      _reserveSendSlot(now);
+      var msg = {
+        to:        to,
+        subject:   "[TEST] " + row.subject,
+        html:      renderBody(row.body_html),
+        text:      renderBodyText(row.body_text),
+        from:      row.from_address,
+        from_name: row.from_name,
+      };
+      if (row.reply_to) msg.replyTo = row.reply_to;
+      try {
+        await mailer.send(msg);
+      } catch (sendErr) {
+        _releaseSendSlot(now);
+        throw sendErr;
+      }
+      return { to: to };
+    },
+
+    // Consent-gated broadcast send. The operator's "send now" — drives a
+    // draft/scheduled campaign through sending → sent, draining the
+    // audience as a consent-gated, RFC 8058-unsubscribable, rate-bound
+    // broadcast against the deliverable plaintext address source. One bad
+    // address is counted, not fatal. When the rate budget stops the drain
+    // before the audience is exhausted the campaign stays in `sending`
+    // and `complete` is false — the cron tick resumes it. Refuses when
+    // the broadcast path isn't wired (no newsletter / no unsubscribe
+    // origin) so the console never half-sends.
+    broadcast: async function (slug) {
+      _validateSlug(slug, "slug");
+      if (!newsletter || !unsubscribeBaseUrl) {
+        var e = new TypeError(
+          "emailCampaigns.broadcast: not available — a deliverable-address source " +
+          "(newsletter) and an https unsubscribe origin must be wired"
+        );
+        e.code = "EMAIL_CAMPAIGN_BROADCAST_UNAVAILABLE";
+        throw e;
+      }
+      var row = await _getRow(slug);
+      if (!row) {
+        throw new TypeError("emailCampaigns.broadcast: campaign '" + slug + "' not found");
+      }
+      // Resume path — a campaign already in `sending` (rate-budget
+      // pause from a prior pass) drains again without re-firing the FSM.
+      if (row.status !== "sending") {
+        var nowSched = Date.now();
+        if (row.status === "draft") {
+          await _fire(row, "schedule");
+          await query(
+            "UPDATE email_campaigns SET status = 'scheduled', schedule_at = ?1, updated_at = ?1 WHERE slug = ?2",
+            [nowSched, slug],
+          );
+          row = await _getRow(slug);
+        }
+        if (row.status !== "scheduled") {
+          throw new TypeError(
+            "emailCampaigns.broadcast: campaign '" + slug + "' is in status '" +
+            row.status + "' — cannot send"
+          );
+        }
+        await _fire(row, "start");
+        await query(
+          "UPDATE email_campaigns SET status = 'sending', updated_at = ?1 WHERE slug = ?2",
+          [Date.now(), slug],
+        );
+        row = await _getRow(slug);
+      }
+
+      var result = await _broadcastDrain(row);
+      var tally = result.tally;
+      var counts = await query(
+        "SELECT outcome, COUNT(*) AS n FROM email_campaign_sends WHERE campaign_slug = ?1 GROUP BY outcome",
+        [slug],
+      );
+      var sentTotal = 0;
+      var resolvedTotal = 0;
+      for (var k = 0; k < counts.rows.length; k += 1) {
+        resolvedTotal += Number(counts.rows[k].n || 0);
+        if (counts.rows[k].outcome === "sent") sentTotal = Number(counts.rows[k].n || 0);
+      }
+
+      if (result.more) {
+        // Rate budget paused the drain mid-audience — leave the campaign
+        // in `sending`, stamp the running counts, let the cron tick
+        // resume. Not terminal: `complete: false`.
+        await query(
+          "UPDATE email_campaigns SET recipients_resolved_count = ?1, sent_count = ?2, updated_at = ?3 WHERE slug = ?4",
+          [resolvedTotal, sentTotal, Date.now(), slug],
+        );
+        return { slug: slug, complete: false, tally: tally, sent_count: sentTotal, resolved_count: resolvedTotal };
+      }
+
+      // Audience exhausted — close the campaign out.
+      var midRow = await _getRow(slug);
+      await _fire(midRow, "complete");
+      var sentAt = Date.now();
+      await query(
+        "UPDATE email_campaigns SET status = 'sent', recipients_resolved_count = ?1, " +
+        "sent_count = ?2, sent_at = ?3, updated_at = ?3 WHERE slug = ?4",
+        [resolvedTotal, sentTotal, sentAt, slug],
+      );
+      return { slug: slug, complete: true, tally: tally, sent_count: sentTotal, resolved_count: resolvedTotal };
+    },
+
+    // Scheduler tick for broadcasts. Walks campaigns due for send
+    // (`scheduled` with schedule_at <= now) AND campaigns parked in
+    // `sending` by a rate-budget pause, and drains each as a consent-
+    // gated broadcast. Inert (returns an empty dispatch list) when the
+    // broadcast path isn't wired. Drop-safe — a single campaign's drain
+    // failure is caught so one bad campaign doesn't stall the tick.
+    broadcastTick: async function (input) {
+      input = input || {};
+      var now = input.now == null ? Date.now() : _validateTs(input.now, "now");
+      var batchSize = _validateBatchSize(input.batch_size);
+      if (!newsletter || !unsubscribeBaseUrl) {
+        return { dispatched: [], enabled: false, now: now };
+      }
+      var due = await query(
+        "SELECT slug FROM email_campaigns " +
+        "WHERE (status = 'sending') OR " +
+        "(status = 'scheduled' AND schedule_at IS NOT NULL AND schedule_at <= ?1) " +
+        "ORDER BY schedule_at ASC, slug ASC LIMIT ?2",
+        [now, batchSize],
+      );
+      var dispatched = [];
+      for (var i = 0; i < due.rows.length; i += 1) {
+        var slug = due.rows[i].slug;
+        try {
+          var res = await this.broadcast(slug);
+          dispatched.push({ slug: slug, complete: res.complete, sent_count: res.sent_count });
+        } catch (_e) {
+          // A concurrent ticker race or a per-campaign fault must not
+          // stall the others — skip and continue.
+          continue;
+        }
+      }
+      return { dispatched: dispatched, enabled: true, now: now };
+    },
   };
 }
 
 module.exports = {
-  create:      create,
-  STATUSES:    STATUSES,
-  EVENT_TYPES: EVENT_TYPES,
-  TERMINAL:    TERMINAL,
+  create:         create,
+  renderBody:     renderBody,
+  renderBodyText: renderBodyText,
+  STATUSES:       STATUSES,
+  EVENT_TYPES:    EVENT_TYPES,
+  SEND_OUTCOMES:  SEND_OUTCOMES,
+  TERMINAL:       TERMINAL,
 };