@flowapt/flowiq-cli 0.2.7 → 0.2.9

package/README.md

@@ -552,13 +552,25 @@ Set an allowlisted set of the active agent's config fields (the prompt-builder
 flowiq agent config <organization_id>                        # show current
 flowiq agent config <organization_id> --use-settings-prompt --model gpt-5.4-mini \
   --rename Zara --tool woo_order_build=true --tool view_cart_tool=true --discount true
+flowiq agent config <organization_id> --test-contact-number 27000000001 --test-contact-name "QA Bot"
 ```
 
 Settable: `settings.use_settings_prompt`, `settings.model`, agent `--rename`,
 the tool-flag columns (`woo_order_build`, `woo_tip_field`, `woo_order_note_field`,
 `view_cart_tool`, `restock_tool`, `block_tool_status`, `postal_code_tool_status`,
-`shopify_products_web_chat`), and `discount.enabled`. Anything else is rejected;
-every change is reported before → after.
+`shopify_products_web_chat`), `discount.enabled`, and the `flowiq test` contact
+(`settings.test_contact_number` / `settings.test_contact_name`). Anything else is
+rejected; every change is reported before → after.
+
+**Test contact (`--test-contact-number` / `--test-contact-name`, v0.2.9).**
+This is the contact `flowiq test` drives the live agent through (read by
+`api/cli/agent-test.js` as `settings.test_contact_number`). ⚠ **Use a clearly
+FAKE number.** Whatever you set becomes the `whatsapp_id` the test harness looks
+up or creates in the org — point it at a real customer's number and your tests
+route through *their* contact record and force `bot_status=true` on it. If that
+number already maps to an existing contact, the command prints a `⚠` warning
+naming it. Pass `--test-contact-number ""` (empty) to clear the override — the
+harness then falls back to a synthetic per-agent `test_<agent_id>` contact.
 
 ### Agent updates — `flowiq agent-updates pull|list|resolve` (alias `au`)
 

package/TEAM-GUIDE.md

@@ -75,6 +75,7 @@ you have installed.
 | 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?"` |
+| Set which contact `flowiq test` uses (use a FAKE number!) | `flowiq agent config <org_id> --test-contact-number 27000000001 --test-contact-name "QA Bot"` |
 | Send a template broadcast to a CSV of people | `flowiq bc map <org_id> --template … --csv …` → `flowiq bc send … ` (dry-run) → `… --commit` |
 | Tag every repeat buyer (e.g. 2+ orders in the last 60 days) | `flowiq seg plan <org_id> --tag-prefix repeat-60d --min-orders 2 --window 60d` → `flowiq seg apply <org_id> repeat-60d` (dry run) → `… --commit` |
 | Tag everyone who bought a product (accurate, windowable) | `flowiq seg plan <org_id> --tag-prefix whey --bought "Whey" --window 90d` → `flowiq seg apply … --commit` |
@@ -122,6 +123,43 @@ 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.
 
+### Example: tag a segment of contacts (Advanced Tagging)
+
+`flowiq tag` is the Contacts → **Advanced Tagging** dialog in your terminal.
+It applies **one named tag** to a matched set. It is **always dry-run first** —
+you see the count and a sample, and *nothing writes* until you add `--commit`.
+
+```bash
+# 1. See who matches (nothing is written)
+flowiq tag segment <org_id> --min-orders 2 --min-spent 1000 --region ZA-GP
+#    → "Custom segment: 4502 contact(s) match." + a 10-row sample
+
+# 2. Happy with the count? Apply the tag:
+flowiq tag segment <org_id> --min-orders 2 --min-spent 1000 --region ZA-GP \
+  --tag gp-repeat-spenders --commit
+#    → "matched 4502 · newly tagged 4502 · already had ... 0"
+
+# 3. Verify, then (if needed) undo:
+flowiq tag list   <org_id> --prefix gp-repeat            # tag → count
+flowiq tag remove <org_id> gp-repeat-spenders --confirm  # removes it from everyone
+```
+
+The five match modes (swap `segment` for any of these):
+
+| Mode | Tags contacts who… |
+|---|---|
+| `field --field order_history --any "Whey,Protein"` | have a keyword in a field (order history, summary, shopify tags, name, email…) |
+| `cohort --type top_spenders --limit 500` | rank in the **top N** by spend / orders / recency (top-N, not a threshold) |
+| `segment --min-orders 2 --min-spent 1000 --region ZA-GP` | match order-count / spend / last-order-date / region filters |
+| `attributes --filter allow_broadcast_true` | match a broadcast-permission state |
+| `messages --min-count 3 --sender user-whatsapp` | have ≥ N messages of a channel type |
+
+Two things to know: for **"who bought product X"** use
+`flowiq seg plan --bought "X" --window 90d` instead of `tag field` — it reads the
+real order line-items (accurate + windowable) rather than the order-history text.
+And a commit over 2000 contacts asks you to type the tag name to confirm
+(add `--yes` to skip). Everything is appends-only and reversible with `tag remove`.
+
 ## Keys, rotation, logging out
 
 - **`flowiq auth refresh`** — rotates this device's key in place (a fresh key

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flowapt/flowiq-cli",
-  "version": "0.2.7",
+  "version": "0.2.9",
   "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/agent-config.js

@@ -41,6 +41,8 @@ export async function config(orgId, opts = {}) {
   const settings = {};
   if (opts.useSettingsPrompt !== undefined) settings.use_settings_prompt = parseBool(opts.useSettingsPrompt, "--use-settings-prompt");
   if (opts.model !== undefined) settings.model = opts.model;
+  if (opts.testContactNumber !== undefined) settings.test_contact_number = opts.testContactNumber;
+  if (opts.testContactName !== undefined) settings.test_contact_name = opts.testContactName;
   if (Object.keys(settings).length) body.settings = settings;
   if (opts.rename !== undefined) body.name = opts.rename;
   if (opts.discount !== undefined) body.discount_enabled = parseBool(opts.discount, "--discount");
@@ -73,7 +75,7 @@ export async function config(orgId, opts = {}) {
     }
     console.log(`${resp.organization_name} → agent ${resp.agent_id}${resp.is_active === false ? " [NON-active]" : ""}`);
     printSnapshot("current", resp.current);
-    console.log("\n(pass --use-settings-prompt / --model / --rename / --tool / --discount to change)");
+    console.log("\n(pass --use-settings-prompt / --model / --rename / --tool / --discount / --test-contact-number / --test-contact-name to change)");
     return;
   }
 
@@ -93,4 +95,5 @@ export async function config(orgId, opts = {}) {
     const a = resp.after?.[k];
     console.log(`    ${k.padEnd(30)} ${b === null || b === undefined ? "(unset)" : b} → ${a === null || a === undefined ? "(unset)" : a}`);
   }
+  for (const w of resp.warnings || []) console.log(`  ⚠ ${w}`);
 }

package/src/index.js

@@ -227,6 +227,8 @@ export function run(argv) {
     .option("--rename <name>", "rename the agent")
     .option("--tool <flag=bool>", "toggle a tool flag (repeatable): woo_order_build/woo_tip_field/woo_order_note_field/view_cart_tool/restock_tool/block_tool_status/postal_code_tool_status/shopify_products_web_chat", agentConfigCmd.collectTool, [])
     .option("--discount [bool]", "agent.discount.enabled (true if bare)")
+    .option("--test-contact-number <number>", "settings.test_contact_number — the contact `flowiq test` uses (use a FAKE number; \"\" clears it → synthetic fallback)")
+    .option("--test-contact-name <name>", "settings.test_contact_name — display name for the test contact (\"\" clears it)")
     .action((orgId, opts) => agentConfigCmd.config(orgId, opts));
 
   // agent-updates (pending client change-requests + chat context; pull + resolve)