@flowapt/flowiq-cli 0.3.8 → 0.4.0

package/README.md

@@ -186,7 +186,7 @@ flowiq ct list
 - **Warnings (non-blocking):** unknown keys (likely typos the runtime would silently ignore) and unknown `{{placeholders}}` (they will NOT be substituted at runtime — known: `organization_id`, `contact_id`, `agent_id`, `contact_whatsapp_id`, `contact_full_name`, `supabase_anon_key`, `openai_api_key`, …).
 - `--agent` + filenames behave like `prompts`/`knowledge`; the file carries `agent_id`, so `push` targets the agent it was pulled from.
 
-### Broadcast — `flowiq broadcast map|preview|send|resume|status|retry|list` (alias `bc`)
+### Broadcast — `flowiq broadcast map|preview|send|resume|list-remote|status|retry|list` (alias `bc`)
 
 Send an **APPROVED** WhatsApp template to every row of a CSV, filling the
 template's variables **per row** from the CSV's own columns. The
@@ -220,13 +220,35 @@ flowiq bc resume <org_id> --campaign july-referrals --commit [--retry-failed]
   `/api/send-template` as `headerMedia`, the same field the dashboard uses. A
   media-header template with no resolvable image is refused (pass
   `--header-media`).
-- **`status <org> <broadcastId>` (v0.3.5)**: live delivery counts for a broadcast
-  by its id — `read` / `delivered` / `sent` / `failed` (+ % reached) from
-  `helpdesk_messages`. Built for the `--python` fire-and-forget engine (which
-  returns a `broadcastId` but has no CLI status log), but works for any broadcast
-  id (dashboard sends included). **`--failures` (v0.3.7)** additionally lists each
-  failed recipient + the Meta error reason (`error_code` / `error_title`) with a
-  by-reason rollup — makes a fire-and-forget send fully auditable.
+- **`list-remote <org>` (v0.3.9)**: list the org's broadcasts **newest-first** with
+  the **full broadcastId** per row + template, status, recipient count and SAST
+  created time — the discovery step `status` / `retry` need (previously the id
+  existed only in the send output or the DB). `--limit <n>` (default 25, max 200),
+  `--template <substr>` (case-insensitive contains), `--since <date>`, `--json`.
+  Read-only. NOTE: plain `bc list` (no org) still lists your **local campaign
+  files** — the remote verb is named after `pinboard list-remote`.
+- **`status <org> <broadcastId>` (v0.3.5)**: live delivery **funnel** for a
+  broadcast by its id — `accepted` → `delivered` → `read`, plus `pending` and
+  `failed`, with percentages, from `helpdesk_messages`. Built for the `--python`
+  fire-and-forget engine (which returns a `broadcastId` but has no CLI status
+  log), but works for any broadcast id (dashboard sends included).
+  **`--failures` (v0.3.7)** additionally lists each failed recipient + the Meta
+  error reason (`error_code` / `error_title`) with a by-reason rollup — makes a
+  fire-and-forget send fully auditable.
+  - **Delivery counting fixed 3 Aug 2026.** It previously counted
+    `message_status='delivered'`, a value present on **6 rows in the whole
+    table**, so *delivered always displayed 0* (the reached TOTAL was right; the
+    breakdown was not). Delivery now comes from the boolean receipt columns
+    (`delivered_receipt_received` / `read_receipt_received`) that the webhooks
+    flip — the same signal as the inbox ticks. **Booleans, not the
+    `delivered_at`/`read_at` timestamps**: those were added recently and are only
+    partially backfilled (2025: 323,325 delivered by boolean, **0** by
+    timestamp), and no row ever carries a timestamp without the boolean.
+  - The stages are **cumulative, not disjoint** (`accepted ⊇ delivered ⊇ read`) —
+    don't add them up. `delivered` counts read-without-a-delivered-receipt too
+    (~65k such rows exist: WhatsApp can skip straight to the read receipt).
+  - **`read` is a FLOOR, never exact** — recipients can disable read receipts in
+    WhatsApp. The JSON carries a `read_caveat` string saying so.
 - **`retry <org> <broadcastId>` (v0.3.7)**: re-send a broadcast to **only its
   failed recipients** — reconstructs the send from the `broadcasts` row (template +
   params + header) and re-fires via the python engine, creating a NEW broadcast.
@@ -416,9 +438,10 @@ flowiq kw push <slug> --prune            # ALSO deletes DB keywords missing from
   collapses to 1 at runtime — rejected).
 - `field:"attributes"` actions are warned (full jsonb replace; constant
   values only) but applied — this CLI is their only safe editing surface.
-- **Action types accepted** (all seven the runtime implements):
+- **Action types accepted** (all nine the runtime implements):
   `send_message` · `update_contact_field` · `add_contact_tag` ·
-  `remove_contact_tag` · `set_agent` · `delay` · `combined`.
+  `remove_contact_tag` · `set_agent` · `delay` · `combined` ·
+  `update_ticket_status` · `renotify_ticket`.
   Per-type rules: tag actions need a non-empty `tags[]` (or a single `tag`
   string) or the runtime writes no tag at all; `set_agent.agent_id` must be
   an agent UUID, or `null`/`""` to CLEAR the contact's binding (warned, since
@@ -429,9 +452,41 @@ flowiq kw push <slug> --prune            # ALSO deletes DB keywords missing from
   *(Before v0.3.9 only the first two + `combined` were accepted, so a
   zero-edit pull→push failed for any org using tag / set_agent / delay
   actions.)*
+- **Ticket actions** (added 30 Jul 2026, for escalation follow-up buttons):
+  `update_ticket_status` changes the CONTACT's open/in_progress tickets —
+  `{ "type": "update_ticket_status", "status": "resolved", "scope": "all_open" }`.
+  `status` ∈ `open`/`in_progress`/`resolved`/`closed` (default `resolved`);
+  `scope` ∈ `all_open` (default) / `latest_open`. Appends the same
+  `data.status_history[]` audit entries as the agent's `manage_tickets` tool
+  (`by:"keyword"`). Canonical use: the follow-up template's **"Query solved"**
+  button resolving the escalation ticket. `renotify_ticket` re-fires the
+  human-needed team notifications for the contact's latest ticket via
+  ticket-tool `mode:"renotify"` (60s server-side rate limit; a resolved/closed
+  ticket is reopened first) — canonical use: the **"I still need help"**
+  button. Both send the action's `text` (if any) after the ticket work.
 - `action_config.link_preview: false` disables WhatsApp's link-preview card
   on that action's text send (absent/`true` = preview on, the default).
   Passed through verbatim; also toggleable per action in the dashboard.
+- **`action_config.when` — conditional actions.** An action only runs if its
+  condition passes, checked against the **live contact row** when the keyword
+  fires (no tag to maintain, nothing goes stale):
+  ```json
+  { "type": "send_message", "when": { "field": "email", "op": "is_not_empty" } }
+  ```
+  `field` ∈ `email` / `phone_number` / `full_name` (allowlist; `city` was removed 03 Aug 2026 — contacts has no such column, so a city condition could never evaluate).
+  `op` ∈ `is_empty` / `is_not_empty` / `equals` / `contains` — the last two
+  need a `value` and are case-insensitive. Rejected on push otherwise
+  (V-21/V-22), because the runtime SKIPS an action it can't evaluate.
+  Typical pattern — one keyword, two possible replies, tag either way:
+  ```
+  action 1  send_message   when email is_not_empty
+            "I've got your email as {{contact.email}} — reply YES to use it."
+  action 2  send_message   when email is_empty
+            "Pop in your email address to finish."
+  action 3  add_contact_tag   (no when → always runs)
+  ```
+  There is **no dashboard field** for conditions yet — the UI preserves them
+  on save but can't edit them, so treat `flowiq kw` as their owner.
 - Scheduled keywords: the keyword-scheduler cron reconciles `active` from
   `start_date`/`end_date` within ~30 min of your push.
 
@@ -712,7 +767,7 @@ flowiq agent config <organization_id> --test-contact-number 27000000001 --test-c
 Settable: `settings.use_settings_prompt`, `settings.model`, agent `--rename`,
 the tool-flag columns (`woo_order_build`, `woo_tip_field`, `woo_order_note_field`,
 `view_cart_tool`, `restock_tool`, `block_tool_status`, `postal_code_tool_status`,
-`shopify_products_web_chat`), `discount.enabled`, and the `flowiq test` contact
+`shopify_products_web_chat`, `ticket_tool_status`), `discount.enabled`, and the `flowiq test` contact
 (`settings.test_contact_number` / `settings.test_contact_name`). Anything else is
 rejected; every change is reported before → after.
 

package/TEAM-GUIDE.md

@@ -78,6 +78,8 @@ When you see it, run `npm i -g @flowapt/flowiq-cli` — a stale version also mea
 | Edit the custom tools (API-call tools) | `flowiq ct pull <org_id>` → edit `tools[]` → `flowiq ct push <slug> --dry-run` → `flowiq ct push <slug>` |
 | Turn one custom tool on/off | `flowiq ct enable\|disable <org_id> <tool_name>` |
 | Edit keyword auto-replies (incl. competition entry keywords, add/remove-tag, set-agent and delay actions) | `flowiq kw pull <org_id>` → edit → `flowiq kw push <slug> --dry-run` → `flowiq kw push <slug>` |
+| Send a **different auto-reply depending on the contact** (e.g. "we already have your email" vs "send us your email") | add `"when": {"field":"email","op":"is_not_empty"}` to one action and `is_empty` to the other — see *Keywords* in `flowiq guide --reference`. CLI-only, no dashboard field yet |
+| Make a follow-up button **close the customer's ticket** ("Query solved") or **re-alert the team** ("I still need help") | keyword action `{"type":"update_ticket_status","status":"resolved"}` / `{"type":"renotify_ticket"}` — see *Keywords* in `flowiq guide --reference`. CLI-only, no dashboard field yet |
 | See an org's agents / create one | `flowiq agent list <org_id>` / `flowiq agent create <org_id> --name "…"` |
 | Change agent model / tool flags | `flowiq agent config <org_id> --model … --tool view_cart_tool=true` |
 | Talk to the live agent safely (no real WhatsApp ever sent) | `flowiq test send <org_id> "hi, do you sell X?"` |
@@ -93,7 +95,8 @@ When you see it, run `npm i -g @flowapt/flowiq-cli` — a stale version also mea
 | Send to one batch tag | `flowiq bc send <org_id> --tag <batch-tag> --template … --body param1="Hi {{first_name}}" --commit` (per-contact tokens: the 6 contact fields + `{{attributes.<key>}}`) |
 | Send a broadcast whose template has an IMAGE header | Same as above — the image is automatic (the template's own header image). Override with `--header-media <public-image-url>` if needed. |
 | Send via the SAME engine as the dashboard's "Python" toggle | add `--python` to a `bc send --tag …` (fire-and-forget; python resolves the tag + sends + tracks; no CLI resume for this engine). **Any tag send over 10 recipients uses python automatically.** |
-| Check how a broadcast is landing (read/delivered/sent/failed) | `flowiq bc status <org_id> <broadcastId>` (the `broadcastId` a `--python` send prints) |
+| Find a broadcast's id (don't have the `broadcastId`?) | `flowiq bc list-remote <org_id>` — the org's broadcasts newest-first with full ids (`--template <substr>` / `--since <date>` / `--limit <n>` to narrow) |
+| Check how a broadcast is landing (accepted → delivered → read, plus failed/pending) | `flowiq bc status <org_id> <broadcastId>` (from the send output, or `bc list-remote`) |
 | See WHO failed on a broadcast + why (Meta error) | `flowiq bc status <org_id> <broadcastId> --failures` |
 | Re-send a broadcast to only the ones that failed | `flowiq bc retry <org_id> <broadcastId>` (dry-run) → `… --commit` |
 | **Get an OLD version of a prompt back** | `flowiq prompts history <org_id>` (pick the version) → `flowiq prompts restore <org_id> <audit_id>` (dry-run) → `… --commit` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flowapt/flowiq-cli",
-  "version": "0.3.8",
+  "version": "0.4.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/commands/audit.js

@@ -94,8 +94,13 @@ export async function list(orgId, opts = {}) {
     }
   }
   console.log("");
-  console.log(`  ids: ${entries.map((e) => e.id.slice(0, 8)).join(" ")}`);
-  console.log(`  detail: flowiq audit show <audit_id>   (full id, or the 8-char prefix won't work — copy from --json)`);
+  // Print FULL ids: `audit show` requires a uuid, so an 8-char prefix here just
+  // sent you back to --json to fetch the real one (`prompts history` already
+  // prints full ids — this now matches it).
+  console.log(`  detail: flowiq audit show <audit_id> [--content]`);
+  for (const e of entries) {
+    console.log(`    ${e.id}  ${e.endpoint} ${e.action}`);
+  }
   console.log("");
 }
 

package/src/commands/broadcast.js

@@ -955,6 +955,38 @@ export async function resume(orgId, opts = {}) {
   await runPipeline(orgId, opts, { commitStage: !!opts.commit, isResume: true });
 }
 
+/** List an org's broadcasts newest-first — the discovery step for `status`/`retry`,
+ *  which need a broadcastId you otherwise only have if you kept the send output.
+ *  Read-only. (`list` without an org stays the LOCAL campaign-file listing; this is
+ *  the remote verb, named after `pinboard list-remote`.) */
+export async function listRemote(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.post("broadcast", {
+      action: "list", organization_id: orgId,
+      ...(opts.limit ? { limit: Number(opts.limit) } : {}),
+      ...(opts.template ? { template: opts.template } : {}),
+      ...(opts.since ? { since: opts.since } : {}),
+    });
+  } 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; }
+  // 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)`);
+  for (const b of rows) {
+    console.log("");
+    console.log(`  ${b.id}`);
+    console.log(`    ${sast(b.created_at)}  ${b.template_name ?? "?"}${b.broadcast_name && b.broadcast_name !== b.template_name ? ` (${b.broadcast_name})` : ""}${b.media_url ? " · media header" : ""}`);
+    console.log(`    status ${b.status ?? "?"} · ${b.total_recipients ?? "?"} recipient(s)`);
+  }
+  console.log("");
+  console.log(`Delivery detail: flowiq bc status ${orgId} <broadcast_id> [--failures]`);
+}
+
 /** Live delivery status for a broadcast by its broadcastId (e.g. from a --python
  *  fire-and-forget send). Read-only — reads the `broadcasts` row + message_status
  *  breakdown. This is the visibility the fire-and-forget engine otherwise loses. */
@@ -966,15 +998,24 @@ export async function status(orgId, broadcastId, opts = {}) {
   catch (e) { console.error(`Status 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 b = resp.broadcast, d = resp.delivery;
-  const reached = d.read + d.delivered + d.sent;
+  // Cumulative funnel (v0.4.0+). Falls back to the old disjoint fields when
+  // talking to a server that predates the 3 Aug 2026 fix.
+  const accepted = d.accepted ?? (d.read + d.delivered + d.sent);
+  const delivered = d.delivered_total ?? d.delivered;
+  const read = d.read_total ?? d.read;
+  const pending = d.pending ?? d.other ?? 0;
+  const pctOf = (n) => (accepted > 0 ? `${((n / accepted) * 100).toFixed(1)}%` : "–");
   console.log(`Broadcast ${b.id} — ${resp.organization_name}`);
   console.log(`  template:   ${b.template_name}${b.broadcast_name ? ` (${b.broadcast_name})` : ""}${b.media_url ? " · media header" : ""}`);
   console.log(`  status:     ${b.status ?? "?"} · created ${b.created_at}`);
   console.log(`  recipients: ${b.total_recipients ?? "?"} · ${d.linked} message(s) linked`);
-  console.log(`    ✅ reached ${reached}   (read ${d.read} · delivered ${d.delivered} · sent ${d.sent})`);
-  console.log(`    ❌ failed  ${d.failed}${d.other ? ` · other/pending ${d.other}` : ""}`);
+  console.log(`    ✅ accepted  ${accepted}`);
+  console.log(`    📬 delivered ${delivered}  (${pctOf(delivered)} of accepted)`);
+  console.log(`    👀 read      ${read}  (${pctOf(read)})  — floor only, recipients can disable read receipts`);
+  console.log(`    ⏳ pending   ${pending}  (accepted, no delivery receipt yet)`);
+  console.log(`    ❌ failed    ${d.failed}${d.failed_pct != null ? `  (${d.failed_pct}% of linked)` : ""}`);
   if (b.total_recipients) {
-    console.log(`    ${((reached / b.total_recipients) * 100).toFixed(1)}% of ${b.total_recipients} recipients reached${d.linked < b.total_recipients ? "  (still sending?)" : ""}`);
+    console.log(`    ${((accepted / b.total_recipients) * 100).toFixed(1)}% of ${b.total_recipients} recipients accepted${d.linked < b.total_recipients ? "  (still sending?)" : ""}`);
   }
   if (opts.failures && resp.failures) {
     console.log("");

package/src/index.js

@@ -445,6 +445,13 @@ export function run(argv) {
     .option("--rate <n>", "max messages per second (hard cap 10)", "8")
     .option("--retry-failed", "also re-attempt rows previously marked failed (confirmed failures only)")
     .action((orgId, opts) => broadcastCmd.resume(orgId, opts));
+  broadcast.command("list-remote <organization_id>")
+    .description("List the org's broadcasts newest-first (full broadcastId + template + status + recipients) — the discovery step for `bc status` / `bc retry`")
+    .option("--limit <n>", "how many to show (default 25, max 200)")
+    .option("--template <substr>", "filter: template_name contains this (case-insensitive)")
+    .option("--since <date>", "filter: created on/after this date, e.g. 2026-07-01")
+    .option("--json", "raw JSON")
+    .action((orgId, opts) => broadcastCmd.listRemote(orgId, opts));
   broadcast.command("status <organization_id> <broadcast_id>")
     .description("Live delivery counts (read/delivered/sent/failed) for a broadcast by its broadcastId — e.g. from a --python fire-and-forget send")
     .option("--failures", "also list each FAILED recipient + the Meta error reason (makes a python send auditable)")