@flowapt/flowiq-cli 0.3.0 → 0.3.2

package/README.md

@@ -230,6 +230,22 @@ throttle *and* your brake. Tags only; the send is `broadcast send --tag` (one
 batch at a time) or the dashboard broadcaster.
 
 ```bash
+# Broadcast list → N even TAGGED COHORTS in ONE command (v0.3.1 — no id file, no DB access):
+flowiq seg plan <org_id> --tag-prefix bcast --from-attribute allow_broadcast_true --split 3 --seed 42
+# every broadcast-opted-in contact (minus archived/blocked), shuffled into 3
+# BALANCED cohorts → bcast-batch-01/02/03. --from-attribute also takes
+# all_contacts | allow_broadcast_false | no_broadcast_permission (same selector
+# 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
@@ -252,11 +268,21 @@ 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)
 ```
 
-- **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.
+- **Cohort sources:** `--from-attribute <filter>` (a broadcast-permission
+  audience — `all_contacts` / `allow_broadcast_true` / `allow_broadcast_false`
+  / `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
+  shuffle reproducible, `--ordered` keeps server order. `--from-attribute
+  allow_broadcast_true --split 3` is the "whole broadcast list → 3 balanced
+  tagged cohorts" one-liner — no id file, no database access.
 - 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 snapshots the cohort at plan time; re-run

package/TEAM-GUIDE.md

@@ -87,6 +87,8 @@ When you see it, run `npm i -g @flowapt/flowiq-cli` — a stale version also mea
 | Tag everyone who bought a product (accurate, windowable) | `flowiq seg plan <org_id> --tag-prefix whey --bought "Whey" --window 90d` → `flowiq seg apply … --commit` |
 | 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.0",
+  "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
@@ -39,6 +40,27 @@ function slugify(name, fallback) {
   return s || fallback;
 }
 
+/** Deterministic PRNG (mulberry32) so `--seed` gives a reproducible shuffle. */
+function mulberry32(seed) {
+  let a = seed >>> 0;
+  return function () {
+    a |= 0; a = (a + 0x6d2b79f5) | 0;
+    let t = Math.imul(a ^ (a >>> 15), 1 | a);
+    t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+}
+
+/** Fisher–Yates shuffle in place. Pass a numeric seed for reproducibility, else Math.random. */
+function shuffle(arr, seed) {
+  const rng = seed !== undefined && seed !== null && String(seed).length ? mulberry32(Number(seed) >>> 0) : Math.random;
+  for (let i = arr.length - 1; i > 0; i--) {
+    const j = Math.floor(rng() * (i + 1));
+    [arr[i], arr[j]] = [arr[j], arr[i]];
+  }
+  return arr;
+}
+
 async function fileExists(p) {
   try { await fs.access(p); return true; } catch { return false; }
 }
@@ -98,26 +120,53 @@ export async function plan(orgId, opts = {}) {
     console.error(`Error: --tag-prefix must be slug-safe lowercase ([a-z0-9-], got "${prefix}").`);
     process.exit(1);
   }
+  const splitMode = opts.split !== undefined;
   const batchSize = Number(opts.batchSize ?? 75);
-  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.`);
+  if (!splitMode) {
+    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.`);
+  }
+  let splitN = 0;
+  if (splitMode) {
+    splitN = Number(opts.split);
+    if (!Number.isInteger(splitN) || splitN < 2 || splitN > 100) { console.error("Error: --split must be an integer 2..100."); process.exit(1); }
+    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 (--min-orders OR --bought,
-  // both with an optional --window) OR an explicit id list (--from-segment /
-  // --ids-file).
+  // 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 criteriaMode = orderMode || productMode;
-  if (orderMode && productMode) {
-    console.error("Error: use either --min-orders or --bought, not both."); process.exit(1);
+  const attributeMode = opts.fromAttribute !== undefined;
+  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 / --from-tag / --min-orders / --bought / --from-segment / --ids-file."); process.exit(1);
   }
-  if (criteriaMode && (opts.fromSegment || opts.idsFile)) {
-    console.error("Error: --min-orders / --bought cannot be combined with --from-segment / --ids-file."); process.exit(1);
+  if (sourceCount > 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;
   let cohortSpec = null;
   if (criteriaMode) {
+    if (attributeMode) {
+      const ATTR = ["all_contacts", "allow_broadcast_true", "allow_broadcast_false", "no_broadcast_permission"];
+      const attribute = String(opts.fromAttribute).trim();
+      if (!ATTR.includes(attribute)) {
+        console.error(`Error: --from-attribute must be one of: ${ATTR.join(", ")}`); process.exit(1);
+      }
+      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) {
       try { windowDays = parseWindowDays(opts.window); }
@@ -140,6 +189,7 @@ export async function plan(orgId, opts = {}) {
       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); }
@@ -160,23 +210,58 @@ export async function plan(orgId, opts = {}) {
     process.exit(1);
   }
   if (resp.cohort) {
-    const w = resp.cohort.window_days ? `in the last ${resp.cohort.window_days} days` : "across all captured history";
-    if (resp.cohort.kind === "product") {
-      const verb = resp.cohort.min_purchases > 1 ? `bought ${resp.cohort.min_purchases}+ times` : "bought";
-      const join = resp.cohort.match === "all" ? "ALL of" : "any of";
-      console.log(`Cohort: ${verb} ${join} [${resp.cohort.product_terms.join(", ")}] ${w} → ${resp.cohort.resolved_count} contact(s) (server-resolved from order line-items).`);
+    if (resp.cohort.kind === "attribute") {
+      const label = {
+        all_contacts: "all contacts",
+        allow_broadcast_true: "broadcast-opted-in contacts",
+        allow_broadcast_false: "broadcast-opted-OUT contacts",
+        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 {
-      console.log(`Cohort: ${resp.cohort.min_orders}+ orders ${w} → ${resp.cohort.resolved_count} contact(s) (server-resolved from captured orders).`);
+      const w = resp.cohort.window_days ? `in the last ${resp.cohort.window_days} days` : "across all captured history";
+      if (resp.cohort.kind === "product") {
+        const verb = resp.cohort.min_purchases > 1 ? `bought ${resp.cohort.min_purchases}+ times` : "bought";
+        const join = resp.cohort.match === "all" ? "ALL of" : "any of";
+        console.log(`Cohort: ${verb} ${join} [${resp.cohort.product_terms.join(", ")}] ${w} → ${resp.cohort.resolved_count} contact(s) (server-resolved from order line-items).`);
+      } else {
+        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); }
+  if (splitMode && splitN > resp.safe_count) {
+    console.error(`Error: --split ${splitN} but only ${resp.safe_count} safe contact(s) — can't make that many cohorts.`); process.exit(1);
+  }
 
-  // Slice safe_ids into contiguous batches (client-side, per the spec split).
+  // --split makes exactly N EVEN cohorts and shuffles by default so the groups
+  // are balanced (not skewed by contact age / id order); --ordered keeps server
+  // order; --seed makes the shuffle reproducible. Without --split, slice into
+  // contiguous --batch-size chunks (the original behaviour).
   const batches = [];
-  for (let i = 0; i < resp.safe_ids.length; i += batchSize) {
-    const nn = String(batches.length + 1).padStart(2, "0");
-    batches.push({ tag: `${prefix}-batch-${nn}`, count: Math.min(batchSize, resp.safe_ids.length - i), contact_ids: resp.safe_ids.slice(i, i + batchSize) });
+  if (splitMode) {
+    const ids = opts.ordered ? resp.safe_ids.slice() : shuffle(resp.safe_ids.slice(), opts.seed);
+    const total = ids.length;
+    const base = Math.floor(total / splitN);
+    const rem = total % splitN;
+    let idx = 0;
+    for (let g = 0; g < splitN; g++) {
+      const size = base + (g < rem ? 1 : 0);
+      const nn = String(g + 1).padStart(2, "0");
+      batches.push({ tag: `${prefix}-batch-${nn}`, count: size, contact_ids: ids.slice(idx, idx + size) });
+      idx += size;
+    }
+    if (batches[0].count > 500) console.log(`⚠ each cohort is ~${batches[0].count} contacts — a single-cohort send is large (Meta tier risk); pace the sends.`);
+  } else {
+    for (let i = 0; i < resp.safe_ids.length; i += batchSize) {
+      const nn = String(batches.length + 1).padStart(2, "0");
+      batches.push({ tag: `${prefix}-batch-${nn}`, count: Math.min(batchSize, resp.safe_ids.length - i), contact_ids: resp.safe_ids.slice(i, i + batchSize) });
+    }
   }
 
   const slug = slugify(opts.segment || prefix, prefix);
@@ -186,7 +271,8 @@ export async function plan(orgId, opts = {}) {
     organization_id: resp.organization_id,
     organization_slug: slugify(resp.organization_name, resp.organization_id.slice(0, 8)),
     tag_prefix: prefix,
-    batch_size: batchSize,
+    batch_size: splitMode ? null : batchSize,
+    split: splitMode ? { cohorts: splitN, shuffled: !opts.ordered, seed: opts.seed ?? null } : null,
     created_at: new Date().toISOString(),
     source: cohort.sourceMeta,
     exclusions: {
@@ -206,7 +292,12 @@ export async function plan(orgId, opts = {}) {
   console.log(`Wrote ${planPath(slug)}`);
   console.log(`  org:      ${resp.organization_name}`);
   console.log(`  input:    ${resp.input_count} · safe: ${resp.safe_count} · excluded: ${ex.not_allow_broadcast + ex.archived + ex.blocked} (allow_broadcast ${ex.not_allow_broadcast}, archived ${ex.archived}, blocked ${ex.blocked}) · not_found ${ex.not_found_in_org} · dupes ${ex.duplicate_in_input}`);
-  console.log(`  batches:  ${batches.length} × ≤${batchSize}  (${batches[0].tag} … ${batches[batches.length - 1].tag})`);
+  if (splitMode) {
+    const how = opts.ordered ? "ordered" : (opts.seed != null ? `shuffled, seed ${opts.seed}` : "shuffled");
+    console.log(`  cohorts:  ${batches.length} even (${how}) — sizes ${batches.map((b) => b.count).join(" / ")}  (${batches[0].tag} … ${batches[batches.length - 1].tag})`);
+  } else {
+    console.log(`  batches:  ${batches.length} × ≤${batchSize}  (${batches[0].tag} … ${batches[batches.length - 1].tag})`);
+  }
   if (cohort.sourceMeta.generated_at) {
     console.log(`  ⚠ tagging point-in-time ids from ${cohort.sourceMeta.generated_at} — re-derive the cohort SQL if freshness matters.`);
   }

package/src/index.js

@@ -416,10 +416,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("Resolve a cohort (id list, order-count, or product-purchase criteria), apply broadcast-safety exclusions, slice into N-sized batch tags, write the plan (no DB write)")
+    .description("Resolve a cohort (id list, order-count, product-purchase, or broadcast-attribute), apply broadcast-safety exclusions, slice into fixed-size OR N even 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("--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")
@@ -427,6 +430,9 @@ export function run(argv) {
     .option("--window <span>", "with --min-orders/--bought: only count orders in this window, e.g. 60d / 8w / 3m (omit = all captured history)")
     .option("--platform <p>", "with --min-orders/--bought: auto | shopify | woo", "auto")
     .option("--batch-size <n>", "contacts per batch tag", "75")
+    .option("--split <n>", "split the safe cohort into exactly N even cohorts (alternative to --batch-size; shuffles by default for balanced groups)")
+    .option("--seed <n>", "with --split: reproducible shuffle seed (omit = random each run)")
+    .option("--ordered", "with --split: keep server order instead of shuffling (deterministic, but skews groups by contact age)")
     .option("--segment <name>", "plan file slug (default: the tag prefix)")
     .option("--include-unsafe", "do NOT exclude non-broadcast-safe contacts (rare; default excludes)")
     .action((orgId, opts) => segmentsCmd.plan(orgId, opts));