@flowapt/flowiq-cli 0.9.9 → 0.11.0

package/src/commands/tag.js

@@ -8,8 +8,12 @@
 //   flowiq tag segment <org> --min-orders 2 --min-spent 1000 --region ZA-GP --tag gp-repeat
 //   flowiq tag attributes <org> --filter allow_broadcast_true --tag broadcastable
 //   flowiq tag messages   <org> --min-count 3 --sender user-whatsapp --tag engaged
+//   flowiq tag ids     <org> --ids a,b,c | --ids-file ids.txt --tag <name> [--commit]
+//   flowiq tag holders <org> <tag> [--limit 200] [--all] [--csv]
+//   flowiq tag field   <org> --field whatsapp_id --any 27794975464 --exact --tag x --commit
 //   flowiq tag list    <org>
-//   flowiq tag remove  <org> <tag>[,<tag>...] --confirm
+//   flowiq tag remove  <org> <tag>[,<tag>...] --confirm              (every contact)
+//   flowiq tag remove  <org> <tag> --contacts a,b | --contacts-file f --confirm   (those only)
 //
 // Every match mode prints the dry-run count + a sample; nothing writes until
 // --commit AND (for large writes) a typed confirmation. Appends only — it
@@ -91,12 +95,76 @@ export async function field(orgId, opts = {}) {
   requireOrg(orgId);
   const keywords = splitList(opts.any || opts.all);
   if (!keywords) { console.error("Error: pass --any \"a,b\" (OR) or --all \"a,b\" (AND)."); process.exit(1); }
+  if (opts.exact && opts.all) { console.error("Error: --exact matches whole values, so it is an OR over --any (drop --all)."); process.exit(1); }
   const payload = {
     mode: "field", organization_id: orgId, field_name: opts.field || "order_history",
-    keywords, logic: opts.all ? "AND" : "OR", case_sensitive: !!opts.caseSensitive,
+    keywords, logic: opts.all ? "AND" : "OR", case_sensitive: !!opts.caseSensitive, exact: !!opts.exact,
   };
   await confirmLargeWrite(orgId, payload, opts, "Field search");
-  await runMatch("Field search", payload, opts);
+  await runMatch(opts.exact ? "Exact field match" : "Field search", payload, opts);
+}
+
+async function readIds(csv, file) {
+  const fs = await import("node:fs/promises");
+  let ids = splitList(csv) || [];
+  if (file) {
+    const text = await fs.readFile(file, "utf8").catch((e) => { console.error(`Error: cannot read ${file}: ${e.message}`); process.exit(1); });
+    ids.push(...text.split(/[\s,]+/).map((s) => s.trim()).filter(Boolean));
+  }
+  ids = [...new Set(ids)];
+  const bad = ids.filter((id) => !UUID_RE.test(id));
+  if (bad.length) console.error(`⚠ ${bad.length} value(s) are not contact UUIDs and will be ignored (e.g. ${bad[0]})`);
+  return ids.filter((id) => UUID_RE.test(id));
+}
+
+// `flowiq tag ids <org> --ids a,b | --ids-file f --tag <name> [--commit]`
+export async function ids(orgId, opts = {}) {
+  requireOrg(orgId);
+  const list = await readIds(opts.ids, opts.idsFile);
+  if (!list.length) { console.error("Error: pass --ids a,b,c or --ids-file <path> (contact UUIDs, one per line or comma-separated)."); process.exit(1); }
+  const payload = { mode: "ids", organization_id: orgId, contact_ids: list };
+  await confirmLargeWrite(orgId, payload, opts, "Id list");
+  const commit = !!opts.commit;
+  if (commit && !opts.tag) { console.error("Error: --tag <name> is required with --commit."); process.exit(1); }
+  let resp;
+  try { resp = await http.post("tag", { ...payload, dry_run: !commit, tag: commit ? opts.tag.trim() : undefined }); }
+  catch (e) { console.error(`Tag ids failed: ${e.message}`); if (e.body?.error && !e.message.includes(e.body.error)) console.error(`  ${e.body.error}`); process.exit(1); }
+  if (opts.json) { console.log(JSON.stringify(resp, null, 2)); return; }
+  if (!commit) {
+    console.log(`Id list: ${resp.matched} of ${list.length} id(s) belong to ${resp.organization_name}${resp.not_found ? ` · ${resp.not_found} not in this org (ignored)` : ""}.`);
+    renderSample(resp.sample);
+    console.log(`\nAdd --tag <name> --commit to apply. (dry run — nothing written)`);
+    return;
+  }
+  console.log(`Id list: matched ${resp.matched} · newly tagged ${resp.tagged} · already had "${resp.tag}" ${resp.already_had}${resp.not_found ? ` · not in org ${resp.not_found}` : ""}.`);
+  console.log(`\nVerify: flowiq tag holders ${orgId} ${resp.tag}   ·   Undo: flowiq tag remove ${orgId} ${resp.tag} --contacts-file <the same file> --confirm`);
+}
+
+// `flowiq tag holders <org> <tag> [--limit] [--all] [--csv]` — who carries a tag.
+export async function holders(orgId, tagName, opts = {}) {
+  requireOrg(orgId);
+  if (!tagName) { console.error("Error: pass the tag name, e.g. flowiq tag holders <org> vip"); process.exit(1); }
+  const pageSize = opts.all ? 1000 : Math.min(Number(opts.limit) || 200, 1000);
+  const contacts = [];
+  let offset = 0, resp;
+  for (;;) {
+    try { resp = await http.post("tag", { mode: "holders", organization_id: orgId, tag: tagName, limit: pageSize, offset }); }
+    catch (e) { console.error(`Holders failed: ${e.message}`); if (e.body?.error && !e.message.includes(e.body.error)) console.error(`  ${e.body.error}`); process.exit(1); }
+    contacts.push(...(resp.contacts || []));
+    if (!opts.all || !resp.has_more || !(resp.contacts || []).length) break;
+    offset += resp.contacts.length;
+  }
+  if (opts.json) { console.log(JSON.stringify({ ...resp, contacts }, null, 2)); return; }
+  if (opts.csv) {
+    console.log("id,full_name,whatsapp_id,email,allow_broadcast,archived,blocked");
+    for (const c of contacts) console.log([c.id, c.full_name, c.whatsapp_id, c.email, c.allow_broadcast, c.archived, c.blocked].map((v) => { const s = v == null ? "" : String(v); return /[",\n]/.test(s) ? `"${s.replace(/"/g, '""')}"` : s; }).join(","));
+    return;
+  }
+  console.log(`"${tagName}" on ${resp.organization_name}: ${resp.total} contact(s)${contacts.length < resp.total ? ` (showing ${contacts.length}; --all for every page, --csv to export)` : ""}`);
+  for (const c of contacts) {
+    const flags = [c.allow_broadcast === false && "no-broadcast", c.archived && "archived", c.blocked && "blocked", c.bot_status === false && "AI off"].filter(Boolean).join(", ");
+    console.log(`  ${(c.full_name || "—").slice(0, 28).padEnd(28)} ${String(c.whatsapp_id || c.email || "").padEnd(16)} ${c.id}${flags ? `  (${flags})` : ""}`);
+  }
 }
 
 export async function cohort(orgId, opts = {}) {
@@ -170,12 +238,14 @@ export async function remove(orgId, tagArg, opts = {}) {
   requireOrg(orgId);
   const tags = splitList(tagArg);
   if (!tags || !tags.length) { console.error("Error: pass one or more tag names (comma-separated)."); process.exit(1); }
+  const contactIds = opts.contacts || opts.contactsFile ? await readIds(opts.contacts, opts.contactsFile) : null;
+  if ((opts.contacts || opts.contactsFile) && !contactIds.length) { console.error("Error: --contacts / --contacts-file gave no contact UUIDs."); process.exit(1); }
   if (!opts.confirm) {
-    console.log(`DRY RUN — would remove ${tags.length} tag(s) from all contacts: ${tags.join(", ")}. Add --confirm to remove.`);
+    console.log(`DRY RUN — would remove ${tags.length} tag(s) from ${contactIds ? `${contactIds.length} listed contact(s)` : "ALL contacts"}: ${tags.join(", ")}. Add --confirm to remove.`);
     return;
   }
   let resp;
-  try { resp = await http.post("tag", { mode: "remove", organization_id: orgId, tags }); }
-  catch (e) { console.error(`Remove failed: ${e.message}`); process.exit(1); }
-  console.log(`Removed ${tags.join(", ")} from ${resp.contacts_touched} contact(s) on ${resp.organization_name}.`);
+  try { resp = await http.post("tag", { mode: "remove", organization_id: orgId, tags, ...(contactIds ? { contact_ids: contactIds } : {}) }); }
+  catch (e) { console.error(`Remove failed: ${e.message}`); if (e.body?.error && !e.message.includes(e.body.error)) console.error(`  ${e.body.error}`); process.exit(1); }
+  console.log(`Removed ${tags.join(", ")} from ${resp.contacts_touched} contact(s) on ${resp.organization_name}${contactIds ? ` (of ${contactIds.length} listed${resp.not_found ? `, ${resp.not_found} not in this org` : ""})` : ""}.`);
 }

package/src/commands/templates.js

@@ -343,8 +343,37 @@ export async function show(orgId, name, opts = {}) {
 
   const rows = resp.templates || [];
   if (!rows.length) {
-    console.error(`No template on this org matching "${name}". List them with: flowiq templates status ${orgId}`);
-    process.exit(1);
+    // Not in FlowIQ's table is not "does not exist": a template made in Meta's
+    // own tools or on a swapped WABA lives only at Meta (Health Matrix, 22 Sep
+    // 2026). Read it from Meta before giving up.
+    let live;
+    try { live = await http.get("templates", { organization_id: orgId, name }); } catch { live = null; }
+    const liveRows = (live?.templates || []).filter((t) => t.name === name) .concat((live?.templates || []).filter((t) => t.name !== name));
+    if (!liveRows.length) {
+      console.error(`No template on this org matching "${name}", in FlowIQ or at Meta. List them with: flowiq templates status ${orgId} --live`);
+      process.exit(1);
+    }
+    const t = liveRows[0];
+    if (liveRows.length > 1 && t.name !== name) {
+      console.error(`"${name}" matches ${liveRows.length} templates at Meta — name one exactly:`);
+      for (const r of liveRows) console.error(`  ${r.name}  [${r.status}] ${r.category}`);
+      process.exit(1);
+    }
+    if (opts.json) { console.log(JSON.stringify({ source: "meta", template: t }, null, 2)); return; }
+    console.log(`${t.name}  [${t.status}] ${t.category}${t.previous_category && t.previous_category !== t.category ? ` (was ${t.previous_category})` : ""} · ${t.language}${t.parameter_format ? ` · ${t.parameter_format}` : ""}`);
+    console.log(`  org:       ${orgId}`);
+    console.log(`  source:    META ONLY — not recorded in FlowIQ's templates table (made in Meta's tools or on another WABA), so it cannot be picked in the send dialog until it is pulled in`);
+    if (t.id) console.log(`  meta id:   ${t.id}`);
+    if (t.rejected_reason && t.rejected_reason !== "NONE") console.log(`  rejected:  ${t.rejected_reason}`);
+    for (const c of t.components || []) {
+      const label = String(c.type || "").toLowerCase().padEnd(9);
+      if (c.type === "BODY" || c.type === "FOOTER") console.log(`  ${label}  ${String(c.text || "").replace(/\n/g, "\n             ")}`);
+      else if (c.type === "HEADER") console.log(`  ${label}  ${c.format}${c.text ? `: ${c.text}` : ""}`);
+      else if (c.type === "BUTTONS") for (const b of c.buttons || []) console.log(`  button     ${b.type}: ${b.text}${b.url ? ` → ${b.url}` : ""}${b.phone_number ? ` → ${b.phone_number}` : ""}`);
+      else if (c.type === "CAROUSEL") console.log(`  carousel   ${(c.cards || []).length} card(s)`);
+    }
+    console.log(`\n  The full Meta record: flowiq templates pull ${orgId}`);
+    return;
   }
   // Prefer an exact name match; otherwise if the substring is ambiguous, say so.
   let row = rows.find((r) => r.template_name === name);
@@ -444,22 +473,54 @@ export async function attempts(orgId, opts = {}) {
   if (opts.json) { console.log(JSON.stringify(resp, null, 2)); return; }
 
   const rows = resp.attempts || [];
-  if (!rows.length) {
+  const logs = resp.status_logs || [];
+  if (!rows.length && !logs.length) {
     console.log(opts.failed ? "(no failed submissions on record for this org)" : "(no template submissions on record for this org — the ledger started 21 Sep 2026)");
     return;
   }
-  console.log(`${rows.length} submission${rows.length === 1 ? "" : "s"}${opts.failed ? " (failed only)" : ""}, newest first (SAST):`);
+  // Meta's history per template, newest first: what happened AFTER submit.
+  // A category flip shows as the same status with a new category.
+  const historyOf = (name) => logs.filter((l) => l.template_name === name);
+  const describeHistory = (name, submittedCategory) => {
+    const h = historyOf(name).slice().reverse(); // oldest first
+    if (!h.length) return [];
+    const lines = [];
+    let lastCat = submittedCategory || null;
+    for (const l of h) {
+      const flipped = l.category && lastCat && l.category !== lastCat;
+      lines.push(`${sast(l.created_at)}  ${l.status}${l.category ? ` / ${l.category}` : ""}${flipped ? `  ⚠ CATEGORY MOVED ${lastCat} → ${l.category}` : ""}${l.reason ? `  (${l.reason})` : ""}`);
+      if (l.category) lastCat = l.category;
+    }
+    return lines;
+  };
+  if (rows.length) console.log(`${rows.length} submission${rows.length === 1 ? "" : "s"}${opts.failed ? " (failed only)" : ""}, newest first (SAST):`);
+  const named = new Set();
   for (const a of rows) {
     const mark = a.outcome === "submitted" ? "✓" : "✗";
     const who = a.source ? `  via ${a.source}` : "";
     console.log(`\n  ${mark} ${sast(a.created_at)}  ${a.template_name || "(unnamed)"}${a.category ? ` [${a.category}]` : ""}${who}`);
     if (a.outcome === "submitted") {
       console.log(`      submitted to Meta — id ${a.meta_template_id || "?"}, status at submit ${a.meta_status || "?"}`);
+      const hist = describeHistory(a.template_name, a.category);
+      named.add(a.template_name);
+      if (hist.length) for (const line of hist) console.log(`      then: ${line}`);
+      else console.log(`      no status webhook from Meta recorded yet (still ${a.meta_status || "PENDING"} as far as FlowIQ knows: flowiq templates status ${orgId} --live --name ${a.template_name})`);
     } else {
       console.log(`      FAILED (HTTP ${a.http_status ?? "?"}) ${a.error || ""}`);
       if (a.message && a.message !== a.error) console.log(`      ${a.message}`);
       if (a.meta_error?.error_user_msg && a.meta_error.error_user_msg !== a.message) console.log(`      Meta: ${a.meta_error.error_user_msg}`);
     }
   }
-  console.log(`\nA failed row is the reason the template is not in \`templates status\` — fix what the message names and submit again.`);
+  // Templates with Meta history but no submission row (submitted before the
+  // ledger existed, or from Meta's own tools): still worth showing when asked
+  // for by name, or when nothing else matched.
+  const orphan = [...new Set(logs.map((l) => l.template_name))].filter((n) => !named.has(n));
+  if (orphan.length && (opts.name || !rows.length)) {
+    console.log(`\nMeta status history with no submission row (older than the ledger, or submitted outside FlowIQ):`);
+    for (const n of orphan.slice(0, 20)) {
+      console.log(`\n  ${n}`);
+      for (const line of describeHistory(n, null)) console.log(`      ${line}`);
+    }
+  }
+  if (rows.length) console.log(`\nA failed row is the reason the template is not in \`templates status\` — fix what the message names and submit again.`);
 }

package/src/commands/tickets.js

@@ -0,0 +1,69 @@
+// `flowiq tickets list|show|status` — escalation tickets (server: api/cli/tickets.js).
+
+import { http } from "../http.js";
+import { fmtSast } from "./audit.js";
+
+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 pad = (s, n) => String(s ?? "").padEnd(n);
+function fail(prefix, e) { console.error(`${prefix}: ${e.message}`); if (e.body?.error && !e.message.includes(e.body.error)) console.error(`  ${e.body.error}`); process.exit(1); }
+
+export function parseOlderThan(v) {
+  if (v == null || v === "") return undefined;
+  const m = /^(\d+)([hdw])$/i.exec(String(v).trim());
+  if (!m) { console.error(`Error: --older-than takes 48h / 3d / 1w (got "${v}").`); process.exit(1); }
+  return Number(m[1]) * { h: 1, d: 24, w: 168 }[m[2].toLowerCase()];
+}
+
+export async function list(orgId, opts = {}) {
+  if (!UUID_RE.test(orgId || "")) { console.error(`Error: "${orgId}" is not a valid organization UUID.`); process.exit(1); }
+  let resp;
+  try { resp = await http.get("tickets", { organization_id: orgId, status: opts.status, contact_id: opts.contact, older_than_hours: parseOlderThan(opts.olderThan), limit: opts.limit }); }
+  catch (e) { fail("List failed", e); }
+  if (opts.json) { console.log(JSON.stringify(resp, null, 2)); return; }
+  if (!resp.tickets.length) { console.log(`No ${resp.statuses.join("/")} ticket(s) on ${resp.organization_name}${opts.olderThan ? ` older than ${opts.olderThan}` : ""}.`); return; }
+  console.log(`${resp.organization_name}: ${resp.capped ? `${resp.tickets.length} of ${resp.total}` : resp.tickets.length} ${resp.statuses.join("/")} ticket(s), newest first`);
+  console.log("");
+  console.log(`  ${pad("OPENED (SAST)", 17)} ${pad("AGE", 6)} ${pad("STATUS", 12)} ${pad("CONTACT", 26)} ${pad("TEAM", 14)} SUMMARY`);
+  for (const t of resp.tickets) {
+    const who = `${t.contact?.full_name ?? "?"}${t.contact?.whatsapp_id ? ` ${t.contact.whatsapp_id}` : ""}`.slice(0, 26);
+    console.log(`  ${pad(fmtSast(t.created_at), 17)} ${pad(`${t.age_hours}h`, 6)} ${pad(t.status, 12)} ${pad(who, 26)} ${pad(t.team ?? "", 14)} ${String(t.summary ?? "").replace(/\s+/g, " ").slice(0, 70)}`);
+    console.log(`  ${" ".repeat(17)} ${t.id}${t.contact?.bot_status === false ? "  AI off on contact" : ""}${t.reopened_count ? `  reopened ${t.reopened_count}x` : ""}`);
+  }
+  if (resp.capped) console.log(`\n  ${resp.total - resp.tickets.length} more; narrow with --contact / --older-than or raise --limit (max 500).`);
+  console.log(`\nflowiq tickets show <ticket_id> · flowiq tickets status <ticket_id> --set resolved --commit`);
+}
+
+export async function show(ticketId, opts = {}) {
+  if (!UUID_RE.test(ticketId || "")) { console.error(`Error: "${ticketId}" is not a valid ticket UUID.`); process.exit(1); }
+  let resp;
+  try { resp = await http.get("tickets", { ticket_id: ticketId }); } catch (e) { fail("Read failed", e); }
+  if (opts.json) { console.log(JSON.stringify(resp, null, 2)); return; }
+  const t = resp.ticket;
+  console.log(`Ticket ${t.id} on ${resp.organization_name}: ${t.status}${t.type ? ` (${t.type})` : ""}`);
+  console.log(`  contact:   ${t.contact?.full_name ?? "?"} ${t.contact?.whatsapp_id ?? ""} (${t.contact_id})${t.contact?.bot_status === false ? " · AI off" : ""}`);
+  console.log(`  opened:    ${fmtSast(t.created_at)} SAST (${t.age_hours}h ago)${t.team ? ` · team ${t.team}` : ""}`);
+  console.log(`  summary:   ${t.summary ?? "(none)"}`);
+  if (t.resolved_at) console.log(`  resolved:  ${fmtSast(t.resolved_at)} SAST by ${t.resolved_by ?? "?"}`);
+  if (t.csat_sent_at) console.log(`  csat sent: ${fmtSast(t.csat_sent_at)} SAST`);
+  if (t.reopened_count) console.log(`  reopened:  ${t.reopened_count}x (${t.data?.reopen_reason ?? ""})`);
+  if (Array.isArray(t.data?.status_history) && t.data.status_history.length) {
+    console.log("  history:");
+    for (const h of t.data.status_history.slice(-10)) console.log(`    ${fmtSast(h.at ?? h.timestamp ?? h.changed_at)} ${h.from ?? "?"} → ${h.to ?? h.status ?? "?"} by ${h.by ?? "?"}${h.note ? ` (${h.note})` : ""}`);
+  }
+}
+
+export async function status(ticketId, opts = {}) {
+  if (!UUID_RE.test(ticketId || "")) { console.error(`Error: "${ticketId}" is not a valid ticket UUID.`); process.exit(1); }
+  if (!opts.set) { console.error("Error: --set open|in_progress|resolved|closed is required."); process.exit(1); }
+  let resp;
+  try { resp = await http.post("tickets", { action: "status", ticket_id: ticketId, status: opts.set, note: opts.note, dry_run: !opts.commit }); }
+  catch (e) { fail("Status change failed", e); }
+  if (opts.json) { console.log(JSON.stringify(resp, null, 2)); return; }
+  if (resp.unchanged) { console.log(`Ticket is already ${opts.set}.`); return; }
+  if (resp.dry_run) {
+    console.log(`Ticket ${ticketId} (${resp.ticket.contact?.full_name ?? resp.ticket.contact_id}, ${resp.organization_name}): ${resp.ticket.status} → ${resp.would_set.status}${resp.would_reenable_bot ? "\n  the org re-enables AI on resolve: the contact's agent would be switched back on" : ""}`);
+    console.log("DRY RUN — add --commit to write.");
+    return;
+  }
+  console.log(`✓ ticket ${ticketId}: ${resp.previous_status} → ${resp.ticket.status}${resp.bot_reenabled ? " · contact's AI re-enabled" : ""}`);
+}

package/src/commands/widgets.js

@@ -0,0 +1,97 @@
+// `flowiq widgets list|show|pull|push|embed|activate` — the web chat widgets
+// (server: api/cli/widgets.js). A push is an id-keyed PATCH, never a full
+// replace: these render on live storefronts.
+
+import fs from "node:fs/promises";
+import path from "node:path";
+import { http } from "../http.js";
+import { fmtSast } from "./audit.js";
+
+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 WIDGET_DIR = path.resolve(process.cwd(), ".flowiq", "widgets");
+export const WIDGET_EMBED_HOST = "https://widget.flowapt.com";
+// The bags a pull writes into the file; a push sends back only what differs.
+const PULL_META = ["id", "organization_id", "created_by", "created_at"];
+
+function fail(prefix, e) { console.error(`${prefix}: ${e.message}`); if (e.body?.error && !e.message.includes(e.body.error)) console.error(`  ${e.body.error}`); process.exit(1); }
+const requireUuid = (v, what) => { if (!UUID_RE.test(v || "")) { console.error(`Error: "${v}" is not a valid ${what} UUID.`); process.exit(1); } };
+
+export function embedSnippet(orgId, widgetId) {
+  return `<!-- FlowIQ Chat Widget -->\n<script\n  src="${WIDGET_EMBED_HOST}/widget/loader.js"\n  data-organization-id="${orgId}"${widgetId ? `\n  data-widget-id="${widgetId}"` : ""}\n></script>`;
+}
+
+export async function list(orgId, opts = {}) {
+  requireUuid(orgId, "organization");
+  let resp;
+  try { resp = await http.get("widgets", { organization_id: orgId }); } catch (e) { fail("List failed", e); }
+  if (opts.json) { console.log(JSON.stringify(resp, null, 2)); return; }
+  if (!resp.count) { console.log(`${resp.organization_name} has no web chat widget.`); return; }
+  console.log(`${resp.organization_name}: ${resp.count} widget(s)`);
+  for (const w of resp.widgets) {
+    console.log(`  ${w.id}  ${w.name ?? "(unnamed)"}${w.is_active ? "  [active: the org-only embed resolves to this one]" : ""}`);
+    console.log(`      agent ${w.agent_name ?? w.agent_id ?? "(org active agent)"}${w.agent_display_name ? ` shown as "${w.agent_display_name}"` : ""} · ${w.widget_position ?? "bottom-right"} · header "${w.header_text ?? ""}"${w.checkout_storefront ? " · checkout storefront" : ""} · created ${fmtSast(w.created_at)}`);
+  }
+  console.log(`\nflowiq widgets pull <widget_id> · widgets embed ${orgId} [<widget_id>]`);
+}
+
+async function fetchWidget(widgetId) {
+  requireUuid(widgetId, "widget");
+  try { return await http.get("widgets", { widget_id: widgetId }); } catch (e) { fail("Widget read failed", e); }
+}
+
+export async function show(widgetId, opts = {}) {
+  const resp = await fetchWidget(widgetId);
+  if (opts.json) { console.log(JSON.stringify(resp, null, 2)); return; }
+  const w = resp.widget;
+  console.log(`${w.name ?? "(unnamed)"}  ${w.id}  on ${resp.organization_name}${w.is_active ? "  [active]" : ""}`);
+  const scalar = Object.entries(w).filter(([k, v]) => !PULL_META.includes(k) && (v === null || typeof v !== "object"));
+  for (const [k, v] of scalar) console.log(`  ${k.padEnd(26)} ${v === null ? "(unset)" : String(v).replace(/\s+/g, " ").slice(0, 140)}`);
+  const bags = Object.entries(w).filter(([k, v]) => v !== null && typeof v === "object");
+  for (const [k, v] of bags) console.log(`  ${k.padEnd(26)} ${JSON.stringify(v).slice(0, 200)}${JSON.stringify(v).length > 200 ? "…" : ""}`);
+  console.log(`\nFull config: flowiq widgets pull ${w.id}`);
+}
+
+export async function pull(widgetId, opts = {}) {
+  const resp = await fetchWidget(widgetId);
+  const w = resp.widget;
+  const slug = String(resp.organization_name || w.organization_id).toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
+  const file = opts.out ? path.resolve(opts.out) : path.join(WIDGET_DIR, `${slug}-${w.id.slice(0, 8)}.json`);
+  await fs.mkdir(path.dirname(file), { recursive: true });
+  await fs.writeFile(file, JSON.stringify({ organization_name: resp.organization_name, widget: w }, null, 2) + "\n", "utf8");
+  console.log(`Wrote ${file}\n  edit the fields under "widget", then: flowiq widgets push ${file} (dry run) → --commit`);
+}
+
+export async function push(file, opts = {}) {
+  let data;
+  try { data = JSON.parse(await fs.readFile(path.resolve(file), "utf8")); } catch (e) { console.error(`Cannot read ${file}: ${e.message}`); process.exit(1); }
+  const w = data.widget || data;
+  requireUuid(w.id, "widget");
+  const patch = {};
+  for (const [k, v] of Object.entries(w)) if (!PULL_META.includes(k)) patch[k] = v;
+  let resp;
+  try { resp = await http.post("widgets", { action: "push", widget_id: w.id, patch, dry_run: !opts.commit }); } catch (e) { fail("Push failed", e); }
+  if (opts.json) { console.log(JSON.stringify(resp, null, 2)); return; }
+  if (resp.unchanged) { console.log("Nothing differs from the live widget."); return; }
+  console.log(`${resp.dry_run ? "Would change" : "Changed"} ${resp.changes.length} field(s) on widget ${resp.widget_id} (${resp.organization_name}):`);
+  for (const c of resp.changes) console.log(`  ${c.field.padEnd(30)} ${JSON.stringify(c.before)?.slice(0, 60) ?? "(unset)"} → ${JSON.stringify(c.after)?.slice(0, 60) ?? "(unset)"}`);
+  if (resp.dry_run) console.log("\nDRY RUN — nothing written. Add --commit to apply (the storefront picks it up on the next widget load).");
+  else console.log("\n✓ live. Nested keys merge; a key set to null was removed.");
+}
+
+export async function embed(orgId, widgetId, opts = {}) {
+  requireUuid(orgId, "organization");
+  if (widgetId) requireUuid(widgetId, "widget");
+  const snippet = embedSnippet(orgId, widgetId || null);
+  if (opts.json) { console.log(JSON.stringify({ organization_id: orgId, widget_id: widgetId || null, snippet })); return; }
+  console.log(snippet);
+  if (!widgetId) console.error("\n(org-only embed: resolves to the org's single widget, else the one marked active; pass the widget id to pin one)");
+}
+
+export async function activate(widgetId, opts = {}) {
+  requireUuid(widgetId, "widget");
+  let resp;
+  try { resp = await http.post("widgets", { action: "activate", widget_id: widgetId }); } catch (e) { fail("Activate failed", e); }
+  if (opts.json) { console.log(JSON.stringify(resp, null, 2)); return; }
+  if (resp.unchanged) { console.log("Already the active widget."); return; }
+  console.log(`✓ ${widgetId} is now the active widget${resp.previously_active?.length ? ` (was: ${resp.previously_active.map((p) => p.name ?? p.id).join(", ")})` : ""}.`);
+}