@flowapt/flowiq-cli 0.2.5 → 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.
 

package/TEAM-GUIDE.md

@@ -76,7 +76,8 @@ you have installed.
 | 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>` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flowapt/flowiq-cli",
-  "version": "0.2.5",
+  "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/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

@@ -409,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)")