@flowapt/flowiq-cli 0.1.1 → 0.1.4

package/README.md

@@ -1,18 +1,20 @@
 # flowiq
 
-FlowIQ staff CLI. Round-trips agent prompts, questionnaires, webhooks, and
-other internal config through `https://api.flowiq.live/cli/*` so the Supabase
-service role never leaves the server.
+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.
 
 ## Install
 
 ```bash
 npm i -g @flowapt/flowiq-cli
+flowiq --version   # should print 0.1.x
 ```
 
 ## Authenticate
 
-Get a personal staff API key from your FlowIQ admin (an `fiq_staff_…`
+Get a personal staff API key from a FlowIQ super-admin (an `fiq_staff_…`
 string). Then:
 
 ```bash
@@ -36,33 +38,137 @@ flowiq auth logout
 
 ## Commands
 
-### `flowiq prompts pull <organization_id>`
+All `pull` commands write to `./.flowiq/<topic>/<slug>.json` relative to
+your current working directory. We recommend picking a dedicated folder
+for your CLI work:
 
-Fetches the active WhatsApp agent's `prompt_sections` and writes them to
-`./.flowiq/prompts/<org-slug>.json`.
+```bash
+mkdir -p ~/flowapt-cli && cd ~/flowapt-cli
+```
+
+### Prompts — `flowiq prompts pull|push <slug>`
+
+Round-trips an org's active WhatsApp agent's system prompt
+(`agents.settings.prompt_sections`).
+
+```bash
+flowiq prompts pull <organization_id>
+# edit ./.flowiq/prompts/<slug>.json — modify section titles/content
+flowiq prompts push <slug>
+```
+
+Notes:
+- `system_prompt` is regenerated server-side from `prompt_sections` on
+  push using the `## SECTION: <title>` format.
+- Sections support optional `hidden: boolean` + `channels: string[]`
+  (`web` / `whatsapp` / `messenger` / `instagram`) — validated on push.
+- For legacy agents without a sections array, pull auto-bootstraps a
+  single "Main" section from `settings.system_prompt` and returns
+  `bootstrapped: true`. The CLI prints a heads-up before push.
+
+### Questionnaires — `flowiq questionnaires pull|push <slug>` (alias `q`)
+
+Round-trips `agents.questionnaire` JSONB.
+
+```bash
+flowiq q pull <organization_id>
+# edit ./.flowiq/questionnaires/<slug>.json — fill in answers
+flowiq q push <slug>
+```
+
+If the DB column is null, pull seeds the local file from a default
+template (9 sections / 23 questions). Optional per-question `note` field
+is preserved round-trip.
+
+### Fine-tuning — `flowiq fine-tuning pull|push <slug>` (alias `ft`)
+
+Round-trips `agents.fine_tuning` (text instructions) + `agents.fine_tuning_entries`
+(structured Q&A entries).
+
+```bash
+flowiq ft pull <organization_id>
+# edit ./.flowiq/fine-tuning/<slug>.json
+flowiq ft push <slug>
+```
+
+Each entry has: `id`, `customer_question`, `correct_answer`, `agent_answer`,
+`notes`, `date` (YYYY-MM-DD), `category` (Product Info / Pricing / Warranty /
+Shipping / Returns / Promotions / Technical Support / Tone Adjustment / Other),
+`suggested_tone` (Friendly / Professional / Encouraging / Brief / Detailed),
+`status` (Pending / Resolved), `messages: []`, `media: []`.
+
+### Messages — `flowiq messages pull <contact_id>` (alias `m`)
+
+Read-only pull of a contact's `helpdesk_messages` history. Anchors on the
+Nth-most-recent `user-*` message, then grabs every row from that anchor
+onward (all sender types — bot-*, tool-call, member, human-*, broadcast,
+call-*, system, etc).
+
+```bash
+flowiq m pull <contact_id> --count 25
+# writes ./.flowiq/messages/<contact-slug>-<org-slug>.json
+```
+
+`--count` defaults to 25, max 200.
+
+### Webhooks (Shopify/WooCommerce) — `flowiq webhooks pull|push|reconnect` (alias `wh`)
+
+Round-trips the **inbound** Shopify or WooCommerce platform webhooks (the
+"Active Webhooks" panel on the Configuration page).
 
 ```bash
-flowiq prompts pull 0689d0be-ba76-43d9-a0d5-f4d59c1db537
-# → wrote .flowiq/prompts/kickz-sa-african-oils.json (18 sections, 18,747 chars)
+flowiq wh pull <organization_id>
+# auto-detects platform from the org row
+flowiq wh push <slug>            # create any topic in the JSON not currently live
+flowiq wh push <slug> --prune    # also delete any live webhook not in the JSON
+flowiq wh reconnect <slug> <webhook_id>   # WooCommerce-only: flip back to status=active
 ```
 
-### `flowiq prompts push <slug-or-path>`
+- For orgs with `feature_flags.ip_whitelist === true` (e.g. customers on
+  Wordfence), all calls are routed via python-render's static-IP proxy.
+- `--prune` is **direct-mode only** (python-render proxy has no delete
+  route) — on ip_whitelist orgs prune prints a clear "delete via store
+  admin UI" message instead.
+- Reconnect is WC-only. Shopify webhooks are always active when present.
+
+### Messaging webhooks — `flowiq messaging-webhooks pull|push` (alias `mw`)
 
-Reads the JSON file and sends the `prompt_sections` array back to the
-server, which regenerates the agent's `system_prompt`.
+Round-trips the **outbound** messaging webhooks in the `meta_webhooks`
+table (the right-hand panel on the Configuration page — these tell
+FlowIQ where to POST when a customer messaging event fires).
 
 ```bash
-flowiq prompts push kickz-sa-african-oils
-# → pushed 18 sections, system_prompt now 17,337 chars
+flowiq mw pull <organization_id>
+flowiq mw push <slug> --dry-run   # diff preview, no writes
+flowiq mw push <slug>             # FULL-REPLACE: deletes every row, then inserts the JSON
 ```
 
-## Environment variables
+Push is full-replace — if someone added a row via the UI between your
+pull and your push, it gets wiped. Pull-edit-push within one session.
+
+Validation: `platform` ∈ `{whatsapp, web}`, `type` from the per-platform
+allowed enum, valid http(s) URL, no duplicate (platform, type, url)
+tuples.
+
+## Environment variable overrides
 
 | Var | Default | Use |
 |---|---|---|
-| `FLOWIQ_API_URL` | `https://api.flowiq.live` | Override the API host (e.g. local dev). |
+| `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. |
 
+## Upgrading
+
+When a new version ships, just re-run:
+
+```bash
+npm i -g @flowapt/flowiq-cli
+flowiq --version
+```
+
+Your saved token in `~/.config/flowiq/auth.json` is preserved across
+upgrades.
+
 ## License
 
 UNLICENSED. Internal staff tool — install requires a valid `fiq_staff_…`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flowapt/flowiq-cli",
-  "version": "0.1.1",
+  "version": "0.1.4",
   "description": "Command-line tool for FlowIQ staff: round-trip agent prompts, questionnaires, webhooks, and more without ever touching service-role credentials.",
   "type": "module",
   "bin": {

package/src/commands/fine-tuning.js

@@ -0,0 +1,132 @@
+// `flowiq fine-tuning pull <organization_id>` /
+// `flowiq fine-tuning push <slug>`.
+// Round-trips the dedicated `agents.fine_tuning` + `agents.fine_tuning_entries`
+// columns through a local JSON file. No DB credentials on disk.
+
+import fs from "node:fs/promises";
+import path from "node:path";
+import { http } from "../http.js";
+
+const FT_DIR = path.resolve(process.cwd(), ".flowiq", "fine-tuning");
+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(/[^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(FT_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 countEntries(entries) {
+  if (!Array.isArray(entries)) return { total: 0, pending: 0, resolved: 0, byCategory: {} };
+  const byCategory = {};
+  let pending = 0, resolved = 0;
+  for (const e of entries) {
+    if (e?.status === "Pending") pending += 1;
+    else if (e?.status === "Resolved") resolved += 1;
+    const cat = e?.category ?? "(none)";
+    byCategory[cat] = (byCategory[cat] ?? 0) + 1;
+  }
+  return { total: entries.length, pending, resolved, byCategory };
+}
+
+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("fine-tuning", { organization_id: orgId });
+  } catch (e) {
+    console.error(`Pull failed: ${e.message}`);
+    process.exit(1);
+  }
+
+  await fs.mkdir(FT_DIR, { recursive: true });
+  const slug = slugify(resp.organization_name, resp.organization_id);
+  const filePath = path.join(FT_DIR, `${slug}.json`);
+  const overwriting = await fileExists(filePath);
+  await fs.writeFile(filePath, JSON.stringify(resp, null, 2) + "\n", "utf8");
+
+  const stats = countEntries(resp.fine_tuning_entries);
+  console.log(`${overwriting ? "Overwrote" : "Wrote"} ${filePath}`);
+  console.log(`  org:           ${resp.organization_name} (${resp.organization_id})`);
+  console.log(`  agent:         ${resp.agent_name} (${resp.agent_id})`);
+  console.log(`  instructions:  ${resp.fine_tuning.length} chars`);
+  console.log(`  entries:       ${stats.total} (${stats.pending} pending, ${stats.resolved} resolved)`);
+  if (stats.total > 0) {
+    const cats = Object.entries(stats.byCategory)
+      .sort((a, b) => b[1] - a[1])
+      .map(([k, v]) => `${k}=${v}`)
+      .join(", ");
+    console.log(`  by category:   ${cats}`);
+  }
+}
+
+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 (typeof data.fine_tuning !== "string") {
+    console.error(`${filePath}: fine_tuning must be a string (use "" if none)`);
+    process.exit(1);
+  }
+
+  let resp;
+  try {
+    resp = await http.post("fine-tuning", {
+      organization_id: data.organization_id,
+      fine_tuning: data.fine_tuning,
+      fine_tuning_entries: data.fine_tuning_entries ?? [],
+    });
+  } 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(`  agent:         ${resp.agent_name} (${resp.agent_id})`);
+  console.log(`  instructions:  ${resp.instructions_chars} chars`);
+  console.log(`  entries:       ${resp.entries.total} (${resp.entries.pending} pending, ${resp.entries.resolved} resolved)`);
+}

package/src/commands/messages.js

@@ -0,0 +1,66 @@
+// `flowiq messages pull <contact_id> [--count N]`.
+// Read-only chat fetch (no push — chat history is the system of record).
+
+import fs from "node:fs/promises";
+import path from "node:path";
+import { http } from "../http.js";
+
+const MSG_DIR = path.resolve(process.cwd(), ".flowiq", "messages");
+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(/[^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; }
+}
+
+export async function pull(contactId, opts = {}) {
+  if (!UUID_RE.test(contactId)) {
+    console.error(`Error: "${contactId}" is not a valid contact UUID.`);
+    process.exit(1);
+  }
+  const query = { contact_id: contactId };
+  if (opts.count) query.count = String(opts.count);
+
+  let resp;
+  try {
+    resp = await http.get("messages", query);
+  } catch (e) {
+    console.error(`Pull failed: ${e.message}`);
+    process.exit(1);
+  }
+
+  await fs.mkdir(MSG_DIR, { recursive: true });
+  const nameSlug = slugify(
+    resp.contact_name || resp.contact_whatsapp_id || resp.contact_id,
+    resp.contact_id
+  );
+  const orgSlug = resp.organization_name ? slugify(resp.organization_name, "") : "";
+  const slug = orgSlug ? `${nameSlug}-${orgSlug}` : nameSlug;
+  const filePath = path.join(MSG_DIR, `${slug}.json`);
+  const overwriting = await fileExists(filePath);
+  await fs.writeFile(filePath, JSON.stringify(resp, null, 2) + "\n", "utf8");
+
+  console.log(`${overwriting ? "Overwrote" : "Wrote"} ${filePath}`);
+  console.log(`  contact:        ${resp.contact_name ?? "(no name)"} (${resp.contact_id})`);
+  if (resp.contact_whatsapp_id) {
+    console.log(`  whatsapp_id:    ${resp.contact_whatsapp_id}`);
+  }
+  if (resp.organization_name) {
+    console.log(`  organization:   ${resp.organization_name} (${resp.organization_id})`);
+  }
+  console.log(`  user msgs:      ${resp.user_messages_found}/${resp.user_messages_requested} requested`);
+  console.log(`  anchor:         ${resp.anchor_created_at}`);
+  console.log(`  total rows:     ${resp.total_rows}`);
+  console.log(`  by sender:`);
+  for (const [k, v] of Object.entries(resp.sender_breakdown).sort()) {
+    console.log(`    ${k.padEnd(16)} ${v}`);
+  }
+}

package/src/commands/messaging-webhooks.js

@@ -0,0 +1,123 @@
+// `flowiq messaging-webhooks pull <organization_id>` /
+// `flowiq messaging-webhooks push <slug> [--dry-run]`.
+// Full-replace round-trip of `meta_webhooks` rows.
+
+import fs from "node:fs/promises";
+import path from "node:path";
+import { http } from "../http.js";
+
+const MW_DIR = path.resolve(process.cwd(), ".flowiq", "messaging-webhooks");
+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(/[^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(MW_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  ")}`);
+}
+
+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("messaging-webhooks", { organization_id: orgId });
+  } catch (e) {
+    console.error(`Pull failed: ${e.message}`);
+    process.exit(1);
+  }
+
+  await fs.mkdir(MW_DIR, { recursive: true });
+  const slug = slugify(resp.organization_name, resp.organization_id);
+  const filePath = path.join(MW_DIR, `${slug}.json`);
+  const overwriting = await fileExists(filePath);
+  await fs.writeFile(filePath, JSON.stringify(resp, null, 2) + "\n", "utf8");
+
+  const rows = Array.isArray(resp.messaging_webhooks) ? resp.messaging_webhooks : [];
+  console.log(`${overwriting ? "Overwrote" : "Wrote"} ${filePath}`);
+  console.log(`  org:      ${resp.organization_name} (${resp.organization_id})`);
+  console.log(`  rows:     ${rows.length}`);
+  if (rows.length && resp.by_platform) {
+    const platStr = Object.entries(resp.by_platform).map(([k, v]) => `${k}=${v}`).join(", ");
+    console.log(`  by plat:  ${platStr}`);
+  }
+}
+
+export async function push(identifier, opts = {}) {
+  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.messaging_webhooks)) {
+    console.error(`${filePath}: messaging_webhooks must be an array`);
+    process.exit(1);
+  }
+
+  let resp;
+  try {
+    resp = await http.post("messaging-webhooks", {
+      organization_id: data.organization_id,
+      messaging_webhooks: data.messaging_webhooks.map((w) => ({
+        url: w.url, type: w.type, platform: w.platform,
+      })),
+      dry_run: !!opts.dryRun,
+    });
+  } catch (e) {
+    console.error(`Push failed: ${e.message}`);
+    process.exit(1);
+  }
+
+  const isDryRun = !!opts.dryRun;
+  console.log(`${isDryRun ? "DRY RUN" : "Pushed"} ${filePath}`);
+  console.log(`  org:        ${resp.organization_name} (${resp.organization_id})`);
+  console.log(`  desired:    ${resp.diff.desired}`);
+  console.log(`  existing:   ${resp.diff.existing}`);
+  console.log(`  to insert:  ${resp.diff.to_insert}`);
+  console.log(`  to delete:  ${resp.diff.to_delete}`);
+  console.log(`  unchanged:  ${resp.diff.unchanged}`);
+  if (isDryRun) {
+    console.log("\nDry-run only — no changes written. Re-run without --dry-run to apply.");
+  } else {
+    console.log(`\n✓ Replaced ${resp.replaced} → ${resp.now} row(s)`);
+  }
+}

package/src/commands/prompts.js

@@ -65,6 +65,14 @@ export async function pull(orgId) {
   console.log(`  agent:     ${resp.agent_name} (${resp.agent_id})`);
   console.log(`  sections:  ${resp.prompt_sections.length}`);
   console.log(`  content:   ${totalChars.toLocaleString()} chars`);
+  if (resp.bootstrapped) {
+    console.log("");
+    console.log("  ⚠ this agent had no prompt_sections — seeded a single \"Main\"");
+    console.log("    section from settings.system_prompt. on push, system_prompt");
+    console.log("    will be regenerated with a \"## SECTION: Main\" header wrap.");
+    console.log("    split the JSON into proper sections before push if you want");
+    console.log("    different headers.");
+  }
 }
 
 export async function push(identifier) {

package/src/commands/webhooks.js

@@ -0,0 +1,186 @@
+// `flowiq webhooks pull <organization_id>` /
+// `flowiq webhooks push <slug> [--prune]` /
+// `flowiq webhooks reconnect <slug> <webhook_id>`.
+// Round-trips Shopify/WooCommerce platform webhooks via /cli/webhooks.
+
+import fs from "node:fs/promises";
+import path from "node:path";
+import { http } from "../http.js";
+
+const WH_DIR = path.resolve(process.cwd(), ".flowiq", "webhooks");
+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(/[^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(WH_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  ")}`);
+}
+
+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("webhooks", { organization_id: orgId });
+  } catch (e) {
+    console.error(`Pull failed: ${e.message}`);
+    process.exit(1);
+  }
+
+  await fs.mkdir(WH_DIR, { recursive: true });
+  const slug = slugify(resp.organization_name, resp.organization_id);
+  const filePath = path.join(WH_DIR, `${slug}.json`);
+  const overwriting = await fileExists(filePath);
+  await fs.writeFile(filePath, JSON.stringify(resp, null, 2) + "\n", "utf8");
+
+  console.log(`${overwriting ? "Overwrote" : "Wrote"} ${filePath}`);
+  console.log(`  org:          ${resp.organization_name} (${resp.organization_id})`);
+  console.log(`  platform:     ${resp.platform}${resp.ip_whitelist ? " (via python-render)" : ""}`);
+  console.log(`  webhooks:     ${resp.webhooks.length} live`);
+  if (resp.webhooks.length && resp.by_status) {
+    const s = Object.entries(resp.by_status).map(([k, v]) => `${k}=${v}`).join(", ");
+    console.log(`  by status:    ${s}`);
+  }
+}
+
+export async function push(identifier, opts = {}) {
+  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 (!["shopify", "woocommerce"].includes(data.platform)) {
+    console.error(`${filePath}: platform must be 'shopify' or 'woocommerce'`);
+    process.exit(1);
+  }
+  if (!Array.isArray(data.webhooks)) {
+    console.error(`${filePath}: webhooks must be an array`);
+    process.exit(1);
+  }
+
+  let resp;
+  try {
+    resp = await http.post("webhooks", {
+      action: "push",
+      organization_id: data.organization_id,
+      platform: data.platform,
+      webhooks: data.webhooks.map((w) => ({ topic: w.topic })),
+      prune: !!opts.prune,
+    });
+  } 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(`  platform:  ${resp.platform}${resp.ip_whitelist ? " (via python-render)" : ""}`);
+  const cr = resp.create_results || {};
+  const dr = resp.prune_results || {};
+  console.log(`  to create: ${resp.diff.to_create.length}${resp.diff.to_create.length ? " → " + resp.diff.to_create.join(", ") : ""}`);
+  console.log(`  to delete: ${resp.diff.to_delete.length}${resp.diff.to_delete.length && !opts.prune ? " (pass --prune to delete)" : ""}`);
+  if (cr.created !== undefined && resp.diff.to_create.length) {
+    console.log(`  ✓ created ${cr.created}/${resp.diff.to_create.length}`);
+  }
+  if (cr.failures?.length) {
+    console.log(`  ⚠ ${cr.failures.length} create failure(s):`);
+    for (const f of cr.failures) console.log(`    - ${f.topic}: ${f.error}`);
+  }
+  if (opts.prune && resp.diff.to_delete.length) {
+    if (dr.skipped_reason) {
+      console.log(`  ⚠ prune skipped: ${dr.skipped_reason}`);
+    } else {
+      console.log(`  ✓ deleted ${dr.deleted}/${resp.diff.to_delete.length}`);
+      if (dr.failures?.length) {
+        console.log(`  ⚠ ${dr.failures.length} delete failure(s):`);
+        for (const f of dr.failures) console.log(`    - ${f.topic}: ${f.error}`);
+      }
+    }
+  }
+  console.log(`Done. created=${cr.created || 0}, deleted=${dr.deleted || 0}, untouched=${resp.diff.untouched}`);
+}
+
+export async function reconnect(identifier, webhookIdRaw) {
+  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.platform !== "woocommerce") {
+    console.error("Reconnect is WooCommerce-only. Shopify webhooks are always active when present.");
+    process.exit(1);
+  }
+  const webhookId = Number(webhookIdRaw);
+  if (!Number.isFinite(webhookId) || webhookId <= 0) {
+    console.error(`Invalid webhook id "${webhookIdRaw}" (must be a positive number).`);
+    process.exit(1);
+  }
+
+  let resp;
+  try {
+    resp = await http.post("webhooks", {
+      action: "reconnect",
+      organization_id: data.organization_id,
+      platform: "woocommerce",
+      webhook_id: webhookId,
+    });
+  } catch (e) {
+    console.error(`Reconnect failed: ${e.message}`);
+    process.exit(1);
+  }
+
+  console.log(
+    `Reconnecting WooCommerce webhook id=${webhookId} for ` +
+    `${resp.organization_name}${resp.ip_whitelist ? " (via python-render)" : ""}`
+  );
+  console.log(`  ✓ ${resp.topic || "(unknown topic)"} → status=${resp.status}`);
+}

package/src/index.js

@@ -5,6 +5,10 @@ import { Command } from "commander";
 import * as authCmd from "./commands/auth.js";
 import * as promptsCmd from "./commands/prompts.js";
 import * as questionnairesCmd from "./commands/questionnaires.js";
+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";
 
 export function run(argv) {
   const program = new Command();
@@ -43,5 +47,52 @@ export function run(argv) {
     .description("Apply a local JSON file's questionnaire to the agent")
     .action((id) => questionnairesCmd.push(id));
 
+  // messages (read-only: pull a contact's helpdesk_messages history)
+  const msgs = program.command("messages")
+    .alias("m")
+    .description("Pull a contact's helpdesk_messages history (read-only)");
+  msgs.command("pull <contact_id>")
+    .description("Pull last N user-message windows of conversation for a contact (default N=25, max 200)")
+    .option("--count <n>", "number of most-recent user-* messages to anchor on", "25")
+    .action((contactId, opts) => messagesCmd.pull(contactId, opts));
+
+  // fine-tuning (agents.fine_tuning text + agents.fine_tuning_entries jsonb)
+  const ft = program.command("fine-tuning")
+    .alias("ft")
+    .description("Round-trip the active agent's fine-tuning instructions + Q&A entries");
+  ft.command("pull <organization_id>")
+    .description("Fetch agents.fine_tuning + agents.fine_tuning_entries into a local JSON file")
+    .action((orgId) => fineTuningCmd.pull(orgId));
+  ft.command("push <slug-or-path>")
+    .description("Apply a local JSON file's fine_tuning + fine_tuning_entries to the agent")
+    .action((id) => fineTuningCmd.push(id));
+
+  // messaging-webhooks (outbound notifications via meta_webhooks table)
+  const mw = program.command("messaging-webhooks")
+    .alias("mw")
+    .description("Round-trip outbound messaging webhooks (meta_webhooks table)");
+  mw.command("pull <organization_id>")
+    .description("Pull all meta_webhooks rows for the org into a local JSON file")
+    .action((orgId) => messagingWebhooksCmd.pull(orgId));
+  mw.command("push <slug-or-path>")
+    .description("FULL-REPLACE: deletes every existing row for the org then inserts the JSON. Pass --dry-run for diff preview.")
+    .option("--dry-run", "preview the diff without writing anything")
+    .action((id, opts) => messagingWebhooksCmd.push(id, opts));
+
+  // webhooks (Shopify/WooCommerce platform webhooks; auto-detects platform + ip_whitelist proxy)
+  const wh = program.command("webhooks")
+    .alias("wh")
+    .description("Round-trip Shopify or WooCommerce platform webhooks (auto-detects platform; routes via python-render when feature_flags.ip_whitelist is on)");
+  wh.command("pull <organization_id>")
+    .description("Fetch the FlowIQ-pointing webhooks live from Shopify/WC into a local JSON file")
+    .action((orgId) => webhooksCmd.pull(orgId));
+  wh.command("push <slug-or-path>")
+    .description("Create any topic in the JSON not currently live on the store. With --prune, also DELETES any live webhook not in the JSON.")
+    .option("--prune", "also delete live webhooks that aren't in the JSON (direct-mode only; python-render proxy has no delete route)")
+    .action((id, opts) => webhooksCmd.push(id, opts));
+  wh.command("reconnect <slug-or-path> <webhook_id>")
+    .description("WooCommerce-only: flip a webhook back to status=active (WC auto-disables after delivery failures)")
+    .action((id, webhookId) => webhooksCmd.reconnect(id, webhookId));
+
   program.parseAsync(argv);
 }