@flowapt/flowiq-cli 0.1.5 → 0.1.6

package/README.md

@@ -1,9 +1,9 @@
 # flowiq
 
 FlowIQ staff CLI. Round-trips agent prompts, questionnaires, fine-tuning,
-contact chats, platform webhooks, and outbound messaging webhooks through
-`https://api.flowiq.live/cli/*` so the Supabase service role never leaves
-the server.
+contact chats, platform webhooks, outbound messaging webhooks, and FlowMod
+master-group prompts through `https://api.flowiq.live/cli/*` so the Supabase
+service role never leaves the server.
 
 ## Install
 
@@ -150,12 +150,74 @@ Validation: `platform` ∈ `{whatsapp, web}`, `type` from the per-platform
 allowed enum, valid http(s) URL, no duplicate (platform, type, url)
 tuples.
 
+### FlowMod prompts — `flowiq flowmod pull|push <slug>` (alias `fm`)
+
+Round-trips a FlowMod org's **master-group** prompts + config. FlowMod groups
+are a separate system from regular WhatsApp agents — their prompts live in the
+`flowmod_master_groups` (model/pre-filter/config/signatures/custom_tools) and
+`flowmod_prompts` (the `main` / `extra` prompt rows, keyed by `master_group_id`)
+tables, read per-message by the `flowmod-group-*` webhooks.
+
+```bash
+flowiq flowmod pull <organization_id>
+# edit ./.flowiq/flowmod/<slug>.json
+flowiq fm push <slug>
+```
+
+The pulled JSON has a `master_groups[]` array; each entry carries its editable
+fields plus a `prompts[]` array (`{ id, type, group_ids, text, data }`). Push
+updates only editable columns — prompt `text`/`data`/`group_ids`/`type`, and
+master-group `name`/`description`/`config`/`pre_filter_prompt`/`events_markdown`/
+`custom_signature*`/`custom_tools` — scoped by row id; it never touches PKs,
+FKs, or timestamps, and there's no `system_prompt` regeneration (FlowMod reads
+the prompt rows directly).
+
+Common uses: edit a master-group's moderator prompt, or flip its reasoning
+effort via `config.reasoningEffort` (`none` / `low` / `medium` / `high`).
+
+### Group chats — `flowiq groups list|pull <name-or-jid>` (alias `grp`)
+
+Read-only pull of **WhatsApp group** chat history (e.g. the `… x Flowapt`
+client comms groups) straight out of the FlowMod **Evolution** Postgres. This
+is the analogue of `messages pull`, but for a group instead of a contact, so
+you can pull a window and summarise it.
+
+> ⚠️ Unlike every other command, this talks to a database **directly** (the
+> Evolution DB is not Supabase and not the `fiq_staff_…` API). To keep this
+> published package secret-free, the connection string comes from your shell
+> environment — set `FLOWMOD_EVO_DB_URL` (or the five `FLOWMOD_DB_*` vars the
+> `flowmod-copilot` edge fn uses) before running. No auth token is needed.
+
+```bash
+export FLOWMOD_EVO_DB_URL='postgres://user:pass@app.flowmod.ai:5555/flowiq-db'
+
+flowiq groups list                               # default instance: flowapt
+flowiq groups list --instance FlowMod            # the other connected instance
+
+flowiq groups pull "Phytoceutics x Flowapt" --last 7d
+flowiq groups pull "Zorora x Flowapt" --since 2026-06-24 --until "2026-06-25 12:00"
+flowiq grp pull 120363408455897717@g.us --last 48h   # or pass the group JID
+# writes ./.flowiq/groups/<instance>-<group-slug>.json + prints a timeline
+```
+
+- Group is matched by JID, exact name, or a unique case-insensitive substring
+  (ambiguous matches list the candidates and exit — pass the JID to disambiguate).
+- Window: `--last <48h|7d|2w|90m>` (default `48h`), or an explicit
+  `--since`/`--until` (SAST; `--until` defaults to now). `--limit` (default
+  1000) keeps the most-recent N in the window.
+- `--json` prints the full payload to stdout instead of the timeline.
+- Read-only — there is no `push`; group history is a system of record.
+  View-once/disappearing messages and raw media bodies can't be read (captions
+  and text come through); history before the instance joined a group may be gappy.
+
 ## Environment variable overrides
 
 | Var | Default | Use |
 |---|---|---|
 | `FLOWIQ_API_URL` | `https://api.flowiq.live` | Override the API host (local dev, staging). |
 | `FLOWIQ_TOKEN` | (saved in `~/.config/flowiq/auth.json`) | Override the auth token, useful for CI. |
+| `FLOWMOD_EVO_DB_URL` | (none) | Full `postgres://` URL for `groups` (Evolution DB). Required for `groups`. |
+| `FLOWMOD_DB_HOST/PORT/USER/PASS/NAME` | (none) | Alternative to `FLOWMOD_EVO_DB_URL` — assembled into a connection string. |
 
 ## Upgrading
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@flowapt/flowiq-cli",
-  "version": "0.1.5",
-  "description": "Command-line tool for FlowIQ staff: round-trip agent prompts, questionnaires, webhooks, and more without ever touching service-role credentials.",
+  "version": "0.1.6",
+  "description": "Command-line tool for FlowIQ staff: round-trip agent prompts, questionnaires, FlowMod master-group prompts, webhooks, and more without ever touching service-role credentials.",
   "type": "module",
   "bin": {
     "flowiq": "bin/flowiq.js"
@@ -18,7 +18,8 @@
     "start": "node bin/flowiq.js"
   },
   "dependencies": {
-    "commander": "^12.1.0"
+    "commander": "^12.1.0",
+    "pg": "^8.22.0"
   },
   "homepage": "https://github.com/MattFlowapt/flow-v1/tree/main/cli",
   "repository": {

package/src/commands/flowmod.js

@@ -0,0 +1,130 @@
+// `flowiq flowmod pull <organization_id>` /
+// `flowiq flowmod push <slug>`.
+// Round-trips an org's FlowMod master-group prompts + config (the
+// flowmod_master_groups + flowmod_prompts tables) through a local JSON file.
+// No DB credentials on disk — all privileged work happens server-side in
+// /api/cli/flowmod.
+
+import fs from "node:fs/promises";
+import path from "node:path";
+import { http } from "../http.js";
+
+const FLOWMOD_DIR = path.resolve(process.cwd(), ".flowiq", "flowmod");
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+function slugify(name, fallback) {
+  const s = String(name || "")
+    .toLowerCase()
+    .replace(/&/g, "and")
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/-+/g, "-")
+    .replace(/^-|-$/g, "");
+  return s || fallback;
+}
+
+async function fileExists(p) {
+  try { await fs.access(p); return true; } catch { return false; }
+}
+
+async function resolvePushPath(identifier) {
+  const candidates = [];
+  if (path.isAbsolute(identifier)) {
+    candidates.push(identifier);
+  } else if (identifier.includes("/") || identifier.includes("\\")) {
+    candidates.push(path.resolve(identifier));
+  } else {
+    const base = identifier.endsWith(".json") ? identifier : `${identifier}.json`;
+    candidates.push(path.join(FLOWMOD_DIR, base));
+    candidates.push(path.resolve(base));
+  }
+  for (const c of candidates) {
+    if (await fileExists(c)) return c;
+  }
+  throw new Error(`File not found. Tried:\n  ${candidates.join("\n  ")}`);
+}
+
+function mainPromptChars(mg) {
+  const prompts = mg.prompts || [];
+  // Prefer the master-level main (no group_ids); fall back to any main prompt
+  // (some master_groups pin their main prompt to specific group_ids).
+  const main =
+    prompts.find((p) => p.type === "main" && (!Array.isArray(p.group_ids) || p.group_ids.length === 0)) ||
+    prompts.find((p) => p.type === "main");
+  return main ? (main.text || "").length : 0;
+}
+
+export async function pull(orgId) {
+  if (!UUID_RE.test(orgId)) {
+    console.error(`Error: "${orgId}" is not a valid organization UUID.`);
+    process.exit(1);
+  }
+  let resp;
+  try {
+    resp = await http.get("flowmod", { organization_id: orgId });
+  } catch (e) {
+    console.error(`Pull failed: ${e.message}`);
+    process.exit(1);
+  }
+
+  await fs.mkdir(FLOWMOD_DIR, { recursive: true });
+  const slug = slugify(resp.organization_name, resp.organization_id);
+  const filePath = path.join(FLOWMOD_DIR, `${slug}.json`);
+  const overwriting = await fileExists(filePath);
+  await fs.writeFile(filePath, JSON.stringify(resp, null, 2) + "\n", "utf8");
+
+  const totalPrompts = (resp.master_groups || []).reduce((a, mg) => a + (mg.prompts?.length ?? 0), 0);
+  console.log(`${overwriting ? "Overwrote" : "Wrote"} ${filePath}`);
+  console.log(`  org:           ${resp.organization_name} (${resp.organization_id})`);
+  console.log(`  master_groups: ${resp.master_groups?.length ?? 0} (${totalPrompts} prompt rows)`);
+  for (const mg of resp.master_groups || []) {
+    const cfg = mg.config || {};
+    const cfgBits = [
+      cfg.model && `model=${cfg.model}`,
+      cfg.reasoningEffort && `effort=${cfg.reasoningEffort}`,
+      Array.isArray(mg.custom_tools) && mg.custom_tools.length ? `${mg.custom_tools.length} tools` : null,
+    ].filter(Boolean).join(", ");
+    console.log(`    • ${mg.name}: main=${mainPromptChars(mg)} chars${cfgBits ? `  (${cfgBits})` : ""}`);
+  }
+}
+
+export async function push(identifier) {
+  let filePath;
+  try {
+    filePath = await resolvePushPath(identifier);
+  } catch (e) {
+    console.error(`Error: ${e.message}`);
+    process.exit(1);
+  }
+  const raw = await fs.readFile(filePath, "utf8");
+  let data;
+  try { data = JSON.parse(raw); }
+  catch (e) {
+    console.error(`Invalid JSON in ${filePath}: ${e.message}`);
+    process.exit(1);
+  }
+
+  if (!data.organization_id || !UUID_RE.test(data.organization_id)) {
+    console.error(`${filePath}: organization_id missing or invalid`);
+    process.exit(1);
+  }
+  if (!Array.isArray(data.master_groups) || data.master_groups.length === 0) {
+    console.error(`${filePath}: master_groups must be a non-empty array`);
+    process.exit(1);
+  }
+
+  let resp;
+  try {
+    resp = await http.post("flowmod", {
+      organization_id: data.organization_id,
+      master_groups: data.master_groups,
+    });
+  } catch (e) {
+    console.error(`Push failed: ${e.message}`);
+    process.exit(1);
+  }
+
+  console.log(`Pushed ${filePath}`);
+  console.log(`  org:           ${resp.organization_name} (${resp.organization_id})`);
+  console.log(`  master_groups: ${resp.master_groups_updated} updated`);
+  console.log(`  prompts:       ${resp.prompts_updated} updated`);
+}

package/src/commands/groups.js

@@ -0,0 +1,329 @@
+// `flowiq groups list|pull` — read WhatsApp GROUP chat history out of the
+// FlowMod Evolution Postgres (app.flowmod.ai:5555), mirroring `messages pull`.
+//
+// This is the only CLI command that talks to a database directly instead of
+// going through api.flowiq.live/cli/* — the Evolution DB is a separate Postgres
+// (NOT Supabase, NOT a service-role key). To keep this published npm package
+// secret-free, the connection string comes from the environment, never source:
+//
+//   FLOWMOD_EVO_DB_URL=postgres://user:pass@app.flowmod.ai:5555/flowiq-db
+//     — or the five vars the flowmod-copilot edge fn already uses —
+//   FLOWMOD_DB_HOST / FLOWMOD_DB_PORT / FLOWMOD_DB_USER / FLOWMOD_DB_PASS / FLOWMOD_DB_NAME
+//
+// Read-only: there is no `push` — group history is a system of record.
+
+import fs from "node:fs/promises";
+import path from "node:path";
+
+const OUT_DIR = path.resolve(process.cwd(), ".flowiq", "groups");
+const DEFAULT_INSTANCE = "flowapt";
+const DEFAULT_LAST_MS = 48 * 3600 * 1000; // 48h
+const DEFAULT_LIMIT = 1000;
+
+// ---------- credential resolution (env only — no baked secret) ----------
+function evoConnString() {
+  const url = process.env.FLOWMOD_EVO_DB_URL?.trim();
+  if (url) return url;
+  const host = process.env.FLOWMOD_DB_HOST?.trim();
+  const user = process.env.FLOWMOD_DB_USER?.trim();
+  const pass = process.env.FLOWMOD_DB_PASS;
+  const name = process.env.FLOWMOD_DB_NAME?.trim();
+  if (host && user && pass != null && name) {
+    const port = process.env.FLOWMOD_DB_PORT?.trim() || "5555";
+    return `postgres://${encodeURIComponent(user)}:${encodeURIComponent(pass)}@${host}:${port}/${name}`;
+  }
+  return null;
+}
+
+async function connect() {
+  const conn = evoConnString();
+  if (!conn) {
+    console.error(
+      "Error: no Evolution DB connection configured.\n" +
+        "Set FLOWMOD_EVO_DB_URL (a full postgres:// URL) in your shell env,\n" +
+        "or the five FLOWMOD_DB_HOST/PORT/USER/PASS/NAME vars.\n" +
+        "Creds are in ~/.claude/context/external-services.md (FlowMod Evolution section)."
+    );
+    process.exit(1);
+  }
+  let Client;
+  try {
+    const mod = await import("pg");
+    Client = (mod.default ?? mod).Client;
+  } catch {
+    console.error("Error: the `pg` package is not installed. Run `npm install` in the cli/ folder.");
+    process.exit(1);
+  }
+  const client = new Client({ connectionString: conn, ssl: false });
+  try {
+    await client.connect();
+  } catch (e) {
+    console.error(`Could not connect to the Evolution DB: ${e.message}`);
+    process.exit(1);
+  }
+  return client;
+}
+
+// ---------- helpers ----------
+function slugify(name, fallback) {
+  const s = String(name || "")
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/-+/g, "-")
+    .replace(/^-|-$/g, "");
+  return s || fallback;
+}
+
+async function fileExists(p) {
+  try { await fs.access(p); return true; } catch { return false; }
+}
+
+// "48h" | "7d" | "90m" | "2w" -> milliseconds (null if unparseable)
+function parseLast(s) {
+  const m = /^(\d+)\s*(m|h|d|w)$/i.exec(String(s).trim());
+  if (!m) return null;
+  const n = Number(m[1]);
+  const mult = { m: 60e3, h: 3600e3, d: 86400e3, w: 604800e3 }[m[2].toLowerCase()];
+  return n * mult;
+}
+
+// "YYYY-MM-DD" | "YYYY-MM-DD HH:MM[:SS]" interpreted as SAST -> unix seconds
+function sastToUnix(s) {
+  const m = /^(\d{4}-\d{2}-\d{2})(?:[ T](\d{2}:\d{2}(?::\d{2})?))?$/.exec(String(s).trim());
+  if (!m) return null;
+  let time = m[2] || "00:00";
+  if (time.length === 5) time += ":00";
+  const d = new Date(`${m[1]}T${time}+02:00`);
+  return Number.isNaN(d.getTime()) ? null : Math.floor(d.getTime() / 1000);
+}
+
+// unix seconds -> "YYYY-MM-DD HH:MM" in SAST (full=false drops the year/date prefix into MM-DD)
+function fmtSast(unix, full = true) {
+  const d = new Date(unix * 1000);
+  const p = new Intl.DateTimeFormat("en-ZA", {
+    timeZone: "Africa/Johannesburg",
+    year: "numeric", month: "2-digit", day: "2-digit",
+    hour: "2-digit", minute: "2-digit", hour12: false,
+  }).formatToParts(d).reduce((a, x) => ((a[x.type] = x.value), a), {});
+  return full
+    ? `${p.year}-${p.month}-${p.day} ${p.hour}:${p.minute}`
+    : `${p.month}-${p.day} ${p.hour}:${p.minute}`;
+}
+
+// Pull a human-readable body out of Evolution's `message` jsonb.
+function extractText(m) {
+  if (!m || typeof m !== "object") return null;
+  if (m.conversation) return m.conversation;
+  if (m.extendedTextMessage?.text) return m.extendedTextMessage.text;
+  if (m.imageMessage) return m.imageMessage.caption ? `[image] ${m.imageMessage.caption}` : "[image]";
+  if (m.videoMessage) return m.videoMessage.caption ? `[video] ${m.videoMessage.caption}` : "[video]";
+  if (m.audioMessage) return m.audioMessage.ptt ? "[voice note]" : "[audio]";
+  if (m.documentMessage) return `[document] ${m.documentMessage.fileName || ""}`.trim();
+  if (m.documentWithCaptionMessage?.message?.documentMessage)
+    return `[document] ${m.documentWithCaptionMessage.message.documentMessage.fileName || ""}`.trim();
+  if (m.stickerMessage) return "[sticker]";
+  if (m.locationMessage) return "[location]";
+  if (m.contactMessage || m.contactsArrayMessage) return "[contact card]";
+  if (m.reactionMessage) return `[reaction ${m.reactionMessage.text || ""}]`.trim();
+  if (m.pollCreationMessage || m.pollCreationMessageV3)
+    return `[poll] ${(m.pollCreationMessage || m.pollCreationMessageV3).name || ""}`.trim();
+  if (m.protocolMessage) return null; // system/internal — skip
+  return null;
+}
+
+async function resolveInstanceId(client, instanceName) {
+  const r = await client.query('SELECT id, "profileName" FROM "Instance" WHERE name = $1', [instanceName]);
+  if (!r.rows.length) {
+    const all = await client.query('SELECT name FROM "Instance" ORDER BY name');
+    console.error(
+      `Error: no Evolution instance named "${instanceName}". Available: ${all.rows.map((x) => x.name).join(", ")}`
+    );
+    process.exit(1);
+  }
+  return r.rows[0];
+}
+
+// ---------- groups list ----------
+export async function list(opts = {}) {
+  const instanceName = opts.instance || DEFAULT_INSTANCE;
+  const client = await connect();
+  try {
+    const inst = await resolveInstanceId(client, instanceName);
+    const r = await client.query(
+      `SELECT ch.name,
+              ch."remoteJid" AS jid,
+              (SELECT count(DISTINCT m.key->>'id') FROM "Message" m
+                 WHERE m."instanceId" = $1 AND m.key->>'remoteJid' = ch."remoteJid") AS msgs,
+              (SELECT max((m."messageTimestamp")::bigint) FROM "Message" m
+                 WHERE m."instanceId" = $1 AND m.key->>'remoteJid' = ch."remoteJid") AS last_ts
+         FROM "Chat" ch
+        WHERE ch."instanceId" = $1 AND ch."remoteJid" LIKE '%@g.us'
+        ORDER BY last_ts DESC NULLS LAST`,
+      [inst.id]
+    );
+    console.log(`Instance "${instanceName}" (${inst.profileName ?? "?"}) — ${r.rows.length} group chats\n`);
+    const rows = r.rows.map((x) => ({
+      group: x.name || "(no name)",
+      msgs: Number(x.msgs || 0),
+      last: x.last_ts ? fmtSast(Number(x.last_ts)) : "—",
+      jid: x.jid,
+    }));
+    const wName = Math.min(48, Math.max(...rows.map((x) => x.group.length), 5));
+    for (const x of rows) {
+      console.log(
+        `  ${x.group.padEnd(wName)}  ${String(x.msgs).padStart(5)} msgs   last ${x.last.padEnd(16)}  ${x.jid}`
+      );
+    }
+  } finally {
+    await client.end();
+  }
+}
+
+// ---------- groups pull ----------
+export async function pull(nameOrJid, opts = {}) {
+  const instanceName = opts.instance || DEFAULT_INSTANCE;
+  const limit = Math.max(1, Math.min(Number(opts.limit) || DEFAULT_LIMIT, 5000));
+
+  // window
+  let untilUnix = Math.floor(Date.now() / 1000);
+  let sinceUnix;
+  if (opts.until) {
+    const u = sastToUnix(opts.until);
+    if (u == null) { console.error(`Error: --until "${opts.until}" is not a valid date (use YYYY-MM-DD or "YYYY-MM-DD HH:MM").`); process.exit(1); }
+    untilUnix = u;
+  }
+  if (opts.since) {
+    const s = sastToUnix(opts.since);
+    if (s == null) { console.error(`Error: --since "${opts.since}" is not a valid date (use YYYY-MM-DD or "YYYY-MM-DD HH:MM").`); process.exit(1); }
+    sinceUnix = s;
+  } else {
+    const lastMs = opts.last ? parseLast(opts.last) : DEFAULT_LAST_MS;
+    if (lastMs == null) { console.error(`Error: --last "${opts.last}" is not valid (use e.g. 48h, 7d, 2w, 90m).`); process.exit(1); }
+    sinceUnix = untilUnix - Math.floor(lastMs / 1000);
+  }
+  if (sinceUnix > untilUnix) { console.error("Error: --since is after --until."); process.exit(1); }
+
+  const client = await connect();
+  try {
+    const inst = await resolveInstanceId(client, instanceName);
+
+    // resolve the group: exact JID, else exact name (case-insensitive), else contains
+    const groups = await client.query(
+      `SELECT ch."remoteJid" AS jid, ch.name FROM "Chat" ch
+        WHERE ch."instanceId" = $1 AND ch."remoteJid" LIKE '%@g.us'`,
+      [inst.id]
+    );
+    let match;
+    const arg = String(nameOrJid).trim();
+    if (/@g\.us$/.test(arg)) {
+      match = groups.rows.find((g) => g.jid === arg);
+    } else {
+      const lc = arg.toLowerCase();
+      const exact = groups.rows.filter((g) => (g.name || "").toLowerCase() === lc);
+      const contains = groups.rows.filter((g) => (g.name || "").toLowerCase().includes(lc));
+      const hits = exact.length ? exact : contains;
+      if (hits.length > 1) {
+        console.error(`"${arg}" matches ${hits.length} groups — be more specific or pass the JID:`);
+        for (const g of hits) console.error(`  ${g.name}  ${g.jid}`);
+        process.exit(1);
+      }
+      match = hits[0];
+    }
+    if (!match) {
+      console.error(`Error: no group matching "${arg}" on instance "${instanceName}". Try \`flowiq groups list --instance ${instanceName}\`.`);
+      process.exit(1);
+    }
+
+    // pull deduped messages in window
+    const r = await client.query(
+      `SELECT DISTINCT ON (m.key->>'id')
+              m.key->>'id'      AS mid,
+              m."pushName"      AS push_name,
+              m."participant"   AS participant,
+              m."messageType"   AS message_type,
+              m.message         AS message,
+              (m."messageTimestamp")::bigint AS ts,
+              m.key->>'fromMe'  AS from_me
+         FROM "Message" m
+        WHERE m."instanceId" = $1 AND m.key->>'remoteJid' = $2
+          AND (m."messageTimestamp")::bigint >= $3
+          AND (m."messageTimestamp")::bigint <= $4
+        ORDER BY m.key->>'id', m."messageTimestamp" DESC`,
+      [inst.id, match.jid, sinceUnix, untilUnix]
+    );
+
+    let rows = r.rows
+      .map((x) => {
+        const fromMe = x.from_me === "true" || x.from_me === true;
+        return {
+          ts: Number(x.ts),
+          ts_sast: fmtSast(Number(x.ts)),
+          sender: fromMe ? (inst.profileName || "Flowapt") : (x.push_name || "(unknown)"),
+          from_me: fromMe,
+          participant: x.participant || null,
+          type: x.message_type,
+          text: extractText(x.message),
+        };
+      })
+      .sort((a, b) => a.ts - b.ts);
+
+    const totalInWindow = rows.length;
+    let truncated = 0;
+    if (rows.length > limit) {
+      truncated = rows.length - limit;
+      rows = rows.slice(rows.length - limit); // keep the most recent `limit`
+    }
+
+    // participants
+    const participants = {};
+    for (const m of rows) if (!m.from_me) participants[m.sender] = (participants[m.sender] || 0) + 1;
+
+    const payload = {
+      instance: instanceName,
+      group_name: match.name,
+      group_jid: match.jid,
+      window: { since_sast: fmtSast(sinceUnix), until_sast: fmtSast(untilUnix) },
+      pulled_at_sast: fmtSast(Math.floor(Date.now() / 1000)),
+      message_count: rows.length,
+      messages_in_window: totalInWindow,
+      truncated_older: truncated,
+      participant_counts: participants,
+      messages: rows.map(({ ts, ts_sast, sender, from_me, type, text }) => ({ ts_sast, sender, from_me, type, text })),
+    };
+
+    await fs.mkdir(OUT_DIR, { recursive: true });
+    const slug = `${slugify(instanceName, "inst")}-${slugify(match.name, match.jid.split("@")[0])}`;
+    const filePath = path.join(OUT_DIR, `${slug}.json`);
+    const overwriting = await fileExists(filePath);
+    await fs.writeFile(filePath, JSON.stringify(payload, null, 2) + "\n", "utf8");
+
+    if (opts.json) {
+      console.log(JSON.stringify(payload, null, 2));
+      return;
+    }
+
+    console.log(`${overwriting ? "Overwrote" : "Wrote"} ${filePath}`);
+    console.log(`  group:        ${match.name}  (${match.jid})`);
+    console.log(`  instance:     ${instanceName} (${inst.profileName ?? "?"})`);
+    console.log(`  window:       ${payload.window.since_sast} → ${payload.window.until_sast} SAST`);
+    console.log(`  messages:     ${rows.length}${truncated ? ` (of ${totalInWindow} in window — ${truncated} older dropped by --limit ${limit})` : ""}`);
+    console.log(`  participants: ${Object.keys(participants).length}`);
+
+    if (!rows.length) {
+      console.log("\n  (no messages in this window)");
+      return;
+    }
+
+    if (rows.length > 400) {
+      console.log(`\n  Timeline has ${rows.length} messages — full text is in the JSON file above.`);
+      return;
+    }
+    console.log("");
+    for (const m of rows) {
+      const t = fmtSast(m.ts, false);
+      console.log(`  [${t}] ${m.sender}: ${m.text ?? `(${m.type} — no readable text)`}`);
+    }
+  } finally {
+    await client.end();
+  }
+}

package/src/index.js

@@ -12,6 +12,8 @@ import * as messagesCmd from "./commands/messages.js";
 import * as fineTuningCmd from "./commands/fine-tuning.js";
 import * as messagingWebhooksCmd from "./commands/messaging-webhooks.js";
 import * as webhooksCmd from "./commands/webhooks.js";
+import * as flowmodCmd from "./commands/flowmod.js";
+import * as groupsCmd from "./commands/groups.js";
 
 // Read version from package.json so it stays in sync with the published npm
 // version automatically (single source of truth — bumping package.json on each
@@ -103,5 +105,34 @@ export function run(argv) {
     .description("WooCommerce-only: flip a webhook back to status=active (WC auto-disables after delivery failures)")
     .action((id, webhookId) => webhooksCmd.reconnect(id, webhookId));
 
+  // flowmod (FlowMod master-group prompts + config: flowmod_master_groups + flowmod_prompts)
+  const flowmod = program.command("flowmod")
+    .alias("fm")
+    .description("Round-trip a FlowMod org's master-group prompts + config (flowmod_master_groups + flowmod_prompts)");
+  flowmod.command("pull <organization_id>")
+    .description("Fetch all master_groups + their flowmod_prompts into a local JSON file")
+    .action((orgId) => flowmodCmd.pull(orgId));
+  flowmod.command("push <slug-or-path>")
+    .description("Apply a local JSON file's master_group + prompt edits (text, config, pre_filter_prompt, signatures)")
+    .action((id) => flowmodCmd.push(id));
+
+  // groups (read-only: pull WhatsApp GROUP chat history from the FlowMod Evolution DB)
+  const groups = program.command("groups")
+    .alias("grp")
+    .description("Read WhatsApp group chat history from the FlowMod Evolution DB (set FLOWMOD_EVO_DB_URL env). Read-only.");
+  groups.command("list")
+    .description("List an Evolution instance's group chats with message counts + last activity")
+    .option("--instance <name>", "Evolution instance name", "flowapt")
+    .action((opts) => groupsCmd.list(opts));
+  groups.command("pull <name-or-jid>")
+    .description("Pull a group's messages in a time window into a local JSON file + print a timeline")
+    .option("--instance <name>", "Evolution instance name", "flowapt")
+    .option("--last <window>", "rolling window back from now, e.g. 48h, 7d, 2w, 90m", "48h")
+    .option("--since <date>", "window start (SAST), YYYY-MM-DD or \"YYYY-MM-DD HH:MM\" (overrides --last)")
+    .option("--until <date>", "window end (SAST), defaults to now")
+    .option("--limit <n>", "max messages to keep (most-recent in window)", String(1000))
+    .option("--json", "print the full JSON payload to stdout instead of the timeline")
+    .action((nameOrJid, opts) => groupsCmd.pull(nameOrJid, opts));
+
   program.parseAsync(argv);
 }