@flowapt/flowiq-cli 0.3.9 → 0.4.1

package/README.md

@@ -214,12 +214,22 @@ flowiq bc resume <org_id> --campaign july-referrals --commit [--retry-failed]
   semantic labels + body text and you confirm each slot once; the mapping is
   saved to `.flowiq/campaigns/<campaign>.json` and reused.
 - **Media-header templates (image/video/document) ARE supported** (v0.3.3) —
-  exactly like the dashboard. The header image defaults to the template's own
-  stored image (`template_data.header.default_url`); override with
+  exactly like the dashboard. The header media defaults to the template's own
+  stored URL (`template_data.header.default_url`); override with
   `--header-media <public-url>` on `map`/`preview`/`send`. Passed to
   `/api/send-template` as `headerMedia`, the same field the dashboard uses. A
-  media-header template with no resolvable image is refused (pass
+  media-header template with no resolvable media is refused (pass
   `--header-media`).
+  - **Header media is VERIFIED, not assumed (v0.4.1).** The CLI probes the
+    resolved URL's `content-type` and compares it to the template's header
+    format: a match prints e.g. `header video (video ✓ video/mp4)`; a
+    **mismatch ABORTS** (e.g. a VIDEO template whose resolved media serves
+    `image/png` — every recipient would get a broken header). Templates
+    created before the 3 Aug 2026 `create-meta-template` mime fix can carry a
+    broken Meta-side default (a truncated png stored for a video template);
+    the abort message says so — fix by passing `--header-media <real video>`.
+    `map` refuses to save a mismatched default into the campaign file. An
+    unreachable URL only warns (`media unverified`), never blocks.
 - **`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
@@ -227,13 +237,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 +448,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 +462,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 +483,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.
@@ -659,6 +697,16 @@ Media headers: pass `media_header.file_url` (a public URL) — the edge function
 uploads it to Meta server-side. Approval is async; re-`pull` for the
 authoritative Meta status.
 
+**Media mime is detected from the file's actual bytes (3 Aug 2026).**
+`media_header.file_type` is optional and can never override what the file
+really is; a file that contradicts the HEADER format is **refused** (e.g. an
+mp4 on a `format: "IMAGE"` header, or a png on `"VIDEO"`). Before this fix the
+upload defaulted to `image/png` regardless of the file, so a VIDEO template
+still APPROVED but Meta stored a truncated 1MB "png" as its default header
+media — a silently broken template (`bc` inherited the dud as the default send
+media). Video headers submitted through the CLI before 3 Aug 2026 should be
+re-checked: `bc` now flags them at send time.
+
 `template_data` is FlowIQ's own send-time mapping (slot labels, default header
 image) stored alongside the template. Omit it and a default is synthesized
 server-side (`auto_synthesized: true`; the response says
@@ -739,7 +787,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?"` |
@@ -92,10 +93,10 @@ When you see it, run `npm i -g @flowapt/flowiq-cli` — a stale version also mea
 | Combine existing tags → a batched send list (include some tags, drop others, split into batches of N) | `flowiq seg plan <org_id> --tag-prefix clearance-bc --from-tag "loyalty-list" --exclude "recent-campaign" --batch-size 1000` → `flowiq seg apply <org_id> clearance-bc --commit` (makes `clearance-bc-batch-01/02/…`) |
 | Split a big id-list cohort into send-safe batch tags | `flowiq seg plan <org_id> --tag-prefix … --ids-file …` → `flowiq seg apply … --commit` |
 | 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 a broadcast whose template has an IMAGE/VIDEO/DOCUMENT header | Same as above — the media is automatic (the template's own stored header). Override with `--header-media <public-url>` if needed. The CLI verifies the resolved media's actual type against the header format — `header video (video ✓ video/mp4)` means verified; a mismatch (e.g. a video template whose stored default is secretly a png — templates made before 3 Aug 2026 can carry this) ABORTS and tells you to pass `--header-media` with the real file. |
 | 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.1",
   "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

@@ -335,6 +335,51 @@ async function introspect(orgId, templateName) {
 }
 
 /** Validation V-1..V-13. Returns {valid, skipped, aborts}. */
+// ---------------------------------------------------------------------------
+// header-media verification
+// ---------------------------------------------------------------------------
+// A resolved header-media URL is NOT confirmation it is the right KIND of
+// media. The template's stored default can be broken — most notably the
+// pre-3-Aug-2026 create-meta-template mime bug, which left VIDEO templates
+// with a truncated image/png as their Meta-side default. Probe the URL's
+// content-type and compare it to the template's header format before trusting
+// it: match → "(video ✓ video/mp4)"; mismatch → hard abort (a send would
+// deliver a broken header to every recipient); unreachable → warn only.
+
+async function probeContentType(url) {
+  const attempt = async (method, headers) => {
+    const ctrl = new AbortController();
+    const t = setTimeout(() => ctrl.abort(), 8000);
+    try {
+      const r = await fetch(url, { method, headers, redirect: "follow", signal: ctrl.signal });
+      if (!r.ok && r.status !== 206) return null;
+      const ct = (r.headers.get("content-type") || "").split(";")[0].trim().toLowerCase();
+      if (method === "GET") { try { await r.body?.cancel(); } catch { /* stream already closed */ } }
+      return ct || null;
+    } catch { return null; } finally { clearTimeout(t); }
+  };
+  // HEAD first; some hosts refuse it, so fall back to a 1-byte ranged GET.
+  return (await attempt("HEAD")) ?? (await attempt("GET", { Range: "bytes=0-0" }));
+}
+
+async function verifyHeaderMedia(template, headerMedia) {
+  if (!headerMedia) return { label: "", status: null };
+  const contentType = await probeContentType(headerMedia);
+  if (!contentType) return { label: " (media unverified — URL did not answer a type probe)", status: "unknown" };
+  const family = contentType.split("/")[0];
+  const want = template.header_type === "image" ? "image" : template.header_type === "video" ? "video" : null;
+  const ok = want ? family === want : (family !== "image" && family !== "video"); // document: any non-image/video
+  if (ok) return { label: ` (${template.header_type} ✓ ${contentType})`, status: "ok", contentType };
+  return { label: ` (⚠ media serves ${contentType}, not ${template.header_type})`, status: "mismatch", contentType };
+}
+
+function headerMismatchMessage(template, headerMedia, contentType, { explicit }) {
+  const base = `template header is ${template.header_type.toUpperCase()} but the resolved media (${headerMedia}) serves ${contentType}`;
+  return explicit
+    ? `${base} — point --header-media at the real ${template.header_type}`
+    : `${base} — the template's stored default header media is broken (created before the 3 Aug 2026 create-meta-template mime fix?); pass --header-media <url> with the real ${template.header_type}`;
+}
+
 function validateRows(template, mapping, headers, rows, illegalChars, headerMedia) {
   const aborts = [];
   if (template.status !== "APPROVED") aborts.push(`V-1: template status is ${template.status} — only APPROVED templates send`);
@@ -533,7 +578,12 @@ async function runPipeline(orgId, opts, { commitStage, isResume }) {
   const headerMedia = isMediaHeader
     ? (opts.headerMedia || cfg?.header_media || template.header_media_default || null)
     : null;
-  console.log(`Template ${template.name} [${template.status}] — ${template.parameter_format}, ${template.body_var_count} body var(s), header ${template.header_type}${headerMedia ? " (image ✓)" : ""}${template.url_button?.present ? ", dynamic URL button" : ""}`);
+  const headerCheck = await verifyHeaderMedia(template, headerMedia);
+  console.log(`Template ${template.name} [${template.status}] — ${template.parameter_format}, ${template.body_var_count} body var(s), header ${template.header_type}${headerCheck.label}${template.url_button?.present ? ", dynamic URL button" : ""}`);
+  if (headerCheck.status === "mismatch") {
+    console.error(`ABORT — ${headerMismatchMessage(template, headerMedia, headerCheck.contentType, { explicit: !!opts.headerMedia })}`);
+    process.exit(1);
+  }
 
   // 4. CSV
   let csv;
@@ -799,8 +849,10 @@ async function runTagPipeline(orgId, opts, { commitStage }) {
   const headerMedia = isMediaHeader
     ? (opts.headerMedia || cfg?.header_media || template.header_media_default || null)
     : null;
-  console.log(`Template ${template.name} [${template.status}] — ${template.parameter_format}, ${template.body_var_count} body var(s), header ${template.header_type}${headerMedia ? " (image ✓)" : ""}${template.url_button?.present ? ", dynamic URL button" : ""}`);
+  const headerCheck = await verifyHeaderMedia(template, headerMedia);
+  console.log(`Template ${template.name} [${template.status}] — ${template.parameter_format}, ${template.body_var_count} body var(s), header ${template.header_type}${headerCheck.label}${template.url_button?.present ? ", dynamic URL button" : ""}`);
   const aborts = [];
+  if (headerCheck.status === "mismatch") aborts.push(headerMismatchMessage(template, headerMedia, headerCheck.contentType, { explicit: !!opts.headerMedia }));
   if (template.status !== "APPROVED") aborts.push(`template status is ${template.status} — only APPROVED templates send`);
   if (template.parameter_format !== "POSITIONAL") aborts.push("NAMED templates are not supported in v1");
   if (template.is_carousel) aborts.push("carousel templates are not supported in v1");
@@ -920,10 +972,22 @@ export async function map(orgId, opts = {}) {
   }
   const built = await interactiveMapping(intro.template, csv.headers, campaign);
   const t = intro.template;
-  const headerMedia = !["text", "none"].includes(t.header_type)
+  let headerMedia = !["text", "none"].includes(t.header_type)
     ? (opts.headerMedia || t.header_media_default || null) : null;
   if (!["text", "none"].includes(t.header_type)) {
-    console.log(headerMedia ? `Header image (${t.header_type}): ${headerMedia}` : `⚠ ${t.header_type} header but no image — pass --header-media <url> on send.`);
+    const check = await verifyHeaderMedia(t, headerMedia);
+    if (check.status === "mismatch") {
+      if (opts.headerMedia) {
+        console.error(`ABORT — ${headerMismatchMessage(t, headerMedia, check.contentType, { explicit: true })}`);
+        process.exit(1);
+      }
+      // The template's stored default is broken — do NOT copy it into the
+      // campaign file (that is how a dud default poisons every later send).
+      console.log(`⚠ ${headerMismatchMessage(t, headerMedia, check.contentType, { explicit: false })}. NOT saved to the campaign.`);
+      headerMedia = null;
+    } else {
+      console.log(headerMedia ? `Header media (${t.header_type}): ${headerMedia}${check.label}` : `⚠ ${t.header_type} header but no media — pass --header-media <url> on send.`);
+    }
   }
   await saveCampaign({
     schema_version: 1, campaign, organization_id: orgId,
@@ -998,15 +1062,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("");