@flowapt/flowiq-cli 0.3.2 → 0.3.4

package/README.md

@@ -187,9 +187,24 @@ flowiq bc resume <org_id> --campaign july-referrals --commit [--retry-failed]
   leading-zero handled). The mapper auto-suggests from the template's
   semantic labels + body text and you confirm each slot once; the mapping is
   saved to `.flowiq/campaigns/<campaign>.json` and reused.
-- **v1 scope**: Meta orgs, POSITIONAL templates, text/no header. NAMED,
-  carousel, media-header templates and WATI orgs are refused with a clear
-  message.
+- **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
+  `--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
+  `--header-media`).
+- **`--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
+  in `VITE_PYTHON_RENDER_API_KEY`; the CLI never holds it). Python resolves the tag
+  + eligibility (`allow_broadcast=true`, not blocked; **no 2000-cap, paginated**) and
+  sends **fire-and-forget**, returning a `broadcastId`. Dry-run (no `--commit`) asks
+  python for the eligible count + a sample. Trade-off vs the default per-row engine:
+  no CLI write-ahead-log / `resume` (python owns the broadcast record), and archived
+  contacts aren't separately filtered. Media headers work on both engines.
+- **v1 scope**: Meta orgs, POSITIONAL templates, text / no header / media header.
+  NAMED and carousel templates and WATI orgs are refused with a clear message.
 - **Validation before anything sends**: APPROVED-only, every slot mapped,
   contiguous params (the Meta `#132000` guard — a stray key is structurally
   impossible), phone validity, illegal characters (Meta `#100`; `reject` by

package/TEAM-GUIDE.md

@@ -91,6 +91,8 @@ 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` |
+| 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) |
 | 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.2",
+  "version": "0.3.4",
   "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,12 +335,17 @@ async function introspect(orgId, templateName) {
 }
 
 /** Validation V-1..V-13. Returns {valid, skipped, aborts}. */
-function validateRows(template, mapping, headers, rows, illegalChars) {
+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`);
   if (template.parameter_format !== "POSITIONAL") aborts.push("V-2: NAMED templates are not supported in v1");
   if (template.is_carousel) aborts.push("V-3: carousel templates are not supported in v1");
-  if (!["text", "none"].includes(template.header_type)) aborts.push(`V-3: media-header templates (${template.header_type}) are not supported in v1`);
+  // Media headers (image/video/document) ARE supported — they just need an image
+  // URL, exactly like the dashboard. Resolved as --header-media / saved mapping /
+  // the template's stored default_url. Only block if a media header has none.
+  if (!["text", "none"].includes(template.header_type) && !headerMedia) {
+    aborts.push(`V-3: template has a ${template.header_type} header but no image resolved — pass --header-media <url> (the template has no stored default header image)`);
+  }
   for (const pos of template.body_positions) {
     if (!mapping.body_params?.[`param${pos}`]?.source) aborts.push(`V-4: body param${pos} is unmapped`);
   }
@@ -428,12 +433,13 @@ async function applySafetyExclusions(orgId, valid, skipped) {
   return keep;
 }
 
-function renderPreview(template, sample) {
+function renderPreview(template, sample, headerMedia) {
   let bodyText = template.body_text;
   for (const [k, v] of Object.entries(sample.values)) {
     bodyText = bodyText.replaceAll(`{{${k.replace("param", "")}}}`, v);
   }
   console.log(`Row ${sample.rownum}  →  ${sample.number}   [VALID]${sample.sanitized ? " (sanitized)" : ""}`);
+  if (headerMedia) console.log(`  Header (${template.header_type}): ${headerMedia}`);
   console.log(`  Body:\n    ${bodyText.replace(/\n/g, "\n    ")}`);
   if (template.url_button?.present && sample.buttonValue != null) {
     const url = template.url_button.url_base.replace(/\{\{[^}]+\}\}/, sample.buttonValue);
@@ -472,7 +478,7 @@ function classifySendError(errText) {
   return "row_fatal";
 }
 
-async function sendOne(apiUrl, orgId, templateName, row) {
+async function sendOne(apiUrl, orgId, templateName, row, headerMedia) {
   // #132000 structural guard: whitelist param\d+ keys only.
   const bodyParameters = {};
   for (const [k, v] of Object.entries(row.values)) {
@@ -484,6 +490,9 @@ async function sendOne(apiUrl, orgId, templateName, row) {
     whatsappNumber: row.number,
     bodyParameters,
     ...(row.buttonValue != null ? { buttonParameters: { param1: row.buttonValue } } : {}),
+    // Static media header (same field the dashboard passes for image/video/doc
+    // headers) — /api/send-template renders it onto the HEADER component.
+    ...(headerMedia ? { headerMedia } : {}),
   };
   // Org-UUID branch: NO auth header (a staff key here would 401 on the fiq_ branch).
   const resp = await fetch(`${apiUrl.replace(/\/$/, "")}/send-template?organizationId=${orgId}`, {
@@ -517,7 +526,14 @@ async function runPipeline(orgId, opts, { commitStage, isResume }) {
   try { intro = await introspect(orgId, templateName); }
   catch (e) { console.error(`Template introspection failed: ${e.message}`); if (e.body?.error) console.error(`  ${e.body.error}`); process.exit(1); }
   const template = intro.template;
-  console.log(`Template ${template.name} [${template.status}] — ${template.parameter_format}, ${template.body_var_count} body var(s), header ${template.header_type}${template.url_button?.present ? ", dynamic URL button" : ""}`);
+  // Media-header templates send a static image (frontend behaviour): prefer an
+  // explicit --header-media, then a previously-saved one, then the template's
+  // stored default_url. Non-media headers → null.
+  const isMediaHeader = !["text", "none"].includes(template.header_type);
+  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" : ""}`);
 
   // 4. CSV
   let csv;
@@ -550,6 +566,7 @@ async function runPipeline(orgId, opts, { commitStage, isResume }) {
       recipient: built.recipient,
       body_params: built.body_params,
       button_params: built.button_params,
+      ...(headerMedia ? { header_media: headerMedia } : {}),
       options: { illegal_chars: opts.illegalChars || "reject" },
     };
     await saveCampaign(cfg);
@@ -558,7 +575,7 @@ async function runPipeline(orgId, opts, { commitStage, isResume }) {
   }
 
   // 6. validate
-  const { aborts, valid, skipped } = validateRows(template, mapping, csv.headers, csv.rows, opts.illegalChars || mapping.options?.illegal_chars || "reject");
+  const { aborts, valid, skipped } = validateRows(template, mapping, csv.headers, csv.rows, opts.illegalChars || mapping.options?.illegal_chars || "reject", headerMedia);
   if (aborts.length) { for (const a of aborts) console.error(`ABORT — ${a}`); process.exit(1); }
 
   // 6b. broadcast-safety exclusions (live)
@@ -590,7 +607,7 @@ async function runPipeline(orgId, opts, { commitStage, isResume }) {
   console.log("");
   const nPreview = Math.max(1, Number(opts.rows ?? 3));
   const samples = [sendable[0], ...sendable.slice(1).filter((r, i, a) => a.findIndex((x) => x.values.param1 === r.values.param1) === i)].filter(Boolean).slice(0, nPreview);
-  for (const s of samples) { renderPreview(template, s); console.log(""); }
+  for (const s of samples) { renderPreview(template, s, headerMedia); console.log(""); }
   console.log(`Summary: ${sendable.length} sendable · skipped ${skipped.length} (${Object.entries(skippedByReason).map(([k, v]) => `${k}: ${v}`).join(", ") || "none"})`);
   if (statusMap.size) console.log(`Status log: ${[...statusMap.values()].filter((s) => s.status === "sent").length} already sent · work set ${workSet.length}`);
   if (ambiguous.length) console.log(`⚠ ${ambiguous.length} number(s) have an AMBIGUOUS in-flight status (crash mid-send?) — never auto-resent: ${ambiguous.slice(0, 5).join(", ")}${ambiguous.length > 5 ? "…" : ""}. Check the chat, then edit the status log if they must be retried.`);
@@ -620,7 +637,7 @@ async function runPipeline(orgId, opts, { commitStage, isResume }) {
 
   // 10-11. send loop + report (shared with the --tag pipeline)
   await executeSendLoop({
-    orgId, campaign, templateName, workSet, statusMap, rate,
+    orgId, campaign, templateName, workSet, statusMap, rate, headerMedia,
     skippedCount: skipped.length,
     writeMetaHeader: !logHeader,
     metaExtras: { csv_fingerprint: csv.header_fingerprint, total_rows: csv.rows.length, valid_rows: sendable.length },
@@ -628,7 +645,7 @@ async function runPipeline(orgId, opts, { commitStage, isResume }) {
 }
 
 /** The paced, write-ahead-logged per-row send loop + final report. */
-async function executeSendLoop({ orgId, campaign, templateName, workSet, statusMap, rate, skippedCount, writeMetaHeader, metaExtras }) {
+async function executeSendLoop({ orgId, campaign, templateName, workSet, statusMap, rate, skippedCount, writeMetaHeader, metaExtras, headerMedia }) {
   const { api_url } = await loadConfig();
   if (writeMetaHeader) {
     await appendLog(campaign, {
@@ -648,7 +665,7 @@ async function executeSendLoop({ orgId, campaign, templateName, workSet, statusM
       // WRITE-AHEAD: sending line BEFORE the POST.
       await appendLog(campaign, { type: "row", number: row.number, rownum: row.rownum, status: "sending", attempt, at: new Date().toISOString() });
       let out;
-      try { out = await sendOne(api_url, orgId, templateName, row); }
+      try { out = await sendOne(api_url, orgId, templateName, row, headerMedia); }
       catch (e) {
         // network/timeout with no response = UNKNOWN outcome → ambiguous, never auto-retried
         await appendLog(campaign, { type: "row", number: row.number, rownum: row.rownum, status: "unknown", error: e.message, attempt, at: new Date().toISOString() });
@@ -714,6 +731,54 @@ export function collectKV(pair, mapAcc) {
   return mapAcc;
 }
 
+/** --python engine: hand the send to the python /meta-broadcast endpoint via the
+ *  staff-gated proxy. Fire-and-forget — python resolves the tag + eligibility
+ *  (allow_broadcast=true, not blocked) and sends in the background, returning a
+ *  broadcastId. No CLI write-ahead log / resume for this engine (python owns the
+ *  broadcast record). Dry-run (no --commit) asks python for the eligible count. */
+async function runPythonTagSend(orgId, { opts, tag, templateName, template, headerMedia, bodyLiterals, buttonLiteral, commitStage }) {
+  const reqBody = (dryRun) => ({
+    action: "send-python", organization_id: orgId, tag, template_name: templateName,
+    body_parameters: bodyLiterals,
+    ...(buttonLiteral ? { button_parameters: { param1: buttonLiteral } } : {}),
+    ...(headerMedia ? { header_media: headerMedia } : {}),
+    dry_run: dryRun,
+  });
+
+  // Dry-run: python fetches the eligible contacts (no send) → count + sample.
+  let dry;
+  try { dry = await http.post("broadcast", reqBody(true)); }
+  catch (e) { console.error(`Python dry-run failed: ${e.message}`); if (e.body?.error) console.error(`  ${e.body.error}`); process.exit(1); }
+  const total = dry.total_contacts_found ?? 0;
+
+  console.log("");
+  console.log(`Engine: PYTHON (yapi.store/meta-broadcast) — fire-and-forget, python-tracked.`);
+  console.log(`Tag "${tag}": ${total} eligible contact(s) (allow_broadcast + not blocked, resolved server-side).`);
+  const sampleNum = dry.sample_contacts?.[0]?.whatsapp_id || dry.sample_contacts?.[0]?.phone_number || "<first eligible>";
+  renderPreview(template, { rownum: 1, number: sampleNum, values: bodyLiterals, buttonValue: buttonLiteral }, headerMedia);
+  if (Object.values(bodyLiterals).some((v) => /\{\{(first_name|full_name|email|phone_number|whatsapp_id)\}\}/.test(String(v)))) {
+    console.log("  ({{first_name}}-style tokens are resolved PER CONTACT by python)");
+  }
+  console.log("");
+
+  if (!commitStage) {
+    console.log("DRY RUN — nothing sent. Add --commit to fire the python broadcast.");
+    return;
+  }
+  if (!total) { console.log("Nothing eligible under this tag."); return; }
+  if (!opts.yes) {
+    const answer = await ask(`Type the tag ("${tag}") to fire the python broadcast to ${total} contact(s): `);
+    if (answer !== tag) { console.log("Mismatch — aborted, nothing sent."); process.exit(0); }
+  }
+
+  let out;
+  try { out = await http.post("broadcast", reqBody(false)); }
+  catch (e) { console.error(`Python broadcast failed: ${e.message}`); if (e.body?.error) console.error(`  ${e.body.error}`); process.exit(1); }
+  console.log("");
+  console.log(`✅ ${out.message || "Broadcast started"}${out.broadcastId ? `  ·  broadcastId ${out.broadcastId}` : ""}`);
+  console.log(`   Python is sending in the background${out.mode ? ` (${out.mode})` : ""} and tracking it under that broadcast id — no CLI resume for this engine.`);
+}
+
 async function runTagPipeline(orgId, opts, { commitStage }) {
   if (!UUID_RE.test(orgId)) { console.error(`Error: "${orgId}" is not a valid organization UUID.`); process.exit(1); }
   const campaign = opts.campaign || slugify(opts.tag, "tag-campaign");
@@ -730,18 +795,30 @@ async function runTagPipeline(orgId, opts, { commitStage }) {
   try { intro = await introspect(orgId, templateName); }
   catch (e) { console.error(`Template introspection failed: ${e.message}`); if (e.body?.error) console.error(`  ${e.body.error}`); process.exit(1); }
   const template = intro.template;
-  console.log(`Template ${template.name} [${template.status}] — ${template.parameter_format}, ${template.body_var_count} body var(s), header ${template.header_type}${template.url_button?.present ? ", dynamic URL button" : ""}`);
+  const isMediaHeader = !["text", "none"].includes(template.header_type);
+  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 aborts = [];
   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");
-  if (!["text", "none"].includes(template.header_type)) aborts.push(`media-header templates (${template.header_type}) are not supported in v1`);
+  // Media headers supported — need an image (--header-media / saved / default_url).
+  if (isMediaHeader && !headerMedia) aborts.push(`template has a ${template.header_type} header but no image resolved — pass --header-media <url> (the template has no stored default header image)`);
   const keys = Object.keys(bodyLiterals);
   if (keys.some((k) => !/^param\d+$/.test(k))) aborts.push(`--body keys must be param1..N (got ${keys.join(", ")})`);
   if (keys.length !== template.body_var_count) aborts.push(`template expects ${template.body_var_count} body param(s), you provided ${keys.length} (--body paramN=…). Values may use {{first_name}}/{{full_name}}/{{email}}/{{phone_number}} — resolved per contact.`);
   if (template.url_button?.present && !buttonLiteral) aborts.push("template has a dynamic URL button — pass --button param1=<code>");
   if (aborts.length) { for (const a of aborts) console.error(`ABORT — ${a}`); process.exit(1); }
 
+  // --python: hand the whole send to the python /meta-broadcast engine (the same
+  // sender the dashboard's "Python endpoint" toggle uses) via the staff-gated
+  // proxy. Python resolves the tag + eligibility + sends fire-and-forget.
+  if (opts.python) {
+    return runPythonTagSend(orgId, { opts, tag, templateName, template, headerMedia, bodyLiterals, buttonLiteral, commitStage });
+  }
+
   // resolve the tag server-side (broadcast-safe recipients only)
   let resolved;
   try { resolved = await http.post("broadcast", { action: "resolve-tag", organization_id: orgId, tag }); }
@@ -769,7 +846,7 @@ async function runTagPipeline(orgId, opts, { commitStage }) {
   });
 
   console.log("");
-  renderPreview(template, sendable[0]);
+  renderPreview(template, sendable[0], headerMedia);
   if (Object.values(bodyLiterals).some((v) => /\{\{(first_name|full_name|email|phone_number|whatsapp_id)\}\}/.test(String(v)))) {
     console.log("  ({{first_name}}-style tokens above are resolved PER CONTACT server-side)");
   }
@@ -799,11 +876,12 @@ async function runTagPipeline(orgId, opts, { commitStage }) {
     organization_id: orgId, organization_slug: slugify(resolved.organization_name, orgId.slice(0, 8)),
     template_name: templateName, tag,
     body_params_literal: bodyLiterals, button_param_literal: buttonLiteral,
+    ...(headerMedia ? { header_media: headerMedia } : {}),
     created_at: cfg?.created_at ?? new Date().toISOString(),
   });
 
   await executeSendLoop({
-    orgId, campaign, templateName, workSet, statusMap, rate,
+    orgId, campaign, templateName, workSet, statusMap, rate, headerMedia,
     skippedCount: resolved.excluded.length,
     writeMetaHeader: !logHeader,
     metaExtras: { tag, tagged_total: resolved.tagged_total, valid_rows: sendable.length },
@@ -829,6 +907,12 @@ export async function map(orgId, opts = {}) {
     return;
   }
   const built = await interactiveMapping(intro.template, csv.headers, campaign);
+  const t = intro.template;
+  const 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.`);
+  }
   await saveCampaign({
     schema_version: 1, campaign, organization_id: orgId,
     organization_slug: slugify(intro.organization_name, orgId.slice(0, 8)),
@@ -836,6 +920,7 @@ export async function map(orgId, opts = {}) {
     created_at: new Date().toISOString(),
     csv: { path: opts.csv, delimiter: csv.delimiter, headers: csv.headers, header_fingerprint: csv.header_fingerprint },
     recipient: built.recipient, body_params: built.body_params, button_params: built.button_params,
+    ...(headerMedia ? { header_media: headerMedia } : {}),
     options: { illegal_chars: "reject" },
   });
   console.log(`Saved mapping: ${cfgPath(campaign)}`);
@@ -847,6 +932,7 @@ export async function preview(orgId, opts = {}) {
 
 export async function send(orgId, opts = {}) {
   if (opts.tag && opts.csv) { console.error("Error: --tag and --csv are mutually exclusive."); process.exit(1); }
+  if (opts.python && !opts.tag) { console.error("Error: --python requires --tag (the python engine is tag-based)."); process.exit(1); }
   if (opts.tag) return runTagPipeline(orgId, opts, { commitStage: !!opts.commit });
   await runPipeline(orgId, opts, { commitStage: !!opts.commit, isResume: !!opts.resume });
 }

package/src/index.js

@@ -371,6 +371,7 @@ export function run(argv) {
     .requiredOption("--template <name>", "approved Meta template name")
     .requiredOption("--csv <file>", "path to the recipients CSV")
     .option("--campaign <name>", "campaign id / config file slug (default: CSV filename)")
+    .option("--header-media <url>", "header image/video/doc URL for a media-header template (default: the template's own stored image)")
     .option("--force-remap", "ignore the saved mapping and rebuild interactively")
     .action((orgId, opts) => broadcastCmd.map(orgId, opts));
   broadcast.command("preview <organization_id>")
@@ -378,6 +379,7 @@ export function run(argv) {
     .option("--template <name>", "template (default: from the saved campaign)")
     .option("--csv <file>", "CSV (default: from the saved campaign)")
     .option("--campaign <name>", "campaign id / config file slug")
+    .option("--header-media <url>", "override the media-header image URL (default: the template's stored image)")
     .option("--rows <n>", "how many sample rows to render", "3")
     .action((orgId, opts) => broadcastCmd.preview(orgId, opts));
   broadcast.command("send <organization_id>")
@@ -388,6 +390,8 @@ export function run(argv) {
     .option("--body <k=v>", "with --tag: body param (repeatable), e.g. --body param1=\"Hi {{first_name}}\"", broadcastCmd.collectKV, {})
     .option("--button <k=v>", "with --tag: dynamic URL button param, e.g. --button param1=<short-code>", broadcastCmd.collectKV, {})
     .option("--campaign <name>", "campaign id / config file slug (default: CSV filename / tag)")
+    .option("--header-media <url>", "header image/video/doc URL for a media-header template (default: the template's own stored image)")
+    .option("--python", "with --tag: send via the python /meta-broadcast engine (same as the dashboard's Python toggle; fire-and-forget, python-tracked)")
     .option("--commit", "actually send (omit to dry-run)")
     .option("--yes", "skip the type-the-campaign-name confirm gate (CI)")
     .option("--force-remap", "ignore the saved mapping and rebuild interactively")