@flowapt/flowiq-cli 0.7.4 → 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
@@ -455,8 +455,43 @@ instead of a CSV. Same guards, same status log, same resume:
 ```bash
 flowiq bc send <org_id> --tag july-promo-batch-01 --template fresh_drop_v1 \
   --body param1="Hi {{first_name}}" [--button param1=<short-code>] --commit
+
+# A template with TWO link buttons (v0.7.5), e.g. one per product: one --button per button,
+# in the order the buttons appear on the template.
+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
+missing (WhatsApp rejects the whole message when a link button is empty); a
+value with no button to go to is ignored with a warning. Swapping the codes per
+batch is how one campaign gets per-batch click counts: mint each batch's links
+with the same `--campaign` and a different `--content`. CSV mode fills one link
+button only, so a two-button template is refused there.
+
 Values are shared across the tag (use `{{first_name}}` etc. for per-contact
 personalization — resolved server-side). Supported per-contact tokens:
 `{{first_name}}` `{{full_name}}` `{{email}}` `{{phone_number}}`
@@ -1227,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,8 @@ 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) |
 | Check how a broadcast is landing (accepted → delivered → read, plus failed/pending) | `flowiq bc status <org_id> <broadcastId>` (from the send output, or `bc list-remote`) |
@@ -183,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.4",
+  "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/button-params.test.mjs

@@ -0,0 +1,50 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { resolveButtonParams, checkButtonParams } from "./commands/broadcast.js";
+
+const oneBtn = { dynamic_url_buttons: 1, url_button: { present: true } };
+const twoBtn = { dynamic_url_buttons: 2, url_button: { present: true } };
+const noBtn = { dynamic_url_buttons: 0, url_button: { present: false } };
+
+test("flags win over the saved campaign", () => {
+  assert.deepEqual(resolveButtonParams({ param1: "a", param2: "b" }, { button_params_literal: { param1: "x" } }), { param1: "a", param2: "b" });
+});
+
+test("saved multi-button values, then the pre-0.7.5 single value", () => {
+  assert.deepEqual(resolveButtonParams({}, { button_params_literal: { param1: "x", param2: "y" } }), { param1: "x", param2: "y" });
+  assert.deepEqual(resolveButtonParams({}, { button_param_literal: "old" }), { param1: "old" });
+  assert.deepEqual(resolveButtonParams(undefined, null), {});
+});
+
+test("empty values are dropped", () => {
+  assert.deepEqual(resolveButtonParams({ param1: "a", param2: "" }, null), { param1: "a" });
+});
+
+test("one dynamic button: same message as before", () => {
+  assert.deepEqual(checkButtonParams(oneBtn, {}).aborts, ["template has a dynamic URL button — pass --button param1=<code>"]);
+  assert.deepEqual(checkButtonParams(oneBtn, { param1: "abc" }), { aborts: [], warnings: [] });
+});
+
+test("two dynamic buttons need both values", () => {
+  const r = checkButtonParams(twoBtn, { param1: "abc" });
+  assert.equal(r.aborts.length, 1);
+  assert.match(r.aborts[0], /2 dynamic URL buttons/);
+  assert.match(r.aborts[0], /missing param2/);
+  assert.deepEqual(checkButtonParams(twoBtn, { param1: "a", param2: "b" }), { aborts: [], warnings: [] });
+});
+
+test("a value with no button is a warning, not an abort", () => {
+  const r = checkButtonParams(oneBtn, { param1: "a", param2: "b" });
+  assert.deepEqual(r.aborts, []);
+  assert.match(r.warnings[0], /param2 ignored/);
+  assert.match(checkButtonParams(noBtn, { param1: "a" }).warnings[0], /0 dynamic URL buttons/);
+});
+
+test("non-param keys abort", () => {
+  assert.match(checkButtonParams(oneBtn, { code: "a", param1: "b" }).aborts[0], /param1\.\.N/);
+});
+
+test("older server without dynamic_url_buttons falls back to url_button", () => {
+  assert.equal(checkButtonParams({ url_button: { present: true } }, {}).aborts.length, 1);
+  assert.equal(checkButtonParams({ url_button: { present: false } }, {}).aborts.length, 0);
+});

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

@@ -502,6 +502,7 @@ function validateRows(template, mapping, headers, rows, illegalChars, headerMedi
   const aborts = [];
   if (template.status !== "APPROVED") aborts.push(`V-1: template status is ${template.status} — only APPROVED templates send`);
   if (template.parameter_format !== "POSITIONAL") aborts.push("V-2: NAMED templates are not supported in v1");
+  if ((template.dynamic_url_buttons ?? 0) > 1) aborts.push(`V-3: this template has ${template.dynamic_url_buttons} dynamic URL buttons; CSV mode fills one — use tag mode: flowiq bc send <org> --tag <tag> --template <name> --button param1=<code> --button param2=<code>`);
   if (template.is_carousel) aborts.push("V-3: carousel templates are TAG-MODE only — use: flowiq bc send <org> --tag <tag> --template <name> (the python engine sends carousels; per-row CSV carousel sends are not supported)");
   // Media headers (image/video/document) ARE supported — they just need an image
   // URL, exactly like the dashboard. Resolved as --header-media / saved mapping /
@@ -604,12 +605,159 @@ function renderPreview(template, sample, headerMedia) {
   console.log(`Row ${sample.rownum}  →  ${sample.number}   [VALID]${sample.sanitized ? " (sanitized)" : ""}`);
   if (headerMedia) console.log(`  Header (${template.header_type}): ${headerMedia}`);
   console.log(`  Body:\n    ${bodyText.replace(/\n/g, "\n    ")}`);
+  // Two-dynamic-button templates (17 Sep 2026): show every button with its own value.
+  if (Array.isArray(template.url_buttons) && template.url_buttons.length && sample.buttonParams) {
+    for (const b of template.url_buttons) {
+      const v = sample.buttonParams[b.param];
+      if (v == null) continue;
+      console.log(`  Button "${b.text ?? "URL"}" (${b.param}) → ${b.url_base.replace(/\{\{[^}]+\}\}/, v)}`);
+    }
+    return;
+  }
   if (template.url_button?.present && sample.buttonValue != null) {
     const url = template.url_button.url_base.replace(/\{\{[^}]+\}\}/, sample.buttonValue);
     console.log(`  Button "${template.url_button.text ?? "URL"}" → ${url}`);
   }
 }
 
+/** Tag-mode URL-button values: every `--button paramN=…` flag, else the saved
+ *  campaign's values (new `button_params_literal`, or the pre-0.7.5 single
+ *  `button_param_literal` as param1). Empty values are dropped. */
+export function resolveButtonParams(flagButtons, cfg) {
+  const out = {};
+  const src = flagButtons && Object.keys(flagButtons).length
+    ? flagButtons
+    : (cfg?.button_params_literal && Object.keys(cfg.button_params_literal).length
+      ? cfg.button_params_literal
+      : (cfg?.button_param_literal ? { param1: cfg.button_param_literal } : {}));
+  for (const [k, v] of Object.entries(src)) {
+    if (v == null || String(v) === "") continue;
+    out[k] = String(v);
+  }
+  return out;
+}
+
+/** Checks tag-mode button values against the template's dynamic URL buttons.
+ *  Every button needs its own value (python / send-template send '' for a
+ *  missing one and Meta rejects the message); a value with no button to go to
+ *  is a warning (it is ignored by both engines). */
+export function checkButtonParams(template, buttonParams) {
+  const aborts = [];
+  const warnings = [];
+  const keys = Object.keys(buttonParams || {});
+  const bad = keys.filter((k) => !/^param\d+$/.test(k));
+  if (bad.length) aborts.push(`--button keys must be param1..N (got ${bad.join(", ")})`);
+  const need = Number.isInteger(template.dynamic_url_buttons)
+    ? template.dynamic_url_buttons
+    : (template.url_button?.present ? 1 : 0);
+  const missing = [];
+  for (let i = 1; i <= need; i++) if (!buttonParams?.[`param${i}`]) missing.push(`param${i}`);
+  if (missing.length) {
+    const how = Array.from({ length: need }, (_, i) => `--button param${i + 1}=<code>`).join(" ");
+    aborts.push(need === 1
+      ? "template has a dynamic URL button — pass --button param1=<code>"
+      : `template has ${need} dynamic URL buttons — pass ${how} (missing ${missing.join(", ")})`);
+  }
+  const extra = keys.filter((k) => /^param\d+$/.test(k) && Number(k.slice(5)) > need);
+  if (extra.length) warnings.push(`--button ${extra.join(", ")} ignored: template has ${need} dynamic URL button${need === 1 ? "" : "s"}`);
+  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.
 // ---------------------------------------------------------------------------
@@ -695,7 +843,9 @@ async function sendOne(apiUrl, orgId, templateName, row, headerMedia) {
     templateName,
     whatsappNumber: row.number,
     bodyParameters,
-    ...(row.buttonValue != null ? { buttonParameters: { param1: row.buttonValue } } : {}),
+    ...(row.buttonParams && Object.keys(row.buttonParams).length
+      ? { buttonParameters: row.buttonParams }
+      : (row.buttonValue != null ? { buttonParameters: { param1: row.buttonValue } } : {})),
     // Static media header (same field the dashboard passes for image/video/doc
     // headers) — /api/send-template renders it onto the HEADER component.
     ...(headerMedia ? { headerMedia } : {}),
@@ -1241,11 +1391,12 @@ function reportRoutingResult(orgId, rr, broadcastId) {
   }
 }
 
-async function runPythonTagSend(orgId, { opts, tag, templateName, template, headerMedia, bodyLiterals, buttonLiteral, commitStage, cardOverrides = null, cardLines = [], replyRouting = null }) {
+async function runPythonTagSend(orgId, { opts, tag, templateName, template, headerMedia, bodyLiterals, buttonLiteral, buttonParams = null, commitStage, cardOverrides = null, cardLines = [], replyRouting = null }) {
+  const buttons = buttonParams && Object.keys(buttonParams).length ? buttonParams : (buttonLiteral ? { param1: buttonLiteral } : null);
   const reqBody = (dryRun) => ({
     action: "send-python", organization_id: orgId, tag, template_name: templateName,
     body_parameters: bodyLiterals,
-    ...(buttonLiteral ? { button_parameters: { param1: buttonLiteral } } : {}),
+    ...(buttons ? { button_parameters: buttons } : {}),
     ...(headerMedia ? { header_media: headerMedia } : {}),
     ...(cardOverrides ? { card_overrides: cardOverrides } : {}),
     ...(replyRouting ? { reply_routing: replyRouting } : {}),
@@ -1262,7 +1413,7 @@ async function runPythonTagSend(orgId, { opts, tag, templateName, template, head
   console.log(`Engine: PYTHON (yapi.store/meta-broadcast) — fire-and-forget, python-tracked.`);
   console.log(`Tag "${tag}": ${total} eligible contact(s) (allow_broadcast + not blocked, resolved server-side).`);
   const sampleNum = dry.sample_contacts?.[0]?.whatsapp_id || dry.sample_contacts?.[0]?.phone_number || "<first eligible>";
-  renderPreview(template, { rownum: 1, number: sampleNum, values: bodyLiterals, buttonValue: buttonLiteral }, headerMedia);
+  renderPreview(template, { rownum: 1, number: sampleNum, values: bodyLiterals, buttonValue: buttonLiteral, buttonParams: buttons }, headerMedia);
   printCarouselPlan(cardOverrides, cardLines);
   if (Object.values(bodyLiterals).some((v) => /\{\{(first_name|full_name|email|phone_number|whatsapp_id)\}\}/.test(String(v)))) {
     console.log("  ({{first_name}}-style tokens are resolved PER CONTACT by python)");
@@ -1307,7 +1458,13 @@ async function runTagPipeline(orgId, opts, { commitStage }) {
     process.exit(1);
   }
   const bodyLiterals = Object.keys(opts.body || {}).length ? opts.body : (cfg?.body_params_literal ?? {});
-  const buttonLiteral = (opts.button && opts.button.param1) ?? cfg?.button_param_literal ?? null;
+  const buttonParams = resolveButtonParams(opts.button, cfg);
+  // 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;
@@ -1319,7 +1476,7 @@ async function runTagPipeline(orgId, opts, { commitStage }) {
     ? (opts.headerMedia || cfg?.header_media || template.header_media_default || null)
     : null;
   const headerCheck = await verifyHeaderMedia(template, headerMedia);
-  console.log(`Template ${template.name} [${template.status}] — ${template.parameter_format}, ${template.body_var_count} body var(s), header ${template.header_type}${headerCheck.label}${template.url_button?.present ? ", dynamic URL button" : ""}${template.is_carousel ? `, CAROUSEL (${template.carousel_cards?.length ?? "?"} cards)` : ""}`);
+  console.log(`Template ${template.name} [${template.status}] — ${template.parameter_format}, ${template.body_var_count} body var(s), header ${template.header_type}${headerCheck.label}${(template.dynamic_url_buttons ?? 0) > 1 ? `, ${template.dynamic_url_buttons} dynamic URL buttons` : (template.url_button?.present ? ", dynamic URL button" : "")}${template.is_carousel ? `, CAROUSEL (${template.carousel_cards?.length ?? "?"} cards)` : ""}`);
   const aborts = [];
   if (headerCheck.status === "mismatch") aborts.push(headerMismatchMessage(template, headerMedia, headerCheck.contentType, { explicit: !!opts.headerMedia }));
   if (template.status !== "APPROVED") aborts.push(`template status is ${template.status} — only APPROVED templates send`);
@@ -1346,9 +1503,25 @@ async function runTagPipeline(orgId, opts, { commitStage }) {
   const keys = Object.keys(bodyLiterals);
   if (keys.some((k) => !/^param\d+$/.test(k))) aborts.push(`--body keys must be param1..N (got ${keys.join(", ")})`);
   if (keys.length !== template.body_var_count) aborts.push(`template expects ${template.body_var_count} body param(s), you provided ${keys.length} (--body paramN=…). Values may use {{first_name}}/{{full_name}}/{{email}}/{{phone_number}} — resolved per contact.`);
-  if (template.url_button?.present && !buttonLiteral) aborts.push("template has a dynamic URL button — pass --button param1=<code>");
+  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
@@ -1360,7 +1533,7 @@ async function runTagPipeline(orgId, opts, { commitStage }) {
   // picked — so a mistyped team stops the run in the dry run, not after a send.
   const replyRouting = await checkRouting(orgId, opts);
 
-  if (opts.at) return scheduleTagSend(orgId, { opts, tag, templateName, template, headerMedia, bodyLiterals, buttonLiteral, commitStage, cardOverrides, cardLines, replyRouting });
+  if (opts.at) return scheduleTagSend(orgId, { opts, tag, templateName, template, headerMedia, bodyLiterals, buttonLiteral, buttonParams, commitStage, cardOverrides, cardLines, replyRouting });
 
   // ENGINE ROUTING (policy): any send of MORE THAN 10 recipients ALWAYS uses the
   // python /meta-broadcast engine (the proven bulk sender). --python forces it at
@@ -1377,7 +1550,7 @@ async function runTagPipeline(orgId, opts, { commitStage }) {
     console.log("Reply routing → PYTHON engine at any size (the routing is stored on the single broadcast python creates).");
   }
   if (opts.python || template.is_carousel || replyRouting) {
-    return runPythonTagSend(orgId, { opts, tag, templateName, template, headerMedia, bodyLiterals, buttonLiteral, commitStage, cardOverrides, cardLines, replyRouting });
+    return runPythonTagSend(orgId, { opts, tag, templateName, template, headerMedia, bodyLiterals, buttonLiteral, buttonParams, commitStage, cardOverrides, cardLines, replyRouting });
   }
 
   // resolve the tag server-side (broadcast-safe recipients only). A >2000 tag
@@ -1387,13 +1560,13 @@ async function runTagPipeline(orgId, opts, { commitStage }) {
   catch (e) {
     if (e.status === 413) {
       console.log(`Tag "${tag}" has >2000 contacts → PYTHON engine (any send >${PYTHON_MIN} uses python).`);
-      return runPythonTagSend(orgId, { opts, tag, templateName, template, headerMedia, bodyLiterals, buttonLiteral, commitStage });
+      return runPythonTagSend(orgId, { opts, tag, templateName, template, headerMedia, bodyLiterals, buttonLiteral, buttonParams, commitStage });
     }
     console.error(`Tag resolution failed: ${e.message}`); if (e.body?.error) console.error(`  ${e.body.error}`); process.exit(1);
   }
   if (resolved.recipients.length > PYTHON_MIN) {
     console.log(`Tag "${tag}": ${resolved.recipients.length} sendable (>${PYTHON_MIN}) → PYTHON engine (any send >${PYTHON_MIN} uses python).`);
-    return runPythonTagSend(orgId, { opts, tag, templateName, template, headerMedia, bodyLiterals, buttonLiteral, commitStage });
+    return runPythonTagSend(orgId, { opts, tag, templateName, template, headerMedia, bodyLiterals, buttonLiteral, buttonParams, commitStage });
   }
   console.log(`Tag "${tag}" on ${resolved.organization_name}: ${resolved.tagged_total} contact(s), ${resolved.recipients.length} sendable, ${resolved.excluded.length} excluded (opt-out/archived/blocked).`);
   if (!resolved.recipients.length) { console.log("Nothing sendable under this tag."); return; }
@@ -1401,7 +1574,7 @@ async function runTagPipeline(orgId, opts, { commitStage }) {
   const values = {};
   for (const [k, v] of Object.entries(bodyLiterals)) values[k] = String(v);
   let sendable = resolved.recipients.map((r, i) => ({
-    rownum: i + 1, number: r.number, values, buttonValue: buttonLiteral, contactName: r.full_name,
+    rownum: i + 1, number: r.number, values, buttonValue: buttonLiteral, buttonParams, contactName: r.full_name,
   }));
   if (opts.limit) sendable = sendable.slice(0, Number(opts.limit));
 
@@ -1447,7 +1620,7 @@ async function runTagPipeline(orgId, opts, { commitStage }) {
     schema_version: 1, campaign, mode: "tag",
     organization_id: orgId, organization_slug: slugify(resolved.organization_name, orgId.slice(0, 8)),
     template_name: templateName, tag,
-    body_params_literal: bodyLiterals, button_param_literal: buttonLiteral,
+    body_params_literal: bodyLiterals, button_param_literal: buttonLiteral, button_params_literal: buttonParams,
     ...(headerMedia ? { header_media: headerMedia } : {}),
     created_at: cfg?.created_at ?? new Date().toISOString(),
   });
@@ -1539,7 +1712,8 @@ const fmtSast = (iso) =>
   new Date(iso).toLocaleString("en-ZA", { timeZone: "Africa/Johannesburg", dateStyle: "medium", timeStyle: "short" });
 
 /** Queue a tag broadcast to fire later (server writes the api_request_queue row). */
-async function scheduleTagSend(orgId, { opts, tag, templateName, template, headerMedia, bodyLiterals, buttonLiteral, commitStage, cardOverrides = null, cardLines = [], replyRouting = null }) {
+async function scheduleTagSend(orgId, { opts, tag, templateName, template, headerMedia, bodyLiterals, buttonLiteral, buttonParams = null, commitStage, cardOverrides = null, cardLines = [], replyRouting = null }) {
+  const buttons = buttonParams && Object.keys(buttonParams).length ? buttonParams : (buttonLiteral ? { param1: buttonLiteral } : null);
   const when = parseSastAt(opts.at);
   if (when.error) { console.error(`Error: --at ${when.error}`); process.exit(1); }
   if (new Date(when.iso).getTime() <= Date.now()) {
@@ -1549,7 +1723,7 @@ async function scheduleTagSend(orgId, { opts, tag, templateName, template, heade
   const needsApproval = !!opts.needsApproval;
 
   console.log("");
-  renderPreview(template, { rownum: 1, number: "(resolved at send time)", values: bodyLiterals, buttonValue: buttonLiteral }, headerMedia);
+  renderPreview(template, { rownum: 1, number: "(resolved at send time)", values: bodyLiterals, buttonValue: buttonLiteral, buttonParams: buttons }, headerMedia);
   printCarouselPlan(cardOverrides, cardLines);
   if (Object.values(bodyLiterals).some((v) => /\{\{(first_name|full_name|email|phone_number|whatsapp_id)\}\}/.test(String(v)))) {
     console.log("  ({{first_name}}-style tokens are resolved PER CONTACT at send time)");
@@ -1578,7 +1752,7 @@ async function scheduleTagSend(orgId, { opts, tag, templateName, template, heade
       scheduled_for: when.iso,
       needs_approval: needsApproval,
       body_parameters: bodyLiterals,
-      ...(buttonLiteral ? { button_parameters: { param1: buttonLiteral } } : {}),
+      ...(buttons ? { button_parameters: buttons } : {}),
       ...(headerMedia ? { header_media: headerMedia } : {}),
       ...(cardOverrides ? { card_overrides: cardOverrides } : {}),
       ...(replyRouting ? { reply_routing: replyRouting } : {}),

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 param, e.g. --button param1=<short-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}$/);
+});