@flowapt/flowiq-cli 0.4.8 → 0.4.9

package/README.md

@@ -187,8 +187,9 @@ flowiq ct list
 
 - **Always `--dry-run` first** on a production agent — it prints added/removed/changed tool names before you commit.
 - **Destructive pushes are blocked by default**: a push that removes a tool, disables one, or sends an empty `tools[]` (wiping everything) writes nothing and shows you exactly what it would strip — re-run with `--confirm` if intentional. Additive/no-op pushes are unaffected.
-- Server-side validation is strict: tool `name` (`^[a-zA-Z0-9_-]{1,64}$`, no duplicates), non-empty `description`, `http(s)` `endpoint`, method `GET/POST/PUT/PATCH/DELETE`, object-typed `parameters`/`headers`/`injected_parameters`, valid `auth_type`/`channels`. Bad payloads are rejected before anything writes.
-- **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`, …).
+- Server-side validation is strict: tool `name` (`^[a-zA-Z0-9_-]{1,64}$`, no duplicates), non-empty `description`, `http(s)` `endpoint`, method `GET/POST/PUT/PATCH/DELETE`, object-typed `parameters`/`headers`/`injected_parameters`, valid `auth_type`/`channels`. Recursive JSON schemas are supported, including arrays of objects and integer/min/max constraints. Bad payloads are rejected before anything writes.
+- **Warnings (non-blocking):** unknown keys (likely typos the runtime would silently ignore) and unknown `{{placeholders}}` (they will NOT be substituted at runtime; known values include `organization_id`, `contact_id`, `agent_id`, `contact_whatsapp_id`, `contact_full_name`, `whatsapp_message_id`, `supabase_anon_key`, `openai_api_key`).
+- **Retailer gateway credential:** `{{retailer_tools_internal_key}}` is super-admin-only and resolves only as the `x-api-key` value for `https://express.chatcart.io/retailer-tools/*` (or loopback in local tests). Validation and runtime both reject putting it in a body or sending it to any other host.
 - `--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-remote|status|retry|list` (alias `bc`)
@@ -319,8 +320,29 @@ flowiq bc scheduled cancel  <org_id> <queue_id> --confirm
   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.
+- **Scope**: Meta orgs, POSITIONAL templates, text / no header / media header,
+  and **carousel templates (tag mode only, v0.4.9)**. NAMED templates and WATI
+  orgs are refused with a clear message; carousels in CSV mode are refused with
+  a pointer to tag mode.
+- **Carousel templates (v0.4.9, `send --tag` only, always the python engine):**
+  the CLI introspects every card (header format, body variables, buttons) and
+  builds the per-card send payload python's `/meta-broadcast` expects. Card
+  media defaults to each card's **stored template image** (written by
+  `create-meta-template` at creation), overridable with repeatable
+  `--card-media <url>` (one per card, in card order); every resolved URL is
+  content-type probed against that card's own IMAGE/VIDEO format (mismatch
+  aborts, per card). Cards whose body carries `{{n}}` variables, or whose URL
+  buttons carry a variable, **require `--cards-file <path>`** — a JSON array
+  with one entry per card:
+  `[{"header_media":"<url>","body_params":{"param1":"…"},"button_payloads":{"btn0":"…"},"url_vars":{"btn1":"<value>"}}, …]`
+  (all keys optional per card; quick-reply payloads default to the button text;
+  `{{first_name}}`-style tokens inside card values are resolved per contact).
+  Carousel sends route to the **python engine at any size** — the per-row Node
+  engine cannot send carousels — so there is no CLI write-ahead log / `resume`
+  for them; audit via `bc status <broadcastId>`. `--at` scheduling works: the
+  card payload is frozen into the queued request. `bc retry` on a carousel
+  broadcast re-resolves card media from the template's stored defaults and does
+  NOT replay per-card body/url values — retry only carousels that need none.
 - **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
@@ -623,6 +645,16 @@ flowiq m pull <contact_id> --count 25
 
 `--count` defaults to 25, max 200.
 
+**When you ask for more than exists, you get the WHOLE history (16 Aug 2026).**
+If the contact has fewer `user-*` messages than `--count`, there is nothing
+older to withhold, so the pull returns every row from the first message onward
+and reports `reached_start: true` (`user msgs: 1/25 requested — that is ALL of
+them; this pull is the entire history`). Before this, the anchor sat on the
+oldest inbound message and silently dropped everything before it — so on a
+contact whose conversation OPENS with an outbound (a delivery notification, a
+broadcast), the message that STARTED the conversation was missing while the
+pull still printed success.
+
 ### Audit log — `flowiq audit [org] | audit show <id>` (v0.3.8)
 
 **Who changed what, when — with the full before/after content.** Every

package/TEAM-GUIDE.md

@@ -114,6 +114,7 @@ When you see it, run `npm i -g @flowapt/flowiq-cli` — a stale version also mea
 | See / approve / cancel what's scheduled | `flowiq bc scheduled list <org_id>` → `flowiq bc scheduled approve <org_id> <queue_id>` or `flowiq bc scheduled cancel <org_id> <queue_id> --confirm` |
 | 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>}}`). Sending a **different template to the SAME tag**? Add a distinct `--campaign <name>` — otherwise the CLI aborts (a campaign belongs to one template; reusing it would send the first template's image + skip everyone it already reached). |
 | 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 a **CAROUSEL** template (v0.4.9) | Tag mode only: `flowiq bc send <org_id> --tag <batch-tag> --template <carousel_name> --body param1="Hi {{first_name}}" --commit`. Card images are automatic (each card's stored template image, type-verified per card); override with repeatable `--card-media <url>` (one per card, in order). If the cards carry `{{n}}` body variables or URL-button variables, the CLI tells you exactly what to put in a `--cards-file <path>` JSON (one entry per card: `header_media` / `body_params` / `button_payloads` / `url_vars`). Always sends via the python engine (any size); no CSV mode for carousels. |
 | 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`) |
@@ -123,7 +124,7 @@ When you see it, run `npm i -g @flowapt/flowiq-cli` — a stale version also mea
 | **See who changed what, and when** | `flowiq audit <org_id>` — add `--endpoint prompts`, `--user <name>`, `--since 2026-07-01` to narrow |
 | See exactly what a change looked like (before → after) | `flowiq audit show <audit_id> --content` (or `--out entry.json`) |
 | Know what the log does and doesn't keep | Anything that CHANGES something is logged — including `flowiq test` (it creates the test contact and clears conversations) and `flowiq auth refresh`. Reads and dry-runs are not. The log never stores the content itself: chats, store data and agent replies are recorded as "who read what", never copied. |
-| Read a contact's chat | `flowiq m pull <contact_id>` then open the JSON |
+| Read a contact's chat | `flowiq m pull <contact_id>` then open the JSON. Ask for more than exists (`--count 100`) and you get the entire history — it says "that is ALL of them" when there is nothing older |
 | 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` |
 | Manage Shopify/Woo platform webhooks | `flowiq wh pull <org_id>` → edit → `flowiq wh push <slug>` |
@@ -168,6 +169,10 @@ flowiq ct push <slug>
 Custom tools define real HTTP calls the agent can execute, so the server
 validates hard (names, URLs, methods, parameter shapes) and warns about typo'd
 keys or `{{placeholders}}` it doesn't recognise. Take the warnings seriously.
+Nested object/array schemas are supported. For ChatCart retailer tools, use
+`{{retailer_tools_internal_key}}` only as the `x-api-key` auth value on the
+trusted `express.chatcart.io/retailer-tools/*` gateway; org/contact identity is
+injected server-side and mutations use `{{whatsapp_message_id}}` for idempotency.
 
 ### Example: tag a segment of contacts (Advanced Tagging)
 

package/package.json

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

@@ -380,11 +380,121 @@ function headerMismatchMessage(template, headerMedia, contentType, { explicit })
     : `${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}`;
 }
 
+// ---------------------------------------------------------------------------
+// carousel card resolution (18 Aug 2026 — tag mode, python engine only)
+// ---------------------------------------------------------------------------
+// Builds the card_overrides[] payload python's /meta-broadcast expects: one
+// entry per card, in card order. Media precedence per card: --cards-file entry
+// header_media → --card-media (positional) → the template's stored default
+// (template_data.carousel.cards[i].header_url, surfaced by introspect). Every
+// resolved URL is content-type probed against that CARD's own header format —
+// a carousel can mix IMAGE and VIDEO cards, so this is per-card, not global.
+// Cards with {{n}} body variables or URL-button variables REQUIRE a
+// --cards-file entry (python emits '' for a missing url var → Meta rejects the
+// whole message, so we refuse client-side). Exported for the test harness.
+
+export async function resolveCarouselCards(template, { cardMediaFlags = [], cardsFileEntries = null } = {}, probe = probeContentType) {
+  const cards = template.carousel_cards || [];
+  const aborts = [], warnings = [], lines = [];
+  const overrides = [];
+  if (!cards.length) {
+    aborts.push("carousel template, but the server returned no card details — api.flowiq.live needs the carousel-aware deploy (api/cli/_introspect.js); until then use the dashboard");
+    return { aborts, warnings, overrides: null, lines };
+  }
+  if (cardMediaFlags.length && cardMediaFlags.length !== cards.length) {
+    aborts.push(`--card-media given ${cardMediaFlags.length} time(s) but the template has ${cards.length} cards — pass one per card, in card order`);
+  }
+  if (cardsFileEntries !== null && (!Array.isArray(cardsFileEntries) || cardsFileEntries.length !== cards.length)) {
+    aborts.push(`--cards-file must be a JSON array with exactly ${cards.length} entries (one per card, in card order)`);
+  }
+  if (aborts.length) return { aborts, warnings, overrides: null, lines };
+
+  for (let i = 0; i < cards.length; i++) {
+    const card = cards[i];
+    const fileEntry = (cardsFileEntries?.[i] && typeof cardsFileEntries[i] === "object") ? cardsFileEntries[i] : {};
+    const media = fileEntry.header_media || cardMediaFlags[i] || card.header_media_default || null;
+    if (!media) {
+      aborts.push(`card ${i + 1}: no media resolved — the template stores no default for this card; pass --card-media <url> (one per card, in order) or a --cards-file entry with header_media`);
+      continue;
+    }
+    const contentType = await probe(media);
+    let mediaLabel;
+    if (!contentType) {
+      warnings.push(`card ${i + 1}: media unverified — ${media} did not answer a type probe`);
+      mediaLabel = `${card.header_format} · unverified`;
+    } else if (contentType.split("/")[0] !== card.header_format) {
+      aborts.push(`card ${i + 1}: the template card header is ${card.header_format.toUpperCase()} but the resolved media (${media}) serves ${contentType} — point it at a real ${card.header_format}`);
+      continue;
+    } else {
+      mediaLabel = `${card.header_format} ✓ ${contentType}`;
+    }
+
+    // Per-card body variables must be supplied — python sends only what we pass.
+    let bodyParams = null;
+    if (card.body_positions.length) {
+      bodyParams = fileEntry.body_params && typeof fileEntry.body_params === "object" ? fileEntry.body_params : null;
+      const badKeys = bodyParams ? Object.keys(bodyParams).filter((k) => !/^param\d+$/.test(k)) : [];
+      if (badKeys.length) { aborts.push(`card ${i + 1}: body_params keys must be param1..N (got ${badKeys.join(", ")})`); continue; }
+      const missing = card.body_positions.filter((p) => !bodyParams?.[`param${p}`]);
+      if (missing.length) {
+        aborts.push(`card ${i + 1}: its body carries variable(s) ${missing.map((p) => `{{${p}}}`).join(", ")} — supply them via --cards-file (entry ${i}: {"body_params":{${card.body_positions.map((p) => `"param${p}":"…"`).join(",")}}}). {{first_name}}-style tokens inside the values are resolved per contact.`);
+        continue;
+      }
+    }
+
+    // URL buttons WITH a variable need a send-side value; static URL / QUICK_REPLY do not
+    // (quick-reply payloads default to the button text server-side).
+    const urlVarButtons = (card.buttons || []).filter((b) => b.type === "URL" && b.has_url_var);
+    let urlVars = null;
+    if (urlVarButtons.length) {
+      urlVars = fileEntry.url_vars && typeof fileEntry.url_vars === "object" ? fileEntry.url_vars : null;
+      const missing = urlVarButtons.filter((b) => {
+        const v = urlVars?.[`btn${b.index}`] ?? urlVars?.[String(b.index)];
+        return v === undefined || v === null || String(v) === "";
+      });
+      if (missing.length) {
+        aborts.push(`card ${i + 1}: button(s) ${missing.map((b) => `"${b.text ?? "URL"}"`).join(", ")} carry a URL variable — supply via --cards-file (entry ${i}: {"url_vars":{${missing.map((b) => `"btn${b.index}":"<value>"`).join(",")}}})`);
+        continue;
+      }
+    }
+    const buttonPayloads = fileEntry.button_payloads && typeof fileEntry.button_payloads === "object" ? fileEntry.button_payloads : null;
+
+    overrides.push({
+      file_url: media,
+      ...(bodyParams ? { body_parameters: bodyParams } : {}),
+      ...(buttonPayloads ? { button_payloads: buttonPayloads } : {}),
+      ...(urlVars ? { url_vars: urlVars } : {}),
+    });
+
+    // Preview lines for the dry-run.
+    let bodyPreview = card.body_text || "";
+    for (const [k, v] of Object.entries(bodyParams || {})) bodyPreview = bodyPreview.replaceAll(`{{${k.replace("param", "")}}}`, String(v));
+    const btnBits = (card.buttons || []).map((b) => {
+      if (b.type === "URL" && b.has_url_var) {
+        const v = urlVars?.[`btn${b.index}`] ?? urlVars?.[String(b.index)] ?? "";
+        return `[${b.text ?? "URL"} → ${String(b.url || "").replace(/\{\{[^}]+\}\}/, String(v))}]`;
+      }
+      if (b.type === "URL") return `[${b.text ?? "URL"} → ${b.url}]`;
+      return `[${b.text ?? b.type}]`;
+    }).join(" ");
+    lines.push(`    Card ${i + 1} (${mediaLabel}): ${media}`);
+    if (bodyPreview) lines.push(`      ${bodyPreview.replace(/\n/g, " ")}`);
+    if (btnBits) lines.push(`      ${btnBits}`);
+  }
+  return { aborts, warnings, overrides: aborts.length ? null : overrides, lines };
+}
+
+function printCarouselPlan(cardOverrides, cardLines) {
+  if (!cardOverrides?.length) return;
+  console.log(`  Carousel (${cardOverrides.length} cards — media re-uploaded to Meta once per broadcast):`);
+  for (const l of cardLines) console.log(l);
+}
+
 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 (template.is_carousel) aborts.push("V-3: carousel templates are TAG-MODE only — use: flowiq bc send <org> --tag <tag> --template <name> (the python engine sends carousels; per-row CSV carousel sends are not supported)");
   // 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.
@@ -793,12 +903,13 @@ export function collectKV(pair, mapAcc) {
  *  (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 }) {
+async function runPythonTagSend(orgId, { opts, tag, templateName, template, headerMedia, bodyLiterals, buttonLiteral, commitStage, cardOverrides = null, cardLines = [] }) {
   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 } : {}),
+    ...(cardOverrides ? { card_overrides: cardOverrides } : {}),
     dry_run: dryRun,
   });
 
@@ -813,6 +924,7 @@ async function runPythonTagSend(orgId, { opts, tag, templateName, template, head
   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);
+  printCarouselPlan(cardOverrides, cardLines);
   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)");
   }
@@ -867,12 +979,28 @@ async function runTagPipeline(orgId, opts, { commitStage }) {
     ? (opts.headerMedia || cfg?.header_media || template.header_media_default || null)
     : null;
   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" : ""}`);
+  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" : ""}${template.is_carousel ? `, CAROUSEL (${template.carousel_cards?.length ?? "?"} cards)` : ""}`);
   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");
+  // Carousel templates (18 Aug 2026): supported in tag mode via the python
+  // engine. Resolve + verify every card BEFORE any other gate so a dry run
+  // reports the full card plan (or every card problem at once).
+  let carouselPlan = null;
+  if (template.is_carousel) {
+    let cardsFileEntries = null;
+    let cardsFileBroken = false;
+    if (opts.cardsFile) {
+      try { cardsFileEntries = JSON.parse(await fs.readFile(opts.cardsFile, "utf8")); }
+      catch (e) { aborts.push(`--cards-file ${opts.cardsFile}: ${e.message}`); cardsFileBroken = true; }
+    }
+    if (!cardsFileBroken) {
+      carouselPlan = await resolveCarouselCards(template, { cardMediaFlags: opts.cardMedia || [], cardsFileEntries });
+      for (const w of carouselPlan.warnings) console.log(`⚠ ${w}`);
+      aborts.push(...carouselPlan.aborts);
+    }
+  }
   // 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);
@@ -885,14 +1013,22 @@ async function runTagPipeline(orgId, opts, { commitStage }) {
   // gated by exactly the same checks as an immediate one (APPROVED, positional,
   // param arithmetic, header-media type). Instead of sending we queue the send
   // for later; python resolves the tag at FIRE time, so the audience is fresh.
-  if (opts.at) return scheduleTagSend(orgId, { opts, tag, templateName, template, headerMedia, bodyLiterals, buttonLiteral, commitStage });
+  const cardOverrides = carouselPlan?.overrides ?? null;
+  const cardLines = carouselPlan?.lines ?? [];
+
+  if (opts.at) return scheduleTagSend(orgId, { opts, tag, templateName, template, headerMedia, bodyLiterals, buttonLiteral, commitStage, cardOverrides, cardLines });
 
   // ENGINE ROUTING (policy): any send of MORE THAN 10 recipients ALWAYS uses the
   // python /meta-broadcast engine (the proven bulk sender). --python forces it at
   // any size; only a ≤10 send stays on the resumable per-row Node engine.
+  // Carousels are python at ANY size — the per-row Node engine
+  // (/api/send-template) has no carousel support.
   const PYTHON_MIN = 10;
-  if (opts.python) {
-    return runPythonTagSend(orgId, { opts, tag, templateName, template, headerMedia, bodyLiterals, buttonLiteral, commitStage });
+  if (template.is_carousel && !opts.python) {
+    console.log("Carousel template → PYTHON engine at any size (the per-row Node engine cannot send carousels).");
+  }
+  if (opts.python || template.is_carousel) {
+    return runPythonTagSend(orgId, { opts, tag, templateName, template, headerMedia, bodyLiterals, buttonLiteral, commitStage, cardOverrides, cardLines });
   }
 
   // resolve the tag server-side (broadcast-safe recipients only). A >2000 tag
@@ -985,6 +1121,10 @@ export async function map(orgId, opts = {}) {
   let intro;
   try { intro = await introspect(orgId, opts.template); }
   catch (e) { console.error(`Template introspection failed: ${e.message}`); if (e.body?.error) console.error(`  ${e.body.error}`); process.exit(1); }
+  if (intro.template.is_carousel) {
+    console.error("Carousel templates are TAG-MODE only (no CSV mapping) — use: flowiq bc send <org> --tag <tag> --template <name>.");
+    process.exit(1);
+  }
   let csv;
   try { csv = await loadCsv(opts.csv); }
   catch (e) { console.error(`CSV error: ${e.message}`); process.exit(1); }
@@ -1050,7 +1190,7 @@ const fmtSast = (iso) =>
   new Date(iso).toLocaleString("en-ZA", { timeZone: "Africa/Johannesburg", dateStyle: "medium", timeStyle: "short" });
 
 /** Queue a tag broadcast to fire later (server writes the api_request_queue row). */
-async function scheduleTagSend(orgId, { opts, tag, templateName, template, headerMedia, bodyLiterals, buttonLiteral, commitStage }) {
+async function scheduleTagSend(orgId, { opts, tag, templateName, template, headerMedia, bodyLiterals, buttonLiteral, commitStage, cardOverrides = null, cardLines = [] }) {
   const when = parseSastAt(opts.at);
   if (when.error) { console.error(`Error: --at ${when.error}`); process.exit(1); }
   if (new Date(when.iso).getTime() <= Date.now()) {
@@ -1061,13 +1201,14 @@ async function scheduleTagSend(orgId, { opts, tag, templateName, template, heade
 
   console.log("");
   renderPreview(template, { rownum: 1, number: "(resolved at send time)", values: bodyLiterals, buttonValue: buttonLiteral }, headerMedia);
+  printCarouselPlan(cardOverrides, cardLines);
   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 at send time)");
   }
   console.log("");
   console.log(`Schedule:    ${fmtSast(when.iso)} SAST${when.explicitOffset ? "" : "  (--at read as SAST)"}`);
   console.log(`Audience:    tag "${tag}" — resolved when it FIRES, not now (so late joiners are included)`);
-  console.log(`Engine:      python /meta-broadcast`);
+  console.log(`Engine:      python /meta-broadcast${cardOverrides ? ` · carousel, ${cardOverrides.length} cards (frozen into the queued request)` : ""}`);
   console.log(needsApproval
     ? `Approval:    REQUIRED — parks as 'request'; run "flowiq bc scheduled approve" before it can fire`
     : `Approval:    none — fires automatically at the scheduled time`);
@@ -1090,6 +1231,7 @@ async function scheduleTagSend(orgId, { opts, tag, templateName, template, heade
       body_parameters: bodyLiterals,
       ...(buttonLiteral ? { button_parameters: { param1: buttonLiteral } } : {}),
       ...(headerMedia ? { header_media: headerMedia } : {}),
+      ...(cardOverrides ? { card_overrides: cardOverrides } : {}),
     });
   } catch (e) {
     console.error(`Schedule failed: ${e.message}`);

package/src/commands/messages.js

@@ -56,8 +56,11 @@ export async function pull(contactId, opts = {}) {
   if (resp.organization_name) {
     console.log(`  organization:   ${resp.organization_name} (${resp.organization_id})`);
   }
-  console.log(`  user msgs:      ${resp.user_messages_found}/${resp.user_messages_requested} requested`);
-  console.log(`  anchor:         ${resp.anchor_created_at}`);
+  console.log(
+    `  user msgs:      ${resp.user_messages_found}/${resp.user_messages_requested} requested` +
+    (resp.reached_start ? ` — that is ALL of them; this pull is the entire history` : '')
+  );
+  console.log(`  anchor:         ${resp.anchor_created_at}${resp.reached_start ? ' (start of history)' : ''}`);
   console.log(`  total rows:     ${resp.total_rows}`);
   console.log(`  by sender:`);
   for (const [k, v] of Object.entries(resp.sender_breakdown).sort()) {

package/src/index.js

@@ -432,6 +432,8 @@ export function run(argv) {
     .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("--card-media <url>", "with --tag, carousel templates: card image/video URL in card order (repeatable — one per card; default: each card's stored template image)", (v, acc) => (acc || []).concat([v]), [])
+    .option("--cards-file <path>", "with --tag, carousel templates: JSON file of per-card overrides [{header_media?, body_params?, button_payloads?, url_vars?}] — required when cards carry {{n}} body variables or URL-button variables")
     .option("--python", "with --tag: force the python /meta-broadcast engine (same as the dashboard's Python toggle). NOTE: any tag send >10 recipients ALWAYS uses python automatically")
     .option("--at <when>", "with --tag: SCHEDULE instead of sending now — \"YYYY-MM-DD HH:MM\" in SAST (e.g. --at \"2026-08-05 09:00\"). Fires automatically; audience is resolved at send time")
     .option("--needs-approval", "with --at: park it awaiting approval (flowiq bc scheduled approve) instead of firing automatically")