@flowapt/flowiq-cli 0.9.9 → 0.10.0

package/README.md

@@ -2046,6 +2046,142 @@ channel gets a warning on every run. Point the agent at a fake number with
 CLI creates is born with `allow_broadcast=false` and the `test-contact` tag, so it
 never lands on a broadcast list (stress contacts too).
 
+### Contacts — `flowiq contacts find|show|census|lint|merge|optout|optin|set|export` (0.10.0)
+
+The contact record from the terminal. `find` searches every contact of the org,
+archived and blocked included (the inbox hides archived chats on every tab but
+Archived), and prints the inbox state with each match.
+
+```bash
+flowiq contacts find <org> --email sofia@            # or --phone 3519 / --name "Sofia" / --id <uuid>
+flowiq contacts show <contact_id> --org <org>
+flowiq contacts census <org>                          # archived chats still carrying unread / customer-last messages
+flowiq contacts lint <org>                            # malformed numbers + the repair + whether a twin contact holds it
+flowiq contacts set <org> <contact_id> --whatsapp-id 27821234567 --commit
+flowiq contacts merge <org> <keep_id> <remove_id> --commit       # the app's merge_contacts_v2
+flowiq contacts optout <org> --contact <id> --reason "asked on 30 Sep" --commit
+flowiq contacts optin  <org> --ids-file ids.txt --commit --confirm
+flowiq contacts export <org> [--subscribers] [--out contacts.csv]
+```
+
+- **`find`** prints id, number, email, other channel identities, state
+  (archived / blocked / AI off / opted out / unread), team, assignee, the
+  latest message and any open ticket. Max 100 matches.
+- **`lint`** flags a doubled country code (`351351…`), a trunk 0 kept after the
+  code (`270…`), non-digits and bad lengths, with the suggested repair. When
+  another contact already holds the repaired number it names the twin and
+  prints the `merge` command instead. Test, stress and web-chat identities
+  are counted and skipped.
+- **`set`** changes one contact's WhatsApp number (and `phone_number` when it
+  was the same). Refused when another contact holds the number: merge instead.
+- **`merge`** is dry-run by default and shows both records with message and
+  order counts; `--commit` runs `merge_contacts_v2` (identities released, every
+  child row repointed, the losing contact deactivated, undo in the inbox).
+- **`optout` / `optin`** write `allow_broadcast` and the same inbox marker row
+  the app writes (`contact-opted-out` / `contact-opted-in`). Already-set
+  contacts are skipped so the count is honest. Opting someone back IN needs
+  `--confirm` on top of `--commit`.
+- **`export`** writes `.flowiq/contacts/<org>.csv` (Excel opens it). `--subscribers`
+  = opted in, not archived, not blocked.
+
+### Widgets — `flowiq widgets list|show|pull|push|embed|activate` (0.10.0)
+
+```bash
+flowiq widgets list <org>
+flowiq widgets pull <widget_id>            # → .flowiq/widgets/<org>-<id8>.json
+flowiq widgets push .flowiq/widgets/lego-ddb5ab43.json            # dry run: every field that would change
+flowiq widgets push … --commit
+flowiq widgets embed <org> [widget_id]     # the <script> snippet a client pastes
+flowiq widgets activate <widget_id>        # the widget an org-only embed resolves to
+```
+
+A push is an **id-keyed patch, never a full replace**: scalar columns are set,
+jsonb bags (`home_copy`, `home_design`, `launcher`, `team_avatars`, …) are
+merged at their top level and a key set to `null` is removed. These render on
+live storefronts, so the dry run prints each change before `--commit`. Avatar
+and icon uploads are not here yet (file upload with circle compositing).
+
+### Tickets — `flowiq tickets list|show|status` (0.10.0)
+
+```bash
+flowiq tickets list <org>                                  # open + in_progress, newest first
+flowiq tickets list <org> --older-than 48h --status open   # stale escalations
+flowiq tickets list <org> --contact <contact_id> --status all
+flowiq tickets show <ticket_id>
+flowiq tickets status <ticket_id> --set resolved --note "…" --commit
+```
+
+`status` writes what the app writes (`resolved_by/at`, `last_updated_*`, reopen
+fields, a `status_history` entry) and, when the org runs
+`reenable_bot_on_ticket_resolve`, switches the contact's AI back on with the
+inbox's three guards (open → closed transition, latest ticket only, bot not
+already on). Dry run by default.
+
+### Flows — `flowiq flows list|show|status|enable|disable` (0.10.0)
+
+```bash
+flowiq flows list <org>                       # trigger, templates, stats, param-key lint per flow
+flowiq flows show <flow_id>                   # full configuration
+flowiq flows status <org> --since 14d [--failed] [--flow <id>]   # execution funnel + verbatim error rollup
+flowiq flows enable <flow_id> --confirm       # arms real sends
+flowiq flows disable <flow_id>
+```
+
+The lint flags a `send_message` step whose `body_parameters` keys are not
+`param1..N` (`b1..b4`, `1,b1`, …): `bc send` refuses those shapes, the flow
+engine hands them to Meta where jsonb key order decides the slots.
+
+### Rules — `flowiq rules list|show|results|enable|disable` (0.10.0)
+
+The Automations rules engine (Shoppers → Rules, `custom_notification_rules`):
+the delayed-send engine behind tag-based, order-stage, webhook and
+Instagram-comment sends.
+
+```bash
+flowiq rules list <org> [--trigger tag_added]
+flowiq rules show <rule_id>
+flowiq rules results <rule_id> --since 30d    # what it queued: status counts, errors, recent sends
+flowiq rules enable <rule_id> --confirm
+flowiq rules disable <rule_id>
+```
+
+### Org views — `flowiq org channels|whatsapp|health|automations|abandoned` (0.10.0)
+
+```bash
+flowiq org channels <org>          # WhatsApp (provider, master switch), Messenger, Instagram, TikTok, email, Meta Ads, Zernio
+flowiq org channels --all          # census across every active org
+flowiq org whatsapp <org>          # the number's health straight from Meta: status, quality, tier, name status, webhook subscription
+flowiq org whatsapp --all          # every Meta org, unhealthy first
+flowiq org health <org>            # is the agent ready? master switch, keys (OpenAI probed), agent, catalogue + embeddings, store webhooks + order sync, traffic
+flowiq org automations <org>       # automated order messages, each type checked against the org's templates
+flowiq org automations <org> --enable order_shipped --commit     # or --disable; no type = the whole feature
+flowiq org abandoned <org>         # abandoned-cart recovery per sequence + the last 30 days of sends
+flowiq org abandoned <org> --disable 2 --commit
+```
+
+`health` probes the org's OpenAI key with a one-token embedding, so an
+exhausted or invalid key shows as such rather than "present".
+
+### Messages, org-wide — `flowiq messages search|failures|stats` (0.10.0)
+
+```bash
+flowiq messages search <org> "flash sale" --since 24h [--sender-type bot-whatsapp] [--include-templates]
+flowiq messages failures <org> --since 7d
+flowiq messages stats <org> --since 6m
+```
+
+- **`search`** answers "did the agent say X to anyone today?" without knowing
+  the contact: time · sender · contact · the match in context. Template and
+  broadcast payloads are excluded unless `--include-templates`.
+- **`failures`** rolls up Meta-failed sends by error code, media type and
+  contact, and lists the sends Meta accepted (wamid) but never confirmed.
+  `messages pull` now ends with the same delivery footer.
+- **`stats`** is the monthly volume: inbound, outbound, free-form (sent inside
+  a customer's 24 h window, Meta's in-window charge from 1 Oct 2026) vs
+  template, bot vs human. The classifier lives in ONE RPC
+  (`cli_message_volume_summary`): template = broadcast_id, JSON payload, or no
+  customer message in the preceding 24 h.
+
 ### Guide — `flowiq guide`
 
 Read the bundled docs in the terminal — no digging through node_modules.

package/TEAM-GUIDE.md

@@ -134,6 +134,19 @@ When you see it, run `npm i -g @flowapt/flowiq-cli` — a stale version also mea
 | Which changelog rows has nobody emailed the team about yet? | `flowiq updates status` / `flowiq updates uncovered` — anything left 20h+ goes out automatically at 08:30 SAST as a plain digest |
 | Set which contact `flowiq test` uses (use a FAKE number!) | `flowiq agent config <org_id> --test-contact-number 27000000001 --test-contact-name "QA Bot"` |
 | **The CLI can't do something I need** (or does it wrong, or should do more) | `flowiq gaps report "<command> cannot <thing>" --command "<command>" --error "<exact error>" --workaround "<what you did instead>"`. If it is already on the list you are told its number: `flowiq gaps hit <number> --note "…"` |
+| Find a customer the inbox cannot show (archived, blocked, wrong tab) | `flowiq contacts find <org_id> --email <part>` (or `--phone`, `--name`): every match with its state, team, latest message and open ticket |
+| A customer's number is wrong (country code doubled, leading 0 kept) | `flowiq contacts lint <org_id>` finds them with the repair; `flowiq contacts set <org_id> <contact_id> --whatsapp-id <number> --commit` fixes one; if a twin contact holds the number, `flowiq contacts merge <org_id> <keep> <remove> --commit` |
+| Opt a customer out of broadcasts (or back in) | `flowiq contacts optout <org_id> --contact <id> --reason "…" --commit` · back in: `flowiq contacts optin … --commit --confirm` |
+| Export the contact list for a client | `flowiq contacts export <org_id> --subscribers` → a CSV Excel opens |
+| Change a web chat widget's copy / colours, or get the embed code | `flowiq widgets pull <widget_id>` → edit → `flowiq widgets push <file>` (dry run) → `--commit` · `flowiq widgets embed <org_id>` |
+| Which escalations are still open, and close one | `flowiq tickets list <org_id> --older-than 48h` · `flowiq tickets status <ticket_id> --set resolved --note "…" --commit` |
+| Did the agent say something wrong to anyone today? | `flowiq messages search <org_id> "the words" --since 24h` |
+| Why did messages not arrive / what failed to send? | `flowiq messages failures <org_id> --since 7d` (Meta error codes by reason, media and contact, plus sends Meta accepted and never confirmed) |
+| How many messages did an org send last month, free-form vs template? | `flowiq messages stats <org_id> --since 6m` |
+| Is a client's WhatsApp number healthy / connected / rate-limited? | `flowiq org whatsapp <org_id>` (straight from Meta); every org: `flowiq org whatsapp --all` |
+| Which channels are connected (Messenger, Instagram, email…)? | `flowiq org channels <org_id>`; every org: `flowiq org channels --all` |
+| Is this client's agent ready to switch on? | `flowiq org health <org_id>` (master switch, keys probed, prompt, catalogue, webhooks, order sync, traffic) |
+| What automated messages / flows / rules does an org have armed? | `flowiq org automations <org_id>` · `flowiq flows list <org_id>` (+ `flows status` for failures) · `flowiq rules list <org_id>` (+ `rules results <rule_id>`) · `flowiq org abandoned <org_id>` |
 | See what the team has asked the CLI to do | `flowiq gaps list` (open, most-hit first) · `flowiq gaps list --mine` · `flowiq gaps show <number>` · in the app: Changelog → **CLI requests** |
 | Close a request (Matt / Gidon) | `flowiq gaps status <number> --to done --fixed-in 0.9.8 --note "what shipped"` — emails everyone who reported or hit it |
 > **Publishing the CLI (maintainers only):** publish from a clean clone, never

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flowapt/flowiq-cli",
-  "version": "0.9.9",
+  "version": "0.10.0",
   "description": "Command-line tool for FlowIQ staff: round-trip agent prompts, questionnaires, fine-tuning, pin-board tasks, webhooks, templates, agent-updates, chat exports, and live agent testing without ever touching service-role credentials.",
   "type": "module",
   "bin": {

package/src/batch-cde.test.mjs

@@ -0,0 +1,73 @@
+// node --test src/batch-cde.test.mjs — pure helpers behind the 0.10.0 topics.
+import test from "node:test";
+import assert from "node:assert/strict";
+import { toCsv } from "./commands/contacts.js";
+import { embedSnippet } from "./commands/widgets.js";
+import { snippetAround } from "./commands/messages.js";
+// The server modules build a Supabase client at import time; dummies keep the
+// pure helpers testable without a key on the machine.
+process.env.VITE_SUPABASE_URL ||= "https://example.supabase.co";
+process.env.SUPABASE_SERVICE_ROLE ||= "test-key";
+const { lintNumber } = await import("../../api/cli/contacts.js");
+const { buildUpdate } = await import("../../api/cli/widgets.js");
+const { lintParams, summariseFlow } = await import("../../api/cli/flows.js");
+const { describeSendAt } = await import("../../api/cli/rules.js");
+
+test("lintNumber catches the doubled country code and the kept trunk 0", () => {
+  assert.deepEqual(lintNumber("351351912345678"), { problem: "country code 351 doubled", suggested: "351912345678" });
+  assert.deepEqual(lintNumber("270821234567"), { problem: "trunk 0 kept after +27", suggested: "27821234567" });
+  assert.equal(lintNumber("27821234567"), null);
+  assert.equal(lintNumber("351912345678"), null);
+  assert.equal(lintNumber("447700900123"), null);
+  assert.equal(lintNumber("12125551234"), null);
+  assert.match(lintNumber("+27 82 123 4567").problem, /non-digit/);
+});
+
+test("toCsv quotes commas, quotes and newlines; arrays join with |", () => {
+  const csv = toCsv([{ a: 'He said "hi", ok', b: ["x", "y"], c: null }], ["a", "b", "c"]);
+  assert.equal(csv, 'a,b,c\n"He said ""hi"", ok",x|y,\n');
+});
+
+test("embedSnippet matches the app's snippet shape", () => {
+  const s = embedSnippet("org-1", "w-1");
+  assert.match(s, /widget\/loader\.js/);
+  assert.match(s, /data-organization-id="org-1"/);
+  assert.match(s, /data-widget-id="w-1"/);
+  assert.doesNotMatch(embedSnippet("org-1", null), /data-widget-id/);
+});
+
+test("snippetAround centres the match", () => {
+  const s = snippetAround("a".repeat(200) + " flash sale " + "b".repeat(200), "flash sale", 60);
+  assert.match(s, /^…a+ flash sale b+…$/);
+});
+
+test("buildUpdate patches scalars, merges jsonb bags and removes null keys", () => {
+  const cur = { name: "A", home_copy: { greeting: "Hi", tagline: "x" }, launcher: null };
+  const { update, changes, errors } = buildUpdate(cur, { name: "B", home_copy: { tagline: null, intro: "yo" }, launcher: { size: "lg" }, organization_id: "nope" });
+  assert.deepEqual(errors.map((e) => e.split(" ")[0]), ["organization_id"]);
+  assert.equal(update.name, "B");
+  assert.deepEqual(update.home_copy, { greeting: "Hi", intro: "yo" });
+  assert.deepEqual(update.launcher, { size: "lg" });
+  assert.deepEqual(changes.map((c) => c.field), ["name", "home_copy.tagline", "home_copy.intro", "launcher.size"]);
+  assert.deepEqual(buildUpdate(cur, { name: "A" }).changes, []);
+});
+
+test("lintParams accepts param1..N and flags anything else", () => {
+  assert.equal(lintParams({ param1: "a", param2: "b" }), null);
+  assert.match(lintParams({ b1: "a", b2: "b" }), /jsonb order/);
+  assert.match(lintParams({ param1: "a", param3: "b" }), /skip a slot/);
+  assert.equal(lintParams({}), null);
+});
+
+test("summariseFlow reads the trigger and the template steps", () => {
+  const f = summariseFlow({ id: "f", name: "n", enabled: true, configuration: { trigger: { type: "event", event: "subscription.renewed", source: "stitch" }, steps: [{ type: "action", action_type: "send_message", config: { template_name: "t_v1", body_parameters: { param1: "x" } } }] } });
+  assert.equal(f.trigger.event, "subscription.renewed");
+  assert.equal(f.steps[0].template_name, "t_v1");
+  assert.deepEqual(f.warnings, []);
+});
+
+test("describeSendAt reads delay, time, quiet hours", () => {
+  assert.equal(describeSendAt({ delay_minutes: 720, quiet_hours: { tz: "Europe/Madrid", start_hour: 10, end_hour: 20 } }), "+720min · quiet 10-20 Europe/Madrid");
+  assert.equal(describeSendAt({ delay_days: 3, send_at_time: "10:00", skip_weekends: true }), "+3d · at 10:00 · skip weekends");
+  assert.equal(describeSendAt(null), "immediately");
+});

package/src/commands/contacts.js

@@ -0,0 +1,173 @@
+// `flowiq contacts find|show|census|lint|merge|optout|optin|set|export` — the
+// contact record from the terminal (server: api/cli/contacts.js).
+
+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;
+
+function requireOrg(orgId) {
+  if (!UUID_RE.test(orgId || "")) { console.error(`Error: "${orgId}" is not a valid organization UUID.`); process.exit(1); }
+}
+function fail(prefix, e) {
+  console.error(`${prefix}: ${e.message}`);
+  if (e.body?.error && !e.message.includes(e.body.error)) console.error(`  ${e.body.error}`);
+  if (e.body?.needs_confirm) console.error("  Re-run with --confirm.");
+  process.exit(1);
+}
+const pad = (s, n) => String(s ?? "").padEnd(n);
+const flags = (c) => [c.archived && "archived", c.blocked && "blocked", c.bot_status === false && "AI off", c.allow_broadcast === false && "opted out", c.has_unread_messages && "unread"].filter(Boolean).join(", ");
+
+function printContact(c) {
+  console.log(`${c.full_name || "(no name)"}  ${c.id}`);
+  console.log(`  whatsapp:   ${c.whatsapp_id ?? "—"}${c.phone_number && c.phone_number !== c.whatsapp_id ? `  (phone ${c.phone_number})` : ""}`);
+  if (c.email) console.log(`  email:      ${c.email}`);
+  if (c.instagram_username || c.messenger_psid || c.tiktok_username) console.log(`  channels:   ${[c.instagram_username && `instagram @${c.instagram_username}`, c.messenger_psid && "messenger", c.tiktok_username && `tiktok @${c.tiktok_username}`].filter(Boolean).join(", ")}`);
+  console.log(`  state:      ${flags(c) || "active"}${c.team ? ` · team ${c.team}` : ""}${c.assignee_email ? ` · assigned to ${c.assignee_email}` : ""}`);
+  if (c.latest_message) console.log(`  latest:     ${fmtSast(c.latest_message.created_at)} SAST · ${c.latest_message.sender_type} · ${c.latest_message.snippet.replace(/\s+/g, " ")}`);
+  if (c.open_ticket) console.log(`  ticket:     ${c.open_ticket.status} since ${fmtSast(c.open_ticket.created_at)} · ${c.open_ticket.summary ?? ""} (${c.open_ticket.id})`);
+  if (c.orders_count) console.log(`  orders:     ${c.orders_count}${c.total_spent ? ` · spent ${c.total_spent}` : ""}${c.last_order_date ? ` · last ${c.last_order_date}` : ""}`);
+  if (Array.isArray(c.tags) && c.tags.length) console.log(`  tags:       ${c.tags.slice(0, 12).join(", ")}${c.tags.length > 12 ? ` +${c.tags.length - 12}` : ""}`);
+  console.log(`  created:    ${fmtSast(c.created_at)} SAST`);
+}
+
+export async function find(orgId, opts = {}) {
+  requireOrg(orgId);
+  if (!opts.email && !opts.phone && !opts.name && !opts.id) { console.error("Error: pass --email, --phone, --name or --id."); process.exit(1); }
+  let resp;
+  try { resp = await http.get("contacts", { organization_id: orgId, find: "1", email: opts.email, phone: opts.phone, name: opts.name, contact_id: opts.id, limit: opts.limit }); }
+  catch (e) { fail("Lookup failed", e); }
+  if (opts.json) { console.log(JSON.stringify(resp, null, 2)); return; }
+  if (!resp.contacts.length) { console.log(`No contact on ${resp.organization_name} matches (archived and blocked contacts were included in the search).`); return; }
+  console.log(`${resp.count} contact(s) on ${resp.organization_name}${resp.count === resp.limit ? ` (limit ${resp.limit}, narrow the search or --limit)` : ""}:\n`);
+  for (const c of resp.contacts) { printContact(c); console.log(""); }
+}
+
+export async function show(contactId, opts = {}) {
+  if (!UUID_RE.test(contactId || "")) { console.error(`Error: "${contactId}" is not a valid contact UUID.`); process.exit(1); }
+  if (!UUID_RE.test(opts.org || "")) { console.error("Error: --org <organization_id> is required (a contact id alone is not scoped)."); process.exit(1); }
+  return find(opts.org, { id: contactId, json: opts.json });
+}
+
+export async function census(orgId, opts = {}) {
+  requireOrg(orgId);
+  let resp;
+  try { resp = await http.get("contacts", { organization_id: orgId, archived_census: "1" }); } catch (e) { fail("Census failed", e); }
+  if (opts.json) { console.log(JSON.stringify(resp, null, 2)); return; }
+  console.log(`${resp.organization_name}: ${resp.archived} archived chat(s)`);
+  console.log(`  with unread messages:        ${resp.archived_with_unread}`);
+  console.log(`  customer wrote last:         ${resp.archived_customer_wrote_last} (of ${resp.customer_last_sampled} checked)`);
+  console.log("Archiving is manual and writes no log; the inbox hides these on every tab but Archived.");
+}
+
+export async function lint(orgId, opts = {}) {
+  requireOrg(orgId);
+  let resp;
+  try { resp = await http.get("contacts", { organization_id: orgId, lint: "1" }); } catch (e) { fail("Lint failed", e); }
+  if (opts.json) { console.log(JSON.stringify(resp, null, 2)); return; }
+  console.log(`${resp.organization_name}: ${resp.scanned} numbers scanned, ${resp.count} malformed${resp.synthetic_skipped ? ` (${resp.synthetic_skipped} test / stress / web-chat identities skipped)` : ""}`);
+  if (!resp.count) return;
+  console.log("");
+  console.log(`  ${pad("NUMBER", 18)} ${pad("PROBLEM", 30)} ${pad("SUGGESTED", 16)} ${pad("TWIN", 8)} CONTACT`);
+  for (const f of resp.findings) {
+    console.log(`  ${pad(f.whatsapp_id, 18)} ${pad(f.problem, 30)} ${pad(f.suggested ?? "—", 16)} ${pad(f.twin ? "yes" : "no", 8)} ${f.full_name ?? ""}${f.archived ? " (archived)" : ""}  ${f.id}`);
+    if (f.twin) console.log(`  ${" ".repeat(18)} twin ${f.twin.full_name ?? "(no name)"} ${f.twin.id}${f.twin.latest_message_at ? `, last message ${fmtSast(f.twin.latest_message_at)}` : ""} → flowiq contacts merge ${orgId} ${f.twin.id} ${f.id} --commit`);
+  }
+  console.log("");
+  console.log(`Repair a number with no twin: flowiq contacts set ${orgId} <contact_id> --whatsapp-id <suggested> --commit`);
+}
+
+export async function merge(orgId, keepId, removeId, opts = {}) {
+  requireOrg(orgId);
+  let resp;
+  try { resp = await http.post("contacts", { action: "merge", organization_id: orgId, keep_id: keepId, remove_id: removeId, dry_run: !opts.commit }); }
+  catch (e) { fail("Merge failed", e); }
+  if (opts.json) { console.log(JSON.stringify(resp, null, 2)); return; }
+  const line = (c) => `${c.full_name || "(no name)"} · ${c.whatsapp_id ?? "no whatsapp"}${c.email ? ` · ${c.email}` : ""}${c.instagram_username ? ` · @${c.instagram_username}` : ""} · ${c.messages} message(s) · ${c.orders_count ?? 0} order(s)`;
+  if (resp.dry_run) {
+    console.log(`KEEP    ${keepId}\n        ${line(resp.keep)}`);
+    console.log(`REMOVE  ${removeId}\n        ${line(resp.remove)}`);
+    for (const w of resp.warnings || []) console.log(`  ⚠ ${w}`);
+    console.log("\nDRY RUN — nothing changed. Add --commit to merge (the removed contact's messages, tickets and orders move to the kept one; the app's merge_contacts_v2 does the work).");
+    return;
+  }
+  console.log(`✓ merged ${resp.removed.full_name || removeId} into ${resp.keep?.full_name || keepId} on ${resp.organization_name}: ${resp.keep?.messages ?? "?"} message(s) now on the kept contact`);
+  for (const w of resp.warnings || []) console.log(`  ⚠ ${w}`);
+  if (resp.rpc?.merge_id) console.log(`  merge id ${resp.rpc.merge_id} (undo in the inbox: contact history → Undo merge)`);
+}
+
+async function readIds(opts) {
+  const ids = [...(opts.contact || [])];
+  if (opts.idsFile) {
+    const text = await fs.readFile(path.resolve(opts.idsFile), "utf8");
+    ids.push(...text.split(/[\s,]+/).map((s) => s.trim()).filter(Boolean));
+  }
+  const bad = ids.filter((id) => !UUID_RE.test(id));
+  if (bad.length) { console.error(`Error: not contact UUIDs: ${bad.slice(0, 5).join(", ")}`); process.exit(1); }
+  if (!ids.length) { console.error("Error: pass --contact <id> (repeatable) or --ids-file <file>."); process.exit(1); }
+  return [...new Set(ids)];
+}
+
+async function optFlag(orgId, opts, action) {
+  requireOrg(orgId);
+  const ids = await readIds(opts);
+  let resp;
+  try { resp = await http.post("contacts", { action, organization_id: orgId, contact_ids: ids, reason: opts.reason, dry_run: !opts.commit, confirm: !!opts.confirm }); }
+  catch (e) { fail(`${action === "optout" ? "Opt-out" : "Opt-in"} failed`, e); }
+  if (opts.json) { console.log(JSON.stringify(resp, null, 2)); return; }
+  console.log(`${resp.organization_name}: ${resp.requested} requested · ${resp.will_change} to change · ${resp.already} already ${action === "optout" ? "opted out" : "opted in"}${resp.missing?.length ? ` · ${resp.missing.length} not found in this org` : ""}`);
+  for (const c of resp.contacts.slice(0, 30)) console.log(`  ${pad(c.whatsapp_id ?? "—", 16)} ${c.full_name ?? ""}  ${c.id}`);
+  if (resp.contacts.length > 30) console.log(`  … ${resp.contacts.length - 30} more`);
+  if (resp.dry_run) { console.log(`\nDRY RUN — nothing changed. Add --commit${action === "optin" ? " --confirm" : ""} to write allow_broadcast=${action === "optin"} and the inbox marker.`); return; }
+  console.log(`\n✓ ${resp.changed} contact(s) ${action === "optout" ? "opted out of" : "opted back in to"} broadcasts.`);
+}
+export const optout = (orgId, opts) => optFlag(orgId, opts, "optout");
+export const optin = (orgId, opts) => optFlag(orgId, opts, "optin");
+
+export async function set(orgId, contactId, opts = {}) {
+  requireOrg(orgId);
+  if (!opts.whatsappId) { console.error("Error: --whatsapp-id <digits> is the only field set here today."); process.exit(1); }
+  let resp;
+  try { resp = await http.post("contacts", { action: "set", organization_id: orgId, contact_id: contactId, whatsapp_id: opts.whatsappId, dry_run: !opts.commit }); }
+  catch (e) { fail("Set failed", e); }
+  if (opts.json) { console.log(JSON.stringify(resp, null, 2)); return; }
+  if (resp.unchanged) { console.log("Already that number; nothing to do."); return; }
+  if (resp.dry_run) { console.log(`${resp.contact.full_name || contactId}: ${resp.contact.whatsapp_id} → ${resp.would_set.whatsapp_id}${resp.would_set.phone_number ? " (phone_number too)" : ""}\nDRY RUN — add --commit to write.`); return; }
+  console.log(`✓ ${resp.contact.full_name || contactId} is now ${resp.contact.whatsapp_id} on ${resp.organization_name}.`);
+}
+
+function csvCell(v) {
+  if (v == null) return "";
+  const s = Array.isArray(v) ? v.join("|") : typeof v === "object" ? JSON.stringify(v) : String(v);
+  return /[",\n\r]/.test(s) ? `"${s.replace(/"/g, '""')}"` : s;
+}
+export function toCsv(rows, columns) {
+  const lines = [columns.join(",")];
+  for (const r of rows) lines.push(columns.map((c) => csvCell(r[c])).join(","));
+  return lines.join("\n") + "\n";
+}
+
+export async function exportContacts(orgId, opts = {}) {
+  requireOrg(orgId);
+  const rows = [];
+  let cursor = null, orgName = null;
+  for (;;) {
+    let resp;
+    try { resp = await http.get("contacts", { organization_id: orgId, export: "1", subscribers: opts.subscribers ? "1" : undefined, cursor_id: cursor ?? undefined }); }
+    catch (e) { fail("Export failed", e); }
+    orgName ||= resp.organization_name;
+    rows.push(...resp.page);
+    process.stderr.write(`\r  ${rows.length} contacts…`);
+    if (resp.done || !resp.next_cursor) break;
+    cursor = resp.next_cursor;
+  }
+  process.stderr.write("\n");
+  const columns = ["id", "full_name", "whatsapp_id", "phone_number", "email", "allow_broadcast", "archived", "blocked", "bot_status", "tags", "orders_count", "total_spent", "last_order_date", "latest_message_at", "created_at", "attributes"];
+  const slug = String(orgName || orgId).toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
+  const out = opts.out ? path.resolve(opts.out) : path.resolve(process.cwd(), ".flowiq", "contacts", `${slug}${opts.subscribers ? "-subscribers" : ""}.${opts.json ? "json" : "csv"}`);
+  await fs.mkdir(path.dirname(out), { recursive: true });
+  await fs.writeFile(out, opts.json ? JSON.stringify(rows, null, 2) + "\n" : toCsv(rows, columns), "utf8");
+  console.log(`Wrote ${out} (${rows.length} contact(s)${opts.subscribers ? ", subscribers only: opted in, not archived, not blocked" : ""}). Excel opens the CSV directly.`);
+}

package/src/commands/flows.js

@@ -0,0 +1,82 @@
+// `flowiq flows list|show|status|enable|disable` — the Flows automation engine
+// (server: api/cli/flows.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}`); if (e.body?.needs_confirm) console.error("  Re-run with --confirm."); process.exit(1); }
+const requireOrg = (v) => { if (!UUID_RE.test(v || "")) { console.error(`Error: "${v}" is not a valid organization UUID.`); process.exit(1); } };
+
+const triggerLabel = (t) => [t.event ?? t.type, t.source && `(${t.source})`, t.tag && `tag ${t.tag}`].filter(Boolean).join(" ");
+
+export async function list(orgId, opts = {}) {
+  requireOrg(orgId);
+  let resp;
+  try { resp = await http.get("flows", { 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 flows.`); return; }
+  console.log(`${resp.organization_name}: ${resp.count} flow(s), ${resp.enabled} enabled`);
+  console.log("");
+  for (const f of resp.flows) {
+    const templates = f.steps.map((s) => s.template_name).filter(Boolean);
+    console.log(`  ${f.enabled ? "ON " : "off"} ${pad(f.name, 40)} ${pad(triggerLabel(f.trigger), 34)} ${templates.join(" → ") || "(no template step)"}`);
+    console.log(`      ${f.id}${f.stats ? ` · triggered ${f.stats.total_triggered ?? 0} · sent ${f.stats.total_sent ?? 0} · failed ${f.stats.total_failed ?? 0}${f.stats.last_triggered_at ? ` · last ${fmtSast(f.stats.last_triggered_at)}` : ""}` : ""}`);
+    for (const w of f.warnings || []) console.log(`      ⚠ ${w}`);
+  }
+  console.log(`\nflowiq flows status ${orgId} --since 14d · flows show <flow_id>`);
+}
+
+export async function show(flowId, opts = {}) {
+  if (!UUID_RE.test(flowId || "")) { console.error(`Error: "${flowId}" is not a valid flow UUID.`); process.exit(1); }
+  let resp;
+  try { resp = await http.get("flows", { flow_id: flowId }); } catch (e) { fail("Read failed", e); }
+  if (opts.json) { console.log(JSON.stringify(resp, null, 2)); return; }
+  const f = resp.flow;
+  console.log(`${f.name}  ${f.id}  on ${resp.organization_name}: ${f.enabled ? "ENABLED" : "disabled"}`);
+  if (f.description) console.log(`  ${f.description}`);
+  console.log(`  trigger:   ${triggerLabel(f.trigger)}${f.trigger.conditions ? ` · ${f.trigger.conditions} condition(s)` : ""}`);
+  for (const s of f.steps) {
+    console.log(`  step ${s.index}:    ${s.action_type ?? s.type}${s.template_name ? ` ${s.template_name}` : ""}${s.delay ? ` · delay ${s.delay}` : ""}${s.body_param_keys.length ? ` · body ${s.body_param_keys.join(",")}` : ""}${s.button_param_keys.length ? ` · button ${s.button_param_keys.join(",")}` : ""}`);
+    if (s.lint) console.log(`             ⚠ ${s.lint}`);
+  }
+  if (f.stats) console.log(`  stats:     ${JSON.stringify(f.stats)}`);
+  console.log(`  updated:   ${fmtSast(f.updated_at)} SAST`);
+  console.log("\n  configuration:");
+  console.log(JSON.stringify(f.configuration, null, 2).split("\n").map((l) => "    " + l).join("\n"));
+}
+
+export async function status(orgId, opts = {}) {
+  requireOrg(orgId);
+  let resp;
+  try { resp = await http.get("flows", { organization_id: orgId, status: "1", since: opts.since, flow_id: opts.flow, failed: opts.failed ? "1" : undefined }); }
+  catch (e) { fail("Status failed", e); }
+  if (opts.json) { console.log(JSON.stringify(resp, null, 2)); return; }
+  console.log(`${resp.organization_name}: ${resp.rows} execution(s) since ${fmtSast(resp.since)} SAST${resp.capped ? " (capped at 5,000)" : ""}`);
+  console.log(`  by status: ${Object.entries(resp.by_status).map(([k, v]) => `${k} ${v}`).join(" · ") || "none"}`);
+  if (resp.by_flow.length) {
+    console.log("");
+    console.log(`  ${pad("FLOW", 40)} ${pad("TOTAL", 7)} ${pad("DONE", 7)} ${pad("PENDING", 8)} ${pad("CANCEL", 7)} FAILED`);
+    for (const f of resp.by_flow) console.log(`  ${pad(f.name ?? f.flow_id, 40)} ${pad(f.total, 7)} ${pad(f.completed ?? 0, 7)} ${pad(f.pending ?? 0, 8)} ${pad(f.cancelled ?? 0, 7)} ${f.failed ?? 0}`);
+  }
+  if (resp.error_rollup.length) {
+    console.log("\n  failures by message:");
+    for (const e of resp.error_rollup) console.log(`    ${String(e.n).padStart(5)} × ${e.message}`);
+  }
+  if (resp.failed) {
+    console.log(`\n  failed executions (${resp.failed.length} shown):`);
+    for (const r of resp.failed) console.log(`    ${fmtSast(r.triggered_at ?? r.created_at)} ${pad(r.flow_name ?? "", 30)} contact ${r.contact_id}  ${String(r.error_message ?? "").slice(0, 100)}`);
+  }
+}
+
+async function toggle(flowId, opts, action) {
+  if (!UUID_RE.test(flowId || "")) { console.error(`Error: "${flowId}" is not a valid flow UUID.`); process.exit(1); }
+  let resp;
+  try { resp = await http.post("flows", { action, flow_id: flowId, confirm: !!opts.confirm }); } catch (e) { fail(`${action} failed`, e); }
+  if (opts.json) { console.log(JSON.stringify(resp, null, 2)); return; }
+  if (resp.unchanged) { console.log(`Flow is already ${resp.enabled ? "enabled" : "disabled"}.`); return; }
+  console.log(`✓ "${resp.name}" ${resp.enabled ? "ENABLED" : "disabled"} (was ${resp.was ? "enabled" : "disabled"}).`);
+}
+export const enable = (id, opts) => toggle(id, opts, "enable");
+export const disable = (id, opts) => toggle(id, opts, "disable");

package/src/commands/messages.js

@@ -4,6 +4,7 @@
 import fs from "node:fs/promises";
 import path from "node:path";
 import { http } from "../http.js";
+import { fmtSast } from "./audit.js";
 
 const MSG_DIR = path.resolve(process.cwd(), ".flowiq", "messages");
 const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
@@ -66,4 +67,70 @@ export async function pull(contactId, opts = {}) {
   for (const [k, v] of Object.entries(resp.sender_breakdown).sort()) {
     console.log(`    ${k.padEnd(16)} ${v}`);
   }
+  // Delivery footer: a wamid with no receipt and no status is a message Meta
+  // accepted and dropped; it looks identical to a delivered one in the JSON.
+  const rows = Array.isArray(resp.messages) ? resp.messages : Array.isArray(resp.rows) ? resp.rows : [];
+  const out = rows.filter((m) => ["bot-whatsapp", "human-whatsapp"].includes(m.sender_type));
+  if (out.length) {
+    const delivered = out.filter((m) => m.delivered_receipt_received === true || m.read_receipt_received === true).length;
+    const failed = out.filter((m) => m.message_status === "failed").length;
+    const noStatus = out.filter((m) => m.whatsapp_message_id && m.message_status == null && !m.sent_receipt_received && !m.delivered_receipt_received && !m.read_receipt_received).length;
+    console.log(`  delivery:       ${out.length} outbound WhatsApp · ${delivered} delivered/read · ${failed} failed · ${noStatus} with NO status at all${noStatus ? "  ⚠ accepted by Meta, never confirmed (flowiq messages failures <org>)" : ""}`);
+  }
+}
+
+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 requireOrg = (v) => { if (!UUID_RE.test(v || "")) { console.error(`Error: "${v}" is not a valid organization UUID.`); process.exit(1); } };
+const pad = (s, n) => String(s ?? "").padEnd(n);
+
+// Show the match in context, not the whole message.
+export function snippetAround(text, needle, width = 90) {
+  const t = String(text ?? "").replace(/\s+/g, " ");
+  const i = t.toLowerCase().indexOf(String(needle).toLowerCase());
+  if (i < 0) return t.slice(0, width);
+  const start = Math.max(0, i - Math.floor(width / 3));
+  const s = t.slice(start, start + width);
+  return `${start > 0 ? "…" : ""}${s}${start + width < t.length ? "…" : ""}`;
+}
+
+export async function search(orgId, textParts, opts = {}) {
+  requireOrg(orgId);
+  const text = (Array.isArray(textParts) ? textParts.join(" ") : String(textParts ?? "")).trim();
+  if (text.length < 2) { console.error("Error: give at least 2 characters to search for."); process.exit(1); }
+  let resp;
+  try { resp = await http.get("messages", { organization_id: orgId, search: text, since: opts.since, until: opts.until, sender_type: opts.senderType, include_templates: opts.includeTemplates ? "1" : undefined, limit: opts.limit }); }
+  catch (e) { fail("Search failed", e); }
+  if (opts.json) { console.log(JSON.stringify(resp, null, 2)); return; }
+  console.log(`${resp.organization_name}: ${resp.count} message(s) containing "${text}" since ${fmtSast(resp.since)} SAST${resp.capped ? ` (capped at ${resp.limit}; narrow with --since / --sender-type)` : ""}${opts.includeTemplates ? "" : " (template sends excluded; --include-templates)"}`);
+  for (const r of resp.rows) {
+    console.log(`  ${pad(fmtSast(r.created_at), 17)} ${pad(r.sender_type, 16)} ${pad((r.contact?.full_name || r.contact?.whatsapp_id || r.contact_id || "").slice(0, 22), 22)} ${snippetAround(r.message, text)}`);
+  }
+  if (resp.rows.length) console.log(`\n  contact ids: flowiq messages search … --json | jq '.rows[].contact_id'  ·  full chat: flowiq messages pull <contact_id>`);
+}
+
+export async function failures(orgId, opts = {}) {
+  requireOrg(orgId);
+  let resp;
+  try { resp = await http.get("messages", { organization_id: orgId, failures: "1", since: opts.since }); } catch (e) { fail("Failures read failed", e); }
+  if (opts.json) { console.log(JSON.stringify(resp, null, 2)); return; }
+  const f = resp.failed, v = resp.vanished;
+  console.log(`${resp.organization_name}: ${f.total} failed send(s) since ${fmtSast(resp.since)} SAST${f.capped ? " (capped)" : ""}`);
+  if (f.by_reason.length) { console.log("  by reason:"); for (const r of f.by_reason) console.log(`    ${String(r.n).padStart(6)} × ${r.key}`); }
+  if (f.by_media.length > 1 || (f.by_media[0] && f.by_media[0].key !== "text")) { console.log("  by media:"); for (const r of f.by_media) console.log(`    ${String(r.n).padStart(6)} × ${r.key}`); }
+  if (f.by_contact.length) { console.log("  top contacts:"); for (const c of f.by_contact.slice(0, 10)) console.log(`    ${String(c.n).padStart(6)} × ${c.contact?.full_name ?? ""} ${c.contact?.whatsapp_id ?? ""} (${c.contact_id})`); }
+  console.log(`\n${v.total} message(s) accepted by Meta but never confirmed (wamid, no receipt, no status, older than 15 min)${v.capped ? " (capped)" : ""}`);
+  if (v.by_media.length) for (const r of v.by_media) console.log(`    ${String(r.n).padStart(6)} × ${r.key}`);
+  for (const r of v.sample.slice(0, 8)) console.log(`    ${fmtSast(r.created_at)} ${pad(r.sender_type, 15)} ${r.contact?.full_name ?? ""} ${r.contact?.whatsapp_id ?? ""}${r.media_url ? "  media" : ""}`);
+}
+
+export async function stats(orgId, opts = {}) {
+  requireOrg(orgId);
+  let resp;
+  try { resp = await http.get("messages", { organization_id: orgId, stats: "1", since: opts.since, until: opts.until }); } catch (e) { fail("Stats failed", e); }
+  if (opts.json) { console.log(JSON.stringify(resp, null, 2)); return; }
+  console.log(`${resp.organization_name}: WhatsApp volume by month (SAST), ${fmtSast(resp.since).slice(0, 10)} to ${fmtSast(resp.until).slice(0, 10)}`);
+  console.log("");
+  console.log(`  ${pad("MONTH", 8)} ${pad("INBOUND", 9)} ${pad("CONTACTS", 9)} ${pad("OUTBOUND", 9)} ${pad("FREE-FORM", 10)} ${pad("TEMPLATE", 9)} ${pad("BOT", 8)} ${pad("HUMAN", 8)} REACHED`);
+  for (const m of resp.months) console.log(`  ${pad(m.month, 8)} ${pad(m.inbound, 9)} ${pad(m.inbound_contacts, 9)} ${pad(m.outbound, 9)} ${pad(`${m.free_form}${m.free_form_pct != null ? ` (${m.free_form_pct}%)` : ""}`, 10)} ${pad(m.template, 9)} ${pad(m.bot, 8)} ${pad(m.human, 8)} ${m.outbound_contacts}`);
+  console.log(`\n  ${resp.classifier}. Free-form = sent inside a customer's 24 h window (Meta's in-window charge from 1 Oct 2026).`);
 }

package/src/commands/org.js

@@ -3,6 +3,7 @@
 // are stripped server-side; this only prints derived booleans + public urls.
 
 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;
 
@@ -97,3 +98,138 @@ export async function create(opts = {}) {
   console.log(`  flowiq agent create ${resp.id} --name "<AgentName>" --make-active`);
   console.log(`  flowiq prompts pull ${resp.id}   # then edit + push`);
 }
+
+// ── views (1 Oct 2026): channels · whatsapp · health · automations · abandoned ──
+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 requireOrg = (v) => { if (!UUID_RE.test(v || "")) { console.error(`Error: "${v}" is not a valid organization UUID.`); process.exit(1); } };
+const yn = (v) => (v ? "yes" : "no");
+const when = (v) => (v ? `${fmtSast(v)} SAST` : "—");
+
+async function view(orgId, name) {
+  requireOrg(orgId);
+  try { return await http.get("org", { organization_id: orgId, view: name }); } catch (e) { fail(`${name} read failed`, e); }
+}
+
+export async function channels(orgId, opts = {}) {
+  if (opts.all) return channelsCensus(opts);
+  const resp = await view(orgId, "channels");
+  if (opts.json) { console.log(JSON.stringify(resp, null, 2)); return; }
+  const c = resp.channels;
+  console.log(`${resp.organization_name} — channels`);
+  const w = c.whatsapp;
+  console.log(`  whatsapp    ${w.connected ? "connected" : "NOT connected"} · provider ${w.provider}${w.phone_number ? ` · ${w.phone_number}` : ""}${w.phone_id ? ` (phone ${w.phone_id})` : ""}${w.connection_type ? ` · ${w.connection_type}` : ""}`);
+  console.log(`              master switch ${w.master_switch ? "ON" : "OFF"} · vert.active ${w.vert_active ? "yes" : "no"}${w.allowed_whatsapp_ids ? ` (only ${w.allowed_whatsapp_ids})` : ""} · connected ${when(w.connected_at)} · registered ${when(w.last_registered_at)}`);
+  const m = c.messenger;
+  console.log(`  messenger   ${m.connected ? "connected" : "not connected"} · via ${m.provider}${m.page_name ? ` · ${m.page_name} (${m.page_id})` : m.page_id ? ` · page ${m.page_id}` : ""} · agent ${yn(m.use_agent)}${m.connected_at ? ` · since ${when(m.connected_at)}` : ""}${m.token_expires_at ? ` · token expires ${when(m.token_expires_at)}` : ""}${m.disconnected_at ? ` · disconnected ${when(m.disconnected_at)} (${m.disconnect_reason ?? "?"})` : ""}`);
+  const i = c.instagram;
+  console.log(`  instagram   ${i.connected ? "connected" : "not connected"} · via ${i.provider}${i.username ? ` · @${i.username}` : ""}${i.account_id ? ` (${i.account_id})` : ""}${i.login_method ? ` · ${i.login_method}` : ""} · agent ${yn(i.use_agent)}${i.connected_at ? ` · since ${when(i.connected_at)}` : ""}${i.token_expires_at ? ` · token expires ${when(i.token_expires_at)}` : ""}${i.disconnected_at ? ` · disconnected ${when(i.disconnected_at)} (${i.disconnect_reason ?? "?"})` : ""}`);
+  const t = c.tiktok;
+  console.log(`  tiktok      ${t.connected ? "connected" : "not connected"}${t.username ? ` · @${t.username}` : ""} · agent ${yn(t.use_agent)}${t.connected_at ? ` · since ${when(t.connected_at)}` : ""}${t.disconnected_at ? ` · disconnected ${when(t.disconnected_at)} (${t.disconnect_reason ?? "?"})` : ""}`);
+  const e = c.email;
+  console.log(`  email       ${e.provider ? `${e.provider}, ${e.connected ? "connected" : "not connected"}` : "no provider"}${e.mailbox ? ` · ${e.mailbox}` : ""} · agent ${yn(e.use_agent)}${e.connected_at ? ` · since ${when(e.connected_at)}` : ""}`);
+  console.log(`  meta ads    ${c.meta_ads.connected ? `connected${c.meta_ads.account_id ? ` · ${c.meta_ads.account_id}` : ""}` : "not connected"}`);
+  if (c.zernio_profile_id) console.log(`  zernio      profile ${c.zernio_profile_id}`);
+}
+
+async function channelsCensus(opts) {
+  let resp;
+  try { resp = await http.get("org", { census: "channels", all: opts.inactive ? "1" : undefined }); } catch (e) { fail("Census failed", e); }
+  if (opts.json) { console.log(JSON.stringify(resp, null, 2)); return; }
+  console.log(`${resp.count} org(s): whatsapp ${Object.entries(resp.providers).map(([k, v]) => `${k} ${v}`).join(", ")} · messenger ${resp.messenger_connected} · instagram ${resp.instagram_connected} · tiktok ${resp.tiktok_connected} · email ${resp.email_connected} · meta ads ${resp.meta_ads_connected}`);
+  console.log("");
+  const pad = (s, n) => String(s ?? "").padEnd(n);
+  console.log(`  ${pad("ORG", 30)} ${pad("WHATSAPP", 12)} ${pad("SWITCH", 7)} ${pad("MESSENGER", 10)} ${pad("INSTAGRAM", 10)} ${pad("TIKTOK", 7)} ${pad("EMAIL", 8)} ADS`);
+  for (const o of resp.orgs) console.log(`  ${pad(o.name.slice(0, 30), 30)} ${pad(`${o.whatsapp}${o.whatsapp_connected ? "" : " (off)"}`, 12)} ${pad(o.master_switch ? "on" : "OFF", 7)} ${pad(o.messenger ?? "—", 10)} ${pad(o.instagram ?? "—", 10)} ${pad(o.tiktok ? "yes" : "—", 7)} ${pad(o.email ?? "—", 8)} ${o.meta_ads ? "yes" : "—"}`);
+}
+
+export async function whatsapp(orgId, opts = {}) {
+  if (opts.all) {
+    let resp;
+    try { resp = await http.get("org", { census: "whatsapp", all: opts.inactive ? "1" : undefined }); } catch (e) { fail("Census failed", e); }
+    if (opts.json) { console.log(JSON.stringify(resp, null, 2)); return; }
+    console.log(`${resp.checked} Meta number(s) checked at Meta, ${resp.unhealthy} with a problem (${resp.skipped_not_meta_or_unconnected} org(s) skipped: not Meta or not connected)`);
+    const pad = (s, n) => String(s ?? "").padEnd(n);
+    console.log("");
+    console.log(`  ${pad("ORG", 30)} ${pad("NUMBER", 18)} ${pad("STATUS", 12)} ${pad("QUALITY", 9)} ${pad("TIER", 12)} PROBLEMS`);
+    for (const o of [...resp.orgs].sort((a, b) => Number(a.healthy) - Number(b.healthy))) console.log(`  ${pad(o.name.slice(0, 30), 30)} ${pad(o.phone_number, 18)} ${pad(o.status ?? "?", 12)} ${pad(o.quality ?? "?", 9)} ${pad(o.tier ?? "?", 12)} ${(o.problems || []).join("; ")}`);
+    return;
+  }
+  const resp = await view(orgId, "whatsapp");
+  if (opts.json) { console.log(JSON.stringify(resp, null, 2)); return; }
+  const w = resp.whatsapp;
+  console.log(`${resp.organization_name} — WhatsApp number health (from Meta)`);
+  if (w.note && !w.phone) { console.log(`  ${w.note}`); return; }
+  const p = w.phone || {};
+  console.log(`  number:      ${p.display_phone_number ?? "?"} · "${p.verified_name ?? "?"}" · phone ${w.phone_id} · WABA ${w.waba_id ?? "?"}`);
+  console.log(`  status:      ${p.status ?? "?"} · platform ${p.platform_type ?? "?"} · account mode ${p.account_mode ?? "?"}`);
+  console.log(`  quality:     ${p.quality_rating ?? "?"} · limit tier ${p.messaging_limit_tier ?? "?"}${p.throughput?.level ? ` · throughput ${p.throughput.level}` : ""}`);
+  console.log(`  name:        ${p.name_status ?? "?"}${p.new_name_status && p.new_name_status !== "NONE" ? ` · pending "${p.new_display_name}" (${p.new_name_status})` : ""} · OBA ${yn(p.is_official_business_account)} · code verification ${p.code_verification_status ?? "?"}`);
+  console.log(`  webhooks:    ${Array.isArray(w.subscribed_apps) ? (w.subscribed_apps.length ? w.subscribed_apps.join(", ") : "NO app subscribed") : w.subscribed_apps ?? "?"}`);
+  if (w.waba && !w.waba.error) console.log(`  waba:        ${w.waba.name ?? ""} · review ${w.waba.account_review_status ?? "?"} · ${w.waba.ownership_type ?? ""}`);
+  console.log(`  ${w.healthy ? "✓ healthy" : `✗ ${w.problems.join("; ")}`}`);
+}
+
+export async function health(orgId, opts = {}) {
+  const resp = await view(orgId, "health");
+  if (opts.json) { console.log(JSON.stringify(resp, null, 2)); return; }
+  const h = resp.health;
+  console.log(`${resp.organization_name} — is the agent ready?  ${h.ready ? "✓ yes" : `✗ ${h.problems.length} problem(s)`}`);
+  for (const p of h.problems) console.log(`  ✗ ${p}`);
+  console.log(`  switch:      master ${h.master_switch ? "ON" : "OFF"} · vert.active ${yn(h.vert_active)}${h.allowed_whatsapp_ids ? ` (only ${h.allowed_whatsapp_ids})` : ""} · provider ${h.provider}${h.coexistence ? ` · ${h.coexistence}` : ""}${h.phone_number ? ` · ${h.phone_number}` : ""}`);
+  console.log(`  keys:        OpenAI ${h.keys.openai.state}${h.keys.openai.detail ? ` (${h.keys.openai.detail})` : ""} · Claude ${h.keys.anthropic_present ? "present" : "none"}`);
+  console.log(`  agent:       ${h.agent ? `${h.agent.name} · ${h.agent.prompt_chars.toLocaleString()} prompt chars · prompt ${h.agent.use_settings_prompt === false ? "OFF" : "on"} · ${h.agent.model ?? "house model"} · product_lookup ${yn(h.agent.product_lookup)} · tickets ${yn(h.agent.ticket_tool_status)}` : "NONE"}`);
+  console.log(`  catalogue:   ${h.catalogue.products} product rows · ${h.catalogue.embedded} with embeddings${h.catalogue.last_sync ? ` · last sync ${when(h.catalogue.last_sync.created_at)} ${h.catalogue.last_sync.success === false ? "FAILED" : "ok"} (+${h.catalogue.last_sync.added ?? 0} ~${h.catalogue.last_sync.updated ?? 0} -${h.catalogue.last_sync.deleted ?? 0})` : " · no sync recorded"}`);
+  const s = h.store;
+  console.log(`  store:       ${s.platform ?? "none"}${s.shopify_domain ? ` ${s.shopify_domain}` : ""}${s.flowiq_webhooks != null ? ` · ${s.flowiq_webhooks} FlowIQ webhooks` : ""}${s.webhooks_note ? ` · ${s.webhooks_note}` : ""}`);
+  if (s.newest_synced_order || s.store_newest_order) console.log(`               newest synced order ${s.newest_synced_order ? `#${s.newest_synced_order.order_number} ${when(s.newest_synced_order.created_at)}` : "none"} · store newest ${s.store_newest_order && !s.store_newest_order.error ? `${s.store_newest_order.name} ${when(s.store_newest_order.created_at)}` : s.store_newest_order?.error ? `read failed (${s.store_newest_order.error})` : "—"}`);
+  console.log(`  traffic:     ${h.traffic.contacts} contacts (${h.traffic.bot_on} with AI on) · inbound 24h ${h.traffic.inbound_24h} · 7d ${h.traffic.inbound_7d} · last bot reply ${when(h.traffic.last_bot_reply_at)}`);
+}
+
+export async function automations(orgId, opts = {}) {
+  requireOrg(orgId);
+  if (opts.enable || opts.disable) {
+    const type = opts.enable || opts.disable;
+    let resp;
+    try { resp = await http.post("org", { action: "automations_set", organization_id: orgId, type: type === true ? undefined : type, enabled: !!opts.enable, dry_run: !opts.commit }); }
+    catch (e) { fail("Set failed", e); }
+    if (opts.json) { console.log(JSON.stringify(resp, null, 2)); return; }
+    if (resp.unchanged) { console.log(`${resp.field} is already ${resp.value}.`); return; }
+    console.log(`${resp.dry_run ? "Would set" : "✓ set"} ${resp.field}: ${resp.from} → ${resp.to} on ${resp.organization_name}${resp.dry_run ? "\nDRY RUN — add --commit to write." : ""}`);
+    return;
+  }
+  const resp = await view(orgId, "automations");
+  if (opts.json) { console.log(JSON.stringify(resp, null, 2)); return; }
+  const a = resp.automations;
+  if (!a.configured) { console.log(`${resp.organization_name} has no automated_messages_config.`); return; }
+  console.log(`${resp.organization_name} — automated order messages: ${a.enabled ? "ON" : "OFF"} (${a.types.filter((t) => t.enabled).length} of ${a.types.length} types on)`);
+  const pad = (s, n) => String(s ?? "").padEnd(n);
+  for (const t of a.types) {
+    console.log(`  ${t.enabled ? "ON " : "off"} ${pad(t.type, 26)} ${pad(t.template_name ?? "(no template)", 34)} ${pad(t.template_state ?? "", 14)} ${t.trigger_event ?? ""}${t.body_mapping ? ` · body ${JSON.stringify(t.body_mapping)}` : ""}`);
+    if (t.warning) console.log(`      ⚠ ${t.warning}`);
+  }
+  console.log(`\nflowiq org automations ${orgId} --enable <type> | --disable <type> [--commit]  (the whole feature: --enable/--disable with no type)`);
+}
+
+export async function abandoned(orgId, opts = {}) {
+  requireOrg(orgId);
+  if (opts.enable !== undefined || opts.disable !== undefined) {
+    const seq = opts.enable ?? opts.disable;
+    let resp;
+    try { resp = await http.post("org", { action: "abandoned_set", organization_id: orgId, sequence: seq === true ? undefined : Number(seq), enabled: opts.enable !== undefined, dry_run: !opts.commit }); }
+    catch (e) { fail("Set failed", e); }
+    if (opts.json) { console.log(JSON.stringify(resp, null, 2)); return; }
+    if (resp.unchanged) { console.log(`${resp.field} is already ${resp.value}.`); return; }
+    console.log(`${resp.dry_run ? "Would set" : "✓ set"} ${resp.field}: ${resp.from} → ${resp.to} on ${resp.organization_name}${resp.dry_run ? "\nDRY RUN — add --commit to write." : ""}`);
+    return;
+  }
+  const resp = await view(orgId, "abandoned");
+  if (opts.json) { console.log(JSON.stringify(resp, null, 2)); return; }
+  const a = resp.abandoned;
+  if (!a.configured) { console.log(`${resp.organization_name} has no abandoned_checkout_config (no recovery messages).`); return; }
+  console.log(`${resp.organization_name} — abandoned-cart recovery: ${a.enabled ? "ON" : "OFF"}${a.use_utm != null ? ` · utm ${yn(a.use_utm)}` : ""}`);
+  for (const s of a.sequences) {
+    console.log(`  ${s.enabled ? "ON " : "off"} sequence ${s.sequence}: ${s.template_name ?? "(no template)"} (${s.template_state ?? "?"}) · after ${s.delay_minutes} min${s.cart_filter ? ` · ${s.cart_filter}` : ""}${s.include_discount ? ` · discount ${s.discount_code ?? (s.auto_create_discount ? "auto" : "?")}` : ""}${s.include_image ? " · image" : ""}${s.link_mode ? ` · ${s.link_mode}` : ""}`);
+    console.log(`      last 30 days: ${s.last_30_days.sent} sent, ${s.last_30_days.not_sent} not sent`);
+  }
+  console.log(`\nflowiq org abandoned ${orgId} --enable <n> | --disable <n> [--commit]  (the whole feature: --enable/--disable with no number)`);
+}

package/src/commands/rules.js

@@ -0,0 +1,67 @@
+// `flowiq rules list|show|results|enable|disable` — the Automations rules
+// engine, custom_notification_rules (server: api/cli/rules.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}`); if (e.body?.needs_confirm) console.error("  Re-run with --confirm."); process.exit(1); }
+
+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("rules", { organization_id: orgId, trigger: opts.trigger }); } 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 automation rules${opts.trigger ? ` with trigger ${opts.trigger}` : ""}.`); return; }
+  console.log(`${resp.organization_name}: ${resp.count} rule(s), ${resp.enabled} enabled`);
+  console.log("");
+  console.log(`  ${pad("", 3)} ${pad("NAME", 32)} ${pad("TRIGGER", 34)} ${pad("SENDS", 30)} WHEN`);
+  for (const r of resp.rules) {
+    console.log(`  ${r.enabled ? "ON " : "off"} ${pad(r.name, 32)} ${pad(`${r.trigger_type}=${r.trigger_value ?? ""}`, 34)} ${pad(r.template_name ?? r.action_type, 30)} ${r.send_at}${r.conditions.length ? ` · conditions: ${r.conditions.join(", ")}` : ""}`);
+    console.log(`      ${r.id}`);
+  }
+  console.log(`\nflowiq rules show <rule_id> · rules results <rule_id> --since 30d`);
+}
+
+export async function show(ruleId, opts = {}) {
+  if (!UUID_RE.test(ruleId || "")) { console.error(`Error: "${ruleId}" is not a valid rule UUID.`); process.exit(1); }
+  let resp;
+  try { resp = await http.get("rules", { rule_id: ruleId }); } catch (e) { fail("Read failed", e); }
+  if (opts.json) { console.log(JSON.stringify(resp, null, 2)); return; }
+  const r = resp.rule;
+  console.log(`${r.name}  ${r.id}  on ${resp.organization_name}: ${r.enabled ? "ENABLED" : "disabled"}`);
+  console.log(`  trigger:    ${r.trigger_type} = ${r.trigger_value ?? "(any)"}`);
+  console.log(`  action:     ${r.action_type}${r.template_name ? ` · template ${r.template_name}` : ""}`);
+  console.log(`  send at:    ${r.send_at}`);
+  if (r.body_parameters) console.log(`  body:       ${JSON.stringify(r.body_parameters)}`);
+  if (r.button_parameters) console.log(`  buttons:    ${JSON.stringify(r.button_parameters)}`);
+  if (r.conditions_raw) console.log(`  conditions: ${JSON.stringify(r.conditions_raw)}`);
+  if (r.action_config) console.log(`  config:     ${JSON.stringify(r.action_config)}`);
+  console.log(`  priority:   ${r.priority} · created ${fmtSast(r.created_at)} SAST`);
+}
+
+export async function results(ruleId, opts = {}) {
+  if (!UUID_RE.test(ruleId || "")) { console.error(`Error: "${ruleId}" is not a valid rule UUID.`); process.exit(1); }
+  let resp;
+  try { resp = await http.get("rules", { rule_id: ruleId, results: "1", since: opts.since }); } catch (e) { fail("Results failed", e); }
+  if (opts.json) { console.log(JSON.stringify(resp, null, 2)); return; }
+  console.log(`${resp.rule.name} (${resp.organization_name}): ${resp.queued} queued send(s) since ${fmtSast(resp.since)} SAST${resp.capped ? " (capped)" : ""}`);
+  console.log(`  by status: ${Object.entries(resp.by_status).map(([k, v]) => `${k} ${v}`).join(" · ") || "none"}`);
+  for (const e of resp.error_rollup) console.log(`  ${String(e.n).padStart(5)} × ${e.message}`);
+  if (resp.recent.length) {
+    console.log("\n  recent:");
+    for (const q of resp.recent) console.log(`    ${fmtSast(q.scheduled_for)} ${pad(q.status, 10)} ${q.template ?? ""} → ${(q.contact_ids || []).join(",")}${q.error_message ? `  ${String(q.error_message).slice(0, 80)}` : ""}`);
+  }
+}
+
+async function toggle(ruleId, opts, action) {
+  if (!UUID_RE.test(ruleId || "")) { console.error(`Error: "${ruleId}" is not a valid rule UUID.`); process.exit(1); }
+  let resp;
+  try { resp = await http.post("rules", { action, rule_id: ruleId, confirm: !!opts.confirm }); } catch (e) { fail(`${action} failed`, e); }
+  if (opts.json) { console.log(JSON.stringify(resp, null, 2)); return; }
+  if (resp.unchanged) { console.log(`Rule is already ${resp.enabled ? "enabled" : "disabled"}.`); return; }
+  console.log(`✓ "${resp.name}" ${resp.enabled ? "ENABLED" : "disabled"} (was ${resp.was ? "enabled" : "disabled"}).`);
+}
+export const enable = (id, opts) => toggle(id, opts, "enable");
+export const disable = (id, opts) => toggle(id, opts, "disable");

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(", ")})` : ""}.`);
+}

package/src/index.js

@@ -28,6 +28,11 @@ import * as agentsCmd from "./commands/agents.js";
 import * as agentUpdatesCmd from "./commands/agent-updates.js";
 import * as plansCmd from "./commands/plans.js";
 import * as gapsCmd from "./commands/gaps.js";
+import * as contactsCmd from "./commands/contacts.js";
+import * as widgetsCmd from "./commands/widgets.js";
+import * as ticketsCmd from "./commands/tickets.js";
+import * as flowsCmd from "./commands/flows.js";
+import * as rulesCmd from "./commands/rules.js";
 import * as exportCmd from "./commands/export.js";
 import * as testCmd from "./commands/agent-test.js";
 import * as knowledgeCmd from "./commands/knowledge.js";
@@ -133,6 +138,26 @@ export function run(argv) {
     .description("Pull last N user-message windows of conversation for a contact (default N=25, max 200)")
     .option("--count <n>", "number of most-recent user-* messages to anchor on", "25")
     .action((contactId, opts) => messagesCmd.pull(contactId, opts));
+  msgs.command("search <organization_id> <text...>")
+    .description("Org-wide text search: did the agent (or anyone) say X to anyone? Template sends excluded unless asked")
+    .option("--since <when>", "24h (default) | 7d | 2w | YYYY-MM-DD")
+    .option("--until <when>", "upper bound")
+    .option("--sender-type <list>", "comma list, e.g. bot-whatsapp or user-whatsapp,user-web (default: conversation rows only)")
+    .option("--include-templates", "also match template / broadcast payloads")
+    .option("--limit <n>", "max rows (default 200, max 1000)")
+    .option("--json", "raw JSON (rows carry contact_id)")
+    .action((orgId, text, opts) => messagesCmd.search(orgId, text, opts));
+  msgs.command("failures <organization_id>")
+    .description("What failed to send and why (Meta error codes by reason / media / contact), plus sends Meta accepted and never confirmed")
+    .option("--since <when>", "7d (default) | 24h | 30d | YYYY-MM-DD")
+    .option("--json", "raw JSON")
+    .action((orgId, opts) => messagesCmd.failures(orgId, opts));
+  msgs.command("stats <organization_id>")
+    .description("Monthly WhatsApp volume: inbound, outbound, free-form (in-window) vs template, bot vs human")
+    .option("--since <when>", "6m (default) | 30d | YYYY-MM-DD")
+    .option("--until <when>", "upper bound (default now)")
+    .option("--json", "raw JSON")
+    .action((orgId, opts) => messagesCmd.stats(orgId, opts));
 
   // fine-tuning (agents.fine_tuning text + agents.fine_tuning_entries jsonb)
   const ft = program.command("fine-tuning")
@@ -418,6 +443,36 @@ export function run(argv) {
     .description("Show the org's platform, storefront url + active agent (raw creds stripped)")
     .option("--json", "print the raw JSON payload")
     .action((orgId, opts) => orgCmd.info(orgId, opts));
+  org.command("channels [organization_id]")
+    .description("Channel connections: WhatsApp (provider, master switch), Messenger, Instagram, TikTok, email, Meta Ads; --all = every org")
+    .option("--all", "census across every active org (no organization_id needed)")
+    .option("--inactive", "with --all: include inactive orgs")
+    .option("--json", "raw JSON")
+    .action((orgId, opts) => orgCmd.channels(orgId, opts));
+  org.command("whatsapp [organization_id]")
+    .description("WhatsApp number health straight from Meta: status, quality, limit tier, name status, webhook subscription; --all = every Meta org")
+    .option("--all", "census across every active Meta org")
+    .option("--inactive", "with --all: include inactive orgs")
+    .option("--json", "raw JSON")
+    .action((orgId, opts) => orgCmd.whatsapp(orgId, opts));
+  org.command("health <organization_id>")
+    .description("Is this client's agent ready? Master switch, keys (probed), agent, catalogue + embeddings, store webhooks + order sync, traffic")
+    .option("--json", "raw JSON")
+    .action((orgId, opts) => orgCmd.health(orgId, opts));
+  org.command("automations <organization_id>")
+    .description("Automated order messages (automated_messages_config): each type, its template and whether that template is approved")
+    .option("--enable [type]", "switch a type on (or the whole feature with no type); dry run unless --commit")
+    .option("--disable [type]", "switch a type off (or the whole feature)")
+    .option("--commit", "write the change")
+    .option("--json", "raw JSON")
+    .action((orgId, opts) => orgCmd.automations(orgId, opts));
+  org.command("abandoned <organization_id>")
+    .description("Abandoned-cart recovery config per sequence (template, delay, cart filter, discount) + the last 30 days of sends")
+    .option("--enable [sequence]", "switch a sequence on (or the whole feature with no number); dry run unless --commit")
+    .option("--disable [sequence]", "switch a sequence off (or the whole feature)")
+    .option("--commit", "write the change")
+    .option("--json", "raw JSON")
+    .action((orgId, opts) => orgCmd.abandoned(orgId, opts));
 
   // org flags — organizations.feature_flags (the Settings → Profile switches).
   // Registry-allowlisted writes, credentials never read or written, dangerous
@@ -616,6 +671,90 @@ export function run(argv) {
     .option("--commit", "apply the change (default is a dry run)")
     .action((planId, opts) => plansCmd.status(planId, opts));
 
+  // contacts (1 Oct 2026): the contact record from the terminal
+  const contacts = program.command("contacts").description("Find a contact (incl. archived / blocked) with its inbox state, lint numbers, merge, opt out / in, fix a number, export");
+  contacts.command("find <organization_id>")
+    .description("Find contacts by email / phone / name / id, archived and blocked included, with team, assignee, latest message and open ticket")
+    .option("--email <substr>", "email contains").option("--phone <digits>", "number contains (digits only)").option("--name <substr>", "name contains").option("--id <uuid>", "one contact by id")
+    .option("--limit <n>", "max matches (default 20, max 100)").option("--json", "raw JSON")
+    .action((orgId, opts) => contactsCmd.find(orgId, opts));
+  contacts.command("show <contact_id>")
+    .description("One contact's record + inbox state (needs --org)")
+    .requiredOption("--org <organization_id>", "the contact's org").option("--json", "raw JSON")
+    .action((contactId, opts) => contactsCmd.show(contactId, opts));
+  contacts.command("census <organization_id>")
+    .description("Archived chats that still carry unread messages or where the customer wrote last")
+    .option("--json", "raw JSON")
+    .action((orgId, opts) => contactsCmd.census(orgId, opts));
+  contacts.command("lint <organization_id>")
+    .description("Malformed WhatsApp numbers (doubled country code, kept trunk 0, bad length) with the repair and whether a twin contact holds it")
+    .option("--json", "raw JSON")
+    .action((orgId, opts) => contactsCmd.lint(orgId, opts));
+  contacts.command("merge <organization_id> <keep_id> <remove_id>")
+    .description("Merge <remove_id> into <keep_id> (messages, tickets, orders move; the app's merge_contacts_v2). Dry run unless --commit")
+    .option("--commit", "do it").option("--json", "raw JSON")
+    .action((orgId, keep, remove, opts) => contactsCmd.merge(orgId, keep, remove, opts));
+  contacts.command("optout <organization_id>")
+    .description("Opt contacts OUT of broadcasts (allow_broadcast=false + the inbox marker). Dry run unless --commit")
+    .option("--contact <id>", "contact id (repeatable)", (v, a) => (a || []).concat(v), []).option("--ids-file <file>", "file of contact ids (whitespace / comma separated)")
+    .option("--reason <text>", "recorded on the marker and the audit row").option("--commit", "write").option("--json", "raw JSON")
+    .action((orgId, opts) => contactsCmd.optout(orgId, opts));
+  contacts.command("optin <organization_id>")
+    .description("Opt contacts back IN to broadcasts (they will receive sends again). Dry run unless --commit --confirm")
+    .option("--contact <id>", "contact id (repeatable)", (v, a) => (a || []).concat(v), []).option("--ids-file <file>", "file of contact ids")
+    .option("--reason <text>", "recorded on the marker and the audit row").option("--commit", "write").option("--confirm", "required with --commit").option("--json", "raw JSON")
+    .action((orgId, opts) => contactsCmd.optin(orgId, opts));
+  contacts.command("set <organization_id> <contact_id>")
+    .description("Repair a contact's WhatsApp number (refused when another contact holds it: merge instead). Dry run unless --commit")
+    .option("--whatsapp-id <digits>", "the corrected number, country code first").option("--commit", "write").option("--json", "raw JSON")
+    .action((orgId, contactId, opts) => contactsCmd.set(orgId, contactId, opts));
+  contacts.command("export <organization_id>")
+    .description("Export the org's contacts to CSV (Excel opens it) → .flowiq/contacts/<org>.csv")
+    .option("--subscribers", "only opted-in, not archived, not blocked").option("--out <file>", "write here instead").option("--json", "write JSON instead of CSV")
+    .action((orgId, opts) => contactsCmd.exportContacts(orgId, opts));
+
+  // widgets (1 Oct 2026): web chat widgets
+  const widgets = program.command("widgets").description("Web chat widgets: list, show, pull / push the config (id-keyed patch), embed code, set the active one");
+  widgets.command("list <organization_id>").description("The org's widgets").option("--json", "raw JSON").action((orgId, opts) => widgetsCmd.list(orgId, opts));
+  widgets.command("show <widget_id>").description("One widget's settings").option("--json", "raw JSON").action((id, opts) => widgetsCmd.show(id, opts));
+  widgets.command("pull <widget_id>").description("Write the full config to .flowiq/widgets/<org>-<id>.json for editing").option("--out <file>", "write here instead").action((id, opts) => widgetsCmd.pull(id, opts));
+  widgets.command("push <file>").description("Push a pulled file back: only differing fields, jsonb bags merged at their top level (null removes a key). Dry run unless --commit")
+    .option("--commit", "write").option("--json", "raw JSON").action((file, opts) => widgetsCmd.push(file, opts));
+  widgets.command("embed <organization_id> [widget_id]").description("The <script> snippet a client pastes (widget id optional: the org-only embed resolves to the active widget)").option("--json", "raw JSON").action((orgId, wid, opts) => widgetsCmd.embed(orgId, wid, opts));
+  widgets.command("activate <widget_id>").description("Make this the widget an org-only embed resolves to").option("--json", "raw JSON").action((id, opts) => widgetsCmd.activate(id, opts));
+
+  // tickets (1 Oct 2026): escalation tickets
+  const tickets = program.command("tickets").description("Escalation tickets: list open / stale ones, show one, change its status");
+  tickets.command("list <organization_id>")
+    .description("Tickets newest first (default open + in_progress)")
+    .option("--status <list>", "open,in_progress (default) | resolved | closed | all").option("--contact <id>", "one contact's tickets")
+    .option("--older-than <age>", "only tickets opened longer ago than 48h / 3d / 1w").option("--limit <n>", "max rows (default 100, max 500)").option("--json", "raw JSON")
+    .action((orgId, opts) => ticketsCmd.list(orgId, opts));
+  tickets.command("show <ticket_id>").description("One ticket in full").option("--json", "raw JSON").action((id, opts) => ticketsCmd.show(id, opts));
+  tickets.command("status <ticket_id>")
+    .description("Change a ticket's status the way the app does (stamps, history; honours reenable_bot_on_ticket_resolve). Dry run unless --commit")
+    .requiredOption("--set <status>", "open | in_progress | resolved | closed").option("--note <text>", "resolution / reopen note").option("--commit", "write").option("--json", "raw JSON")
+    .action((id, opts) => ticketsCmd.status(id, opts));
+
+  // flows (1 Oct 2026): the Flows automation engine
+  const flows = program.command("flows").description("Flows: list (trigger, templates, param-key lint), show, execution status + failures, enable / disable");
+  flows.command("list <organization_id>").description("Every flow with trigger, templates, stats and a lint of its body_parameters keys").option("--json", "raw JSON").action((orgId, opts) => flowsCmd.list(orgId, opts));
+  flows.command("show <flow_id>").description("One flow with its full configuration").option("--json", "raw JSON").action((id, opts) => flowsCmd.show(id, opts));
+  flows.command("status <organization_id>")
+    .description("Execution funnel per status and per flow, with the verbatim error rollup")
+    .option("--since <when>", "14d (default) | 7d | 2w | YYYY-MM-DD").option("--flow <id>", "one flow").option("--failed", "also list the failed executions").option("--json", "raw JSON")
+    .action((orgId, opts) => flowsCmd.status(orgId, opts));
+  flows.command("enable <flow_id>").description("Enable a flow (arms real sends: needs --confirm)").option("--confirm", "required").option("--json", "raw JSON").action((id, opts) => flowsCmd.enable(id, opts));
+  flows.command("disable <flow_id>").description("Disable a flow").option("--json", "raw JSON").action((id, opts) => flowsCmd.disable(id, opts));
+
+  // rules (1 Oct 2026): the Automations rules engine (custom_notification_rules)
+  const rules = program.command("rules").description("Automation rules (Shoppers → Rules): list, show, what each has queued, enable / disable");
+  rules.command("list <organization_id>").description("Every rule: trigger, template, delay / quiet hours, conditions").option("--trigger <type>", "tag_added | shopify_order_stage | external_webhook | instagram_comment").option("--json", "raw JSON").action((orgId, opts) => rulesCmd.list(orgId, opts));
+  rules.command("show <rule_id>").description("One rule in full").option("--json", "raw JSON").action((id, opts) => rulesCmd.show(id, opts));
+  rules.command("results <rule_id>").description("What the rule queued (api_request_queue): status counts, errors, recent sends").option("--since <when>", "30d (default) | 7d | YYYY-MM-DD").option("--json", "raw JSON").action((id, opts) => rulesCmd.results(id, opts));
+  rules.command("enable <rule_id>").description("Enable a rule (arms real template sends: needs --confirm)").option("--confirm", "required").option("--json", "raw JSON").action((id, opts) => rulesCmd.enable(id, opts));
+  rules.command("disable <rule_id>").description("Disable a rule").option("--json", "raw JSON").action((id, opts) => rulesCmd.disable(id, opts));
+
   // gaps (CLI gap reports + feature requests, filed by anyone incl. a Claude session)
   const gaps = program.command("gaps")
     .alias("requests")