@flowapt/flowiq-cli 0.7.0 → 0.7.1

package/README.md

@@ -1131,6 +1131,54 @@ flowiq insights run <organization_id> --from 2026-09-01 --to 2026-09-07 --store-
   schedule for that period, else standard.
 - `enable` / `disable` / `run` are audited (`flowiq audit --endpoint insights`).
 
+### Team updates — `flowiq updates status|uncovered|draft|asset|preview|send` (v0.7.1)
+
+The **"what changed in FlowIQ" email to the Flowapt team** — every super admin
+gets it. An *issue* is a JSON file composed from `platform_changelog` rows:
+headline sections (a screenshot straight from the app, what it does, and a
+**For the team** note: how we use it, what to tell clients), an *Also shipped*
+list, and a *CLI and MCP* block. The renderer, the send (from
+flowiq@flowapt.com, reply-to Matt) and the record (`team_updates`, with the exact
+HTML that went out) live server-side in the `team-update-email` edge function.
+
+```bash
+flowiq updates status                                   # uncovered changelog rows · recent sends · recipients
+flowiq updates uncovered                                # the rows no issue has emailed yet
+flowiq updates draft                                    # → ./.flowiq/updates/<date>.json, a default issue to enrich
+flowiq updates draft --since 2026-09-07T22:00:00+02:00  # compose from a period instead of the last covered point
+flowiq updates asset ./api-keys-card.png                # host a screenshot, prints the https URL for image.url
+flowiq updates preview .flowiq/updates/2026-09-10.json --open   # render to .html exactly as emailed
+flowiq updates send .flowiq/updates/2026-09-10.json --test      # one copy to YOU; nothing marked covered
+flowiq updates send .flowiq/updates/2026-09-10.json --test --to kiah@flowapt.com
+flowiq updates send .flowiq/updates/2026-09-10.json --yes       # the real send, to every super admin
+```
+
+- **Issue shape** (`issue` key in the file): `subject`, `preheader`, `title`,
+  `intro`, `date_label`, `headlines[]`, `also[]`, `tools[]`, `closing`,
+  `changelog_ids[]`. A headline/tool section: `type` (feature | improvement |
+  fix | ui | agent | cli | infra | db | mcp — the chip is the app's own), `major`,
+  `title`, `what[]` (paragraphs), `team[]` (bullets), `image{url,alt,caption}`,
+  `terminal{command,output}`, `link{label,url}`, `org_name`, `version`. An
+  `also[]` item: `type`, `title`, `note`, `link`. Inline markup anywhere:
+  `**bold**`, `` `code` ``, `[label](https://…)`.
+- **`preview` and `send` lint the file first** (required fields, unknown types,
+  non-https images, em dashes) and stop with line-level help.
+- **`send` without `--test` needs `--yes`**: it emails the whole team AND moves
+  the covered-up-to mark, so those changelog rows will never be auto-digested.
+  `--test` sends to you (or `--to`) and marks nothing.
+- **The safety net:** pg_cron `team-update-email-daily` (08:30 SAST) emails a
+  default digest of any changelog row that has gone un-emailed for 20h+, so a
+  ship is never silently missed. The curated `send` is what stops it firing —
+  compose the issue the same day you ship.
+- **Who may do what:** everyone with a staff key can `status`, `uncovered`,
+  `draft`, `asset`, `preview` and `send --test` (a copy to yourself, nothing
+  marked covered). **The real send is Matt only** — any other key gets
+  `403 Only matt@flowapt.com may post the team update` and the attempt is
+  audited (`ALLOWED_SENDERS` in `api/cli/team-updates.js`).
+- Every link in the email opens the app's Changelog at that entry
+  (`app.flowiq.live/?changelog=1&entry=<id>`). `send` and `asset` are audited
+  (`flowiq audit --endpoint team-updates`).
+
 ### WhatsApp templates — `flowiq templates pull|list|show|create|status` (alias `tpl`)
 
 Read an org's live templates straight from Meta (read-only), render any single

package/TEAM-GUIDE.md

@@ -103,6 +103,9 @@ When you see it, run `npm i -g @flowapt/flowiq-cli` — a stale version also mea
 | 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) |
 | Client wants leads/requests emailed to their team instead of a human escalation | `flowiq agent config <org_id> --tool email_request_tool=true`, then set the recipient list in Agents → Tool Library → Email Request to Team (no CLI path for the addresses yet) |
 | Talk to the live agent safely (no real WhatsApp ever sent) | `flowiq test send <org_id> "hi, do you sell X?"` |
+| **Tell the team what shipped** (the FlowIQ team update email) | `flowiq updates draft` → enrich the JSON (screenshots via `flowiq updates asset`, a *For the team* note per headline) → `flowiq updates preview <file> --open` → `flowiq updates send <file> --test` → `flowiq updates send <file> --yes` |
+| Can I use `flowiq updates`? | Yes: `status`, `uncovered`, `draft`, `preview` and `send --test` (a copy to yourself) work for everyone. Only the real `send --yes` to the whole team is Matt's; anyone else gets a 403 there |
+| Which changelog rows has nobody emailed the team about yet? | `flowiq updates status` / `flowiq updates uncovered` — anything left 20h+ goes out automatically at 08:30 SAST as a plain digest |
 | Set which contact `flowiq test` uses (use a FAKE number!) | `flowiq agent config <org_id> --test-contact-number 27000000001 --test-contact-name "QA Bot"` |
 > **Publishing the CLI (maintainers only):** publish from a clean clone, never
 > from your working tree — `npm publish` packs whatever is on disk. A

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flowapt/flowiq-cli",
-  "version": "0.7.0",
+  "version": "0.7.1",
   "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/team-updates.js

@@ -0,0 +1,169 @@
+// `flowiq updates <verb>` — the "what changed in FlowIQ" email to the Flowapt team.
+//   status               uncovered changelog rows, last sends, who receives it
+//   uncovered            list the changelog rows no issue has covered yet
+//   draft [--out f]      write ./.flowiq/updates/<date>.json — a default issue
+//                        composed from the uncovered rows, ready to enrich
+//                        (screenshots, "for the team" notes, a CLI block)
+//   asset <file>         host an image for the email; prints the public URL
+//   preview <file>       render the issue to <file>.html (--open shows it)
+//   send <file>          --test → one copy to you (or --to a@b) without
+//                        marking anything covered; without --test the issue
+//                        goes to every super admin and needs --yes
+// The renderer, the send and the record all live server-side
+// (/cli/team-updates → the team-update-email edge fn); every send is audited.
+
+import fs from "node:fs/promises";
+import path from "node:path";
+import { spawn } from "node:child_process";
+import { http } from "../http.js";
+
+const DIR = path.resolve(process.cwd(), ".flowiq", "updates");
+const TYPES = ["feature", "improvement", "fix", "ui", "agent", "cli", "infra", "db", "mcp"];
+
+function sastStamp() {
+  return new Date().toLocaleDateString("en-CA", { timeZone: "Africa/Johannesburg" }); // YYYY-MM-DD
+}
+
+async function readIssue(file) {
+  const p = path.resolve(process.cwd(), file);
+  let raw;
+  try { raw = await fs.readFile(p, "utf8"); }
+  catch { console.error(`Error: cannot read ${p}`); process.exit(1); }
+  let doc;
+  try { doc = JSON.parse(raw); }
+  catch (e) { console.error(`Error: ${p} is not valid JSON (${e.message})`); process.exit(1); }
+  const issue = doc.issue && typeof doc.issue === "object" ? doc.issue : doc;
+  const problems = lint(issue);
+  if (problems.length) {
+    console.error(`Error: ${p} has ${problems.length} problem(s):`);
+    for (const m of problems) console.error(`  - ${m}`);
+    process.exit(1);
+  }
+  return { issue, file: p };
+}
+
+/** The same checks the server applies, so a bad file fails here with line-level help. */
+function lint(issue) {
+  const out = [];
+  if (!issue.subject) out.push("subject is required");
+  if (!issue.title) out.push("title is required");
+  const secs = [...(issue.headlines ?? []).map((s, i) => [`headlines[${i}]`, s]), ...(issue.tools ?? []).map((s, i) => [`tools[${i}]`, s])];
+  for (const [where, s] of secs) {
+    if (!s.title) out.push(`${where}: title is required`);
+    if (s.type && !TYPES.includes(s.type)) out.push(`${where}: type '${s.type}' is not one of ${TYPES.join("|")}`);
+    if (s.image && !/^https:\/\//.test(s.image.url || "")) out.push(`${where}: image.url must be https (host it with \`flowiq updates asset\`)`);
+    if (s.what && !Array.isArray(s.what)) out.push(`${where}: what must be an array of paragraphs`);
+    if (s.team && !Array.isArray(s.team)) out.push(`${where}: team must be an array of bullets`);
+  }
+  (issue.also ?? []).forEach((a, i) => {
+    if (!a.title) out.push(`also[${i}]: title is required`);
+    if (a.type && !TYPES.includes(a.type)) out.push(`also[${i}]: type '${a.type}' is not valid`);
+  });
+  const text = JSON.stringify(issue);
+  if (/—/.test(text)) out.push("contains an em dash (—) — house style is no em dashes in anything a teammate reads");
+  return out;
+}
+
+function fmtWhen(iso) {
+  return new Date(iso).toLocaleString("en-GB", { timeZone: "Africa/Johannesburg", day: "numeric", month: "short", hour: "2-digit", minute: "2-digit" });
+}
+
+export async function status(opts) {
+  let r;
+  try { r = await http.get("team-updates"); }
+  catch (e) { console.error(`Status failed: ${e.message}`); process.exit(1); }
+  if (opts?.json) { console.log(JSON.stringify(r, null, 2)); return; }
+  console.log(`Team updates`);
+  console.log(`  uncovered:  ${r.uncovered} changelog row(s) not yet emailed${r.covered_until ? ` (covered up to ${fmtWhen(r.covered_until)} SAST)` : " (nothing has ever been sent)"}`);
+  console.log(`  recipients: ${(r.recipients ?? []).map((x) => x.email).join(", ") || "none"}`);
+  if (Array.isArray(r.recent) && r.recent.length) {
+    console.log(`  recent:`);
+    for (const s of r.recent) console.log(`    ${fmtWhen(s.created_at)}  ${s.status.padEnd(6)} ${s.source.padEnd(9)} ${String(s.subject).slice(0, 70)}  → ${s.recipients?.length ?? 0}`);
+  }
+}
+
+export async function uncovered(opts) {
+  let r;
+  try { r = await http.get("team-updates", { uncovered: 1, limit: opts?.limit ?? 60 }); }
+  catch (e) { console.error(`Failed: ${e.message}`); process.exit(1); }
+  if (opts?.json) { console.log(JSON.stringify(r, null, 2)); return; }
+  if (!r.rows?.length) { console.log("Nothing uncovered — every changelog row has been emailed."); return; }
+  console.log(`${r.rows.length} uncovered row(s)${r.since ? ` since ${fmtWhen(r.since)} SAST` : ""}:`);
+  for (const row of r.rows) console.log(`  ${fmtWhen(row.created_at)}  ${row.type.padEnd(11)} ${row.is_major ? "MAJOR " : "      "} ${row.title}${row.org_name ? `  [${row.org_name}]` : ""}`);
+}
+
+export async function draft(opts) {
+  let r;
+  try { r = await http.get("team-updates", { draft: 1, limit: opts?.limit ?? 60, since: opts?.since }); }
+  catch (e) { console.error(`Draft failed: ${e.message}`); process.exit(1); }
+  if (!r.count) { console.log("Nothing to draft — every changelog row has been emailed. Use --since <iso> to re-cover a period."); return; }
+  await fs.mkdir(DIR, { recursive: true });
+  const out = path.resolve(process.cwd(), opts?.out || path.join(DIR, `${sastStamp()}.json`));
+  const doc = {
+    _help: [
+      "This is a default issue composed from the uncovered changelog rows. Enrich it, then `flowiq updates preview` / `send`.",
+      "headlines[]: type, major, title, what[] (paragraphs), team[] (bullets: how WE use it / what to tell clients), image{url,alt,caption} (host with `flowiq updates asset`), terminal{command,output}, link{label,url}.",
+      "also[]: short rows (title, note, type). tools[]: CLI / MCP sections, same shape as headlines.",
+      "Inline markup in any text: **bold**, `code`, [label](https://…). No emoji, no em dashes.",
+    ],
+    issue: r.issue,
+  };
+  await fs.writeFile(out, JSON.stringify(doc, null, 2) + "\n");
+  console.log(`Drafted ${r.count} row(s) → ${path.relative(process.cwd(), out)}`);
+  console.log(`  headlines ${r.issue.headlines?.length ?? 0} · also ${r.issue.also?.length ?? 0} · cli/mcp ${r.issue.tools?.length ?? 0}`);
+  console.log(`  next: enrich it, then \`flowiq updates preview ${path.relative(process.cwd(), out)} --open\``);
+}
+
+export async function asset(file, opts) {
+  const p = path.resolve(process.cwd(), file);
+  let buf;
+  try { buf = await fs.readFile(p); }
+  catch { console.error(`Error: cannot read ${p}`); process.exit(1); }
+  const ext = path.extname(p).toLowerCase();
+  const type = { ".png": "image/png", ".jpg": "image/jpeg", ".jpeg": "image/jpeg", ".webp": "image/webp", ".gif": "image/gif" }[ext];
+  if (!type) { console.error(`Error: ${ext || "(no extension)"} is not an image type the email can use (png, jpg, webp, gif)`); process.exit(1); }
+  let r;
+  try { r = await http.post("team-updates", { action: "asset", name: opts?.name || path.basename(p), content_type: type, data_base64: buf.toString("base64") }); }
+  catch (e) { console.error(`Upload failed: ${e.message}`); process.exit(1); }
+  console.log(r.url);
+}
+
+export async function preview(file, opts) {
+  const { issue, file: p } = await readIssue(file);
+  let r;
+  try { r = await http.post("team-updates", { action: "preview", issue, to_name: opts?.as || "Matt" }); }
+  catch (e) { console.error(`Preview failed: ${e.message}`); process.exit(1); }
+  const out = p.replace(/\.json$/i, "") + ".html";
+  await fs.writeFile(out, r.html);
+  console.log(`Subject: ${r.subject}`);
+  console.log(`Rendered → ${path.relative(process.cwd(), out)} (${(r.html.length / 1024).toFixed(1)} KB)`);
+  if (opts?.open) spawn(process.platform === "darwin" ? "open" : "xdg-open", [out], { stdio: "ignore", detached: true }).unref();
+}
+
+export async function send(file, opts) {
+  const { issue } = await readIssue(file);
+  const to = (opts?.to || "").split(",").map((s) => s.trim().toLowerCase()).filter(Boolean);
+  const test = !!opts?.test;
+  if (test && !to.length) {
+    let me;
+    try { me = await http.get("whoami"); }
+    catch (e) { console.error(`whoami failed: ${e.message}`); process.exit(1); }
+    const email = me?.user_email || me?.email || me?.userEmail;
+    if (!email) { console.error("Could not resolve your email for the test send; pass --to."); process.exit(1); }
+    to.push(email);
+  }
+  if (!test && !opts?.yes) {
+    console.error("Refusing: this sends to the whole Flowapt team and marks the changelog rows as covered. Re-run with --yes, or use --test first.");
+    process.exit(1);
+  }
+  let r;
+  try { r = await http.post("team-updates", { action: "send", issue, to: to.length ? to : undefined, test }); }
+  catch (e) { console.error(`Send failed: ${e.message}`); process.exit(1); }
+  const ok = (r.recipients ?? []).filter((x) => x.status === "sent");
+  const bad = (r.recipients ?? []).filter((x) => x.status !== "sent");
+  console.log(`${test ? "Test sent" : "Sent"}: "${issue.subject}"`);
+  for (const x of ok) console.log(`  ✓ ${x.to}`);
+  for (const x of bad) console.log(`  ✗ ${x.to}  ${x.error ?? x.status}`);
+  if (!test) console.log(r.covers_until ? `  covered up to ${fmtWhen(r.covers_until)} SAST · record ${r.id}` : `  NOT marked as covered (every send failed)`);
+  if (bad.length) process.exitCode = 1;
+}

package/src/index.js

@@ -21,6 +21,7 @@ import * as templatesCmd from "./commands/templates.js";
 import * as orgCmd from "./commands/org.js";
 import * as orgFlagsCmd from "./commands/org-flags.js";
 import * as insightsCmd from "./commands/insights.js";
+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";
@@ -864,6 +865,39 @@ export function run(argv) {
     .option("--out <file>", "write the JSON to a file instead of stdout")
     .action((orgId, path, opts) => storeApiCmd.wooGet(orgId, path, opts));
 
+  // updates — the "what changed in FlowIQ" email to the Flowapt team
+  const updates = program.command("updates").description("Team update email: what changed in FlowIQ, sent to every super admin (status / draft / preview / send)");
+  updates.command("status")
+    .description("uncovered changelog rows, recent sends and who receives the email")
+    .option("--json", "machine-readable output")
+    .action((opts) => teamUpdatesCmd.status(opts));
+  updates.command("uncovered")
+    .description("list the changelog rows no team update has covered yet")
+    .option("--limit <n>", "rows to list (default 60)")
+    .option("--json", "machine-readable output")
+    .action((opts) => teamUpdatesCmd.uncovered(opts));
+  updates.command("draft")
+    .description("write ./.flowiq/updates/<date>.json: a default issue composed from the uncovered rows, ready to enrich")
+    .option("--since <iso>", "compose from rows created after this time instead of the last covered point")
+    .option("--limit <n>", "rows to include (default 60)")
+    .option("--out <file>", "write the issue here instead of ./.flowiq/updates/<date>.json")
+    .action((opts) => teamUpdatesCmd.draft(opts));
+  updates.command("asset <file>")
+    .description("host an image (png/jpg/webp/gif, max 6 MB) for the email and print its public URL")
+    .option("--name <name>", "file name to store under (default: the file's own name)")
+    .action((file, opts) => teamUpdatesCmd.asset(file, opts));
+  updates.command("preview <file>")
+    .description("render the issue JSON to <file>.html exactly as it will be emailed")
+    .option("--as <first-name>", "greet this name in the preview (default Matt)")
+    .option("--open", "open the rendered HTML in the browser")
+    .action((file, opts) => teamUpdatesCmd.preview(file, opts));
+  updates.command("send <file>")
+    .description("email the issue: --test sends one copy to you (or --to) and marks nothing; without --test it goes to every super admin and needs --yes")
+    .option("--test", "send a single test copy only (to you unless --to is given); nothing is marked as covered")
+    .option("--to <emails>", "comma-separated recipients instead of the team list")
+    .option("--yes", "confirm the real send to the whole team")
+    .action((file, opts) => teamUpdatesCmd.send(file, opts));
+
   // doctor (version + auth + server contract in one read-only command)
   program.command("doctor")
     .description("Check this install: version vs npm, auth, and whether the server still supports it. Exits 1 if something needs fixing")