@flowapt/flowiq-cli 0.7.5 → 0.8.1

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
@@ -1241,25 +1262,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

@@ -167,6 +167,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 +185,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.8.1",
   "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/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

@@ -274,7 +274,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 +294,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 +627,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}$/);
+});