@flowapt/flowiq-cli 0.2.4 → 0.2.6

package/README.md

@@ -230,20 +230,32 @@ throttle *and* your brake. Tags only; the send is `broadcast send --tag` (one
 batch at a time) or the dashboard broadcaster.
 
 ```bash
+# Cohort by ORDER-COUNT CRITERIA (v0.2.6 — server-resolved, no id file needed):
+flowiq seg plan <org_id> --tag-prefix repeat-60d --min-orders 2 --window 60d
+# "everyone with 2+ orders in the last 60 days" — counted from the captured
+# order stores (shopify_orders/woo_orders), NOT the lifetime orders_count column.
+# --window takes 60d / 8w / 3m; omit it for all captured history. --platform auto|shopify|woo.
+
+# Cohort by explicit id list (the original mode):
 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)
+flowiq seg apply <org_id> repeat-60d            # DRY-RUN (default — nothing writes)
+flowiq seg apply <org_id> repeat-60d --commit   # append the tags (idempotent — re-runs report already_had)
+flowiq seg list  <org_id> --prefix repeat-60d   # VERIFY: tag → count
+flowiq seg untag <org_id> repeat-60d --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.
+- **Two cohort sources:** `--min-orders [--window]` resolves the cohort
+  server-side (the windowed order count the app's Advanced Tagging UI cannot
+  express — its Min Orders filter is lifetime-only), or pass explicit
+  **contact UUIDs** (a snapshot JSON's `contact_ids[]` or a plain file) for
+  SQL-derived / bespoke cohorts.
 - 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).
+- Point-in-time warning: the plan snapshots the cohort at plan time; re-run
+  `plan` to refresh it (someone who ordered since won't auto-drop, criteria
+  mode included).
 
 ### Keywords — `flowiq keywords pull|push|list` (alias `kw`)
 
@@ -269,6 +281,9 @@ 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_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.
 - Scheduled keywords: the keyword-scheduler cron reconciles `active` from
   `start_date`/`end_date` within ~30 min of your push.
 
@@ -416,6 +431,13 @@ Media headers: pass `media_header.file_url` (a public URL) — the edge function
 uploads it to Meta server-side. Approval is async; re-`pull` for the
 authoritative Meta status.
 
+`template_data` is FlowIQ's own send-time mapping (slot labels, default header
+image) stored alongside the template. Omit it and a default is synthesized
+server-side (`auto_synthesized: true`; the response says
+`template_data_synthesized: true`) so the row always exists for `status` and
+broadcast mapping suggestions — pass your own only when you want real slot
+labels (e.g. `"body_params": {"1": "first_name", "2": "order_number"}`).
+
 ### Org — `flowiq org create` / `flowiq org info <organization_id>`
 
 Create a brand-new organization, or look one up (read-only; raw store/Meta
@@ -545,6 +567,19 @@ flowiq test cleanup <organization_id> --confirm      # delete the stress contact
 `--agent <id>` targets a specific (non-active) agent. `test stress cleanup` is
 destructive and requires `--confirm`.
 
+### Guide — `flowiq guide`
+
+Read the bundled docs in the terminal — no digging through node_modules.
+
+```bash
+flowiq guide               # the team guide (TEAM-GUIDE.md), paged; q to quit
+flowiq guide --reference   # this full command reference (README.md)
+flowiq guide --no-pager    # plain print (also automatic when piped)
+```
+
+Both files ship inside the npm package, so what you read always matches the
+version you have installed.
+
 ## Environment variable overrides
 
 | Var | Default | Use |

package/TEAM-GUIDE.md

@@ -34,6 +34,10 @@ Confirm with:
 flowiq auth whoami
 ```
 
+This guide travels with the CLI — read it any time with `flowiq guide`
+(`--reference` for the full command reference). It always matches the version
+you have installed.
+
 > **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.
@@ -72,7 +76,8 @@ flowiq auth whoami
 | 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` |
+| 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` |
+| Split a big id-list 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>` |
@@ -84,6 +89,7 @@ flowiq auth whoami
 | 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` |
+| Re-read this guide / the full command reference | `flowiq guide` / `flowiq guide --reference` |
 
 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.

package/package.json

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

@@ -0,0 +1,32 @@
+// flowiq guide — read the bundled team guide (TEAM-GUIDE.md) or the full
+// command reference (README.md) right in the terminal. Both files ship inside
+// the npm tarball, so what this prints always matches the installed CLI
+// version — no drift between the tool and its docs.
+import { readFileSync, existsSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+
+const PKG_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..");
+
+export function show(opts = {}) {
+  const file = opts.reference ? "README.md" : "TEAM-GUIDE.md";
+  const fullPath = path.join(PKG_ROOT, file);
+
+  if (!existsSync(fullPath)) {
+    console.error(`Could not find ${file} in the installed package (${PKG_ROOT}).`);
+    console.error("Reinstall the CLI:  npm i -g @flowapt/flowiq-cli");
+    process.exit(1);
+  }
+
+  // Interactive terminal → page it (quit with q); piped/redirected or
+  // --no-pager → plain print.
+  if (process.stdout.isTTY && opts.pager !== false) {
+    const pager = process.env.PAGER || "less";
+    const args = pager === "less" ? ["-R", fullPath] : [fullPath];
+    const res = spawnSync(pager, args, { stdio: "inherit" });
+    if (!res.error) return;
+    // pager missing → fall through to plain print
+  }
+  process.stdout.write(readFileSync(fullPath, "utf8"));
+}

package/src/commands/segments.js

@@ -3,11 +3,17 @@
 // runbook). This command TAGS ONLY — it never sends. The send per tag is
 // `flowiq broadcast send --tag <batch-tag>` (or the dashboard broadcaster).
 //
-//   plan  <org> --tag-prefix X (--from-segment file | --ids-file file)  # exclusions → slice → plan file (no DB write)
+//   plan  <org> --tag-prefix X (--from-segment file | --ids-file file
+//                               | --min-orders N [--window 60d])        # exclusions → slice → plan file (no DB write)
 //   apply <org> <slug>  [--commit] [--yes]                              # append the batch tags (dry-run default)
 //   list  <org> [--prefix X]                                            # VERIFY: tag → contact count
 //   untag <org> <slug> --commit --confirm                               # ROLLBACK: remove the plan's own tags
 //
+// --min-orders resolves the cohort SERVER-SIDE (segment_order_cohort RPC):
+// contacts with >= N captured orders (shopify_orders/woo_orders) inside the
+// --window (e.g. 60d / 8w / 3m; omit for all captured history) — the windowed
+// count the Advanced Tagging UI cannot express (its Min Orders is lifetime).
+//
 // Golden rules encoded: exclusions (opt-out/archived/blocked) are applied
 // BEFORE slicing; apply is append-only + idempotent (`already_had` reported,
 // never double-added); untag only ever removes the plan's own tags.
@@ -52,10 +58,20 @@ async function resolvePlan(identifier) {
   throw new Error(`Plan file not found. Tried:\n  ${candidates.join("\n  ")}`);
 }
 
+/** Parse --window "60d" / "8w" / "3m" / "45" → days. */
+function parseWindowDays(spec) {
+  const m = String(spec).trim().match(/^(\d+)([dwm])?$/i);
+  if (!m) throw new Error(`--window must look like 60d / 8w / 3m (got "${spec}")`);
+  const n = Number(m[1]);
+  const days = n * ({ d: 1, w: 7, m: 30 }[(m[2] || "d").toLowerCase()]);
+  if (!Number.isInteger(days) || days < 1 || days > 3650) throw new Error("--window must resolve to 1..3650 days");
+  return days;
+}
+
 /** Read the cohort ids from a christiaan/segments snapshot or a plain file. */
 async function readCohort(opts, orgId) {
   if (!!opts.fromSegment === !!opts.idsFile) {
-    throw new Error("provide exactly one of --from-segment / --ids-file");
+    throw new Error("provide exactly one of --from-segment / --ids-file / --min-orders");
   }
   let ids = [], sourceMeta;
   if (opts.fromSegment) {
@@ -86,23 +102,50 @@ export async function plan(orgId, opts = {}) {
   if (!Number.isInteger(batchSize) || batchSize < 1) { console.error("Error: --batch-size must be ≥ 1."); process.exit(1); }
   if (batchSize > 500) console.log(`⚠ batch size ${batchSize} is large — Meta tier risk; the runbook default is 75.`);
 
+  // Cohort source: a server-resolved order-count criterion (--min-orders
+  // [--window]) OR an explicit id list (--from-segment / --ids-file).
+  const criteriaMode = opts.minOrders !== undefined;
+  if (criteriaMode && (opts.fromSegment || opts.idsFile)) {
+    console.error("Error: --min-orders cannot be combined with --from-segment / --ids-file.");
+    process.exit(1);
+  }
+
   let cohort;
-  try { cohort = await readCohort(opts, orgId); }
-  catch (e) { console.error(`Error: ${e.message}`); process.exit(1); }
-  if (cohort.badUuids.length) console.log(`⚠ skipped ${cohort.badUuids.length} non-UUID line(s) in the cohort source.`);
-  if (!cohort.ids.length) { console.error("Error: no valid contact ids in the cohort source."); process.exit(1); }
+  let cohortSpec = null;
+  if (criteriaMode) {
+    const minOrders = Number(opts.minOrders);
+    if (!Number.isInteger(minOrders) || minOrders < 1) { console.error("Error: --min-orders must be an integer ≥ 1."); process.exit(1); }
+    let windowDays = null;
+    if (opts.window) {
+      try { windowDays = parseWindowDays(opts.window); }
+      catch (e) { console.error(`Error: ${e.message}`); process.exit(1); }
+    }
+    cohortSpec = { min_orders: minOrders, window_days: windowDays, platform: opts.platform || "auto" };
+    cohort = { ids: [], badUuids: [], sourceMeta: { type: "order_cohort", ...cohortSpec } };
+  } else {
+    try { cohort = await readCohort(opts, orgId); }
+    catch (e) { console.error(`Error: ${e.message}`); process.exit(1); }
+    if (cohort.badUuids.length) console.log(`⚠ skipped ${cohort.badUuids.length} non-UUID line(s) in the cohort source.`);
+    if (!cohort.ids.length) { console.error("Error: no valid contact ids in the cohort source."); process.exit(1); }
+  }
 
   let resp;
   try {
     resp = await http.post("segments", {
       mode: "plan", organization_id: orgId,
-      contact_ids: cohort.ids, include_unsafe: !!opts.includeUnsafe,
+      ...(criteriaMode ? { cohort: cohortSpec } : { contact_ids: cohort.ids }),
+      include_unsafe: !!opts.includeUnsafe,
     });
   } catch (e) {
     console.error(`Plan failed: ${e.message}`);
     if (e.body?.error) console.error(`  ${e.body.error}`);
     process.exit(1);
   }
+  if (resp.cohort) {
+    const w = resp.cohort.window_days ? `in the last ${resp.cohort.window_days} days` : "across all captured history";
+    console.log(`Cohort: ${resp.cohort.min_orders}+ orders ${w} → ${resp.cohort.resolved_count} contact(s) (server-resolved from captured orders).`);
+    cohort.sourceMeta.resolved_count = resp.cohort.resolved_count;
+  }
   if (!resp.safe_count) { console.error("Nothing to tag — 0 safe contacts after exclusions (V-13)."); process.exit(1); }
 
   // Slice safe_ids into contiguous batches (client-side, per the spec split).

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 keywordsCmd from "./commands/keywords.js";
+import * as guideCmd from "./commands/guide.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
@@ -408,10 +409,13 @@ export function run(argv) {
     .alias("seg")
     .description("Slice a contact cohort into fixed-size batch tags and bulk-apply them (broadcast batching)");
   segments.command("plan <organization_id>")
-    .description("Ingest a cohort id list, apply broadcast-safety exclusions, slice into N-sized batch tags, write the plan (no DB write)")
+    .description("Resolve a cohort (id list OR order-count criteria), apply broadcast-safety exclusions, slice into N-sized batch tags, write the plan (no DB write)")
     .requiredOption("--tag-prefix <name>", "campaign tag stem; batches become <prefix>-batch-NN")
     .option("--from-segment <path>", "a segments snapshot JSON (uses its contact_ids[])")
     .option("--ids-file <path>", "a plain newline/CSV file of contact UUIDs")
+    .option("--min-orders <n>", "SERVER-RESOLVED cohort: contacts with ≥ n captured orders (instead of an id file)")
+    .option("--window <span>", "with --min-orders: only count orders in this window, e.g. 60d / 8w / 3m (omit = all captured history)")
+    .option("--platform <p>", "with --min-orders: auto | shopify | woo", "auto")
     .option("--batch-size <n>", "contacts per batch tag", "75")
     .option("--segment <name>", "plan file slug (default: the tag prefix)")
     .option("--include-unsafe", "do NOT exclude non-broadcast-safe contacts (rare; default excludes)")
@@ -448,5 +452,12 @@ export function run(argv) {
     .description("List local keyword snapshots")
     .action(() => keywordsCmd.list());
 
+  // guide (bundled docs — always match the installed version)
+  program.command("guide")
+    .description("Read the team guide (how we use this CLI); --reference for the full command reference")
+    .option("--reference", "show the full command reference (README) instead of the team guide")
+    .option("--no-pager", "print straight to stdout instead of paging")
+    .action((opts) => guideCmd.show(opts));
+
   program.parseAsync(argv);
 }