@flowapt/flowiq-cli 0.4.3 → 0.4.4

package/README.md

@@ -206,8 +206,34 @@ flowiq bc send <org_id> --template … --csv … --campaign july-referrals --com
 
 # 4) Interrupted? Continue only unsent rows:
 flowiq bc resume <org_id> --campaign july-referrals --commit [--retry-failed]
+
+# SCHEDULE a tag send for later instead of sending now (--at is SAST):
+flowiq bc send <org_id> --tag <batch-tag> --template <name> --body param1="…" \
+  --at "2026-08-05 09:00" --commit
+flowiq bc send … --at "2026-08-05 09:00" --needs-approval --commit  # park it for approval
+
+flowiq bc scheduled list <org_id>                   # open rows (pending + awaiting-approval)
+flowiq bc scheduled list <org_id> --all             # incl. fired / cancelled
+flowiq bc scheduled approve <org_id> <queue_id>     # 'request' → 'pending' (--at re-times it)
+flowiq bc scheduled cancel  <org_id> <queue_id> --confirm
 ```
 
+- **Scheduling (v0.4.4)** — `--at "YYYY-MM-DD HH:MM"` on a `--tag` send queues it
+  instead of sending. It writes the same `api_request_queue` row the dashboard
+  writes, replayed by the `process-api-queue` cron (every 3 min, so it fires
+  0–3 min after the stated minute). Runs **every** pre-send check first
+  (APPROVED, positional, param arithmetic, header-media type) — a scheduled
+  send can't skip a guard an immediate one enforces.
+  - `--at` is always read as **SAST**, never the machine's local timezone, so
+    the same command schedules the same instant from anywhere.
+  - The **audience resolves when it FIRES**, not when you schedule — someone
+    tagged tomorrow morning still receives a send scheduled today.
+  - Defaults to fire-by-itself. `--needs-approval` parks it until
+    `bc scheduled approve`. ⚠ **A parked row NEVER fires until approved** and
+    never errors — `scheduled list` flags those `AWAITING APPROVAL — will NOT
+    fire` (two dashboard-scheduled broadcasts silently missed their sends this
+    way). Cancel is dry-run unless you pass `--confirm`.
+
 - **Per-row values**: each template slot maps to a CSV **column**, a
   **literal**, or a **concat transform** (e.g. `Country Code` + `Phone`,
   leading-zero handled). The mapper auto-suggests from the template's
@@ -729,6 +755,84 @@ server-side (`auto_synthesized: true`; the response says
 broadcast mapping suggestions — pass your own only when you want real slot
 labels (e.g. `"body_params": {"1": "first_name", "2": "order_number"}`).
 
+### Store API (READ-ONLY) — `flowiq shopify get|gql` / `flowiq woo get`
+
+Write your own request against a client's **own** store API. You supply the
+endpoint (or the GraphQL query); the server resolves that org's credentials and
+makes the call. Credentials never reach your machine and are never printed.
+
+**Writes are refused, structurally:**
+
+* **REST** — the HTTP method is hardcoded `GET` and is never read from your
+  request. Every write in both APIs is POST/PUT/PATCH/DELETE, so "GET only" *is*
+  "read only". There is no endpoint allowlist to fall out of date, so any
+  endpoint — including ones Shopify or Woo ship tomorrow — works immediately.
+* **GraphQL** — the document is lexed (strings and `#` comments stripped) and
+  any `mutation` / `subscription` operation is rejected before the call is made.
+  Shopify exposes every Admin write as a mutation, so this rejects the whole
+  write surface. The word "mutation" inside a *string* or a *comment* is fine.
+
+```bash
+# Shopify REST — any Admin endpoint. The ".json" suffix is optional.
+flowiq shopify get <org_id> orders.json --q status=any --q limit=250
+flowiq shopify get <org_id> products --q limit=5 --q fields=id,title,status
+flowiq shopify get <org_id> inventory_levels.json --q location_ids=123 --all
+flowiq shopify get <org_id> orders/450789469.json          # a single record
+
+# Shopify GraphQL — you write the query. Inline, from a file, or on stdin.
+flowiq shopify gql <org_id> -q 'query { shop { name currencyCode } }'
+flowiq shopify gql <org_id> --query-file ./q.graphql --var n=50
+cat q.graphql | flowiq shopify gql <org_id>
+
+# WooCommerce REST — default namespace wc/v3.
+flowiq woo get <org_id> orders --q status=completed --q per_page=100 --all
+flowiq woo get <org_id> products/1234
+flowiq woo get <org_id> reports/sales --namespace wc/v3 --q period=month
+flowiq woo get <org_id> settings/general --namespace wc/v3
+```
+
+**Output contract — stdout is the payload and nothing else**, so it pipes
+straight into `jq`. The metadata banner (record count, pages, rate-limit
+headroom, timing) goes to **stderr**, so you still see it on your terminal:
+
+```bash
+flowiq shopify get <org_id> orders.json --q status=any --all | jq -r '.orders[].name'
+flowiq woo get <org_id> orders --all --out ./orders.json     # or write to a file
+flowiq shopify get <org_id> shop --json                      # full envelope incl. metadata
+```
+
+Flags:
+
+| Flag | Meaning |
+|---|---|
+| `--q <k=v>` | Query parameter, repeatable. A repeated key becomes a repeated parameter (`--q ids=1 --q ids=2`). Params go here, never in the path. |
+| `--all` | Follow pagination (Shopify's `Link: rel=next`; Woo's `page`) and return every record. |
+| `--max-pages <n>` | Page limit for `--all` (default 10, hard cap 50). |
+| `--namespace <ns>` | Woo REST namespace — default `wc/v3`; also `wc-analytics`, `wp/v2`. |
+| `--api-version <v>` | Shopify Admin API version (default `2024-01`). |
+| `-q, --query` / `--query-file` | The GraphQL document, inline or from a file (stdin also works). |
+| `--var <k=v>` | GraphQL variable, repeatable. JSON values are parsed (`--var ids='["1"]'`). |
+| `--json` | Print the full envelope (metadata + data) instead of just the payload. |
+| `--compact` | Single-line JSON. |
+| `--out <file>` | Write the JSON to a file instead of stdout. |
+
+Notes:
+
+* **`--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.
+* **Rate limits are surfaced, not hidden.** REST prints Shopify's
+  `api calls 3/40`; GraphQL prints the query cost and remaining points.
+* **GraphQL errors are surfaced.** Shopify returns field errors as HTTP 200 with
+  an `errors` array; the CLI prints them rather than letting you read
+  `data: null` as "no results".
+* **Orgs behind an IP whitelist / WAF** (`feature_flags.ip_whitelist`, e.g.
+  Hydroponic on Wordfence) reject calls from our servers. You get an explicit
+  message saying so, not an opaque 403.
+* Every call is written to the audit log (`flowiq audit <org>`) — who, which
+  org, which endpoint or query, how many records. **The response body is never
+  stored**; the log records what was asked, not the customer data that came back.
+
 ### Org — `flowiq org create` / `flowiq org info <organization_id>`
 
 Create a brand-new organization, or look one up (read-only; raw store/Meta
@@ -802,10 +906,22 @@ flowiq agent config <organization_id> --test-contact-number 27000000001 --test-c
 Settable: `settings.use_settings_prompt`, `settings.model`, agent `--rename`,
 the tool-flag columns (`woo_order_build`, `woo_tip_field`, `woo_order_note_field`,
 `view_cart_tool`, `restock_tool`, `block_tool_status`, `postal_code_tool_status`,
-`shopify_products_web_chat`, `ticket_tool_status`), `discount.enabled`, and the `flowiq test` contact
+`shopify_products_web_chat`, `ticket_tool_status`, `collapse_product_variants`),
+`discount.enabled`, and the `flowiq test` contact
 (`settings.test_contact_number` / `settings.test_contact_name`). Anything else is
 rejected; every change is reported before → after.
 
+**`--tool collapse_product_variants=true` (added 4 Aug 2026).** Not a tool toggle —
+it changes what `get_product_info` RETURNS. OFF (the default) the result cap counts
+**variant rows**, so on a catalogue with several packaging/size variants per product
+the agent sees only a handful of distinct products and will tell a customer an
+in-stock item "isn't showing". ON, the tool fetches `max*6` rows (cap 300) and
+collapses them to ≤`max` **distinct products**, listing each product's variants
+inline. Measured on African Oils: a 40-row response went from **15–24 distinct
+products to 40**, out of a 334-product catalogue. Costs ~50% more tokens per call.
+Requires ≤12 variants per product for the inline rendering branch — check with
+`SELECT max(c) FROM (SELECT count(*) c FROM products_all WHERE organization_id=… GROUP BY product_id) t`.
+
 **Test contact (`--test-contact-number` / `--test-contact-name`, v0.2.9).**
 This is the contact `flowiq test` drives the live agent through (read by
 `api/cli/agent-test.js` as `settings.test_contact_number`). ⚠ **Use a clearly

package/TEAM-GUIDE.md

@@ -80,8 +80,14 @@ When you see it, run `npm i -g @flowapt/flowiq-cli` — a stale version also mea
 | Edit keyword auto-replies (incl. competition entry keywords, add/remove-tag, set-agent and delay actions) | `flowiq kw pull <org_id>` → edit → `flowiq kw push <slug> --dry-run` → `flowiq kw push <slug>` |
 | Send a **different auto-reply depending on the contact** (e.g. "we already have your email" vs "send us your email") | add `"when": {"field":"email","op":"is_not_empty"}` to one action and `is_empty` to the other — see *Keywords* in `flowiq guide --reference`. CLI-only, no dashboard field yet |
 | Make a follow-up button **close the customer's ticket** ("Query solved") or **re-alert the team** ("I still need help") | keyword action `{"type":"update_ticket_status","status":"resolved"}` / `{"type":"renotify_ticket"}` — see *Keywords* in `flowiq guide --reference`. CLI-only, no dashboard field yet |
+| 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` |
+| Pull every matching record, not just the first page | add `--all` (bounded — it prints `⚠ TRUNCATED` if it stops early, so a partial answer never looks complete) |
+| Feed store data into jq / a file | stdout is the payload only, banner goes to stderr: `flowiq shopify get <org> orders.json \| jq -r '.orders[].name'` · or `--out ./orders.json` |
 | See an org's agents / create one | `flowiq agent list <org_id>` / `flowiq agent create <org_id> --name "…"` |
 | Change agent model / tool flags | `flowiq agent config <org_id> --model … --tool view_cart_tool=true` |
+| Agent says an in-stock product "isn't showing" | `flowiq agent config <org_id> --tool collapse_product_variants=true` — the search cap counts VARIANT rows until this is on |
 | Talk to the live agent safely (no real WhatsApp ever sent) | `flowiq test send <org_id> "hi, do you sell X?"` |
 | Set which contact `flowiq test` uses (use a FAKE number!) | `flowiq agent config <org_id> --test-contact-number 27000000001 --test-contact-name "QA Bot"` |
 | Send a template broadcast to a CSV of people | `flowiq bc map <org_id> --template … --csv …` → `flowiq bc send … ` (dry-run) → `… --commit` |
@@ -93,6 +99,8 @@ When you see it, run `npm i -g @flowapt/flowiq-cli` — a stale version also mea
 | 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) |
+| 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 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.** |
@@ -192,6 +200,75 @@ flowiq tag attributes <org_id> --filter allow_broadcast_true \
 `--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.
 
+### Scheduling a broadcast
+
+Add `--at` to a tag send and it queues instead of sending. The time is **South
+African time**, always — it does not matter where your laptop thinks it is.
+
+```bash
+flowiq bc send <org_id> --tag 5-aug-batch-01 --template my_template \
+  --body param1="Hi {{first_name}}" --at "2026-08-05 09:00" --commit
+```
+
+It fires on its own, so there is nothing more to do. Two things worth knowing:
+
+- **The audience is worked out when it fires, not now.** Anyone who picks up
+  that tag between now and then is included.
+- It goes out **within about 3 minutes** of the time you set, not to the second.
+
+Check on it, change your mind, or hand it to someone else to sign off:
+
+```bash
+flowiq bc scheduled list <org_id>                    # what's queued
+flowiq bc scheduled cancel <org_id> <queue_id> --confirm
+```
+
+If you'd rather someone approved it before it goes out, add `--needs-approval`
+when scheduling. **It then will not send until somebody runs
+`flowiq bc scheduled approve <org_id> <queue_id>`** — `scheduled list` marks it
+`AWAITING APPROVAL — will NOT fire` so it can't be forgotten. (Two broadcasts
+scheduled in the dashboard were missed exactly this way.)
+
+### Asking a client's store a question directly
+
+When you need something the dashboard doesn't show — "how many orders are still
+unfulfilled?", "what does this product's inventory actually look like per
+location?", "which orders used that discount code?" — you can ask the client's
+own store, in their own API, without a Shopify or Woo login.
+
+```bash
+# Shopify — any Admin REST endpoint. ".json" is optional.
+flowiq shopify get <org_id> orders.json --q status=any --q financial_status=paid --q limit=250
+
+# WooCommerce — same idea.
+flowiq woo get <org_id> orders --q status=processing --all
+```
+
+**You cannot break anything with this.** Reads are the only thing it can do:
+REST calls are locked to `GET`, and a GraphQL document containing a `mutation`
+is refused before it is sent. There is no "are you sure?" because there is
+nothing to be sure about.
+
+The answer comes back as JSON on stdout and a summary line on stderr, so it
+pipes into other tools cleanly:
+
+```bash
+flowiq shopify get <org_id> orders.json --q status=any --all | jq -r '.orders[].name'
+flowiq woo get <org_id> products --all --out ./products.json
+```
+
+Three things worth knowing:
+
+- **`--all` pages through everything**, but it stops at a sane limit and tells
+  you when it did (`⚠ TRUNCATED — stopped at --max-pages 10`). If you see that,
+  narrow the query rather than assuming you have the full set.
+- **If REST can't express your question, write GraphQL** —
+  `flowiq shopify gql <org_id> -q 'query { … }'` lets you pick exactly the
+  fields and nesting you want. Put a long query in a file and use
+  `--query-file`.
+- **Some stores sit behind a firewall** (Hydroponic's, for one) and will refuse
+  our call. You'll get a message saying exactly that.
+
 ## 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.3",
+  "version": "0.4.4",
   "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

@@ -864,6 +864,12 @@ async function runTagPipeline(orgId, opts, { commitStage }) {
   if (template.url_button?.present && !buttonLiteral) aborts.push("template has a dynamic URL button — pass --button param1=<code>");
   if (aborts.length) { for (const a of aborts) console.error(`ABORT — ${a}`); process.exit(1); }
 
+  // SCHEDULE (--at): validation above has already run, so a scheduled send is
+  // gated by exactly the same checks as an immediate one (APPROVED, positional,
+  // param arithmetic, header-media type). Instead of sending we queue the send
+  // for later; python resolves the tag at FIRE time, so the audience is fresh.
+  if (opts.at) return scheduleTagSend(orgId, { opts, tag, templateName, template, headerMedia, bodyLiterals, buttonLiteral, commitStage });
+
   // ENGINE ROUTING (policy): any send of MORE THAN 10 recipients ALWAYS uses the
   // python /meta-broadcast engine (the proven bulk sender). --python forces it at
   // any size; only a ≤10 send stays on the resumable per-row Node engine.
@@ -1002,6 +1008,145 @@ export async function map(orgId, opts = {}) {
   console.log(`Saved mapping: ${cfgPath(campaign)}`);
 }
 
+/** Parse a `--at` value as SOUTH AFRICAN time (SAST, UTC+2) and return an ISO string.
+ *  Accepts "YYYY-MM-DD HH:MM" / "YYYY-MM-DDTHH:MM" (SAST), or a value carrying its
+ *  own offset/Z (honoured as given). A bare local string is deliberately NOT handed
+ *  to `new Date()`: that interprets it in the RUNNER's timezone, so the same command
+ *  would schedule a different moment on a laptop in another country. */
+export function parseSastAt(input) {
+  const raw = String(input || "").trim();
+  if (!raw) return { error: "empty --at value" };
+  if (/(Z|[+-]\d{2}:?\d{2})$/.test(raw)) {
+    const d = new Date(raw);
+    return Number.isNaN(d.getTime()) ? { error: `not a valid timestamp: ${raw}` } : { iso: d.toISOString(), explicitOffset: true };
+  }
+  const m = raw.match(/^(\d{4})-(\d{2})-(\d{2})[T ](\d{2}):(\d{2})(?::(\d{2}))?$/);
+  if (!m) return { error: `use "YYYY-MM-DD HH:MM" (SAST), e.g. --at "2026-08-05 09:00" — got "${raw}"` };
+  const [, y, mo, d, h, mi, s] = m;
+  // Build the instant explicitly at +02:00 so the runner's TZ is irrelevant.
+  const iso = new Date(`${y}-${mo}-${d}T${h}:${mi}:${s || "00"}+02:00`);
+  if (Number.isNaN(iso.getTime())) return { error: `not a valid date/time: ${raw}` };
+  return { iso: iso.toISOString(), explicitOffset: false };
+}
+
+const fmtSast = (iso) =>
+  new Date(iso).toLocaleString("en-ZA", { timeZone: "Africa/Johannesburg", dateStyle: "medium", timeStyle: "short" });
+
+/** Queue a tag broadcast to fire later (server writes the api_request_queue row). */
+async function scheduleTagSend(orgId, { opts, tag, templateName, template, headerMedia, bodyLiterals, buttonLiteral, commitStage }) {
+  const when = parseSastAt(opts.at);
+  if (when.error) { console.error(`Error: --at ${when.error}`); process.exit(1); }
+  if (new Date(when.iso).getTime() <= Date.now()) {
+    console.error(`ABORT — --at is in the past (${fmtSast(when.iso)} SAST). Nothing would ever fire.`);
+    process.exit(1);
+  }
+  const needsApproval = !!opts.needsApproval;
+
+  console.log("");
+  renderPreview(template, { rownum: 1, number: "(resolved at send time)", values: bodyLiterals, buttonValue: buttonLiteral }, headerMedia);
+  if (Object.values(bodyLiterals).some((v) => /\{\{(first_name|full_name|email|phone_number|whatsapp_id)\}\}/.test(String(v)))) {
+    console.log("  ({{first_name}}-style tokens are resolved PER CONTACT at send time)");
+  }
+  console.log("");
+  console.log(`Schedule:    ${fmtSast(when.iso)} SAST${when.explicitOffset ? "" : "  (--at read as SAST)"}`);
+  console.log(`Audience:    tag "${tag}" — resolved when it FIRES, not now (so late joiners are included)`);
+  console.log(`Engine:      python /meta-broadcast`);
+  console.log(needsApproval
+    ? `Approval:    REQUIRED — parks as 'request'; run "flowiq bc scheduled approve" before it can fire`
+    : `Approval:    none — fires automatically at the scheduled time`);
+
+  if (!commitStage) {
+    console.log("");
+    console.log("DRY RUN — nothing was scheduled. Add --commit to queue it.");
+    return;
+  }
+
+  let resp;
+  try {
+    resp = await http.post("broadcast", {
+      action: "schedule",
+      organization_id: orgId,
+      tag,
+      template_name: templateName,
+      scheduled_for: when.iso,
+      needs_approval: needsApproval,
+      body_parameters: bodyLiterals,
+      ...(buttonLiteral ? { button_parameters: { param1: buttonLiteral } } : {}),
+      ...(headerMedia ? { header_media: headerMedia } : {}),
+    });
+  } catch (e) {
+    console.error(`Schedule failed: ${e.message}`);
+    if (e.body?.error) console.error(`  ${e.body.error}`);
+    process.exit(1);
+  }
+
+  console.log("");
+  console.log(`✓ Scheduled for ${fmtSast(resp.scheduled_for)} SAST — queue id ${resp.queue_id}`);
+  console.log(`  ~${resp.audience_at_schedule ?? "?"} contacts carry "${tag}" right now (re-counted at send time).`);
+  if (resp.fires_automatically) {
+    console.log(`  It will fire on its own. Cancel with: flowiq bc scheduled cancel ${orgId} ${resp.queue_id}`);
+  } else {
+    console.log(`  ⚠ PARKED awaiting approval — it will NOT fire until you run:`);
+    console.log(`      flowiq bc scheduled approve ${orgId} ${resp.queue_id}`);
+  }
+}
+
+/** List scheduled broadcasts (queue rows). Read-only. */
+export async function scheduledList(orgId, opts = {}) {
+  if (!UUID_RE.test(orgId)) { console.error(`Error: "${orgId}" is not a valid organization UUID.`); process.exit(1); }
+  let resp;
+  try {
+    resp = await http.post("broadcast", {
+      action: "scheduled-list",
+      organization_id: orgId,
+      status_filter: opts.all ? "all" : (opts.status || "open"),
+      limit: opts.limit,
+    });
+  } catch (e) { console.error(`Scheduled list failed: ${e.message}`); if (e.body?.error) console.error(`  ${e.body.error}`); process.exit(1); }
+  if (opts.json) { console.log(JSON.stringify(resp, null, 2)); return; }
+  if (!resp.scheduled?.length) { console.log(`No ${opts.all ? "" : "open "}scheduled broadcasts on ${resp.organization_name}.`); return; }
+  console.log(`Scheduled broadcasts on ${resp.organization_name}:`);
+  for (const s of resp.scheduled) {
+    const flag = s.stalled ? " ⚠ AWAITING APPROVAL — will NOT fire" : "";
+    console.log("");
+    console.log(`  ${s.id}`);
+    console.log(`    ${fmtSast(s.scheduled_for)} SAST · ${s.status}${flag}`);
+    console.log(`    template ${s.template_name ?? "?"} → tag ${s.tag ?? "?"} · ${s.engine} · via ${s.source}${s.scheduled_by ? ` (${s.scheduled_by})` : ""}`);
+    if (s.audience_at_schedule != null) console.log(`    ~${s.audience_at_schedule} recipients at schedule time`);
+    if (s.processed_at) console.log(`    fired ${fmtSast(s.processed_at)} SAST${s.broadcast_id ? ` · broadcastId ${s.broadcast_id}` : ""}`);
+    if (s.error_message) console.log(`    error: ${s.error_message}`);
+  }
+  console.log("");
+  console.log(`  ${resp.count} row(s). Approve: flowiq bc scheduled approve <org> <id> · Cancel: … cancel <org> <id>`);
+}
+
+/** Approve (request → pending) or cancel a scheduled broadcast. */
+export async function scheduledUpdate(orgId, queueId, op, opts = {}) {
+  if (!UUID_RE.test(orgId)) { console.error(`Error: "${orgId}" is not a valid organization UUID.`); process.exit(1); }
+  if (!UUID_RE.test(queueId || "")) { console.error(`Error: "${queueId}" is not a valid queue id (get it from: flowiq bc scheduled list <org>).`); process.exit(1); }
+  let at = null;
+  if (opts.at) {
+    const parsed = parseSastAt(opts.at);
+    if (parsed.error) { console.error(`Error: --at ${parsed.error}`); process.exit(1); }
+    at = parsed.iso;
+  }
+  if (op === "cancel" && !opts.confirm) {
+    console.log(`DRY RUN — would cancel scheduled broadcast ${queueId}. Add --confirm to cancel.`);
+    return;
+  }
+  let resp;
+  try {
+    resp = await http.post("broadcast", {
+      action: "scheduled-update", organization_id: orgId, queue_id: queueId, op, ...(at ? { scheduled_for: at } : {}),
+    });
+  } catch (e) { console.error(`${op} failed: ${e.message}`); if (e.body?.error) console.error(`  ${e.body.error}`); process.exit(1); }
+  if (op === "approve") {
+    console.log(`✓ Approved — ${queueId} is now '${resp.status}' and WILL fire at ${fmtSast(resp.scheduled_for)} SAST.`);
+  } else {
+    console.log(`✓ Cancelled — ${queueId} is now '${resp.status}' and will not fire.`);
+  }
+}
+
 export async function preview(orgId, opts = {}) {
   await runPipeline(orgId, opts, { commitStage: false, isResume: false });
 }

package/src/commands/store-api.js

@@ -0,0 +1,176 @@
+// `flowiq shopify` / `flowiq woo` — READ-ONLY passthrough to a client org's own
+// store API. You write the request; the server resolves the credentials and
+// refuses anything that isn't a read.
+//
+//   flowiq shopify get <org> orders.json --q status=any --q limit=250 --all
+//   flowiq shopify gql <org> -q 'query { shop { name currencyCode } }'
+//   flowiq woo get <org> orders --q status=completed --all
+//
+// OUTPUT CONTRACT (why this is jq-friendly by default):
+//   stdout = the API payload, and nothing else.
+//   stderr = the one-line metadata banner (pages, count, rate limit, timing).
+// So `flowiq shopify get <org> orders.json | jq '.orders[].name'` just works,
+// and the banner still shows up on your terminal. `--json` puts the FULL
+// envelope (metadata + data) on stdout instead, for when you want to keep it.
+
+import { writeFileSync } from "node:fs";
+import { readFileSync } from "node:fs";
+import { http } from "../http.js";
+
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+/**
+ * Repeatable `--q key=value`. A repeated key becomes an array, because several
+ * store filters are legitimately multi-valued (`--q ids=1 --q ids=2`).
+ */
+export function collectQuery(pair, acc) {
+  const idx = pair.indexOf("=");
+  if (idx < 1) throw new Error(`Expected key=value (got "${pair}")`);
+  const key = pair.slice(0, idx);
+  const value = pair.slice(idx + 1);
+  if (key in acc) {
+    acc[key] = Array.isArray(acc[key]) ? acc[key].concat(value) : [acc[key], value];
+  } else {
+    acc[key] = value;
+  }
+  return acc;
+}
+
+/** Repeatable `--var key=value` for GraphQL variables (JSON value if it parses). */
+export function collectVar(pair, acc) {
+  const idx = pair.indexOf("=");
+  if (idx < 1) throw new Error(`Expected key=value (got "${pair}")`);
+  const key = pair.slice(0, idx);
+  const raw = pair.slice(idx + 1);
+  try { acc[key] = JSON.parse(raw); } catch { acc[key] = raw; }
+  return acc;
+}
+
+function requireOrg(orgId) {
+  if (!UUID_RE.test(orgId || "")) {
+    console.error(`Error: "${orgId}" is not a valid organization UUID.`);
+    console.error("Find it with:  flowiq org info <organization_id>");
+    process.exit(1);
+  }
+}
+
+/** Read a query from --query-file, an inline flag, or piped stdin. */
+function resolveQueryText(opts) {
+  if (opts.queryFile) {
+    try {
+      return readFileSync(opts.queryFile, "utf8");
+    } catch (e) {
+      console.error(`Could not read --query-file ${opts.queryFile}: ${e.message}`);
+      process.exit(1);
+    }
+  }
+  if (opts.query) return opts.query;
+  if (!process.stdin.isTTY) {
+    try {
+      const piped = readFileSync(0, "utf8");
+      if (piped.trim()) return piped;
+    } catch { /* nothing piped */ }
+  }
+  console.error("Error: pass a query with -q/--query, --query-file <path>, or on stdin.");
+  console.error("Example:  flowiq shopify gql <org> -q 'query { shop { name } }'");
+  process.exit(1);
+}
+
+function banner(resp) {
+  const bits = [];
+  bits.push(`${resp.organization?.name ?? "?"} · ${resp.platform}${resp.mode === "graphql" ? " graphql" : ""}`);
+  if (resp.count != null) bits.push(`${resp.count} record${resp.count === 1 ? "" : "s"}`);
+  if (resp.pages > 1) bits.push(`${resp.pages} pages`);
+  if (resp.total_pages) bits.push(`of ${resp.total_pages} available`);
+  if (resp.rate_limit) bits.push(`api calls ${resp.rate_limit}`);
+  if (resp.cost?.throttleStatus) {
+    const t = resp.cost.throttleStatus;
+    bits.push(`cost ${resp.cost.actualQueryCost ?? "?"} · ${Math.round(t.currentlyAvailable)}/${t.maximumAvailable} left`);
+  }
+  if (resp.auth_mode === "query") bits.push("auth via query string (host stripped the header)");
+  bits.push(`${resp.duration_ms}ms`);
+  console.error(`→ ${bits.join(" · ")}`);
+
+  if (resp.truncated) {
+    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.");
+  }
+  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)) {
+      console.error(`    ${err.message}${err.path ? ` (at ${Array.isArray(err.path) ? err.path.join(".") : err.path})` : ""}`);
+    }
+  }
+}
+
+function emit(resp, opts) {
+  banner(resp);
+  const payload = opts.json ? resp : resp.data;
+  const text = JSON.stringify(payload, null, opts.compact ? 0 : 2);
+  if (opts.out) {
+    writeFileSync(opts.out, text);
+    console.error(`✓ wrote ${opts.out} (${text.length.toLocaleString()} chars)`);
+    return;
+  }
+  console.log(text);
+}
+
+async function send(payload, opts) {
+  let resp;
+  try {
+    resp = await http.post("store-api", payload);
+  } catch (e) {
+    console.error(`Request failed: ${e.message}`);
+    if (e.body?.upstream_status) console.error(`  upstream HTTP ${e.body.upstream_status}`);
+    process.exit(1);
+  }
+  emit(resp, opts);
+}
+
+// ---------------------------------------------------------------------------
+// shopify
+// ---------------------------------------------------------------------------
+
+export async function shopifyGet(orgId, path, opts = {}) {
+  requireOrg(orgId);
+  await send({
+    platform: "shopify",
+    organization_id: orgId,
+    mode: "rest",
+    path,
+    query: opts.q || {},
+    all: !!opts.all,
+    max_pages: opts.maxPages ? Number(opts.maxPages) : undefined,
+    api_version: opts.apiVersion,
+  }, opts);
+}
+
+export async function shopifyGql(orgId, opts = {}) {
+  requireOrg(orgId);
+  const query = resolveQueryText(opts);
+  await send({
+    platform: "shopify",
+    organization_id: orgId,
+    mode: "graphql",
+    graphql: { query, variables: opts.var && Object.keys(opts.var).length ? opts.var : undefined },
+    api_version: opts.apiVersion,
+  }, opts);
+}
+
+// ---------------------------------------------------------------------------
+// woo
+// ---------------------------------------------------------------------------
+
+export async function wooGet(orgId, path, opts = {}) {
+  requireOrg(orgId);
+  await send({
+    platform: "woo",
+    organization_id: orgId,
+    mode: "rest",
+    path,
+    namespace: opts.namespace,
+    query: opts.q || {},
+    all: !!opts.all,
+    max_pages: opts.maxPages ? Number(opts.maxPages) : undefined,
+  }, opts);
+}

package/src/index.js

@@ -30,6 +30,7 @@ import * as tagCmd from "./commands/tag.js";
 import * as keywordsCmd from "./commands/keywords.js";
 import * as guideCmd from "./commands/guide.js";
 import * as auditCmd from "./commands/audit.js";
+import * as storeApiCmd from "./commands/store-api.js";
 import { maybeNotifyUpdate } from "./update-check.js";
 
 // Read version from package.json so it stays in sync with the published npm
@@ -241,7 +242,7 @@ export function run(argv) {
     .option("--use-settings-prompt [bool]", "settings.use_settings_prompt (true if bare)")
     .option("--model <model>", "settings.model (e.g. gpt-5.4-mini)")
     .option("--rename <name>", "rename the agent")
-    .option("--tool <flag=bool>", "toggle a tool flag (repeatable): woo_order_build/woo_tip_field/woo_order_note_field/view_cart_tool/restock_tool/block_tool_status/postal_code_tool_status/shopify_products_web_chat", agentConfigCmd.collectTool, [])
+    .option("--tool <flag=bool>", "toggle a tool flag (repeatable): woo_order_build/woo_tip_field/woo_order_note_field/view_cart_tool/restock_tool/block_tool_status/postal_code_tool_status/shopify_products_web_chat/ticket_tool_status/collapse_product_variants", agentConfigCmd.collectTool, [])
     .option("--discount [bool]", "agent.discount.enabled (true if bare)")
     .option("--test-contact-number <number>", "settings.test_contact_number — the contact `flowiq test` uses (use a FAKE number; \"\" clears it → synthetic fallback)")
     .option("--test-contact-name <name>", "settings.test_contact_name — display name for the test contact (\"\" clears it)")
@@ -426,6 +427,8 @@ export function run(argv) {
     .option("--campaign <name>", "campaign id / config file slug (default: CSV filename / tag)")
     .option("--header-media <url>", "header image/video/doc URL for a media-header template (default: the template's own stored image)")
     .option("--python", "with --tag: force the python /meta-broadcast engine (same as the dashboard's Python toggle). NOTE: any tag send >10 recipients ALWAYS uses python automatically")
+    .option("--at <when>", "with --tag: SCHEDULE instead of sending now — \"YYYY-MM-DD HH:MM\" in SAST (e.g. --at \"2026-08-05 09:00\"). Fires automatically; audience is resolved at send time")
+    .option("--needs-approval", "with --at: park it awaiting approval (flowiq bc scheduled approve) instead of firing automatically")
     .option("--commit", "actually send (omit to dry-run)")
     .option("--yes", "skip the type-the-campaign-name confirm gate (CI)")
     .option("--force-remap", "ignore the saved mapping and rebuild interactively")
@@ -445,6 +448,24 @@ export function run(argv) {
     .option("--rate <n>", "max messages per second (hard cap 10)", "8")
     .option("--retry-failed", "also re-attempt rows previously marked failed (confirmed failures only)")
     .action((orgId, opts) => broadcastCmd.resume(orgId, opts));
+  const scheduled = broadcast.command("scheduled")
+    .description("Scheduled broadcasts (queue rows): list / approve / cancel");
+  scheduled.command("list <organization_id>")
+    .description("List scheduled broadcasts. Default: only OPEN rows (pending + awaiting-approval)")
+    .option("--all", "include fired / cancelled / failed rows too")
+    .option("--status <s>", "filter to one status (pending|request|completed|cancelled|failed)")
+    .option("--limit <n>", "max rows (default 25, max 200)")
+    .option("--json", "raw JSON")
+    .action((orgId, opts) => broadcastCmd.scheduledList(orgId, opts));
+  scheduled.command("approve <organization_id> <queue_id>")
+    .description("Approve a parked ('request') scheduled broadcast so it will fire")
+    .option("--at <when>", "also re-time it — \"YYYY-MM-DD HH:MM\" SAST")
+    .action((orgId, queueId, opts) => broadcastCmd.scheduledUpdate(orgId, queueId, "approve", opts));
+  scheduled.command("cancel <organization_id> <queue_id>")
+    .description("Cancel a scheduled broadcast so it never fires (dry-run unless --confirm)")
+    .option("--confirm", "actually cancel")
+    .action((orgId, queueId, opts) => broadcastCmd.scheduledUpdate(orgId, queueId, "cancel", opts));
+
   broadcast.command("list-remote <organization_id>")
     .description("List the org's broadcasts newest-first (full broadcastId + template + status + recipients) — the discovery step for `bc status` / `bc retry`")
     .option("--limit <n>", "how many to show (default 25, max 200)")
@@ -594,6 +615,45 @@ export function run(argv) {
     .description("List local keyword snapshots")
     .action(() => keywordsCmd.list());
 
+  // shopify / woo — READ-ONLY passthrough to the client's own store API.
+  // You write the request; creds are resolved server-side and never displayed.
+  // stdout is the payload (pipe it to jq); the metadata banner goes to stderr.
+  const shopify = program.command("shopify")
+    .description("Read-only passthrough to an org's Shopify Admin API (REST + GraphQL). Writes are refused.");
+  shopify.command("get <organization_id> <path>")
+    .description('GET any Shopify Admin REST endpoint, e.g. `get <org> orders.json --q status=any` (".json" optional)')
+    .option("--q <k=v>", "query parameter (repeatable), e.g. --q status=any --q limit=250", storeApiCmd.collectQuery, {})
+    .option("--all", "follow Link rel=next and return every page (bounded by --max-pages and a size/time cap)")
+    .option("--max-pages <n>", "page limit when using --all (default 10, cap 50)")
+    .option("--api-version <ver>", "Shopify Admin API version (default 2024-01)")
+    .option("--json", "print the full envelope (metadata + data) instead of just the payload")
+    .option("--compact", "single-line JSON")
+    .option("--out <file>", "write the JSON to a file instead of stdout")
+    .action((orgId, path, opts) => storeApiCmd.shopifyGet(orgId, path, opts));
+  shopify.command("gql <organization_id>")
+    .description("Run a Shopify Admin GraphQL QUERY (you write it). Any document containing a mutation is refused.")
+    .option("-q, --query <graphql>", "the query document, inline")
+    .option("--query-file <path>", "read the query document from a file")
+    .option("--var <k=v>", "GraphQL variable (repeatable; JSON values parsed)", storeApiCmd.collectVar, {})
+    .option("--api-version <ver>", "Shopify Admin API version (default 2024-01)")
+    .option("--json", "print the full envelope (metadata + data) instead of just the payload")
+    .option("--compact", "single-line JSON")
+    .option("--out <file>", "write the JSON to a file instead of stdout")
+    .action((orgId, opts) => storeApiCmd.shopifyGql(orgId, opts));
+
+  const woo = program.command("woo")
+    .description("Read-only passthrough to an org's WooCommerce REST API. Writes are refused.");
+  woo.command("get <organization_id> <path>")
+    .description("GET any WooCommerce REST endpoint, e.g. `get <org> orders --q status=completed`")
+    .option("--q <k=v>", "query parameter (repeatable), e.g. --q status=completed --q per_page=100", storeApiCmd.collectQuery, {})
+    .option("--namespace <ns>", "REST namespace (default wc/v3; also wc-analytics, wp/v2)")
+    .option("--all", "page through every result (bounded by --max-pages and a size/time cap)")
+    .option("--max-pages <n>", "page limit when using --all (default 10, cap 50)")
+    .option("--json", "print the full envelope (metadata + data) instead of just the payload")
+    .option("--compact", "single-line JSON")
+    .option("--out <file>", "write the JSON to a file instead of stdout")
+    .action((orgId, path, opts) => storeApiCmd.wooGet(orgId, path, opts));
+
   // guide (bundled docs — always match the installed version)
   program.command("guide")
     .description("Read the team guide (how we use this CLI); --reference for the full command reference")