@flowapt/flowiq-cli 0.3.2 → 0.3.3

package/README.md

@@ -187,9 +187,15 @@ 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`).
+- **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,7 @@ 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. |
 | 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.3",
   "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() });
@@ -730,12 +747,17 @@ 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.`);
@@ -769,7 +791,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 +821,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 +852,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 +865,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)}`);

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