@flowapt/flowiq-cli 0.7.2 → 0.7.3

package/README.md

@@ -1586,6 +1586,38 @@ flowiq au resolve <update_id> --status declined --internal "duplicate of …"
 - An interactive confirm shows exactly what the client will read; `--yes`
   skips the confirm (but never the `--note` requirement).
 
+### Broadcast planning — `flowiq plans list|show|status` (alias `planning`) (v0.7.3)
+
+The Broadcast → Planning board in the app (the campaign plans clients submit
+and Flowapt reviews), from the terminal.
+
+```bash
+flowiq plans list                                        # open plans across every ACTIVE client
+flowiq plans list --status pending_review                # waiting for Flowapt review
+flowiq plans list <organization_id> --status all --since 2026-09-01
+flowiq plans show <plan_id>                              # copy, second message, buttons, creative, audience, notes
+flowiq plans show <plan_id> --json --out plan.json
+flowiq plans status <plan_id> --to approved              # dry run
+flowiq plans status <plan_id> --to rejected --comment "Please send the image as a PNG" --commit
+flowiq plans status <plan_id> --to sent --commit
+```
+
+- **`list`** defaults to open plans (`draft`, `pending_review`, `approved`,
+  `scheduled`) across all active orgs; pass an org id for one client,
+  `--status all` / a status / a comma list to widen or narrow, `--since` to
+  filter by send date, `--include-inactive` for inactive orgs. The header
+  shows the totals for every status, and each row prints the full plan id.
+- **`show`** prints the plan the way the dialog does: message copy, the
+  second message sent when a button is tapped, buttons with their URLs, the
+  creative (file name + link), audience, template link, the response to the
+  client, internal notes and the notes thread.
+- **`status`** is a dry run until `--commit`. `--comment` is the response the
+  **client reads**; `--internal` is staff-only. `approved` and `rejected`
+  record you as the reviewer; `rejected` requires `--comment`. Every commit is
+  in `flowiq audit --endpoint plans`.
+- Editing a plan's copy, buttons or links is not in the CLI yet; do that in
+  the app.
+
 ### Chat export — `flowiq export chats <organization_id> [--out <path>]`
 
 Full chat history → TXT, byte-identical to the in-app "Export Settings TXT"

package/TEAM-GUIDE.md

@@ -87,6 +87,9 @@ When you see it, run `npm i -g @flowapt/flowiq-cli` — a stale version also mea
 | 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 |
+| See broadcast plans waiting for Flowapt review, across every client | `flowiq plans list --status pending_review`, then `flowiq plans show <plan_id>` for the copy, second message, buttons, creative and audience |
+| See one client's broadcast plans | `flowiq plans list <org_id>` (open plans) or `flowiq plans list <org_id> --status all --since 2026-09-01` |
+| Mark a broadcast plan approved, scheduled or sent | `flowiq plans status <plan_id> --to sent` (a dry run), then add `--commit`. Rejecting needs `--comment "..."`, which the client reads |
 | 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 |
 | **Size a customer cohort** | Use `customers(first:250, query:…)` and paginate — **NOT `customersCount(query:…)`, which Shopify ignores the filter on** and answers 10,000 every time. Any count showing `precision: AT_LEAST` is a cap, not a total; the CLI warns you. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flowapt/flowiq-cli",
-  "version": "0.7.2",
+  "version": "0.7.3",
   "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/plans.js

@@ -0,0 +1,258 @@
+// `flowiq plans list|show|status` — Broadcast Planning (the Broadcast → Planning
+// board in the app, table broadcast_planning), via /cli/plans.
+//   list   read: open plans across all active orgs, or one org
+//   show   read: one plan in full (copy, second message, buttons, creative, notes)
+//   status write: dry run unless --commit; audited server-side
+
+import fs from "node:fs/promises";
+import path from "node:path";
+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 STATUSES = ["draft", "pending_review", "approved", "rejected", "scheduled", "sent", "cancelled"];
+const STATUS_ORDER = ["pending_review", "approved", "scheduled", "draft", "rejected", "sent", "cancelled"];
+const STATUS_LABEL = {
+  pending_review: "PENDING REVIEW",
+  approved: "APPROVED",
+  scheduled: "SCHEDULED",
+  draft: "DRAFT",
+  rejected: "REJECTED",
+  sent: "SENT",
+  cancelled: "CANCELLED",
+};
+const MONTHS = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"];
+
+function sastParts(ts) {
+  const parts = new Intl.DateTimeFormat("en-CA", {
+    timeZone: "Africa/Johannesburg",
+    year: "numeric", month: "2-digit", day: "2-digit",
+    hour: "2-digit", minute: "2-digit", hour12: false,
+  }).formatToParts(new Date(ts));
+  return Object.fromEntries(parts.map((p) => [p.type, p.value]));
+}
+
+function fmtTs(ts) {
+  if (!ts) return "-";
+  const p = sastParts(ts);
+  const hour = p.hour === "24" ? "00" : p.hour;
+  return `${Number(p.day)} ${MONTHS[Number(p.month) - 1]} ${p.year} ${hour}:${p.minute}`;
+}
+
+function fmtDate(dateStr, timeStr) {
+  if (!dateStr) return "no date";
+  const [y, m, d] = String(dateStr).split("-");
+  return `${Number(d)} ${MONTHS[Number(m) - 1]} ${y} ${timeStr ? String(timeStr).slice(0, 5) : "--:--"}`;
+}
+
+function indent(text, pad = "  ") {
+  const t = String(text ?? "").trim();
+  if (!t) return `${pad}(empty)`;
+  return t.split("\n").map((line) => `${pad}${line}`).join("\n");
+}
+
+function fail(prefix, e) {
+  console.error(`${prefix}: ${e.message}`);
+  if (e.body?.error && !String(e.message).includes(e.body.error)) console.error(`  ${e.body.error}`);
+  process.exit(1);
+}
+
+export async function list(orgId, opts = {}) {
+  if (orgId && !UUID_RE.test(orgId)) {
+    console.error(`Error: "${orgId}" is not a valid organization UUID (find it with \`flowiq org list\`).`);
+    process.exit(1);
+  }
+  const query = {};
+  if (orgId) query.organization_id = orgId;
+  if (opts.status) query.status = opts.status;
+  if (opts.since) query.since = opts.since;
+  if (opts.includeInactive) query.include_inactive = "1";
+  if (opts.limit != null) query.limit = String(opts.limit);
+
+  let resp;
+  try {
+    resp = await http.get("plans", query);
+  } catch (e) {
+    fail("List failed", e);
+  }
+  if (opts.json) {
+    console.log(JSON.stringify(resp, null, 2));
+    return;
+  }
+
+  const scope = resp.organization_name
+    ? resp.organization_name
+    : `all ${resp.include_inactive ? "" : "active "}orgs`;
+  const totals = STATUS_ORDER.filter((s) => resp.counts?.[s]).map((s) => `${s} ${resp.counts[s]}`).join(" · ");
+  console.log(`Broadcast plans · ${scope} · status ${resp.status_filter}${resp.since ? ` · from ${resp.since}` : ""}`);
+  console.log(`  every status in this scope: ${totals || "none"}`);
+
+  const plans = resp.plans || [];
+  if (!plans.length) {
+    console.log("  (no matching plans)");
+    return;
+  }
+
+  for (const s of STATUS_ORDER) {
+    const group = plans.filter((p) => p.status === s);
+    if (!group.length) continue;
+    console.log(`\n${STATUS_LABEL[s]} (${group.length})`);
+    for (const p of group) {
+      const flag = p.date_passed ? " (date passed)" : p.scheduled_date === resp.today ? " (today)" : "";
+      console.log(`  ${fmtDate(p.scheduled_date, p.scheduled_time)}${flag}  ${p.organization_name ?? p.organization_id}  ·  ${p.topic}`);
+      const bits = [
+        p.type || "type not set",
+        p.audience,
+        p.origin === "flowapt" ? `Flowapt suggestion (client: ${p.client_status ?? "-"})` : null,
+        p.creative_file ? `creative ${p.creative_file}` : null,
+        p.template_id ? "template linked" : null,
+        p.has_client_comment ? "has response to client" : null,
+        p.notes_count ? `${p.notes_count} note(s)` : null,
+      ].filter(Boolean);
+      console.log(`    ${bits.join(" · ")}`);
+      const reviewed = p.reviewed_at
+        ? ` · reviewed ${fmtTs(p.reviewed_at)}${p.reviewed_by_name ? ` by ${p.reviewed_by_name}` : ""}`
+        : "";
+      console.log(`    submitted ${fmtTs(p.created_at)}${p.created_by_name ? ` by ${p.created_by_name}` : ""}${reviewed}`);
+      console.log(`    id ${p.id}`);
+    }
+  }
+  if (resp.truncated) {
+    console.log(`\n⚠ ${plans.length} shown and the limit (${resp.limit}) was reached: pass --limit, or narrow with --status / --since.`);
+  }
+  console.log("\nFull plan: flowiq plans show <plan_id>");
+}
+
+export async function show(planId, opts = {}) {
+  if (!UUID_RE.test(planId)) {
+    console.error(`Error: "${planId}" is not a valid plan UUID (get it from \`flowiq plans list\`).`);
+    process.exit(1);
+  }
+  let resp;
+  try {
+    resp = await http.get("plans", { plan_id: planId });
+  } catch (e) {
+    fail("Show failed", e);
+  }
+  if (opts.out) {
+    const out = path.resolve(process.cwd(), opts.out);
+    await fs.mkdir(path.dirname(out), { recursive: true });
+    await fs.writeFile(out, JSON.stringify(resp, null, 2) + "\n", "utf8");
+    console.error(`Wrote ${out}`);
+  }
+  if (opts.json) {
+    console.log(JSON.stringify(resp, null, 2));
+    return;
+  }
+
+  const p = resp.plan;
+  const more = p.more && typeof p.more === "object" ? p.more : {};
+  const creative = p.creative && typeof p.creative === "object" ? p.creative : {};
+  const flag = p.scheduled_date && p.scheduled_date < resp.today
+    ? " (date passed)"
+    : p.scheduled_date === resp.today ? " (today)" : "";
+
+  console.log(p.topic);
+  console.log(`  org:        ${p.organization_name ?? "?"} (${p.organization_id})${p.organization_inactive ? " [inactive org]" : ""}`);
+  console.log(`  status:     ${p.status}${p.origin === "flowapt" ? ` · Flowapt suggestion, client: ${p.client_status ?? "-"}` : ""}`);
+  console.log(`  send:       ${fmtDate(p.scheduled_date, p.scheduled_time)}${flag}`);
+  console.log(`  type:       ${more.type ?? "-"}`);
+  console.log(`  audience:   ${p.has_segment ? (p.segment_details || "segment (no details given)") : "whole list"}`);
+  if (p.shopify_segment_formula) console.log(`  formula:    ${p.shopify_segment_formula}`);
+  if (p.product_focus) console.log(`  product:    ${p.product_focus}`);
+  if (p.landing_page_url) console.log(`  landing:    ${p.landing_page_url}`);
+  console.log(`  submitted:  ${fmtTs(p.created_at)}${p.created_by_name ? ` by ${p.created_by_name}` : ""}`);
+  if (p.reviewed_at) console.log(`  reviewed:   ${fmtTs(p.reviewed_at)}${p.reviewed_by_name ? ` by ${p.reviewed_by_name}` : ""}`);
+  if (p.client_approved_at) console.log(`  client OK:  ${fmtTs(p.client_approved_at)}${p.client_approved_by_name ? ` by ${p.client_approved_by_name}` : ""}`);
+  console.log(`  id:         ${p.id}`);
+
+  console.log("\nMessage copy");
+  console.log(indent(p.copy_text));
+
+  if (more.slide2?.message) {
+    console.log("\nSecond message (sent when a button is tapped)");
+    console.log(indent(more.slide2.message));
+  }
+  if (more.slides && typeof more.slides === "object") {
+    for (const [key, slide] of Object.entries(more.slides)) {
+      if (!slide || typeof slide !== "object") continue;
+      console.log(`\n${key}${slide.triggered_by ? ` (after ${slide.triggered_by})` : ""}`);
+      if (slide.message) console.log(indent(slide.message));
+      if (slide.media_url) console.log(`  media: ${slide.media_url}`);
+    }
+  }
+
+  const buttons = Array.isArray(more.buttons) ? more.buttons : [];
+  if (buttons.length) {
+    console.log("\nButtons");
+    for (const b of buttons) console.log(`  [${b?.type ?? "?"}] ${b?.text ?? ""}${b?.url ? ` → ${b.url}` : ""}`);
+  }
+
+  console.log("\nCreative");
+  if (creative.original_filename || creative.file_url) {
+    const size = creative.file_size ? ` · ${(creative.file_size / 1024 / 1024).toFixed(1)} MB` : "";
+    console.log(`  ${creative.original_filename ?? "(unnamed)"} · ${creative.file_type ?? "type ?"}${size} · supplied by ${creative.supplier ?? "?"}`);
+    if (creative.file_url) console.log(`  ${creative.file_url}`);
+  } else {
+    console.log(`  none attached${creative.supplier ? ` (supplied by ${creative.supplier})` : ""}`);
+  }
+
+  if (p.template) console.log(`\nTemplate: ${p.template.template_name} (${p.template.status ?? "status ?"}, ${p.template.category ?? "category ?"})`);
+  else if (p.template_id) console.log(`\nTemplate id: ${p.template_id}`);
+  if (p.send_draft_id) console.log(`Send draft id: ${p.send_draft_id}`);
+
+  if (p.superadmin_comment) {
+    console.log("\nResponse to client");
+    console.log(indent(p.superadmin_comment));
+  }
+  if (p.internal_notes) {
+    console.log("\nInternal notes (staff only)");
+    console.log(indent(p.internal_notes));
+  }
+  const notes = resp.notes || [];
+  if (notes.length) {
+    console.log(`\nNotes (${notes.length})`);
+    for (const n of notes) console.log(`  ${fmtTs(n.created_at)} ${n.author_name ?? "?"} [${n.kind ?? "note"}]: ${String(n.body ?? "").replace(/\s+/g, " ").trim()}`);
+  }
+
+  console.log(`\nChange status: flowiq plans status ${p.id} --to <status> [--comment "..."] [--commit]`);
+}
+
+export async function status(planId, opts = {}) {
+  if (!UUID_RE.test(planId)) {
+    console.error(`Error: "${planId}" is not a valid plan UUID (get it from \`flowiq plans list\`).`);
+    process.exit(1);
+  }
+  const to = String(opts.to || "").toLowerCase();
+  if (!STATUSES.includes(to)) {
+    console.error(`Error: --to must be one of ${STATUSES.join(" | ")} (got "${opts.to}").`);
+    process.exit(1);
+  }
+  if (to === "rejected" && !(opts.comment && opts.comment.trim())) {
+    console.error("Refusing to reject without --comment: the client reads it as the response to their plan.");
+    process.exit(1);
+  }
+
+  let resp;
+  try {
+    resp = await http.post("plans", {
+      action: "status",
+      plan_id: planId,
+      status: to,
+      superadmin_comment: opts.comment ?? null,
+      internal_notes: opts.internal ?? null,
+      dry_run: !opts.commit,
+    });
+  } catch (e) {
+    fail("Status change failed", e);
+  }
+
+  const prev = resp.previous || {};
+  const next = resp.next || {};
+  console.log(`${resp.dry_run ? "DRY RUN" : "Updated"} · ${resp.topic}`);
+  console.log(`  org:       ${resp.organization_name ?? resp.organization_id}`);
+  console.log(`  status:    ${prev.status} → ${next.status}`);
+  if (next.superadmin_comment !== prev.superadmin_comment) console.log(`  client reads: ${next.superadmin_comment}`);
+  if (next.internal_notes !== prev.internal_notes) console.log(`  internal:  ${next.internal_notes}`);
+  if (resp.reviewer_email) console.log(`  reviewer:  ${resp.reviewer_email} (reviewed_at ${fmtTs(next.reviewed_at)})`);
+  if (resp.dry_run) console.log("\nNothing written. Re-run with --commit to apply.");
+}

package/src/index.js

@@ -25,6 +25,7 @@ import * as teamUpdatesCmd from "./commands/team-updates.js";
 import * as agentConfigCmd from "./commands/agent-config.js";
 import * as agentsCmd from "./commands/agents.js";
 import * as agentUpdatesCmd from "./commands/agent-updates.js";
+import * as plansCmd from "./commands/plans.js";
 import * as exportCmd from "./commands/export.js";
 import * as testCmd from "./commands/agent-test.js";
 import * as knowledgeCmd from "./commands/knowledge.js";
@@ -445,6 +446,31 @@ export function run(argv) {
     .option("--yes", "skip the interactive confirm gate (the --note requirement still applies)")
     .action((updateId, opts) => agentUpdatesCmd.resolve(updateId, opts));
 
+  // plans (Broadcast Planning board: list across orgs, show one plan, change status)
+  const plans = program.command("plans")
+    .alias("planning")
+    .description("Broadcast Planning (Broadcast → Planning): list plans across orgs, show one in full, change a plan's status");
+  plans.command("list [organization_id]")
+    .description("List plans, default open (draft, pending_review, approved, scheduled), across all active orgs or one org")
+    .option("--status <status>", "open (default) | all | pending_review | draft | approved | rejected | scheduled | sent | cancelled (comma-separated allowed)")
+    .option("--since <date>", "only plans scheduled on or after YYYY-MM-DD")
+    .option("--include-inactive", "include plans from inactive orgs (cross-org listing)")
+    .option("--limit <n>", "max plans returned (default 100, max 500)")
+    .option("--json", "print the raw response")
+    .action((orgId, opts) => plansCmd.list(orgId, opts));
+  plans.command("show <plan_id>")
+    .description("Show one plan in full: copy, second message, buttons, creative, audience, notes")
+    .option("--json", "print the raw response")
+    .option("--out <file>", "also write the full plan JSON to a file")
+    .action((planId, opts) => plansCmd.show(planId, opts));
+  plans.command("status <plan_id>")
+    .description("Change a plan's status (dry run unless --commit); approved/rejected also record you as the reviewer")
+    .requiredOption("--to <status>", "draft | pending_review | approved | rejected | scheduled | sent | cancelled")
+    .option("--comment <text>", "response to the client, shown on their plan (required for rejected)")
+    .option("--internal <text>", "staff-only internal notes (replaces the current internal notes)")
+    .option("--commit", "apply the change (default is a dry run)")
+    .action((planId, opts) => plansCmd.status(planId, opts));
+
   // audit (who did what, when — with the full before/after content)
   const audit = program.command("audit")
     .description("Staff-CLI audit trail: who changed what, when — with full before/after content")