@flowapt/flowiq-cli 0.4.1 → 0.4.3

package/README.md

@@ -379,6 +379,12 @@ flowiq seg untag <org_id> repeat-60d --commit --confirm   # ROLLBACK (its own ta
   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.
+- **Large cohorts are chunked server-side** (fixed 3 Aug 2026): the tagging RPC
+  writes every batch inside one statement, so a ~90k apply used to hit the
+  database timeout and roll back with nothing written. Apply now splits into
+  calls of ≤8000 contacts. Safe to re-run at any size — if a chunk ever does
+  fail, the error names how many landed and a re-run finishes the job
+  (append-only ⇒ idempotent).
 - 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).
@@ -405,6 +411,9 @@ flowiq tag segment <org_id> --min-orders 2 --min-spent 1000 --region ZA-GP --tag
 
 # Attributes — broadcast permission (all_contacts / allow_broadcast_true|false / no_broadcast_permission)
 flowiq tag attributes <org_id> --filter allow_broadcast_true --tag broadcastable --commit
+# Big org (cohort > ~20k)? Chunk it: repeat this until it reports "matched 0" —
+# each run tags the next 10k untagged contacts (see the bullet below on the 50k cap / DB timeout)
+flowiq tag attributes <org_id> --filter allow_broadcast_true --limit 10000 --exclude broadcastable --tag broadcastable --commit --yes
 
 # Message activity — ≥ N messages of a sender type, optional date range
 flowiq tag messages <org_id> --min-count 3 --sender user-whatsapp --tag engaged --commit
@@ -422,6 +431,12 @@ flowiq tag remove <org_id> vip,old-promo --confirm  # remove tag(s) from ALL con
 - **`cohort` is top-N, not a threshold** — `top_spenders --limit 500` tags the
   top 500 by spend, not "everyone above £X". Use `tag segment --min-spent` for
   a threshold.
+- **Big orgs: chunk `attributes` commits with `--limit` + `--exclude <your-tag>`**
+  (flags added 3 Aug 2026, in-repo pending publish). The tagging RPC hard-caps at 50,000
+  per call AND a single large commit updates row-by-row, so a ~50k commit dies
+  on the DB statement timeout (full rollback, nothing written). `--limit 10000
+  --exclude <the-tag-you're-adding>` makes each run pick the next 10k untagged
+  matches — re-run until `matched 0`. Idempotent and safe to re-run.
 - **Undo** any tag with `flowiq tag remove <org> <tag> --confirm`.
 
 ### Keywords — `flowiq keywords pull|push|list` (alias `kw`)

package/TEAM-GUIDE.md

@@ -92,6 +92,7 @@ When you see it, run `npm i -g @flowapt/flowiq-cli` — a stale version also mea
 | 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` |
+| Split a whole tagged audience into batches of N (e.g. 90k → 7000s) | `flowiq seg plan <org_id> --tag-prefix 3-aug-bc --from-tag "3-aug-bc" --batch-size 7000` → `flowiq seg apply <org_id> 3-aug-bc --commit --yes` (makes `…-batch-01…13`; works at any size — big applies are chunked internally) |
 | Send to one batch tag | `flowiq bc send <org_id> --tag <batch-tag> --template … --body param1="Hi {{first_name}}" --commit` (per-contact tokens: the 6 contact fields + `{{attributes.<key>}}`) |
 | Send a broadcast whose template has an IMAGE/VIDEO/DOCUMENT header | Same as above — the media is automatic (the template's own stored header). Override with `--header-media <public-url>` if needed. The CLI verifies the resolved media's actual type against the header format — `header video (video ✓ video/mp4)` means verified; a mismatch (e.g. a video template whose stored default is secretly a png — templates made before 3 Aug 2026 can carry this) ABORTS and tells you to pass `--header-media` with the real file. |
 | Send via the SAME engine as the dashboard's "Python" toggle | add `--python` to a `bc send --tag …` (fire-and-forget; python resolves the tag + sends + tracks; no CLI resume for this engine). **Any tag send over 10 recipients uses python automatically.** |
@@ -179,6 +180,18 @@ real order line-items (accurate + windowable) rather than the order-history text
 And a commit over 2000 contacts asks you to type the tag name to confirm
 (add `--yes` to skip). Everything is appends-only and reversible with `tag remove`.
 
+**Tagging a very large audience (20k+, e.g. "everyone opted in") with `attributes`?**
+One giant commit will fail on a database timeout (nothing writes). Chunk it instead:
+
+```bash
+# repeat this exact line until it prints "matched 0" — each run tags the NEXT 10k
+flowiq tag attributes <org_id> --filter allow_broadcast_true \
+  --limit 10000 --exclude my-campaign-tag --tag my-campaign-tag --commit --yes
+```
+
+`--exclude` names the same tag you're adding, so every run skips the people who
+already have it. Safe to re-run as many times as you like.
+
 ## Keys, rotation, logging out
 
 - **`flowiq auth refresh`** — rotates this device's key in place (a fresh key

package/package.json

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

@@ -132,6 +132,7 @@ export async function attributes(orgId, opts = {}) {
   const payload = {
     mode: "attributes", organization_id: orgId, filter_type: opts.filter || "all_contacts",
     include_tags: splitList(opts.include), exclude_tags: splitList(opts.exclude),
+    limit: opts.limit ? Number(opts.limit) : undefined, offset: opts.offset ? Number(opts.offset) : 0,
   };
   await confirmLargeWrite(orgId, payload, opts, `Attributes ${payload.filter_type}`);
   await runMatch(`Attributes ${payload.filter_type}`, payload, opts);

package/src/index.js

@@ -550,6 +550,8 @@ export function run(argv) {
     .option("--filter <f>", "attribute filter", "all_contacts")
     .option("--include <csv>", "only contacts carrying any of these tags")
     .option("--exclude <csv>", "exclude contacts carrying any of these tags")
+    .option("--limit <n>", "max contacts per run (default 50000 — the RPC cap; a 50k commit can hit the DB statement timeout, so chunk big orgs: --limit 10000 --exclude <tag>, re-run until 0 match)")
+    .option("--offset <n>", "skip the first N", "0")
     .option("--tag <name>", "tag to apply (required with --commit)")
     .option("--commit", "write the tag (omit = dry-run count + sample)")
     .option("--yes", "skip the type-the-tag confirm on large (>2000) writes")