@flowapt/flowiq-cli 0.8.1 → 0.9.0

package/README.md

@@ -930,6 +930,7 @@ ids and prefixes — never a key.
 | `agent-config` | config | before + after snapshot + the changed keys |
 | `agents` / `org` / `meta-templates` | create | the created record / submitted request |
 | `messaging-webhooks` / `webhooks` | push, reconnect | full before + after |
+| `popups` | create / push / duplicate / delete / upload | **full before + after document** (popup + webhooks) |
 | `pinboard` | push | full prior row + the new one |
 | `agent-updates` | resolve | prior status + the client-facing note |
 | `broadcast` | **send (committed)**, retry | the exact payload sent + the resulting broadcastId |
@@ -1024,6 +1025,85 @@ Push refuses an `auth_type` whose credentials are incomplete (e.g. `bearer`
 with no `auth_config.token`), because that would make every delivery fail
 closed — FlowIQ never falls back to an unauthenticated send.
 
+### Popups — `flowiq popups schema|list|pull|push|create|duplicate|activate|deactivate|live|delete|upload` (alias `pp`) (v0.9.0)
+
+Every popup in FlowIQ — the ones built in the dashboard designer and the
+ones built here — is written through ONE endpoint, the popup service's
+`/api/popup-settings`. That endpoint owns the validator, the write rules
+and the schema; this CLI holds **no popup logic**. So a popup feature that
+ships in the popup service works from the terminal the same day, with no
+CLI release, and `flowiq popups schema` always prints what a popup may
+contain **today**.
+
+```bash
+flowiq popups schema                              # what a document may contain (content, rules, design, webhooks); --json for enums + limits
+flowiq popups list <org_id>                       # every popup: id, active/live, views, signups, what a signup triggers
+flowiq popups pull <org_id> [popup_id]            # → ./.flowiq/popups/<org-slug>/<name>-<id8>.json (popup + webhooks + etag); no id = all
+flowiq popups push <file> [--dry-run]             # apply the document; refused (409) if someone edited it since the pull (--force overrides)
+flowiq popups create <org_id> <file> [--dry-run]  # create from a document (a pulled file from ANY org works — ids are stripped); created INACTIVE
+flowiq popups duplicate <org_id> <popup_id> [--name …] [--from-org <id>] [--no-webhooks]
+flowiq popups activate|deactivate <org_id> <popup_id>
+flowiq popups live <org_id> <popup_id> [--off]    # which ACTIVE popup the store embed shows (one per org; prints what it demoted)
+flowiq popups delete <org_id> <popup_id> [--confirm]
+flowiq popups upload <org_id> <popup_id> <file> --slot main | --font "Gilmer" [--weight 500] [--italic]
+```
+
+**The document.** One JSON file per popup:
+
+```json
+{
+  "organization_id": "…",
+  "etag": "6939ff535be8f3f6",
+  "popup": { "id": "…", "name": "…", "slug": "spin", "is_active": true,
+             "content_settings": { "welcome": {…}, "success": {…}, "wheel": {…} },
+             "style_settings":   { "design": {…} },
+             "rules_settings":   { "when_to_show": {…}, "whom_to_show": {…}, … },
+             "stats": { "sales_stats": false } },
+  "webhooks": [ { "id": "…", "name": "Discount", "url": "…/functions/v1/send-discount-code-popup",
+                  "discount_config": { "enabled": true, "template_name": "welcome_v1", … } } ]
+}
+```
+
+- **A popup with no webhook sends NOTHING on signup.** The WhatsApp welcome +
+  discount code is the `send-discount-code-popup` row; Klaviyo / Omnisend /
+  Marsello / Passes / Flows are their own rows. `flowiq popups schema` lists
+  every FlowIQ function with its URL and config keys. **One row per function
+  per popup** — every row fires on every signup, so two rows = two messages;
+  the server refuses a push that would create the duplicate.
+- **`push` is id-keyed for webhooks** and **MERGES integration configs**
+  (`discount_config` / `pass_config` / `flows_config`) over what the row
+  holds — a file that knows three keys can never wipe a fourth (`null`
+  deletes a key on purpose). A webhook without an `id` but with a URL one
+  existing row already has UPDATES that row. Webhooks missing from the file
+  are left alone unless `--replace-webhooks --confirm-delete-webhooks`.
+- **`push` never changes which popup is live** (`currently_active_on_store`
+  and `image_history` are not sent from the file). Use `popups live`.
+- **Validation is the server's** (the editor gets the same answers): answer
+  keys (`choice_fields`, `questions`, deck cards, wheel segment ids) must
+  match `[a-zA-Z0-9_-]{1,64}` or the submissions API drops them; an enabled
+  wheel needs 2–12 wedges with at least one weight; an enabled teaser needs
+  text; `size.width` is kept equal to `size.maxWidth`. Errors block, warnings
+  ride back and are printed (`⚠`). Unknown keys are **stored with a
+  warning**, never dropped — popups evolve faster than any allowlist.
+- **`create` and `duplicate` land INACTIVE** with no slug and zero stats;
+  `activate` when checked. `duplicate` copies the webhooks too (`--from-org`
+  copies a popup from another org, webhooks excluded — templates, lists and
+  pass designs belong to the source client).
+- **Kill switch = `deactivate`** (`is_active=false`: store embed, pinned id
+  and the `popup.flowapt.com/p/…` link all 404). `live --off` only unselects
+  it — a store embed that pins its id still serves it while active.
+- **`delete` removes the signups, webhooks and delivery history with it**;
+  a live popup or one with signups needs `--confirm`.
+- **`upload`** puts an image in the private `popups_images` bucket (1-year
+  signed URL) or a font in the PUBLIC `popup_fonts` bucket, and prints the
+  URL to paste into the design.
+- **Concurrency:** the file's `etag` is sent as `if_match`; if the popup was
+  edited in the dashboard since the pull, push is refused with 409 — pull,
+  re-apply, push. `--force` overwrites. Every push refreshes the file (new
+  etag), and a rename moves it to its new file name.
+- **Audit:** create / push / duplicate / delete / upload are audited with the
+  full before + after document (`flowiq audit <org> --endpoint popups`).
+
 ### FlowMod prompts — `flowiq flowmod pull|push <slug>` (alias `fm`)
 
 Round-trips a FlowMod org's **master-group** prompts + config. FlowMod groups

package/TEAM-GUIDE.md

@@ -86,6 +86,13 @@ When you see it, run `npm i -g @flowapt/flowiq-cli` — a stale version also mea
 | 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 |
 | Make a keyword/button **hand the chat to a team or person** (assign in the inbox + email/WhatsApp them) | keyword action `{"type":"assign_chat","team_id":"…","assignee_user_id":"…","notify_member":true}` — see *Keywords* in `flowiq guide --reference`. Also in the dashboard (action type "Assign Chat") |
+| **See a client's popups** and what each one sends on signup | `flowiq popups list <org_id>` — "sends to: NOTHING" means a signup goes nowhere; add a `send-discount-code-popup` webhook |
+| **Change a popup's copy, wheel, rules or webhooks** | `flowiq popups pull <org_id> <popup_id>` → edit the JSON → `flowiq popups push <file> --dry-run` → `… push <file>`. Same rules as the dashboard (it is the same endpoint); if someone edited it in between you get a 409 — pull again |
+| **What can a popup contain right now?** (wheel, deck, intro page, scratch card, questions…) | `flowiq popups schema` — served by the popup service, so it is never stale |
+| **Build a client's popup from a proven one** | `flowiq popups duplicate <client_org> <popup_id> --from-org <source_org> --name "Client — welcome"`, then `pull` → edit → `push`, add its webhooks, `activate`, `live` |
+| Copy a popup inside the same client (webhooks included) | `flowiq popups duplicate <org_id> <popup_id>` — lands inactive with zero stats |
+| Switch a popup on / off / choose which one the store shows | `flowiq popups activate\|deactivate <org_id> <popup_id>` · `flowiq popups live <org_id> <popup_id>` (prints which popup it demoted) |
+| Put a picture or the client's own font on a popup | `flowiq popups upload <org_id> <popup_id> ./hero.jpg --slot main` · `… ./Gilmer-Medium.otf --font Gilmer --weight 500` — paste the printed URL into the design, then push |
 | **Find an org's ID** (needed by nearly every command) | `flowiq org list` — or `flowiq org list african` to filter |
 | See broadcast plans waiting for Flowapt review, across every client | `flowiq plans list --status pending_review`, then `flowiq plans show <plan_id>` for the copy, second message, buttons, creative and audience |
 | See one client's broadcast plans | `flowiq plans list <org_id>` (open plans) or `flowiq plans list <org_id> --status all --since 2026-09-01` |

package/package.json

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

@@ -0,0 +1,367 @@
+// `flowiq popups …` — create, read, change, copy, switch on and delete popups.
+//
+// The CLI knows NOTHING about what a popup may contain. A popup is a JSON
+// document; the popup service validates it and owns every write rule, and
+// `flowiq popups schema` prints what it accepts TODAY. So a popup feature that
+// ships in the popup service works from here the same day, with no CLI release.
+//
+//   flowiq popups schema [--json]
+//   flowiq popups list <org_id> [--json]
+//   flowiq popups pull <org_id> [popup_id]          (no id = every popup)
+//   flowiq popups push <file> [--dry-run] [--replace-webhooks] [--confirm-delete-webhooks] [--force]
+//   flowiq popups create <org_id> <file> [--dry-run]
+//   flowiq popups duplicate <org_id> <popup_id> [--name …] [--from-org <id>] [--no-webhooks]
+//   flowiq popups activate|deactivate <org_id> <popup_id>
+//   flowiq popups live <org_id> <popup_id> [--off]
+//   flowiq popups delete <org_id> <popup_id> [--confirm]
+//   flowiq popups upload <org_id> <popup_id> <file> --slot <name> | --font <family> [--weight n] [--italic]
+
+import fs from "node:fs/promises";
+import path from "node:path";
+import { http } from "../http.js";
+
+const POPUPS_DIR = path.resolve(process.cwd(), ".flowiq", "popups");
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+// What `push` sends from the file. currently_active_on_store and
+// image_history are deliberately NOT here: which popup a store shows is
+// changed with `popups live`, never as a side effect of pushing an old file.
+const PUSH_COLUMNS = ["name", "slug", "is_active", "content_settings", "style_settings", "rules_settings", "stats"];
+
+function slugify(name, fallback) {
+  const s = String(name || "").toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/-+/g, "-").replace(/^-|-$/g, "");
+  return s || fallback;
+}
+
+function die(msg) {
+  console.error(msg);
+  process.exit(1);
+}
+
+function requireUuid(value, what) {
+  if (!UUID_RE.test(String(value || ""))) die(`Error: "${value}" is not a valid ${what} UUID.`);
+}
+
+async function fileExists(p) {
+  try { await fs.access(p); return true; } catch { return false; }
+}
+
+/** A failed call: print the service's own errors + warnings, then exit. */
+function fail(prefix, e) {
+  const body = e.body || {};
+  console.error(`${prefix}: ${e.message}`);
+  const errors = Array.isArray(body.errors) ? body.errors : [];
+  if (errors.length > 1) for (const err of errors.slice(1)) console.error(`  also: ${err}`);
+  printWarnings(body.warnings);
+  process.exit(1);
+}
+
+function printWarnings(warnings) {
+  if (!Array.isArray(warnings) || warnings.length === 0) return;
+  console.log(`\n  ${warnings.length} warning${warnings.length === 1 ? "" : "s"}:`);
+  for (const w of warnings) console.log(`   ⚠ ${w}`);
+}
+
+function docPath(orgSlug, doc) {
+  const popup = doc.popup || {};
+  const base = `${slugify(popup.slug || popup.name, "popup")}-${String(popup.id || "").slice(0, 8)}`;
+  return path.join(POPUPS_DIR, orgSlug, `${base}.json`);
+}
+
+async function writeDoc(resp) {
+  const doc = resp.data;
+  const orgSlug = slugify(resp.organization_slug || resp.organization_name, doc.organization_id);
+  const filePath = docPath(orgSlug, doc);
+  await fs.mkdir(path.dirname(filePath), { recursive: true });
+  const overwriting = await fileExists(filePath);
+  const onDisk = {
+    document_version: doc.document_version,
+    organization_id: doc.organization_id,
+    organization_name: resp.organization_name,
+    pulled_at: new Date().toISOString(),
+    etag: doc.etag,
+    popup: doc.popup,
+    webhooks: doc.webhooks,
+  };
+  await fs.writeFile(filePath, JSON.stringify(onDisk, null, 2) + "\n", "utf8");
+  return { filePath, overwriting };
+}
+
+function describe(popup) {
+  const flags = [popup.is_active ? "active" : "inactive"];
+  if (popup.currently_active_on_store) flags.push("LIVE on store");
+  if (popup.slug) flags.push(`/${popup.slug}`);
+  return flags.join(" · ");
+}
+
+// ---------------------------------------------------------------------------
+
+export async function schema(opts = {}) {
+  let resp;
+  try { resp = await http.get("popups", { op: "schema" }); } catch (e) { fail("Schema failed", e); }
+  const s = resp.data;
+  if (opts.json) return console.log(JSON.stringify(s, null, 2));
+
+  console.log(`Popup document (version ${s.document_version}) — served by the popup service, so this is what it accepts TODAY.\n`);
+  console.log("content_settings:");
+  for (const [k, v] of Object.entries(s.content_settings)) {
+    console.log(`  ${k}${v.required ? " (required)" : v.enable_flag ? ` (on when ${k}.${v.enable_flag} is true)` : ""}`);
+    console.log(`      ${v.summary}`);
+  }
+  console.log("\nrules_settings:");
+  for (const [k, v] of Object.entries(s.rules_settings)) console.log(`  ${k}${v.required ? " (required)" : ""}\n      ${v.summary}`);
+  console.log("\nstyle_settings:");
+  for (const [k, v] of Object.entries(s.style_settings)) console.log(`  ${k}\n      ${v}`);
+  console.log("\nwebhooks (what a signup triggers — a popup with none sends nothing):");
+  for (const [slug, v] of Object.entries(s.webhooks)) console.log(`  ${slug}  → ${v.config_column}\n      ${v.url}\n      ${v.summary}`);
+  console.log("\nrules:");
+  for (const r of s.rules) console.log(`  • ${r}`);
+  console.log("\n--json prints the whole schema, enums and limits included.");
+}
+
+export async function list(orgId, opts = {}) {
+  requireUuid(orgId, "organization");
+  let resp;
+  try { resp = await http.get("popups", { op: "list", organization_id: orgId }); } catch (e) { fail("List failed", e); }
+  const popups = resp.data?.popups || [];
+  if (opts.json) return console.log(JSON.stringify(popups, null, 2));
+
+  console.log(`${resp.organization_name} (${orgId}) — ${popups.length} popup${popups.length === 1 ? "" : "s"}\n`);
+  for (const p of popups) {
+    console.log(`  ${p.id}  ${p.name}`);
+    console.log(`      ${describe(p)} · ${p.total_impressions || 0} views · ${p.total_submissions || 0} signups`);
+    console.log(`      sends to: ${p.webhook_functions?.length ? p.webhook_functions.join(", ") : "NOTHING (no webhooks)"}`);
+  }
+  if (popups.length) console.log(`\nflowiq popups pull ${orgId} <popup_id>   writes one to ./.flowiq/popups/`);
+}
+
+export async function pull(orgId, popupId) {
+  requireUuid(orgId, "organization");
+  let ids = [];
+  if (popupId) {
+    requireUuid(popupId, "popup");
+    ids = [popupId];
+  } else {
+    let resp;
+    try { resp = await http.get("popups", { op: "list", organization_id: orgId }); } catch (e) { fail("Pull failed", e); }
+    ids = (resp.data?.popups || []).map((p) => p.id);
+    if (ids.length === 0) return console.log(`${resp.organization_name} has no popups.`);
+  }
+  for (const id of ids) {
+    let resp;
+    try { resp = await http.get("popups", { op: "get", organization_id: orgId, popup_id: id }); } catch (e) { fail(`Pull failed (${id})`, e); }
+    const { filePath, overwriting } = await writeDoc(resp);
+    console.log(`${overwriting ? "Overwrote" : "Wrote"} ${filePath}`);
+    console.log(`  ${resp.data.popup.name} — ${describe(resp.data.popup)} · ${resp.data.webhooks.length} webhook(s)`);
+  }
+}
+
+async function isFile(p) {
+  try { return (await fs.stat(p)).isFile(); } catch { return false; }
+}
+
+async function readDoc(file) {
+  if (!file || !String(file).trim()) die("Error: give the popup document to read (a path, or a name under ./.flowiq/popups/).");
+  const candidates = path.isAbsolute(file) ? [file] : [path.resolve(file), path.join(POPUPS_DIR, file), path.join(POPUPS_DIR, `${file}.json`)];
+  for (const c of candidates) {
+    if (await isFile(c)) {
+      const raw = await fs.readFile(c, "utf8");
+      try { return { filePath: c, doc: JSON.parse(raw) }; } catch (e) { die(`Invalid JSON in ${c}: ${e.message}`); }
+    }
+  }
+  die(`File not found. Tried:\n  ${candidates.join("\n  ")}`);
+}
+
+const pickPushColumns = (popup) => Object.fromEntries(PUSH_COLUMNS.filter((c) => popup[c] !== undefined).map((c) => [c, popup[c]]));
+
+function printDiff(diff) {
+  const changed = diff?.changed || [];
+  const w = diff?.webhooks || {};
+  console.log(`  changed:   ${changed.length ? changed.join(", ") : "nothing"}`);
+  console.log(`  webhooks:  +${w.insert || 0} new · ~${w.update || 0} updated · -${w.delete || 0} removed`);
+}
+
+export async function push(file, opts = {}) {
+  const { filePath, doc } = await readDoc(file);
+  if (!doc.organization_id || !UUID_RE.test(doc.organization_id)) die(`${filePath}: organization_id missing or invalid`);
+  if (!doc.popup || typeof doc.popup !== "object") die(`${filePath}: no "popup" object`);
+  if (!doc.popup.id) die(`${filePath}: popup.id is missing — this document has never been created. Use:\n  flowiq popups create ${doc.organization_id} ${file}`);
+
+  const body = {
+    op: "push",
+    organization_id: doc.organization_id,
+    popup_id: doc.popup.id,
+    popup: pickPushColumns(doc.popup),
+    webhooks: Array.isArray(doc.webhooks) ? doc.webhooks : undefined,
+    webhooks_mode: opts.replaceWebhooks ? "replace" : undefined,
+    confirm_delete_webhooks: !!opts.confirmDeleteWebhooks,
+    if_match: doc.etag,
+    force: !!opts.force,
+    dry_run: !!opts.dryRun,
+  };
+
+  let resp;
+  try { resp = await http.post("popups", body); } catch (e) {
+    if (e.status === 409) {
+      console.error(`Push refused: ${e.message}`);
+      console.error(`\n  Pull it again (flowiq popups pull ${doc.organization_id} ${doc.popup.id}), re-apply your edit, and push — or --force to overwrite.`);
+      process.exit(1);
+    }
+    fail("Push failed", e);
+  }
+
+  console.log(`${opts.dryRun ? "DRY RUN" : "Pushed"} ${filePath}`);
+  console.log(`  org:       ${resp.organization_name} (${doc.organization_id})`);
+  console.log(`  popup:     ${doc.popup.name} (${doc.popup.id})`);
+  printDiff(resp.diff);
+  printWarnings(resp.warnings);
+  if (opts.dryRun) return console.log("\nDry run only — nothing was written. Re-run without --dry-run to apply.");
+
+  // The file now carries the NEW etag, so the next push from it is accepted.
+  const { filePath: refreshed } = await writeDoc(resp);
+  // A rename moves the document to its new file name; the old one would
+  // otherwise linger with a stale etag and push a stale name later.
+  if (path.resolve(refreshed) !== path.resolve(filePath)) await fs.rm(filePath, { force: true });
+  console.log(`\n✓ Saved. ${refreshed} refreshed from the server (new etag).`);
+}
+
+export async function create(orgId, file, opts = {}) {
+  requireUuid(orgId, "organization");
+  const { filePath, doc } = await readDoc(file);
+  const popup = doc.popup && typeof doc.popup === "object" ? doc.popup : doc;
+  if (!popup.name) die(`${filePath}: popup.name is required`);
+
+  // A document pulled from another popup carries ids that belong to IT.
+  const webhooks = (Array.isArray(doc.webhooks) ? doc.webhooks : []).map(({ id, popup_id, total_attempts, successful_deliveries, failed_deliveries, last_success_at, last_failure_at, created_at, updated_at, ...rest }) => rest);
+  const body = {
+    op: "create",
+    organization_id: orgId,
+    popup: { ...pickPushColumns(popup), is_active: false },
+    webhooks,
+    dry_run: !!opts.dryRun,
+  };
+
+  let resp;
+  try { resp = await http.post("popups", body); } catch (e) { fail("Create failed", e); }
+
+  if (opts.dryRun) {
+    console.log(`DRY RUN — would create "${popup.name}" in ${resp.organization_name} with ${webhooks.length} webhook(s), inactive.`);
+    printWarnings(resp.warnings);
+    return console.log("\nNothing was written. Re-run without --dry-run to create it.");
+  }
+  const { filePath: written } = await writeDoc(resp);
+  const created = resp.data.popup;
+  console.log(`✓ Created "${created.name}" in ${resp.organization_name}`);
+  console.log(`  id:        ${created.id}`);
+  console.log(`  state:     INACTIVE — check it, then: flowiq popups activate ${orgId} ${created.id}`);
+  console.log(`  webhooks:  ${resp.data.webhooks.length}`);
+  console.log(`  file:      ${written}`);
+  printWarnings(resp.warnings);
+}
+
+export async function duplicate(orgId, popupId, opts = {}) {
+  requireUuid(orgId, "organization");
+  requireUuid(popupId, "popup");
+  if (opts.fromOrg) requireUuid(opts.fromOrg, "source organization");
+  let resp;
+  try {
+    resp = await http.post("popups", {
+      op: "duplicate",
+      organization_id: orgId,
+      popup_id: popupId,
+      name: opts.name,
+      source_organization_id: opts.fromOrg,
+      include_webhooks: opts.webhooks === false ? false : undefined,
+    });
+  } catch (e) { fail("Duplicate failed", e); }
+  const { filePath } = await writeDoc(resp);
+  const created = resp.data.popup;
+  console.log(`✓ Copied into ${resp.organization_name} as "${created.name}"`);
+  console.log(`  id:        ${created.id}`);
+  console.log(`  state:     INACTIVE, no link, zero stats`);
+  console.log(`  webhooks:  ${resp.data.webhooks.length} copied`);
+  console.log(`  file:      ${filePath}`);
+  printWarnings(resp.warnings);
+}
+
+async function setColumns(orgId, popupId, popup, done) {
+  requireUuid(orgId, "organization");
+  requireUuid(popupId, "popup");
+  let resp;
+  try { resp = await http.post("popups", { op: "push", organization_id: orgId, popup_id: popupId, popup }); } catch (e) { fail("Update failed", e); }
+  console.log(`✓ ${resp.data.popup.name}: ${done(resp.data.popup)}`);
+  for (const d of resp.demoted || []) {
+    console.log(`  ↳ demoted "${d.name}" (${d.id}) — it was the live popup. Put it back with:\n      flowiq popups live ${orgId} ${d.id}`);
+  }
+  printWarnings(resp.warnings);
+}
+
+export const activate = (orgId, popupId) =>
+  setColumns(orgId, popupId, { is_active: true }, () => "ACTIVE — it can now be served and accept signups.");
+
+export const deactivate = (orgId, popupId) =>
+  setColumns(orgId, popupId, { is_active: false }, () => "INACTIVE — it is served nowhere (store embed, pinned id and its link all 404).");
+
+export const live = (orgId, popupId, opts = {}) =>
+  setColumns(orgId, popupId, { currently_active_on_store: !opts.off }, (p) =>
+    p.currently_active_on_store
+      ? `is now the popup this organization's store embed shows (any other live popup was demoted).${p.is_active ? "" : " ⚠ It is INACTIVE, so nothing will show until you activate it."}`
+      : "is no longer selected as the store's live popup. NOTE: a store embed that pins this popup's id still serves it while it is active — deactivate it to take it down."
+  );
+
+export async function remove(orgId, popupId, opts = {}) {
+  requireUuid(orgId, "organization");
+  requireUuid(popupId, "popup");
+  try {
+    await http.post("popups", { op: "delete", organization_id: orgId, popup_id: popupId, confirm: !!opts.confirm });
+  } catch (e) {
+    if (e.status === 409) {
+      console.error(`Delete refused: ${e.message}`);
+      console.error("\n  Deleting a popup deletes its signups, webhooks and delivery history with it. Re-run with --confirm if that is what you want.");
+      process.exit(1);
+    }
+    fail("Delete failed", e);
+  }
+  console.log(`✓ Deleted popup ${popupId}`);
+}
+
+const CONTENT_TYPES = { png: "image/png", jpg: "image/jpeg", jpeg: "image/jpeg", webp: "image/webp", gif: "image/gif", svg: "image/svg+xml", avif: "image/avif", otf: "font/otf", ttf: "font/ttf", woff: "font/woff", woff2: "font/woff2" };
+
+export async function upload(orgId, popupId, file, opts = {}) {
+  requireUuid(orgId, "organization");
+  requireUuid(popupId, "popup");
+  const isFont = !!opts.font;
+  if (!isFont && !opts.slot) die("Error: give --slot <name> for an image (main, main-mobile, textimage, success-main, intro-logo, deck-<key>…) or --font <family> for a font.");
+  const abs = path.resolve(file);
+  if (!(await fileExists(abs))) die(`File not found: ${abs}`);
+  const ext = path.extname(abs).replace(/^\./, "").toLowerCase();
+  const target = {
+    organization_id: orgId,
+    popup_id: popupId,
+    kind: isFont ? "font" : "image",
+    slot: opts.slot,
+    family: opts.font,
+    weight: opts.weight ? Number(opts.weight) : undefined,
+    style: opts.italic ? "italic" : undefined,
+    ext,
+  };
+
+  let ticket;
+  try { ticket = await http.post("popups", { op: "upload-url", ...target }); } catch (e) { fail("Upload failed", e); }
+
+  const bytes = await fs.readFile(abs);
+  const put = await fetch(ticket.data.signed_url, {
+    method: "PUT",
+    headers: { "Content-Type": CONTENT_TYPES[ext] || "application/octet-stream", "x-upsert": "true" },
+    body: bytes,
+  });
+  if (!put.ok) die(`Upload failed: storage answered HTTP ${put.status} ${(await put.text()).slice(0, 200)}`);
+
+  let ref;
+  try { ref = await http.post("popups", { op: "file-url", ...target }); } catch (e) { fail("Upload succeeded but the URL lookup failed", e); }
+  console.log(`✓ Uploaded ${path.basename(abs)} (${Math.round(bytes.length / 1024)} KB) → ${ref.data.bucket}/${ref.data.path}`);
+  console.log(`\n${ref.data.url}\n`);
+  console.log(isFont
+    ? `Reference it in style_settings.design.customFonts: [{ "family": "${opts.font}", "faces": [{ "weight": ${target.weight || 400}, "style": "${target.style || "normal"}", "url": "<the URL above>" }] }]`
+    : "Paste that URL where the design wants the image (e.g. style_settings.design.image.url), then flowiq popups push.");
+}

package/src/index.js

@@ -11,6 +11,7 @@ import * as questionnairesCmd from "./commands/questionnaires.js";
 import * as messagesCmd from "./commands/messages.js";
 import * as fineTuningCmd from "./commands/fine-tuning.js";
 import * as messagingWebhooksCmd from "./commands/messaging-webhooks.js";
+import * as popupsCmd from "./commands/popups.js";
 import * as webhooksCmd from "./commands/webhooks.js";
 import * as flowmodCmd from "./commands/flowmod.js";
 import * as groupsCmd from "./commands/groups.js";
@@ -137,6 +138,62 @@ export function run(argv) {
     .option("--dry-run", "preview the diff without writing anything")
     .action((id, opts) => messagingWebhooksCmd.push(id, opts));
 
+  // popups — the popup service's /api/popup-settings is the ONE home for popup
+  // writes (editor + CLI). This CLI holds no popup logic: `schema` reads what a
+  // popup may contain from the server, so new popup features need no release.
+  const popups = program.command("popups")
+    .alias("pp")
+    .description("Popups: list / pull / push / create / duplicate / activate / live / delete / upload — one JSON document per popup, validated by the popup service");
+  popups.command("schema")
+    .description("What a popup document may contain TODAY (content, rules, design, webhooks) — served by the popup service, never stale")
+    .option("--json", "print the full schema as JSON (enums + limits included)")
+    .action((opts) => popupsCmd.schema(opts));
+  popups.command("list <organization_id>")
+    .description("Every popup of an org: id, state, views, signups, and what a signup triggers")
+    .option("--json", "print as JSON")
+    .action((orgId, opts) => popupsCmd.list(orgId, opts));
+  popups.command("pull <organization_id> [popup_id]")
+    .description("Write a popup's full document (popup + webhooks + etag) to ./.flowiq/popups/<org>/; no popup_id = every popup")
+    .action((orgId, popupId) => popupsCmd.pull(orgId, popupId));
+  popups.command("push <file>")
+    .description("Apply a pulled document back: id-keyed webhook upsert, integration configs MERGED, refused if someone else edited it since the pull")
+    .option("--dry-run", "show what would change without writing")
+    .option("--replace-webhooks", "webhooks not in the file are REMOVED (needs --confirm-delete-webhooks)")
+    .option("--confirm-delete-webhooks", "allow the push to remove webhooks")
+    .option("--force", "overwrite even if the popup changed since the pull")
+    .action((file, opts) => popupsCmd.push(file, opts));
+  popups.command("create <organization_id> <file>")
+    .description("Create a popup from a JSON document (a pulled file from ANY org works — ids are stripped); created INACTIVE")
+    .option("--dry-run", "validate only")
+    .action((orgId, file, opts) => popupsCmd.create(orgId, file, opts));
+  popups.command("duplicate <organization_id> <popup_id>")
+    .description("Copy a popup (design, content, behaviour AND webhooks) — inactive, no link, zero stats")
+    .option("--name <name>", "name for the copy (default: \"<name> (copy)\")")
+    .option("--from-org <organization_id>", "copy a popup that lives in ANOTHER org (webhooks are not copied across orgs)")
+    .option("--no-webhooks", "do not copy the webhooks")
+    .action((orgId, popupId, opts) => popupsCmd.duplicate(orgId, popupId, opts));
+  popups.command("activate <organization_id> <popup_id>")
+    .description("Switch a popup ON (is_active) — the real on/off switch")
+    .action((orgId, popupId) => popupsCmd.activate(orgId, popupId));
+  popups.command("deactivate <organization_id> <popup_id>")
+    .description("Switch a popup OFF everywhere (store, pinned id and its link)")
+    .action((orgId, popupId) => popupsCmd.deactivate(orgId, popupId));
+  popups.command("live <organization_id> <popup_id>")
+    .description("Make this the popup the org's store embed shows (one per org; others are demoted)")
+    .option("--off", "unselect it (NOT a kill switch — use deactivate for that)")
+    .action((orgId, popupId, opts) => popupsCmd.live(orgId, popupId, opts));
+  popups.command("delete <organization_id> <popup_id>")
+    .description("Delete a popup and its signups; a live popup or one with signups needs --confirm")
+    .option("--confirm", "delete even if live or it has signups")
+    .action((orgId, popupId, opts) => popupsCmd.remove(orgId, popupId, opts));
+  popups.command("upload <organization_id> <popup_id> <file>")
+    .description("Upload an image (--slot) or a custom font (--font) for a popup and print the URL to put in its design")
+    .option("--slot <name>", "image slot: main, main-mobile, textimage, textimage-mobile, success-main, success-mobile, intro-logo, deck-<key>…")
+    .option("--font <family>", "font family name (uploads to the public popup_fonts bucket)")
+    .option("--weight <n>", "font weight (default 400)")
+    .option("--italic", "italic face")
+    .action((orgId, popupId, file, opts) => popupsCmd.upload(orgId, popupId, file, opts));
+
   // webhooks (Shopify/WooCommerce platform webhooks; auto-detects platform + ip_whitelist proxy)
   const wh = program.command("webhooks")
     .alias("wh")