@flowapt/flowiq-cli 0.4.7 → 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
@@ -480,6 +502,47 @@ flowiq tag remove <org_id> vip,old-promo --confirm  # remove tag(s) from ALL con
   matches — re-run until `matched 0`. Idempotent and safe to re-run.
 - **Undo** any tag with `flowiq tag remove <org> <tag> --confirm`.
 
+### Links — `flowiq links shorten|list` (v0.4.8)
+
+Short links with campaign UTM tags — the terminal half of the in-app **URL
+Shortener**. Same engine server-side (`api/_url-shorten-engine.js`), so a link
+minted here is identical to one minted in the dialog.
+
+```bash
+# Dry run FIRST — shows the exact destination each short link will carry
+flowiq links shorten <org> --url "https://shop.co.za/product/x" \
+  --campaign 13Aug_Seeds --content 13Aug_Seeds
+
+flowiq links shorten <org> --url "https://shop.co.za/product/x" \
+  --url "https://shop.co.za/product/y" \
+  --campaign 13Aug_Seeds --content 13Aug_Seeds --domain linklnk.io --commit
+
+flowiq links shorten <org> --file ./slide2.txt --campaign 13Aug_Seeds_VM --content 13Aug_Seeds_VM --commit
+flowiq links list <org> --campaign 13Aug_Seeds
+```
+
+- **`utm_source=whatsapp` and `utm_medium=whatsapp_paid` are FIXED** (the dialog
+  sets them too) — a link built any other way stops matching the attribution
+  queries. You supply `--campaign` and `--content`, and they must be **supplied
+  together**: a campaign with no content silently under-tags every link.
+- **Dry-run by default.** `--commit` mints. The dry run prints the full
+  destination URL per link and whether an identical row already exists.
+- **A new UTM tag = a NEW row with its own code and its own click count.** Reuse
+  is keyed on the exact `(org, full_url)` pair, which is what makes per-campaign
+  attribution work. Re-running the same command is idempotent (`↻ reused`).
+- **Pasting an existing short link is REFUSED** (`chatcart.io` / `linklnk.io` /
+  `yapi.store`) with "pass the destination URL". Shortening a short link would
+  add a second hop and split the click count — and would silently keep the OLD
+  campaign tag, which is the trap this guard exists for.
+- **`--file`** shortens every URL found in a text file — the fast path for a
+  multi-link message body. It does NOT rewrite the file; it prints the mapping.
+- `--domain` picks the short host: `chatcart.io` (default), `linklnk.io`,
+  `yapi.store`. All three resolve identically — match whatever that campaign's
+  other links already use.
+- `--campaign` on **`list`** is an EXACT match, not a prefix: asking for
+  `13Aug_Seeds` does not return the `13Aug_Seeds_VM` rows.
+- Scope group `broadcast`. Audited (`links` / `shorten`); dry runs are not.
+
 ### Keywords — `flowiq keywords pull|push|list` (alias `kw`)
 
 Round-trips an org's **keyword auto-reply engine** — the `keywords` +
@@ -504,10 +567,10 @@ flowiq kw push <slug> --prune            # ALSO deletes DB keywords missing from
   collapses to 1 at runtime — rejected).
 - `field:"attributes"` actions are warned (full jsonb replace; constant
   values only) but applied — this CLI is their only safe editing surface.
-- **Action types accepted** (all nine the runtime implements):
+- **Action types accepted** (all ten the runtime implements):
   `send_message` · `update_contact_field` · `add_contact_tag` ·
   `remove_contact_tag` · `set_agent` · `delay` · `combined` ·
-  `update_ticket_status` · `renotify_ticket`.
+  `update_ticket_status` · `renotify_ticket` · `assign_chat`.
   Per-type rules: tag actions need a non-empty `tags[]` (or a single `tag`
   string) or the runtime writes no tag at all; `set_agent.agent_id` must be
   an agent UUID, or `null`/`""` to CLEAR the contact's binding (warned, since
@@ -530,6 +593,18 @@ flowiq kw push <slug> --prune            # ALSO deletes DB keywords missing from
   ticket-tool `mode:"renotify"` (60s server-side rate limit; a resolved/closed
   ticket is reopened first) — canonical use: the **"I still need help"**
   button. Both send the action's `text` (if any) after the ticket work.
+- **Assign-chat action** (added 13 Aug 2026, for keyword-driven handovers —
+  e.g. a broadcast quick-reply button handing the conversation to a person):
+  `{ "type": "assign_chat", "team_id": "<team-uuid>", "assignee_user_id":
+  "<user-uuid>", "notify_team": true, "notify_member": true }` — writes the
+  contact's `team_id` and/or `assignee` (at least ONE of the two is required,
+  both UUID-shaped; `assignee_user_id` is the profiles/auth user id, not an
+  `organization_members` id), then invokes `team-assignment-notify` for each
+  target unless its `notify_*` flag is explicitly `false`. The notify fn
+  re-checks the org's team/member notification feature flags AND the target's
+  own notify config (Teams page) server-side, so a target with notifications
+  off is assigned silently. Also editable in the dashboard (Keyword Actions →
+  action type "Assign Chat").
 - `action_config.link_preview: false` disables WhatsApp's link-preview card
   on that action's text send (absent/`true` = preview on, the default).
   Passed through verbatim; also toggleable per action in the dashboard.
@@ -570,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
@@ -990,11 +1075,24 @@ flowiq agent config <organization_id> --test-contact-number 27000000001 --test-c
 Settable: `settings.use_settings_prompt`, `settings.model`, agent `--rename`,
 the tool-flag columns (`woo_order_build`, `woo_tip_field`, `woo_order_note_field`,
 `view_cart_tool`, `restock_tool`, `block_tool_status`, `postal_code_tool_status`,
-`shopify_products_web_chat`, `ticket_tool_status`, `collapse_product_variants`),
+`shopify_products_web_chat`, `ticket_tool_status`, `product_lookup`,
+`collapse_product_variants`),
 `discount.enabled`, and the `flowiq test` contact
 (`settings.test_contact_number` / `settings.test_contact_name`). Anything else is
 rejected; every change is reported before → after.
 
+**`--tool product_lookup=true` (added 11 Aug 2026).** Turns on the `product_lookup`
+tool: a typo-tolerant **pg_trgm fuzzy match on `product_title`** (plus badge/tag
+search), as opposed to `get_product_info`, which is **semantic**. This matters far
+beyond typo tolerance: `get_product_info` needs BOTH a populated
+`products_all.embedding` column AND a working OpenAI key (it embeds the query at
+call time), so on an org missing either one, **every** product question fails and
+the agent cannot quote a price, confirm stock, or send a product link.
+`product_lookup` needs neither and reads the row directly. Reach for it whenever an
+agent answers product questions with "I can't pull the live menu". Found on Ouma
+Bets Gebak (11 Aug 2026): 25 product rows, 0 embeddings, and an unfunded OpenAI
+account — enabling this flag restored product answers immediately.
+
 **`--tool collapse_product_variants=true` (added 4 Aug 2026).** Not a tool toggle —
 it changes what `get_product_info` RETURNS. OFF (the default) the result cap counts
 **variant rows**, so on a catalogue with several packaging/size variants per product

package/TEAM-GUIDE.md

@@ -80,6 +80,7 @@ When you see it, run `npm i -g @flowapt/flowiq-cli` — a stale version also mea
 | Edit keyword auto-replies (incl. competition entry keywords, add/remove-tag, set-agent and delay actions) | `flowiq kw pull <org_id>` → edit → `flowiq kw push <slug> --dry-run` → `flowiq kw push <slug>` |
 | Send a **different auto-reply depending on the contact** (e.g. "we already have your email" vs "send us your email") | add `"when": {"field":"email","op":"is_not_empty"}` to one action and `is_empty` to the other — see *Keywords* in `flowiq guide --reference`. CLI-only, no dashboard field yet |
 | Make a follow-up button **close the customer's ticket** ("Query solved") or **re-alert the team** ("I still need help") | keyword action `{"type":"update_ticket_status","status":"resolved"}` / `{"type":"renotify_ticket"}` — see *Keywords* in `flowiq guide --reference`. CLI-only, no dashboard field yet |
+| Make a keyword/button **hand the chat to a team or person** (assign in the inbox + email/WhatsApp them) | keyword action `{"type":"assign_chat","team_id":"…","assignee_user_id":"…","notify_member":true}` — see *Keywords* in `flowiq guide --reference`. Also in the dashboard (action type "Assign Chat") |
 | **Find an org's ID** (needed by nearly every command) | `flowiq org list` — or `flowiq org list african` to filter |
 | What's the stock on a product, per branch? | `flowiq shopify stock <org_id> "olive oil"` — shows each location by NAME, and says "not tracked" rather than a confusing 0 |
 | Has this order shipped? What's the tracking? | `flowiq shopify order <org_id> '#14728'` — status, courier, tracking number + link |
@@ -93,8 +94,13 @@ When you see it, run `npm i -g @flowapt/flowiq-cli` — a stale version also mea
 | See an org's agents / create one | `flowiq agent list <org_id>` / `flowiq agent create <org_id> --name "…"` |
 | Change agent model / tool flags | `flowiq agent config <org_id> --model … --tool view_cart_tool=true` |
 | Agent says an in-stock product "isn't showing" | `flowiq agent config <org_id> --tool collapse_product_variants=true` — the search cap counts VARIANT rows until this is on |
+| Agent can't quote ANY price / "I can't pull the live menu" | `flowiq agent config <org_id> --tool product_lookup=true` — name-based fuzzy lookup that works without embeddings or a live OpenAI key (semantic `get_product_info` needs both) |
 | Talk to the live agent safely (no real WhatsApp ever sent) | `flowiq test send <org_id> "hi, do you sell X?"` |
 | Set which contact `flowiq test` uses (use a FAKE number!) | `flowiq agent config <org_id> --test-contact-number 27000000001 --test-contact-name "QA Bot"` |
+| **Make short links for a campaign** (with UTM tracking) | `flowiq links shorten <org_id> --url "https://shop.co.za/product/x" --campaign 13Aug_Seeds --content 13Aug_Seeds` (dry run) → `… --commit`. `utm_source`/`utm_medium` are set for you; campaign + content must be given together |
+| Short links for every URL in a message | `flowiq links shorten <org_id> --file ./message.txt --campaign X --content X --commit` |
+| Check which links a campaign has, and their clicks | `flowiq links list <org_id> --campaign 13Aug_Seeds` |
+| A link already looks short (`linklnk.io/abc123`) — can I re-tag it? | No: paste the DESTINATION url instead. Re-shortening keeps the old campaign tag and splits the click count, so the CLI refuses it |
 | Send a template broadcast to a CSV of people | `flowiq bc map <org_id> --template … --csv …` → `flowiq bc send … ` (dry-run) → `… --commit` |
 | Tag every repeat buyer (e.g. 2+ orders in the last 60 days) | `flowiq seg plan <org_id> --tag-prefix repeat-60d --min-orders 2 --window 60d` → `flowiq seg apply <org_id> repeat-60d` (dry run) → `… --commit` |
 | Tag everyone who bought a product (accurate, windowable) | `flowiq seg plan <org_id> --tag-prefix whey --bought "Whey" --window 90d` → `flowiq seg apply … --commit` |
@@ -108,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`) |
@@ -117,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>` |
@@ -162,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.7",
+  "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/links.js

@@ -0,0 +1,144 @@
+// `flowiq links` — short links + campaign UTM tags from the terminal.
+//
+// The terminal half of the in-app URL Shortener. Same engine server-side
+// (api/_url-shorten-engine.js), so a link minted here is identical to one minted
+// in the dialog: utm_source=whatsapp, utm_medium=whatsapp_paid fixed, campaign +
+// content yours.
+//
+//   flowiq links shorten <org> --url <u> [--url <u2>…] --campaign 13Aug_Seeds --content 13Aug_Seeds
+//   flowiq links shorten <org> --file ./message.txt --campaign X --content X --domain linklnk.io
+//   flowiq links list <org> [--campaign X] [--limit 25]
+//
+// Dry-run FIRST (`--dry-run`) on anything going into a real campaign: it shows
+// the exact destination URL each short link will carry, and whether an identical
+// row already exists (so you can see you are about to reuse an OLD campaign tag).
+
+import fs from "node:fs";
+import { http } from "../http.js";
+
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const URL_PATTERN = /(https?:\/\/[^\s\)]+)/g;
+
+function requireOrg(orgId) {
+  if (!UUID_RE.test(orgId)) {
+    console.error(`Error: "${orgId}" is not a valid organization UUID. Find it with: flowiq org list <name>`);
+    process.exit(1);
+  }
+}
+
+export async function shorten(orgId, opts = {}) {
+  requireOrg(orgId);
+
+  // Collect URLs: repeatable --url, and/or every URL found in --file.
+  const urls = [...(opts.url || [])];
+  if (opts.file) {
+    let text;
+    try {
+      text = fs.readFileSync(opts.file, "utf8");
+    } catch (e) {
+      console.error(`Error: could not read --file ${opts.file}: ${e.message}`);
+      process.exit(1);
+    }
+    const found = text.match(URL_PATTERN) || [];
+    if (!found.length) console.error(`⚠ No URLs found in ${opts.file}`);
+    urls.push(...found);
+  }
+  if (!urls.length) {
+    console.error("Error: pass at least one --url <url>, or --file <path> containing URLs.");
+    process.exit(1);
+  }
+
+  // Dedupe while preserving order — the same URL twice would otherwise print twice.
+  const seen = new Set();
+  const unique = urls.filter((u) => {
+    const k = u.trim();
+    if (seen.has(k)) return false;
+    seen.add(k);
+    return true;
+  });
+
+  const dryRun = opts.dryRun !== false && opts.commit !== true;
+
+  let resp;
+  try {
+    resp = await http.post("links", {
+      organization_id: orgId,
+      action: "shorten",
+      urls: unique,
+      campaign: opts.campaign,
+      content: opts.content,
+      domain: opts.domain,
+      dry_run: dryRun,
+    });
+  } catch (e) {
+    console.error(`Shorten failed: ${e.message}`);
+    process.exit(1);
+  }
+
+  if (opts.json) { console.log(JSON.stringify(resp, null, 2)); return; }
+
+  const utm = resp.utm
+    ? `utm_source=${resp.utm.source} · utm_medium=${resp.utm.medium} · utm_campaign=${resp.utm.campaign} · utm_content=${resp.utm.content}`
+    : "no UTM tags (plain short link)";
+  console.log(`${resp.organization_name} · ${resp.domain}`);
+  console.log(`${utm}\n`);
+
+  for (const r of resp.results) {
+    const label = {
+      created: "✓ created",
+      reused: "↻ reused ",
+      would_create: "· would create",
+      would_reuse: "· would REUSE an existing row",
+      refused_already_short: "✗ refused",
+      invalid_url: "✗ invalid url",
+      failed: "✗ failed",
+    }[r.state] || r.state;
+    console.log(`${label}  ${r.short_url || r.input}`);
+    if (r.full_url) console.log(`            → ${r.full_url}`);
+    if (r.note) console.log(`            ⚠ ${r.note}`);
+  }
+
+  console.log("");
+  if (dryRun) {
+    console.log(`DRY RUN — nothing written. Re-run with --commit to mint these links.`);
+  } else {
+    console.log(`${resp.created} created · ${resp.reused} reused${resp.failed ? ` · ${resp.failed} failed` : ""}`);
+  }
+  // A reuse is not automatically wrong (idempotent re-run), but it means the code
+  // you are about to paste already existed — with whatever campaign tag it was
+  // born with. Worth a second look when you asked for a NEW campaign.
+  const reusedRows = resp.results.filter((r) => r.state === "reused" || r.state === "would_reuse");
+  if (reusedRows.length && resp.utm) {
+    console.log(`⚠ ${reusedRows.length} url(s) already had a row with this exact destination — those keep their existing click history.`);
+  }
+}
+
+export async function list(orgId, opts = {}) {
+  requireOrg(orgId);
+  let resp;
+  try {
+    resp = await http.post("links", {
+      organization_id: orgId,
+      action: "list",
+      campaign: opts.campaign,
+      limit: opts.limit,
+    });
+  } catch (e) {
+    console.error(`List failed: ${e.message}`);
+    process.exit(1);
+  }
+
+  if (opts.json) { console.log(JSON.stringify(resp, null, 2)); return; }
+
+  if (!resp.links.length) {
+    console.log(opts.campaign ? `No links on ${resp.organization_name} for campaign "${opts.campaign}".` : `No links on ${resp.organization_name}.`);
+    return;
+  }
+  const pad = (s, n) => String(s ?? "").padEnd(n);
+  console.log(`${pad("CODE", 10)}${pad("CLICKS", 8)}${pad("CREATED", 12)}URL`);
+  for (const l of resp.links) {
+    const day = String(l.created_at || "").slice(0, 10);
+    console.log(`${pad(l.code, 10)}${pad(l.clicks ?? 0, 8)}${pad(day, 12)}${l.full_url}`);
+  }
+  console.log(`\n${resp.count} link(s)${opts.campaign ? ` · campaign "${opts.campaign}"` : ""}`);
+}

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

@@ -27,6 +27,7 @@ import * as customToolsCmd from "./commands/custom-tools.js";
 import * as broadcastCmd from "./commands/broadcast.js";
 import * as segmentsCmd from "./commands/segments.js";
 import * as tagCmd from "./commands/tag.js";
+import * as linksCmd from "./commands/links.js";
 import * as keywordsCmd from "./commands/keywords.js";
 import * as guideCmd from "./commands/guide.js";
 import * as auditCmd from "./commands/audit.js";
@@ -431,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")
@@ -534,6 +537,26 @@ export function run(argv) {
     .option("--confirm", "required alongside --commit")
     .action((orgId, id, opts) => segmentsCmd.untag(orgId, id, opts));
 
+  // links (short links + campaign UTM tags — the URL Shortener dialog in the terminal; dry-run default)
+  const links = program.command("links")
+    .description("Short links with campaign UTM tags (dry-run by default; --commit to mint)");
+  links.command("shorten <organization_id>")
+    .description("Shorten one or more URLs, tagging each with utm_campaign/utm_content")
+    .option("--url <url>", "URL to shorten (repeatable)", (v, acc) => (acc || []).concat([v]), [])
+    .option("--file <path>", "shorten every URL found in this text file")
+    .option("--campaign <value>", "utm_campaign (e.g. 13Aug_Seeds) — must be paired with --content")
+    .option("--content <value>", "utm_content — must be paired with --campaign")
+    .option("--domain <host>", "short domain: chatcart.io (default) | linklnk.io | yapi.store")
+    .option("--commit", "actually mint the links (omit = dry-run preview)")
+    .option("--json", "raw JSON output")
+    .action((orgId, opts) => linksCmd.shorten(orgId, opts));
+  links.command("list <organization_id>")
+    .description("List the org's short links, newest first")
+    .option("--campaign <value>", "only links carrying this exact utm_campaign")
+    .option("--limit <n>", "max rows (default 25, max 200)")
+    .option("--json", "raw JSON output")
+    .action((orgId, opts) => linksCmd.list(orgId, opts));
+
   // tag (the Advanced Tagging dialog in the terminal — ONE named tag on a matched set; dry-run default)
   const tag = program.command("tag")
     .description("Advanced Tagging: apply one named tag to a matched set of contacts (dry-run by default; --commit to write)");