@flowapt/flowiq-cli 0.6.7 → 0.7.0

package/src/campaign-naming.test.mjs

@@ -0,0 +1,76 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { resolveCampaign, resolveContent, dateToken, parseDateToken, isConforming, pascal } from "./campaign-naming.js";
+
+const NOW = new Date(2026, 8, 9); // 9 Sep 2026, local
+
+test("Matt's worked example", () => {
+  const r = resolveCampaign("Spring Promotion", { now: NOW });
+  assert.equal(r.value, "9Sep_SpringPromotion");
+  assert.ok(r.changed);
+});
+
+test("already correct is left alone and reports no change", () => {
+  const r = resolveCampaign("9Sep_SpringPromotion", { now: NOW });
+  assert.equal(r.value, "9Sep_SpringPromotion");
+  assert.equal(r.changed, false);
+  assert.deepEqual(r.notes, []);
+});
+
+test("the house habit: fused date, no underscore (924 tags in 12 months)", () => {
+  assert.equal(resolveCampaign("10JunFathersDay", { now: NOW }).value, "10Jun_FathersDay");
+});
+
+test("Sept is corrected to Sep, and the date is kept", () => {
+  const r = resolveCampaign("5Sept_BraaiDayOffer", { now: NOW });
+  assert.equal(r.value, "5Sep_BraaiDayOffer");
+  assert.ok(r.notes.some((n) => n.includes("Sept")));
+});
+
+test("leading zero is dropped", () => {
+  assert.equal(resolveCampaign("09Sep_Foo", { now: NOW }).value, "9Sep_Foo");
+});
+
+test("--date overrides a send scheduled for another day", () => {
+  assert.equal(resolveCampaign("Heritage Day", { date: "2026-09-24", now: NOW }).value, "24Sep_HeritageDay");
+  assert.equal(resolveCampaign("24Sep_HeritageDay", { date: "25Sep", now: NOW }).value, "25Sep_HeritageDay");
+});
+
+test("--date accepts SA d/m/yyyy and long month names", () => {
+  assert.equal(parseDateToken("24/09/2026"), "24Sep");
+  assert.equal(parseDateToken("24 September"), "24Sep");
+  assert.equal(parseDateToken("2026-09-24"), "24Sep");
+  assert.equal(parseDateToken("banana"), null);
+  assert.equal(parseDateToken("24/13/2026"), null);
+});
+
+test("separators and casing all collapse to PascalCase", () => {
+  assert.equal(pascal("spring-promotion"), "SpringPromotion");
+  assert.equal(pascal("spring_promotion"), "SpringPromotion");
+  assert.equal(pascal("  spring   promotion "), "SpringPromotion");
+  assert.equal(pascal("R500 promo"), "R500Promo");
+});
+
+test("an acronym keeps its case", () => {
+  assert.equal(resolveCampaign("CTWA Launch", { now: NOW }).value, "9Sep_CTWALaunch");
+});
+
+test("empty and title-less inputs error rather than minting rubbish", () => {
+  assert.ok(resolveCampaign("", { now: NOW }).error);
+  assert.ok(resolveCampaign("9Sep", { now: NOW }).error);
+  assert.ok(resolveCampaign("Spring", { date: "nonsense", now: NOW }).error);
+});
+
+test("utm_content is per-link and gets no date", () => {
+  assert.equal(resolveContent("View More").value, "ViewMore");
+  assert.equal(resolveContent("").value, "");
+});
+
+test("dateToken / isConforming", () => {
+  assert.equal(dateToken(NOW), "9Sep");
+  assert.equal(dateToken(new Date(2026, 11, 25)), "25Dec");
+  assert.ok(isConforming("9Sep_SpringPromotion"));
+  assert.ok(!isConforming("9Sept_SpringPromotion"));
+  assert.ok(!isConforming("SpringPromotion"));
+  assert.ok(!isConforming("9Sep_Spring_Promotion"));
+});

package/src/commands/doctor.js

@@ -0,0 +1,150 @@
+// `flowiq doctor` — one command that answers "is my CLI healthy and current?"
+//
+// Written because the honest answer used to need three commands and some
+// knowledge: `flowiq --version` (installed), `npm view` (latest), and nothing
+// at all for "does the SERVER still speak my dialect?". A teammate — or a
+// teammate's AI assistant — needs one place that says what is wrong and the
+// exact command to fix it.
+//
+// Read-only, no org needed, safe to run any time. Exit code 1 when something
+// actionable is wrong, so it can gate a script.
+
+import { http, serverContract, cliVersion } from "../http.js";
+import { cachedLatest, fetchLatestNow, cmpVersion } from "../update-check.js";
+import { loadConfig, configDir } from "../config.js";
+
+const green = (s) => `\x1b[32m${s}\x1b[0m`;
+const red = (s) => `\x1b[31m${s}\x1b[0m`;
+const amber = (s) => `\x1b[33m${s}\x1b[0m`;
+const dim = (s) => `\x1b[2m${s}\x1b[0m`;
+
+const OK = green("✓");
+const WARN = amber("⚠");
+const BAD = red("✗");
+
+function ageLabel(ts) {
+  if (!ts) return "never";
+  const h = (Date.now() - ts) / 3600000;
+  if (h < 1) return `${Math.round(h * 60)} min ago`;
+  if (h < 48) return `${h.toFixed(1)} h ago`;
+  return `${Math.round(h / 24)} days ago`;
+}
+
+export async function doctor(opts = {}) {
+  const installed = cliVersion();
+  const problems = [];
+  const out = {
+    cli_version: installed,
+    npm_latest: null,
+    server_min_version: null,
+    api_build: null,
+    api_url: null,
+    authenticated: false,
+    user: null,
+    problems: [],
+  };
+
+  const lines = [];
+  lines.push(`flowiq doctor`);
+  lines.push("");
+
+  // ── 1. installed vs npm latest ────────────────────────────────────────────
+  // Ask the registry LIVE here (with a short timeout). The background cache is
+  // refreshed at most once a day, so on the day of a release it is stale — which
+  // is precisely when someone runs doctor.
+  const live = await fetchLatestNow(3000);
+  const cached = cachedLatest();
+  const latest = live || cached.latest;
+  out.npm_latest = latest;
+
+  if (!latest) {
+    lines.push(`  ${WARN} version    installed ${installed} · could not reach npm ${dim("(offline?)")}`);
+  } else if (cmpVersion(latest, installed) > 0) {
+    lines.push(`  ${BAD} version    installed ${installed} · latest ${latest}`);
+    problems.push({
+      what: `CLI is out of date (${installed} → ${latest})`,
+      fix: "npm i -g @flowapt/flowiq-cli@latest",
+    });
+  } else if (cmpVersion(installed, latest) > 0) {
+    // A dev machine, a worktree build, or a version bumped but not yet
+    // published. Saying "(latest)" here would be a lie, and it is exactly the
+    // state in which someone wonders why teammates do not have their feature.
+    lines.push(`  ${WARN} version    installed ${installed} is AHEAD of npm (${latest}) ${dim("— unpublished build")}`);
+  } else {
+    lines.push(`  ${OK} version    ${installed} ${dim(live ? "(latest)" : `(latest, cached ${ageLabel(cached.checkedAt)})`)}`);
+  }
+
+  // ── 2. config + auth ──────────────────────────────────────────────────────
+  let cfg = {};
+  try { cfg = await loadConfig(); } catch { /* handled below */ }
+  out.api_url = cfg.api_url || null;
+  lines.push(`  ${cfg.api_url ? OK : BAD} api        ${cfg.api_url || "not configured"} ${dim(configDir())}`);
+  if (!cfg.api_url) problems.push({ what: "no api_url configured", fix: "flowiq auth login" });
+
+  if (!cfg.token) {
+    lines.push(`  ${BAD} auth       not authenticated`);
+    problems.push({ what: "not authenticated", fix: "flowiq auth login" });
+  } else {
+    // whoami doubles as the live server probe — it is how the response headers
+    // carrying the version contract reach us at all.
+    try {
+      // `whoami` is also the live server probe: it is how the response headers
+      // carrying the version contract reach us at all.
+      const who = await http.get("whoami");
+      out.authenticated = true;
+      out.user = who?.user_email || null;
+      out.super_admin = who?.is_super_admin === true;
+      const role = who?.is_super_admin ? "super admin" : red("NOT a super admin");
+      lines.push(`  ${OK} auth       ${out.user || "authenticated"} ${dim(`· ${role}`)}`);
+      if (who && who.is_super_admin !== true) {
+        problems.push({ what: "this key is not a super-admin key — most commands will 403", fix: "ask Matt to re-issue the staff key" });
+      }
+    } catch (e) {
+      lines.push(`  ${BAD} auth       ${e.message.split("\n")[0]}`);
+      problems.push({
+        what: "the API rejected this key",
+        fix: e.status === 401 || e.status === 403 ? "flowiq auth login" : "check api_url / network, then retry",
+      });
+    }
+  }
+
+  // ── 3. the server's version contract ──────────────────────────────────────
+  out.server_min_version = serverContract.minVersion;
+  out.api_build = serverContract.apiBuild;
+
+  if (!serverContract.minVersion) {
+    lines.push(`  ${WARN} server     did not declare a minimum CLI version ${dim("(deploy predates the version contract)")}`);
+  } else if (cmpVersion(serverContract.minVersion, installed) > 0) {
+    lines.push(`  ${BAD} server     requires ${serverContract.minVersion}, you have ${installed}`);
+    problems.push({
+      what: `this CLI is older than the server's contract (needs ${serverContract.minVersion})`,
+      fix: "npm i -g @flowapt/flowiq-cli@latest",
+    });
+  } else {
+    lines.push(`  ${OK} server     contract ${serverContract.minVersion} or newer ${dim(`· build ${serverContract.apiBuild || "?"}`)}`);
+  }
+
+  // The REVERSE skew: a CLI newer than the deployment it is talking to. Not an
+  // error — it is the normal state for the minutes between a push and the
+  // Vercel deploy — but it explains "the command exists and still doesn't work".
+  if (latest && serverContract.minVersion && cmpVersion(installed, latest) === 0 && cmpVersion(installed, serverContract.minVersion) > 0) {
+    lines.push(`  ${dim("i  server     min is " + serverContract.minVersion + " while you run " + installed + " — fine; newest features need the matching deploy")}`);
+  }
+
+  out.problems = problems;
+  if (opts.json) { console.log(JSON.stringify(out, null, 2)); return problems.length ? 1 : 0; }
+
+  console.log(lines.join("\n"));
+  console.log("");
+  if (!problems.length) {
+    console.log(green("  Everything checks out."));
+  } else {
+    console.log(red(`  ${problems.length} thing${problems.length === 1 ? "" : "s"} to fix:`));
+    for (const p of problems) {
+      console.log(`    • ${p.what}`);
+      console.log(`      ${p.fix}`);
+    }
+  }
+  console.log("");
+  return problems.length ? 1 : 0;
+}

package/src/commands/insights.js

@@ -0,0 +1,201 @@
+// `flowiq insights …` — the Customer Insights Report from the terminal.
+//
+//   flowiq insights status [org_id] [--off|--on] [--min-chats N] [--all]   who has it, who does not, last report, chat volume
+//   flowiq insights enable <org_id> [--daily] [--weekly [day]] [--monthly [day]] [--report standard|advanced]
+//                                   [--store-only] [--recipient a@b.com …] [--dry-run] [--force]
+//   flowiq insights disable <org_id>
+//   flowiq insights run <org_id> [--period daily|weekly|monthly | --from D --to D] [--report …]
+//                                [--recipient …] [--store-only] --commit
+//
+// `run` is DRY-RUN by default (it prints the exact engine, window and
+// recipients) and fires only with --commit — it costs OpenAI tokens and can
+// email a client. The server refuses the three ways an enabled org silently
+// produces nothing (no OpenAI key, emailing with no recipients, an empty
+// window); --force overrides all but an inactive org.
+
+import { http } from "../http.js";
+import { schedulesFromOpts, describeSchedule, sastRange } from "../insights-config.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 pad = (s, n) => String(s ?? "").padEnd(n);
+const padL = (s, n) => String(s ?? "").padStart(n);
+
+function requireUuid(orgId) {
+  if (!UUID_RE.test(orgId || "")) {
+    console.error(`Error: "${orgId}" is not a valid organization UUID (find it with \`flowiq org list <name>\`).`);
+    process.exit(1);
+  }
+}
+
+function fmtWhen(iso) {
+  if (!iso) return "never";
+  const d = new Date(iso);
+  if (Number.isNaN(d.getTime())) return String(iso);
+  // SAST, minute precision
+  const s = new Date(d.getTime() + 2 * 3600 * 1000).toISOString();
+  return `${s.slice(0, 10)} ${s.slice(11, 16)}`;
+}
+
+function daysAgo(iso) {
+  if (!iso) return null;
+  return Math.floor((Date.now() - new Date(iso).getTime()) / 86400000);
+}
+
+function printProblems(body) {
+  for (const e of body.errors || []) console.error(`  ✗ ${e}`);
+  for (const w of body.warnings || []) console.error(`  ⚠ ${w}`);
+}
+
+function fail(prefix, e) {
+  console.error(`${prefix}: ${e.message}`);
+  const b = e.body || {};
+  if (b.errors?.length || b.warnings?.length) printProblems(b);
+  if (b.needs_force) console.error("  Fix the cause, or re-run with --force to write anyway.");
+  process.exit(1);
+}
+
+// ── status ───────────────────────────────────────────────────────────────────
+
+export async function status(orgId, opts = {}) {
+  if (orgId) return statusOne(orgId, opts);
+  let resp;
+  try { resp = await http.get("insights", { status: "1", all: opts.all ? "1" : undefined }); } catch (e) { fail("Status failed", e); }
+  if (opts.json) { console.log(JSON.stringify(resp, null, 2)); return; }
+
+  let orgs = resp.orgs || [];
+  const total = orgs.length;
+  const enabledTotal = orgs.filter((o) => o.enabled).length;
+  if (opts.on) orgs = orgs.filter((o) => o.enabled);
+  if (opts.off) orgs = orgs.filter((o) => !o.enabled);
+  const minChats = Number(opts.minChats ?? 0);
+  if (minChats > 0) orgs = orgs.filter((o) => o.contacts_30d >= minChats);
+  const sort = opts.sort || "chats";
+  orgs.sort((a, b) =>
+    sort === "name" ? a.name.localeCompare(b.name)
+    : sort === "last" ? (new Date(b.last_report?.at || 0) - new Date(a.last_report?.at || 0))
+    : (b.contacts_30d - a.contacts_30d) || a.name.localeCompare(b.name));
+
+  console.log(`Customer Insights Report — ${enabledTotal} of ${total} org(s) enabled${resp.include_inactive ? " (incl. inactive)" : ""}` +
+    `${opts.on ? " · showing ON" : opts.off ? " · showing OFF" : ""}${minChats ? ` · ≥${minChats} chatting contacts/30d` : ""}\n`);
+  if (!orgs.length) { console.log("(no orgs match the filter)"); return; }
+
+  const nameW = Math.min(28, Math.max(4, ...orgs.map((o) => o.name.length)));
+  console.log(`${pad("NAME", nameW)}  ${pad("STATE", 5)}  ${padL("CHATS30D", 8)}  ${pad("KEY", 3)}  ${pad("LAST REPORT", 18)}  ${pad("RCPT", 4)}  SCHEDULES`);
+  for (const o of orgs) {
+    const state = o.enabled ? "ON" : o.configured ? "off" : "—";
+    const last = o.last_report ? `${fmtWhen(o.last_report.at)}${o.last_report.store_only ? " s" : ""}` : "never";
+    const sched = o.enabled ? o.schedules_described.join(", ") + (o.schedules_source === "implicit-daily" ? " (implicit)" : "") : "";
+    console.log(
+      `${pad(o.name.slice(0, nameW), nameW)}  ${pad(state, 5)}  ${padL(o.contacts_30d, 8)}  ${pad(o.has_openai_key ? "yes" : "NO", 3)}  ${pad(last, 18)}  ${padL(o.recipients.length, 4)}  ${sched}${o.inactive ? "  (inactive)" : ""}`
+    );
+  }
+  console.log(`\n${orgs.length} org(s) shown · CHATS30D = distinct contacts who messaged in the last 30 days · KEY = has its own OpenAI key (required) · "s" = store-only`);
+  console.log("Enable one:  flowiq insights enable <org_id> --weekly monday --recipient client@example.com");
+}
+
+async function statusOne(orgId, opts = {}) {
+  requireUuid(orgId);
+  let resp;
+  try { resp = await http.get("insights", { organization_id: orgId }); } catch (e) { fail("Status failed", e); }
+  if (opts.json) { console.log(JSON.stringify(resp, null, 2)); return; }
+
+  console.log(`${resp.name} (${resp.id})${resp.inactive ? "  [INACTIVE]" : ""}`);
+  console.log(`  insights:       ${resp.enabled ? "ENABLED" : resp.configured ? "disabled (config kept)" : "never configured"}`);
+  if (resp.enabled || resp.configured) {
+    console.log(`  schedules:      ${resp.schedules_described.join(", ") || "(none)"}${resp.schedules_source === "implicit-daily" ? "  ⚠ no schedules stored — the scheduler runs DAILY standard by default" : resp.schedules_source === "legacy" ? "  (legacy single-config shape)" : ""}`);
+    console.log(`  recipients:     ${resp.recipients.length ? resp.recipients.join(", ") : `(none — emails would go to ${resp.engine_fallback_email})`}`);
+  }
+  console.log(`  openai key:     ${resp.has_openai_key ? "own key present" : "NONE — the engines refuse to run"}${resp.has_spare_openai_key ? " (+ spare)" : ""}`);
+  console.log(`  studio config:  ${resp.studio_configured_at ? `saved ${fmtWhen(resp.studio_configured_at)} (advanced engine)` : "none (advanced runs on engine defaults)"}`);
+  console.log(`  chats (30d):    ${resp.contacts_30d} contacts · ${resp.messages_30d} messages · last inbound ${fmtWhen(resp.last_inbound_at)}`);
+  console.log(`  reports (30d):  ${resp.reports_30d}`);
+  if (resp.reports?.length) {
+    console.log("\n  Recent reports (SAST):");
+    for (const r of resp.reports) {
+      console.log(`    ${fmtWhen(r.at)}  ${pad(r.kind || "?", 8)} ${padL(r.contacts ?? "?", 5)} contacts ${padL(r.messages ?? "?", 6)} msgs  ` +
+        `${r.store_only ? "stored only" : `${r.emails_sent ?? 0} email(s)${r.emails_failed ? `, ${r.emails_failed} failed` : ""}`}` +
+        `${r.recipients?.length && !r.store_only ? ` → ${r.recipients.join(", ")}` : ""}${r.source && r.source !== "edge" ? `  [${r.source}]` : ""}`);
+    }
+  } else {
+    console.log("\n  No reports yet.");
+  }
+}
+
+// ── enable / disable ─────────────────────────────────────────────────────────
+
+export async function enable(orgId, opts = {}) {
+  requireUuid(orgId);
+  let schedules;
+  try { schedules = schedulesFromOpts({ daily: opts.daily, weekly: opts.weekly, monthly: opts.monthly, report: opts.report, storeOnly: opts.storeOnly }); }
+  catch (e) { console.error(`Error: ${e.message}`); process.exit(1); }
+  if (!schedules && (opts.report || opts.storeOnly)) {
+    console.error("Error: --report / --store-only describe a schedule — add --daily, --weekly or --monthly to say which.");
+    process.exit(1);
+  }
+  const recipients = {};
+  if (opts.recipient?.length) recipients.replace = opts.recipient;
+  if (opts.addRecipient?.length) recipients.add = opts.addRecipient;
+  if (opts.removeRecipient?.length) recipients.remove = opts.removeRecipient;
+
+  const body = { organization_id: orgId, action: "enable", dry_run: opts.dryRun === true, force: opts.force === true };
+  if (schedules) body.schedules = schedules;
+  if (Object.keys(recipients).length) body.recipients = recipients;
+
+  let resp;
+  try { resp = await http.post("insights", body); } catch (e) { fail("Enable failed", e); }
+  if (opts.json) { console.log(JSON.stringify(resp, null, 2)); return; }
+
+  const o = resp.organization;
+  const after = resp.after;
+  console.log(`${resp.dry_run ? "DRY RUN — " : ""}${o.name}: insights ${resp.before?.enabled ? "already on, config updated" : "ENABLED"}${resp.forced ? "  (FORCED past pre-flight)" : ""}`);
+  console.log(`  schedules:   ${(after.schedules || []).map(describeSchedule).join(", ")}  [${resp.schedules_source}]`);
+  console.log(`  recipients:  ${after.recipient_emails?.length ? after.recipient_emails.join(", ") : "(none)"}`);
+  printProblems(resp);
+  if (resp.dry_run) {
+    console.log(resp.would_write ? "\n  Would write. Re-run without --dry-run." : "\n  Would NOT write — fix the ✗ items (or --force).");
+  } else {
+    console.log("\n  Next run: 09:00 SAST on the next matching day (cron 72). Fire one now: flowiq insights run " + orgId + " --commit");
+    console.log("  Undo:     flowiq insights disable " + orgId);
+  }
+}
+
+export async function disable(orgId, opts = {}) {
+  requireUuid(orgId);
+  let resp;
+  try { resp = await http.post("insights", { organization_id: orgId, action: "disable" }); } catch (e) { fail("Disable failed", e); }
+  if (opts.json) { console.log(JSON.stringify(resp, null, 2)); return; }
+  console.log(`${resp.organization.name}: insights ${resp.changed ? "DISABLED" : "already disabled"} (schedules + recipients kept; re-enable with \`flowiq insights enable\`)`);
+}
+
+// ── run (Run Now) ────────────────────────────────────────────────────────────
+
+export async function run(orgId, opts = {}) {
+  requireUuid(orgId);
+  const body = { organization_id: orgId, action: "run", commit: opts.commit === true, force: opts.force === true, store_only: opts.storeOnly === true };
+  if (opts.from || opts.to) {
+    if (!opts.from || !opts.to) { console.error("Error: --from and --to go together (YYYY-MM-DD, SAST days)."); process.exit(1); }
+    try { const r = sastRange(opts.from, opts.to); body.start_date = r.start; body.end_date = r.end; }
+    catch (e) { console.error(`Error: ${e.message}`); process.exit(1); }
+  } else if (opts.period) {
+    if (!["daily", "weekly", "monthly"].includes(opts.period)) { console.error("Error: --period must be daily, weekly or monthly."); process.exit(1); }
+    body.period = opts.period;
+  }
+  if (opts.report) body.report_type = opts.report;
+  if (opts.recipient?.length) body.recipients = opts.recipient;
+
+  let resp;
+  try { resp = await http.post("insights", body); } catch (e) { fail("Run failed", e); }
+  if (opts.json) { console.log(JSON.stringify(resp, null, 2)); return; }
+
+  const o = resp.organization;
+  console.log(`${resp.dry_run ? "DRY RUN — " : "STARTED — "}${o.name}: ${resp.period} ${resp.report_type} report via ${resp.engine}`);
+  console.log(`  window:      ${fmtWhen(resp.window.start)} → ${fmtWhen(resp.window.end)} SAST  (${resp.messages_in_window ?? "?"} customer messages)`);
+  console.log(`  delivery:    ${resp.store_only ? "store only — no emails" : `email → ${resp.recipients.join(", ")}`}`);
+  printProblems(resp);
+  if (resp.dry_run) {
+    console.log(resp.would_run ? "\n  Would run. Add --commit to fire it." : "\n  Would NOT run — fix the ✗ items (or --force).");
+  } else {
+    console.log(`\n  job ${resp.job_id || "?"} — python-render is working in the background (a few minutes for a large org).`);
+    console.log(`  Check:  flowiq insights status ${orgId}   (the report appears under "Recent reports")`);
+  }
+}

package/src/commands/links.js

@@ -5,16 +5,26 @@
 // in the dialog: utm_source=whatsapp, utm_medium=whatsapp_paid fixed, campaign +
 // content yours.
 //
-//   flowiq links shorten <org> --url <u> [--url <u2>…] --campaign 13Aug_Seeds --content 13Aug_Seeds
-//   flowiq links shorten <org> --file ./message.txt --campaign X --content X --domain linklnk.io
+//   flowiq links shorten <org> --url <u> [--url <u2>…] --campaign "Spring Promotion"
+//   flowiq links shorten <org> --file ./message.txt --campaign X --content ViewMore --domain linklnk.io
 //   flowiq links list <org> [--campaign X] [--limit 25]
 //
+// NAMING — you do not have to get the tag right yourself. The house convention
+// is `Date_Campaign` (`9Sep_SpringPromotion`: the date the broadcast GOES OUT,
+// then the campaign title in PascalCase), and --campaign is normalised to it:
+// today's date is prefixed when you omit one, `Sept`→`Sep`, a fused
+// `10JunFathersDay` gains its underscore, and spaces/hyphens become PascalCase.
+// The resolved tag is printed before anything is minted (shorten is dry-run by
+// default). `--date <9Sep|2026-09-24|24/9/2026>` for a send going out later;
+// `--raw-campaign` to bypass normalisation entirely.
+//
 // Dry-run FIRST (`--dry-run`) on anything going into a real campaign: it shows
 // the exact destination URL each short link will carry, and whether an identical
 // row already exists (so you can see you are about to reuse an OLD campaign tag).
 
 import fs from "node:fs";
 import { http } from "../http.js";
+import { resolveCampaign, resolveContent, isConforming } from "../campaign-naming.js";
 
 const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 const URL_PATTERN = /(https?:\/\/[^\s\)]+)/g;
@@ -59,14 +69,50 @@ export async function shorten(orgId, opts = {}) {
 
   const dryRun = opts.dryRun !== false && opts.commit !== true;
 
+  // ── Campaign naming (Date_Campaign) ───────────────────────────────────────
+  // Normalise what was typed into the house convention so staff do not have to
+  // carry it in their heads. --raw-campaign opts out; the agent's own `ai_<org>`
+  // links are minted server-side and never come through here.
+  let campaign = opts.campaign;
+  let content = opts.content;
+  const namingNotes = [];
+  if (campaign && !opts.rawCampaign) {
+    const r = resolveCampaign(campaign, { date: opts.date });
+    if (r.error) {
+      console.error(`Error: ${r.error}`);
+      console.error(`Convention is Date_Campaign, e.g. --campaign "Spring Promotion" → 9Sep_SpringPromotion.`);
+      console.error(`Pass --raw-campaign to use "${campaign}" exactly as typed.`);
+      process.exit(1);
+    }
+    if (r.changed) namingNotes.push(`campaign "${campaign}" → ${r.value}`, ...r.notes.map((n) => `  · ${n}`));
+    campaign = r.value;
+  } else if (campaign && opts.rawCampaign && !isConforming(campaign)) {
+    namingNotes.push(`campaign "${campaign}" used raw (--raw-campaign) — does not match Date_Campaign`);
+  }
+  // utm_content is per-LINK (which button / which product). Default it to the
+  // campaign, which is what the paired-flags API expects and what most sends do.
+  if (campaign && !content) {
+    content = campaign;
+    namingNotes.push(`content defaulted to ${content} (pass --content for a per-link tag, e.g. ViewMore)`);
+  } else if (content && !opts.rawCampaign) {
+    const rc = resolveContent(content);
+    if (rc.changed) namingNotes.push(`content "${content}" → ${rc.value}`);
+    content = rc.value;
+  }
+  if (namingNotes.length && !opts.json) {
+    console.log("Naming (Date_Campaign):");
+    for (const n of namingNotes) console.log(`  ${n}`);
+    console.log("");
+  }
+
   let resp;
   try {
     resp = await http.post("links", {
       organization_id: orgId,
       action: "shorten",
       urls: unique,
-      campaign: opts.campaign,
-      content: opts.content,
+      campaign,
+      content,
       domain: opts.domain,
       dry_run: dryRun,
     });

package/src/commands/org-flags.js

@@ -0,0 +1,151 @@
+// `flowiq org flags …` — an org's feature flags (the Settings → Profile
+// switches) from the terminal.
+//
+//   flowiq org flags show <org_id>                     what this org carries (secrets redacted)
+//   flowiq org flags list --key <path> [--all]         which orgs carry ONE flag, and its value
+//   flowiq org flags set <org_id> <key> <value> [--yes] write a registered key (type-checked server-side)
+//   flowiq org flags unset <org_id> <key> --yes         remove a key (revert to the platform default)
+//   flowiq org flags keys                               what is settable, by Settings section
+//
+// The server (api/cli/org-flags + _org-flags-registry) is the only validator:
+// only keys the Profile tab manages can be set, credentials are never shown
+// or written, dangerous keys need --yes.
+
+import { http } from "../http.js";
+import { parseFlagValue, fmtValue } from "../flag-values.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 pad = (s, n) => String(s ?? "").padEnd(n);
+
+function requireUuid(orgId) {
+  if (!UUID_RE.test(orgId || "")) {
+    console.error(`Error: "${orgId}" is not a valid organization UUID (find it with \`flowiq org list <name>\`).`);
+    process.exit(1);
+  }
+}
+
+function fail(prefix, e) {
+  console.error(`${prefix}: ${e.message}`);
+  const b = e.body || {};
+  if (b.needs_confirm) {
+    if (b.danger) console.error(`  ⚠ ${b.danger}`);
+    if (b.before !== undefined) console.error(`  current: ${fmtValue(b.before)}`);
+    if (b.would_set !== undefined) console.error(`  would set: ${fmtValue(b.would_set)}`);
+    console.error("  Re-run with --yes to confirm.");
+  } else if (b.settable === false) {
+    console.error("  `flowiq org flags keys` lists what can be set; `flowiq org flags show <org>` still READS it.");
+  }
+  process.exit(1);
+}
+
+export async function keys(opts = {}) {
+  let resp;
+  try { resp = await http.get("org-flags", { keys: "1" }); } catch (e) { fail("Lookup failed", e); }
+  if (opts.json) { console.log(JSON.stringify(resp, null, 2)); return; }
+  const rows = (resp.keys || []).filter((k) => !opts.section || k.section.toLowerCase().includes(opts.section.toLowerCase()));
+  const bySection = new Map();
+  for (const k of rows) {
+    if (!bySection.has(k.section)) bySection.set(k.section, []);
+    bySection.get(k.section).push(k);
+  }
+  console.log(`Settable feature flags (${rows.length}) — the Settings → Profile switches, by section.\n`);
+  for (const [section, list] of bySection) {
+    console.log(`${section}`);
+    for (const k of list) {
+      const type = k.type === "integer" && k.min !== undefined ? `integer ${k.min}-${k.max}` : k.type;
+      console.log(`  ${pad(k.key, 46)} ${pad(type, 14)}${k.danger ? " ⚠ needs --yes" : ""}`);
+      if (k.note) console.log(`  ${pad("", 46)} ${k.note}`);
+    }
+    console.log("");
+  }
+  console.log("Wildcards (`x.*`) take one more segment, e.g. integrations_visible.instagram.");
+  console.log("Anything else on an org is readable via `flowiq org flags show` but not settable here.");
+}
+
+export async function show(orgId, opts = {}) {
+  requireUuid(orgId);
+  let resp;
+  try { resp = await http.get("org-flags", { organization_id: orgId }); } catch (e) { fail("Lookup failed", e); }
+  if (opts.json) { console.log(JSON.stringify(resp, null, 2)); return; }
+
+  const o = resp.organization;
+  console.log(`${o.name} (${o.id})${o.inactive ? "  [INACTIVE]" : ""} — ${resp.key_count} top-level flag key(s)\n`);
+  const known = Object.entries(resp.known || {});
+  if (known.length) {
+    const bySection = new Map();
+    for (const [key, v] of known) {
+      if (!bySection.has(v.section)) bySection.set(v.section, []);
+      bySection.get(v.section).push([key, v.value]);
+    }
+    for (const [section, list] of bySection) {
+      console.log(section);
+      for (const [key, value] of list) console.log(`  ${pad(key, 46)} ${fmtValue(value, 70)}`);
+      console.log("");
+    }
+  } else {
+    console.log("(none of the registered flags are set on this org)\n");
+  }
+  if (resp.unknown_keys?.length) {
+    console.log(`Other keys on this org (readable with --json, not settable from the CLI): ${resp.unknown_keys.join(", ")}`);
+  }
+  if (resp.secret_keys?.length) {
+    console.log(`Credentials present (never shown): ${resp.secret_keys.join(", ")}`);
+  }
+  console.log("\nChange one:  flowiq org flags set <org_id> <key> <value>   (see `flowiq org flags keys`)");
+}
+
+export async function list(opts = {}) {
+  if (!opts.key) { console.error("Error: --key <path> is required (e.g. --key export_insights.enabled)."); process.exit(1); }
+  let resp;
+  try { resp = await http.get("org-flags", { list: "1", key: opts.key, all: opts.all ? "1" : undefined }); } catch (e) { fail("Lookup failed", e); }
+  if (opts.json) { console.log(JSON.stringify(resp, null, 2)); return; }
+
+  let rows = resp.rows || [];
+  if (opts.on) rows = rows.filter((r) => r.value === true);
+  if (opts.off) rows = rows.filter((r) => r.value !== true);
+  if (opts.present) rows = rows.filter((r) => r.present);
+  if (opts.absent) rows = rows.filter((r) => !r.present);
+
+  const s = resp.summary;
+  const label = resp.registered ? ""
+    : resp.registered_parent ? `  (sub-key of \`${resp.registered_parent}\` — set it through the parent${resp.registered_parent === "export_insights" ? ", or \`flowiq insights enable\`" : ""})`
+    : "  (not a registered key — read-only)";
+  console.log(`${resp.key}${label} across ${s.orgs} org(s)${resp.include_inactive ? " incl. inactive" : ""}: ` +
+    `${s.present} present · ${s.absent} absent` + (s.true || s.false ? ` · ${s.true} true · ${s.false} false` : "") + "\n");
+  if (!rows.length) { console.log("(no orgs match the filter)"); return; }
+  const nameW = Math.min(34, Math.max(4, ...rows.map((r) => (r.name || "").length)));
+  console.log(`${pad("NAME", nameW)}  ${pad("ID", 36)}  VALUE`);
+  for (const r of rows) {
+    console.log(`${pad((r.name || "").slice(0, nameW), nameW)}  ${pad(r.id, 36)}  ${r.present ? fmtValue(r.value, 60) : "(absent)"}${r.inactive ? "  (inactive)" : ""}`);
+  }
+  console.log(`\n${rows.length} org(s) shown`);
+}
+
+export async function set(orgId, key, value, opts = {}) {
+  requireUuid(orgId);
+  let parsed;
+  try { parsed = parseFlagValue(value); } catch (e) { console.error(`Error: ${e.message}`); process.exit(1); }
+  let resp;
+  try {
+    resp = await http.post("org-flags", { organization_id: orgId, action: "set", key, value: parsed, confirm: opts.yes === true });
+  } catch (e) { fail("Set failed", e); }
+  if (opts.json) { console.log(JSON.stringify(resp, null, 2)); return; }
+  console.log(`${resp.organization.name} — ${resp.key}`);
+  console.log(`  ${fmtValue(resp.before, 70)} → ${fmtValue(resp.after, 70)}${resp.changed ? "" : "   (no change)"}`);
+  if (resp.danger) console.log(`  ⚠ ${resp.danger}`);
+  for (const w of resp.warnings || []) console.log(`  ⚠ ${w}`);
+  console.log(`  Undo: flowiq org flags ${resp.before === null ? `unset ${orgId} ${resp.key} --yes` : `set ${orgId} ${resp.key} '${JSON.stringify(resp.before)}'${resp.danger ? " --yes" : ""}`}`);
+}
+
+export async function unset(orgId, key, opts = {}) {
+  requireUuid(orgId);
+  let resp;
+  try {
+    resp = await http.post("org-flags", { organization_id: orgId, action: "unset", key, confirm: opts.yes === true });
+  } catch (e) { fail("Unset failed", e); }
+  if (opts.json) { console.log(JSON.stringify(resp, null, 2)); return; }
+  console.log(`${resp.organization.name} — removed ${resp.key}`);
+  console.log(`  was: ${fmtValue(resp.before, 70)}`);
+  for (const w of resp.warnings || []) console.log(`  ⚠ ${w}`);
+  console.log(`  Undo: flowiq org flags set ${orgId} ${resp.key} '${JSON.stringify(resp.before)}'${resp.danger ? " --yes" : ""}`);
+}