@flowapt/flowiq-cli 0.6.0 → 0.6.2

package/README.md

@@ -238,12 +238,20 @@ flowiq bc scheduled approve <org_id> <queue_id>     # 'request' → 'pending' (-
 flowiq bc scheduled cancel  <org_id> <queue_id> --confirm
 ```
 
-- **Scheduling (v0.4.4)** — `--at "YYYY-MM-DD HH:MM"` on a `--tag` send queues it
-  instead of sending. It writes the same `api_request_queue` row the dashboard
-  writes, replayed by the `process-api-queue` cron (every 3 min, so it fires
-  0–3 min after the stated minute). Runs **every** pre-send check first
+- **Scheduling (v0.4.4 tag / v0.6.1 CSV)** — `--at "YYYY-MM-DD HH:MM"` queues the
+  send instead of firing it. It writes the same `api_request_queue` row the
+  dashboard writes, replayed by the `process-api-queue` cron (every 3 min, so it
+  fires 0–3 min after the stated minute). Runs **every** pre-send check first
   (APPROVED, positional, param arithmetic, header-media type) — a scheduled
   send can't skip a guard an immediate one enforces.
+  - **CSV mode (v0.6.1):** the rows are imported + tagged **NOW** (same as an
+    immediate send); only the python call is queued. Scheduled CSV campaigns
+    therefore show on the dashboard's Scheduled sends page and can be
+    approved/cancelled from there or via `bc scheduled` — nothing depends on
+    anyone's laptop being awake at send time. Python re-resolves the tag when
+    it fires, so anyone tagged `bc-<campaign>` in the meantime is included.
+    A scheduled campaign counts as fired for the re-run guard — cancel the
+    queued row first, then re-run with `--resend`.
   - `--at` is always read as **SAST**, never the machine's local timezone, so
     the same command schedules the same instant from anywhere.
   - The **audience resolves when it FIRES**, not when you schedule — someone
@@ -1168,9 +1176,12 @@ flowiq agent config <organization_id>                        # show current
 flowiq agent config <organization_id> --use-settings-prompt --model gpt-5.4-mini \
   --rename Zara --tool woo_order_build=true --tool view_cart_tool=true --discount true
 flowiq agent config <organization_id> --test-contact-number 27000000001 --test-contact-name "QA Bot"
+flowiq agent config <organization_id> --model gpt-5.6-luna --reasoning-effort high
 ```
 
-Settable: `settings.use_settings_prompt`, `settings.model`, agent `--rename`,
+Settable: `settings.use_settings_prompt`, `settings.model`,
+`settings.reasoning_effort` (`--reasoning-effort low|medium|high`, `""` clears it —
+pairs with reasoning models like `gpt-5.6-luna`), 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`, `product_lookup`,

package/TEAM-GUIDE.md

@@ -97,6 +97,7 @@ When you see it, run `npm i -g @flowapt/flowiq-cli` — a stale version also mea
 | Feed store data into jq / a file | stdout is the payload only, banner goes to stderr: `flowiq shopify get <org> orders.json \| jq -r '.orders[].name'` · or `--out ./orders.json` |
 | 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` |
+| Set the house model + reasoning tier | `flowiq agent config <org_id> --model gpt-5.6-luna --reasoning-effort high` |
 | 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?"` |
@@ -114,7 +115,7 @@ When you see it, run `npm i -g @flowapt/flowiq-cli` — a stale version also mea
 | Combine existing tags → a batched send list (include some tags, drop others, split into batches of N) | `flowiq seg plan <org_id> --tag-prefix clearance-bc --from-tag "loyalty-list" --exclude "recent-campaign" --batch-size 1000` → `flowiq seg apply <org_id> clearance-bc --commit` (makes `clearance-bc-batch-01/02/…`) |
 | Split a big id-list cohort into send-safe batch tags | `flowiq seg plan <org_id> --tag-prefix … --ids-file …` → `flowiq seg apply … --commit` |
 | Split a whole tagged audience into batches of N (e.g. 90k → 7000s) | `flowiq seg plan <org_id> --tag-prefix 3-aug-bc --from-tag "3-aug-bc" --batch-size 7000` → `flowiq seg apply <org_id> 3-aug-bc --commit --yes` (makes `…-batch-01…13`; works at any size — big applies are chunked internally) |
-| Schedule a broadcast for later instead of sending now | `flowiq bc send <org_id> --tag <batch-tag> --template <name> --at "2026-08-05 09:00" --commit` (time is SAST; fires on its own; audience resolved at send time) |
+| Schedule a broadcast for later instead of sending now | `flowiq bc send <org_id> --tag <batch-tag> --template <name> --at "2026-08-05 09:00" --commit` (time is SAST; fires on its own; audience resolved at send time). **Works with --csv too (v0.6.1):** rows import+tag immediately, the send queues server-side, and it shows on the dashboard's Scheduled sends page. Nothing depends on your laptop being on at send time. |
 | 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. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flowapt/flowiq-cli",
-  "version": "0.6.0",
+  "version": "0.6.2",
   "description": "Command-line tool for FlowIQ staff: round-trip agent prompts, questionnaires, fine-tuning, pin-board tasks, webhooks, templates, agent-updates, chat exports, and live agent testing without ever touching service-role credentials.",
   "type": "module",
   "bin": {

package/src/commands/agent-config.js

@@ -41,6 +41,7 @@ export async function config(orgId, opts = {}) {
   const settings = {};
   if (opts.useSettingsPrompt !== undefined) settings.use_settings_prompt = parseBool(opts.useSettingsPrompt, "--use-settings-prompt");
   if (opts.model !== undefined) settings.model = opts.model;
+  if (opts.reasoningEffort !== undefined) settings.reasoning_effort = opts.reasoningEffort;
   if (opts.testContactNumber !== undefined) settings.test_contact_number = opts.testContactNumber;
   if (opts.testContactName !== undefined) settings.test_contact_name = opts.testContactName;
   if (Object.keys(settings).length) body.settings = settings;
@@ -75,7 +76,7 @@ export async function config(orgId, opts = {}) {
     }
     console.log(`${resp.organization_name} → agent ${resp.agent_id}${resp.is_active === false ? " [NON-active]" : ""}`);
     printSnapshot("current", resp.current);
-    console.log("\n(pass --use-settings-prompt / --model / --rename / --tool / --discount / --test-contact-number / --test-contact-name to change)");
+    console.log("\n(pass --use-settings-prompt / --model / --reasoning-effort / --rename / --tool / --discount / --test-contact-number / --test-contact-name to change)");
     return;
   }
 

package/src/commands/broadcast.js

@@ -804,10 +804,17 @@ async function runPipeline(orgId, opts, { commitStage, isResume }) {
   const { header: logHeader, map: statusMap, handoff } = await loadStatusLog(campaign);
   if (isResume) {
     if (handoff) {
-      console.error(`Campaign "${campaign}" already fanned out via python on ${handoff.at}${handoff.broadcast_id ? ` (broadcastId ${handoff.broadcast_id})` : ""}.`);
-      console.error("There is no per-row resume on the python engine — python owns the send. Audit / re-fire failures with:");
-      console.error(`  flowiq bc status ${orgId} ${handoff.broadcast_id || "<broadcast_id>"} [--failures]`);
-      console.error(`  flowiq bc retry  ${orgId} ${handoff.broadcast_id || "<broadcast_id>"} --commit`);
+      if (handoff.queue_id) {
+        console.error(`Campaign "${campaign}" is QUEUED via python (queue id ${handoff.queue_id}, fires ${handoff.scheduled_for || "?"}).`);
+        console.error("There is nothing to resume — manage the queued send instead:");
+        console.error(`  flowiq bc scheduled list   ${orgId}`);
+        console.error(`  flowiq bc scheduled cancel ${orgId} ${handoff.queue_id} --confirm`);
+      } else {
+        console.error(`Campaign "${campaign}" already fanned out via python on ${handoff.at}${handoff.broadcast_id ? ` (broadcastId ${handoff.broadcast_id})` : ""}.`);
+        console.error("There is no per-row resume on the python engine — python owns the send. Audit / re-fire failures with:");
+        console.error(`  flowiq bc status ${orgId} ${handoff.broadcast_id || "<broadcast_id>"} [--failures]`);
+        console.error(`  flowiq bc retry  ${orgId} ${handoff.broadcast_id || "<broadcast_id>"} --commit`);
+      }
       process.exit(1);
     }
     if (!logHeader) { console.error(`No status log for campaign "${campaign}" — nothing to resume.`); process.exit(1); }
@@ -868,23 +875,55 @@ async function runPipeline(orgId, opts, { commitStage, isResume }) {
   const tokens = buildCsvTokenParams(template, campaign);
   const batchCap = Math.min(Number(opts.upsertBatch ?? CONTACT_BATCH_CAP) || CONTACT_BATCH_CAP, CONTACT_BATCH_CAP);
   if (opts.skipUpsert) console.log("⚠ --skip-upsert is ignored on the python CSV path — the upsert IS how per-row values reach python.");
+  // --at (v0.6.1): upsert+tag NOW, then QUEUE the python call instead of firing
+  // it — the same api_request_queue row tag sends and the dashboard write,
+  // replayed by the process-api-queue cron. Parsed EARLY so a garbage/past
+  // value aborts before anything is written.
+  let scheduledAt = null;
+  if (opts.at) {
+    scheduledAt = parseSastAt(opts.at);
+    if (scheduledAt.error) { console.error(`Error: --at ${scheduledAt.error}`); process.exit(1); }
+    if (new Date(scheduledAt.iso).getTime() <= Date.now()) {
+      console.error(`ABORT — --at is in the past (${fmtSast(scheduledAt.iso)} SAST). Nothing would ever fire.`);
+      process.exit(1);
+    }
+  }
   console.log(`Engine:      PYTHON server-side fan-out (yapi.store/meta-broadcast) — fire-and-forget, python-paced`);
   console.log(`Tag:         "${tag}"  ·  per-row values → attributes bc_${campaign}_param1..${template.body_var_count}${tokens.button ? " + _button" : ""}`);
-  console.log(`Plan:        upsert+tag ${workSet.length} contact(s) in ${Math.ceil(Math.max(1, workSet.length) / batchCap)} batch(es) → one python broadcast`);
+  console.log(`Plan:        upsert+tag ${workSet.length} contact(s) in ${Math.ceil(Math.max(1, workSet.length) / batchCap)} batch(es) → ${scheduledAt ? "QUEUE one python broadcast" : "one python broadcast"}`);
+  if (scheduledAt) {
+    console.log(`Schedule:    fires ${fmtSast(scheduledAt.iso)} SAST${scheduledAt.explicitOffset ? "" : "  (--at read as SAST)"} — server-side queue row, replayed by the process-api-queue cron (0–3 min after the minute); shows on the dashboard's Scheduled sends page`);
+    console.log(opts.needsApproval
+      ? `Approval:    REQUIRED — parks as 'request'; run "flowiq bc scheduled approve" before it can fire`
+      : `Approval:    none — fires automatically at the scheduled time`);
+  }
 
   // A prior fan-off means the tag already reached its audience — re-running
   // resends to EVERY tagged contact (python cannot skip per row).
   if (handoff && !opts.resend) {
     console.log("");
-    console.log(`⚠ Campaign "${campaign}" ALREADY fanned out via python on ${handoff.at}${handoff.broadcast_id ? ` (broadcastId ${handoff.broadcast_id})` : ""}.`);
-    if (!commitStage) {
-      console.log("  A --commit re-run would resend to EVERY tagged contact (no per-row skip). Audit with bc status; re-fire failures with bc retry; pass --resend to deliberately resend to all.");
+    if (handoff.queue_id) {
+      console.log(`⚠ Campaign "${campaign}" is already QUEUED via python (queue id ${handoff.queue_id}, fires ${handoff.scheduled_for || "?"}).`);
+      if (!commitStage) {
+        console.log("  A --commit re-run would be refused — manage the queued send with bc scheduled list/cancel; pass --resend to run this campaign again (e.g. after cancelling the queued row).");
+      } else {
+        console.error("  Refusing to double-book the tag. Manage the queued send instead:");
+        console.error(`    flowiq bc scheduled list   ${orgId}`);
+        console.error(`    flowiq bc scheduled cancel ${orgId} ${handoff.queue_id} --confirm`);
+        console.error("  To run this campaign again anyway (e.g. after cancelling), pass --resend.");
+        process.exit(1);
+      }
     } else {
-      console.error("  Refusing to resend to the whole tag. Audit / re-fire failures with:");
-      console.error(`    flowiq bc status ${orgId} ${handoff.broadcast_id || "<broadcast_id>"} [--failures]`);
-      console.error(`    flowiq bc retry  ${orgId} ${handoff.broadcast_id || "<broadcast_id>"} --commit`);
-      console.error("  To deliberately resend to EVERYONE tagged, pass --resend.");
-      process.exit(1);
+      console.log(`⚠ Campaign "${campaign}" ALREADY fanned out via python on ${handoff.at}${handoff.broadcast_id ? ` (broadcastId ${handoff.broadcast_id})` : ""}.`);
+      if (!commitStage) {
+        console.log("  A --commit re-run would resend to EVERY tagged contact (no per-row skip). Audit with bc status; re-fire failures with bc retry; pass --resend to deliberately resend to all.");
+      } else {
+        console.error("  Refusing to resend to the whole tag. Audit / re-fire failures with:");
+        console.error(`    flowiq bc status ${orgId} ${handoff.broadcast_id || "<broadcast_id>"} [--failures]`);
+        console.error(`    flowiq bc retry  ${orgId} ${handoff.broadcast_id || "<broadcast_id>"} --commit`);
+        console.error("  To deliberately resend to EVERYONE tagged, pass --resend.");
+        process.exit(1);
+      }
     }
   }
   // A pre-v0.6.0 per-row log means part of the audience was already reached
@@ -907,7 +946,7 @@ async function runPipeline(orgId, opts, { commitStage, isResume }) {
 
   if (!commitStage) {
     console.log("");
-    console.log("DRY RUN — nothing was sent, no contacts written or tagged. Add --commit to send.");
+    console.log(`DRY RUN — nothing was ${scheduledAt ? "scheduled" : "sent"}, no contacts written or tagged. Add --commit to ${scheduledAt ? "queue it" : "send"}.`);
     return;
   }
   if (!workSet.length) { console.log("Nothing to send — all rows were skipped."); return; }
@@ -915,7 +954,7 @@ async function runPipeline(orgId, opts, { commitStage, isResume }) {
   // 8. gate (BEFORE any write — the upsert itself tags real contacts)
   if (!opts.yes) {
     console.log("");
-    const answer = await ask(`Type the campaign name ("${campaign}") to tag ${workSet.length} contact(s) and fire ONE python broadcast: `);
+    const answer = await ask(`Type the campaign name ("${campaign}") to tag ${workSet.length} contact(s) and ${scheduledAt ? `QUEUE one python broadcast for ${fmtSast(scheduledAt.iso)} SAST` : "fire ONE python broadcast"}: `);
     if (answer !== campaign) { console.log("Mismatch — aborted, nothing written, nothing sent."); process.exit(0); }
   }
 
@@ -942,27 +981,68 @@ async function runPipeline(orgId, opts, { commitStage, isResume }) {
   }
   if (pyTotal != null && pyTotal !== workSet.length) {
     if (pyTotal > workSet.length) {
-      console.log(`⚠ Tag "${tag}" resolves to ${pyTotal} contact(s) — ${pyTotal - workSet.length} MORE than this CSV (tagged by an earlier run of this campaign?). They will ALSO receive the send.`);
+      console.log(`⚠ Tag "${tag}" resolves to ${pyTotal} contact(s) — ${pyTotal - workSet.length} MORE than this CSV (tagged by an earlier run of this campaign?). They will ALSO receive the send${scheduledAt ? " when it fires" : ""}.`);
       if (!opts.yes) {
-        const extra = await ask(`Type YES to send to all ${pyTotal}: `);
-        if (extra !== "YES") { console.log(`Aborted — nothing sent. The tag still carries ${pyTotal} contact(s); use a fresh --campaign for a clean audience.`); process.exit(0); }
+        const extra = await ask(`Type YES to ${scheduledAt ? "schedule for" : "send to"} all ${pyTotal}: `);
+        if (extra !== "YES") { console.log(`Aborted — nothing ${scheduledAt ? "scheduled" : "sent"}. The tag still carries ${pyTotal} contact(s); use a fresh --campaign for a clean audience.`); process.exit(0); }
       }
     } else {
       console.log(`Note: python resolves ${pyTotal} of ${workSet.length} tagged (the rest are opted-out/blocked server-side).`);
     }
   }
 
-  // 11. fire — ONE call; python paces + tracks the rest
-  let out;
-  try { out = await http.post("broadcast", reqBody(false)); }
-  catch (e) { console.error(`Python broadcast failed: ${e.message}${e.body?.error ? ` — ${e.body.error}` : ""}`); process.exit(1); }
-  if (!logHeader) {
+  const writeMetaLine = async () => {
+    if (logHeader) return;
     await appendLog(campaign, {
       type: "meta", campaign, organization_id: orgId, template_name: templateName, engine: "python",
       csv_fingerprint: csv.header_fingerprint, total_rows: csv.rows.length, valid_rows: sendable.length,
       started_at: new Date().toISOString(),
     });
+  };
+
+  // 11a. --at: QUEUE instead of firing — the same api_request_queue row a tag
+  // send writes (type broadcast_send_python), so the dashboard's Scheduled
+  // sends page + bc scheduled list/approve/cancel all see it. Python
+  // re-resolves the tag when it FIRES, so late tag joiners are included.
+  if (scheduledAt) {
+    let resp;
+    try {
+      resp = await http.post("broadcast", {
+        action: "schedule", organization_id: orgId, tag, template_name: templateName,
+        scheduled_for: scheduledAt.iso, needs_approval: !!opts.needsApproval,
+        body_parameters: tokens.body,
+        ...(tokens.button ? { button_parameters: { param1: tokens.button } } : {}),
+        ...(headerMedia ? { header_media: headerMedia } : {}),
+      });
+    } catch (e) {
+      console.error(`Schedule failed: ${e.message}${e.body?.error ? ` — ${e.body.error}` : ""}`);
+      console.error(`Nothing queued. The ${workSet.length} contact(s) ARE tagged "${tag}" — re-run to retry the schedule.`);
+      process.exit(1);
+    }
+    await writeMetaLine();
+    await appendLog(campaign, {
+      type: "handoff", engine: "python-scheduled", tag, queue_id: resp.queue_id ?? null,
+      scheduled_for: resp.scheduled_for ?? scheduledAt.iso, tagged: workSet.length, python_total: pyTotal,
+      at: new Date().toISOString(),
+    });
+    console.log("");
+    console.log(`✓ Scheduled for ${fmtSast(resp.scheduled_for ?? scheduledAt.iso)} SAST — queue id ${resp.queue_id}`);
+    console.log(`  ${workSet.length} contact(s) tagged "${tag}" now; python re-resolves the tag when it fires.`);
+    if (resp.fires_automatically ?? !opts.needsApproval) {
+      console.log(`  It will fire on its own. Cancel with: flowiq bc scheduled cancel ${orgId} ${resp.queue_id}`);
+    } else {
+      console.log(`  ⚠ PARKED awaiting approval — it will NOT fire until you run:`);
+      console.log(`      flowiq bc scheduled approve ${orgId} ${resp.queue_id}`);
+    }
+    console.log(`  Also visible/manageable on the dashboard's Scheduled sends page.`);
+    return;
   }
+
+  // 11b. fire — ONE call; python paces + tracks the rest
+  let out;
+  try { out = await http.post("broadcast", reqBody(false)); }
+  catch (e) { console.error(`Python broadcast failed: ${e.message}${e.body?.error ? ` — ${e.body.error}` : ""}`); process.exit(1); }
+  await writeMetaLine();
   await appendLog(campaign, {
     type: "handoff", engine: "python", tag, broadcast_id: out.broadcastId ?? out.broadcast_id ?? null,
     tagged: workSet.length, python_total: pyTotal, at: new Date().toISOString(),

package/src/index.js

@@ -271,6 +271,7 @@ export function run(argv) {
     .option("--agent <id>", "target a specific agent instead of the org's active one")
     .option("--use-settings-prompt [bool]", "settings.use_settings_prompt (true if bare)")
     .option("--model <model>", "settings.model (e.g. gpt-5.4-mini)")
+    .option("--reasoning-effort <level>", "settings.reasoning_effort — low|medium|high (\"\" clears it); pairs with reasoning models (e.g. gpt-5.6-luna + high)")
     .option("--rename <name>", "rename the agent")
     .option("--tool <flag=bool>", "toggle a tool flag (repeatable): 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", agentConfigCmd.collectTool, [])
     .option("--discount [bool]", "agent.discount.enabled (true if bare)")
@@ -459,7 +460,7 @@ export function run(argv) {
     .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("--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("--commit", "actually send (omit to dry-run)")
     .option("--yes", "skip the type-the-campaign-name confirm gate (CI)")