@flowapt/flowiq-cli 0.7.5 → 0.9.0

package/README.md

@@ -82,7 +82,7 @@ flowiq prompts push <slug>
 Notes:
 - `system_prompt` is regenerated server-side from `prompt_sections` on
   push using the `## SECTION: <title>` format.
-- Sections support optional `hidden: boolean` + `channels: string[]`
+- Sections support optional `hidden: boolean` + `channels: string[]` (`web`, `whatsapp`, `messenger`, `instagram`, `email`; empty = every channel)
   (`web` / `whatsapp` / `messenger` / `instagram`) — validated on push.
 - **Time-boxed sections:** optional `active_from` / `active_until`
   (`"YYYY-MM-DD"` or `"YYYY-MM-DDTHH:mm"`) + `active_tz` (IANA, default
@@ -462,6 +462,27 @@ flowiq bc send <org_id> --tag new-arrivals-batch-01 --template new_arrivals_v3 \
   --button param1=<cycle-harmony-code> --button param2=<neuroshyft-code> --commit
 ```
 
+**Pasted links (v0.8.0, first on npm as 0.8.1):** you can paste the REAL link instead of a code:
+
+```bash
+flowiq bc send <org_id> --tag spring-batch-01 --template updates_v8 \
+  --body param1="Hi {{first_name}}" \
+  --button param1="https://shop.co.za/collections/spring?ref=ig&utm_source=klaviyo"
+```
+
+The dry run shows what will go out: `→ linklnk.io/<code-on-commit>`, the tags
+(`utm_campaign=18Sep_UpdatesV8 · utm_content=ClickHere · utm_source=whatsapp`),
+anything it replaced (`⚠ replaced utm_source=klaviyo with whatsapp`) and where
+the link really lands (a store redirect that drops the tags is pointed past;
+a `/discount/` link is kept). Your other params (`ref`, a discount code, a
+variant) are kept. `--commit` mints the code, then sends. `--link-campaign
+"Spring Promotion"` names the campaign tag (default: the template name; `--at`
+supplies the date); `--keep-link` sends the link exactly as pasted with no
+FlowIQ tags (clicks are counted, the sale will not show as WhatsApp). Only a
+button whose base is one of our short domains (`linklnk.io/{{1}}`) takes a
+link; a button that already points at the store takes the part after the
+slash. A whole short link pasted as the value is reduced to its code.
+
 **Link buttons (v0.7.5):** every button whose URL carries a `{{1}}` needs its own
 `--button paramN=` value (`param1` = the first such button, `param2` = the
 second). The dry run prints each button's final URL and stops if one is
@@ -909,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 |
@@ -1003,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
@@ -1241,25 +1342,41 @@ flowiq updates send .flowiq/updates/2026-09-10.json --yes       # the real send,
   (`app.flowiq.live/?changelog=1&entry=<id>`). `send` and `asset` are audited
   (`flowiq audit --endpoint team-updates`).
 
-### WhatsApp templates — `flowiq templates pull|list|show|create|status` (alias `tpl`)
+### WhatsApp templates — `flowiq templates pull|list|show|create|status|attempts` (alias `tpl`)
 
 Read an org's live templates straight from Meta (read-only), render any single
-row **including an unsubmitted DRAFT**, and submit new ones through the
-`create-meta-template` edge function.
+row **including an unsubmitted DRAFT**, submit new ones through the
+`create-meta-template` edge function, and read the **submission ledger** — every
+create call, including the ones that failed and why.
 
 ```bash
 flowiq templates pull <organization_id>   # → ./.flowiq/templates/<slug>.json (Meta-side truth)
 flowiq templates status <organization_id> --name booking   # poll approval
 flowiq templates show <organization_id> heritage_day_v2    # render ONE row, drafts included
 flowiq templates create <organization_id> --request-file req.json
+flowiq templates attempts <organization_id> --failed       # why a submit was refused (v0.8.1)
 ```
 
+**`attempts` is the only record of a FAILED submission (v0.8.1).** A refused
+submission writes no template row (so `status` cannot show it), never reaches
+Meta (so `pull` cannot either), and the server logs that used to be the only
+evidence expire after 24 hours. Every create call since 21 Sep 2026 — from the
+dashboard or this CLI — now writes a `template_submission_attempts` row, and
+`attempts` prints them newest first in SAST: `✓` submitted (Meta id + status at
+submit) or `✗` FAILED with the HTTP status, the short label and the sentence
+that names the cause, e.g. `HEADER format is DOCUMENT but the media at file_url
+is video/mp4 — point file_url at a document (pdf)`. That sentence is what to
+tell the client. `--failed` filters to refusals, `--name <substr>` to one
+template, `--limit <n>` (default 20, max 100), `--json` for the rows.
+
 **`show` is the only way to read a DRAFT from the terminal (v0.6.7).** A draft
 never reaches Meta, so `templates pull` cannot see it and neither can the
 broadcast introspector — before this, reviewing one meant opening the dialog.
 `show` prints the body with its examples substituted (as the customer will read
-it), then every carousel card: media URL, source filename, whether the Meta
-asset handle is present, card body, and each button's resolved URL. `--raw`
+it), then — for a carousel draft only (v0.8.1; a standard draft used to print
+the dialog's two default cards as a phantom carousel) — every carousel card:
+media URL, source filename, whether the Meta asset handle is present, card
+body, and each button's resolved URL. `--raw`
 also prints the escaped body so invisible whitespace is visible; `--json` gives
 the row.
 

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` |
@@ -167,6 +174,7 @@ several.
 | 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 a **CAROUSEL** template (v0.4.9) | Tag mode only: `flowiq bc send <org_id> --tag <batch-tag> --template <carousel_name> --body param1="Hi {{first_name}}" --commit`. Card images are automatic (each card's stored template image, type-verified per card); override with repeatable `--card-media <url>` (one per card, in order). If the cards carry `{{n}}` body variables or URL-button variables, the CLI tells you exactly what to put in a `--cards-file <path>` JSON (one entry per card: `header_media` / `body_params` / `button_payloads` / `url_vars`). Always sends via the python engine (any size); no CSV mode for carousels. |
+| Send a broadcast whose link button should open a page on the store, tracked | Paste the real link: `flowiq bc send <org_id> --tag <batch-tag> --template <name> --button param1="https://shop.co.za/collections/spring?ref=ig"` (dry run shows `→ linklnk.io/<code>`, the campaign tag and anything replaced) → `… --commit` mints the code and sends. `--link-campaign "Spring Promotion"` names the tag (default: the template name); `--keep-link` sends your link untouched with no FlowIQ tags (clicks counted, the sale will not show as WhatsApp) |
 | Send a template with TWO link buttons (e.g. one per product) and track clicks per batch | Mint two short links per batch with the same campaign and a different `--content` (e.g. `--content CycleHarmony_b01` and `--content NeuroShyft_b01`), then `flowiq bc send <org_id> --tag <batch-tag> --template <name> --button param1=<first-code> --button param2=<second-code>`. `param1` is the first link button on the template, `param2` the second. The dry run prints both final URLs and stops if either is missing. Tag mode only (v0.7.5). |
 | 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) |
@@ -184,6 +192,7 @@ several.
 | Check / create WhatsApp templates | `flowiq tpl pull <org_id>` / `flowiq tpl create <org_id> --request-file req.json` |
 | **Read a template you have not submitted yet (a DRAFT)** | `flowiq tpl show <org_id> <template_name>` — the ONLY way to see a draft from the terminal (`pull` reads Meta, and a draft never gets there). Renders the message as the customer will read it, every carousel card, and a **Checks** list of the things Meta would bounce it for |
 | Check a carousel before submitting it | `flowiq tpl show <org_id> <name>` and read **Checks**. It catches a card link using the wrong `{{n}}`, a missing greeting example, a bold/italic marker against a space (WhatsApp shows the literal `_`), wrong card counts and over-length text. It cannot know a card names a product you do not stock — read the card text against the shop yourself |
+| **A template would not submit and you want to know why** | `flowiq tpl attempts <org_id> --failed` — the submission ledger. Every create call since 21 Sep 2026, from the dashboard or the CLI, with the reason a refused one was refused (e.g. `HEADER format is DOCUMENT but the media at file_url is video/mp4`). A failed submit writes no template row and never reaches Meta, so this is the ONLY place it shows |
 | Manage Shopify/Woo platform webhooks | `flowiq wh pull <org_id>` → edit → `flowiq wh push <slug>` |
 | Manage outbound messaging webhooks (incl. their auth) | `flowiq mw pull <org_id>` → `flowiq mw push <slug> --dry-run` → push |
 | Create a brand-new client org | `flowiq org create --name "Client Name"` → then `agent create` on the printed id |

package/package.json

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

@@ -21,6 +21,11 @@
 //   • `flowiq bc --campaign`, which names the LOCAL .flowiq/campaigns/<x>.json
 //     file and the `bc-<x>` contact tag, not a UTM.
 // `--raw-campaign` bypasses normalisation entirely when you genuinely need it.
+//
+// MIRROR: api/_shared/campaign-naming.js is a byte-identical copy of this file
+// (the server normalises the tag for the dashboard's tracked links and for
+// `bc send --button <url>`; the npm tarball cannot reach api/). Edit BOTH, or
+// `npm test` fails on the parity check in campaign-naming.test.mjs.
 
 export const MONTHS = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"];
 
@@ -162,3 +167,11 @@ export function resolveContent(input) {
     notes: value && value !== original ? [`content "${original}" → "${value}"`] : [],
   };
 }
+
+/** A button label → utm_content: "CLICK HERE" → ClickHere, "Shop now" → ShopNow, "Plano" → Plano. */
+export function contentFromLabel(label) {
+  const words = String(label ?? "").replace(/[^A-Za-z0-9]+/g, " ").trim().split(/\s+/).filter(Boolean);
+  return words
+    .map((w) => (/^[A-Z0-9]+$/.test(w) && w.length > 1 ? w[0] + w.slice(1).toLowerCase() : w[0].toUpperCase() + w.slice(1)))
+    .join("");
+}

package/src/campaign-naming.test.mjs

@@ -74,3 +74,16 @@ test("dateToken / isConforming", () => {
   assert.ok(!isConforming("SpringPromotion"));
   assert.ok(!isConforming("9Sep_Spring_Promotion"));
 });
+
+// The server carries a byte-identical copy (api/_shared/campaign-naming.js) so the
+// dashboard's tracked links and `bc send --button <url>` name campaigns exactly the
+// way `links shorten` does. Skipped inside the npm tarball, where api/ does not exist.
+test("api/_shared/campaign-naming.js is a byte-identical mirror", async (t) => {
+  const { readFileSync, existsSync } = await import("node:fs");
+  const { fileURLToPath } = await import("node:url");
+  const path = await import("node:path");
+  const here = path.dirname(fileURLToPath(import.meta.url));
+  const mirror = path.join(here, "..", "..", "api", "_shared", "campaign-naming.js");
+  if (!existsSync(mirror)) { t.skip("api/ not present (npm tarball)"); return; }
+  assert.equal(readFileSync(mirror, "utf8"), readFileSync(path.join(here, "campaign-naming.js"), "utf8"));
+});

package/src/commands/broadcast.js

@@ -663,6 +663,101 @@ export function checkButtonParams(template, buttonParams) {
   return { aborts, warnings };
 }
 
+// ---------------------------------------------------------------------------
+// Tracked links from a PASTED url (v0.8.0, 18 Sep 2026)
+// ---------------------------------------------------------------------------
+// `--button param1=https://store.co.za/collections/new?ref=ig` — a real link
+// instead of a pre-minted code. The server (api/cli/links.js `tracked_link`, the
+// same engine the dashboard's send dialog uses) keeps their params, puts our
+// utm_source / utm_medium on, names utm_campaign `Date_Campaign` (default: the
+// template name, --link-campaign to override) and utm_content after the button,
+// follows the link to where it lands, and mints the code on --commit. The dry
+// run prints all of it first. `--keep-link` sends the link exactly as pasted
+// (a plain forward, no tags). Only a button whose base is one of OUR short
+// domains (`linklnk.io/{{1}}`) can take a full link; a client-domain button
+// takes the part after the slash.
+const OUR_SHORT_HOST_RE = /(^|\.)(linklnk\.io|chatcart\.io|yapi\.store)$/i;
+const SHORT_LINK_RE = /^https?:\/\/(?:[a-z0-9-]+\.)*(?:linklnk\.io|chatcart\.io|yapi\.store)\/([A-Za-z0-9_-]{3,64})\/?$/i;
+
+export function isHttpUrl(value) {
+  const v = String(value ?? "").trim();
+  if (!/^https?:\/\//i.test(v)) return false;
+  try { new URL(v); return true; } catch { return false; }
+}
+
+/** A whole short link pasted as a button value → its bare code (else null). */
+export function codeFromShortLink(value) {
+  const m = String(value ?? "").trim().match(SHORT_LINK_RE);
+  return m ? m[1] : null;
+}
+
+/** Which --button values are pasted links, and whether their button can take one. */
+export function planTrackedLinks(template, buttonParams) {
+  const plan = [];
+  const aborts = [];
+  const buttons = Array.isArray(template?.url_buttons) && template.url_buttons.length
+    ? template.url_buttons
+    : (template?.url_button?.present ? [{ param: "param1", url_base: template.url_button.url_base, text: template.url_button.text }] : []);
+  for (const [param, value] of Object.entries(buttonParams || {})) {
+    if (!isHttpUrl(value)) continue;
+    const btn = buttons.find((b) => b.param === param);
+    if (!btn) continue; // a value with no button is already a warning
+    let host = null;
+    try { host = new URL(String(btn.url_base || "").replace(/\{\{[^}]+\}\}/g, "x")).host; } catch { /* no host */ }
+    if (!host || !OUR_SHORT_HOST_RE.test(host)) {
+      aborts.push(`--button ${param} is a full link, but the template's "${btn.text ?? param}" button already points at ${host || "a fixed address"} — pass only the part after the slash`);
+      continue;
+    }
+    plan.push({ param, url: String(value).trim(), label: btn.text || param, host });
+  }
+  return { plan, aborts };
+}
+
+/** `--at "2026-08-05 09:00"` → `2026-08-05` for the campaign tag's date (else undefined). */
+export function linkDateFromAt(at) {
+  const m = String(at ?? "").trim().match(/^(\d{4}-\d{2}-\d{2})/);
+  return m ? m[1] : undefined;
+}
+
+/** Today in THIS machine's time zone as YYYY-MM-DD — sent with every tracked
+ *  link so the server (UTC) never dates a late-evening SAST send yesterday. */
+export function localDateIso(d = new Date()) {
+  return `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, "0")}-${String(d.getDate()).padStart(2, "0")}`;
+}
+
+async function resolveTrackedButtons(orgId, plan, { campaign, dateIso, keep, dryRun }) {
+  const out = {};
+  console.log("");
+  console.log(dryRun ? "Tracked links — the pasted url(s) become short codes on --commit:" : "Tracked links — minting short codes:");
+  for (const p of plan) {
+    let resp;
+    try {
+      resp = await http.post("links", {
+        organization_id: orgId, action: "tracked_link", url: p.url,
+        campaign, content: p.label, mode: keep ? "keep" : "tracked", domain: p.host,
+        ...(dateIso ? { date: dateIso } : {}), dry_run: dryRun,
+      });
+    } catch (e) {
+      console.error(`ABORT — tracked link for ${p.param} failed: ${e.message}`);
+      if (e.body?.error) console.error(`  ${e.body.error}`);
+      process.exit(1);
+    }
+    const r = resp.result || {};
+    if (!resp.success) { console.error(`ABORT — --button ${p.param} ${p.url}: ${r.note || r.state || "refused"}`); process.exit(1); }
+    const code = r.code || "<code-on-commit>";
+    console.log(`  Button "${p.label}" (${p.param}): ${p.url}`);
+    console.log(`     → ${p.host}/${code}${r.state === "reused" || r.state === "would_reuse" ? "  (existing row — keeps its click history)" : ""}`);
+    if (resp.utm) console.log(`     utm_campaign=${resp.utm.campaign} · utm_content=${resp.utm.content} · utm_source=${resp.utm.source} · utm_medium=${resp.utm.medium}`);
+    else console.log("     kept as pasted — no FlowIQ tags (clicks are counted; the sale will not show as WhatsApp)");
+    for (const rp of r.replaced || []) console.log(`     ⚠ replaced ${rp.key}=${rp.from} with ${rp.to}`);
+    for (const n of r.notes || []) console.log(`     ⚠ ${n}`);
+    if (r.full_url && r.full_url !== p.url) console.log(`     final: ${r.full_url}`);
+    for (const n of resp.utm?.naming || []) console.log(`     · ${n}`);
+    out[p.param] = code;
+  }
+  return out;
+}
+
 // ---------------------------------------------------------------------------
 // CSV → python fan-out builders (v0.6.0). Exported for the test harness.
 // ---------------------------------------------------------------------------
@@ -1364,7 +1459,12 @@ async function runTagPipeline(orgId, opts, { commitStage }) {
   }
   const bodyLiterals = Object.keys(opts.body || {}).length ? opts.body : (cfg?.body_params_literal ?? {});
   const buttonParams = resolveButtonParams(opts.button, cfg);
-  const buttonLiteral = buttonParams.param1 ?? null;
+  // A whole short link pasted as a value is just its code.
+  for (const [k, v] of Object.entries(buttonParams)) {
+    const code = codeFromShortLink(v);
+    if (code) { buttonParams[k] = code; console.log(`ℹ --button ${k}: using the code ${code} from the short link you pasted`); }
+  }
+  let buttonLiteral = buttonParams.param1 ?? null;
 
   // introspect + validate params arithmetically (the #132000 guard, pre-send)
   let intro;
@@ -1406,8 +1506,22 @@ async function runTagPipeline(orgId, opts, { commitStage }) {
   const buttonCheck = checkButtonParams(template, buttonParams);
   for (const w of buttonCheck.warnings) console.log(`⚠ ${w}`);
   aborts.push(...buttonCheck.aborts);
+  const linkPlan = planTrackedLinks(template, buttonParams);
+  aborts.push(...linkPlan.aborts);
   if (aborts.length) { for (const a of aborts) console.error(`ABORT — ${a}`); process.exit(1); }
 
+  // Pasted links → tracked short codes (dry run previews, --commit mints).
+  if (linkPlan.plan.length) {
+    const codes = await resolveTrackedButtons(orgId, linkPlan.plan, {
+      campaign: opts.linkCampaign || templateName,
+      dateIso: linkDateFromAt(opts.at) || localDateIso(),
+      keep: !!opts.keepLink,
+      dryRun: !commitStage,
+    });
+    Object.assign(buttonParams, codes);
+    buttonLiteral = buttonParams.param1 ?? null;
+  }
+
   // SCHEDULE (--at): validation above has already run, so a scheduled send is
   // gated by exactly the same checks as an immediate one (APPROVED, positional,
   // param arithmetic, header-media type). Instead of sending we queue the send

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/commands/templates.js

@@ -1,6 +1,7 @@
 // `flowiq templates pull <org_id>` / `list` — read WhatsApp templates from Meta.
 // `flowiq templates create <org> --request-file f.json` / `status` — §12 (create).
-// Pull is read-only via /cli/templates; create proxies /cli/meta-templates.
+// `flowiq templates attempts <org>` — the submission ledger, failures included.
+// Pull is read-only via /cli/templates; create/status/show/attempts use /cli/meta-templates.
 
 import fs from "node:fs/promises";
 import path from "node:path";
@@ -257,7 +258,10 @@ function renderDraft(d, opts) {
     }
   }
 
-  const cards = Array.isArray(d.carouselCards) ? d.carouselCards : [];
+  // A standard-mode draft still carries the dialog's two DEFAULT cards in
+  // carouselCards (the form snapshot is saved whole), so only carousel mode
+  // renders them — otherwise `show` invents a 2-card carousel that never existed.
+  const cards = d.templateMode === "carousel" && Array.isArray(d.carouselCards) ? d.carouselCards : [];
   if (cards.length) {
     console.log(`\n  CAROUSEL — ${cards.length} card(s)`);
     cards.forEach((c, i) => {
@@ -355,3 +359,64 @@ export async function show(orgId, name, opts = {}) {
   if (td.carousel?.cards) console.log(`  carousel:  ${td.carousel.cards.length} card(s) with stored header media`);
   console.log(`\n  For the message structure as Meta holds it: flowiq templates pull ${orgId}`);
 }
+
+// ── attempts ────────────────────────────────────────────────────────────────
+// The submission ledger: one row per create-meta-template call (dashboard or
+// CLI), including the ones our own guards or Meta refused. A FAILED submission
+// writes no `templates` row and never reaches Meta, so until this existed the
+// only record was the edge fn's logs — gone after 24 h. Yoga Life's two 10:11
+// failures on 21 Sep 2026 were recoverable that day and would not have been the next.
+function sast(iso) {
+  if (!iso) return "?";
+  try {
+    return new Date(iso).toLocaleString("en-ZA", {
+      timeZone: "Africa/Johannesburg", year: "numeric", month: "2-digit", day: "2-digit",
+      hour: "2-digit", minute: "2-digit", second: "2-digit", hour12: false,
+    }).replace(",", "");
+  } catch { return iso; }
+}
+
+export async function attempts(orgId, opts = {}) {
+  if (!UUID_RE.test(orgId)) {
+    console.error(`Error: "${orgId}" is not a valid organization UUID. Find it with: flowiq org list <name>`);
+    process.exit(1);
+  }
+  let resp;
+  try {
+    resp = await http.get("meta-templates", {
+      organization_id: orgId,
+      attempts: "1",
+      failed: opts.failed ? "1" : undefined,
+      limit: opts.limit ? String(opts.limit) : undefined,
+      name: opts.name,
+    });
+  } catch (e) {
+    console.error(`Attempts lookup failed: ${e.message}`);
+    process.exit(1);
+  }
+  if (!("attempts" in (resp || {}))) {
+    console.error("The API did not return a submission ledger — api/cli/meta-templates.js on the server is older than this CLI (needs the ?attempts=1 branch, CLI v0.8.1). Retry once the Vercel deploy of origin/main has landed.");
+    process.exit(1);
+  }
+  if (opts.json) { console.log(JSON.stringify(resp, null, 2)); return; }
+
+  const rows = resp.attempts || [];
+  if (!rows.length) {
+    console.log(opts.failed ? "(no failed submissions on record for this org)" : "(no template submissions on record for this org — the ledger started 21 Sep 2026)");
+    return;
+  }
+  console.log(`${rows.length} submission${rows.length === 1 ? "" : "s"}${opts.failed ? " (failed only)" : ""}, newest first (SAST):`);
+  for (const a of rows) {
+    const mark = a.outcome === "submitted" ? "✓" : "✗";
+    const who = a.source ? `  via ${a.source}` : "";
+    console.log(`\n  ${mark} ${sast(a.created_at)}  ${a.template_name || "(unnamed)"}${a.category ? ` [${a.category}]` : ""}${who}`);
+    if (a.outcome === "submitted") {
+      console.log(`      submitted to Meta — id ${a.meta_template_id || "?"}, status at submit ${a.meta_status || "?"}`);
+    } else {
+      console.log(`      FAILED (HTTP ${a.http_status ?? "?"}) ${a.error || ""}`);
+      if (a.message && a.message !== a.error) console.log(`      ${a.message}`);
+      if (a.meta_error?.error_user_msg && a.meta_error.error_user_msg !== a.message) console.log(`      Meta: ${a.meta_error.error_user_msg}`);
+    }
+  }
+  console.log(`\nA failed row is the reason the template is not in \`templates status\` — fix what the message names and submit again.`);
+}

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")
@@ -274,7 +331,7 @@ export function run(argv) {
   // templates (read WhatsApp templates from Meta; create via /cli/meta-templates)
   const templates = program.command("templates")
     .alias("tpl")
-    .description("Read an org's WhatsApp templates (pull/list/show — show also reads DRAFTS); create + submit to Meta (create/status)");
+    .description("Read an org's WhatsApp templates (pull/list/show — show also reads DRAFTS); create + submit to Meta (create/status); attempts = the submission ledger, failures included");
   templates.command("pull <organization_id>")
     .description("Fetch every live WhatsApp template from Meta into a local JSON snapshot")
     .action((orgId) => templatesCmd.pull(orgId));
@@ -294,6 +351,13 @@ export function run(argv) {
     .option("--raw", "also print the raw body text (escaped), so invisible whitespace is visible")
     .option("--json", "raw JSON row output")
     .action((orgId, name, opts) => templatesCmd.show(orgId, name, opts));
+  templates.command("attempts <organization_id>")
+    .description("The submission ledger — every create call, dashboard or CLI, INCLUDING the ones that failed and why (a failed submit writes no template row and never reaches Meta)")
+    .option("--failed", "only the failed submissions")
+    .option("--name <substr>", "filter by template name substring")
+    .option("--limit <n>", "rows to return (default 20, max 100)")
+    .option("--json", "raw JSON output")
+    .action((orgId, opts) => templatesCmd.attempts(orgId, opts));
 
   // 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, read/set its feature flags");
@@ -620,7 +684,9 @@ export function run(argv) {
     .option("--csv <file>", "path to the recipients CSV (per-row values)")
     .option("--tag <tag>", "send to every broadcast-safe contact carrying this tag (e.g. a segments batch tag)")
     .option("--body <k=v>", "with --tag: body param (repeatable), e.g. --body param1=\"Hi {{first_name}}\"", broadcastCmd.collectKV, {})
-    .option("--button <k=v>", "with --tag: dynamic URL button value, repeatable for a second button, e.g. --button param1=<code> --button param2=<code>", broadcastCmd.collectKV, {})
+    .option("--button <k=v>", "with --tag: dynamic URL button value, repeatable for a second button, e.g. --button param1=<code> --button param2=<code>. v0.8.0: paste the REAL link instead (--button param1=https://store.co.za/collections/new) and it becomes a tracked short code on --commit", broadcastCmd.collectKV, {})
+    .option("--link-campaign <name>", "with a pasted --button link: the utm_campaign, normalised to Date_Campaign (default: the template name, e.g. new_arrivals_v3 → 18Sep_NewArrivalsV3)")
+    .option("--keep-link", "with a pasted --button link: send it exactly as pasted — a plain forward, no FlowIQ utm tags (clicks are counted; the sale will not show as WhatsApp)")
     .option("--campaign <name>", "campaign id / config file slug (default: CSV filename / tag)")
     .option("--header-media <url>", "header image/video/doc URL for a media-header template (default: the template's own stored image)")
     .option("--card-media <url>", "with --tag, carousel templates: card image/video URL in card order (repeatable — one per card; default: each card's stored template image)", (v, acc) => (acc || []).concat([v]), [])

package/src/tracked-link.test.mjs

@@ -0,0 +1,57 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { isHttpUrl, codeFromShortLink, planTrackedLinks, linkDateFromAt, localDateIso } from "./commands/broadcast.js";
+
+const ours = { dynamic_url_buttons: 2, url_button: { present: true, url_base: "https://linklnk.io/{{1}}", text: "Shop" },
+  url_buttons: [{ param: "param1", url_base: "https://linklnk.io/{{1}}", text: "Shop" }, { param: "param2", url_base: "https://barkyn.linklnk.io/{{1}}", text: "Plano" }] };
+const theirs = { dynamic_url_buttons: 1, url_button: { present: true, url_base: "https://store.co.za/{{1}}", text: "Shop" },
+  url_buttons: [{ param: "param1", url_base: "https://store.co.za/{{1}}", text: "Shop" }] };
+
+test("a pasted link is recognised, a code or a path is not", () => {
+  assert.equal(isHttpUrl("https://store.co.za/collections/new?ref=ig"), true);
+  assert.equal(isHttpUrl("aB3xY9"), false);
+  assert.equal(isHttpUrl("collections/new"), false);
+  assert.equal(isHttpUrl("store.co.za/collections/new"), false);
+});
+
+test("a whole short link pasted as a value gives back its code", () => {
+  assert.equal(codeFromShortLink("https://linklnk.io/aB3xY9"), "aB3xY9");
+  assert.equal(codeFromShortLink("https://barkyn.linklnk.io/pV2zqM/"), "pV2zqM");
+  assert.equal(codeFromShortLink("https://store.co.za/aB3xY9"), null);
+  assert.equal(codeFromShortLink("aB3xY9"), null);
+});
+
+test("links on our-domain buttons are planned, codes are left alone", () => {
+  const { plan, aborts } = planTrackedLinks(ours, { param1: "https://store.co.za/a?ref=ig", param2: "abc123" });
+  assert.deepEqual(aborts, []);
+  assert.deepEqual(plan, [{ param: "param1", url: "https://store.co.za/a?ref=ig", label: "Shop", host: "linklnk.io" }]);
+});
+
+test("a subdomain of ours counts as ours", () => {
+  const { plan } = planTrackedLinks(ours, { param1: "x", param2: "https://barkyn.com/plan" });
+  assert.equal(plan[0].host, "barkyn.linklnk.io");
+});
+
+test("a full link on a client-domain button aborts with the reason", () => {
+  const { plan, aborts } = planTrackedLinks(theirs, { param1: "https://store.co.za/collections/new" });
+  assert.deepEqual(plan, []);
+  assert.match(aborts[0], /already points at store.co.za/);
+  assert.match(aborts[0], /part after the slash/);
+});
+
+test("older server shape (url_button only) still plans param1", () => {
+  const { plan } = planTrackedLinks({ url_button: ours.url_button }, { param1: "https://store.co.za/a" });
+  assert.equal(plan.length, 1);
+  assert.equal(plan[0].param, "param1");
+});
+
+test("--at gives the campaign tag its date", () => {
+  assert.equal(linkDateFromAt("2026-09-24 10:00"), "2026-09-24");
+  assert.equal(linkDateFromAt(undefined), undefined);
+  assert.equal(linkDateFromAt("tomorrow"), undefined);
+});
+
+test("the tag's date is the machine's local day, not UTC", () => {
+  assert.equal(localDateIso(new Date(2026, 8, 18, 0, 47)), "2026-09-18");
+  assert.match(localDateIso(), /^\d{4}-\d{2}-\d{2}$/);
+});