@flowapt/flowiq-cli 0.1.12 → 0.2.1

package/src/commands/broadcast.js

@@ -0,0 +1,879 @@
+// `flowiq broadcast` — CSV → WhatsApp template broadcast (per the
+// flowiq-broadcast-send-SPEC).
+//
+//   map     <org>  --template T --csv F [--campaign C]   build/refresh the saved mapping (no send)
+//   preview <org>  [--campaign C] [--rows 3]             dry-run render of sample rows
+//   send    <org>  --template T --csv F [--commit]       full pipeline; DRY-RUN by default
+//   resume  <org>  --campaign C [--commit]               continue from the status log
+//
+// Pipeline: introspect template (live Meta + DB labels, via /cli/broadcast) →
+// parse CSV → build/load column→param MAPPING (each row fills the template
+// with its OWN values) → validate (V-1..V-13) → broadcast-safety classify
+// (opted-out/archived/blocked are skipped) → preview → [--commit] upsert
+// contacts (/cli/contacts-upsert, ≤4000/batch, 3× retry then ABORT) → send
+// per row via /api/send-template (org-UUID branch, NO auth header), paced
+// ≤10 msg/s, with a WRITE-AHEAD per-row status log:
+//   {status:"sending"} appended BEFORE the POST, the terminal sent/failed
+//   line after — so a crash mid-row leaves an ambiguous row that is NEVER
+//   auto-resent (surfaced for manual review). Resume dedups on
+//   normalized-number-within-campaign, never on CSV fingerprint.
+//
+// #132000 structural guard: the payload builder whitelists /^param\d+$/ keys
+// only — a stray "name" key (which would add a body param on a POSITIONAL
+// template) is impossible by construction.
+
+import fs from "node:fs/promises";
+import path from "node:path";
+import readline from "node:readline";
+import { createHash } from "node:crypto";
+import { http } from "../http.js";
+import { loadConfig } from "../config.js";
+
+const CAMPAIGN_DIR = path.resolve(process.cwd(), ".flowiq", "campaigns");
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const HARD_RATE_CAP = 10;
+const CONTACT_BATCH_CAP = 4000;
+const CLASSIFY_CHUNK = 2000;
+
+// ---------------------------------------------------------------------------
+// small utils
+// ---------------------------------------------------------------------------
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+function slugify(name, fallback) {
+  const s = String(name || "").toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/-+/g, "-").replace(/^-|-$/g, "");
+  return s || fallback;
+}
+
+async function fileExists(p) {
+  try { await fs.access(p); return true; } catch { return false; }
+}
+
+function ask(question) {
+  return new Promise((resolve) => {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    rl.question(question, (answer) => { rl.close(); resolve(answer.trim()); });
+  });
+}
+
+function sha256(s) {
+  return "sha256:" + createHash("sha256").update(s).digest("hex");
+}
+
+// Mirrors the server's normalizePhoneNumber (send-template.js) exactly.
+function normalizePhone(phone) {
+  if (!phone) return "";
+  let n = String(phone).replace(/\D/g, "");
+  if (n.startsWith("0")) n = "27" + n.substring(1);
+  if (n.length === 9 && !n.startsWith("0")) n = "27" + n;
+  return n;
+}
+
+function isPlausiblePhone(n) {
+  return /^\d{10,15}$/.test(n);
+}
+
+// ---------------------------------------------------------------------------
+// CSV (RFC-4180-ish, dependency-free)
+// ---------------------------------------------------------------------------
+
+function sniffDelimiter(headerLine) {
+  const counts = [",", ";", "\t"].map((d) => [d, headerLine.split(d).length - 1]);
+  counts.sort((a, b) => b[1] - a[1]);
+  return counts[0][1] > 0 ? counts[0][0] : ",";
+}
+
+function parseCsv(text, delimiter) {
+  const rows = [];
+  let field = "", row = [], inQuotes = false;
+  for (let i = 0; i < text.length; i++) {
+    const ch = text[i];
+    if (inQuotes) {
+      if (ch === '"') {
+        if (text[i + 1] === '"') { field += '"'; i++; }
+        else inQuotes = false;
+      } else field += ch;
+    } else if (ch === '"') inQuotes = true;
+    else if (ch === delimiter) { row.push(field); field = ""; }
+    else if (ch === "\n") { row.push(field); rows.push(row); field = ""; row = []; }
+    else if (ch === "\r") { /* handled by \n */ }
+    else field += ch;
+  }
+  if (field.length || row.length) { row.push(field); rows.push(row); }
+  return rows.filter((r) => r.some((c) => c.trim() !== ""));
+}
+
+async function loadCsv(csvPath) {
+  let text = await fs.readFile(path.resolve(csvPath), "utf8");
+  if (text.charCodeAt(0) === 0xfeff) text = text.slice(1); // strip BOM
+  const firstLine = text.split("\n", 1)[0];
+  const delimiter = sniffDelimiter(firstLine);
+  const table = parseCsv(text, delimiter);
+  if (table.length < 2) throw new Error("CSV needs a header row + at least one data row");
+  const headers = table[0].map((h) => h.trim());
+  const seen = new Set();
+  for (const h of headers) {
+    const k = h.toLowerCase();
+    if (seen.has(k)) throw new Error(`Duplicate CSV header "${h}" — mapping would be ambiguous`);
+    seen.add(k);
+  }
+  const rows = table.slice(1).map((r, i) => {
+    const obj = { __rownum: i + 1 };
+    headers.forEach((h, j) => { obj[h] = (r[j] ?? "").trim(); });
+    return obj;
+  });
+  return { headers, rows, delimiter, header_fingerprint: sha256(JSON.stringify(headers)) };
+}
+
+// ---------------------------------------------------------------------------
+// mapping engine
+// ---------------------------------------------------------------------------
+
+const norm = (s) => String(s || "").toLowerCase().replace(/[^a-z0-9]+/g, "");
+const tokens = (s) => new Set(String(s || "").toLowerCase().split(/[^a-z0-9]+/).filter(Boolean));
+
+function similarity(label, header) {
+  const nl = norm(label), nh = norm(header);
+  if (!nl || !nh) return 0;
+  if (nl === nh) return 1.0;
+  const tl = tokens(label), th = tokens(header);
+  const inter = [...tl].filter((t) => th.has(t)).length;
+  if (inter && inter === tl.size && inter === th.size) return 0.9;
+  if (nl.includes(nh) || nh.includes(nl)) return 0.7;
+  const union = new Set([...tl, ...th]).size;
+  return union ? 0.3 + 0.3 * (inter / union) : 0;
+}
+
+const CC_HEADERS = ["countrycode", "cc", "dialcode", "dialingcode"];
+const PHONE_HEADERS = ["phone", "phonenumber", "whatsapp", "whatsappid", "whatsappnumber", "number", "mobile", "cell", "msisdn"];
+
+function findHeader(headers, candidates) {
+  return headers.find((h) => candidates.includes(norm(h))) ?? null;
+}
+
+/** Resolve one mapped value for a row. concat strips a leading 0 from parts
+ *  AFTER the first (the country-code + local-part rule: 27 + 0831112222 must
+ *  become 27831112222, not 270831112222). */
+function resolveValue(mapping, row) {
+  if (!mapping || !mapping.source) return "";
+  if (mapping.source === "literal") return String(mapping.value ?? "");
+  if (mapping.source === "column") return String(row[mapping.name] ?? "");
+  if (mapping.source === "transform" && mapping.transform === "concat") {
+    let out = "";
+    for (const part of mapping.parts || []) {
+      let v = part.type === "literal" ? String(part.value ?? "") : String(row[part.name] ?? "");
+      if (mapping.normalizePhone && out.length > 0) v = v.replace(/^\s*0/, "");
+      out += v;
+    }
+    return mapping.normalizePhone ? normalizePhone(out) : out;
+  }
+  return "";
+}
+
+function describeMapping(m) {
+  if (!m || !m.source) return "(unmapped)";
+  if (m.source === "column") return `column "${m.name}"`;
+  if (m.source === "literal") return `literal "${m.value}"`;
+  if (m.source === "transform") {
+    const parts = (m.parts || []).map((p) => (p.type === "column" ? p.name : `"${p.value}"`)).join(" + ");
+    return `concat(${parts})${m.normalizePhone ? " [normalizePhone]" : ""}`;
+  }
+  return "(unknown)";
+}
+
+function contextSnippet(bodyText, position) {
+  const idx = bodyText.indexOf(`{{${position}}}`);
+  if (idx === -1) return "";
+  const start = Math.max(0, idx - 40);
+  const end = Math.min(bodyText.length, idx + 40);
+  return `${start > 0 ? "…" : ""}${bodyText.slice(start, end).replace(/\n/g, " ")}${end < bodyText.length ? "…" : ""}`;
+}
+
+function autoSuggest(template, headers) {
+  const ccHeader = findHeader(headers, CC_HEADERS);
+  const phoneHeader = headers.find((h) => PHONE_HEADERS.includes(norm(h))) ?? null;
+  const phoneMapping = ccHeader && phoneHeader
+    ? { source: "transform", transform: "concat", normalizePhone: true, parts: [{ type: "column", name: ccHeader }, { type: "column", name: phoneHeader }] }
+    : phoneHeader
+      ? { source: "transform", transform: "concat", normalizePhone: true, parts: [{ type: "column", name: phoneHeader }] }
+      : null;
+
+  const bodyParams = {};
+  for (const pos of template.body_positions) {
+    const label = template.body_labels?.[String(pos)];
+    const useLabel = label && norm(label) !== String(pos) ? label : null;
+    let best = null, bestScore = 0;
+    if (useLabel) {
+      for (const h of headers) {
+        const s = similarity(useLabel, h);
+        if (s > bestScore) { best = h; bestScore = s; }
+      }
+    }
+    const phoneish = useLabel && /phone|number|whatsapp/i.test(useLabel);
+    let suggestion = null;
+    if (phoneish && phoneMapping) suggestion = { ...phoneMapping };
+    else if (best && bestScore >= 0.7) suggestion = { source: "column", name: best };
+    bodyParams[`param${pos}`] = {
+      mapping: suggestion,
+      confidence: phoneish && phoneMapping ? 0.78 : bestScore,
+      label: useLabel ?? String(pos),
+      context: contextSnippet(template.body_text, pos),
+    };
+  }
+  return { bodyParams, recipient: phoneMapping, ccHeader, phoneHeader };
+}
+
+async function interactiveMapping(template, headers, campaign) {
+  const auto = autoSuggest(template, headers);
+  const pickColumn = async () => {
+    headers.forEach((h, i) => console.log(`    ${i + 1}. ${h}`));
+    const n = Number(await ask("  column #: "));
+    if (!Number.isInteger(n) || n < 1 || n > headers.length) throw new Error("invalid column number");
+    return headers[n - 1];
+  };
+  const buildConcat = async () => {
+    console.log('  build a concat — enter parts one per line ("col:<header>" or "lit:<text>"), empty line to finish:');
+    const parts = [];
+    for (;;) {
+      const line = await ask("  part: ");
+      if (!line) break;
+      if (line.startsWith("col:")) parts.push({ type: "column", name: line.slice(4).trim() });
+      else if (line.startsWith("lit:")) parts.push({ type: "literal", value: line.slice(4) });
+      else console.log('  (use "col:<header>" or "lit:<text>")');
+    }
+    const np = (await ask("  normalizePhone? [y/N]: ")).toLowerCase() === "y";
+    return { source: "transform", transform: "concat", normalizePhone: np, parts };
+  };
+  const confirmSlot = async (name, meta) => {
+    console.log("");
+    console.log(`  ${name}  label: ${meta.label ?? "-"}`);
+    if (meta.context) console.log(`          context: "${meta.context}"`);
+    console.log(`          suggestion: ${describeMapping(meta.mapping)}${meta.confidence ? `  [confidence ${meta.confidence.toFixed(2)}]` : ""}`);
+    for (;;) {
+      const a = (await ask("          [Enter]=accept  c=column  l=literal  t=transform: ")).toLowerCase();
+      if (a === "" && meta.mapping) return meta.mapping;
+      if (a === "" && !meta.mapping) { console.log("          (no suggestion — pick c/l/t)"); continue; }
+      if (a === "c") return { source: "column", name: await pickColumn() };
+      if (a === "l") return { source: "literal", value: await ask("          literal value: ") };
+      if (a === "t") return await buildConcat();
+    }
+  };
+
+  console.log(`Template ${template.name} — ${template.parameter_format}, ${template.body_var_count} body var(s)${template.url_button?.present ? " + 1 URL button" : ""}.`);
+  const body_params = {};
+  for (const pos of template.body_positions) {
+    const key = `param${pos}`;
+    body_params[key] = { ...(await confirmSlot(key, auto.bodyParams[key])), label: auto.bodyParams[key].label };
+  }
+  let button_params = {};
+  if (template.url_button?.present) {
+    console.log("");
+    console.log(`  BUTTON param1  (URL base: ${template.url_button.url_base})`);
+    const code = await ask("          short code / value for this campaign: ");
+    button_params = { param1: { source: "literal", value: code, url_base: template.url_button.url_base } };
+  }
+  console.log("");
+  const recipient = await confirmSlot("RECIPIENT whatsappNumber", { mapping: auto.recipient, label: "recipient", confidence: auto.recipient ? 0.78 : 0 });
+
+  console.log("");
+  console.log("Mapping:");
+  for (const [k, v] of Object.entries(body_params)) console.log(`  ${k.padEnd(18)} ${describeMapping(v)}`);
+  if (button_params.param1) console.log(`  BUTTON param1      ${describeMapping(button_params.param1)}`);
+  console.log(`  RECIPIENT          ${describeMapping(recipient)}`);
+  const save = (await ask(`Save this mapping to .flowiq/campaigns/${campaign}.json? [Y/n]: `)).toLowerCase();
+  if (save === "n") throw new Error("mapping not saved — aborted");
+  return { body_params, button_params, recipient };
+}
+
+// ---------------------------------------------------------------------------
+// campaign config + status log
+// ---------------------------------------------------------------------------
+
+const cfgPath = (campaign) => path.join(CAMPAIGN_DIR, `${campaign}.json`);
+const logPath = (campaign) => path.join(CAMPAIGN_DIR, `${campaign}.status.jsonl`);
+
+async function loadCampaign(campaign) {
+  try { return JSON.parse(await fs.readFile(cfgPath(campaign), "utf8")); }
+  catch { return null; }
+}
+
+async function saveCampaign(cfg) {
+  await fs.mkdir(CAMPAIGN_DIR, { recursive: true });
+  await fs.writeFile(cfgPath(cfg.campaign), JSON.stringify(cfg, null, 2) + "\n", "utf8");
+}
+
+/** Fold the JSONL into number → latest status. `sending` with no terminal
+ *  line = ambiguous (crash mid-row): NEVER auto-resent. */
+async function loadStatusLog(campaign) {
+  const map = new Map();
+  let header = null;
+  try {
+    const text = await fs.readFile(logPath(campaign), "utf8");
+    for (const line of text.split("\n")) {
+      if (!line.trim()) continue;
+      let obj; try { obj = JSON.parse(line); } catch { continue; }
+      if (obj.type === "meta") { header = obj; continue; }
+      if (obj.type === "row" && obj.number) map.set(obj.number, obj);
+    }
+  } catch { /* no log yet */ }
+  return { header, map };
+}
+
+async function appendLog(campaign, obj) {
+  await fs.mkdir(CAMPAIGN_DIR, { recursive: true });
+  await fs.appendFile(logPath(campaign), JSON.stringify(obj) + "\n", "utf8");
+}
+
+// ---------------------------------------------------------------------------
+// pipeline stages
+// ---------------------------------------------------------------------------
+
+async function introspect(orgId, templateName) {
+  const resp = await http.post("broadcast", { action: "introspect", organization_id: orgId, template_name: templateName });
+  return resp;
+}
+
+/** Validation V-1..V-13. Returns {valid, skipped, aborts}. */
+function validateRows(template, mapping, headers, rows, illegalChars) {
+  const aborts = [];
+  if (template.status !== "APPROVED") aborts.push(`V-1: template status is ${template.status} — only APPROVED templates send`);
+  if (template.parameter_format !== "POSITIONAL") aborts.push("V-2: NAMED templates are not supported in v1");
+  if (template.is_carousel) aborts.push("V-3: carousel templates are not supported in v1");
+  if (!["text", "none"].includes(template.header_type)) aborts.push(`V-3: media-header templates (${template.header_type}) are not supported in v1`);
+  for (const pos of template.body_positions) {
+    if (!mapping.body_params?.[`param${pos}`]?.source) aborts.push(`V-4: body param${pos} is unmapped`);
+  }
+  // V-2b: positions must be contiguous 1..N (the #132000 arithmetic guard).
+  const want = Array.from({ length: template.body_var_count }, (_, i) => i + 1);
+  if (JSON.stringify(template.body_positions) !== JSON.stringify(want)) {
+    aborts.push(`V-2: template positions ${JSON.stringify(template.body_positions)} are not contiguous 1..N — refusing`);
+  }
+  if (template.url_button?.present && !mapping.button_params?.param1?.source) {
+    aborts.push("V-5: the template has a dynamic URL button but button param1 is unmapped");
+  }
+  const referenced = new Set();
+  const collect = (m) => {
+    if (!m) return;
+    if (m.source === "column") referenced.add(m.name);
+    if (m.source === "transform") for (const p of m.parts || []) if (p.type === "column") referenced.add(p.name);
+  };
+  Object.values(mapping.body_params || {}).forEach(collect);
+  collect(mapping.recipient);
+  for (const col of referenced) {
+    if (!headers.includes(col)) aborts.push(`V-6: mapped column "${col}" is not in the CSV headers`);
+  }
+  if (aborts.length) return { aborts, valid: [], skipped: [] };
+
+  const valid = [], skipped = [];
+  const seenNumbers = new Set();
+  const illegal = (v) => /[\n\r\t]| {4,}/.test(v);
+  for (const row of rows) {
+    const recipient = resolveValue(mapping.recipient, row);
+    if (!recipient) { skipped.push({ row: row.__rownum, reason: "empty_recipient" }); continue; }
+    const number = normalizePhone(recipient);
+    if (!isPlausiblePhone(number)) { skipped.push({ row: row.__rownum, reason: `bad_phone:${recipient}` }); continue; }
+    if (seenNumbers.has(number)) { skipped.push({ row: row.__rownum, reason: "duplicate_number", number }); continue; }
+
+    const values = {};
+    let bad = null, sanitized = false;
+    for (const pos of template.body_positions) {
+      let v = resolveValue(mapping.body_params[`param${pos}`], row);
+      if (!v) { bad = `empty_value:param${pos}`; break; }
+      if (illegal(v)) {
+        if (illegalChars === "strip") { v = v.replace(/[\n\r\t]+| {4,}/g, " ").replace(/ +/g, " ").trim(); sanitized = true; }
+        else { bad = `illegal_chars:param${pos}`; break; }
+      }
+      values[`param${pos}`] = v;
+    }
+    if (bad) { skipped.push({ row: row.__rownum, reason: bad, number }); continue; }
+
+    let buttonValue = null;
+    if (template.url_button?.present) {
+      buttonValue = resolveValue(mapping.button_params.param1, row);
+      if (!buttonValue) { skipped.push({ row: row.__rownum, reason: "empty_value:button", number }); continue; }
+    }
+    seenNumbers.add(number);
+    valid.push({ rownum: row.__rownum, number, values, buttonValue, sanitized, contactName: firstColumnName(mapping, row) });
+  }
+  if (!valid.length) aborts.push("V-13: 0 valid rows after filtering — nothing to send");
+  return { aborts, valid, skipped };
+}
+
+/** Best human name for the contact upsert — the value mapped to param1 when
+ *  it's a column (usually the customer-name column), else null. */
+function firstColumnName(mapping, row) {
+  const m = mapping.body_params?.param1;
+  if (m?.source === "column") return String(row[m.name] ?? "").trim() || null;
+  return null;
+}
+
+/** Broadcast-safety classification via /cli/broadcast — excluded numbers are
+ *  moved to skipped (send-template itself does NOT check allow_broadcast). */
+async function applySafetyExclusions(orgId, valid, skipped) {
+  const excludedNumbers = new Map();
+  for (let i = 0; i < valid.length; i += CLASSIFY_CHUNK) {
+    const chunk = valid.slice(i, i + CLASSIFY_CHUNK).map((r) => r.number);
+    const resp = await http.post("broadcast", { action: "classify", organization_id: orgId, phones: chunk });
+    for (const r of resp.results || []) {
+      if (r.classification === "excluded") excludedNumbers.set(r.phone, r.reason);
+    }
+  }
+  const keep = [];
+  for (const r of valid) {
+    const reason = excludedNumbers.get(r.number);
+    if (reason) skipped.push({ row: r.rownum, reason: `opted_out:${reason}`, number: r.number });
+    else keep.push(r);
+  }
+  return keep;
+}
+
+function renderPreview(template, sample) {
+  let bodyText = template.body_text;
+  for (const [k, v] of Object.entries(sample.values)) {
+    bodyText = bodyText.replaceAll(`{{${k.replace("param", "")}}}`, v);
+  }
+  console.log(`Row ${sample.rownum}  →  ${sample.number}   [VALID]${sample.sanitized ? " (sanitized)" : ""}`);
+  console.log(`  Body:\n    ${bodyText.replace(/\n/g, "\n    ")}`);
+  if (template.url_button?.present && sample.buttonValue != null) {
+    const url = template.url_button.url_base.replace(/\{\{[^}]+\}\}/, sample.buttonValue);
+    console.log(`  Button "${template.url_button.text ?? "URL"}" → ${url}`);
+  }
+}
+
+async function upsertContacts(orgId, rows, batchCap) {
+  let created = 0, updated = 0, skippedN = 0, dropped = 0;
+  const uniq = rows;
+  for (let i = 0; i < uniq.length; i += batchCap) {
+    const chunk = uniq.slice(i, i + batchCap).map((r) => ({ whatsapp_id: r.number, full_name: r.contactName }));
+    let resp = null, lastErr = null;
+    for (let attempt = 1; attempt <= 3; attempt++) {
+      try { resp = await http.post("contacts-upsert", { organization_id: orgId, contacts: chunk }); break; }
+      catch (e) { lastErr = e; await sleep(1000 * 2 ** (attempt - 1)); }
+    }
+    if (!resp) {
+      // MUST-FIX: never send against a partially-populated contact set.
+      throw new Error(`contact upsert failed after 3 attempts (${lastErr?.message}) — ABORTING before the send stage`);
+    }
+    created += resp.created ?? 0; updated += resp.updated ?? 0; skippedN += resp.skipped ?? 0; dropped += resp.dropped_invalid ?? 0;
+    process.stdout.write(`  upserted ${Math.min(i + batchCap, uniq.length)}/${uniq.length}\r`);
+  }
+  console.log(`\n  contacts: +${created} created, ${updated} updated, ${skippedN} skipped${dropped ? `, ⚠ ${dropped} dropped as invalid server-side` : ""}`);
+  return { created, updated, skipped: skippedN, dropped };
+}
+
+function classifySendError(errText) {
+  const t = String(errText || "");
+  if (t.includes("#132000") || /parameters .*does not match/i.test(t)) return "config_fatal";
+  if (/messaging limit|daily.*cap|tier/i.test(t)) return "soft_stop";
+  if (/rate|too many|throughput|429/i.test(t)) return "retryable";
+  if (t.includes("#100")) return "invalid_param";
+  if (/contact not found/i.test(t)) return "contact_missing";
+  return "row_fatal";
+}
+
+async function sendOne(apiUrl, orgId, templateName, row) {
+  // #132000 structural guard: whitelist param\d+ keys only.
+  const bodyParameters = {};
+  for (const [k, v] of Object.entries(row.values)) {
+    if (!/^param\d+$/.test(k)) throw new Error(`internal: stray bodyParameters key "${k}" — refusing (V-12)`);
+    bodyParameters[k] = v;
+  }
+  const payload = {
+    templateName,
+    whatsappNumber: row.number,
+    bodyParameters,
+    ...(row.buttonValue != null ? { buttonParameters: { param1: row.buttonValue } } : {}),
+  };
+  // Org-UUID branch: NO auth header (a staff key here would 401 on the fiq_ branch).
+  const resp = await fetch(`${apiUrl.replace(/\/$/, "")}/send-template?organizationId=${orgId}`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(payload),
+  });
+  const json = await resp.json().catch(() => ({}));
+  const result = json?.results?.[0] ?? {};
+  const ok = json?.success === true && (result.success !== false) && (result.messageId || json?.messageId);
+  return { ok: !!ok, messageId: result.messageId ?? json?.messageId ?? null, error: result.error ?? json?.error ?? (resp.ok ? null : `HTTP ${resp.status}`) };
+}
+
+// ---------------------------------------------------------------------------
+// shared pipeline runner
+// ---------------------------------------------------------------------------
+
+async function runPipeline(orgId, opts, { commitStage, isResume }) {
+  if (!UUID_RE.test(orgId)) { console.error(`Error: "${orgId}" is not a valid organization UUID.`); process.exit(1); }
+  const campaign = opts.campaign || (opts.csv ? slugify(path.basename(opts.csv, path.extname(opts.csv)), "campaign") : null);
+  if (!campaign) { console.error("Error: pass --campaign (no CSV filename to derive it from)."); process.exit(1); }
+
+  let cfg = await loadCampaign(campaign);
+  const templateName = opts.template || cfg?.template_name;
+  if (!templateName) { console.error("Error: --template required (or an existing campaign config)."); process.exit(1); }
+  const csvPath = opts.csv || cfg?.csv?.path;
+  if (!csvPath) { console.error("Error: --csv required (or an existing campaign config)."); process.exit(1); }
+
+  // 1-3. introspect (doubles as org check)
+  let intro;
+  try { intro = await introspect(orgId, templateName); }
+  catch (e) { console.error(`Template introspection failed: ${e.message}`); if (e.body?.error) console.error(`  ${e.body.error}`); process.exit(1); }
+  const template = intro.template;
+  console.log(`Template ${template.name} [${template.status}] — ${template.parameter_format}, ${template.body_var_count} body var(s), header ${template.header_type}${template.url_button?.present ? ", dynamic URL button" : ""}`);
+
+  // 4. CSV
+  let csv;
+  try { csv = await loadCsv(csvPath); }
+  catch (e) { console.error(`CSV error: ${e.message}`); process.exit(1); }
+
+  // 5. mapping (load + revalidate, else interactive)
+  let mapping = cfg && !opts.forceRemap ? cfg : null;
+  if (mapping) {
+    const problems = [];
+    if (mapping.template_name !== templateName) problems.push(`saved mapping is for template ${mapping.template_name}`);
+    if (mapping.csv?.header_fingerprint !== csv.header_fingerprint) problems.push("CSV headers changed since the mapping was saved");
+    if (Object.keys(mapping.body_params || {}).length !== template.body_var_count) problems.push("template variable count changed");
+    if (problems.length) {
+      console.log(`Saved mapping can't be reused: ${problems.join("; ")} — rebuilding interactively.`);
+      mapping = null;
+    }
+  }
+  if (!mapping) {
+    const built = await interactiveMapping(template, csv.headers, campaign);
+    cfg = {
+      schema_version: 1,
+      campaign,
+      organization_id: orgId,
+      organization_slug: slugify(intro.organization_name, orgId.slice(0, 8)),
+      template_name: templateName,
+      parameter_format: template.parameter_format,
+      created_at: new Date().toISOString(),
+      csv: { path: csvPath, delimiter: csv.delimiter, headers: csv.headers, header_fingerprint: csv.header_fingerprint },
+      recipient: built.recipient,
+      body_params: built.body_params,
+      button_params: built.button_params,
+      options: { illegal_chars: opts.illegalChars || "reject" },
+    };
+    await saveCampaign(cfg);
+    console.log(`Saved mapping: ${cfgPath(campaign)}`);
+    mapping = cfg;
+  }
+
+  // 6. validate
+  const { aborts, valid, skipped } = validateRows(template, mapping, csv.headers, csv.rows, opts.illegalChars || mapping.options?.illegal_chars || "reject");
+  if (aborts.length) { for (const a of aborts) console.error(`ABORT — ${a}`); process.exit(1); }
+
+  // 6b. broadcast-safety exclusions (live)
+  let sendable = await applySafetyExclusions(orgId, valid, skipped);
+  if (opts.limit) sendable = sendable.slice(0, Number(opts.limit));
+
+  // resume folding
+  const { header: logHeader, map: statusMap } = await loadStatusLog(campaign);
+  if (isResume) {
+    if (!logHeader) { console.error(`No status log for campaign "${campaign}" — nothing to resume.`); process.exit(1); }
+    if (logHeader.csv_fingerprint && logHeader.csv_fingerprint !== csv.header_fingerprint) {
+      console.error("CSV headers changed since this campaign started — start a NEW campaign instead of resuming.");
+      process.exit(1);
+    }
+  }
+  const ambiguous = [];
+  const workSet = sendable.filter((r) => {
+    const st = statusMap.get(r.number);
+    if (!st) return true;
+    if (st.status === "sent") return false;
+    if (st.status === "sending") { ambiguous.push(r.number); return false; } // never auto-resend
+    if (st.status === "failed") return isResume ? !!opts.retryFailed : true;
+    return true;
+  });
+
+  // 7. preview
+  const skippedByReason = {};
+  for (const s of skipped) { const k = s.reason.split(":")[0]; skippedByReason[k] = (skippedByReason[k] ?? 0) + 1; }
+  console.log("");
+  const nPreview = Math.max(1, Number(opts.rows ?? 3));
+  const samples = [sendable[0], ...sendable.slice(1).filter((r, i, a) => a.findIndex((x) => x.values.param1 === r.values.param1) === i)].filter(Boolean).slice(0, nPreview);
+  for (const s of samples) { renderPreview(template, s); console.log(""); }
+  console.log(`Summary: ${sendable.length} sendable · skipped ${skipped.length} (${Object.entries(skippedByReason).map(([k, v]) => `${k}: ${v}`).join(", ") || "none"})`);
+  if (statusMap.size) console.log(`Status log: ${[...statusMap.values()].filter((s) => s.status === "sent").length} already sent · work set ${workSet.length}`);
+  if (ambiguous.length) console.log(`⚠ ${ambiguous.length} number(s) have an AMBIGUOUS in-flight status (crash mid-send?) — never auto-resent: ${ambiguous.slice(0, 5).join(", ")}${ambiguous.length > 5 ? "…" : ""}. Check the chat, then edit the status log if they must be retried.`);
+  console.log(`Upsert plan: ${workSet.length} contacts in ${Math.ceil(workSet.length / CONTACT_BATCH_CAP)} batch(es)`);
+  const rate = Math.min(Number(opts.rate ?? 8) || 8, HARD_RATE_CAP);
+  console.log(`Send plan:   ${workSet.length} messages @ ≤${rate}/s ≈ ${Math.ceil(workSet.length / rate)}s`);
+
+  if (!commitStage) {
+    console.log("");
+    console.log("DRY RUN — nothing was sent, no contacts written. Add --commit to send.");
+    return;
+  }
+  if (!workSet.length) { console.log("Nothing to send — all rows are already sent/skipped."); return; }
+
+  // 8. gate
+  if (!opts.yes) {
+    console.log("");
+    const answer = await ask(`Type the campaign name ("${campaign}") to send ${workSet.length} message(s): `);
+    if (answer !== campaign) { console.log("Mismatch — aborted, nothing sent."); process.exit(0); }
+  }
+
+  // 9. upsert
+  if (!opts.skipUpsert && !(isResume && logHeader)) {
+    try { await upsertContacts(orgId, workSet, Math.min(Number(opts.upsertBatch ?? CONTACT_BATCH_CAP) || CONTACT_BATCH_CAP, CONTACT_BATCH_CAP)); }
+    catch (e) { console.error(e.message); process.exit(1); }
+  }
+
+  // 10-11. send loop + report (shared with the --tag pipeline)
+  await executeSendLoop({
+    orgId, campaign, templateName, workSet, statusMap, rate,
+    skippedCount: skipped.length,
+    writeMetaHeader: !logHeader,
+    metaExtras: { csv_fingerprint: csv.header_fingerprint, total_rows: csv.rows.length, valid_rows: sendable.length },
+  });
+}
+
+/** The paced, write-ahead-logged per-row send loop + final report. */
+async function executeSendLoop({ orgId, campaign, templateName, workSet, statusMap, rate, skippedCount, writeMetaHeader, metaExtras }) {
+  const { api_url } = await loadConfig();
+  if (writeMetaHeader) {
+    await appendLog(campaign, {
+      type: "meta", campaign, organization_id: orgId, template_name: templateName,
+      ...(metaExtras || {}),
+      started_at: new Date().toISOString(),
+    });
+  }
+  let sent = 0, failed = 0, effRate = rate;
+  const perMsgMs = () => Math.ceil(1000 / Math.max(1, effRate));
+  console.log(`Sending ${workSet.length} messages @ ≤${effRate}/s …`);
+
+  outer: for (const [i, row] of workSet.entries()) {
+    const rowStart = Date.now();
+    const attemptBase = (statusMap.get(row.number)?.attempt ?? 0) + 1;
+    for (let attempt = attemptBase; ; attempt++) {
+      // WRITE-AHEAD: sending line BEFORE the POST.
+      await appendLog(campaign, { type: "row", number: row.number, rownum: row.rownum, status: "sending", attempt, at: new Date().toISOString() });
+      let out;
+      try { out = await sendOne(api_url, orgId, templateName, row); }
+      catch (e) {
+        // network/timeout with no response = UNKNOWN outcome → ambiguous, never auto-retried
+        await appendLog(campaign, { type: "row", number: row.number, rownum: row.rownum, status: "unknown", error: e.message, attempt, at: new Date().toISOString() });
+        console.error(`\n  ${row.number}: network error mid-send (${e.message}) — outcome UNKNOWN, left for manual review.`);
+        failed++;
+        break;
+      }
+      if (out.ok) {
+        await appendLog(campaign, { type: "row", number: row.number, rownum: row.rownum, status: "sent", message_id: out.messageId, attempt, at: new Date().toISOString() });
+        sent++;
+        break;
+      }
+      const cls = classifySendError(out.error);
+      if (cls === "retryable" && attempt < attemptBase + 5) {
+        await appendLog(campaign, { type: "row", number: row.number, rownum: row.rownum, status: "retrying", error: String(out.error), attempt, at: new Date().toISOString() });
+        await sleep(Math.min(500 * 2 ** (attempt - attemptBase), 30000));
+        continue;
+      }
+      await appendLog(campaign, { type: "row", number: row.number, rownum: row.rownum, status: "failed", error: String(out.error), attempt, at: new Date().toISOString() });
+      failed++;
+      if (cls === "config_fatal") {
+        console.error(`\nABORT — Meta #132000 on ${row.number}: ${out.error}`);
+        console.error("The parameters produce the wrong count; every row would fail. Fix the mapping/params and resume.");
+        break outer;
+      }
+      if (cls === "soft_stop") {
+        console.error(`\nSOFT STOP — Meta messaging limit reached (${out.error}). Remaining rows stay pending; resume tomorrow:`);
+        console.error(`  flowiq broadcast resume ${orgId} --campaign ${campaign} --commit`);
+        break outer;
+      }
+      if (cls === "retryable") effRate = Math.max(1, Math.floor(effRate / 2));
+      break;
+    }
+    const spent = Date.now() - rowStart;
+    await sleep(Math.max(0, perMsgMs() - spent));
+    if ((i + 1) % 25 === 0 || i === workSet.length - 1) {
+      process.stdout.write(`  ${sent} sent · ${failed} failed · ${workSet.length - sent - failed} pending (${Math.round(((i + 1) / workSet.length) * 100)}%)\r`);
+    }
+  }
+
+  console.log("\n");
+  console.log(`Broadcast — ${campaign}`);
+  console.log(`  sent:    ${sent}`);
+  console.log(`  failed:  ${failed}`);
+  console.log(`  skipped: ${skippedCount} [pre-send validation/safety]`);
+  console.log(`  status log: ${logPath(campaign)}`);
+  if (failed || workSet.length > sent + failed) {
+    console.log(`  Re-run failed/pending: flowiq broadcast resume ${orgId} --campaign ${campaign} --commit --retry-failed`);
+  }
+  await fs.writeFile(path.join(CAMPAIGN_DIR, `${campaign}.report.json`),
+    JSON.stringify({ campaign, sent, failed, skipped: skippedCount, finished_at: new Date().toISOString() }, null, 2) + "\n", "utf8");
+}
+
+// ---------------------------------------------------------------------------
+// tag pipeline (`send --tag` — the segments↔broadcast bridge)
+// ---------------------------------------------------------------------------
+
+/** Commander collector for repeatable k=v flags (`--body param1="Hi {{first_name}}"`). */
+export function collectKV(pair, mapAcc) {
+  const idx = pair.indexOf("=");
+  if (idx < 1) throw new Error(`Expected k=v (got "${pair}")`);
+  mapAcc[pair.slice(0, idx)] = pair.slice(idx + 1);
+  return mapAcc;
+}
+
+async function runTagPipeline(orgId, opts, { commitStage }) {
+  if (!UUID_RE.test(orgId)) { console.error(`Error: "${orgId}" is not a valid organization UUID.`); process.exit(1); }
+  const campaign = opts.campaign || slugify(opts.tag, "tag-campaign");
+  let cfg = await loadCampaign(campaign);
+  if (cfg && cfg.mode !== "tag") { console.error(`Campaign "${campaign}" is a CSV campaign — pick a different --campaign for the tag send.`); process.exit(1); }
+  const tag = opts.tag || cfg?.tag;
+  const templateName = opts.template || cfg?.template_name;
+  if (!tag || !templateName) { console.error("Error: --tag and --template required (or an existing tag campaign config)."); process.exit(1); }
+  const bodyLiterals = Object.keys(opts.body || {}).length ? opts.body : (cfg?.body_params_literal ?? {});
+  const buttonLiteral = (opts.button && opts.button.param1) ?? cfg?.button_param_literal ?? null;
+
+  // introspect + validate params arithmetically (the #132000 guard, pre-send)
+  let intro;
+  try { intro = await introspect(orgId, templateName); }
+  catch (e) { console.error(`Template introspection failed: ${e.message}`); if (e.body?.error) console.error(`  ${e.body.error}`); process.exit(1); }
+  const template = intro.template;
+  console.log(`Template ${template.name} [${template.status}] — ${template.parameter_format}, ${template.body_var_count} body var(s), header ${template.header_type}${template.url_button?.present ? ", dynamic URL button" : ""}`);
+  const aborts = [];
+  if (template.status !== "APPROVED") aborts.push(`template status is ${template.status} — only APPROVED templates send`);
+  if (template.parameter_format !== "POSITIONAL") aborts.push("NAMED templates are not supported in v1");
+  if (template.is_carousel) aborts.push("carousel templates are not supported in v1");
+  if (!["text", "none"].includes(template.header_type)) aborts.push(`media-header templates (${template.header_type}) are not supported in v1`);
+  const keys = Object.keys(bodyLiterals);
+  if (keys.some((k) => !/^param\d+$/.test(k))) aborts.push(`--body keys must be param1..N (got ${keys.join(", ")})`);
+  if (keys.length !== template.body_var_count) aborts.push(`template expects ${template.body_var_count} body param(s), you provided ${keys.length} (--body paramN=…). Values may use {{first_name}}/{{full_name}}/{{email}}/{{phone_number}} — resolved per contact.`);
+  if (template.url_button?.present && !buttonLiteral) aborts.push("template has a dynamic URL button — pass --button param1=<code>");
+  if (aborts.length) { for (const a of aborts) console.error(`ABORT — ${a}`); process.exit(1); }
+
+  // resolve the tag server-side (broadcast-safe recipients only)
+  let resolved;
+  try { resolved = await http.post("broadcast", { action: "resolve-tag", organization_id: orgId, tag }); }
+  catch (e) { console.error(`Tag resolution failed: ${e.message}`); if (e.body?.error) console.error(`  ${e.body.error}`); process.exit(1); }
+  console.log(`Tag "${tag}" on ${resolved.organization_name}: ${resolved.tagged_total} contact(s), ${resolved.recipients.length} sendable, ${resolved.excluded.length} excluded (opt-out/archived/blocked).`);
+  if (!resolved.recipients.length) { console.log("Nothing sendable under this tag."); return; }
+
+  const values = {};
+  for (const [k, v] of Object.entries(bodyLiterals)) values[k] = String(v);
+  let sendable = resolved.recipients.map((r, i) => ({
+    rownum: i + 1, number: r.number, values, buttonValue: buttonLiteral, contactName: r.full_name,
+  }));
+  if (opts.limit) sendable = sendable.slice(0, Number(opts.limit));
+
+  // resume folding (same semantics as the CSV path)
+  const { header: logHeader, map: statusMap } = await loadStatusLog(campaign);
+  const ambiguous = [];
+  const workSet = sendable.filter((r) => {
+    const st = statusMap.get(r.number);
+    if (!st) return true;
+    if (st.status === "sent") return false;
+    if (st.status === "sending") { ambiguous.push(r.number); return false; }
+    if (st.status === "failed") return !!opts.retryFailed || !logHeader;
+    return true;
+  });
+
+  console.log("");
+  renderPreview(template, sendable[0]);
+  if (Object.values(bodyLiterals).some((v) => /\{\{(first_name|full_name|email|phone_number|whatsapp_id)\}\}/.test(String(v)))) {
+    console.log("  ({{first_name}}-style tokens above are resolved PER CONTACT server-side)");
+  }
+  console.log("");
+  console.log(`Summary: ${sendable.length} sendable · ${resolved.excluded.length} excluded`);
+  if (statusMap.size) console.log(`Status log: ${[...statusMap.values()].filter((s) => s.status === "sent").length} already sent · work set ${workSet.length}`);
+  if (ambiguous.length) console.log(`⚠ ${ambiguous.length} AMBIGUOUS in-flight number(s) — never auto-resent: ${ambiguous.slice(0, 5).join(", ")}${ambiguous.length > 5 ? "…" : ""}`);
+  const rate = Math.min(Number(opts.rate ?? 8) || 8, HARD_RATE_CAP);
+  console.log(`Send plan:   ${workSet.length} messages @ ≤${rate}/s ≈ ${Math.ceil(Math.max(1, workSet.length) / rate)}s`);
+
+  if (!commitStage) {
+    console.log("");
+    console.log("DRY RUN — nothing was sent. Add --commit to send.");
+    return;
+  }
+  if (!workSet.length) { console.log("Nothing to send — all rows are already sent."); return; }
+
+  if (!opts.yes) {
+    console.log("");
+    const answer = await ask(`Type the campaign name ("${campaign}") to send ${workSet.length} message(s): `);
+    if (answer !== campaign) { console.log("Mismatch — aborted, nothing sent."); process.exit(0); }
+  }
+
+  // Persist the tag campaign config so `resume` can reconstruct it.
+  await saveCampaign({
+    schema_version: 1, campaign, mode: "tag",
+    organization_id: orgId, organization_slug: slugify(resolved.organization_name, orgId.slice(0, 8)),
+    template_name: templateName, tag,
+    body_params_literal: bodyLiterals, button_param_literal: buttonLiteral,
+    created_at: cfg?.created_at ?? new Date().toISOString(),
+  });
+
+  await executeSendLoop({
+    orgId, campaign, templateName, workSet, statusMap, rate,
+    skippedCount: resolved.excluded.length,
+    writeMetaHeader: !logHeader,
+    metaExtras: { tag, tagged_total: resolved.tagged_total, valid_rows: sendable.length },
+  });
+}
+
+// ---------------------------------------------------------------------------
+// verbs
+// ---------------------------------------------------------------------------
+
+export async function map(orgId, opts = {}) {
+  if (!UUID_RE.test(orgId)) { console.error(`Error: "${orgId}" is not a valid organization UUID.`); process.exit(1); }
+  const campaign = opts.campaign || slugify(path.basename(opts.csv, path.extname(opts.csv)), "campaign");
+  let intro;
+  try { intro = await introspect(orgId, opts.template); }
+  catch (e) { console.error(`Template introspection failed: ${e.message}`); if (e.body?.error) console.error(`  ${e.body.error}`); process.exit(1); }
+  let csv;
+  try { csv = await loadCsv(opts.csv); }
+  catch (e) { console.error(`CSV error: ${e.message}`); process.exit(1); }
+  const existing = await loadCampaign(campaign);
+  if (existing && !opts.forceRemap) {
+    console.log(`Campaign "${campaign}" already has a saved mapping (${cfgPath(campaign)}) — use --force-remap to rebuild.`);
+    return;
+  }
+  const built = await interactiveMapping(intro.template, csv.headers, campaign);
+  await saveCampaign({
+    schema_version: 1, campaign, organization_id: orgId,
+    organization_slug: slugify(intro.organization_name, orgId.slice(0, 8)),
+    template_name: opts.template, parameter_format: intro.template.parameter_format,
+    created_at: new Date().toISOString(),
+    csv: { path: opts.csv, delimiter: csv.delimiter, headers: csv.headers, header_fingerprint: csv.header_fingerprint },
+    recipient: built.recipient, body_params: built.body_params, button_params: built.button_params,
+    options: { illegal_chars: "reject" },
+  });
+  console.log(`Saved mapping: ${cfgPath(campaign)}`);
+}
+
+export async function preview(orgId, opts = {}) {
+  await runPipeline(orgId, opts, { commitStage: false, isResume: false });
+}
+
+export async function send(orgId, opts = {}) {
+  if (opts.tag && opts.csv) { console.error("Error: --tag and --csv are mutually exclusive."); process.exit(1); }
+  if (opts.tag) return runTagPipeline(orgId, opts, { commitStage: !!opts.commit });
+  await runPipeline(orgId, opts, { commitStage: !!opts.commit, isResume: !!opts.resume });
+}
+
+export async function resume(orgId, opts = {}) {
+  const cfg = opts.campaign ? await loadCampaign(opts.campaign) : null;
+  if (cfg?.mode === "tag") return runTagPipeline(orgId, { ...opts, tag: cfg.tag }, { commitStage: !!opts.commit });
+  await runPipeline(orgId, opts, { commitStage: !!opts.commit, isResume: true });
+}
+
+export async function list() {
+  let files;
+  try { files = (await fs.readdir(CAMPAIGN_DIR)).filter((f) => f.endsWith(".json") && !f.endsWith(".report.json")); }
+  catch { console.log("(no local campaigns; run `broadcast map <org_id> --template … --csv …`)"); return; }
+  if (!files.length) { console.log("(no local campaigns)"); return; }
+  files.sort();
+  for (const f of files) {
+    try {
+      const d = JSON.parse(await fs.readFile(path.join(CAMPAIGN_DIR, f), "utf8"));
+      const { map: statusMap } = await loadStatusLog(d.campaign);
+      const sent = [...statusMap.values()].filter((s) => s.status === "sent").length;
+      console.log(f);
+      console.log(`  org:       ${d.organization_slug ?? d.organization_id} · template ${d.template_name}`);
+      console.log(`  csv:       ${d.csv?.path} (${(d.csv?.headers || []).join(", ")})`);
+      console.log(`  sent:      ${sent} (status log)`);
+    } catch (e) {
+      console.log(`${f}  [invalid JSON: ${e.message}]`);
+    }
+  }
+}