@flowapt/flowiq-cli 0.1.0

package/README.md

@@ -0,0 +1,69 @@
+# 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.
+
+## Install
+
+```bash
+npm i -g @flowapt/flowiq-cli
+```
+
+## Authenticate
+
+Get a personal staff API key from your FlowIQ admin (an `fiq_staff_…`
+string). Then:
+
+```bash
+flowiq auth login
+# paste your key when prompted
+```
+
+Your key is saved to `~/.config/flowiq/auth.json` with `chmod 600`. To
+verify what you're authenticated as:
+
+```bash
+flowiq auth whoami
+```
+
+To log out (deletes the local key file, does NOT revoke the key
+server-side — ask your admin to revoke):
+
+```bash
+flowiq auth logout
+```
+
+## Commands
+
+### `flowiq prompts pull <organization_id>`
+
+Fetches the active WhatsApp agent's `prompt_sections` and writes them to
+`./.flowiq/prompts/<org-slug>.json`.
+
+```bash
+flowiq prompts pull 0689d0be-ba76-43d9-a0d5-f4d59c1db537
+# → wrote .flowiq/prompts/kickz-sa-african-oils.json (18 sections, 18,747 chars)
+```
+
+### `flowiq prompts push <slug-or-path>`
+
+Reads the JSON file and sends the `prompt_sections` array back to the
+server, which regenerates the agent's `system_prompt`.
+
+```bash
+flowiq prompts push kickz-sa-african-oils
+# → pushed 18 sections, system_prompt now 17,337 chars
+```
+
+## Environment variables
+
+| Var | Default | Use |
+|---|---|---|
+| `FLOWIQ_API_URL` | `https://api.flowiq.live` | Override the API host (e.g. local dev). |
+| `FLOWIQ_TOKEN` | (saved in `~/.config/flowiq/auth.json`) | Override the auth token, useful for CI. |
+
+## License
+
+UNLICENSED. Internal staff tool — install requires a valid `fiq_staff_…`
+key issued by a FlowIQ super-admin.

package/bin/flowiq.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+// Entry point — node shebang. Symlinked into PATH by `npm i -g`.
+import { run } from "../src/index.js";
+run(process.argv);

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@flowapt/flowiq-cli",
+  "version": "0.1.0",
+  "description": "Command-line tool for FlowIQ staff: round-trip agent prompts, questionnaires, webhooks, and more without ever touching service-role credentials.",
+  "type": "module",
+  "bin": {
+    "flowiq": "bin/flowiq.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "start": "node bin/flowiq.js"
+  },
+  "dependencies": {
+    "commander": "^12.1.0"
+  },
+  "homepage": "https://github.com/MattFlowapt/flow-v1/tree/main/cli",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MattFlowapt/flow-v1.git",
+    "directory": "cli"
+  },
+  "bugs": {
+    "url": "https://github.com/MattFlowapt/flow-v1/issues"
+  },
+  "keywords": [
+    "flowapt",
+    "flowiq",
+    "cli",
+    "whatsapp",
+    "internal-tool"
+  ],
+  "license": "UNLICENSED",
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/commands/auth.js

@@ -0,0 +1,89 @@
+// `flowiq auth login` / `flowiq auth logout` / `flowiq auth whoami`.
+// Stores a `fiq_staff_…` bearer token at ~/.config/flowiq/auth.json.
+
+import readline from "node:readline";
+import { loadConfig, saveConfig, clearConfig, configFilePath } from "../config.js";
+import { http } from "../http.js";
+
+function prompt(question, { silent = false } = {}) {
+  return new Promise((resolve) => {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    if (silent) {
+      // Best-effort masking: turn off terminal echo for the duration of the read.
+      const stdin = process.stdin;
+      const wasRaw = stdin.isRaw;
+      stdin.setRawMode?.(true);
+      let buf = "";
+      stdin.resume();
+      stdin.setEncoding("utf8");
+      process.stdout.write(question);
+      const onData = (ch) => {
+        if (ch === "\r" || ch === "\n" || ch === "") {
+          stdin.setRawMode?.(wasRaw);
+          stdin.removeListener("data", onData);
+          process.stdout.write("\n");
+          rl.close();
+          resolve(buf);
+        } else if (ch === "") {
+          process.stdout.write("\n");
+          process.exit(130);
+        } else if (ch === "" || ch === "\b") {
+          if (buf.length) { buf = buf.slice(0, -1); process.stdout.write("\b \b"); }
+        } else {
+          buf += ch;
+          process.stdout.write("*");
+        }
+      };
+      stdin.on("data", onData);
+    } else {
+      rl.question(question, (answer) => { rl.close(); resolve(answer); });
+    }
+  });
+}
+
+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();
+  }
+
+  if (!token.startsWith("fiq_staff_")) {
+    console.error(`Error: token must start with "fiq_staff_" (got ${token.slice(0, 12)}…).`);
+    process.exit(1);
+  }
+
+  // Save first so http.js can use it, then verify with /cli/whoami.
+  const file = await saveConfig({ api_url: cfg.api_url, 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})`);
+    console.log(`Token saved to ${file}`);
+  } catch (e) {
+    // Roll back the save if verification failed — leaving a bad token on disk
+    // is worse than no token at all.
+    await clearConfig();
+    console.error(`Login failed: ${e.message}`);
+    process.exit(1);
+  }
+}
+
+export async function logout() {
+  const removed = await clearConfig();
+  console.log(removed ? "Logged out." : "Already logged out.");
+}
+
+export async function whoami() {
+  try {
+    const me = await http.get("whoami");
+    console.log(JSON.stringify(me, null, 2));
+  } catch (e) {
+    console.error(`whoami failed: ${e.message}`);
+    process.exit(e.code === "ENOAUTH" ? 0 : 1);
+  }
+}

package/src/commands/prompts.js

@@ -0,0 +1,112 @@
+// `flowiq prompts pull <organization_id>` / `flowiq prompts push <slug>`.
+// Round-trips an org's active WhatsApp agent's prompt_sections through a
+// local JSON file. No DB credentials on disk — all work happens server-side
+// via /cli/prompts on api.flowiq.live.
+
+import fs from "node:fs/promises";
+import path from "node:path";
+import { http } from "../http.js";
+
+const PROMPTS_DIR = path.resolve(process.cwd(), ".flowiq", "prompts");
+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(PROMPTS_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("prompts", { organization_id: orgId });
+  } catch (e) {
+    console.error(`Pull failed: ${e.message}`);
+    process.exit(1);
+  }
+
+  await fs.mkdir(PROMPTS_DIR, { recursive: true });
+  const slug = slugify(resp.organization_name, resp.organization_id);
+  const filePath = path.join(PROMPTS_DIR, `${slug}.json`);
+  const overwriting = await fileExists(filePath);
+  await fs.writeFile(filePath, JSON.stringify(resp, null, 2) + "\n", "utf8");
+
+  const totalChars = resp.prompt_sections.reduce((a, s) => a + (s.content?.length || 0), 0);
+  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(`  sections:  ${resp.prompt_sections.length}`);
+  console.log(`  content:   ${totalChars.toLocaleString()} chars`);
+}
+
+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.prompt_sections) || data.prompt_sections.length === 0) {
+    console.error(`${filePath}: prompt_sections must be a non-empty array`);
+    process.exit(1);
+  }
+
+  let resp;
+  try {
+    resp = await http.post("prompts", {
+      organization_id: data.organization_id,
+      prompt_sections: data.prompt_sections,
+    });
+  } 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(`  sections:   ${resp.sections}`);
+  console.log(`  content:    ${resp.total_chars.toLocaleString()} chars`);
+  console.log(`  prompt now: ${resp.system_prompt_chars.toLocaleString()} chars`);
+}

package/src/config.js

@@ -0,0 +1,70 @@
+// Token + base-URL config for the flowiq CLI.
+//
+// Storage: ~/.config/flowiq/auth.json, chmod 600 (mode 0600). One file holds:
+//   { api_url: "https://api.flowiq.live", token: "fiq_staff_..." }
+//
+// Env-var overrides (handy for CI or local dev):
+//   FLOWIQ_API_URL   → base URL (default https://api.flowiq.live)
+//   FLOWIQ_TOKEN     → bearer token (takes precedence over the saved file)
+
+import fs from "node:fs/promises";
+import path from "node:path";
+import os from "node:os";
+
+const DEFAULT_API_URL = "https://api.flowiq.live";
+
+function configDir() {
+  // Honour XDG_CONFIG_HOME if set; else ~/.config (Linux/Mac default).
+  const xdg = process.env.XDG_CONFIG_HOME;
+  const base = xdg && xdg.trim() ? xdg : path.join(os.homedir(), ".config");
+  return path.join(base, "flowiq");
+}
+
+function configFile() {
+  return path.join(configDir(), "auth.json");
+}
+
+async function readFile() {
+  try {
+    const raw = await fs.readFile(configFile(), "utf8");
+    return JSON.parse(raw);
+  } catch (e) {
+    if (e.code === "ENOENT") return null;
+    throw e;
+  }
+}
+
+export async function loadConfig() {
+  const saved = (await readFile()) || {};
+  const envToken = process.env.FLOWIQ_TOKEN?.trim();
+  const envApi = process.env.FLOWIQ_API_URL?.trim();
+  return {
+    api_url: envApi || saved.api_url || DEFAULT_API_URL,
+    token: envToken || saved.token || null,
+  };
+}
+
+export async function saveConfig({ api_url, token }) {
+  const dir = configDir();
+  await fs.mkdir(dir, { recursive: true, mode: 0o700 });
+  const file = configFile();
+  const payload = JSON.stringify({ api_url, token }, null, 2) + "\n";
+  await fs.writeFile(file, payload, { encoding: "utf8", mode: 0o600 });
+  // Defensive chmod for hosts where the open() mode was honoured loosely.
+  try { await fs.chmod(file, 0o600); } catch { /* best-effort */ }
+  return file;
+}
+
+export async function clearConfig() {
+  try {
+    await fs.unlink(configFile());
+    return true;
+  } catch (e) {
+    if (e.code === "ENOENT") return false;
+    throw e;
+  }
+}
+
+export function configFilePath() {
+  return configFile();
+}

package/src/http.js

@@ -0,0 +1,57 @@
+// Tiny fetch wrapper for the flowiq CLI. All requests:
+//   - go to ${config.api_url}/cli/<endpoint>
+//   - carry Authorization: Bearer <token>
+//   - parse JSON, surfacing { error, message } shape with a readable error.
+
+import { loadConfig } from "./config.js";
+
+async function call(method, endpoint, { query, body } = {}) {
+  const cfg = await loadConfig();
+  if (!cfg.token) {
+    const err = new Error(
+      "Not authenticated. Run `flowiq auth login` and paste your staff API key."
+    );
+    err.code = "ENOAUTH";
+    throw err;
+  }
+
+  const qs = query
+    ? "?" + new URLSearchParams(
+        Object.fromEntries(Object.entries(query).filter(([, v]) => v != null))
+      ).toString()
+    : "";
+  const url = `${cfg.api_url.replace(/\/$/, "")}/cli/${endpoint}${qs}`;
+
+  const init = {
+    method,
+    headers: {
+      Authorization: `Bearer ${cfg.token}`,
+      Accept: "application/json",
+    },
+  };
+  if (body !== undefined) {
+    init.headers["Content-Type"] = "application/json";
+    init.body = JSON.stringify(body);
+  }
+
+  const resp = await fetch(url, init);
+  const text = await resp.text();
+  let parsed;
+  try { parsed = text ? JSON.parse(text) : {}; } catch { parsed = { _raw: text }; }
+  if (!resp.ok) {
+    const err = new Error(
+      parsed.message || parsed.error || `${method} ${endpoint} → HTTP ${resp.status}`
+    );
+    err.status = resp.status;
+    err.body = parsed;
+    throw err;
+  }
+  return parsed;
+}
+
+export const http = {
+  get: (endpoint, query) => call("GET", endpoint, { query }),
+  post: (endpoint, body) => call("POST", endpoint, { body }),
+  put: (endpoint, body) => call("PUT", endpoint, { body }),
+  del: (endpoint, body) => call("DELETE", endpoint, { body }),
+};

package/src/index.js

@@ -0,0 +1,35 @@
+// flowiq — staff CLI entry point.
+// commander dispatches to src/commands/* based on argv.
+
+import { Command } from "commander";
+import * as authCmd from "./commands/auth.js";
+import * as promptsCmd from "./commands/prompts.js";
+
+export function run(argv) {
+  const program = new Command();
+  program
+    .name("flowiq")
+    .description("FlowIQ staff CLI — round-trip agent prompts, webhooks, and more, without service-role credentials.")
+    .version("0.1.0");
+
+  // 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")
+    .option("--api-url <url>", "override the API host (default https://api.flowiq.live)")
+    .action((opts) => authCmd.login(opts));
+  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());
+
+  // prompts
+  const prompts = program.command("prompts").description("Round-trip an org's active WhatsApp agent system prompt");
+  prompts.command("pull <organization_id>")
+    .description("Fetch the active agent's prompt_sections into a local JSON file")
+    .action((orgId) => promptsCmd.pull(orgId));
+  prompts.command("push <slug-or-path>")
+    .description("Apply a local JSON file's prompt_sections to the agent (regenerates system_prompt server-side)")
+    .action((id) => promptsCmd.push(id));
+
+  program.parseAsync(argv);
+}