@flowapt/flowiq-cli 0.3.4 → 0.3.5

package/README.md

@@ -160,7 +160,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|list` (alias `bc`)
+### Broadcast — `flowiq broadcast map|preview|send|resume|status|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
@@ -194,6 +194,11 @@ 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). `flowiq bc status <org> <broadcastId>`.
 - **`--python` engine (v0.3.4, `send --tag` only)**: hand the whole send to the
   **python `/meta-broadcast` endpoint** — the *same* sender the dashboard's "Python
   endpoint" toggle uses — via a staff-gated proxy (the master key stays server-side

package/TEAM-GUIDE.md

@@ -93,6 +93,7 @@ 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` |
 | 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) |
+| Check how a broadcast is landing (read/delivered/sent/failed) | `flowiq bc status <org_id> <broadcastId>` (the `broadcastId` a `--python` send prints) |
 | Read a contact's chat | `flowiq m pull <contact_id>` then open the JSON |
 | Export an org's full chat history | `flowiq export chats <org_id>` |
 | Check / create WhatsApp templates | `flowiq tpl pull <org_id>` / `flowiq tpl create <org_id> --request-file req.json` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flowapt/flowiq-cli",
-  "version": "0.3.4",
+  "version": "0.3.5",
   "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

@@ -943,6 +943,29 @@ export async function resume(orgId, opts = {}) {
   await runPipeline(orgId, opts, { commitStage: !!opts.commit, isResume: true });
 }
 
+/** 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. */
+export async function status(orgId, broadcastId, opts = {}) {
+  if (!UUID_RE.test(orgId)) { console.error(`Error: "${orgId}" is not a valid organization UUID.`); process.exit(1); }
+  if (!UUID_RE.test(broadcastId)) { console.error("Error: broadcast id must be a UUID (the broadcastId a --python send printed)."); process.exit(1); }
+  let resp;
+  try { resp = await http.post("broadcast", { action: "status", organization_id: orgId, broadcast_id: broadcastId }); }
+  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;
+  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}` : ""}`);
+  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?)" : ""}`);
+  }
+}
+
 export async function list() {
   let files;
   try { files = (await fs.readdir(CAMPAIGN_DIR)).filter((f) => f.endsWith(".json") && !f.endsWith(".report.json")); }

package/src/index.js

@@ -411,6 +411,10 @@ 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("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("--json", "raw JSON")
+    .action((orgId, broadcastId, opts) => broadcastCmd.status(orgId, broadcastId, opts));
   broadcast.command("list")
     .description("List local campaigns + sent counts")
     .action(() => broadcastCmd.list());