@flowapt/flowiq-cli 0.3.1 → 0.3.2

package/README.md

@@ -238,6 +238,14 @@ flowiq seg plan <org_id> --tag-prefix bcast --from-attribute allow_broadcast_tru
 # as `tag attributes --filter`). --split N (2..100) replaces --batch-size;
 # --seed makes the shuffle reproducible, --ordered keeps server order (no shuffle).
 
+# Cohort from EXISTING TAGS → batched (v0.3.2 — combine tags, then split, no id file):
+flowiq seg plan <org_id> --tag-prefix 18-july-clearance-bc \
+  --from-tag "9-jul-loyalty-list" --exclude "recent-campaign,opt-out" --batch-size 1000
+# contacts carrying ANY of the --from-tag tags, MINUS anyone carrying any --exclude
+# tag, minus archived/blocked/opted-out → sliced into 1000-sized batch tags
+# (18-july-clearance-bc-batch-01, -02, …). --from-tag pairs with --split too.
+# This is the "existing tags → batched send list" flow, entirely in the CLI.
+
 # 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
@@ -262,11 +270,13 @@ flowiq seg untag <org_id> repeat-60d --commit --confirm   # ROLLBACK (its own ta
 
 - **Cohort sources:** `--from-attribute <filter>` (a broadcast-permission
   audience — `all_contacts` / `allow_broadcast_true` / `allow_broadcast_false`
-  / `no_broadcast_permission`, resolved server-side past the 1000-row cap);
-  `--min-orders [--window]` (the windowed order count the app's Advanced Tagging
-  UI cannot express — its Min Orders filter is lifetime-only); `--bought`
-  (product line-items); or explicit **contact UUIDs** (a snapshot JSON's
-  `contact_ids[]` or a plain file). Exactly one per plan.
+  / `no_broadcast_permission`, resolved server-side in one RPC call);
+  **`--from-tag "a,b" [--exclude "c,d"]`** (contacts carrying ANY of the include
+  tags minus anyone carrying an exclude tag — the "existing tags → batched send
+  list" source, v0.3.2); `--min-orders [--window]` (the windowed order count the
+  app's Advanced Tagging UI cannot express — its Min Orders filter is
+  lifetime-only); `--bought` (product line-items); or explicit **contact UUIDs**
+  (a snapshot JSON's `contact_ids[]` or a plain file). Exactly one per plan.
 - **`--split N` = exactly N even cohorts** (2..100), an alternative to
   `--batch-size` fixed chunks. It **shuffles by default** so the cohorts are
   balanced (not skewed by contact age / signup order); `--seed S` makes the

package/TEAM-GUIDE.md

@@ -88,6 +88,7 @@ When you see it, run `npm i -g @flowapt/flowiq-cli` — a stale version also mea
 | Advanced Tagging in the terminal (one named tag on a matched set) | `flowiq tag field\|cohort\|segment\|attributes\|messages <org_id> …` (dry-run) → add `--tag <name> --commit` |
 | List / remove tags | `flowiq tag list <org_id>` · `flowiq tag remove <org_id> <tag> --confirm` |
 | Split your whole broadcast list into N even cohorts (e.g. 3 for A/B/C or waves) | `flowiq seg plan <org_id> --tag-prefix bcast --from-attribute allow_broadcast_true --split 3` → `flowiq seg apply <org_id> bcast --commit` (makes `bcast-batch-01/02/03`, ~even, shuffled) |
+| Combine existing tags → a batched send list (include some tags, drop others, split into batches of N) | `flowiq seg plan <org_id> --tag-prefix clearance-bc --from-tag "loyalty-list" --exclude "recent-campaign" --batch-size 1000` → `flowiq seg apply <org_id> clearance-bc --commit` (makes `clearance-bc-batch-01/02/…`) |
 | 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 |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flowapt/flowiq-cli",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "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,8 +3,9 @@
 // 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
-//                               | --min-orders N [--window 60d])        # exclusions → slice → plan file (no DB write)
+//   plan  <org> --tag-prefix X (--from-attribute F | --from-tag "a,b" [--exclude "c,d"]
+//                               | --min-orders N [--window 60d] | --bought "P"
+//                               | --from-segment file | --ids-file file)  # 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
@@ -132,18 +133,20 @@ export async function plan(orgId, opts = {}) {
     if (opts.seed !== undefined && !Number.isFinite(Number(opts.seed))) { console.error("Error: --seed must be a number."); process.exit(1); }
   }
 
-  // Cohort source: a server-resolved criterion (--from-attribute / --min-orders
-  // / --bought) OR an explicit id list (--from-segment / --ids-file). Exactly one.
+  // Cohort source: a server-resolved criterion (--from-attribute / --from-tag /
+  // --min-orders / --bought) OR an explicit id list (--from-segment / --ids-file).
+  // Exactly one.
   const orderMode = opts.minOrders !== undefined;
   const productMode = opts.bought !== undefined;
   const attributeMode = opts.fromAttribute !== undefined;
-  const criteriaMode = orderMode || productMode || attributeMode;
-  const sourceCount = [orderMode, productMode, attributeMode, !!opts.fromSegment, !!opts.idsFile].filter(Boolean).length;
+  const tagMode = opts.fromTag !== undefined;
+  const criteriaMode = orderMode || productMode || attributeMode || tagMode;
+  const sourceCount = [orderMode, productMode, attributeMode, tagMode, !!opts.fromSegment, !!opts.idsFile].filter(Boolean).length;
   if (sourceCount === 0) {
-    console.error("Error: a cohort source is required — one of --from-attribute / --min-orders / --bought / --from-segment / --ids-file."); process.exit(1);
+    console.error("Error: a cohort source is required — one of --from-attribute / --from-tag / --min-orders / --bought / --from-segment / --ids-file."); process.exit(1);
   }
   if (sourceCount > 1) {
-    console.error("Error: pick exactly ONE cohort source (--from-attribute / --min-orders / --bought / --from-segment / --ids-file)."); process.exit(1);
+    console.error("Error: pick exactly ONE cohort source (--from-attribute / --from-tag / --min-orders / --bought / --from-segment / --ids-file)."); process.exit(1);
   }
 
   let cohort;
@@ -157,6 +160,12 @@ export async function plan(orgId, opts = {}) {
       }
       cohortSpec = { attribute };
       cohort = { ids: [], badUuids: [], sourceMeta: { type: "attribute_cohort", attribute } };
+    } else if (tagMode) {
+      const includeTags = String(opts.fromTag).split(",").map((s) => s.trim()).filter(Boolean);
+      if (!includeTags.length) { console.error("Error: --from-tag needs at least one tag (comma-separate several)."); process.exit(1); }
+      const excludeTags = opts.exclude ? String(opts.exclude).split(",").map((s) => s.trim()).filter(Boolean) : [];
+      cohortSpec = { include_tags: includeTags, exclude_tags: excludeTags };
+      cohort = { ids: [], badUuids: [], sourceMeta: { type: "tag_cohort", include_tags: includeTags, exclude_tags: excludeTags } };
     } else {
     let windowDays = null;
     if (opts.window) {
@@ -209,6 +218,10 @@ export async function plan(orgId, opts = {}) {
         no_broadcast_permission: "contacts with no broadcast permission set",
       }[resp.cohort.attribute] || resp.cohort.attribute;
       console.log(`Cohort: ${label} → ${resp.cohort.resolved_count} contact(s) (server-resolved).`);
+    } else if (resp.cohort.kind === "tag") {
+      const inc = resp.cohort.include_tags.join(", ");
+      const exc = resp.cohort.exclude_tags && resp.cohort.exclude_tags.length ? `, excluding [${resp.cohort.exclude_tags.join(", ")}]` : "";
+      console.log(`Cohort: contacts tagged any of [${inc}]${exc} → ${resp.cohort.resolved_count} contact(s) (server-resolved).`);
     } else {
       const w = resp.cohort.window_days ? `in the last ${resp.cohort.window_days} days` : "across all captured history";
       if (resp.cohort.kind === "product") {

package/src/index.js

@@ -421,6 +421,8 @@ export function run(argv) {
     .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("--from-attribute <filter>", "SERVER-RESOLVED cohort: every contact matching a broadcast-permission filter (all_contacts | allow_broadcast_true | allow_broadcast_false | no_broadcast_permission)")
+    .option("--from-tag <csv>", "SERVER-RESOLVED cohort: contacts carrying ANY of these tag(s) (comma-separated)")
+    .option("--exclude <csv>", "with --from-tag: drop contacts carrying ANY of these tag(s)")
     .option("--min-orders <n>", "SERVER-RESOLVED cohort: contacts with ≥ n captured orders (instead of an id file)")
     .option("--bought <terms>", "SERVER-RESOLVED cohort: contacts who bought these product(s) (comma-separated name substrings) from real order line-items")
     .option("--match <mode>", "with --bought: any (bought any listed product) | all (bought every one)", "any")