@flowapt/flowiq-cli 0.1.10 → 0.1.12

package/README.md

@@ -16,12 +16,24 @@ flowiq --version   # should print 0.1.x
 
 ## Authenticate
 
-Get a personal staff API key from a FlowIQ super-admin (an `fiq_staff_…`
-string). Then:
+Default flow — browser login (like `npm login`):
 
 ```bash
 flowiq auth login
-# paste your key when prompted
+```
+
+The CLI shows a short code (e.g. `FQ4X-9KTB`), opens
+`https://app.flowiq.live/cli-auth` when you press ENTER, and waits. A
+logged-in FlowIQ **super admin** confirms the code on the page matches the
+one in your terminal and clicks Approve — the CLI then receives a
+freshly-minted personal key automatically. **Never approve a code you
+didn't just see in your own terminal.**
+
+Fallbacks (CI / no browser):
+
+```bash
+flowiq auth login --token fiq_staff_…   # supply a key directly
+flowiq auth login --paste               # prompt for a key on stdin
 ```
 
 Your key is saved to `~/.config/flowiq/auth.json` with `chmod 600`. To
@@ -31,8 +43,16 @@ verify what you're authenticated as:
 flowiq auth whoami
 ```
 
+To rotate this device's token (mints a fresh key, revokes the old one
+server-side — run whenever you want a new secret):
+
+```bash
+flowiq auth refresh
+```
+
 To log out (deletes the local key file, does NOT revoke the key
-server-side — ask your admin to revoke):
+server-side — use `flowiq auth refresh` first if you want the old key
+dead, or ask another super admin to revoke):
 
 ```bash
 flowiq auth logout
@@ -117,6 +137,28 @@ flowiq knowledge list
 - **Object-shape guard:** some agents use `additional_config` for Flowapt-managed config (`external_woo_build`, …) rather than text sources — a pull flags that, and a push is **refused** (never clobbers managed config).
 - `--agent` + filenames behave like `prompts` (a non-active agent saves to `<org-slug>-<agent-slug>.json`). The file carries `agent_id`, so `push` targets the agent it was pulled from.
 
+### Custom tools — `flowiq custom-tools pull|push|enable|disable|list` (alias `ct`)
+
+Round-trips an agent's **custom tools** — the `agents.additional_tools` array
+of "any API call → tool" definitions (the "Custom Tools" panel in the UI:
+`get_more_answers`, CRM wrappers, loyalty tools, …). These define real HTTP
+calls the agent can execute, so treat pushes with care.
+
+```bash
+flowiq custom-tools pull <org_id>               # → ./.flowiq/custom-tools/<slug>.json (tools[])
+flowiq ct pull <org_id> --agent <id>            # a specific (non-active) agent
+flowiq ct push <slug> --dry-run                 # validate + per-tool diff, writes NOTHING
+flowiq ct push <slug>                            # FULL-REPLACE tools[] onto the agent
+flowiq ct enable <org_id> <tool_name>            # flip one tool on (no round-trip)
+flowiq ct disable <org_id> <tool_name>           # flip one tool off
+flowiq ct list
+```
+
+- **Always `--dry-run` first** on a production agent — it prints added/removed/changed tool names before you commit.
+- Server-side validation is strict: tool `name` (`^[a-zA-Z0-9_-]{1,64}$`, no duplicates), non-empty `description`, `http(s)` `endpoint`, method `GET/POST/PUT/PATCH/DELETE`, object-typed `parameters`/`headers`/`injected_parameters`, valid `auth_type`/`channels`. Bad payloads are rejected before anything writes.
+- **Warnings (non-blocking):** unknown keys (likely typos the runtime would silently ignore) and unknown `{{placeholders}}` (they will NOT be substituted at runtime — known: `organization_id`, `contact_id`, `agent_id`, `contact_whatsapp_id`, `contact_full_name`, `supabase_anon_key`, `openai_api_key`, …).
+- `--agent` + filenames behave like `prompts`/`knowledge`; the file carries `agent_id`, so `push` targets the agent it was pulled from.
+
 ### Messages — `flowiq messages pull <contact_id>` (alias `m`)
 
 Read-only pull of a contact's `helpdesk_messages` history. Anchors on the

package/package.json

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

@@ -1,8 +1,23 @@
-// `flowiq auth login` / `flowiq auth logout` / `flowiq auth whoami`.
-// Stores a `fiq_staff_…` bearer token at ~/.config/flowiq/auth.json.
+// `flowiq auth login` / `logout` / `whoami` / `refresh`.
+//
+// Default login = browser device flow (like `npm login` / `gh auth login`):
+//   1. POST /cli/login-start (unauthenticated) → device_code + user_code
+//   2. Show the user code, press ENTER → open https://app.flowiq.live/cli-auth
+//   3. A logged-in SUPER ADMIN confirms the codes match and approves
+//   4. Poll /cli/login-poll until the key is minted server-side (mint-at-claim)
+//
+// Fallbacks: `--token <key>` (direct) or `--paste` (interactive paste) keep
+// the original flow for CI or when no browser is handy.
+//
+// `flowiq auth refresh` rotates the saved key in place via /cli/token-rotate —
+// run it on each device whenever you want a fresh secret; the old key is
+// revoked server-side. If the saved key is already dead it falls back to the
+// full browser login.
 
 import readline from "node:readline";
-import { loadConfig, saveConfig, clearConfig, configFilePath } from "../config.js";
+import os from "node:os";
+import { spawn } from "node:child_process";
+import { loadConfig, saveConfig, clearConfig } from "../config.js";
 import { http } from "../http.js";
 
 function prompt(question, { silent = false } = {}) {
@@ -41,25 +56,42 @@ function prompt(question, { silent = false } = {}) {
   });
 }
 
-export async function login(opts = {}) {
-  const cfg = await loadConfig();
-  if (opts.apiUrl) cfg.api_url = opts.apiUrl;
-
-  let token = opts.token;
-  if (!token) {
-    process.stdout.write(`API URL: ${cfg.api_url}\n`);
-    token = await prompt("Paste your staff API key (fiq_staff_…): ", { silent: true });
-    token = token.trim();
+// Unauthenticated POST — login-start / login-poll run BEFORE a token exists,
+// so they can't go through http.js (which requires the saved token).
+async function unauthedPost(apiUrl, endpoint, body) {
+  const url = `${apiUrl.replace(/\/$/, "")}/cli/${endpoint}`;
+  const resp = await fetch(url, {
+    method: "POST",
+    headers: { "Content-Type": "application/json", Accept: "application/json" },
+    body: JSON.stringify(body ?? {}),
+  });
+  const text = await resp.text();
+  let parsed;
+  try { parsed = text ? JSON.parse(text) : {}; } catch { parsed = { _raw: text }; }
+  if (!resp.ok) {
+    throw new Error(parsed.message || parsed.error || `${endpoint} → HTTP ${resp.status}`);
   }
+  return parsed;
+}
 
-  if (!token.startsWith("fiq_staff_")) {
-    console.error(`Error: token must start with "fiq_staff_" (got ${token.slice(0, 12)}…).`);
-    process.exit(1);
+function openBrowser(url) {
+  const platform = process.platform;
+  let cmd, args;
+  if (platform === "darwin") { cmd = "open"; args = [url]; }
+  else if (platform === "win32") { cmd = "cmd"; args = ["/c", "start", "", url]; }
+  else { cmd = "xdg-open"; args = [url]; }
+  try {
+    spawn(cmd, args, { stdio: "ignore", detached: true }).unref();
+    return true;
+  } catch {
+    return false;
   }
+}
 
-  // Save first so http.js can use it, then verify with /cli/whoami.
-  const file = await saveConfig({ api_url: cfg.api_url, token });
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
 
+async function saveAndVerify(apiUrl, token) {
+  const file = await saveConfig({ api_url: apiUrl, token });
   try {
     const me = await http.get("whoami");
     console.log(`Logged in as ${me.user_email || me.user_id} (super_admin=${me.is_super_admin})`);
@@ -73,6 +105,109 @@ export async function login(opts = {}) {
   }
 }
 
+async function browserLogin(cfg) {
+  const deviceName = `${os.hostname()} (${os.platform()})`;
+  let start;
+  try {
+    start = await unauthedPost(cfg.api_url, "login-start", { device_name: deviceName });
+  } catch (e) {
+    console.error(`Could not start browser login: ${e.message}`);
+    console.error("Fallback: flowiq auth login --paste");
+    process.exit(1);
+  }
+
+  console.log("");
+  console.log("First, confirm this code matches the one shown in your browser:");
+  console.log("");
+  console.log(`    ${start.user_code}`);
+  console.log("");
+  console.log(`Approval page: ${start.verification_url}`);
+  await prompt("Press ENTER to open in the browser... ");
+  if (!openBrowser(start.verification_url)) {
+    console.log("(Could not open a browser — visit the URL above manually.)");
+  }
+
+  const intervalMs = Math.max(2, start.interval || 5) * 1000;
+  const deadline = Date.now() + (start.expires_in || 600) * 1000;
+  process.stdout.write("Waiting for a super admin to approve");
+
+  while (Date.now() < deadline) {
+    await sleep(intervalMs);
+    let poll;
+    try {
+      poll = await unauthedPost(cfg.api_url, "login-poll", { device_code: start.device_code });
+    } catch (e) {
+      console.error(`\nPolling failed: ${e.message}`);
+      process.exit(1);
+    }
+
+    if (poll.status === "pending") { process.stdout.write("."); continue; }
+    if (poll.status === "slow_down") { await sleep(intervalMs); continue; }
+    process.stdout.write("\n");
+
+    if (poll.status === "approved") {
+      console.log(`Approved${poll.user_email ? ` by ${poll.user_email}` : ""}.`);
+      await saveAndVerify(cfg.api_url, poll.token);
+      return;
+    }
+    if (poll.status === "denied") { console.error("Login was DENIED in the browser."); process.exit(1); }
+    if (poll.status === "expired") { console.error("Login request expired. Re-run `flowiq auth login`."); process.exit(1); }
+    if (poll.status === "claimed") { console.error("This login was already claimed. Re-run `flowiq auth login`."); process.exit(1); }
+    console.error(`Unexpected status: ${poll.status}`); process.exit(1);
+  }
+
+  console.error("\nTimed out waiting for approval. Re-run `flowiq auth login`.");
+  process.exit(1);
+}
+
+export async function login(opts = {}) {
+  const cfg = await loadConfig();
+  if (opts.apiUrl) cfg.api_url = opts.apiUrl;
+
+  // Fallback paths: --token (direct) or --paste (interactive paste).
+  let token = opts.token;
+  if (!token && opts.paste) {
+    process.stdout.write(`API URL: ${cfg.api_url}\n`);
+    token = (await prompt("Paste your staff API key (fiq_staff_…): ", { silent: true })).trim();
+  }
+
+  if (token) {
+    if (!token.startsWith("fiq_staff_")) {
+      console.error(`Error: token must start with "fiq_staff_" (got ${token.slice(0, 12)}…).`);
+      process.exit(1);
+    }
+    await saveAndVerify(cfg.api_url, token);
+    return;
+  }
+
+  // Default: browser device flow.
+  await browserLogin(cfg);
+}
+
+export async function refresh() {
+  const cfg = await loadConfig();
+  if (!cfg.token) {
+    console.log("No saved token — starting browser login instead.");
+    await browserLogin(cfg);
+    return;
+  }
+
+  try {
+    const rotated = await http.post("token-rotate", {});
+    await saveConfig({ api_url: cfg.api_url, token: rotated.token });
+    console.log(`Token rotated (${rotated.rotated_from} → ${rotated.key_prefix}).`);
+    console.log(rotated.old_key_revoked ? "Old key revoked." : "WARNING: old key could not be revoked — revoke it manually.");
+  } catch (e) {
+    if (e.status === 401) {
+      console.log("Saved token is no longer valid — starting browser login…");
+      await browserLogin(cfg);
+      return;
+    }
+    console.error(`Refresh failed: ${e.message}`);
+    process.exit(1);
+  }
+}
+
 export async function logout() {
   const removed = await clearConfig();
   console.log(removed ? "Logged out." : "Already logged out.");

package/src/commands/custom-tools.js

@@ -0,0 +1,197 @@
+// `flowiq custom-tools pull <org_id> [--agent <id>]` / `push <slug> [--dry-run]`
+// / `enable|disable <org_id> <tool_name>` / `list`.
+// Round-trips an agent's CUSTOM TOOLS — the `agents.additional_tools` array of
+// "any API call → tool" definitions (get_more_answers, zoho_* wrappers, …).
+// Via /cli/custom-tools; no DB creds on disk.
+//
+// These define real HTTP calls the agent can execute, so push is validated
+// hard server-side and `--dry-run` prints the per-tool diff without writing.
+
+import fs from "node:fs/promises";
+import path from "node:path";
+import { http } from "../http.js";
+
+const CT_DIR = path.resolve(process.cwd(), ".flowiq", "custom-tools");
+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(CT_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 printWarnings(warnings) {
+  for (const w of warnings || []) console.log(`  ⚠ ${w}`);
+}
+
+function printDiff(diff) {
+  if (!diff) return;
+  const parts = [];
+  if (diff.added?.length) parts.push(`+${diff.added.length} added (${diff.added.join(", ")})`);
+  if (diff.removed?.length) parts.push(`-${diff.removed.length} removed (${diff.removed.join(", ")})`);
+  if (diff.changed?.length) parts.push(`~${diff.changed.length} changed (${diff.changed.join(", ")})`);
+  parts.push(`${diff.unchanged ?? 0} unchanged`);
+  console.log(`  diff:      ${parts.join("; ")}`);
+}
+
+export async function pull(orgId, opts = {}) {
+  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("custom-tools", { organization_id: orgId, agent_id: opts.agent });
+  } catch (e) {
+    console.error(`Pull failed: ${e.message}`);
+    process.exit(1);
+  }
+
+  await fs.mkdir(CT_DIR, { recursive: true });
+  // Non-active agents get an agent-suffixed filename (same as prompts) so
+  // pulling multiple agents from one org doesn't clobber each other.
+  const orgSlug = slugify(resp.organization_name, resp.organization_id);
+  const slug = resp.is_active === false
+    ? `${orgSlug}-${slugify(resp.agent_name, resp.agent_id.slice(0, 8))}`
+    : orgSlug;
+  const filePath = path.join(CT_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(`  agent:     ${resp.agent_name} (${resp.agent_id})${resp.is_active === false ? " [NON-active]" : ""}`);
+  console.log(`  tools:     ${resp.tool_count} (${resp.enabled_count} enabled)`);
+  for (const t of resp.tools || []) {
+    const flags = [
+      t.enabled === false ? "DISABLED" : null,
+      t.super_admin_only ? "super-admin" : null,
+      t.channels?.length ? `channels: ${t.channels.join(",")}` : null,
+    ].filter(Boolean).join(", ");
+    let host = t.endpoint;
+    try { host = new URL(t.endpoint).host; } catch { /* keep raw */ }
+    console.log(`    ${String(t.name).padEnd(32)} ${String(t.method || "?").padEnd(6)} ${host}${flags ? `  [${flags}]` : ""}`);
+  }
+}
+
+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.tools)) {
+    console.error(`${filePath}: tools must be an array of tool definitions`);
+    process.exit(1);
+  }
+
+  let resp;
+  try {
+    resp = await http.post("custom-tools", {
+      organization_id: data.organization_id,
+      agent_id: data.agent_id, // push back to the agent this file was pulled from
+      tools: data.tools,
+      dry_run: !!opts.dryRun,
+    });
+  } catch (e) {
+    console.error(`Push failed: ${e.message}`);
+    if (e.body?.error) console.error(`  ${e.body.error}`);
+    process.exit(1);
+  }
+
+  console.log(`${resp.dry_run ? "DRY RUN (nothing written) —" : "Pushed"} ${filePath}`);
+  console.log(`  org:       ${resp.organization_name} (${data.organization_id})`);
+  console.log(`  agent:     ${resp.agent_name}${resp.is_active === false ? " [NON-active]" : ""}`);
+  console.log(`  tools:     ${resp.tool_count}`);
+  printDiff(resp.diff);
+  printWarnings(resp.warnings);
+  if (resp.dry_run) console.log("  re-run without --dry-run to apply.");
+}
+
+async function toggle(orgId, toolName, enabled, opts = {}) {
+  if (!UUID_RE.test(orgId)) {
+    console.error(`Error: "${orgId}" is not a valid organization UUID.`);
+    process.exit(1);
+  }
+  let resp;
+  try {
+    resp = await http.post("custom-tools", {
+      organization_id: orgId,
+      agent_id: opts.agent,
+      toggle: { name: toolName, enabled },
+    });
+  } catch (e) {
+    console.error(`${enabled ? "Enable" : "Disable"} failed: ${e.message}`);
+    if (e.body?.error) console.error(`  ${e.body.error}`);
+    process.exit(1);
+  }
+  console.log(`${enabled ? "Enabled" : "Disabled"} "${resp.name}" on ${resp.agent_name} (${resp.organization_name})${resp.is_active === false ? " [NON-active]" : ""}`);
+}
+
+export const enable = (orgId, toolName, opts) => toggle(orgId, toolName, true, opts);
+export const disable = (orgId, toolName, opts) => toggle(orgId, toolName, false, opts);
+
+export async function list() {
+  let files;
+  try {
+    files = (await fs.readdir(CT_DIR)).filter((f) => f.endsWith(".json"));
+  } catch {
+    console.log("(no local custom-tools files; run `custom-tools pull <org_id>`)");
+    return;
+  }
+  if (!files.length) {
+    console.log("(no local custom-tools files; run `custom-tools pull <org_id>`)");
+    return;
+  }
+  files.sort();
+  for (const f of files) {
+    const fp = path.join(CT_DIR, f);
+    try {
+      const d = JSON.parse(await fs.readFile(fp, "utf8"));
+      console.log(f);
+      console.log(`  org:       ${d.organization_name ?? "(unknown)"} (${d.organization_id ?? "?"})`);
+      console.log(`  agent:     ${d.agent_name ?? "?"} (${d.agent_id ?? "?"})`);
+      console.log(`  tools:     ${d.tool_count ?? (Array.isArray(d.tools) ? d.tools.length : "?")}`);
+      console.log(`  pulled:    ${d.pulled_at ?? "(unknown)"}`);
+    } catch (e) {
+      console.log(`${f}  [invalid JSON: ${e.message}]`);
+    }
+  }
+}

package/src/index.js

@@ -23,6 +23,7 @@ import * as agentUpdatesCmd from "./commands/agent-updates.js";
 import * as exportCmd from "./commands/export.js";
 import * as testCmd from "./commands/agent-test.js";
 import * as knowledgeCmd from "./commands/knowledge.js";
+import * as customToolsCmd from "./commands/custom-tools.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
@@ -40,10 +41,14 @@ export function run(argv) {
   // auth
   const auth = program.command("auth").description("Manage CLI authentication");
   auth.command("login")
-    .description("Save a staff API key (fiq_staff_…)")
-    .option("--token <token>", "supply the token via flag instead of stdin")
+    .description("Log in via the browser (super-admin approval); --token/--paste for the old key-paste flow")
+    .option("--token <token>", "supply a staff API key directly instead of the browser flow")
+    .option("--paste", "prompt for a staff API key on stdin instead of the browser flow")
     .option("--api-url <url>", "override the API host (default https://api.flowiq.live)")
     .action((opts) => authCmd.login(opts));
+  auth.command("refresh")
+    .description("Rotate this device's token in place (old key is revoked server-side)")
+    .action(() => authCmd.refresh());
   auth.command("logout").description("Remove the saved token").action(() => authCmd.logout());
   auth.command("whoami").description("Show the user behind the saved token").action(() => authCmd.whoami());
 
@@ -306,5 +311,29 @@ export function run(argv) {
     .description("List local knowledge snapshots")
     .action(() => knowledgeCmd.list());
 
+  // custom-tools (agent custom tools: additional_tools — the "any API call → tool" defs)
+  const customTools = program.command("custom-tools")
+    .alias("ct")
+    .description("Round-trip an agent's CUSTOM TOOLS (additional_tools — the \"any API call → tool\" definitions)");
+  customTools.command("pull <organization_id>")
+    .description("Fetch the agent's custom tools into a local JSON file (default: active agent)")
+    .option("--agent <id>", "target a specific agent instead of the org's active one")
+    .action((orgId, opts) => customToolsCmd.pull(orgId, opts));
+  customTools.command("push <slug-or-path>")
+    .description("FULL-REPLACE the agent's custom tools with the local JSON's tools[] (validated server-side)")
+    .option("--dry-run", "validate + print the per-tool diff WITHOUT writing")
+    .action((id, opts) => customToolsCmd.push(id, opts));
+  customTools.command("enable <organization_id> <tool_name>")
+    .description("Enable one custom tool by name (no round-trip)")
+    .option("--agent <id>", "target a specific agent instead of the org's active one")
+    .action((orgId, name, opts) => customToolsCmd.enable(orgId, name, opts));
+  customTools.command("disable <organization_id> <tool_name>")
+    .description("Disable one custom tool by name (no round-trip)")
+    .option("--agent <id>", "target a specific agent instead of the org's active one")
+    .action((orgId, name, opts) => customToolsCmd.disable(orgId, name, opts));
+  customTools.command("list")
+    .description("List local custom-tools snapshots")
+    .action(() => customToolsCmd.list());
+
   program.parseAsync(argv);
 }