@flowapt/flowiq-cli 0.3.9 → 0.4.0

package/README.md

@@ -227,13 +227,28 @@ flowiq bc resume <org_id> --campaign july-referrals --commit [--retry-failed]
   `--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 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.
+- **`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.
@@ -423,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
@@ -436,6 +452,18 @@ 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.
@@ -445,7 +473,7 @@ flowiq kw push <slug> --prune            # ALSO deletes DB keywords missing from
   ```json
   { "type": "send_message", "when": { "field": "email", "op": "is_not_empty" } }
   ```
-  `field` ∈ `email` / `phone_number` / `full_name` / `city` (allowlist).
+  `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.
@@ -739,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

@@ -79,6 +79,7 @@ When you see it, run `npm i -g @flowapt/flowiq-cli` — a stale version also mea
 | 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?"` |
@@ -95,7 +96,7 @@ When you see it, run `npm i -g @flowapt/flowiq-cli` — a stale version also mea
 | 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.** |
 | 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 (read/delivered/sent/failed) | `flowiq bc status <org_id> <broadcastId>` (from the send output, or `bc list-remote`) |
+| 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.9",
+  "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/broadcast.js

@@ -998,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("");