@flowapt/flowiq-cli 0.9.7 → 0.9.9

package/src/commands/agent-test.js

@@ -4,10 +4,10 @@
 // expect/expectNot checks client-side, and prints the transcript.
 //
 //   test resolve  <org_id> [--agent <id>]
-//   test send     <org_id> <message...> [--agent] [--clear] [--sender] [--image] [--timeout] [--json]
+//   test send     <org_id> <message...> [--agent] [--clear] [--sender] [--image] [--timeout] [--json] [--force]
 //   test scenario <org_id> <file.json> [--agent] [--no-clear-between] [--json] [--sender] [--timeout]
 //   test qa       <org_id> [--agent] ...           (bundled generic smoke pack)
-//   test clear    <org_id> [--agent]
+//   test clear    <org_id> [--agent] [--force]
 //   test stress   <org_id> [pack.json] [--agent] [--concurrency 6] [--timeout] [--out] [--contact]
 //   test cleanup  <org_id> [--agent] --confirm     (deletes stress contacts)
 //   test extract  <org_id> [--out]                 (rebuild transcripts from DB)
@@ -28,7 +28,9 @@ function requireOrg(orgId) {
   }
 }
 
-async function runTurn(orgId, { agent, message, image, clear, sender, timeout }) {
+// force: the server refuses send / clear on a test contact that had real
+// (non-web) inbound in the last 6 h, i.e. a live customer conversation.
+async function runTurn(orgId, { agent, message, image, clear, sender, timeout, force }) {
   return http.post("agent-test", {
     action: "send",
     organization_id: orgId,
@@ -38,11 +40,18 @@ async function runTurn(orgId, { agent, message, image, clear, sender, timeout })
     clear: !!clear,
     sender,
     timeout_ms: timeout,
+    force: !!force,
   });
 }
 
-async function clearConv(orgId, agent) {
-  return http.post("agent-test", { action: "clear", organization_id: orgId, agent_id: agent });
+async function clearConv(orgId, agent, force) {
+  return http.post("agent-test", { action: "clear", organization_id: orgId, agent_id: agent, force: !!force });
+}
+
+let warned = false;
+function printWarnings(r) {
+  if (warned) return;
+  for (const w of r?.warnings || []) { console.error(`⚠ ${w}`); warned = true; }
 }
 
 // A bare string is ONE needle, not a list of characters. Iterating a string
@@ -88,9 +97,11 @@ export async function send(orgId, messageParts, opts = {}) {
   if (!message) { console.error("usage: test send <org_id> <message...>"); process.exit(1); }
   let r;
   try {
-    r = await runTurn(orgId, { agent: opts.agent, message, image: opts.image, clear: opts.clear, sender: opts.sender, timeout: opts.timeout });
+    r = await runTurn(orgId, { agent: opts.agent, message, image: opts.image, clear: opts.clear, sender: opts.sender, timeout: opts.timeout, force: opts.force });
   } catch (e) { console.error(`Send failed: ${e.message}`); process.exit(1); }
   if (opts.json) { console.log(JSON.stringify(r, null, 2)); return; }
+  printWarnings(r);
+  if (opts.clear && r.previous_memory_cutoff !== undefined) console.log(`# cleared first; previous memory_cutoff: ${r.previous_memory_cutoff ?? "(none)"}`);
   console.log(`# org=${r.org?.name} agent=${r.agent?.name}${r.agent?.is_active ? " (active)" : " (override)"} contact=${r.contact?.id}`);
   printTurn({ title: "send", tq: "" }, 0, message, r, []);
 }
@@ -103,14 +114,15 @@ async function runPack(orgId, pack, opts) {
   for (let s = 0; s < scenarios.length; s++) {
     const sc = scenarios[s];
     if (clearBetween) {
-      try { await clearConv(orgId, opts.agent); } catch (e) { console.error(`  (clear failed: ${e.message})`); }
+      try { printWarnings(await clearConv(orgId, opts.agent, opts.force)); } catch (e) { console.error(`  (clear failed: ${e.message})`); }
     }
     const scResult = { id: sc.id, tq: sc.tq, title: sc.title, turns: [] };
     for (let t = 0; t < sc.turns.length; t++) {
       const turn = sc.turns[t];
       let r;
       try {
-        r = await runTurn(orgId, { agent: opts.agent, message: turn.text, sender: opts.sender, timeout: opts.timeout });
+        r = await runTurn(orgId, { agent: opts.agent, message: turn.text, sender: opts.sender, timeout: opts.timeout, force: opts.force });
+        printWarnings(r);
       } catch (e) {
         r = { status: "error", reply: null, tool_calls: [], raw: { error: e.message } };
       }
@@ -144,10 +156,12 @@ export async function qa(orgId, opts = {}) {
 export async function clear(orgId, opts = {}) {
   requireOrg(orgId);
   let resp;
-  try { resp = await clearConv(orgId, opts.agent); }
+  try { resp = await clearConv(orgId, opts.agent, opts.force); }
   catch (e) { console.error(`Clear failed: ${e.message}`); process.exit(1); }
+  printWarnings(resp);
   const tools = Number(resp.tools_cleared || 0);
   console.log(`Cleared web conversation for contact ${resp.contact_id} (history hidden via memory_cutoff; ${tools} remembered tool result(s) set aside in more_data.tool_usage_history_cleared; onboarding/disclaimer state NOT reset).`);
+  console.log(`Previous memory_cutoff: ${resp.previous_memory_cutoff ?? "(none)"}${resp.previous_memory_cutoff ? " (to undo, set contacts.memory_cutoff back to it)" : ""}`);
 }
 
 // ---------- phase 2: stress + extract ----------

package/src/commands/agent-updates.js

@@ -320,8 +320,8 @@ export async function resolve(updateId, opts = {}) {
     process.exit(1);
   }
   const status = opts.status || "resolved";
-  if (!["resolved", "declined"].includes(status)) {
-    console.error(`Error: --status must be resolved or declined (got "${status}").`);
+  if (!["resolved", "declined", "in_progress"].includes(status)) {
+    console.error(`Error: --status must be resolved, declined or in_progress (got "${status}").`);
     process.exit(1);
   }
   // R-3: a client-facing note is mandatory on resolve (--yes does NOT waive it).
@@ -332,7 +332,7 @@ export async function resolve(updateId, opts = {}) {
   }
 
   if (!opts.yes) {
-    console.log(`About to mark update ${updateId} as ${status.toUpperCase()}.`);
+    console.log(`About to mark update ${updateId} as ${status.toUpperCase()}${status === "in_progress" ? " (not closed: no resolution stamp)" : ""}.`);
     if (opts.note) console.log(`The client will read:  FlowIQ: ${opts.note}`);
     if (opts.internal) console.log(`Staff-only note:       ${opts.internal}`);
     const answer = await confirmPrompt("Type y to confirm: ");
@@ -363,6 +363,7 @@ export async function resolve(updateId, opts = {}) {
   console.log(`  title:     ${resp.title}`);
   console.log(`  was:       ${resp.previous_status}`);
   console.log(`  by:        ${resp.resolved_by_email ?? resp.resolved_by}`);
+  if (resp.status === "in_progress") console.log(`  still open: resolve it later with --note once the fix is proven.`);
   if (resp.superadmin_comment) console.log(`  client:    FlowIQ: ${resp.superadmin_comment}`);
   if (resp.internal_notes) console.log(`  internal:  ${resp.internal_notes}`);
   if (resp.already_resolved) console.log(`  ⚠ was already terminal (${resp.previous_status}) — note/status overwritten.`);

package/src/commands/audit.js

@@ -61,6 +61,7 @@ export async function list(orgId, opts = {}) {
       user: opts.user,
       since: opts.since,
       until: opts.until,
+      before: opts.before,
       limit: opts.limit,
     });
   } catch (e) {
@@ -80,7 +81,10 @@ export async function list(orgId, opts = {}) {
   }
 
   console.log("");
-  console.log(`${entries.length} entr${entries.length === 1 ? "y" : "ies"} (newest first)`);
+  const total = resp.total ?? entries.length;
+  console.log(resp.capped
+    ? `${entries.length} of ${total.toLocaleString()} matching entries (newest first; limit ${resp.limit}${resp.requested_limit > resp.limit ? `, the most one call returns — you asked for ${resp.requested_limit}` : ""})`
+    : `${entries.length} entr${entries.length === 1 ? "y" : "ies"} (newest first)`);
   console.log("");
   console.log(`  ${pad("WHEN (SAST)", 17)} ${pad("WHO", 24)} ${pad("WHAT", 26)} SUMMARY`);
   console.log(`  ${"-".repeat(17)} ${"-".repeat(24)} ${"-".repeat(26)} ${"-".repeat(40)}`);
@@ -101,6 +105,9 @@ export async function list(orgId, opts = {}) {
   for (const e of entries) {
     console.log(`    ${e.id}  ${e.endpoint} ${e.action}`);
   }
+  if (resp.capped && resp.next_before) {
+    console.log(`\n  ${(total - entries.length).toLocaleString()} older match(es) not shown: add --before ${resp.next_before}`);
+  }
   console.log("");
 }
 

package/src/commands/broadcast.js

@@ -1935,15 +1935,19 @@ export async function listRemote(orgId, opts = {}) {
       ...(opts.limit ? { limit: Number(opts.limit) } : {}),
       ...(opts.template ? { template: opts.template } : {}),
       ...(opts.since ? { since: opts.since } : {}),
+      ...(opts.minRecipients ? { min_recipients: Number(opts.minRecipients) } : {}),
     });
   } catch (e) { console.error(`Listing failed: ${e.message}`); if (e.body?.error) console.error(`  ${e.body.error}`); process.exit(1); }
   if (opts.json) { console.log(JSON.stringify(resp, null, 2)); return; }
   const rows = resp.broadcasts || [];
-  if (!rows.length) { console.log(`No broadcasts found for ${resp.organization_name}${opts.template || opts.since ? " matching the filters" : ""}.`); return; }
+  if (!rows.length) { console.log(`No broadcasts found for ${resp.organization_name}${opts.template || opts.since || opts.minRecipients ? " matching the filters" : ""}.`); return; }
   // Full ids one per row, deliberately — an id you can't paste into `bc status`
   // is useless (the same lesson the audit listing learned).
   const sast = (iso) => { try { return new Date(iso).toLocaleString("sv-SE", { timeZone: "Africa/Johannesburg" }).slice(0, 16); } catch { return iso; } };
-  console.log(`Broadcasts — ${resp.organization_name} (${rows.length} shown, newest first; times SAST)`);
+  const shown = resp.capped
+    ? `${rows.length} of ${resp.total.toLocaleString()} shown`
+    : `${rows.length} shown`;
+  console.log(`Broadcasts — ${resp.organization_name} (${shown}${resp.min_recipients ? `, ${resp.min_recipients}+ recipients` : ""}, newest first; times SAST)`);
   for (const b of rows) {
     console.log("");
     console.log(`  ${b.id}`);
@@ -1951,6 +1955,9 @@ export async function listRemote(orgId, opts = {}) {
     console.log(`    status ${b.status ?? "?"} · ${b.total_recipients ?? "?"} recipient(s)`);
   }
   console.log("");
+  if (resp.capped) {
+    console.log(`⚠ ${(resp.total - rows.length).toLocaleString()} older broadcast(s) not shown (limit ${resp.limit}). Narrow with --since, --template${resp.min_recipients ? "" : " or --min-recipients 2 (hides one-recipient sends like welcomes and cart reminders)"}.`);
+  }
   console.log(`Delivery detail: flowiq bc status ${orgId} <broadcast_id> [--failures]`);
 }
 
@@ -1984,6 +1991,15 @@ export async function status(orgId, broadcastId, opts = {}) {
   if (b.total_recipients) {
     console.log(`    ${((accepted / b.total_recipients) * 100).toFixed(1)}% of ${b.total_recipients} recipients accepted${d.linked < b.total_recipients ? "  (still sending?)" : ""}`);
   }
+  const p = resp.payload;
+  if (p && (Object.keys(p.body_parameters || {}).length || Object.keys(p.button_parameters || {}).length || Object.keys(p.header_parameters || {}).length)) {
+    console.log(`  sent with:`);
+    const slot = (k) => String(k).replace(/^param/, "{{") + (String(k).startsWith("param") ? "}}" : "");
+    for (const [k, v] of Object.entries(p.header_parameters || {})) console.log(`    header ${slot(k)}  ${String(v).replace(/\s+/g, " ")}`);
+    for (const [k, v] of Object.entries(p.body_parameters || {})) console.log(`    body   ${slot(k)}  ${String(v).replace(/\s+/g, " ")}`);
+    for (const [k, v] of Object.entries(p.button_parameters || {})) console.log(`    button ${slot(k)}  ${v}`);
+    for (const l of p.links || []) console.log(`    link   ${l.short_code} → ${l.destination}  (${l.clicks} click${l.clicks === 1 ? "" : "s"})`);
+  }
   if (resp.reply_routing) {
     const rr = resp.reply_routing;
     console.log(`  replies →   ${describeRouting(rr)}${rr.enabled === false ? "  (switched OFF)" : ""}`);

package/src/commands/doctor.js

@@ -101,10 +101,19 @@ export async function doctor(opts = {}) {
       }
     } catch (e) {
       lines.push(`  ${BAD} auth       ${e.message.split("\n")[0]}`);
-      problems.push({
-        what: "the API rejected this key",
-        fix: e.status === 401 || e.status === 403 ? "flowiq auth login" : "check api_url / network, then retry",
-      });
+      if (e.code === "EVERCELCHALLENGE") {
+        problems.push({
+          what: "Vercel's bot protection is challenging this network; the key was never checked",
+          fix: "wait a few minutes or switch network (hotspot), then flowiq doctor again; do NOT re-login",
+        });
+      } else {
+        // Only a JSON 401/403 from our API means the key itself was refused.
+        const keyRefused = (e.status === 401 || e.status === 403) && e.code !== "ENONJSON";
+        problems.push({
+          what: keyRefused ? "the API rejected this key" : "the API could not be reached properly",
+          fix: keyRefused ? "flowiq auth login" : "check api_url / network, then retry",
+        });
+      }
     }
   }
 

package/src/commands/gaps.js

@@ -244,7 +244,7 @@ export async function show(ref, opts = {}) {
     }
   }
   console.log(`\nSame problem? flowiq gaps hit ${r.number} --note "what you were doing"`);
-  console.log(`Maintainers (${(resp.editors || []).join(", ")}): flowiq gaps status ${r.number} --to done --version <x.y.z> --note "…"`);
+  console.log(`Maintainers (${(resp.editors || []).join(", ")}): flowiq gaps status ${r.number} --to done --fixed-in <x.y.z> --note "…"`);
 }
 
 // ── hit ─────────────────────────────────────────────────────────────────────
@@ -324,7 +324,7 @@ export async function status(ref, opts = {}) {
       ref: r0,
       status: to,
       note: opts.note ?? null,
-      version: opts.version ?? null,
+      version: opts.fixedIn ?? null,
       duplicate_of: dupRef,
       notify: opts.notify !== false,
     });

package/src/commands/keywords.js

@@ -37,6 +37,32 @@ async function resolvePushPath(identifier) {
   throw new Error(`File not found. Tried:\n  ${candidates.join("\n  ")}`);
 }
 
+const sastDay = (iso) => {
+  try { return new Date(iso).toLocaleString("sv-SE", { timeZone: "Africa/Johannesburg" }).slice(0, 16); }
+  catch { return String(iso).slice(0, 16); }
+};
+
+// The keyword-scheduler cron (every 30 min) flips `active` on at start_date and
+// off at end_date; the runtime itself reads `active` only. So an ACTIVE row with
+// a future start is answering already, and an active row past its end has not
+// been switched off yet.
+export function scheduleLabel(k, now = Date.now()) {
+  const start = k.start_date ? Date.parse(k.start_date) : null;
+  const end = k.end_date ? Date.parse(k.end_date) : null;
+  const parts = [];
+  if (start && start > now) {
+    parts.push(k.active === false
+      ? ` · starts ${sastDay(k.start_date)} SAST`
+      : ` · ⚠ LIVE BEFORE ITS START (${sastDay(k.start_date)} SAST): active, so it answers now`);
+  }
+  if (end) {
+    parts.push(end <= now && k.active !== false
+      ? ` · ⚠ PAST ITS END (${sastDay(k.end_date)} SAST) but still active`
+      : ` · ends ${sastDay(k.end_date)}${end > now ? " SAST" : ""}`);
+  }
+  return parts.join("");
+}
+
 export async function pull(orgId) {
   if (!UUID_RE.test(orgId)) {
     console.error(`Error: "${orgId}" is not a valid organization UUID.`);
@@ -59,9 +85,24 @@ export async function pull(orgId) {
   console.log(`${overwriting ? "Overwrote" : "Wrote"} ${filePath}`);
   console.log(`  org:       ${resp.organization_name} (${resp.organization_id})`);
   console.log(`  keywords:  ${resp.keyword_count}`);
-  for (const k of resp.keywords || []) {
+  // Active rows first, in the order the runtime tries them (first match wins),
+  // then the inactive ones.
+  const all = resp.keywords || [];
+  const order = resp.runtime_order || [];
+  const byId = new Map(all.map((k) => [k.id, k]));
+  const listed = [
+    ...order.map((id) => byId.get(id)).filter(Boolean),
+    ...all.filter((k) => !order.includes(k.id)),
+  ];
+  if (order.length) console.log(`  (active rows in runtime order: the first matching row answers)`);
+  for (const k of listed) {
     const acts = (k.keyword_actions || []).length;
-    console.log(`    ${String(k.type).padEnd(28)} [${(k.keywords || []).join(", ")}] · ${acts} action(s)${k.active === false ? " · INACTIVE" : ""}${k.end_date ? ` · ends ${k.end_date.slice(0, 10)}` : ""}`);
+    console.log(`    ${String(k.type).padEnd(28)} [${(k.keywords || []).join(", ")}] · ${acts} action(s)${k.active === false ? " · INACTIVE" : ""}${scheduleLabel(k)}`);
+  }
+  for (const c of resp.collisions || []) {
+    console.log("");
+    console.log(`  ⚠ TRIGGER COLLISION: ${c.triggers.map((t) => `"${t}"`).join(", ")} matches both "${c.winner.type}" and "${c.shadowed.type}".`);
+    console.log(`    ${c.note}.`);
   }
   if (resp.has_attribute_actions) {
     console.log("");

package/src/commands/links.js

@@ -115,6 +115,7 @@ export async function shorten(orgId, opts = {}) {
       content,
       domain: opts.domain,
       dry_run: dryRun,
+      confirm_new_campaign: !!opts.newCampaign,
     });
   } catch (e) {
     console.error(`Shorten failed: ${e.message}`);
@@ -128,6 +129,13 @@ export async function shorten(orgId, opts = {}) {
     : "no UTM tags (plain short link)";
   console.log(`${resp.organization_name} · ${resp.domain}`);
   console.log(`${utm}\n`);
+  if (resp.campaign_conflicts?.length) {
+    const c = resp.campaign_conflicts[0];
+    console.log(`⚠ CAMPAIGN FORK: this org already runs ${resp.campaign_conflicts.map((x) => `"${x.campaign}" (${x.links} link${x.links === 1 ? "" : "s"})`).join(", ")},`);
+    console.log(`  the same campaign as "${resp.utm?.campaign}" spelled differently. The Broadcasts tab would show two rows.`);
+    console.log(`  Reuse it: --campaign ${c.campaign} --raw-campaign    or confirm a separate campaign: --new-campaign`);
+    console.log("");
+  }
 
   for (const r of resp.results) {
     const label = {

package/src/commands/prompts.js

@@ -5,6 +5,7 @@
 
 import fs from "node:fs/promises";
 import path from "node:path";
+import { randomUUID } from "node:crypto";
 import { http } from "../http.js";
 import { fmtSast } from "./audit.js";
 
@@ -54,15 +55,16 @@ export async function pull(orgId, opts = {}) {
     process.exit(1);
   }
 
-  await fs.mkdir(PROMPTS_DIR, { recursive: true });
   // Non-active agents get an agent-suffixed filename so pulling multiple agents
   // from the same org doesn't clobber each other's working copy. The active
-  // agent keeps the plain <org>.json name (backwards-compatible).
+  // agent keeps the plain <org>.json name (backwards-compatible). --out writes
+  // anywhere else (a scratch copy that leaves the working file alone).
   const orgSlug = slugify(resp.organization_name, resp.organization_id);
   const slug = resp.is_active === false
     ? `${orgSlug}-${slugify(resp.agent_name, resp.agent_id.slice(0, 8))}`
     : orgSlug;
-  const filePath = path.join(PROMPTS_DIR, `${slug}.json`);
+  const filePath = opts.out ? path.resolve(opts.out) : path.join(PROMPTS_DIR, `${slug}.json`);
+  await fs.mkdir(path.dirname(filePath), { recursive: true });
   const overwriting = await fileExists(filePath);
   await fs.writeFile(filePath, JSON.stringify(resp, null, 2) + "\n", "utf8");
 
@@ -82,6 +84,18 @@ export async function pull(orgId, opts = {}) {
   }
 }
 
+/** Give every section without an id a fresh uuid. Returns the titles it touched. */
+export function mintSectionIds(sections) {
+  const touched = [];
+  for (const sec of sections) {
+    if (sec && typeof sec === "object" && (typeof sec.id !== "string" || !sec.id.trim())) {
+      sec.id = randomUUID();
+      touched.push(sec.title || "(untitled)");
+    }
+  }
+  return touched;
+}
+
 export async function push(identifier) {
   let filePath;
   try {
@@ -107,6 +121,14 @@ export async function push(identifier) {
     process.exit(1);
   }
 
+  // A section added by hand has no id yet. Mint one and write it back to the
+  // file BEFORE pushing, so a later pull or push keeps the same id.
+  const minted = mintSectionIds(data.prompt_sections);
+  if (minted.length) {
+    await fs.writeFile(filePath, JSON.stringify(data, null, 2) + "\n", "utf8");
+    console.log(`Added an id to ${minted.length} new section(s) in ${filePath}: ${minted.map((t) => `"${t}"`).join(", ")}`);
+  }
+
   let resp;
   try {
     resp = await http.post("prompts", {

package/src/commands/store-api.js

@@ -265,6 +265,45 @@ async function rawGet(orgId, path, query, { label } = {}) {
   return resp.data;
 }
 
+// Shopify's own product search (title, SKU, vendor, tags…), so a partial title
+// on a 3,594-product catalogue is found without scanning pages. Anything
+// Shopify's search syntax takes works here too: "sku:75461", "handle:foo".
+const STOCK_SEARCH_GQL = `query StockSearch($q: String!) {
+  products(first: 50, query: $q) {
+    edges { node {
+      legacyResourceId title status
+      variants(first: 100) { edges { node {
+        legacyResourceId title sku price inventoryPolicy inventoryQuantity
+        inventoryItem { legacyResourceId }
+      } } }
+    } }
+  }
+}`;
+
+async function searchProducts(orgId, search) {
+  console.error(`  $ flowiq shopify gql <org> --query '${STOCK_SEARCH_GQL.replace(/\s+/g, " ")}' --var q=${JSON.stringify(search)}    # Shopify product search`);
+  const resp = await http.post("store-api", {
+    platform: "shopify", organization_id: orgId, mode: "graphql",
+    graphql: { query: STOCK_SEARCH_GQL, variables: { q: search } },
+  });
+  if (resp.graphql_errors?.length) throw new Error(`Shopify search failed: ${resp.graphql_errors.map((e) => e.message).join("; ")}`);
+  // Map to the REST shape the rest of the recipe reads.
+  return (resp.data?.products?.edges || []).map(({ node: p }) => ({
+    id: Number(p.legacyResourceId),
+    title: p.title,
+    status: String(p.status || "").toLowerCase(),
+    variants: (p.variants?.edges || []).map(({ node: v }) => ({
+      id: Number(v.legacyResourceId),
+      title: v.title,
+      sku: v.sku,
+      price: v.price,
+      inventory_policy: String(v.inventoryPolicy || "").toLowerCase(),
+      inventory_quantity: v.inventoryQuantity,
+      inventory_item_id: v.inventoryItem?.legacyResourceId ? Number(v.inventoryItem.legacyResourceId) : null,
+    })),
+  }));
+}
+
 export async function shopifyStock(orgId, search, opts = {}) {
   requireOrg(orgId);
   if (!search || !String(search).trim()) {
@@ -278,17 +317,22 @@ export async function shopifyStock(orgId, search, opts = {}) {
     const p = await rawGet(orgId, "products.json", { title: search, limit: 50 }, { label: "find the product" });
     products = (p?.products || []).filter((x) =>
       String(x.title).toLowerCase().includes(String(search).toLowerCase()));
+    let fromSearch = false;
     if (!products.length) {
-      const all = await rawGet(orgId, "products.json", { limit: 250, fields: "id,title,variants,status" },
-        { label: "no title match — scanning the catalogue" });
-      products = (all?.products || []).filter((x) =>
-        String(x.title).toLowerCase().includes(String(search).toLowerCase()));
+      // No exact title: ask Shopify's search, then keep the titles holding every
+      // word of the search (or, when none do, what Shopify ranked closest).
+      const found = await searchProducts(orgId, String(search));
+      const words = String(search).toLowerCase().split(/\s+/).filter((w) => w && !w.includes(":"));
+      const strict = found.filter((x) => words.every((w) => String(x.title).toLowerCase().includes(w)));
+      products = strict.length ? strict : found;
+      fromSearch = products.length > 0 && !strict.length && words.length > 0;
     }
     if (!products.length) {
-      console.error(`\nNothing matched "${search}". This searches product TITLES only — ` +
-        `the passthrough can query anything else Shopify exposes.`);
+      console.error(`\nShopify's product search found nothing for "${search}" (it searches the whole catalogue: ` +
+        `title, SKU, vendor, tags). Try fewer words, or "sku:<sku>" / "handle:<handle>".`);
       process.exit(1);
     }
+    if (fromSearch) console.error(`  (no title holds every word of "${search}"; showing Shopify's closest matches)`);
     const itemIds = products.flatMap((x) => (x.variants || []).map((v) => v.inventory_item_id)).filter(Boolean);
     // 2. inventory_item_id → per-location levels   3. location_id → names
     levels = itemIds.length
@@ -335,6 +379,9 @@ export async function shopifyStock(orgId, search, opts = {}) {
   }
   console.error("");
   console.log(renderTable(rows) ?? "(no variants)");
+  if (products.flatMap((x) => x.variants || []).length > 50) {
+    console.error(`\n⚠ per-location levels cover the first 50 variants only; narrow the search for the rest.`);
+  }
   console.error(`\n${products.length} product(s) · ${rows.length} variant(s). ` +
     `"not tracked" means Shopify holds no inventory record at that location — it is not a zero.`);
 }

package/src/commands/templates.js

@@ -91,6 +91,10 @@ export async function create(orgId, opts = {}) {
   } catch (e) {
     console.error(`Create failed: ${e.message}`);
     if (e.body) console.error(JSON.stringify(e.body, null, 2));
+    if (e.status === 504 || /TIMEOUT/i.test(e.message)) {
+      console.error(`\n⚠ The template may already be created at Meta (the upload can outlive the proxy). Do NOT retry yet; check first:`);
+      console.error(`  flowiq templates status ${organizationId} --live --name ${templateRequest.name}`);
+    }
     process.exit(1);
   }
 
@@ -103,6 +107,8 @@ export async function status(orgId, opts = {}) {
     console.error(`Error: "${orgId}" is not a valid organization UUID.`);
     process.exit(1);
   }
+  if (opts.watch && !opts.live) opts.live = true;
+  if (opts.live) return liveStatus(orgId, opts);
   let resp;
   try {
     resp = await http.get("meta-templates", { organization_id: orgId, name: opts.name });
@@ -112,18 +118,55 @@ export async function status(orgId, opts = {}) {
   }
   const rows = resp.templates || [];
   if (!rows.length) {
-    console.log(opts.name ? `(no templates matching "${opts.name}")` : "(no templates on record for this org)");
+    // An empty FlowIQ table is not "no templates": templates made in Meta's
+    // own tools, or on a swapped WABA, exist only at Meta (Health Matrix, 22 Sep).
+    console.log(opts.name
+      ? `No template matching "${opts.name}" is recorded in FlowIQ. Meta may still hold one: flowiq templates status ${orgId} --live --name ${opts.name}`
+      : `No templates are recorded in FlowIQ for this org. Meta may still hold some: flowiq templates status ${orgId} --live (or templates pull ${orgId}).`);
     return;
   }
-  console.log(`${rows.length} template row${rows.length === 1 ? "" : "s"}${opts.name ? ` matching "${opts.name}"` : ""}:`);
+  console.log(`${rows.length} template row${rows.length === 1 ? "" : "s"}${opts.name ? ` matching "${opts.name}"` : ""} recorded in FlowIQ:`);
   for (const t of rows) {
     const name = t.template_name || t.name || "(unnamed)";
-    const st = t.status || "(no status)";
+    // meta_status is what Meta's status webhook last reported; `status` is often
+    // left at its submit-time value.
+    const st = t.meta_status || t.status || "(no status)";
     const cat = t.category ? ` [${t.category}]` : "";
     console.log(`  ${name.padEnd(40)} ${String(st).padEnd(16)}${cat}`);
   }
-  console.log("\nNote: status is captured at submit time (older rows may be null). For the live");
-  console.log("Meta-side status + rejection reasons, run `templates pull <org_id>`.");
+  console.log(`\nThis is FlowIQ's record (Meta's webhook keeps it current). Straight from Meta, with rejection reasons:`);
+  console.log(`  flowiq templates status ${orgId} --live${opts.name ? ` --name ${opts.name}` : ""} [--watch]`);
+}
+
+const TERMINAL = new Set(["APPROVED", "REJECTED", "DISABLED", "PAUSED", "DELETED", "LIMIT_EXCEEDED"]);
+
+async function liveStatus(orgId, opts) {
+  const intervalMs = 15000, maxMs = 15 * 60 * 1000, started = Date.now();
+  for (;;) {
+    let resp;
+    try {
+      resp = await http.get("templates", { organization_id: orgId, name: opts.name });
+    } catch (e) {
+      console.error(`Live status failed: ${e.message}`);
+      process.exit(1);
+    }
+    const rows = resp.templates || [];
+    const stamp = new Date().toLocaleTimeString("en-GB", { timeZone: "Africa/Johannesburg" });
+    if (!rows.length) {
+      console.log(`${stamp}  Meta holds no template${opts.name ? ` matching "${opts.name}"` : "s"} on ${resp.organization_name}'s WABA.`);
+    } else {
+      console.log(`${stamp}  ${rows.length} template${rows.length === 1 ? "" : "s"} at Meta (${resp.organization_name})${opts.name ? ` matching "${opts.name}"` : ""}:`);
+      for (const t of rows) {
+        const moved = t.previous_category && t.previous_category !== t.category ? ` (was ${t.previous_category})` : "";
+        const why = t.rejected_reason && t.rejected_reason !== "NONE" ? `  reason: ${t.rejected_reason}` : "";
+        console.log(`  ${String(t.name).padEnd(40)} ${String(t.status).padEnd(16)} [${t.category}${moved}] ${t.language}${t.parameter_format ? ` · ${t.parameter_format}` : ""}${why}`);
+      }
+    }
+    const pending = rows.filter((t) => !TERMINAL.has(String(t.status)));
+    if (!opts.watch || (rows.length && !pending.length)) return;
+    if (Date.now() - started > maxMs) { console.log(`Still not decided after 15 min; stopped watching.`); return; }
+    await new Promise((r) => setTimeout(r, intervalMs));
+  }
 }
 
 export async function list() {

package/src/http.js

@@ -70,7 +70,7 @@ export function isBelowServerMinimum() {
  * serialised — and always name the HTTP status, since a 504 tells you "retry or
  * narrow it" while a 400 never will.
  */
-export function describeError(parsed, method, endpoint, status) {
+export function describeError(parsed, method, endpoint, status, { json = true } = {}) {
   const pick = (v) => (typeof v === "string" && v.trim() ? v.trim() : null);
   const nested = (v) => {
     if (!v || typeof v !== "object") return null;
@@ -95,12 +95,27 @@ export function describeError(parsed, method, endpoint, status) {
   if (!detail) return where;
 
   // A timeout is transient and the remedy is specific, so say so rather than
-  // leaving the reader to work out whether they hit a hard limit.
-  const timedOut = status === 504 || /TIMEOUT|timed out/i.test(detail);
-  return timedOut
-    ? `${detail} [${where}] — this is a TIMEOUT, not a limit: retry, or narrow the request ` +
-      `(fewer pages via --max-pages, a smaller --q limit, or a tighter filter).`
-    : `${detail} [${where}]`;
+  // leaving the reader to work out whether they hit a hard limit. Only a JSON
+  // body is scanned for the word: an HTML page (a Vercel challenge) carries
+  // "timeout" in its inline script and is not one.
+  const timedOut = status === 504 || (json && /TIMEOUT|timed out/i.test(detail));
+  if (!timedOut) return `${detail} [${where}]`;
+  // A write can finish on the server after the proxy gave up, so "retry" is the
+  // wrong first move there (a template created twice, a send fired twice).
+  if (method !== "GET" && endpoint !== "store-api") {
+    return `${detail} [${where}] — this is a TIMEOUT: the server may still have finished the write. ` +
+      `Check the result (the command's list / status / pull verb, or flowiq audit) before retrying.`;
+  }
+  return `${detail} [${where}] — this is a TIMEOUT, not a limit: retry, or narrow the request ` +
+    `(fewer pages via --max-pages, a smaller --q limit, or a tighter filter).`;
+}
+
+/** Vercel's bot protection answers with an HTML challenge page (403/429),
+ *  before the request ever reaches our API. It is about this network, not the key. */
+export function isVercelChallenge(status, headers, text) {
+  const mitigated = headers?.get?.("x-vercel-mitigated") || "";
+  if (/challenge/i.test(mitigated)) return true;
+  return (status === 403 || status === 429) && /Vercel Security Checkpoint|vercel-challenge|_vercel\/challenge/i.test(text || "");
 }
 
 async function call(method, endpoint, { query, body } = {}) {
@@ -138,8 +153,19 @@ async function call(method, endpoint, { query, body } = {}) {
   const text = await resp.text();
   let parsed, isJson = true;
   try { parsed = text ? JSON.parse(text) : {}; } catch { parsed = { _raw: text }; isJson = false; }
+  if (!resp.ok && isVercelChallenge(resp.status, resp.headers, text)) {
+    const err = new Error(
+      `Vercel is challenging this network (bot protection) [${method} ${endpoint} → HTTP ${resp.status}]. ` +
+      `This is not your key and the request never reached the API: wait a few minutes, or try another ` +
+      `network (a phone hotspot), then retry.`
+    );
+    err.status = resp.status;
+    err.code = "EVERCELCHALLENGE";
+    err.body = parsed;
+    throw err;
+  }
   if (!resp.ok) {
-    const err = new Error(describeError(parsed, method, endpoint, resp.status));
+    const err = new Error(describeError(parsed, method, endpoint, resp.status, { json: isJson }));
     err.status = resp.status;
     err.body = parsed;
     throw err;