@flowapt/flowiq-cli 0.7.3 → 0.7.5

package/README.md

@@ -193,7 +193,7 @@ flowiq ct list
 - **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`)
+### Broadcast — `flowiq broadcast map|preview|send|resume|list-remote|status|route|retry|list` (alias `bc`)
 
 Send an **APPROVED** WhatsApp template to every row of a CSV, filling the
 template's variables **per row** from the CSV's own columns. The
@@ -237,6 +237,16 @@ flowiq bc scheduled list <org_id>                   # open rows (pending + await
 flowiq bc scheduled list <org_id> --all             # incl. fired / cancelled
 flowiq bc scheduled approve <org_id> <queue_id>     # 'request' → 'pending' (--at re-times it)
 flowiq bc scheduled cancel  <org_id> <queue_id> --confirm
+
+# REPLY ROUTING (v0.7.4): assign EVERY reply to this broadcast to a team / person.
+flowiq bc send <org_id> --tag <batch-tag> --template <name> --body param1="…" \
+  --route-team "Spa" --commit                       # typed replies AND button taps → the Spa team
+flowiq bc send … --route-team "Spa" --route-member kim@client.com --route-window 48h --no-route-notify
+flowiq bc send … --csv people.csv --campaign 17Sep_Spa --route-team "Spa" --at "2026-09-18 09:00" --commit
+
+flowiq bc route <org_id> <broadcastId>                                   # show what a broadcast routes to + how many chats it has routed
+flowiq bc route <org_id> <broadcastId> --team "Spa" --commit             # set it on a broadcast that already went out
+flowiq bc route <org_id> <broadcastId> --clear --commit                  # switch it off
 ```
 
 - **Scheduling (v0.4.4 tag / v0.6.1 CSV)** — `--at "YYYY-MM-DD HH:MM"` queues the
@@ -295,6 +305,37 @@ flowiq bc scheduled cancel  <org_id> <queue_id> --confirm
   template. In **tag mode the campaign slug defaults to the tag**, so to send
   template A then template B to the SAME tag, pass a distinct `--campaign` for
   each. `resume` passes no `--template`, so it is never affected.
+- **Reply routing — `--route-team` / `--route-member` on `send`, and `bc route` (v0.7.4)**:
+  "every reply to this broadcast goes to team X / person Y". The first message a
+  recipient sends inside the window (default **72 h** after the send, `--route-window
+  48h|3d`, max 14 d) assigns the chat — **once per recipient per broadcast** — and
+  notifies the target through the normal assignment notification (the Teams-page
+  notify settings + the org's two notification flags still decide whether anything is
+  actually sent; `--no-route-notify` assigns silently). It is the fix for the gap a
+  quick-reply button + exact keyword + `assign_chat` cannot close: that route only
+  catches button TAPS, and a broad keyword mutes the AI agent. Routing is a side
+  effect — **keywords and the AI agent answer exactly as they would have**, and it
+  also applies to a chat whose agent is switched off. Skipped: business auto-replies
+  ("thank you for contacting…", out of office) and opt-outs (`stop`). An internal
+  note in the chat says why it was assigned. **An existing assignment is
+  overwritten**, same as the keyword action.
+  - `--route-team` takes a team name (case-insensitive; a unique partial match is
+    fine) or id; `--route-member` takes an email, a name or an id and must be an
+    ACTIVE member of that org. A typo stops the run in the **dry run** with the org's
+    teams listed — nothing is tagged, queued or sent.
+  - The routing is stored on the broadcast (`broadcasts.reply_routing`), so it
+    **forces the python engine at any size** (the per-row Node engine writes one
+    broadcast per recipient). Works in tag mode, CSV mode and with `--at` (the queued
+    send carries it and it is applied the moment the send fires).
+  - After a commit the CLI prints `Replies → … ✓ saved`. If it prints **REPLY ROUTING
+    NOT SAVED / NOT CONFIRMED**, the messages still went out — fix it straight away
+    with `bc route <org> <broadcastId> --team … --commit`.
+  - `bc route` with no flags shows the current routing and how many chats it has
+    routed; with `--team/--member` sets it; `--clear` removes it. Dry-run unless
+    `--commit`, audited. Only replies arriving AFTER the change are routed — nothing
+    is applied retroactively. `bc status` prints the routing too.
+  - Using routing AND a button keyword with `assign_chat` on the same campaign is
+    harmless but notifies twice on a tap — drop the keyword's assign when routing is on.
 - **`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
@@ -414,8 +455,22 @@ instead of a CSV. Same guards, same status log, same resume:
 ```bash
 flowiq bc send <org_id> --tag july-promo-batch-01 --template fresh_drop_v1 \
   --body param1="Hi {{first_name}}" [--button param1=<short-code>] --commit
+
+# A template with TWO link buttons (v0.7.5), e.g. one per product: one --button per button,
+# in the order the buttons appear on the template.
+flowiq bc send <org_id> --tag new-arrivals-batch-01 --template new_arrivals_v3 \
+  --button param1=<cycle-harmony-code> --button param2=<neuroshyft-code> --commit
 ```
 
+**Link buttons (v0.7.5):** every button whose URL carries a `{{1}}` needs its own
+`--button paramN=` value (`param1` = the first such button, `param2` = the
+second). The dry run prints each button's final URL and stops if one is
+missing (WhatsApp rejects the whole message when a link button is empty); a
+value with no button to go to is ignored with a warning. Swapping the codes per
+batch is how one campaign gets per-batch click counts: mint each batch's links
+with the same `--campaign` and a different `--content`. CSV mode fills one link
+button only, so a two-button template is refused there.
+
 Values are shared across the tag (use `{{first_name}}` etc. for per-contact
 personalization — resolved server-side). Supported per-contact tokens:
 `{{first_name}}` `{{full_name}}` `{{email}}` `{{phone_number}}`

package/TEAM-GUIDE.md

@@ -167,11 +167,14 @@ several.
 | 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 a template with TWO link buttons (e.g. one per product) and track clicks per batch | Mint two short links per batch with the same campaign and a different `--content` (e.g. `--content CycleHarmony_b01` and `--content NeuroShyft_b01`), then `flowiq bc send <org_id> --tag <batch-tag> --template <name> --button param1=<first-code> --button param2=<second-code>`. `param1` is the first link button on the template, `param2` the second. The dry run prints both final URLs and stops if either is missing. Tag mode only (v0.7.5). |
 | 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`) |
 | See WHO failed on a broadcast + why (Meta error) | `flowiq bc status <org_id> <broadcastId> --failures` |
 | Re-send a broadcast to only the ones that failed | `flowiq bc retry <org_id> <broadcastId>` (dry-run) → `… --commit` |
+| Make EVERY reply to a broadcast land with a team or a person (client asks "all replies to the Spa team") | Add `--route-team "Spa"` (and/or `--route-member kim@client.com`) to the `bc send`. The first reply from each recipient within 72 hours (`--route-window 48h` to change) assigns the chat and notifies them, typed replies and button taps alike. The AI agent and keywords still answer as normal, so nothing is muted. The dry run shows `Replies → team Spa …`; a wrong team name stops the run and lists the org's teams. Works with `--csv` and `--at` too. |
+| Add, check or remove that routing on a broadcast that already went out | `flowiq bc route <org_id> <broadcastId>` shows it and how many chats it has routed · `… --team "Spa" --commit` sets it · `… --clear --commit` removes it. Only replies from now on are affected. |
 | **Get an OLD version of a prompt back** | `flowiq prompts history <org_id>` (pick the version) → `flowiq prompts restore <org_id> <audit_id>` (dry-run) → `… --commit` |
 | **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`) |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flowapt/flowiq-cli",
-  "version": "0.7.3",
+  "version": "0.7.5",
   "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/button-params.test.mjs

@@ -0,0 +1,50 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { resolveButtonParams, checkButtonParams } from "./commands/broadcast.js";
+
+const oneBtn = { dynamic_url_buttons: 1, url_button: { present: true } };
+const twoBtn = { dynamic_url_buttons: 2, url_button: { present: true } };
+const noBtn = { dynamic_url_buttons: 0, url_button: { present: false } };
+
+test("flags win over the saved campaign", () => {
+  assert.deepEqual(resolveButtonParams({ param1: "a", param2: "b" }, { button_params_literal: { param1: "x" } }), { param1: "a", param2: "b" });
+});
+
+test("saved multi-button values, then the pre-0.7.5 single value", () => {
+  assert.deepEqual(resolveButtonParams({}, { button_params_literal: { param1: "x", param2: "y" } }), { param1: "x", param2: "y" });
+  assert.deepEqual(resolveButtonParams({}, { button_param_literal: "old" }), { param1: "old" });
+  assert.deepEqual(resolveButtonParams(undefined, null), {});
+});
+
+test("empty values are dropped", () => {
+  assert.deepEqual(resolveButtonParams({ param1: "a", param2: "" }, null), { param1: "a" });
+});
+
+test("one dynamic button: same message as before", () => {
+  assert.deepEqual(checkButtonParams(oneBtn, {}).aborts, ["template has a dynamic URL button — pass --button param1=<code>"]);
+  assert.deepEqual(checkButtonParams(oneBtn, { param1: "abc" }), { aborts: [], warnings: [] });
+});
+
+test("two dynamic buttons need both values", () => {
+  const r = checkButtonParams(twoBtn, { param1: "abc" });
+  assert.equal(r.aborts.length, 1);
+  assert.match(r.aborts[0], /2 dynamic URL buttons/);
+  assert.match(r.aborts[0], /missing param2/);
+  assert.deepEqual(checkButtonParams(twoBtn, { param1: "a", param2: "b" }), { aborts: [], warnings: [] });
+});
+
+test("a value with no button is a warning, not an abort", () => {
+  const r = checkButtonParams(oneBtn, { param1: "a", param2: "b" });
+  assert.deepEqual(r.aborts, []);
+  assert.match(r.warnings[0], /param2 ignored/);
+  assert.match(checkButtonParams(noBtn, { param1: "a" }).warnings[0], /0 dynamic URL buttons/);
+});
+
+test("non-param keys abort", () => {
+  assert.match(checkButtonParams(oneBtn, { code: "a", param1: "b" }).aborts[0], /param1\.\.N/);
+});
+
+test("older server without dynamic_url_buttons falls back to url_button", () => {
+  assert.equal(checkButtonParams({ url_button: { present: true } }, {}).aborts.length, 1);
+  assert.equal(checkButtonParams({ url_button: { present: false } }, {}).aborts.length, 0);
+});

package/src/commands/broadcast.js

@@ -502,6 +502,7 @@ function validateRows(template, mapping, headers, rows, illegalChars, headerMedi
   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.dynamic_url_buttons ?? 0) > 1) aborts.push(`V-3: this template has ${template.dynamic_url_buttons} dynamic URL buttons; CSV mode fills one — use tag mode: flowiq bc send <org> --tag <tag> --template <name> --button param1=<code> --button param2=<code>`);
   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 /
@@ -604,12 +605,64 @@ function renderPreview(template, sample, headerMedia) {
   console.log(`Row ${sample.rownum}  →  ${sample.number}   [VALID]${sample.sanitized ? " (sanitized)" : ""}`);
   if (headerMedia) console.log(`  Header (${template.header_type}): ${headerMedia}`);
   console.log(`  Body:\n    ${bodyText.replace(/\n/g, "\n    ")}`);
+  // Two-dynamic-button templates (17 Sep 2026): show every button with its own value.
+  if (Array.isArray(template.url_buttons) && template.url_buttons.length && sample.buttonParams) {
+    for (const b of template.url_buttons) {
+      const v = sample.buttonParams[b.param];
+      if (v == null) continue;
+      console.log(`  Button "${b.text ?? "URL"}" (${b.param}) → ${b.url_base.replace(/\{\{[^}]+\}\}/, v)}`);
+    }
+    return;
+  }
   if (template.url_button?.present && sample.buttonValue != null) {
     const url = template.url_button.url_base.replace(/\{\{[^}]+\}\}/, sample.buttonValue);
     console.log(`  Button "${template.url_button.text ?? "URL"}" → ${url}`);
   }
 }
 
+/** Tag-mode URL-button values: every `--button paramN=…` flag, else the saved
+ *  campaign's values (new `button_params_literal`, or the pre-0.7.5 single
+ *  `button_param_literal` as param1). Empty values are dropped. */
+export function resolveButtonParams(flagButtons, cfg) {
+  const out = {};
+  const src = flagButtons && Object.keys(flagButtons).length
+    ? flagButtons
+    : (cfg?.button_params_literal && Object.keys(cfg.button_params_literal).length
+      ? cfg.button_params_literal
+      : (cfg?.button_param_literal ? { param1: cfg.button_param_literal } : {}));
+  for (const [k, v] of Object.entries(src)) {
+    if (v == null || String(v) === "") continue;
+    out[k] = String(v);
+  }
+  return out;
+}
+
+/** Checks tag-mode button values against the template's dynamic URL buttons.
+ *  Every button needs its own value (python / send-template send '' for a
+ *  missing one and Meta rejects the message); a value with no button to go to
+ *  is a warning (it is ignored by both engines). */
+export function checkButtonParams(template, buttonParams) {
+  const aborts = [];
+  const warnings = [];
+  const keys = Object.keys(buttonParams || {});
+  const bad = keys.filter((k) => !/^param\d+$/.test(k));
+  if (bad.length) aborts.push(`--button keys must be param1..N (got ${bad.join(", ")})`);
+  const need = Number.isInteger(template.dynamic_url_buttons)
+    ? template.dynamic_url_buttons
+    : (template.url_button?.present ? 1 : 0);
+  const missing = [];
+  for (let i = 1; i <= need; i++) if (!buttonParams?.[`param${i}`]) missing.push(`param${i}`);
+  if (missing.length) {
+    const how = Array.from({ length: need }, (_, i) => `--button param${i + 1}=<code>`).join(" ");
+    aborts.push(need === 1
+      ? "template has a dynamic URL button — pass --button param1=<code>"
+      : `template has ${need} dynamic URL buttons — pass ${how} (missing ${missing.join(", ")})`);
+  }
+  const extra = keys.filter((k) => /^param\d+$/.test(k) && Number(k.slice(5)) > need);
+  if (extra.length) warnings.push(`--button ${extra.join(", ")} ignored: template has ${need} dynamic URL button${need === 1 ? "" : "s"}`);
+  return { aborts, warnings };
+}
+
 // ---------------------------------------------------------------------------
 // CSV → python fan-out builders (v0.6.0). Exported for the test harness.
 // ---------------------------------------------------------------------------
@@ -695,7 +748,9 @@ async function sendOne(apiUrl, orgId, templateName, row, headerMedia) {
     templateName,
     whatsappNumber: row.number,
     bodyParameters,
-    ...(row.buttonValue != null ? { buttonParameters: { param1: row.buttonValue } } : {}),
+    ...(row.buttonParams && Object.keys(row.buttonParams).length
+      ? { buttonParameters: row.buttonParams }
+      : (row.buttonValue != null ? { buttonParameters: { param1: row.buttonValue } } : {})),
     // Static media header (same field the dashboard passes for image/video/doc
     // headers) — /api/send-template renders it onto the HEADER component.
     ...(headerMedia ? { headerMedia } : {}),
@@ -944,6 +999,10 @@ async function runPipeline(orgId, opts, { commitStage, isResume }) {
     }
   }
 
+  // Reply routing: resolved before the dry-run exit so the preview shows it, and
+  // before the upsert so a bad team name never tags a single contact.
+  const replyRouting = isResume ? null : await checkRouting(orgId, opts);
+
   if (!commitStage) {
     console.log("");
     console.log(`DRY RUN — nothing was ${scheduledAt ? "scheduled" : "sent"}, no contacts written or tagged. Add --commit to ${scheduledAt ? "queue it" : "send"}.`);
@@ -968,6 +1027,7 @@ async function runPipeline(orgId, opts, { commitStage, isResume }) {
     body_parameters: tokens.body,
     ...(tokens.button ? { button_parameters: { param1: tokens.button } } : {}),
     ...(headerMedia ? { header_media: headerMedia } : {}),
+    ...(replyRouting ? { reply_routing: replyRouting } : {}),
     dry_run: dryRun,
   });
   let pyTotal = null;
@@ -1013,6 +1073,7 @@ async function runPipeline(orgId, opts, { commitStage, isResume }) {
         body_parameters: tokens.body,
         ...(tokens.button ? { button_parameters: { param1: tokens.button } } : {}),
         ...(headerMedia ? { header_media: headerMedia } : {}),
+        ...(replyRouting ? { reply_routing: replyRouting } : {}),
       });
     } catch (e) {
       console.error(`Schedule failed: ${e.message}${e.body?.error ? ` — ${e.body.error}` : ""}`);
@@ -1035,6 +1096,10 @@ async function runPipeline(orgId, opts, { commitStage, isResume }) {
       console.log(`      flowiq bc scheduled approve ${orgId} ${resp.queue_id}`);
     }
     console.log(`  Also visible/manageable on the dashboard's Scheduled sends page.`);
+    if (replyRouting) {
+      if (resp.reply_routing?.saved) console.log(`  Replies → ${describeRouting(resp.reply_routing.requested)}  ✓ queued with the send (applied the moment it fires)`);
+      else console.log(`  ⚠ REPLY ROUTING NOT CONFIRMED by the server — set it after it fires with: flowiq bc route ${orgId} <broadcast_id> --team … --commit`);
+    }
     return;
   }
 
@@ -1052,6 +1117,7 @@ async function runPipeline(orgId, opts, { commitStage, isResume }) {
   console.log(`   Python is sending in the background to tag "${tag}" (${pyTotal ?? workSet.length} contact(s)) and tracking it under that broadcast id.`);
   console.log(`   Delivery:  flowiq bc status ${orgId} ${out.broadcastId || "<broadcast_id>"} [--failures]`);
   console.log(`   Failures:  flowiq bc retry  ${orgId} ${out.broadcastId || "<broadcast_id>"} --commit`);
+  if (replyRouting) reportRoutingResult(orgId, out.reply_routing, out.broadcastId ?? out.broadcast_id ?? null);
 }
 
 /** The paced, write-ahead-logged per-row send loop + final report. */
@@ -1146,13 +1212,99 @@ 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, cardOverrides = null, cardLines = [] }) {
+// ── Reply routing (v0.7.4) ───────────────────────────────────────────────────
+// `--route-team` / `--route-member` = "assign every reply to this broadcast to …".
+// The server resolves names → ids, stores it on the broadcast, and the agent runtime
+// applies it once per recipient inside the window WITHOUT muting keywords or the AI.
+
+/** "72" | "72h" | "3d" → whole hours, or { error }. */
+export function parseRouteWindow(input) {
+  if (input === undefined || input === null || input === "") return { hours: null };
+  const m = String(input).trim().toLowerCase().match(/^(\d{1,4})\s*(h|hr|hrs|hours?|d|days?)?$/);
+  if (!m) return { error: `"${input}" is not a window — use hours or days, e.g. 72, 72h or 3d` };
+  const n = Number(m[1]);
+  const hours = m[2] && m[2].startsWith("d") ? n * 24 : n;
+  if (hours < 1 || hours > 336) return { error: `the window must be between 1 hour and 14 days (got ${hours} h)` };
+  return { hours };
+}
+
+/** The send flags → the request's reply_routing object (null when no routing asked for). */
+export function routingFromOpts(opts = {}, keys = { team: "routeTeam", member: "routeMember", window: "routeWindow", notify: "routeNotify" }) {
+  const team = typeof opts[keys.team] === "string" ? opts[keys.team].trim() : "";
+  const member = typeof opts[keys.member] === "string" ? opts[keys.member].trim() : "";
+  const hasWindow = opts[keys.window] !== undefined && opts[keys.window] !== null && opts[keys.window] !== "";
+  const noNotify = opts[keys.notify] === false;
+  if (!team && !member) {
+    if (hasWindow || noNotify) return { error: "the routing window / no-notify flags need a team or a member to route to" };
+    return { routing: null };
+  }
+  const win = parseRouteWindow(opts[keys.window]);
+  if (win.error) return { error: win.error };
+  return {
+    routing: {
+      ...(team ? { team } : {}),
+      ...(member ? { member } : {}),
+      ...(win.hours ? { window_hours: win.hours } : {}),
+      ...(noNotify ? { notify: false } : {}),
+    },
+  };
+}
+
+export function describeRouting(d) {
+  if (!d) return "none";
+  const who = [d.team_name ? `team ${d.team_name}` : null, d.member_name || d.member_email || null].filter(Boolean).join(" + ") || "(unnamed target)";
+  const notes = [];
+  if (d.team_name) notes.push(d.notify_team === false ? "team not notified" : "team notified");
+  if (d.member_name || d.member_email) notes.push(d.notify_member === false ? "person not notified" : "person notified");
+  return `${who} · first reply within ${d.window_hours ?? 72} h · ${notes.join(", ")}`;
+}
+
+/** Resolve the routing on the server BEFORE anything is tagged, queued or sent. Exits on a bad team/member. */
+async function checkRouting(orgId, opts) {
+  const parsed = routingFromOpts(opts);
+  if (parsed.error) { console.error(`Error: ${parsed.error}`); process.exit(1); }
+  if (!parsed.routing) return null;
+  let resp;
+  try { resp = await http.post("broadcast", { action: "resolve-routing", organization_id: orgId, reply_routing: parsed.routing }); }
+  catch (e) {
+    console.error(`Reply routing refused: ${e.body?.error || e.message}`);
+    if (/unknown action|Unknown action|not supported/i.test(String(e.body?.error || "")) || e.status === 404) {
+      console.error("  (the server does not know reply routing yet — run `flowiq doctor`)");
+    }
+    process.exit(1);
+  }
+  if (!resp?.reply_routing) {
+    console.error("Reply routing refused: the server did not confirm it (it may predate v0.7.4 — run `flowiq doctor`). Nothing sent.");
+    process.exit(1);
+  }
+  console.log(`Replies →    ${describeRouting(resp.reply_routing)}`);
+  console.log(`             (assigned once per recipient; keywords and the AI agent still answer as normal)`);
+  return parsed.routing;
+}
+
+/** After a commit: say plainly whether the routing landed. */
+function reportRoutingResult(orgId, rr, broadcastId) {
+  if (!rr) {
+    console.log("   ⚠ REPLY ROUTING NOT CONFIRMED by the server — replies will NOT be assigned.");
+    if (broadcastId) console.log(`     Fix now: flowiq bc route ${orgId} ${broadcastId} --team … --commit`);
+    return;
+  }
+  if (rr.saved) console.log(`   Replies → ${describeRouting(rr.requested)}  ✓ saved`);
+  else {
+    console.log(`   ⚠ REPLY ROUTING NOT SAVED: ${rr.error || "unknown reason"}`);
+    if (broadcastId) console.log(`     Fix now: flowiq bc route ${orgId} ${broadcastId} --team … --commit`);
+  }
+}
+
+async function runPythonTagSend(orgId, { opts, tag, templateName, template, headerMedia, bodyLiterals, buttonLiteral, buttonParams = null, commitStage, cardOverrides = null, cardLines = [], replyRouting = null }) {
+  const buttons = buttonParams && Object.keys(buttonParams).length ? buttonParams : (buttonLiteral ? { param1: buttonLiteral } : null);
   const reqBody = (dryRun) => ({
     action: "send-python", organization_id: orgId, tag, template_name: templateName,
     body_parameters: bodyLiterals,
-    ...(buttonLiteral ? { button_parameters: { param1: buttonLiteral } } : {}),
+    ...(buttons ? { button_parameters: buttons } : {}),
     ...(headerMedia ? { header_media: headerMedia } : {}),
     ...(cardOverrides ? { card_overrides: cardOverrides } : {}),
+    ...(replyRouting ? { reply_routing: replyRouting } : {}),
     dry_run: dryRun,
   });
 
@@ -1166,7 +1318,7 @@ async function runPythonTagSend(orgId, { opts, tag, templateName, template, head
   console.log(`Engine: PYTHON (yapi.store/meta-broadcast) — fire-and-forget, python-tracked.`);
   console.log(`Tag "${tag}": ${total} eligible contact(s) (allow_broadcast + not blocked, resolved server-side).`);
   const sampleNum = dry.sample_contacts?.[0]?.whatsapp_id || dry.sample_contacts?.[0]?.phone_number || "<first eligible>";
-  renderPreview(template, { rownum: 1, number: sampleNum, values: bodyLiterals, buttonValue: buttonLiteral }, headerMedia);
+  renderPreview(template, { rownum: 1, number: sampleNum, values: bodyLiterals, buttonValue: buttonLiteral, buttonParams: buttons }, 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)");
@@ -1189,6 +1341,7 @@ async function runPythonTagSend(orgId, { opts, tag, templateName, template, head
   console.log("");
   console.log(`✅ ${out.message || "Broadcast started"}${out.broadcastId ? `  ·  broadcastId ${out.broadcastId}` : ""}`);
   console.log(`   Python is sending in the background${out.mode ? ` (${out.mode})` : ""} and tracking it under that broadcast id — no CLI resume for this engine.`);
+  if (replyRouting) reportRoutingResult(orgId, out.reply_routing, out.broadcastId ?? out.broadcast_id ?? null);
 }
 
 async function runTagPipeline(orgId, opts, { commitStage }) {
@@ -1210,7 +1363,8 @@ async function runTagPipeline(orgId, opts, { commitStage }) {
     process.exit(1);
   }
   const bodyLiterals = Object.keys(opts.body || {}).length ? opts.body : (cfg?.body_params_literal ?? {});
-  const buttonLiteral = (opts.button && opts.button.param1) ?? cfg?.button_param_literal ?? null;
+  const buttonParams = resolveButtonParams(opts.button, cfg);
+  const buttonLiteral = buttonParams.param1 ?? null;
 
   // introspect + validate params arithmetically (the #132000 guard, pre-send)
   let intro;
@@ -1222,7 +1376,7 @@ 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" : ""}${template.is_carousel ? `, CAROUSEL (${template.carousel_cards?.length ?? "?"} cards)` : ""}`);
+  console.log(`Template ${template.name} [${template.status}] — ${template.parameter_format}, ${template.body_var_count} body var(s), header ${template.header_type}${headerCheck.label}${(template.dynamic_url_buttons ?? 0) > 1 ? `, ${template.dynamic_url_buttons} dynamic URL buttons` : (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`);
@@ -1249,7 +1403,9 @@ async function runTagPipeline(orgId, opts, { commitStage }) {
   const keys = Object.keys(bodyLiterals);
   if (keys.some((k) => !/^param\d+$/.test(k))) aborts.push(`--body keys must be param1..N (got ${keys.join(", ")})`);
   if (keys.length !== template.body_var_count) aborts.push(`template expects ${template.body_var_count} body param(s), you provided ${keys.length} (--body paramN=…). Values may use {{first_name}}/{{full_name}}/{{email}}/{{phone_number}} — resolved per contact.`);
-  if (template.url_button?.present && !buttonLiteral) aborts.push("template has a dynamic URL button — pass --button param1=<code>");
+  const buttonCheck = checkButtonParams(template, buttonParams);
+  for (const w of buttonCheck.warnings) console.log(`⚠ ${w}`);
+  aborts.push(...buttonCheck.aborts);
   if (aborts.length) { for (const a of aborts) console.error(`ABORT — ${a}`); process.exit(1); }
 
   // SCHEDULE (--at): validation above has already run, so a scheduled send is
@@ -1259,7 +1415,11 @@ async function runTagPipeline(orgId, opts, { 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 });
+  // Reply routing is resolved HERE — after the template checks, before any engine is
+  // picked — so a mistyped team stops the run in the dry run, not after a send.
+  const replyRouting = await checkRouting(orgId, opts);
+
+  if (opts.at) return scheduleTagSend(orgId, { opts, tag, templateName, template, headerMedia, bodyLiterals, buttonLiteral, buttonParams, commitStage, cardOverrides, cardLines, replyRouting });
 
   // 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
@@ -1270,8 +1430,13 @@ async function runTagPipeline(orgId, opts, { 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 });
+  // Reply routing lives on ONE broadcasts row, which only the python engine creates per
+  // send (the per-row Node engine writes a row per recipient) → python at any size.
+  if (replyRouting && !opts.python && !template.is_carousel) {
+    console.log("Reply routing → PYTHON engine at any size (the routing is stored on the single broadcast python creates).");
+  }
+  if (opts.python || template.is_carousel || replyRouting) {
+    return runPythonTagSend(orgId, { opts, tag, templateName, template, headerMedia, bodyLiterals, buttonLiteral, buttonParams, commitStage, cardOverrides, cardLines, replyRouting });
   }
 
   // resolve the tag server-side (broadcast-safe recipients only). A >2000 tag
@@ -1281,13 +1446,13 @@ async function runTagPipeline(orgId, opts, { commitStage }) {
   catch (e) {
     if (e.status === 413) {
       console.log(`Tag "${tag}" has >2000 contacts → PYTHON engine (any send >${PYTHON_MIN} uses python).`);
-      return runPythonTagSend(orgId, { opts, tag, templateName, template, headerMedia, bodyLiterals, buttonLiteral, commitStage });
+      return runPythonTagSend(orgId, { opts, tag, templateName, template, headerMedia, bodyLiterals, buttonLiteral, buttonParams, commitStage });
     }
     console.error(`Tag resolution failed: ${e.message}`); if (e.body?.error) console.error(`  ${e.body.error}`); process.exit(1);
   }
   if (resolved.recipients.length > PYTHON_MIN) {
     console.log(`Tag "${tag}": ${resolved.recipients.length} sendable (>${PYTHON_MIN}) → PYTHON engine (any send >${PYTHON_MIN} uses python).`);
-    return runPythonTagSend(orgId, { opts, tag, templateName, template, headerMedia, bodyLiterals, buttonLiteral, commitStage });
+    return runPythonTagSend(orgId, { opts, tag, templateName, template, headerMedia, bodyLiterals, buttonLiteral, buttonParams, commitStage });
   }
   console.log(`Tag "${tag}" on ${resolved.organization_name}: ${resolved.tagged_total} contact(s), ${resolved.recipients.length} sendable, ${resolved.excluded.length} excluded (opt-out/archived/blocked).`);
   if (!resolved.recipients.length) { console.log("Nothing sendable under this tag."); return; }
@@ -1295,7 +1460,7 @@ async function runTagPipeline(orgId, opts, { commitStage }) {
   const values = {};
   for (const [k, v] of Object.entries(bodyLiterals)) values[k] = String(v);
   let sendable = resolved.recipients.map((r, i) => ({
-    rownum: i + 1, number: r.number, values, buttonValue: buttonLiteral, contactName: r.full_name,
+    rownum: i + 1, number: r.number, values, buttonValue: buttonLiteral, buttonParams, contactName: r.full_name,
   }));
   if (opts.limit) sendable = sendable.slice(0, Number(opts.limit));
 
@@ -1341,7 +1506,7 @@ async function runTagPipeline(orgId, opts, { commitStage }) {
     schema_version: 1, campaign, mode: "tag",
     organization_id: orgId, organization_slug: slugify(resolved.organization_name, orgId.slice(0, 8)),
     template_name: templateName, tag,
-    body_params_literal: bodyLiterals, button_param_literal: buttonLiteral,
+    body_params_literal: bodyLiterals, button_param_literal: buttonLiteral, button_params_literal: buttonParams,
     ...(headerMedia ? { header_media: headerMedia } : {}),
     created_at: cfg?.created_at ?? new Date().toISOString(),
   });
@@ -1433,7 +1598,8 @@ 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, cardOverrides = null, cardLines = [] }) {
+async function scheduleTagSend(orgId, { opts, tag, templateName, template, headerMedia, bodyLiterals, buttonLiteral, buttonParams = null, commitStage, cardOverrides = null, cardLines = [], replyRouting = null }) {
+  const buttons = buttonParams && Object.keys(buttonParams).length ? buttonParams : (buttonLiteral ? { param1: buttonLiteral } : null);
   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()) {
@@ -1443,7 +1609,7 @@ async function scheduleTagSend(orgId, { opts, tag, templateName, template, heade
   const needsApproval = !!opts.needsApproval;
 
   console.log("");
-  renderPreview(template, { rownum: 1, number: "(resolved at send time)", values: bodyLiterals, buttonValue: buttonLiteral }, headerMedia);
+  renderPreview(template, { rownum: 1, number: "(resolved at send time)", values: bodyLiterals, buttonValue: buttonLiteral, buttonParams: buttons }, 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)");
@@ -1472,9 +1638,10 @@ async function scheduleTagSend(orgId, { opts, tag, templateName, template, heade
       scheduled_for: when.iso,
       needs_approval: needsApproval,
       body_parameters: bodyLiterals,
-      ...(buttonLiteral ? { button_parameters: { param1: buttonLiteral } } : {}),
+      ...(buttons ? { button_parameters: buttons } : {}),
       ...(headerMedia ? { header_media: headerMedia } : {}),
       ...(cardOverrides ? { card_overrides: cardOverrides } : {}),
+      ...(replyRouting ? { reply_routing: replyRouting } : {}),
     });
   } catch (e) {
     console.error(`Schedule failed: ${e.message}`);
@@ -1491,6 +1658,10 @@ async function scheduleTagSend(orgId, { opts, tag, templateName, template, heade
     console.log(`  ⚠ PARKED awaiting approval — it will NOT fire until you run:`);
     console.log(`      flowiq bc scheduled approve ${orgId} ${resp.queue_id}`);
   }
+  if (replyRouting) {
+    if (resp.reply_routing?.saved) console.log(`  Replies → ${describeRouting(resp.reply_routing.requested)}  ✓ queued with the send (applied the moment it fires)`);
+    else console.log(`  ⚠ REPLY ROUTING NOT CONFIRMED by the server — cancel and re-schedule, or set it after it fires with: flowiq bc route ${orgId} <broadcast_id> --team … --commit`);
+  }
 }
 
 /** List scheduled broadcasts (queue rows). Read-only. */
@@ -1515,6 +1686,7 @@ export async function scheduledList(orgId, opts = {}) {
     console.log(`    ${fmtSast(s.scheduled_for)} SAST · ${s.status}${flag}`);
     console.log(`    template ${s.template_name ?? "?"} → tag ${s.tag ?? "?"} · ${s.engine} · via ${s.source}${s.scheduled_by ? ` (${s.scheduled_by})` : ""}`);
     if (s.audience_at_schedule != null) console.log(`    ~${s.audience_at_schedule} recipients at schedule time`);
+    if (s.reply_routing) console.log(`    replies → ${describeRouting(s.reply_routing)}`);
     if (s.processed_at) console.log(`    fired ${fmtSast(s.processed_at)} SAST${s.broadcast_id ? ` · broadcastId ${s.broadcast_id}` : ""}`);
     if (s.error_message) console.log(`    error: ${s.error_message}`);
   }
@@ -1628,6 +1800,11 @@ export async function status(orgId, broadcastId, opts = {}) {
   if (b.total_recipients) {
     console.log(`    ${((accepted / b.total_recipients) * 100).toFixed(1)}% of ${b.total_recipients} recipients accepted${d.linked < b.total_recipients ? "  (still sending?)" : ""}`);
   }
+  if (resp.reply_routing) {
+    const rr = resp.reply_routing;
+    console.log(`  replies →   ${describeRouting(rr)}${rr.enabled === false ? "  (switched OFF)" : ""}`);
+    console.log(`              ${rr.routed} chat(s) routed so far${rr.set_by ? ` · set by ${rr.set_by}` : ""}`);
+  }
   if (opts.failures && resp.failures) {
     console.log("");
     console.log(`  Failures by reason:`);
@@ -1641,6 +1818,41 @@ export async function status(orgId, broadcastId, opts = {}) {
   }
 }
 
+/** Show / set / clear reply routing on a broadcast that already exists. Dry run unless --commit. */
+export async function route(orgId, broadcastId, opts = {}) {
+  if (!UUID_RE.test(orgId)) { console.error(`Error: "${orgId}" is not a valid organization UUID.`); process.exit(1); }
+  if (!UUID_RE.test(broadcastId)) { console.error("Error: broadcast id must be a UUID (see `flowiq bc list-remote <org>`)."); process.exit(1); }
+  const parsed = routingFromOpts(opts, { team: "team", member: "member", window: "window", notify: "notify" });
+  if (parsed.error) { console.error(`Error: ${parsed.error}`); process.exit(1); }
+  if (opts.clear && parsed.routing) { console.error("Error: pass --clear OR a --team/--member, not both."); process.exit(1); }
+  let resp;
+  try {
+    resp = await http.post("broadcast", {
+      action: "route", organization_id: orgId, broadcast_id: broadcastId,
+      ...(parsed.routing ? { reply_routing: parsed.routing } : {}),
+      ...(opts.clear ? { clear: true } : {}),
+      commit: !!opts.commit,
+    });
+  } catch (e) { console.error(`Route failed: ${e.body?.error || e.message}`); process.exit(1); }
+  if (opts.json) { console.log(JSON.stringify(resp, null, 2)); return; }
+  const b = resp.broadcast;
+  console.log(`Broadcast ${b.id} — ${resp.organization_name}`);
+  console.log(`  template:   ${b.template_name} · sent ${fmtSast(b.created_at)} SAST · ${b.total_recipients ?? "?"} recipient(s)`);
+  console.log(`  replies →   ${resp.current ? describeRouting(resp.current) : "no routing set"}`);
+  console.log(`              ${resp.routed} chat(s) routed so far`);
+  if (resp.mode === "show") {
+    console.log("");
+    console.log(`Set it:   flowiq bc route ${orgId} ${b.id} --team "<team>" [--member <email>] [--window 72h] [--no-notify] --commit`);
+    console.log(`Clear it: flowiq bc route ${orgId} ${b.id} --clear --commit`);
+    return;
+  }
+  console.log("");
+  console.log(`  ${resp.mode === "clear" ? "CLEAR" : "SET"} →     ${resp.mode === "clear" ? "no routing (replies are no longer assigned)" : describeRouting(resp.next)}`);
+  for (const w of resp.warnings || []) console.log(`  ⚠ ${w}`);
+  if (resp.dry_run) { console.log(""); console.log("DRY RUN — nothing changed. Add --commit to apply."); return; }
+  console.log(`  ✓ saved. Only replies that arrive from now on are routed; chats already routed are left as they are.`);
+}
+
 /** Re-send a broadcast to ONLY its failed recipients (transient-failure recovery).
  *  Reconstructs the send from the broadcasts row + re-fires via python. The dry-run
  *  shows the failed count + reason breakdown; --commit creates a NEW broadcast. */

package/src/index.js

@@ -620,7 +620,7 @@ export function run(argv) {
     .option("--csv <file>", "path to the recipients CSV (per-row values)")
     .option("--tag <tag>", "send to every broadcast-safe contact carrying this tag (e.g. a segments batch tag)")
     .option("--body <k=v>", "with --tag: body param (repeatable), e.g. --body param1=\"Hi {{first_name}}\"", broadcastCmd.collectKV, {})
-    .option("--button <k=v>", "with --tag: dynamic URL button param, e.g. --button param1=<short-code>", broadcastCmd.collectKV, {})
+    .option("--button <k=v>", "with --tag: dynamic URL button value, repeatable for a second button, e.g. --button param1=<code> --button param2=<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]), [])
@@ -628,6 +628,10 @@ export function run(argv) {
     .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>", "SCHEDULE instead of sending now (tag AND CSV mode, v0.6.1) — \"YYYY-MM-DD HH:MM\" in SAST (e.g. --at \"2026-08-05 09:00\"). CSV: rows are imported+tagged NOW, the python call is queued server-side and shows on the dashboard's Scheduled sends page. Fires automatically; the tag is re-resolved at send time")
     .option("--needs-approval", "with --at: park it awaiting approval (flowiq bc scheduled approve) instead of firing automatically")
+    .option("--route-team <team>", "REPLY ROUTING (v0.7.4): assign every reply to this broadcast to this team (name or id). Once per recipient, typed replies AND button taps, without muting keywords or the AI agent. Forces the python engine")
+    .option("--route-member <who>", "REPLY ROUTING: also/instead assign to this person (email, name or id) — must be an active member of the org")
+    .option("--route-window <dur>", "REPLY ROUTING: how long after the send a reply still counts, e.g. 72h or 3d (default 72h, max 14d)")
+    .option("--no-route-notify", "REPLY ROUTING: assign silently — do not send the team/person their assignment notification")
     .option("--commit", "actually send (omit to dry-run)")
     .option("--yes", "skip the type-the-campaign-name confirm gate (CI)")
     .option("--force-remap", "ignore the saved mapping and rebuild interactively")
@@ -679,6 +683,16 @@ export function run(argv) {
     .option("--limit <n>", "with --failures: how many failed rows to print", "40")
     .option("--json", "raw JSON")
     .action((orgId, broadcastId, opts) => broadcastCmd.status(orgId, broadcastId, opts));
+  broadcast.command("route <organization_id> <broadcast_id>")
+    .description("Reply routing on an EXISTING broadcast: no flags = show it; --team/--member = set it; --clear = switch it off. DRY-RUN unless --commit. Only replies arriving after the change are routed")
+    .option("--team <team>", "assign replies to this team (name or id)")
+    .option("--member <who>", "assign replies to this person (email, name or id)")
+    .option("--window <dur>", "how long after the SEND a reply still counts, e.g. 72h or 3d (default 72h, max 14d)")
+    .option("--no-notify", "assign silently (no assignment notification)")
+    .option("--clear", "remove the routing from this broadcast")
+    .option("--commit", "apply (omit to dry-run)")
+    .option("--json", "raw JSON")
+    .action((orgId, broadcastId, opts) => broadcastCmd.route(orgId, broadcastId, opts));
   broadcast.command("retry <organization_id> <broadcast_id>")
     .description("Re-send a broadcast to ONLY its failed recipients (transient-failure recovery). DRY-RUN by default; --commit re-fires via python")
     .option("--commit", "actually re-send (omit to see the failed count + reasons)")

package/src/reply-routing.test.mjs

@@ -0,0 +1,58 @@
+// Reply routing flag parsing (v0.7.4) — pure functions only, no network.
+import test from "node:test";
+import assert from "node:assert/strict";
+import { parseRouteWindow, routingFromOpts, describeRouting } from "./commands/broadcast.js";
+
+test("window: hours, h suffix, days", () => {
+  assert.deepEqual(parseRouteWindow("72"), { hours: 72 });
+  assert.deepEqual(parseRouteWindow("72h"), { hours: 72 });
+  assert.deepEqual(parseRouteWindow(" 3D "), { hours: 72 });
+  assert.deepEqual(parseRouteWindow("14 days"), { hours: 336 });
+  assert.deepEqual(parseRouteWindow(undefined), { hours: null });
+});
+
+test("window: rejects garbage, zero and anything past 14 days", () => {
+  assert.ok(parseRouteWindow("soon").error);
+  assert.ok(parseRouteWindow("0").error);
+  assert.ok(parseRouteWindow("15d").error);
+  assert.ok(parseRouteWindow("-5").error);
+  assert.ok(parseRouteWindow("1.5h").error);
+});
+
+test("no routing flags = no routing, and the send request stays untouched", () => {
+  assert.deepEqual(routingFromOpts({ routeNotify: true }), { routing: null });
+  assert.deepEqual(routingFromOpts({}), { routing: null });
+});
+
+test("a window or --no-route-notify without a target is an error, never a silent no-op", () => {
+  assert.ok(routingFromOpts({ routeWindow: "48h" }).error);
+  assert.ok(routingFromOpts({ routeNotify: false }).error);
+});
+
+test("team + member + window + silent", () => {
+  assert.deepEqual(
+    routingFromOpts({ routeTeam: " Spa ", routeMember: "kim@example.com", routeWindow: "2d", routeNotify: false }),
+    { routing: { team: "Spa", member: "kim@example.com", window_hours: 48, notify: false } },
+  );
+  // Defaults are left to the server (72 h, notify on) — the client sends only what was typed.
+  assert.deepEqual(routingFromOpts({ routeTeam: "Spa", routeNotify: true }), { routing: { team: "Spa" } });
+});
+
+test("a bad window stops the run", () => {
+  assert.ok(routingFromOpts({ routeTeam: "Spa", routeWindow: "whenever" }).error);
+});
+
+test("`bc route` reads its own flag names", () => {
+  const keys = { team: "team", member: "member", window: "window", notify: "notify" };
+  assert.deepEqual(routingFromOpts({ team: "Spa", window: "24", notify: true }, keys), { routing: { team: "Spa", window_hours: 24 } });
+  assert.deepEqual(routingFromOpts({ notify: true }, keys), { routing: null });
+});
+
+test("describeRouting reads like a sentence", () => {
+  assert.equal(describeRouting(null), "none");
+  assert.equal(
+    describeRouting({ team_name: "Spa", member_name: null, window_hours: 72, notify_team: true, notify_member: null }),
+    "team Spa · first reply within 72 h · team notified",
+  );
+  assert.match(describeRouting({ team_name: "Spa", member_name: "Kim", window_hours: 24, notify_team: false, notify_member: false }), /team Spa \+ Kim .* 24 h .* team not notified, person not notified/);
+});