@flowapt/flowiq-cli 0.3.6 → 0.3.7

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|status|list` (alias `bc`)
+### Broadcast — `flowiq broadcast map|preview|send|resume|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
@@ -198,7 +198,15 @@ flowiq bc resume <org_id> --campaign july-referrals --commit [--retry-failed]
   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>`.
+  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.
+- **`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.
+  DRY-RUN by default (shows the failed count + reason breakdown); `--commit` fires.
+  Note: permanent failures (e.g. `131026` undeliverable, opt-outs) just fail again —
+  retry earns its keep on transient (throttle/throughput) failures. Capped at 500.
 - **Engine auto-routing (v0.3.6):** any `send --tag` of **more than 10** eligible
   recipients **always uses the python engine** (a `>2000` tag routes there too).
   Only a ≤10 send stays on the resumable per-row Node engine. `--python` forces
@@ -242,8 +250,12 @@ flowiq bc send <org_id> --tag july-promo-batch-01 --template fresh_drop_v1 \
 ```
 
 Values are shared across the tag (use `{{first_name}}` etc. for per-contact
-personalization — resolved server-side). Opted-out / archived / blocked
-contacts under the tag are excluded automatically. Tags with >2000 contacts
+personalization — resolved server-side). Supported per-contact tokens:
+`{{first_name}}` `{{full_name}}` `{{email}}` `{{phone_number}}`
+`{{whatsapp_id}}` `{{contact_id}}`, plus `{{attributes.<key>}}` for any
+top-level key of the contact's `attributes` JSON (missing / object-valued
+keys render as empty — both engines, since 21 Jul 2026). Opted-out /
+archived / blocked contacts under the tag are excluded automatically. Tags with >2000 contacts
 are refused — slice them with `flowiq segments` first.
 
 ### Segments — `flowiq segments plan|apply|list|untag` (alias `seg`)

package/TEAM-GUIDE.md

@@ -90,10 +90,12 @@ When you see it, run `npm i -g @flowapt/flowiq-cli` — a stale version also mea
 | Split your whole broadcast list into N even cohorts (e.g. 3 for A/B/C or waves) | `flowiq seg plan <org_id> --tag-prefix bcast --from-attribute allow_broadcast_true --split 3` → `flowiq seg apply <org_id> bcast --commit` (makes `bcast-batch-01/02/03`, ~even, shuffled) |
 | 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` |
+| 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) |
+| 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` |
 | 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.6",
+  "version": "0.3.7",
   "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

@@ -962,7 +962,7 @@ 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 }); }
+  try { resp = await http.post("broadcast", { action: "status", organization_id: orgId, broadcast_id: broadcastId, include_failures: !!opts.failures }); }
   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;
@@ -976,6 +976,47 @@ export async function status(orgId, broadcastId, opts = {}) {
   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?)" : ""}`);
   }
+  if (opts.failures && resp.failures) {
+    console.log("");
+    console.log(`  Failures by reason:`);
+    for (const [reason, n] of Object.entries(resp.failure_reasons || {}).sort((a, b2) => b2[1] - a[1])) console.log(`    ${String(n).padStart(5)} × ${reason}`);
+    const cap = opts.limit ? Number(opts.limit) : 40;
+    console.log("");
+    console.log(`  Failed recipients${resp.failures.length > cap ? ` (showing ${cap} of ${resp.failures.length}; --json for all)` : ` (${resp.failures.length})`}:`);
+    for (const f of resp.failures.slice(0, cap)) {
+      console.log(`    ${(f.number || "—").padEnd(14)} ${(f.name || "").slice(0, 22).padEnd(22)} ${f.error_code ?? "?"} ${f.error_title || ""}`);
+    }
+  }
+}
+
+/** Re-send a broadcast to ONLY its failed recipients (transient-failure recovery).
+ *  Reconstructs the send from the broadcasts row + re-fires via python. The dry-run
+ *  shows the failed count + reason breakdown; --commit creates a NEW broadcast. */
+export async function retry(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 to retry)."); process.exit(1); }
+  let dry;
+  try { dry = await http.post("broadcast", { action: "retry", organization_id: orgId, broadcast_id: broadcastId, dry_run: true }); }
+  catch (e) { console.error(`Retry check failed: ${e.message}`); if (e.body?.error) console.error(`  ${e.body.error}`); process.exit(1); }
+  console.log(`Broadcast ${broadcastId} (${dry.broadcast?.template_name ?? "?"}) — ${dry.failed_count} failed recipient(s).`);
+  for (const [reason, n] of Object.entries(dry.failure_reasons || {}).sort((a, b) => b[1] - a[1])) console.log(`    ${String(n).padStart(5)} × ${reason}`);
+  if (!dry.failed_count) { console.log("Nothing to retry."); return; }
+  console.log("");
+  console.log("Note: permanent failures (131026 undeliverable / opt-outs) just fail again — retry helps transient (throttle/throughput) failures.");
+  if (!opts.commit) {
+    console.log(`DRY RUN — would re-send to ${dry.failed_count} failed recipient(s) via the python engine. Add --commit to retry.`);
+    return;
+  }
+  if (!opts.yes) {
+    const a = await ask(`Type "retry" to re-send to ${dry.failed_count} failed recipient(s): `);
+    if (a !== "retry") { console.log("Aborted — nothing re-sent."); process.exit(0); }
+  }
+  let out;
+  try { out = await http.post("broadcast", { action: "retry", organization_id: orgId, broadcast_id: broadcastId, dry_run: false }); }
+  catch (e) { console.error(`Retry failed: ${e.message}`); if (e.body?.error) console.error(`  ${e.body.error}`); process.exit(1); }
+  console.log("");
+  console.log(`✅ ${out.message || `Retry fired for ${out.retried} recipient(s)`}${out.broadcastId ? `  ·  new broadcastId ${out.broadcastId}` : ""}`);
+  if (out.broadcastId) console.log(`   Watch it: flowiq bc status ${orgId} ${out.broadcastId} --failures`);
 }
 
 export async function list() {

package/src/index.js

@@ -413,8 +413,15 @@ export function run(argv) {
     .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("--failures", "also list each FAILED recipient + the Meta error reason (makes a python send auditable)")
+    .option("--limit <n>", "with --failures: how many failed rows to print", "40")
     .option("--json", "raw JSON")
     .action((orgId, broadcastId, opts) => broadcastCmd.status(orgId, broadcastId, opts));
+  broadcast.command("retry <organization_id> <broadcast_id>")
+    .description("Re-send a broadcast to ONLY its failed recipients (transient-failure recovery). DRY-RUN by default; --commit re-fires via python")
+    .option("--commit", "actually re-send (omit to see the failed count + reasons)")
+    .option("--yes", "skip the type-'retry' confirm gate")
+    .action((orgId, broadcastId, opts) => broadcastCmd.retry(orgId, broadcastId, opts));
   broadcast.command("list")
     .description("List local campaigns + sent counts")
     .action(() => broadcastCmd.list());