@flowapt/flowiq-cli 0.4.0 → 0.4.2

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
@@ -395,6 +405,9 @@ flowiq tag segment <org_id> --min-orders 2 --min-spent 1000 --region ZA-GP --tag
 
 # Attributes — broadcast permission (all_contacts / allow_broadcast_true|false / no_broadcast_permission)
 flowiq tag attributes <org_id> --filter allow_broadcast_true --tag broadcastable --commit
+# Big org (cohort > ~20k)? Chunk it: repeat this until it reports "matched 0" —
+# each run tags the next 10k untagged contacts (see the bullet below on the 50k cap / DB timeout)
+flowiq tag attributes <org_id> --filter allow_broadcast_true --limit 10000 --exclude broadcastable --tag broadcastable --commit --yes
 
 # Message activity — ≥ N messages of a sender type, optional date range
 flowiq tag messages <org_id> --min-count 3 --sender user-whatsapp --tag engaged --commit
@@ -412,6 +425,12 @@ flowiq tag remove <org_id> vip,old-promo --confirm  # remove tag(s) from ALL con
 - **`cohort` is top-N, not a threshold** — `top_spenders --limit 500` tags the
   top 500 by spend, not "everyone above £X". Use `tag segment --min-spent` for
   a threshold.
+- **Big orgs: chunk `attributes` commits with `--limit` + `--exclude <your-tag>`**
+  (flags added 3 Aug 2026, in-repo pending publish). The tagging RPC hard-caps at 50,000
+  per call AND a single large commit updates row-by-row, so a ~50k commit dies
+  on the DB statement timeout (full rollback, nothing written). `--limit 10000
+  --exclude <the-tag-you're-adding>` makes each run pick the next 10k untagged
+  matches — re-run until `matched 0`. Idempotent and safe to re-run.
 - **Undo** any tag with `flowiq tag remove <org> <tag> --confirm`.
 
 ### Keywords — `flowiq keywords pull|push|list` (alias `kw`)
@@ -687,6 +706,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

package/TEAM-GUIDE.md

@@ -93,7 +93,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` (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 (accepted → delivered → read, plus failed/pending) | `flowiq bc status <org_id> <broadcastId>` (from the send output, or `bc list-remote`) |
@@ -179,6 +179,18 @@ real order line-items (accurate + windowable) rather than the order-history text
 And a commit over 2000 contacts asks you to type the tag name to confirm
 (add `--yes` to skip). Everything is appends-only and reversible with `tag remove`.
 
+**Tagging a very large audience (20k+, e.g. "everyone opted in") with `attributes`?**
+One giant commit will fail on a database timeout (nothing writes). Chunk it instead:
+
+```bash
+# repeat this exact line until it prints "matched 0" — each run tags the NEXT 10k
+flowiq tag attributes <org_id> --filter allow_broadcast_true \
+  --limit 10000 --exclude my-campaign-tag --tag my-campaign-tag --commit --yes
+```
+
+`--exclude` names the same tag you're adding, so every run skips the people who
+already have it. Safe to re-run as many times as you like.
+
 ## Keys, rotation, logging out
 
 - **`flowiq auth refresh`** — rotates this device's key in place (a fresh key

package/package.json

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

package/src/commands/tag.js

@@ -132,6 +132,7 @@ export async function attributes(orgId, opts = {}) {
   const payload = {
     mode: "attributes", organization_id: orgId, filter_type: opts.filter || "all_contacts",
     include_tags: splitList(opts.include), exclude_tags: splitList(opts.exclude),
+    limit: opts.limit ? Number(opts.limit) : undefined, offset: opts.offset ? Number(opts.offset) : 0,
   };
   await confirmLargeWrite(orgId, payload, opts, `Attributes ${payload.filter_type}`);
   await runMatch(`Attributes ${payload.filter_type}`, payload, opts);

package/src/index.js

@@ -550,6 +550,8 @@ export function run(argv) {
     .option("--filter <f>", "attribute filter", "all_contacts")
     .option("--include <csv>", "only contacts carrying any of these tags")
     .option("--exclude <csv>", "exclude contacts carrying any of these tags")
+    .option("--limit <n>", "max contacts per run (default 50000 — the RPC cap; a 50k commit can hit the DB statement timeout, so chunk big orgs: --limit 10000 --exclude <tag>, re-run until 0 match)")
+    .option("--offset <n>", "skip the first N", "0")
     .option("--tag <name>", "tag to apply (required with --commit)")
     .option("--commit", "write the tag (omit = dry-run count + sample)")
     .option("--yes", "skip the type-the-tag confirm on large (>2000) writes")