@flowapt/flowiq-cli 0.4.4 → 0.4.6

package/README.md

@@ -256,6 +256,16 @@ flowiq bc scheduled cancel  <org_id> <queue_id> --confirm
     the abort message says so — fix by passing `--header-media <real video>`.
     `map` refuses to save a mismatched default into the campaign file. An
     unreachable URL only warns (`media unverified`), never blocks.
+- **One campaign = one template (v0.4.6).** A campaign's saved mapping, header
+  media and write-ahead status log (dedup) all belong to the template it was
+  built for. Running `bc send` / `map` with a **different `--template` on an
+  existing `--campaign`** now **ABORTS** (`Campaign "X" was built for template
+  A …`) — reusing the slug would silently send A's header media and skip the
+  recipients A already reached (the header-media check only catches a media-TYPE
+  change, not a same-type creative swap). Use a fresh `--campaign` for a new
+  template. In **tag mode the campaign slug defaults to the tag**, so to send
+  template A then template B to the SAME tag, pass a distinct `--campaign` for
+  each. `resume` passes no `--template`, so it is never affected.
 - **`list-remote <org>` (v0.3.9)**: list the org's broadcasts **newest-first** with
   the **full broadcastId** per row + template, status, recipient count and SAST
   created time — the discovery step `status` / `retry` need (previously the id
@@ -578,6 +588,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 |
@@ -814,10 +836,63 @@ Flags:
 | `--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.
+
+#### Counting things — read `precision` before you trust a number
+
+Shopify's `*Count` fields return `{count, precision}`. **`precision: "AT_LEAST"`
+means the number is a CAP (10,000), not an answer.** The CLI now warns on stderr
+whenever a capped count comes back, because it is very easy to read 10,000 as a
+real total.
+
+**`customersCount` additionally IGNORES its `query:` filter.** Verified 4 Aug 2026
+straight against Shopify with no FlowIQ layer involved, on API versions 2024-01,
+2024-10 and 2025-01: an impossible email filter still returns `10000 / AT_LEAST`.
+Its sibling `ordersCount` honours the same argument and returns
+`1372 / EXACT`, so this is specific to that field, not a general limit. **This is
+Shopify's behaviour, not the CLI's** — but sizing an audience with it gives you a
+plausible, wrong number, so the CLI calls it out.
+
+Count a filtered customer cohort with the connection instead, which filters
+correctly, and paginate:
+
+```bash
+flowiq shopify gql <org> -q 'query { customers(first: 250, query: "orders_count:>=20") {
+  edges { node { id } } pageInfo { hasNextPage endCursor } } }'
+```
+
 Notes:
 
+* **A long `--all` can TIME OUT rather than truncate.** The server budgets ~25s and
+  then returns a partial result, but a very wide pull can still exceed the function
+  limit. You now get an explicit timeout message naming the remedy (retry, fewer
+  `--max-pages`, a smaller `--q limit`) — previously this surfaced as
+  `Request failed: [object Object]`, which read like a hard limit and wasn't.
 * **`--all` is bounded and says so.** It stops at `--max-pages`, at a ~3.5MB
   response size, or at a time budget, and then reports `⚠ TRUNCATED — <reason>`
   on stderr. A partial result is never presented as a complete one.
@@ -844,6 +919,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
 ```
 

package/TEAM-GUIDE.md

@@ -80,6 +80,11 @@ 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 |
+| **Size a customer cohort** | Use `customers(first:250, query:…)` and paginate — **NOT `customersCount(query:…)`, which Shopify ignores the filter on** and answers 10,000 every time. Any count showing `precision: AT_LEAST` is a cap, not a total; the CLI warns you. |
+| A big `--all` failed with a timeout | It's transient, not a limit — retry, or narrow it with `--max-pages` / a smaller `--q limit`. The message now says so. |
 | Ask a client's Shopify store anything (read-only) | `flowiq shopify get <org_id> orders.json --q status=any --q limit=250` — any Admin REST endpoint; writes are refused |
 | Ask a client's Shopify store something REST can't express | `flowiq shopify gql <org_id> -q 'query { shop { name } }'` — you write the GraphQL; any `mutation` is refused |
 | Ask a client's WooCommerce store anything (read-only) | `flowiq woo get <org_id> orders --q status=completed --all` |
@@ -101,7 +106,7 @@ When you see it, run `npm i -g @flowapt/flowiq-cli` — a stale version also mea
 | Split a whole tagged audience into batches of N (e.g. 90k → 7000s) | `flowiq seg plan <org_id> --tag-prefix 3-aug-bc --from-tag "3-aug-bc" --batch-size 7000` → `flowiq seg apply <org_id> 3-aug-bc --commit --yes` (makes `…-batch-01…13`; works at any size — big applies are chunked internally) |
 | Schedule a broadcast for later instead of sending now | `flowiq bc send <org_id> --tag <batch-tag> --template <name> --at "2026-08-05 09:00" --commit` (time is SAST; fires on its own; audience resolved at send time) |
 | See / approve / cancel what's scheduled | `flowiq bc scheduled list <org_id>` → `flowiq bc scheduled approve <org_id> <queue_id>` or `flowiq bc scheduled cancel <org_id> <queue_id> --confirm` |
-| Send to one batch tag | `flowiq bc send <org_id> --tag <batch-tag> --template … --body param1="Hi {{first_name}}" --commit` (per-contact tokens: the 6 contact fields + `{{attributes.<key>}}`) |
+| Send to one batch tag | `flowiq bc send <org_id> --tag <batch-tag> --template … --body param1="Hi {{first_name}}" --commit` (per-contact tokens: the 6 contact fields + `{{attributes.<key>}}`). Sending a **different template to the SAME tag**? Add a distinct `--campaign <name>` — otherwise the CLI aborts (a campaign belongs to one template; reusing it would send the first template's image + skip everyone it already reached). |
 | Send a broadcast whose template has an IMAGE/VIDEO/DOCUMENT header | Same as above — the media is automatic (the template's own stored header). Override with `--header-media <public-url>` if needed. The CLI verifies the resolved media's actual type against the header format — `header video (video ✓ video/mp4)` means verified; a mismatch (e.g. a video template whose stored default is secretly a png — templates made before 3 Aug 2026 can carry this) ABORTS and tells you to pass `--header-media` with the real file. |
 | Send via the SAME engine as the dashboard's "Python" toggle | add `--python` to a `bc send --tag …` (fire-and-forget; python resolves the tag + sends + tracks; no CLI resume for this engine). **Any tag send over 10 recipients uses python automatically.** |
 | Find a broadcast's id (don't have the `broadcastId`?) | `flowiq bc list-remote <org_id>` — the org's broadcasts newest-first with full ids (`--template <substr>` / `--since <date>` / `--limit <n>` to narrow) |
@@ -111,6 +116,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` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flowapt/flowiq-cli",
-  "version": "0.4.4",
+  "version": "0.4.6",
   "description": "Command-line tool for FlowIQ staff: round-trip agent prompts, questionnaires, fine-tuning, pin-board tasks, webhooks, templates, agent-updates, chat exports, and live agent testing without ever touching service-role credentials.",
   "type": "module",
   "bin": {

package/src/commands/broadcast.js

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

package/src/commands/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

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

package/src/http.js

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

package/src/index.js

@@ -211,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")
@@ -627,9 +632,20 @@ export function run(argv) {
     .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")
@@ -637,6 +653,7 @@ export function run(argv) {
     .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));
@@ -650,6 +667,7 @@ export function run(argv) {
     .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));