@flowapt/flowiq-cli 0.1.11 → 0.2.1

package/README.md

@@ -137,6 +137,113 @@ 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.
+
+### Broadcast — `flowiq broadcast map|preview|send|resume|list` (alias `bc`)
+
+Send an **APPROVED** WhatsApp template to every row of a CSV, filling the
+template's variables **per row** from the CSV's own columns. The
+highest-stakes command in the CLI — built as a map → preview → commit
+pipeline with several layers of deliberate friction.
+
+```bash
+# 1) Build the column→param mapping interactively (saved per campaign, no send)
+flowiq bc map <org_id> --template rewards_referral_v1 --csv ./people.csv --campaign july-referrals
+
+# 2) Dry-run: validation + exact rendered messages for sample rows (default)
+flowiq bc send <org_id> --template rewards_referral_v1 --csv ./people.csv --campaign july-referrals
+
+# 3) Commit: upsert contacts, then send per row @ ≤8/s
+flowiq bc send <org_id> --template … --csv … --campaign july-referrals --commit
+#   → prompts: type the campaign name to confirm
+
+# 4) Interrupted? Continue only unsent rows:
+flowiq bc resume <org_id> --campaign july-referrals --commit [--retry-failed]
+```
+
+- **Per-row values**: each template slot maps to a CSV **column**, a
+  **literal**, or a **concat transform** (e.g. `Country Code` + `Phone`,
+  leading-zero handled). The mapper auto-suggests from the template's
+  semantic labels + body text and you confirm each slot once; the mapping is
+  saved to `.flowiq/campaigns/<campaign>.json` and reused.
+- **v1 scope**: Meta orgs, POSITIONAL templates, text/no header. NAMED,
+  carousel, media-header templates and WATI orgs are refused with a clear
+  message.
+- **Validation before anything sends**: APPROVED-only, every slot mapped,
+  contiguous params (the Meta `#132000` guard — a stray key is structurally
+  impossible), phone validity, illegal characters (Meta `#100`; `reject` by
+  default), duplicates, and **live broadcast-safety** — opted-out / archived /
+  blocked contacts are skipped, always.
+- **Dry-run is the default**; `--commit` + typing the campaign name is the
+  only way to send (`--yes` for CI skips the typing, never the dry-run).
+- **Write-ahead status log** (`.flowiq/campaigns/<campaign>.status.jsonl`):
+  every row logs `sending` *before* the POST and `sent`/`failed` after. A
+  crash mid-row leaves an *ambiguous* row that is **never auto-resent** —
+  it's surfaced for manual review. `resume` sends only never-attempted rows
+  (`--retry-failed` adds confirmed failures).
+- **Error handling**: `#132000` aborts the run (config bug — every row would
+  fail); rate errors back off exponentially and halve the send rate; a Meta
+  daily-cap soft-stops cleanly with a resume hint.
+- Contacts are **pre-upserted** (`/cli/contacts-upsert`, ≤4000/batch, retries
+  then aborts) so the send payload never needs a `name` key — the classic
+  `#132000` footgun.
+
+**Tag mode** — send to everyone carrying a tag (e.g. a `segments` batch tag)
+instead of a CSV. Same guards, same status log, same resume:
+
+```bash
+flowiq bc send <org_id> --tag july-promo-batch-01 --template fresh_drop_v1 \
+  --body param1="Hi {{first_name}}" [--button param1=<short-code>] --commit
+```
+
+Values are shared across the tag (use `{{first_name}}` etc. for per-contact
+personalization — resolved server-side). Opted-out / archived / blocked
+contacts under the tag are excluded automatically. Tags with >2000 contacts
+are refused — slice them with `flowiq segments` first.
+
+### Segments — `flowiq segments plan|apply|list|untag` (alias `seg`)
+
+Slice a big contact cohort into fixed-size **batch tags** (default 75) so
+sends respect Meta tier limits and stay controllable — the batch tag is your
+throttle *and* your brake. Tags only; the send is `broadcast send --tag` (one
+batch at a time) or the dashboard broadcaster.
+
+```bash
+flowiq seg plan <org_id> --tag-prefix july-promo --ids-file ./cohort.txt   # or --from-segment snapshot.json
+# → exclusions (opt-out/archived/blocked) applied BEFORE slicing → .flowiq/segments/<slug>.json
+flowiq seg apply <org_id> july-promo            # DRY-RUN
+flowiq seg apply <org_id> july-promo --commit   # append the tags (idempotent — re-runs report already_had)
+flowiq seg list  <org_id> --prefix july-promo   # VERIFY: tag → count
+flowiq seg untag <org_id> july-promo --commit --confirm   # ROLLBACK (its own tags only)
+```
+
+- The cohort comes in as **contact UUIDs** (a snapshot JSON's `contact_ids[]`
+  or a plain file); defining the cohort with SQL stays upstream.
+- Apply is **append-only** — it never touches a contact's other tags, names,
+  or anything else, and never double-adds.
+- Point-in-time warning: the plan tags snapshot ids; re-derive the cohort SQL
+  if freshness matters (someone who ordered since won't auto-drop).
+
 ### Messages — `flowiq messages pull <contact_id>` (alias `m`)
 
 Read-only pull of a contact's `helpdesk_messages` history. Anchors on the
@@ -343,19 +450,30 @@ the tool-flag columns (`woo_order_build`, `woo_tip_field`, `woo_order_note_field
 `shopify_products_web_chat`), and `discount.enabled`. Anything else is rejected;
 every change is reported before → after.
 
-### Agent updates — `flowiq agent-updates pull|list` (alias `au`)
+### Agent updates — `flowiq agent-updates pull|list|resolve` (alias `au`)
 
-Read-only pull of an org's client-raised "change the agent" requests
-(`agent_updates`), each with the chat context around the triggering message +
-the linked contact. Attachments are downloaded locally.
+Pull an org's client-raised "change the agent" requests (`agent_updates`),
+each with the chat context around the triggering message + the linked contact
+(attachments downloaded locally) — then, once the fix is verified, resolve the
+ticket from the same terminal.
 
 ```bash
 flowiq au pull <organization_id>                       # pending, with context
 flowiq au pull <organization_id> --status all --titles "EFT, bank"
 flowiq au pull <organization_id> --before 20 --after 10 --no-files
 # → ./.flowiq/agent-updates/<slug>.json + files/<update-id>/<attachment>
+
+flowiq au resolve <update_id> --note "We updated the agent so it no longer …"
+flowiq au resolve <update_id> --status declined --internal "duplicate of …"
 ```
 
+- **`--note` is what the client reads** (rendered as `FlowIQ: <note>` in their
+  console) and is **required** when resolving; `--internal` is staff-only.
+- The typical flow is `prompts push → flowiq test → au resolve` — resolve is
+  the LAST step, after a live test proves the fix. Don't resolve on hope.
+- An interactive confirm shows exactly what the client will read; `--yes`
+  skips the confirm (but never the `--note` requirement).
+
 ### Chat export — `flowiq export chats <organization_id> [--out <path>]`
 
 Full chat history → TXT, byte-identical to the in-app "Export Settings TXT"

package/TEAM-GUIDE.md

@@ -0,0 +1,134 @@
+# FlowIQ CLI — Team Guide
+
+The `flowiq` CLI is how Flowapt staff work on client agents and org data from
+the terminal: prompts, questionnaires, fine-tuning, knowledge sources, custom
+tools, webhooks, templates, chat reads, live agent testing, and more — all
+**without a database credential ever touching your laptop**. Every command goes
+to `api.flowiq.live` with your personal staff key, is validated server-side,
+and is logged under your name.
+
+This guide is the "how we work" version. The full command reference with every
+flag is [README.md](./README.md).
+
+---
+
+## Get set up (2 minutes)
+
+```bash
+npm i -g @flowapt/flowiq-cli
+flowiq auth login
+```
+
+`auth login` works like `npm login`:
+
+1. Your terminal shows a short code, e.g. `FQ4X-9KTB`.
+2. Press ENTER — your browser opens `app.flowiq.live/cli-auth`.
+3. A logged-in **super admin** (you, if you are one) checks the code on the
+   page matches the one in your terminal and clicks **Approve**.
+4. Back in the terminal: you're logged in. A personal key was minted for this
+   device — you never see it, never paste it.
+
+Confirm with:
+
+```bash
+flowiq auth whoami
+```
+
+> **Approving someone else's login:** when a teammate runs `auth login`, they
+> read you their code (or you open the link they send). On `/cli-auth`, check
+> the code AND the device name match what they told you, then Approve.
+> **Never approve a code you can't verify came from a teammate's terminal
+> right now** — that's the one way this flow can be abused.
+
+## The golden rules
+
+1. **Pull before you edit.** Local files under `./.flowiq/` are working
+   copies, not the source of truth. Someone may have edited in the UI since
+   your last pull — always re-pull first.
+2. **`--dry-run` before any push to a production agent** (where the command
+   supports it: `custom-tools`, `messaging-webhooks`). It shows exactly what
+   would change before anything writes.
+3. **Pushes are full-replace.** What's in your file becomes the whole surface
+   (all prompt sections, all tools, all webhooks). Deleting an entry from the
+   file deletes it from the platform.
+4. **`--agent <id>` targets a specific agent**; without it you get the org's
+   *active* agent. Files remember which agent they came from, so a push always
+   goes back to the agent you pulled — never "whatever is active now".
+5. Run the CLI from the repo root when you can — `./.flowiq/` is gitignored
+   there.
+
+## Everyday tasks
+
+| I want to… | Run |
+|---|---|
+| Edit a client agent's system prompt | `flowiq prompts pull <org_id>` → edit the JSON → `flowiq prompts push <slug>` |
+| Edit the questionnaire answers | `flowiq q pull <org_id>` → edit → `flowiq q push <slug>` |
+| Edit fine-tuning instructions / Q&A | `flowiq ft pull <org_id>` → edit → `flowiq ft push <slug>` |
+| Edit the text knowledge sources (get_more_answers playbooks) | `flowiq kn pull <org_id>` → edit `sources[]` → `flowiq kn push <slug>` |
+| Edit the custom tools (API-call tools) | `flowiq ct pull <org_id>` → edit `tools[]` → `flowiq ct push <slug> --dry-run` → `flowiq ct push <slug>` |
+| Turn one custom tool on/off | `flowiq ct enable\|disable <org_id> <tool_name>` |
+| See an org's agents / create one | `flowiq agent list <org_id>` / `flowiq agent create <org_id> --name "…"` |
+| Change agent model / tool flags | `flowiq agent config <org_id> --model … --tool view_cart_tool=true` |
+| Talk to the live agent safely (no real WhatsApp ever sent) | `flowiq test send <org_id> "hi, do you sell X?"` |
+| Send a template broadcast to a CSV of people | `flowiq bc map <org_id> --template … --csv …` → `flowiq bc send … ` (dry-run) → `… --commit` |
+| Split a big cohort into send-safe batch tags | `flowiq seg plan <org_id> --tag-prefix … --ids-file …` → `flowiq seg apply … --commit` |
+| Send to one batch tag | `flowiq bc send <org_id> --tag <batch-tag> --template … --body param1="Hi {{first_name}}" --commit` |
+| Read a contact's chat | `flowiq m pull <contact_id>` then open the JSON |
+| Export an org's full chat history | `flowiq export chats <org_id>` |
+| Check / create WhatsApp templates | `flowiq tpl pull <org_id>` / `flowiq tpl create <org_id> --request-file req.json` |
+| Manage Shopify/Woo platform webhooks | `flowiq wh pull <org_id>` → edit → `flowiq wh push <slug>` |
+| Manage outbound messaging webhooks | `flowiq mw pull <org_id>` → `flowiq mw push <slug> --dry-run` → push |
+| See a client's pending change requests | `flowiq au pull <org_id>` |
+| Close a client's change request (after verifying the fix!) | `flowiq au resolve <update_id> --note "what changed"` — the client reads the note |
+| Check an org's platform + active agent | `flowiq org info <org_id>` |
+| Work a Pin Board task | `flowiq pin list-remote open` → `pull` → edit → `push` |
+
+The flow is the same everywhere: **pull → edit the JSON → push**. Slugs are the
+filename the pull printed (e.g. `phytoceutics`), or pass a file path.
+
+### Example: fix a line in a client's prompt
+
+```bash
+flowiq prompts pull 08becb51-9734-432e-a1e8-3a2115c0f3eb
+# → wrote ./.flowiq/prompts/phytoceutics.json
+#   edit the section's "content" in that file (keep section "id"s intact)
+flowiq prompts push phytoceutics
+# server regenerates the full system prompt from the sections
+flowiq test send 08becb51-… "question that exercises your change"
+```
+
+### Example: safely change custom tools
+
+```bash
+flowiq ct pull <org_id>
+#   edit tools[] in the JSON
+flowiq ct push <slug> --dry-run
+#   → "diff: +1 added (…); ~1 changed (…); 8 unchanged" + any warnings
+flowiq ct push <slug>
+```
+
+Custom tools define real HTTP calls the agent can execute, so the server
+validates hard (names, URLs, methods, parameter shapes) and warns about typo'd
+keys or `{{placeholders}}` it doesn't recognise. Take the warnings seriously.
+
+## Keys, rotation, logging out
+
+- **`flowiq auth refresh`** — rotates this device's key in place (a fresh key
+  is minted, the old one is revoked server-side). Run it whenever you want a
+  new secret, e.g. after using the CLI on a machine you don't fully trust.
+- **`flowiq auth logout`** — deletes the key file from this machine only. The
+  key itself stays valid server-side, so if the machine is lost/compromised,
+  run `refresh` first (kills the old key) or ask a super admin to revoke it.
+- Keys live at `~/.config/flowiq/auth.json` (chmod 600). CI can use
+  `FLOWIQ_TOKEN=…` instead.
+
+## Troubleshooting
+
+| Symptom | Fix |
+|---|---|
+| `npm i -g …` says the new version doesn't exist | `npm i -g @flowapt/flowiq-cli@<version> --prefer-online` (npm's cache is stale for a few minutes after a publish) |
+| `401 Unauthorized` on every command | `flowiq auth refresh` (falls back to browser login if the key is dead) |
+| `403 … doesn't cover "<scope>"` | Your admin access has been scoped down — ask another super admin to widen your `allowed_scopes` |
+| "Organization has no active_whatsapp_agent" | Target the agent directly: `--agent <id>` (ids from `flowiq agent list <org_id>`) |
+| Login browser page says the code expired | Codes live 10 minutes — just re-run `flowiq auth login` |
+| Pushed the wrong thing | Everything is pull→push, so re-pull an older copy if you have one, or check with Matt — server logs record every push with who/what/when |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flowapt/flowiq-cli",
-  "version": "0.1.11",
+  "version": "0.2.1",
   "description": "Command-line tool for FlowIQ staff: round-trip agent prompts, questionnaires, fine-tuning, pin-board tasks, webhooks, templates, agent-updates, chat exports, and live agent testing without ever touching service-role credentials.",
   "type": "module",
   "bin": {
@@ -9,7 +9,8 @@
   "files": [
     "bin",
     "src",
-    "README.md"
+    "README.md",
+    "TEAM-GUIDE.md"
   ],
   "engines": {
     "node": ">=18"

package/src/commands/agent-updates.js

@@ -4,6 +4,7 @@
 
 import fs from "node:fs/promises";
 import path from "node:path";
+import readline from "node:readline";
 import { http } from "../http.js";
 
 const AU_DIR = path.resolve(process.cwd(), ".flowiq", "agent-updates");
@@ -184,3 +185,72 @@ export async function list() {
     }
   }
 }
+
+// --- resolve (write-back) ---------------------------------------------------
+// Flips a client-raised ticket to resolved/declined and writes the note the
+// CLIENT reads ("FlowIQ: <note>"). --internal is staff-only. Deliberately a
+// separate explicit step after `flowiq test` proves the fix — never automate
+// it off the back of a push ("don't resolve on hope").
+
+const UUID_RE_RESOLVE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+function confirmPrompt(question) {
+  return new Promise((resolve) => {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    rl.question(question, (answer) => { rl.close(); resolve(answer.trim().toLowerCase()); });
+  });
+}
+
+export async function resolve(updateId, opts = {}) {
+  if (!UUID_RE_RESOLVE.test(updateId)) {
+    console.error(`Error: "${updateId}" is not a valid update UUID (get it from agent-updates pull).`);
+    process.exit(1);
+  }
+  const status = opts.status || "resolved";
+  if (!["resolved", "declined"].includes(status)) {
+    console.error(`Error: --status must be resolved or declined (got "${status}").`);
+    process.exit(1);
+  }
+  // R-3: a client-facing note is mandatory on resolve (--yes does NOT waive it).
+  if (status === "resolved" && (!opts.note || !opts.note.trim())) {
+    console.error('Refusing to resolve without --note (the client reads this as "FlowIQ: …").');
+    console.error('Pass --note "…", or use --status declined.');
+    process.exit(1);
+  }
+
+  if (!opts.yes) {
+    console.log(`About to mark update ${updateId} as ${status.toUpperCase()}.`);
+    if (opts.note) console.log(`The client will read:  FlowIQ: ${opts.note}`);
+    if (opts.internal) console.log(`Staff-only note:       ${opts.internal}`);
+    const answer = await confirmPrompt("Type y to confirm: ");
+    if (answer !== "y" && answer !== "yes") {
+      console.log("Aborted — nothing changed.");
+      process.exit(0);
+    }
+  }
+
+  let resp;
+  try {
+    resp = await http.post("agent-updates", {
+      action: "resolve",
+      update_id: updateId,
+      status,
+      superadmin_comment: opts.note ?? null,
+      internal_notes: opts.internal ?? null,
+      superadmin_response_image: opts.image ?? null,
+    });
+  } catch (e) {
+    console.error(`Resolve failed: ${e.message}`);
+    if (e.body?.error) console.error(`  ${e.body.error}`);
+    process.exit(1);
+  }
+
+  console.log(`Update ${resp.update_id} → ${resp.status.toUpperCase()}`);
+  console.log(`  org:       ${resp.organization_name ?? resp.organization_id}`);
+  console.log(`  title:     ${resp.title}`);
+  console.log(`  was:       ${resp.previous_status}`);
+  console.log(`  by:        ${resp.resolved_by_email ?? resp.resolved_by}`);
+  if (resp.superadmin_comment) console.log(`  client:    FlowIQ: ${resp.superadmin_comment}`);
+  if (resp.internal_notes) console.log(`  internal:  ${resp.internal_notes}`);
+  if (resp.already_resolved) console.log(`  ⚠ was already terminal (${resp.previous_status}) — note/status overwritten.`);
+}