@flowapt/flowiq-cli 0.9.9 → 0.11.0

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/links.js

@@ -7,7 +7,9 @@
 //
 //   flowiq links shorten <org> --url <u> [--url <u2>…] --campaign "Spring Promotion"
 //   flowiq links shorten <org> --file ./message.txt --campaign X --content ViewMore --domain linklnk.io
-//   flowiq links list <org> [--campaign X] [--limit 25]
+//   flowiq links shorten <org> --url <u> --slug spring-sale --commit     (readable code)
+//   flowiq links list <org> [--campaign X] [--code abc123] [--to /collections/x] [--limit 25] [--all]
+//   flowiq links repoint <org> <code> --to <url> [--commit]            (move a live code)
 //
 // NAMING — you do not have to get the tag right yourself. The house convention
 // is `Date_Campaign` (`9Sep_SpringPromotion`: the date the broadcast GOES OUT,
@@ -114,11 +116,13 @@ export async function shorten(orgId, opts = {}) {
       campaign,
       content,
       domain: opts.domain,
+      slug: opts.slug,
       dry_run: dryRun,
       confirm_new_campaign: !!opts.newCampaign,
     });
   } catch (e) {
     console.error(`Shorten failed: ${e.message}`);
+    if (e.body?.error && !e.message.includes(e.body.error)) console.error(`  ${e.body.error}`);
     process.exit(1);
   }
 
@@ -127,7 +131,7 @@ export async function shorten(orgId, opts = {}) {
   const utm = resp.utm
     ? `utm_source=${resp.utm.source} · utm_medium=${resp.utm.medium} · utm_campaign=${resp.utm.campaign} · utm_content=${resp.utm.content}`
     : "no UTM tags (plain short link)";
-  console.log(`${resp.organization_name} · ${resp.domain}`);
+  console.log(`${resp.organization_name} · ${resp.domain}${resp.slug ? ` · slug ${resp.slug}` : ""}`);
   console.log(`${utm}\n`);
   if (resp.campaign_conflicts?.length) {
     const c = resp.campaign_conflicts[0];
@@ -169,30 +173,69 @@ export async function shorten(orgId, opts = {}) {
 
 export async function list(orgId, opts = {}) {
   requireOrg(orgId);
-  let resp;
-  try {
-    resp = await http.post("links", {
-      organization_id: orgId,
-      action: "list",
-      campaign: opts.campaign,
-      limit: opts.limit,
-    });
-  } catch (e) {
-    console.error(`List failed: ${e.message}`);
-    process.exit(1);
+  // --all walks every page (500 a call) so a whole campaign or a whole org can
+  // be exported; without it the first page is the answer and has_more says so.
+  const pageSize = opts.all ? 500 : (opts.limit ? Number(opts.limit) : 25);
+  const links = [];
+  let offset = 0, resp, hasMore = false;
+  for (;;) {
+    try {
+      resp = await http.post("links", {
+        organization_id: orgId,
+        action: "list",
+        campaign: opts.campaign,
+        code: opts.code,
+        to: opts.to,
+        limit: pageSize,
+        offset,
+      });
+    } catch (e) {
+      console.error(`List failed: ${e.message}`);
+      process.exit(1);
+    }
+    links.push(...(resp.links || []));
+    hasMore = !!resp.has_more;
+    if (!opts.all || !hasMore || !(resp.links || []).length) break;
+    offset += (resp.links || []).length;
+    if (offset > 50000) break;
   }
 
-  if (opts.json) { console.log(JSON.stringify(resp, null, 2)); return; }
+  if (opts.json) { console.log(JSON.stringify({ ...resp, count: links.length, links, has_more: hasMore }, null, 2)); return; }
 
-  if (!resp.links.length) {
-    console.log(opts.campaign ? `No links on ${resp.organization_name} for campaign "${opts.campaign}".` : `No links on ${resp.organization_name}.`);
+  const what = [opts.campaign && `campaign "${opts.campaign}"`, opts.code && `code "${opts.code}"`, opts.to && `destination containing "${opts.to}"`].filter(Boolean).join(", ");
+  if (!links.length) {
+    console.log(what ? `No links on ${resp.organization_name} for ${what}.` : `No links on ${resp.organization_name}.`);
     return;
   }
   const pad = (s, n) => String(s ?? "").padEnd(n);
-  console.log(`${pad("CODE", 10)}${pad("CLICKS", 8)}${pad("CREATED", 12)}URL`);
-  for (const l of resp.links) {
+  const codeW = Math.min(50, Math.max(10, ...links.map((l) => String(l.code || "").length + 2)));
+  console.log(`${pad("CODE", codeW)}${pad("CLICKS", 8)}${pad("CREATED", 12)}URL`);
+  for (const l of links) {
     const day = String(l.created_at || "").slice(0, 10);
-    console.log(`${pad(l.code, 10)}${pad(l.clicks ?? 0, 8)}${pad(day, 12)}${l.full_url}`);
+    console.log(`${pad(l.code, codeW)}${pad(l.clicks ?? 0, 8)}${pad(day, 12)}${l.full_url}${l.is_active === false ? "  (inactive)" : ""}${l.per_message ? "  (per-message)" : ""}`);
+  }
+  console.log(`\n${links.length} link(s)${what ? ` · ${what}` : ""}${hasMore ? ` · more exist (--all, or --limit up to 500)` : ""}`);
+}
+
+// `flowiq links repoint <org> <code> --to <url> [--commit]` — move where a
+// live code sends people. The code stays in every message that carries it.
+export async function repoint(orgId, code, opts = {}) {
+  requireOrg(orgId);
+  if (!code) { console.error("Error: pass the short code, e.g. flowiq links repoint <org> VVSSh2 --to https://…"); process.exit(1); }
+  if (!opts.to) { console.error("Error: --to <url> is required (the new destination page)."); process.exit(1); }
+  let resp;
+  try {
+    resp = await http.post("links", { organization_id: orgId, action: "repoint", code, url: opts.to, dry_run: !opts.commit, confirm: !!opts.commit });
+  } catch (e) {
+    console.error(`Repoint failed: ${e.message}`);
+    if (e.body?.error && !e.message.includes(e.body.error)) console.error(`  ${e.body.error}`);
+    process.exit(1);
   }
-  console.log(`\n${resp.count} link(s)${opts.campaign ? ` · campaign "${opts.campaign}"` : ""}`);
+  if (opts.json) { console.log(JSON.stringify(resp, null, 2)); return; }
+  console.log(`${resp.organization_name} · ${resp.code} (${resp.clicks ?? 0} clicks${resp.is_active === false ? ", inactive" : ""})`);
+  console.log(`  from: ${resp.from}`);
+  console.log(`  to:   ${resp.to}`);
+  if (resp.unchanged) { console.log("\nAlready points there — nothing to do."); return; }
+  if (resp.dry_run) console.log("\nDRY RUN — nothing changed. Add --commit to repoint.");
+  else console.log(`\n✓ repointed. Undo: flowiq links repoint ${orgId} ${resp.code} --to '${resp.from}' --commit`);
 }

package/src/commands/members.js

@@ -0,0 +1,95 @@
+// `flowiq members list|add|role|rename|remove` + `flowiq users lookup` — an
+// org's people and one user across orgs (server: api/cli/members.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); }
+const requireOrg = (v) => { if (!UUID_RE.test(v || "")) { console.error(`Error: "${v}" is not a valid organization UUID.`); process.exit(1); } };
+const who = (v) => (UUID_RE.test(v || "") ? { user_id: v } : { email: v });
+
+export async function list(orgId, opts = {}) {
+  requireOrg(orgId);
+  let resp;
+  try { resp = await http.get("members", { organization_id: orgId }); } catch (e) { fail("List failed", e); }
+  if (opts.json) { console.log(JSON.stringify(resp, null, 2)); return; }
+  console.log(`${resp.organization_name}: ${resp.count} member(s)${resp.pending_invitations.length ? ` · ${resp.pending_invitations.length} pending invitation(s)` : ""}`);
+  console.log("");
+  console.log(`  ${pad("ROLE", 7)} ${pad("NAME", 24)} ${pad("EMAIL", 34)} ${pad("LAST SIGN-IN", 18)} SINCE`);
+  const order = { admin: 0, member: 1, viewer: 2 };
+  for (const m of [...resp.members].sort((a, b) => (order[a.role] ?? 9) - (order[b.role] ?? 9) || String(a.full_name || "").localeCompare(String(b.full_name || "")))) {
+    const flags = [m.is_owner && "owner", m.status !== "active" && m.status, m.view_only && "view-only", m.account_missing && "NO ACCOUNT", m.profile_deleted && "profile deleted"].filter(Boolean).join(", ");
+    console.log(`  ${pad(m.role, 7)} ${pad((m.full_name || "—").slice(0, 24), 24)} ${pad((m.email || "?").slice(0, 34), 34)} ${pad(m.last_sign_in_at ? fmtSast(m.last_sign_in_at) : "never", 18)} ${String(m.since || "").slice(0, 10)}${flags ? `  (${flags})` : ""}`);
+  }
+  for (const i of resp.pending_invitations) console.log(`  ${pad("invite", 7)} ${pad("—", 24)} ${pad(i.email, 34)} ${pad("pending", 18)} ${String(i.created_at || "").slice(0, 10)}  (${i.role})`);
+  console.log(`\nflowiq members add ${orgId} <email> --role member · role ${orgId} <email> admin|member|viewer · remove ${orgId} <email> --confirm`);
+}
+
+export async function add(orgId, emailOrId, opts = {}) {
+  requireOrg(orgId);
+  if (!emailOrId) { console.error("Error: pass the person's email (they must already have an account)."); process.exit(1); }
+  let resp;
+  try { resp = await http.post("members", { action: "add", organization_id: orgId, ...who(emailOrId), role: opts.role || "member" }); } catch (e) { fail("Add failed", e); }
+  if (opts.json) { console.log(JSON.stringify(resp, null, 2)); return; }
+  if (resp.unchanged) { console.log(resp.note); return; }
+  console.log(`✓ ${resp.email} is now a ${resp.role}${resp.reactivated ? " again" : ""}. Undo: flowiq members remove ${orgId} ${resp.email} --confirm`);
+}
+
+export async function role(orgId, emailOrId, newRole, opts = {}) {
+  requireOrg(orgId);
+  if (!emailOrId || !newRole) { console.error("Error: flowiq members role <org> <email> admin|member|viewer"); process.exit(1); }
+  let resp;
+  try { resp = await http.post("members", { action: "role", organization_id: orgId, ...who(emailOrId), role: newRole }); } catch (e) { fail("Role change failed", e); }
+  if (opts.json) { console.log(JSON.stringify(resp, null, 2)); return; }
+  if (resp.unchanged) { console.log(`Already ${resp.role}.`); return; }
+  console.log(`✓ ${resp.email}: ${resp.from} → ${resp.to}. Undo: flowiq members role ${orgId} ${resp.email} ${resp.from}`);
+}
+
+export async function rename(emailOrId, name, opts = {}) {
+  if (!emailOrId || !name) { console.error("Error: flowiq members rename <email> \"Full Name\""); process.exit(1); }
+  let resp;
+  try { resp = await http.post("members", { action: "rename", ...who(emailOrId), full_name: name }); } catch (e) { fail("Rename failed", e); }
+  if (opts.json) { console.log(JSON.stringify(resp, null, 2)); return; }
+  console.log(`✓ ${resp.email}: "${resp.from ?? ""}" → "${resp.to}" (profiles.full_name, shown in every org they belong to)`);
+}
+
+export async function remove(orgId, emailOrId, opts = {}) {
+  requireOrg(orgId);
+  if (!emailOrId) { console.error("Error: flowiq members remove <org> <email> --confirm"); process.exit(1); }
+  let resp;
+  try { resp = await http.post("members", { action: "remove", organization_id: orgId, ...who(emailOrId), confirm: !!opts.confirm }); } catch (e) { fail("Remove failed", e); }
+  if (opts.json) { console.log(JSON.stringify(resp, null, 2)); return; }
+  if (resp.dry_run) { console.log(`Would remove ${resp.email} (${resp.role}${resp.is_owner ? ", OWNER" : ""}) from this org. Add --confirm.`); return; }
+  console.log(`✓ removed ${resp.email} (${resp.role}). Undo: flowiq members add ${orgId} ${resp.email} --role ${resp.role}`);
+}
+
+// `flowiq users lookup <email>` — the account behind an address, across orgs.
+export async function lookup(email, opts = {}) {
+  if (!email) { console.error("Error: flowiq users lookup <email>"); process.exit(1); }
+  let resp;
+  try { resp = await http.get("members", { email }); }
+  catch (e) {
+    if (e.status === 404 || /No account/.test(e.message)) {
+      console.log(`No account for ${email}.`);
+      const inv = e.body?.invitations || [];
+      if (inv.length) { console.log(`  invitations:`); for (const i of inv) console.log(`    ${i.status.padEnd(9)} ${i.role.padEnd(7)} org ${i.organization_id} ${String(i.created_at).slice(0, 10)}`); }
+      else console.log("  no invitation on record either — they were never invited, or were invited under another address.");
+      return;
+    }
+    fail("Lookup failed", e);
+  }
+  if (opts.json) { console.log(JSON.stringify(resp, null, 2)); return; }
+  const u = resp.user;
+  console.log(`${u.email}  ${u.id}${resp.super_admin ? "  (Flowapt super admin)" : ""}`);
+  console.log(`  name:          ${resp.full_name ?? "(no profile name)"}${resp.profile_deleted ? "  (profile deleted)" : ""}`);
+  console.log(`  signs in with: ${u.providers.join(", ")}${u.email_confirmed_at ? "" : "  (email NOT confirmed)"}${u.banned_until ? `  BANNED until ${u.banned_until}` : ""}`);
+  console.log(`  created:       ${fmtSast(u.created_at)} SAST · last sign-in ${u.last_sign_in_at ? `${fmtSast(u.last_sign_in_at)} SAST` : "never"}`);
+  if (!resp.organizations.length) console.log("  organizations: none");
+  else {
+    console.log(`  organizations: ${resp.organizations.length}`);
+    for (const o of resp.organizations) console.log(`    ${pad(o.role, 7)} ${pad((o.organization_name || o.organization_id).slice(0, 30), 30)} ${o.organization_id}${o.status !== "active" ? `  (${o.status})` : ""}${o.inactive ? "  (org inactive)" : ""}`);
+  }
+  console.log(`\n  Password-reset emails are sent by Supabase Auth and are not recorded here; a stuck login is usually a wrong provider (Google vs password) or an unconfirmed email.`);
+}

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,109 @@ 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>)" : ""}`);
+  }
+  // Who sent each bot row: the agent, a broadcast, or an automation (the
+  // notification_* columns are in the JSON; this names them so "was 'Hey MRS'
+  // the agent or the order confirmation?" is answered here, not in SQL).
+  const sources = {};
+  for (const m of rows.filter((x) => String(x.sender_type || "").startsWith("bot-"))) sources[sentBy(m)] = (sources[sentBy(m)] || 0) + 1;
+  const keys = Object.keys(sources);
+  if (keys.length) console.log(`  sent by:        ${keys.sort().map((k) => `${k} ${sources[k]}`).join(" · ")}`);
+}
+
+export function sentBy(m) {
+  if (m.broadcast_id) return "broadcast";
+  if (m.notification_template) return `automation: ${m.notification_template}${m.notification_event ? ` (${m.notification_event})` : ""}`;
+  if (m.notification_rule_id) return `rule ${String(m.notification_rule_id).slice(0, 8)}`;
+  if (m.notification_event) return `automation (${m.notification_event})`;
+  return "agent";
+}
+
+// `flowiq messages delete <contact_id> [--before 30d] [--sender-type a,b] --confirm`
+export async function remove(contactId, opts = {}) {
+  if (!UUID_RE.test(contactId)) { console.error(`Error: "${contactId}" is not a valid contact UUID.`); process.exit(1); }
+  const senderTypes = opts.senderType ? String(opts.senderType).split(",").map((s) => s.trim()).filter(Boolean) : undefined;
+  let preview;
+  try { preview = await http.post("messages", { action: "delete", contact_id: contactId, before: opts.before, sender_types: senderTypes, dry_run: true }); }
+  catch (e) { fail("Delete failed", e); }
+  if (opts.json && !opts.confirm) { console.log(JSON.stringify(preview, null, 2)); return; }
+  console.log(`${preview.contact_name || "(no name)"} ${preview.contact_whatsapp_id || ""} on ${preview.organization_name}: ${preview.count} message(s)${preview.before ? ` older than ${fmtSast(preview.before)} SAST` : ""}${senderTypes ? ` of type ${senderTypes.join(", ")}` : ""}`);
+  for (const [k, v] of Object.entries(preview.by_sender).sort()) console.log(`    ${pad(k, 18)} ${v}`);
+  if (preview.oldest) console.log(`  from ${fmtSast(preview.oldest)} to ${fmtSast(preview.newest)} SAST`);
+  if (!preview.count) return;
+  if (!opts.confirm) { console.log(`\nDRY RUN — nothing deleted. Add --confirm to delete (you will be asked to type the contact id).`); return; }
+  const readline = await import("node:readline");
+  const typed = await new Promise((resolve) => { const rl = readline.createInterface({ input: process.stdin, output: process.stdout }); rl.question(`This cannot be undone. Type the contact id (${contactId}) to delete ${preview.count} message(s): `, (a) => { rl.close(); resolve(a.trim()); }); });
+  if (typed !== contactId) { console.log("Mismatch — aborted, nothing deleted."); process.exit(0); }
+  let resp;
+  try { resp = await http.post("messages", { action: "delete", contact_id: contactId, before: opts.before, sender_types: senderTypes, dry_run: false, confirm: true }); }
+  catch (e) { fail("Delete failed", e); }
+  if (opts.json) { console.log(JSON.stringify(resp, null, 2)); return; }
+  console.log(`✓ deleted ${resp.deleted} message(s). The audit row keeps their ids, types and times (flowiq audit --endpoint messages).`);
+  if (resp.error) console.error(`  ⚠ ${resp.error}`);
+}
+
+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).`);
 }