@flowapt/flowiq-cli 0.4.4 → 0.4.5

package/README.md

@@ -578,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 |
@@ -814,8 +826,33 @@ 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.
+
 Notes:
 
 * **`--all` is bounded and says so.** It stops at `--max-pages`, at a ~3.5MB
@@ -844,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
 ```
 

package/TEAM-GUIDE.md

@@ -80,6 +80,9 @@ 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` |
@@ -111,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` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flowapt/flowiq-cli",
-  "version": "0.4.4",
+  "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/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

@@ -103,9 +103,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);
@@ -157,6 +207,154 @@ export async function shopifyGql(orgId, opts = {}) {
   }, 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
 // ---------------------------------------------------------------------------

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));