@flowapt/flowiq-cli 0.4.3 → 0.4.5

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
@@ -552,6 +578,18 @@ flowiq audit show <audit_id> --out entry.json       # dump the whole entry
 Filters: `--endpoint --action --status --agent --target --user --since --until
 --limit` (default 50, max 200) `--json`.
 
+**What gets logged.** Every command that CHANGES something writes a row —
+including two that were missed until 4 Aug 2026 and are now covered:
+`flowiq test` (it creates the test contact, can re-enable a contact's bot, and
+clears the conversation) and `flowiq auth refresh` (it mints a new key and
+revokes the old one). Reads and dry-runs deliberately write nothing.
+
+**What is never logged:** the content itself. `messages` / `export chats` /
+`shopify` / `woo` record *who read what*, never a copy of the conversation or
+the store data. `flowiq test` records the prompt you sent, the tools the agent
+called and how long its reply was — not the reply. `auth refresh` records key
+ids and prefixes — never a key.
+
 **What's captured, and how much:**
 
 | Surface | Action | Content stored |
@@ -729,6 +767,109 @@ 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. |
+| `--table` | Render the returned list as a table instead of JSON. A rendering only — same data, nothing reshaped or filtered. |
+| `--out <file>` | Write the JSON to a file instead of stdout. |
+
+#### Two recipes — composed of the SAME calls, and they print them
+
+Some questions take 3-4 chained calls and a manual id-join (stock needs
+product → `inventory_item_id` → `inventory_levels` → `locations`). These two do
+that chaining for you — and **echo every raw call they make as a runnable
+command**, so the API stays the interface and you can take those lines further
+than the recipe goes. Nothing here is expressible only through the recipe.
+
+```bash
+flowiq shopify stock <org> "olive oil"     # stock per LOCATION NAME, per variant
+flowiq shopify order <org> '#14728'        # order + fulfilments + tracking url
+flowiq shopify stock <org> "olive oil" --raw   # the underlying JSON instead
+```
+
+```
+Looking up stock for "1 litre Oil Pourer" — the calls being made:
+  $ flowiq shopify get <org> products.json --q title="1 litre Oil Pourer" --q limit=50
+  $ flowiq shopify get <org> inventory_levels.json --q inventory_item_ids=45186940764314
+  $ flowiq shopify get <org> locations.json --q fields=id,name
+```
+
+`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.
+
+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
@@ -740,6 +881,10 @@ flowiq org create --name "New Client" [--slug new-client] [--owner client@email.
 #   person to already have an account (otherwise invite them later in the app).
 #   Provider defaults to meta. Prints the new org id + the next-step commands.
 
+flowiq org list                        # every org + its UUID (the lookup everything else needs)
+flowiq org list african                 # filter by name or slug
+flowiq org list --all                   # include inactive orgs
+
 flowiq org info <organization_id>       # platform, storefront url, active agent
 ```
 
@@ -802,10 +947,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,17 @@ 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 |
+| **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 |
+| 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 +102,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.** |
@@ -103,6 +114,7 @@ When you see it, run `npm i -g @flowapt/flowiq-cli` — a stale version also mea
 | **Get an OLD version of a prompt back** | `flowiq prompts history <org_id>` (pick the version) → `flowiq prompts restore <org_id> <audit_id>` (dry-run) → `… --commit` |
 | **See who changed what, and when** | `flowiq audit <org_id>` — add `--endpoint prompts`, `--user <name>`, `--since 2026-07-01` to narrow |
 | See exactly what a change looked like (before → after) | `flowiq audit show <audit_id> --content` (or `--out entry.json`) |
+| Know what the log does and doesn't keep | Anything that CHANGES something is logged — including `flowiq test` (it creates the test contact and clears conversations) and `flowiq auth refresh`. Reads and dry-runs are not. The log never stores the content itself: chats, store data and agent replies are recorded as "who read what", never copied. |
 | Read a contact's chat | `flowiq m pull <contact_id>` then open the JSON |
 | Export an org's full chat history | `flowiq export chats <org_id>` |
 | Check / create WhatsApp templates | `flowiq tpl pull <org_id>` / `flowiq tpl create <org_id> --request-file req.json` |
@@ -192,6 +204,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.5",
   "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/org.js

@@ -6,6 +6,37 @@ 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;
 
+// `flowiq org list [search]` — the discovery step every other command needed.
+// Until this existed the only way to turn "African Oils" into a UUID was the
+// dashboard or raw SQL, which made every org-scoped command awkward to start.
+export async function list(search, opts = {}) {
+  let resp;
+  try {
+    resp = await http.get("org", { list: "1", search: search || undefined });
+  } catch (e) {
+    console.error(`Lookup failed: ${e.message}`);
+    process.exit(1);
+  }
+  if (opts.json) { console.log(JSON.stringify(resp, null, 2)); return; }
+
+  const orgs = (resp.orgs || []).filter((o) => (opts.all ? true : !o.inactive));
+  if (!orgs.length) {
+    console.log(search ? `No organizations match "${search}".` : "No organizations found.");
+    return;
+  }
+  const pad = (s, n) => String(s ?? "").padEnd(n);
+  const nameW = Math.min(34, Math.max(4, ...orgs.map((o) => (o.name || "").length)));
+  console.log(`${pad("NAME", nameW)}  ${pad("ID", 36)}  ${pad("PLATFORM", 9)}STORE`);
+  for (const o of orgs) {
+    console.log(
+      `${pad((o.name || "").slice(0, nameW), nameW)}  ${pad(o.id, 36)}  ` +
+      `${pad(o.platform || "—", 9)}${o.store || ""}${o.inactive ? "  (inactive)" : ""}`
+    );
+  }
+  const hidden = (resp.orgs || []).length - orgs.length;
+  console.log(`\n${orgs.length} organization(s)${hidden ? ` · ${hidden} inactive hidden (--all to show)` : ""}`);
+}
+
 export async function info(orgId, opts = {}) {
   if (!UUID_RE.test(orgId)) {
     console.error(`Error: "${orgId}" is not a valid organization UUID.`);

package/src/commands/store-api.js

@@ -0,0 +1,374 @@
+// `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})` : ""}`);
+    }
+  }
+}
+
+/**
+ * Print a flat array of objects as a table. Only ever a RENDERING of whatever
+ * the API returned — it never changes, filters or reshapes the data, so
+ * `--table` and the default JSON are the same answer in two skins.
+ */
+function renderTable(rows) {
+  if (!Array.isArray(rows) || rows.length === 0) return null;
+  const flat = rows.map((r) => {
+    if (r === null || typeof r !== "object" || Array.isArray(r)) return { value: r };
+    const o = {};
+    for (const [k, v] of Object.entries(r)) {
+      o[k] = v === null || v === undefined ? ""
+        : typeof v === "object" ? (Array.isArray(v) ? `[${v.length}]` : "{…}")
+        : String(v);
+    }
+    return o;
+  });
+  const cols = [...new Set(flat.flatMap((r) => Object.keys(r)))];
+  if (!cols.length) return null;
+  const w = {};
+  for (const c of cols) w[c] = Math.min(48, Math.max(c.length, ...flat.map((r) => (r[c] ?? "").length)));
+  const cut = (s, n) => (s.length > n ? s.slice(0, n - 1) + "…" : s.padEnd(n));
+  const lines = [cols.map((c) => cut(c.toUpperCase(), w[c])).join("  ")];
+  lines.push(cols.map((c) => "─".repeat(w[c])).join("  "));
+  for (const r of flat) lines.push(cols.map((c) => cut(r[c] ?? "", w[c])).join("  "));
+  return lines.join("\n");
+}
+
+/** The single array in a Shopify-style `{orders: [...]}` wrapper, or the array itself. */
+function primaryArray(data) {
+  if (Array.isArray(data)) return data;
+  if (data && typeof data === "object") {
+    const keys = Object.keys(data).filter((k) => Array.isArray(data[k]));
+    if (keys.length === 1) return data[keys[0]];
+  }
+  return null;
+}
+
+function emit(resp, opts) {
+  banner(resp);
+  const payload = opts.json ? resp : resp.data;
+
+  if (opts.table && !opts.json) {
+    const rows = primaryArray(resp.data);
+    const table = rows ? renderTable(rows) : renderTable([resp.data]);
+    if (table) {
+      if (opts.out) { writeFileSync(opts.out, table + "\n"); console.error(`✓ wrote ${opts.out}`); return; }
+      console.log(table);
+      return;
+    }
+    console.error("(--table: response is not a flat list; printing JSON)");
+  }
+
+  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);
+}
+
+// ---------------------------------------------------------------------------
+// Recipes — NOT wrappers.
+//
+// These answer the two questions people actually ask ("what's the stock on X",
+// "did this order ship") which otherwise take 3-4 chained calls and a manual
+// id-join. They are composed of THE SAME `shopify get` passthrough calls you
+// could type yourself, and they PRINT EVERY CALL THEY MAKE as a runnable
+// command — so the raw API stays the interface, and anyone (or any agent)
+// reading the output can copy those lines, change them, and go further than
+// the recipe does. Nothing here is expressible only through the recipe.
+// `--raw` dumps the underlying JSON instead of the summary.
+// ---------------------------------------------------------------------------
+
+/** Run a passthrough GET, echoing the equivalent command so it can be reused. */
+async function rawGet(orgId, path, query, { label } = {}) {
+  const qs = Object.entries(query || {})
+    .flatMap(([k, v]) => (Array.isArray(v) ? v.map((x) => [k, x]) : [[k, v]]))
+    .map(([k, v]) => `--q ${k}=${/[ "']/.test(String(v)) ? JSON.stringify(String(v)) : v}`)
+    .join(" ");
+  console.error(`  $ flowiq shopify get <org> ${path}${qs ? " " + qs : ""}${label ? `    # ${label}` : ""}`);
+  const resp = await http.post("store-api", {
+    platform: "shopify", organization_id: orgId, mode: "rest", path, query: query || {},
+  });
+  return resp.data;
+}
+
+export async function shopifyStock(orgId, search, opts = {}) {
+  requireOrg(orgId);
+  if (!search || !String(search).trim()) {
+    console.error('Error: give me something to look for, e.g. flowiq shopify stock <org> "olive oil"');
+    process.exit(1);
+  }
+  console.error(`Looking up stock for "${search}" — the calls being made:`);
+  let products, levels, locations;
+  try {
+    // 1. name → products + variants (variants carry inventory_item_id)
+    const p = await rawGet(orgId, "products.json", { title: search, limit: 50 }, { label: "find the product" });
+    products = (p?.products || []).filter((x) =>
+      String(x.title).toLowerCase().includes(String(search).toLowerCase()));
+    if (!products.length) {
+      const all = await rawGet(orgId, "products.json", { limit: 250, fields: "id,title,variants,status" },
+        { label: "no title match — scanning the catalogue" });
+      products = (all?.products || []).filter((x) =>
+        String(x.title).toLowerCase().includes(String(search).toLowerCase()));
+    }
+    if (!products.length) {
+      console.error(`\nNothing matched "${search}". This searches product TITLES only — ` +
+        `the passthrough can query anything else Shopify exposes.`);
+      process.exit(1);
+    }
+    const itemIds = products.flatMap((x) => (x.variants || []).map((v) => v.inventory_item_id)).filter(Boolean);
+    // 2. inventory_item_id → per-location levels   3. location_id → names
+    levels = itemIds.length
+      ? (await rawGet(orgId, "inventory_levels.json",
+          { inventory_item_ids: itemIds.slice(0, 50).join(","), limit: 250 },
+          { label: "per-location levels" }))?.inventory_levels || []
+      : [];
+    locations = (await rawGet(orgId, "locations.json", { fields: "id,name" },
+      { label: "turn location ids into names" }))?.locations || [];
+  } catch (e) {
+    console.error(`\nRequest failed: ${e.message}`);
+    process.exit(1);
+  }
+
+  if (opts.raw) { console.log(JSON.stringify({ products, inventory_levels: levels, locations }, null, 2)); return; }
+
+  const locName = new Map(locations.map((l) => [l.id, l.name]));
+  const byItem = new Map();
+  for (const l of levels) {
+    if (!byItem.has(l.inventory_item_id)) byItem.set(l.inventory_item_id, []);
+    byItem.get(l.inventory_item_id).push(l);
+  }
+  const rows = [];
+  for (const p of products) {
+    for (const v of p.variants || []) {
+      const ls = byItem.get(v.inventory_item_id) || [];
+      const per = ls.map((l) => {
+        // `available: null` is Shopify saying "this item is not TRACKED at this
+        // location" — not zero, and not an error. Say so, rather than printing
+        // null and letting the reader guess.
+        const qty = l.available === null || l.available === undefined ? "not tracked" : String(l.available);
+        return `${locName.get(l.location_id) || l.location_id}: ${qty}`;
+      });
+      rows.push({
+        product: p.title,
+        variant: v.title === "Default Title" ? "—" : v.title,
+        sku: v.sku || "",
+        price: v.price ?? "",
+        policy: v.inventory_policy === "continue" ? "oversell ok" : "stop at 0",
+        total: v.inventory_quantity ?? "",
+        per_location: per.length ? per.join(" · ") : "(no level rows — untracked)",
+      });
+    }
+  }
+  console.error("");
+  console.log(renderTable(rows) ?? "(no variants)");
+  console.error(`\n${products.length} product(s) · ${rows.length} variant(s). ` +
+    `"not tracked" means Shopify holds no inventory record at that location — it is not a zero.`);
+}
+
+export async function shopifyOrder(orgId, ref, opts = {}) {
+  requireOrg(orgId);
+  const name = String(ref).trim();
+  console.error(`Looking up order ${name} — the calls being made:`);
+  let order;
+  try {
+    if (/^\d{10,}$/.test(name)) {
+      order = (await rawGet(orgId, `orders/${name}.json`, {}, { label: "by Shopify order id" }))?.order;
+    } else {
+      const r = await rawGet(orgId, "orders.json",
+        { name, status: "any", limit: 5 }, { label: "by order name" });
+      order = (r?.orders || [])[0];
+    }
+  } catch (e) {
+    console.error(`\nRequest failed: ${e.message}`);
+    process.exit(1);
+  }
+  if (!order) {
+    console.error(`\nNo order matching "${name}". Note Shopify matches the ORDER NAME (#14728), not the ` +
+      `confirmation number customers are shown on the thank-you page.`);
+    process.exit(1);
+  }
+  if (opts.raw) { console.log(JSON.stringify(order, null, 2)); return; }
+
+  const f = order.fulfillments || [];
+  console.error("");
+  console.log(`${order.name}  ${order.financial_status || "?"} / ${order.fulfillment_status || "unfulfilled"}`);
+  console.log(`  placed    ${order.created_at}`);
+  console.log(`  total     ${order.currency} ${order.total_price}`);
+  console.log(`  customer  ${[order.customer?.first_name, order.customer?.last_name].filter(Boolean).join(" ") || "—"}` +
+    `${order.email ? ` · ${order.email}` : ""}`);
+  console.log(`  items     ${(order.line_items || []).map((li) => `${li.quantity}× ${li.title}`).join(", ") || "—"}`);
+  if (!f.length) {
+    console.log(`  shipping  nothing fulfilled yet`);
+  } else {
+    for (const ff of f) {
+      console.log(`  shipment  ${ff.status}` +
+        ` · ${ff.tracking_company || "no carrier recorded"}` +
+        ` · ${ff.tracking_number || "no tracking number"}` +
+        ` · courier status: ${ff.shipment_status || "none reported"}` +
+        ` · ${(ff.line_items || []).length} item(s)`);
+      if (ff.tracking_url) console.log(`            ${ff.tracking_url}`);
+    }
+  }
+  console.error(`\nFull payload: add --raw (or use the passthrough directly — ` +
+    `flowiq shopify get <org> orders/${order.id}.json)`);
+}
+
+// ---------------------------------------------------------------------------
+// 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
@@ -210,6 +211,11 @@ export function run(argv) {
 
   // org (read-only org summary for the prompt-builder skill, creds stripped)
   const org = program.command("org").description("Org info (read) + create a new organization");
+  org.command("list [search]")
+    .description("List organizations with their UUIDs — the lookup every other command needs (filter by name/slug)")
+    .option("--all", "include inactive organizations")
+    .option("--json", "raw JSON")
+    .action((search, opts) => orgCmd.list(search, opts));
   org.command("create")
     .description("Create a NEW organization (org row + admin membership; owner defaults to you)")
     .requiredOption("--name <name>", "organization name")
@@ -241,7 +247,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 +432,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 +453,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 +620,58 @@ 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("--table", "render the returned list as a table instead of JSON (same data, no reshaping)")
+    .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));
+  // Recipes: the same passthrough calls, composed — and every call is PRINTED
+  // as a runnable command so the raw API stays the interface.
+  shopify.command("stock <organization_id> <search>")
+    .description("Stock per location for products matching a title — chains products → inventory_levels → locations and PRINTS each raw call it makes")
+    .option("--raw", "print the underlying JSON from every call instead of the summary table")
+    .action((orgId, search, opts) => storeApiCmd.shopifyStock(orgId, search, opts));
+  shopify.command("order <organization_id> <name-or-id>")
+    .description("One order with its fulfilments + tracking, e.g. `order <org> #14728` — PRINTS the raw call it makes")
+    .option("--raw", "print the full order JSON instead of the summary")
+    .action((orgId, ref, opts) => storeApiCmd.shopifyOrder(orgId, ref, 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("--table", "render the returned list as a table instead of JSON (same data, no reshaping)")
+    .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("--table", "render the returned list as a table instead of JSON (same data, no reshaping)")
+    .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")