@flowapt/flowiq-cli 0.4.5 → 0.4.7

package/README.md

@@ -84,6 +84,11 @@ Notes:
   push using the `## SECTION: <title>` format.
 - Sections support optional `hidden: boolean` + `channels: string[]`
   (`web` / `whatsapp` / `messenger` / `instagram`) — validated on push.
+- **Time-boxed sections:** optional `active_from` / `active_until`
+  (`"YYYY-MM-DD"` or `"YYYY-MM-DDTHH:mm"`) + `active_tz` (IANA, default
+  `Africa/Johannesburg`). Outside the window the section is skipped at
+  prompt assembly server-side — an expired promo needs NO cleanup push.
+  Validated on push (format, from ≤ until, real timezone).
 - For legacy agents without a sections array, pull auto-bootstraps a
   single "Main" section from `settings.system_prompt` and returns
   `bootstrapped: true`. The CLI prints a heads-up before push.
@@ -256,6 +261,16 @@ flowiq bc scheduled cancel  <org_id> <queue_id> --confirm
     the abort message says so — fix by passing `--header-media <real video>`.
     `map` refuses to save a mismatched default into the campaign file. An
     unreachable URL only warns (`media unverified`), never blocks.
+- **One campaign = one template (v0.4.6).** A campaign's saved mapping, header
+  media and write-ahead status log (dedup) all belong to the template it was
+  built for. Running `bc send` / `map` with a **different `--template` on an
+  existing `--campaign`** now **ABORTS** (`Campaign "X" was built for template
+  A …`) — reusing the slug would silently send A's header media and skip the
+  recipients A already reached (the header-media check only catches a media-TYPE
+  change, not a same-type creative swap). Use a fresh `--campaign` for a new
+  template. In **tag mode the campaign slug defaults to the tag**, so to send
+  template A then template B to the SAME tag, pass a distinct `--campaign` for
+  each. `resume` passes no `--template`, so it is never affected.
 - **`list-remote <org>` (v0.3.9)**: list the org's broadcasts **newest-first** with
   the **full broadcastId** per row + template, status, recipient count and SAST
   created time — the discovery step `status` / `retry` need (previously the id
@@ -853,8 +868,36 @@ Looking up stock for "1 litre Oil Pourer" — the calls being made:
 `stock` prints **"not tracked"** where Shopify returns `available: null` — that
 means no inventory record exists at that location, which is not the same as zero.
 
+#### Counting things — read `precision` before you trust a number
+
+Shopify's `*Count` fields return `{count, precision}`. **`precision: "AT_LEAST"`
+means the number is a CAP (10,000), not an answer.** The CLI now warns on stderr
+whenever a capped count comes back, because it is very easy to read 10,000 as a
+real total.
+
+**`customersCount` additionally IGNORES its `query:` filter.** Verified 4 Aug 2026
+straight against Shopify with no FlowIQ layer involved, on API versions 2024-01,
+2024-10 and 2025-01: an impossible email filter still returns `10000 / AT_LEAST`.
+Its sibling `ordersCount` honours the same argument and returns
+`1372 / EXACT`, so this is specific to that field, not a general limit. **This is
+Shopify's behaviour, not the CLI's** — but sizing an audience with it gives you a
+plausible, wrong number, so the CLI calls it out.
+
+Count a filtered customer cohort with the connection instead, which filters
+correctly, and paginate:
+
+```bash
+flowiq shopify gql <org> -q 'query { customers(first: 250, query: "orders_count:>=20") {
+  edges { node { id } } pageInfo { hasNextPage endCursor } } }'
+```
+
 Notes:
 
+* **A long `--all` can TIME OUT rather than truncate.** The server budgets ~25s and
+  then returns a partial result, but a very wide pull can still exceed the function
+  limit. You now get an explicit timeout message naming the remedy (retry, fewer
+  `--max-pages`, a smaller `--q limit`) — previously this surfaced as
+  `Request failed: [object Object]`, which read like a hard limit and wasn't.
 * **`--all` is bounded and says so.** It stops at `--max-pages`, at a ~3.5MB
   response size, or at a time budget, and then reports `⚠ TRUNCATED — <reason>`
   on stderr. A partial result is never presented as a complete one.

package/TEAM-GUIDE.md

@@ -83,6 +83,8 @@ When you see it, run `npm i -g @flowapt/flowiq-cli` — a stale version also mea
 | **Find an org's ID** (needed by nearly every command) | `flowiq org list` — or `flowiq org list african` to filter |
 | What's the stock on a product, per branch? | `flowiq shopify stock <org_id> "olive oil"` — shows each location by NAME, and says "not tracked" rather than a confusing 0 |
 | Has this order shipped? What's the tracking? | `flowiq shopify order <org_id> '#14728'` — status, courier, tracking number + link |
+| **Size a customer cohort** | Use `customers(first:250, query:…)` and paginate — **NOT `customersCount(query:…)`, which Shopify ignores the filter on** and answers 10,000 every time. Any count showing `precision: AT_LEAST` is a cap, not a total; the CLI warns you. |
+| A big `--all` failed with a timeout | It's transient, not a limit — retry, or narrow it with `--max-pages` / a smaller `--q limit`. The message now says so. |
 | Ask a client's Shopify store anything (read-only) | `flowiq shopify get <org_id> orders.json --q status=any --q limit=250` — any Admin REST endpoint; writes are refused |
 | Ask a client's Shopify store something REST can't express | `flowiq shopify gql <org_id> -q 'query { shop { name } }'` — you write the GraphQL; any `mutation` is refused |
 | Ask a client's WooCommerce store anything (read-only) | `flowiq woo get <org_id> orders --q status=completed --all` |
@@ -104,7 +106,7 @@ When you see it, run `npm i -g @flowapt/flowiq-cli` — a stale version also mea
 | 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) |
 | Schedule a broadcast for later instead of sending now | `flowiq bc send <org_id> --tag <batch-tag> --template <name> --at "2026-08-05 09:00" --commit` (time is SAST; fires on its own; audience resolved at send time) |
 | See / approve / cancel what's scheduled | `flowiq bc scheduled list <org_id>` → `flowiq bc scheduled approve <org_id> <queue_id>` or `flowiq bc scheduled cancel <org_id> <queue_id> --confirm` |
-| 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 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>}}`). Sending a **different template to the SAME tag**? Add a distinct `--campaign <name>` — otherwise the CLI aborts (a campaign belongs to one template; reusing it would send the first template's image + skip everyone it already reached). |
 | 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.** |
 | Find a broadcast's id (don't have the `broadcastId`?) | `flowiq bc list-remote <org_id>` — the org's broadcasts newest-first with full ids (`--template <substr>` / `--since <date>` / `--limit <n>` to narrow) |
@@ -141,6 +143,12 @@ flowiq prompts push phytoceutics
 flowiq test send 08becb51-… "question that exercises your change"
 ```
 
+**Scheduling a promo section:** add `"active_from": "2026-08-07"`,
+`"active_until": "2026-08-10"` (and optionally `"active_tz": "Europe/Lisbon"`,
+default is SAST) to a section in the JSON and push. The AI only sees the
+section inside that window — when the promo ends it disappears by itself,
+no cleanup push needed. Date-only values mean start-of-day / end-of-day.
+
 ### Example: safely change custom tools
 
 ```bash

package/package.json

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

@@ -563,6 +563,13 @@ async function runPipeline(orgId, opts, { commitStage, isResume }) {
   let cfg = await loadCampaign(campaign);
   const templateName = opts.template || cfg?.template_name;
   if (!templateName) { console.error("Error: --template required (or an existing campaign config)."); process.exit(1); }
+  // Same guard as runTagPipeline: a campaign's saved mapping, header media and status-log
+  // dedup all belong to the template it was built for. A different --template on the same
+  // --campaign must use a fresh slug, not silently inherit them. (resume passes no --template.)
+  if (cfg && opts.template && cfg.template_name && cfg.template_name !== opts.template) {
+    console.error(`Campaign "${campaign}" was built for template ${cfg.template_name}, but --template ${opts.template} was passed — reusing it would inherit that mapping/header media and skip contacts it already reached. Use a different --campaign for ${opts.template}.`);
+    process.exit(1);
+  }
   const csvPath = opts.csv || cfg?.csv?.path;
   if (!csvPath) { console.error("Error: --csv required (or an existing campaign config)."); process.exit(1); }
 
@@ -837,6 +844,16 @@ async function runTagPipeline(orgId, opts, { commitStage }) {
   const tag = opts.tag || cfg?.tag;
   const templateName = opts.template || cfg?.template_name;
   if (!tag || !templateName) { console.error("Error: --tag and --template required (or an existing tag campaign config)."); process.exit(1); }
+  // A tag campaign owns a status log (dedup) and any saved header media, BOTH tied to the
+  // template it was built for. Reusing this --campaign slug with a different --template would
+  // silently send the old template's header media and skip the recipients it already reached
+  // — and the header-media check only catches a media-TYPE change (image→video), not a
+  // same-type creative swap. A new template needs its own --campaign. (resume passes no
+  // --template, so opts.template is undefined there and this never fires.)
+  if (cfg && opts.template && cfg.template_name && cfg.template_name !== opts.template) {
+    console.error(`Campaign "${campaign}" was built for template ${cfg.template_name}, but --template ${opts.template} was passed — reusing it would send ${cfg.template_name}'s header media and skip contacts it already reached. Use a different --campaign for ${opts.template}.`);
+    process.exit(1);
+  }
   const bodyLiterals = Object.keys(opts.body || {}).length ? opts.body : (cfg?.body_params_literal ?? {});
   const buttonLiteral = (opts.button && opts.button.param1) ?? cfg?.button_param_literal ?? null;
 

package/src/commands/store-api.js

@@ -76,6 +76,20 @@ function resolveQueryText(opts) {
   process.exit(1);
 }
 
+/** Field names in a GraphQL result whose `precision` says the count is a cap. */
+function findCapped(node, path = [], hits = []) {
+  if (!node || typeof node !== "object") return hits;
+  if (Array.isArray(node)) {
+    for (const v of node) findCapped(v, path, hits);
+    return hits;
+  }
+  if (node.precision === "AT_LEAST" && typeof node.count === "number") {
+    hits.push(`${path[path.length - 1] || "count"} (${node.count.toLocaleString()})`);
+  }
+  for (const [k, v] of Object.entries(node)) findCapped(v, [...path, k], hits);
+  return hits;
+}
+
 function banner(resp) {
   const bits = [];
   bits.push(`${resp.organization?.name ?? "?"} · ${resp.platform}${resp.mode === "graphql" ? " graphql" : ""}`);
@@ -95,6 +109,23 @@ function banner(resp) {
     console.error(`⚠ TRUNCATED — ${resp.truncated_reason}. Not all records were returned.`);
     console.error("  Narrow the query, or raise --max-pages and page through with the store's own cursor.");
   }
+  // Shopify's *Count fields return {count, precision}. `AT_LEAST` means the
+  // number is a CAP (10,000), not an answer — and it is quiet enough to be read
+  // as a real total. Worse, `customersCount` IGNORES its `query:` argument
+  // entirely (verified 4 Aug 2026 straight against Shopify on api 2024-01,
+  // 2024-10 and 2025-01: an impossible email filter still returns 10000), so a
+  // filtered cohort size comes back looking plausible and is wrong. Its sibling
+  // `ordersCount` honours the same argument and returns EXACT, so this is
+  // field-specific, not a general count-field limit.
+  const capped = findCapped(resp.data);
+  if (capped.length) {
+    console.error(`⚠ ${capped.join(", ")} returned precision "AT_LEAST" — that is a CAP, not a count.`);
+    console.error(`  The real number is at least that; never size an audience from it.`);
+  }
+  if (/customersCount\s*\(/.test(resp.__query || "") && /\bquery\s*:/.test(resp.__query || "")) {
+    console.error(`⚠ customersCount IGNORES its query: filter — Shopify returns the same capped number`);
+    console.error(`  whether you filter or not. Count with customers(first:N, query:…) and paginate instead.`);
+  }
   if (resp.graphql_errors?.length) {
     console.error(`⚠ GraphQL returned ${resp.graphql_errors.length} error(s):`);
     for (const err of resp.graphql_errors.slice(0, 5)) {
@@ -165,7 +196,7 @@ function emit(resp, opts) {
   console.log(text);
 }
 
-async function send(payload, opts) {
+async function send(payload, opts, sentQuery) {
   let resp;
   try {
     resp = await http.post("store-api", payload);
@@ -174,6 +205,7 @@ async function send(payload, opts) {
     if (e.body?.upstream_status) console.error(`  upstream HTTP ${e.body.upstream_status}`);
     process.exit(1);
   }
+  if (sentQuery) Object.defineProperty(resp, "__query", { value: sentQuery, enumerable: false });
   emit(resp, opts);
 }
 
@@ -204,7 +236,7 @@ export async function shopifyGql(orgId, opts = {}) {
     mode: "graphql",
     graphql: { query, variables: opts.var && Object.keys(opts.var).length ? opts.var : undefined },
     api_version: opts.apiVersion,
-  }, opts);
+  }, opts, query);
 }
 
 // ---------------------------------------------------------------------------

package/src/http.js

@@ -17,6 +17,55 @@ try {
   CLI_VERSION = JSON.parse(readFileSync(path.join(dir, "..", "package.json"), "utf8")).version || "unknown";
 } catch { /* version is a nice-to-have; never block a request on it */ }
 
+/**
+ * Turn an error body into a STRING a human can act on.
+ *
+ * Our own endpoints answer `{error, message}` with string values, but the
+ * hosting platform does not: a killed or crashed function replies
+ * `{"error":{"code":"FUNCTION_INVOCATION_TIMEOUT","message":"…"}}`. The old code
+ * did `new Error(parsed.message || parsed.error)`, and `new Error(someObject)`
+ * stringifies to the useless **"[object Object]"** — which is exactly what a
+ * long `--all` run reported, hiding a plain timeout behind a message that looked
+ * like a bug in the CLI. Reported 4 Aug 2026 after it cost three runs to
+ * diagnose.
+ *
+ * So: prefer a string message, then a nested code/message, then the whole body
+ * serialised — and always name the HTTP status, since a 504 tells you "retry or
+ * narrow it" while a 400 never will.
+ */
+export function describeError(parsed, method, endpoint, status) {
+  const pick = (v) => (typeof v === "string" && v.trim() ? v.trim() : null);
+  const nested = (v) => {
+    if (!v || typeof v !== "object") return null;
+    const msg = pick(v.message) || pick(v.error) || pick(v.reason);
+    const code = pick(v.code) || pick(v.type);
+    if (msg && code) return `${msg} (${code})`;
+    return msg || code || null;
+  };
+
+  let detail =
+    pick(parsed?.message) ||
+    pick(parsed?.error) ||
+    nested(parsed?.error) ||
+    nested(parsed) ||
+    pick(parsed?._raw);
+
+  if (!detail && parsed && typeof parsed === "object" && Object.keys(parsed).length) {
+    try { detail = JSON.stringify(parsed).slice(0, 400); } catch { /* fall through */ }
+  }
+
+  const where = `${method} ${endpoint} → HTTP ${status}`;
+  if (!detail) return where;
+
+  // A timeout is transient and the remedy is specific, so say so rather than
+  // leaving the reader to work out whether they hit a hard limit.
+  const timedOut = status === 504 || /TIMEOUT|timed out/i.test(detail);
+  return timedOut
+    ? `${detail} [${where}] — this is a TIMEOUT, not a limit: retry, or narrow the request ` +
+      `(fewer pages via --max-pages, a smaller --q limit, or a tighter filter).`
+    : `${detail} [${where}]`;
+}
+
 async function call(method, endpoint, { query, body } = {}) {
   const cfg = await loadConfig();
   if (!cfg.token) {
@@ -52,9 +101,7 @@ async function call(method, endpoint, { query, body } = {}) {
   let parsed, isJson = true;
   try { parsed = text ? JSON.parse(text) : {}; } catch { parsed = { _raw: text }; isJson = false; }
   if (!resp.ok) {
-    const err = new Error(
-      parsed.message || parsed.error || `${method} ${endpoint} → HTTP ${resp.status}`
-    );
+    const err = new Error(describeError(parsed, method, endpoint, resp.status));
     err.status = resp.status;
     err.body = parsed;
     throw err;