@flowapt/flowiq-cli 0.4.7 → 0.4.8

package/README.md

@@ -480,6 +480,47 @@ flowiq tag remove <org_id> vip,old-promo --confirm  # remove tag(s) from ALL con
   matches — re-run until `matched 0`. Idempotent and safe to re-run.
 - **Undo** any tag with `flowiq tag remove <org> <tag> --confirm`.
 
+### Links — `flowiq links shorten|list` (v0.4.8)
+
+Short links with campaign UTM tags — the terminal half of the in-app **URL
+Shortener**. Same engine server-side (`api/_url-shorten-engine.js`), so a link
+minted here is identical to one minted in the dialog.
+
+```bash
+# Dry run FIRST — shows the exact destination each short link will carry
+flowiq links shorten <org> --url "https://shop.co.za/product/x" \
+  --campaign 13Aug_Seeds --content 13Aug_Seeds
+
+flowiq links shorten <org> --url "https://shop.co.za/product/x" \
+  --url "https://shop.co.za/product/y" \
+  --campaign 13Aug_Seeds --content 13Aug_Seeds --domain linklnk.io --commit
+
+flowiq links shorten <org> --file ./slide2.txt --campaign 13Aug_Seeds_VM --content 13Aug_Seeds_VM --commit
+flowiq links list <org> --campaign 13Aug_Seeds
+```
+
+- **`utm_source=whatsapp` and `utm_medium=whatsapp_paid` are FIXED** (the dialog
+  sets them too) — a link built any other way stops matching the attribution
+  queries. You supply `--campaign` and `--content`, and they must be **supplied
+  together**: a campaign with no content silently under-tags every link.
+- **Dry-run by default.** `--commit` mints. The dry run prints the full
+  destination URL per link and whether an identical row already exists.
+- **A new UTM tag = a NEW row with its own code and its own click count.** Reuse
+  is keyed on the exact `(org, full_url)` pair, which is what makes per-campaign
+  attribution work. Re-running the same command is idempotent (`↻ reused`).
+- **Pasting an existing short link is REFUSED** (`chatcart.io` / `linklnk.io` /
+  `yapi.store`) with "pass the destination URL". Shortening a short link would
+  add a second hop and split the click count — and would silently keep the OLD
+  campaign tag, which is the trap this guard exists for.
+- **`--file`** shortens every URL found in a text file — the fast path for a
+  multi-link message body. It does NOT rewrite the file; it prints the mapping.
+- `--domain` picks the short host: `chatcart.io` (default), `linklnk.io`,
+  `yapi.store`. All three resolve identically — match whatever that campaign's
+  other links already use.
+- `--campaign` on **`list`** is an EXACT match, not a prefix: asking for
+  `13Aug_Seeds` does not return the `13Aug_Seeds_VM` rows.
+- Scope group `broadcast`. Audited (`links` / `shorten`); dry runs are not.
+
 ### Keywords — `flowiq keywords pull|push|list` (alias `kw`)
 
 Round-trips an org's **keyword auto-reply engine** — the `keywords` +
@@ -504,10 +545,10 @@ flowiq kw push <slug> --prune            # ALSO deletes DB keywords missing from
   collapses to 1 at runtime — rejected).
 - `field:"attributes"` actions are warned (full jsonb replace; constant
   values only) but applied — this CLI is their only safe editing surface.
-- **Action types accepted** (all nine the runtime implements):
+- **Action types accepted** (all ten the runtime implements):
   `send_message` · `update_contact_field` · `add_contact_tag` ·
   `remove_contact_tag` · `set_agent` · `delay` · `combined` ·
-  `update_ticket_status` · `renotify_ticket`.
+  `update_ticket_status` · `renotify_ticket` · `assign_chat`.
   Per-type rules: tag actions need a non-empty `tags[]` (or a single `tag`
   string) or the runtime writes no tag at all; `set_agent.agent_id` must be
   an agent UUID, or `null`/`""` to CLEAR the contact's binding (warned, since
@@ -530,6 +571,18 @@ flowiq kw push <slug> --prune            # ALSO deletes DB keywords missing from
   ticket-tool `mode:"renotify"` (60s server-side rate limit; a resolved/closed
   ticket is reopened first) — canonical use: the **"I still need help"**
   button. Both send the action's `text` (if any) after the ticket work.
+- **Assign-chat action** (added 13 Aug 2026, for keyword-driven handovers —
+  e.g. a broadcast quick-reply button handing the conversation to a person):
+  `{ "type": "assign_chat", "team_id": "<team-uuid>", "assignee_user_id":
+  "<user-uuid>", "notify_team": true, "notify_member": true }` — writes the
+  contact's `team_id` and/or `assignee` (at least ONE of the two is required,
+  both UUID-shaped; `assignee_user_id` is the profiles/auth user id, not an
+  `organization_members` id), then invokes `team-assignment-notify` for each
+  target unless its `notify_*` flag is explicitly `false`. The notify fn
+  re-checks the org's team/member notification feature flags AND the target's
+  own notify config (Teams page) server-side, so a target with notifications
+  off is assigned silently. Also editable in the dashboard (Keyword Actions →
+  action type "Assign Chat").
 - `action_config.link_preview: false` disables WhatsApp's link-preview card
   on that action's text send (absent/`true` = preview on, the default).
   Passed through verbatim; also toggleable per action in the dashboard.
@@ -990,11 +1043,24 @@ flowiq agent config <organization_id> --test-contact-number 27000000001 --test-c
 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`, `ticket_tool_status`, `collapse_product_variants`),
+`shopify_products_web_chat`, `ticket_tool_status`, `product_lookup`,
+`collapse_product_variants`),
 `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.
 
+**`--tool product_lookup=true` (added 11 Aug 2026).** Turns on the `product_lookup`
+tool: a typo-tolerant **pg_trgm fuzzy match on `product_title`** (plus badge/tag
+search), as opposed to `get_product_info`, which is **semantic**. This matters far
+beyond typo tolerance: `get_product_info` needs BOTH a populated
+`products_all.embedding` column AND a working OpenAI key (it embeds the query at
+call time), so on an org missing either one, **every** product question fails and
+the agent cannot quote a price, confirm stock, or send a product link.
+`product_lookup` needs neither and reads the row directly. Reach for it whenever an
+agent answers product questions with "I can't pull the live menu". Found on Ouma
+Bets Gebak (11 Aug 2026): 25 product rows, 0 embeddings, and an unfunded OpenAI
+account — enabling this flag restored product answers immediately.
+
 **`--tool collapse_product_variants=true` (added 4 Aug 2026).** Not a tool toggle —
 it changes what `get_product_info` RETURNS. OFF (the default) the result cap counts
 **variant rows**, so on a catalogue with several packaging/size variants per product

package/TEAM-GUIDE.md

@@ -80,6 +80,7 @@ When you see it, run `npm i -g @flowapt/flowiq-cli` — a stale version also mea
 | Edit keyword auto-replies (incl. competition entry keywords, add/remove-tag, set-agent and delay actions) | `flowiq kw pull <org_id>` → edit → `flowiq kw push <slug> --dry-run` → `flowiq kw push <slug>` |
 | Send a **different auto-reply depending on the contact** (e.g. "we already have your email" vs "send us your email") | add `"when": {"field":"email","op":"is_not_empty"}` to one action and `is_empty` to the other — see *Keywords* in `flowiq guide --reference`. CLI-only, no dashboard field yet |
 | Make a follow-up button **close the customer's ticket** ("Query solved") or **re-alert the team** ("I still need help") | keyword action `{"type":"update_ticket_status","status":"resolved"}` / `{"type":"renotify_ticket"}` — see *Keywords* in `flowiq guide --reference`. CLI-only, no dashboard field yet |
+| Make a keyword/button **hand the chat to a team or person** (assign in the inbox + email/WhatsApp them) | keyword action `{"type":"assign_chat","team_id":"…","assignee_user_id":"…","notify_member":true}` — see *Keywords* in `flowiq guide --reference`. Also in the dashboard (action type "Assign Chat") |
 | **Find an org's ID** (needed by nearly every command) | `flowiq org list` — or `flowiq org list african` to filter |
 | What's the stock on a product, per branch? | `flowiq shopify stock <org_id> "olive oil"` — shows each location by NAME, and says "not tracked" rather than a confusing 0 |
 | Has this order shipped? What's the tracking? | `flowiq shopify order <org_id> '#14728'` — status, courier, tracking number + link |
@@ -93,8 +94,13 @@ When you see it, run `npm i -g @flowapt/flowiq-cli` — a stale version also mea
 | 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` |
 | Agent says an in-stock product "isn't showing" | `flowiq agent config <org_id> --tool collapse_product_variants=true` — the search cap counts VARIANT rows until this is on |
+| Agent can't quote ANY price / "I can't pull the live menu" | `flowiq agent config <org_id> --tool product_lookup=true` — name-based fuzzy lookup that works without embeddings or a live OpenAI key (semantic `get_product_info` needs both) |
 | 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"` |
+| **Make short links for a campaign** (with UTM tracking) | `flowiq links shorten <org_id> --url "https://shop.co.za/product/x" --campaign 13Aug_Seeds --content 13Aug_Seeds` (dry run) → `… --commit`. `utm_source`/`utm_medium` are set for you; campaign + content must be given together |
+| Short links for every URL in a message | `flowiq links shorten <org_id> --file ./message.txt --campaign X --content X --commit` |
+| Check which links a campaign has, and their clicks | `flowiq links list <org_id> --campaign 13Aug_Seeds` |
+| A link already looks short (`linklnk.io/abc123`) — can I re-tag it? | No: paste the DESTINATION url instead. Re-shortening keeps the old campaign tag and splits the click count, so the CLI refuses it |
 | 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` |

package/package.json

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

@@ -0,0 +1,144 @@
+// `flowiq links` — short links + campaign UTM tags from the terminal.
+//
+// The terminal half of the in-app URL Shortener. Same engine server-side
+// (api/_url-shorten-engine.js), so a link minted here is identical to one minted
+// in the dialog: utm_source=whatsapp, utm_medium=whatsapp_paid fixed, campaign +
+// content yours.
+//
+//   flowiq links shorten <org> --url <u> [--url <u2>…] --campaign 13Aug_Seeds --content 13Aug_Seeds
+//   flowiq links shorten <org> --file ./message.txt --campaign X --content X --domain linklnk.io
+//   flowiq links list <org> [--campaign X] [--limit 25]
+//
+// Dry-run FIRST (`--dry-run`) on anything going into a real campaign: it shows
+// the exact destination URL each short link will carry, and whether an identical
+// row already exists (so you can see you are about to reuse an OLD campaign tag).
+
+import fs from "node:fs";
+import { http } from "../http.js";
+
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const URL_PATTERN = /(https?:\/\/[^\s\)]+)/g;
+
+function requireOrg(orgId) {
+  if (!UUID_RE.test(orgId)) {
+    console.error(`Error: "${orgId}" is not a valid organization UUID. Find it with: flowiq org list <name>`);
+    process.exit(1);
+  }
+}
+
+export async function shorten(orgId, opts = {}) {
+  requireOrg(orgId);
+
+  // Collect URLs: repeatable --url, and/or every URL found in --file.
+  const urls = [...(opts.url || [])];
+  if (opts.file) {
+    let text;
+    try {
+      text = fs.readFileSync(opts.file, "utf8");
+    } catch (e) {
+      console.error(`Error: could not read --file ${opts.file}: ${e.message}`);
+      process.exit(1);
+    }
+    const found = text.match(URL_PATTERN) || [];
+    if (!found.length) console.error(`⚠ No URLs found in ${opts.file}`);
+    urls.push(...found);
+  }
+  if (!urls.length) {
+    console.error("Error: pass at least one --url <url>, or --file <path> containing URLs.");
+    process.exit(1);
+  }
+
+  // Dedupe while preserving order — the same URL twice would otherwise print twice.
+  const seen = new Set();
+  const unique = urls.filter((u) => {
+    const k = u.trim();
+    if (seen.has(k)) return false;
+    seen.add(k);
+    return true;
+  });
+
+  const dryRun = opts.dryRun !== false && opts.commit !== true;
+
+  let resp;
+  try {
+    resp = await http.post("links", {
+      organization_id: orgId,
+      action: "shorten",
+      urls: unique,
+      campaign: opts.campaign,
+      content: opts.content,
+      domain: opts.domain,
+      dry_run: dryRun,
+    });
+  } catch (e) {
+    console.error(`Shorten failed: ${e.message}`);
+    process.exit(1);
+  }
+
+  if (opts.json) { console.log(JSON.stringify(resp, null, 2)); return; }
+
+  const utm = resp.utm
+    ? `utm_source=${resp.utm.source} · utm_medium=${resp.utm.medium} · utm_campaign=${resp.utm.campaign} · utm_content=${resp.utm.content}`
+    : "no UTM tags (plain short link)";
+  console.log(`${resp.organization_name} · ${resp.domain}`);
+  console.log(`${utm}\n`);
+
+  for (const r of resp.results) {
+    const label = {
+      created: "✓ created",
+      reused: "↻ reused ",
+      would_create: "· would create",
+      would_reuse: "· would REUSE an existing row",
+      refused_already_short: "✗ refused",
+      invalid_url: "✗ invalid url",
+      failed: "✗ failed",
+    }[r.state] || r.state;
+    console.log(`${label}  ${r.short_url || r.input}`);
+    if (r.full_url) console.log(`            → ${r.full_url}`);
+    if (r.note) console.log(`            ⚠ ${r.note}`);
+  }
+
+  console.log("");
+  if (dryRun) {
+    console.log(`DRY RUN — nothing written. Re-run with --commit to mint these links.`);
+  } else {
+    console.log(`${resp.created} created · ${resp.reused} reused${resp.failed ? ` · ${resp.failed} failed` : ""}`);
+  }
+  // A reuse is not automatically wrong (idempotent re-run), but it means the code
+  // you are about to paste already existed — with whatever campaign tag it was
+  // born with. Worth a second look when you asked for a NEW campaign.
+  const reusedRows = resp.results.filter((r) => r.state === "reused" || r.state === "would_reuse");
+  if (reusedRows.length && resp.utm) {
+    console.log(`⚠ ${reusedRows.length} url(s) already had a row with this exact destination — those keep their existing click history.`);
+  }
+}
+
+export async function list(orgId, opts = {}) {
+  requireOrg(orgId);
+  let resp;
+  try {
+    resp = await http.post("links", {
+      organization_id: orgId,
+      action: "list",
+      campaign: opts.campaign,
+      limit: opts.limit,
+    });
+  } catch (e) {
+    console.error(`List failed: ${e.message}`);
+    process.exit(1);
+  }
+
+  if (opts.json) { console.log(JSON.stringify(resp, null, 2)); return; }
+
+  if (!resp.links.length) {
+    console.log(opts.campaign ? `No links on ${resp.organization_name} for campaign "${opts.campaign}".` : `No links on ${resp.organization_name}.`);
+    return;
+  }
+  const pad = (s, n) => String(s ?? "").padEnd(n);
+  console.log(`${pad("CODE", 10)}${pad("CLICKS", 8)}${pad("CREATED", 12)}URL`);
+  for (const l of resp.links) {
+    const day = String(l.created_at || "").slice(0, 10);
+    console.log(`${pad(l.code, 10)}${pad(l.clicks ?? 0, 8)}${pad(day, 12)}${l.full_url}`);
+  }
+  console.log(`\n${resp.count} link(s)${opts.campaign ? ` · campaign "${opts.campaign}"` : ""}`);
+}

package/src/index.js

@@ -27,6 +27,7 @@ import * as customToolsCmd from "./commands/custom-tools.js";
 import * as broadcastCmd from "./commands/broadcast.js";
 import * as segmentsCmd from "./commands/segments.js";
 import * as tagCmd from "./commands/tag.js";
+import * as linksCmd from "./commands/links.js";
 import * as keywordsCmd from "./commands/keywords.js";
 import * as guideCmd from "./commands/guide.js";
 import * as auditCmd from "./commands/audit.js";
@@ -534,6 +535,26 @@ export function run(argv) {
     .option("--confirm", "required alongside --commit")
     .action((orgId, id, opts) => segmentsCmd.untag(orgId, id, opts));
 
+  // links (short links + campaign UTM tags — the URL Shortener dialog in the terminal; dry-run default)
+  const links = program.command("links")
+    .description("Short links with campaign UTM tags (dry-run by default; --commit to mint)");
+  links.command("shorten <organization_id>")
+    .description("Shorten one or more URLs, tagging each with utm_campaign/utm_content")
+    .option("--url <url>", "URL to shorten (repeatable)", (v, acc) => (acc || []).concat([v]), [])
+    .option("--file <path>", "shorten every URL found in this text file")
+    .option("--campaign <value>", "utm_campaign (e.g. 13Aug_Seeds) — must be paired with --content")
+    .option("--content <value>", "utm_content — must be paired with --campaign")
+    .option("--domain <host>", "short domain: chatcart.io (default) | linklnk.io | yapi.store")
+    .option("--commit", "actually mint the links (omit = dry-run preview)")
+    .option("--json", "raw JSON output")
+    .action((orgId, opts) => linksCmd.shorten(orgId, opts));
+  links.command("list <organization_id>")
+    .description("List the org's short links, newest first")
+    .option("--campaign <value>", "only links carrying this exact utm_campaign")
+    .option("--limit <n>", "max rows (default 25, max 200)")
+    .option("--json", "raw JSON output")
+    .action((orgId, opts) => linksCmd.list(orgId, opts));
+
   // tag (the Advanced Tagging dialog in the terminal — ONE named tag on a matched set; dry-run default)
   const tag = program.command("tag")
     .description("Advanced Tagging: apply one named tag to a matched set of contacts (dry-run by default; --commit to write)");