@flowapt/flowiq-cli 0.8.1 → 0.9.2

package/src/commands/hours.js

@@ -1,7 +1,9 @@
 // `flowiq hours log <org> --minutes N|--hours H --desc "…"` / `list <org>` /
-// `summary`. The client-hours ledger: every org's package includes 10 hours of
-// Flowapt work per calendar month, and every piece of client work gets logged
-// against it (manually here, or automatically by Claude via the FlowIQ MCP).
+// `summary` / `package show|set|clear`. The client-hours ledger: every piece
+// of client work gets logged against the org's monthly hours PACKAGE. Since
+// v0.9.2 each org has its own package (or shares one with sibling orgs, e.g.
+// Barkyn PT/ES/IT), set with `hours package set` by Matt or Gidon only; an org
+// with no package reads "no package on file", never an implied 10h.
 // All writes happen server-side (/cli/hours) with the staff token.
 
 import { http } from "../http.js";
@@ -14,6 +16,24 @@ function fmtHours(minutes) {
   return `${Number.isInteger(h) ? h : h.toFixed(1)}h`;
 }
 
+/** "5h package" / "10h package shared with Barkyn - Spain, Barkyn - Italy" / "no package on file". */
+function describePackage(pkg, orgName) {
+  if (!pkg) return "no package on file (set one with `flowiq hours package set`)";
+  const size = `${fmtHours(pkg.allowance_minutes)}/month`;
+  if (!pkg.shared) return `${size} package`;
+  const others = (pkg.organizations || []).filter((n) => n !== orgName);
+  return `${size} package "${pkg.name}", shared with ${others.join(", ")}`;
+}
+
+/** "3h of 5h used (2h left)" / "⚠ 1.5h OVER" against a package; "" with none. */
+function standingLine(pkg) {
+  if (!pkg) return "";
+  const used = pkg.used_minutes;
+  const allowance = pkg.allowance_minutes;
+  const tail = used > allowance ? `  ⚠ ${fmtHours(used - allowance)} OVER` : ` (${fmtHours(allowance - used)} left)`;
+  return `${fmtHours(used)} of ${fmtHours(allowance)} used${pkg.shared ? " across the shared package" : ""}${tail}`;
+}
+
 function requireOrg(orgId) {
   if (!UUID_RE.test(orgId || "")) {
     console.error(`Error: "${orgId}" is not a valid organization UUID (find it with \`flowiq org list <search>\`).`);
@@ -88,11 +108,11 @@ export async function log(orgId, opts) {
     process.exit(1);
   }
 
-  const used = resp.month_total_minutes;
-  const allowance = resp.allowance_hours * 60;
   console.log(`Logged ${fmtHours(minutes)} for ${resp.organization.name}`);
-  console.log(`  entry:  ${resp.id}`);
-  console.log(`  month:  ${resp.month} — ${fmtHours(used)} of ${resp.allowance_hours}h package used${used > allowance ? `  ⚠ ${fmtHours(used - allowance)} OVER` : ` (${fmtHours(allowance - used)} left)`}`);
+  console.log(`  entry:   ${resp.id}`);
+  console.log(`  month:   ${resp.month}: ${fmtHours(resp.month_total_minutes)} logged for this org`);
+  console.log(`  package: ${describePackage(resp.package, resp.organization.name)}`);
+  if (resp.package) console.log(`           ${standingLine(resp.package)}`);
 }
 
 export async function list(orgId, opts) {
@@ -109,9 +129,10 @@ export async function list(orgId, opts) {
     console.log(JSON.stringify(resp, null, 2));
     return;
   }
-  const over = resp.remaining_minutes < 0;
   console.log(`${resp.organization.name} — ${resp.month}`);
-  console.log(`  package: ${resp.allowance_hours}h/month · used ${fmtHours(resp.total_minutes)} · ${over ? `⚠ ${fmtHours(-resp.remaining_minutes)} OVER` : `${fmtHours(resp.remaining_minutes)} left`}`);
+  console.log(`  logged:  ${fmtHours(resp.total_minutes)} for this org`);
+  console.log(`  package: ${describePackage(resp.package, resp.organization.name)}`);
+  if (resp.package) console.log(`           ${standingLine(resp.package)}`);
   if (!resp.entries.length) {
     console.log("  (no entries this month)");
     return;
@@ -138,13 +159,107 @@ export async function summary(opts) {
     return;
   }
   if (!resp.organizations.length) {
-    console.log(`(no hours logged for any org in ${resp.month})`);
+    console.log(`(no hours logged and no packages set for ${resp.month})`);
     return;
   }
-  const allowance = resp.allowance_hours * 60;
-  console.log(`Client hours — ${resp.month} (package: ${resp.allowance_hours}h/month per org)\n`);
+  console.log(`Client hours — ${resp.month}\n`);
   for (const o of resp.organizations) {
-    const flag = o.total_minutes > allowance ? `  ⚠ ${fmtHours(o.total_minutes - allowance)} OVER` : "";
-    console.log(`  ${fmtHours(o.total_minutes).padStart(6)}  (${String(o.entries).padStart(2)} entr${o.entries === 1 ? "y" : "ies"})  ${o.name || o.id}${flag}`);
+    const p = o.package;
+    let pkgCol;
+    if (!p) pkgCol = "no package on file";
+    else if (p.shared) {
+      const flag = p.used_minutes > p.allowance_minutes ? `  ⚠ ${fmtHours(p.used_minutes - p.allowance_minutes)} OVER` : "";
+      pkgCol = `shared "${p.name}": ${fmtHours(p.used_minutes)} / ${fmtHours(p.allowance_minutes)}${flag}`;
+    } else {
+      const flag = p.used_minutes > p.allowance_minutes ? `  ⚠ ${fmtHours(p.used_minutes - p.allowance_minutes)} OVER` : "";
+      pkgCol = `of ${fmtHours(p.allowance_minutes)}${flag}`;
+    }
+    console.log(`  ${fmtHours(o.total_minutes).padStart(6)}  (${String(o.entries).padStart(3)} entr${o.entries === 1 ? "y  " : "ies"})  ${(o.name || o.id).padEnd(28)} ${pkgCol}`);
+  }
+}
+
+// ── packages ───────────────────────────────────────────────────────────────
+
+function printPackage(p) {
+  const who = p.updated_by ? ` · set by ${p.updated_by} ${String(p.updated_at).slice(0, 10)}` : "";
+  console.log(`  ${p.name}  ·  ${fmtHours(p.monthly_minutes)}/month${p.organizations.length > 1 ? "  ·  SHARED" : ""}${who}`);
+  for (const o of p.organizations) console.log(`      ${o.name}  ${o.id}`);
+  if (p.notes) console.log(`      notes: ${p.notes}`);
+}
+
+export async function packageShow(orgId, opts) {
+  if (orgId) requireOrg(orgId);
+  let resp;
+  try {
+    resp = await http.get("hours", { packages: "1" });
+  } catch (e) {
+    console.error(`Package lookup failed: ${e.message}`);
+    process.exit(1);
+  }
+  let packages = resp.packages;
+  if (orgId) packages = packages.filter((p) => p.organizations.some((o) => o.id === orgId));
+  if (opts.json) {
+    console.log(JSON.stringify(orgId ? { packages } : resp, null, 2));
+    return;
+  }
+  if (!packages.length) {
+    console.log(orgId ? "No package on file for this org." : "No packages set yet.");
+  } else {
+    console.log(`Hours packages (${packages.length})\n`);
+    for (const p of packages) printPackage(p);
+  }
+  console.log(`\nChanges: ${resp.editors.join(", ")} only${resp.can_edit ? " (you can)" : " (not you)"}.`);
+}
+
+export async function packageSet(orgIds, opts) {
+  for (const id of orgIds) requireOrg(id);
+  const hours = Number(opts.hours);
+  if (!Number.isFinite(hours) || hours < 0 || hours > 1000) {
+    console.error(`Error: --hours must be a number between 0 and 1000 (got "${opts.hours}").`);
+    process.exit(1);
+  }
+  let resp;
+  try {
+    resp = await http.post("hours", {
+      action: "package_set",
+      organization_ids: orgIds,
+      hours,
+      name: opts.name || undefined,
+      notes: opts.notes || undefined,
+      dry_run: !!opts.dryRun,
+    });
+  } catch (e) {
+    console.error(`Package change failed: ${e.message}`);
+    process.exit(1);
+  }
+  const plan = resp.plan;
+  const who = plan.organizations.map((o) => o.name).join(", ");
+  console.log(`${resp.dry_run ? "DRY RUN — nothing written.\n" : ""}${plan.mode === "update" ? "Update" : "New"} package "${plan.name}": ${fmtHours(plan.monthly_minutes)}/month for ${who}`);
+  for (const b of plan.before) {
+    console.log(`  before: "${b.name}" ${fmtHours(b.monthly_minutes)}/month (${b.organizations.map((o) => o.name).join(", ")})`);
+  }
+  if (!plan.before.length) console.log("  before: no package on file");
+  for (const l of plan.left_behind) {
+    console.log(`  ⚠ ${l.remaining.join(", ")} stay${l.remaining.length === 1 ? "s" : ""} on "${l.package}" without ${plan.organizations.length === 1 ? "this org" : "these orgs"}`);
+  }
+  if (resp.dry_run) console.log("\nRun again without --dry-run to apply.");
+}
+
+export async function packageClear(orgId, opts) {
+  requireOrg(orgId);
+  let resp;
+  try {
+    resp = await http.post("hours", { action: "package_clear", organization_id: orgId, dry_run: !!opts.dryRun });
+  } catch (e) {
+    console.error(`Package change failed: ${e.message}`);
+    process.exit(1);
+  }
+  if (resp.changed === false) {
+    console.log(`${resp.organization.name}: no package on file, nothing to clear.`);
+    return;
   }
+  const plan = resp.plan;
+  console.log(`${resp.dry_run ? "DRY RUN — nothing written.\n" : ""}${plan.organization.name} ${resp.dry_run ? "would leave" : "left"} package "${plan.package.name}" (${fmtHours(plan.package.monthly_minutes)}/month)`);
+  if (plan.package_removed) console.log("  the package had no other orgs, so it is removed");
+  else console.log(`  still on it: ${plan.remaining.join(", ")}`);
 }

package/src/commands/plans.js

@@ -65,6 +65,8 @@ export async function list(orgId, opts = {}) {
   if (orgId) query.organization_id = orgId;
   if (opts.status) query.status = opts.status;
   if (opts.since) query.since = opts.since;
+  if (opts.createdSince) query.created_since = opts.createdSince;
+  if (opts.touchedSince) query.touched_since = opts.touchedSince;
   if (opts.includeInactive) query.include_inactive = "1";
   if (opts.limit != null) query.limit = String(opts.limit);
 
@@ -83,7 +85,12 @@ export async function list(orgId, opts = {}) {
     ? resp.organization_name
     : `all ${resp.include_inactive ? "" : "active "}orgs`;
   const totals = STATUS_ORDER.filter((s) => resp.counts?.[s]).map((s) => `${s} ${resp.counts[s]}`).join(" · ");
-  console.log(`Broadcast plans · ${scope} · status ${resp.status_filter}${resp.since ? ` · from ${resp.since}` : ""}`);
+  const windowBits = [
+    resp.since ? `send date from ${resp.since}` : null,
+    resp.created_since ? `created from ${resp.created_since}` : null,
+    resp.touched_since ? `touched from ${resp.touched_since}` : null,
+  ].filter(Boolean);
+  console.log(`Broadcast plans · ${scope} · status ${resp.status_filter}${windowBits.length ? ` · ${windowBits.join(" · ")}` : ""}`);
   console.log(`  every status in this scope: ${totals || "none"}`);
 
   const plans = resp.plans || [];

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.");
+}