@wrangled/cli 0.3.147 → 0.3.149

package/dist/guide.js

@@ -528,6 +528,9 @@ ${cli} meta ads cancel-turn-on <ad-id> --reason "<why>"   cancel a paused ad's s
 ${cli} meta audience create --account act_<id> --name "<name>" --kind website|video|page|instagram --retention-days <n> (--pixel <id> | --video <id> --watched 50% | --page <id> --engagement engaged | --instagram <id> --engagement engaged) --idempotency-key <key>   make a custom audience in an account on the control list
 ${cli} meta audience lookalike --account act_<id> --name "<name>" --seed <audience-id> --country US --percent 1 --idempotency-key <key>   make a lookalike of a custom audience there; customer-list upload is not offered
 ${cli} meta ad preview <ad-id> [--placement <ad_format>]... | meta ad review <ad-id>   Meta's preview links of an ad, or whether Meta approved it and why not, asked now
+${cli} meta ad status <ad-id> [--name <expected>]   the ad's status, id and name from Meta now; with --name, exits 1 unless it is active and its id and name match
+${cli} meta ad pause <ad-id> --idempotency-key <key> --reason "<why>" [--name "<expected>"] [--run <run-id>]   pause one ad (it can only pause) and read it from Meta again; exits 0 only when it reads PAUSED; the same key never pauses twice
+${cli} meta ad pauses [<ad-id>] [--since <YYYY-MM-DD>]   every pause attempt with its result, refusals too
 ${cli} meta lead-forms <page-id> | meta targeting search "<words>" [--account act_<id>]   a Page's lead forms, or interest targeting ids, read from Meta
 ${cli} meta adset budget <id> | meta campaign budget <id> (--percent <n> | --daily <n>) --reason "<why>"   change a daily budget within the workspace's limits
 ${cli} meta adset edit <id> (--name "<name>" | --targeting @spec.json | --bid-strategy <s> [--bid-amount <n>] | --optimization-goal <goal>) --reason "<why>"   edit an ad set, never turning it on or off
@@ -564,6 +567,7 @@ ${cli} facts [--kind <kind>] [--subject <type>[:<ref>]] [--status <status>] [--j
 ${cli} number-alerts [--since <date>]   the key numbers that swung far from normal, day by day
 ${cli} facts propose --file <fact.json>   suggest a fact for a person to confirm
 ${cli} lessons [--status active|retired] [--about ads|pages|funnel|messages|cross_channel] [--dimension <d>] | lessons add --file <lesson.json> | lessons retire <id> --note "<why>"   lessons from winners and flops, writing one, retiring one
+${cli} tests p1   this brand's P1 test ads by verdict, judged on its own sales against its P1 thresholds, with Meta's count beside
 ${cli} tests [--status <status>] [--funnel <key>] [--limit <n>] | tests show <id> | tests draft --file <test.json> | tests start <id> | tests abandon <id> [--note "<why>"] | tests results <id> | tests decide <id> --decision <d> [--note "<why>"]   funnel tests, one change each
 ${cli} ads tags [--ad <id>] [--status <status>] [--limit <n>] | ads tag --file <tags.json>   the marketing tags of ads not made here, and suggesting them
 ${cli} ads names [--unparsed]   Meta ad names and the tags each gives; --unparsed lists those that fit no pattern

package/dist/main.js

@@ -30,6 +30,7 @@ import { SKILL_NAME_PATTERN } from "./skill-zip.js";
 import { installSkillFolder, operatorConnection, packSkill, parseSkillRef, readSkillFolder, unpackSkill, } from "./skills.js";
 import { versionAtLeast } from "./version.js";
 const DEFAULT_WAIT_SECONDS = 300;
+const META_AD_PAUSE_USAGE = 'meta ad pause <ad-id> --idempotency-key <key> --reason "<why>" [--name "<expected>"] [--run <run-id>]';
 const META_CHANGE_COLUMNS = ["id", "level", "object", "change", "status", "when", "by", "reason"];
 const GOOGLE_ADS_CHANGE_COLUMNS = ["id", "account", "level", "object", "change", "status", "when", "by", "reason"];
 const AD_CHANGE_COLUMNS = ["platform", ...GOOGLE_ADS_CHANGE_COLUMNS];
@@ -1997,6 +1998,83 @@ const commands = {
                 console.log(`Issue${issue.level === null ? "" : ` (${issue.level.toLowerCase()})`}: ${[issue.summary, issue.message].filter(Boolean).join(". ")}`);
         },
     },
+    "meta ad status": {
+        usage: "meta ad status <ad-id> [--name <expected>]   the ad's status, id and name from Meta now; with --name, exits 1 unless it is safe to pause",
+        async run(args, options) {
+            if (args.length !== 1)
+                throw new CliError("Usage: meta ad status <ad-id> [--name <expected>]", exitCodes.usage);
+            const query = options.name === undefined ? "" : `?${new URLSearchParams({ name: options.name })}`;
+            const live = await api(await resolveConnection(options), `/api/v1/meta/ads/${encodeURIComponent(args[0])}/status${query}`);
+            const failed = live.check && [!live.check.active && "it is not active", !live.check.idMatches && "Meta's id differs", !live.check.nameMatches && "its name differs"].filter((f) => f !== false);
+            if (options.format === "json")
+                printJson(live);
+            else {
+                printFields({
+                    ad: live.adId,
+                    id: live.id,
+                    name: live.name,
+                    status: live.status,
+                    "effective status": live.effectiveStatus,
+                    "read at": live.readAt,
+                    check: failed && (failed.length === 0 ? "ok" : `failed: ${failed.join(", ")}`),
+                });
+            }
+            if (failed && failed.length > 0) {
+                throw new CliError(`Ad ${live.adId} is not safe to pause as "${live.check.expectedName}": ${failed.join(", ")} (Meta says ${live.effectiveStatus}, id ${live.id ?? "none"}, name "${live.name ?? ""}").`, exitCodes.error);
+            }
+        },
+    },
+    "meta ad pause": {
+        usage: `${META_AD_PAUSE_USAGE}   pause one ad, never anything else, and read it from Meta again to confirm; exits 1 unless it reads PAUSED`,
+        async run(args, options) {
+            if (options.status !== undefined && options.status.toLowerCase() !== "paused") {
+                throw new CliError(`meta ad pause only pauses; it cannot set status ${options.status}. Usage: ${META_AD_PAUSE_USAGE}`, exitCodes.usage);
+            }
+            if (args.length !== 1 || !options.idempotencyKey || !options.reason)
+                throw new CliError(`Usage: ${META_AD_PAUSE_USAGE}`, exitCodes.usage);
+            const attempt = await api(await resolveConnection(options), `/api/v1/meta/ads/${encodeURIComponent(args[0])}/pause`, {
+                idempotencyKey: options.idempotencyKey,
+                reason: options.reason,
+                ...(options.name === undefined ? {} : { name: options.name }),
+                ...(options.run === undefined ? {} : { runId: options.run }),
+            });
+            if (options.format === "json")
+                printJson(attempt);
+            else {
+                printFields({
+                    ad: attempt.adId,
+                    result: attempt.result,
+                    before: attempt.beforeStatus,
+                    after: attempt.afterStatus,
+                    "effective status": attempt.effectiveStatus,
+                    "read at": attempt.readAt,
+                    change: attempt.changeId,
+                    attempt: attempt.id,
+                    error: attempt.error,
+                });
+            }
+            if (attempt.result !== "paused" && attempt.result !== "already_paused") {
+                throw new CliError(`Ad ${attempt.adId} is not confirmed paused (${attempt.result})${attempt.error === null ? "" : `: ${attempt.error}`}`, exitCodes.error);
+            }
+        },
+    },
+    "meta ad pauses": {
+        usage: "meta ad pauses [<ad-id>] [--since <YYYY-MM-DD>]   every meta ad pause attempt, newest first, refusals too",
+        async run(args, options) {
+            if (args.length > 1)
+                throw new CliError("Usage: meta ad pauses [<ad-id>] [--since <YYYY-MM-DD>]", exitCodes.usage);
+            const query = new URLSearchParams();
+            if (args[0] !== undefined)
+                query.set("adId", args[0]);
+            if (options.since)
+                query.set("since", options.since);
+            const { attempts } = await api(await resolveConnection(options), `/api/v1/meta/pause-attempts${query.size ? `?${query}` : ""}`);
+            if (options.format === "json")
+                return printJson({ attempts });
+            const rows = attempts.map((a) => ({ when: a.createdAt, ad: a.adId, result: a.result, before: a.beforeStatus, after: a.afterStatus, key: a.idempotencyKey, by: a.requestedBy, error: a.error }));
+            console.log(rows.length ? renderTable(["when", "ad", "result", "before", "after", "key", "by", "error"], rows) : "No pause attempts yet.");
+        },
+    },
     "meta lead-forms": {
         usage: "meta lead-forms <page-id>   a Facebook Page's lead forms, for a lead ad",
         async run(args, options) {
@@ -3076,6 +3154,17 @@ const commands = {
             console.log(renderTable(TEST_COLUMNS, tests.map(testRow)));
         },
     },
+    "tests p1": {
+        usage: "tests p1   this brand's P1 test ads by verdict (working, not working, paused, ready for P3, still testing), judged on its own sales against its P1 thresholds",
+        async run(args, options) {
+            if (args.length > 0)
+                throw new CliError("Usage: tests p1", exitCodes.usage);
+            const report = await api(await resolveConnection(options), "/api/v1/p1-tests");
+            if (options.format === "json")
+                return printJson(report);
+            process.stdout.write(p1TestsText(report));
+        },
+    },
     "tests show": {
         usage: "tests show <id|test_id>   one funnel test in full",
         async run(args, options) {
@@ -4169,6 +4258,45 @@ const FIRST_TOUCH_SALE_RULE = "Each sale goes to the Facebook ad that first brou
  * The winners report as plain Markdown: which goal the ads are judged on and what one means, then the dates asked for and,
  * unless they are the same dates, the last 30 days, each currency apart.
  */
+const P1_GROUPS = [
+    ["working", "Working"],
+    ["not_working", "Not working"],
+    ["paused", "Paused"],
+    ["ready_for_p3", "Ready for P3"],
+    ["testing", "Still testing"],
+    [null, "No verdict"],
+];
+function p1TestsText(report) {
+    const { window, thresholds: t, judgedOn } = report;
+    const lines = [`P1 tests for ${report.brand}, ${window.from} to ${window.to} (${window.days} days), judged on ${judgedOn.label}`];
+    const amount = (n, currency) => (n === null ? "" : currency === null ? n.toFixed(2) : money(n, currency));
+    if (t !== null) {
+        const currency = report.ads.find((ad) => ad.currency !== null)?.currency ?? null;
+        lines.push(`Thresholds: not working after ${amount(t.minSpend, currency)} spent; working at ${amount(t.maxCostPerResult, currency)} or less per ${judgedOn.one}; ` +
+            `ready for P3 at ${t.p3MinResults} or more at ${amount(t.p3MaxCostPerResult, currency)} or less each`);
+    }
+    if (report.missing !== null)
+        lines.push(report.missing);
+    const columns = ["ad", "campaign", "spend", `results (${judgedOn.label})`, "Meta's count", "cost per result", "why"];
+    for (const [verdict, title] of P1_GROUPS) {
+        const ads = report.ads.filter((ad) => ad.verdict === verdict);
+        if (ads.length === 0)
+            continue;
+        const rows = ads.map((ad) => ({
+            ad: `${ad.name} (${ad.adId})`,
+            campaign: ad.campaignName,
+            spend: amount(ad.spend, ad.currency),
+            [columns[3]]: String(ad.results),
+            "Meta's count": ad.metaResults === null ? "" : `${ad.metaResults}${ad.metaDisagrees ? " (differs)" : ""}`,
+            "cost per result": amount(ad.costPerResult, ad.currency),
+            why: ad.because,
+        }));
+        lines.push("", `${title} (${ads.length})`, renderTable(columns, rows));
+    }
+    if (report.ads.length === 0)
+        lines.push("", "No live ads in the P1 campaigns.");
+    return `${lines.join("\n")}\n`;
+}
 function winnersText(report) {
     const { week, last30Days } = report;
     const words = winnersWords(report);
@@ -4953,9 +5081,9 @@ Options:
   --sort-detail <label> content collections create: the detail whose date orders the collection, newest first, such as "Check date"
   --added               content collections sort: order the collection by when items were added, newest first
   --tool-run <id>       a succeeded tool run content create and edit link; repeat for several
-  --run <id>            the agent run making the content (content) or the Meta change (meta ads|adset), the tool run to
+  --run <id>            the agent run making the content (content) or the Meta change (meta ads|adset, meta ad pause), the tool run to
                         record (creatives create), or the tool run whose outputs media list shows
-  --reason <why>        why: what meta ads|adset pause|resume, meta ads move, meta ad|adset copy, meta adset|campaign budget, meta adset edit, meta ad edit, meta ad rename, meta campaign create, meta audience create|lookalike, meta changes undo, meta ad create --status active and
+  --reason <why>        why: what meta ads|adset pause|resume, meta ad pause, meta ads move, meta ad|adset copy, meta adset|campaign budget, meta adset edit, meta ad edit, meta ad rename, meta campaign create, meta audience create|lookalike, meta changes undo, meta ad create --status active and
                         the google-ads commands record in the change log
   --percent <n>         with meta adset|campaign budget or google-ads campaign budget, the whole-number percent change from the daily budget now (--percent=-10 lowers it);
                         with meta audience lookalike, how wide, 1 (the closest 1%) to 10
@@ -4970,7 +5098,8 @@ Options:
   --roas-floor <n>      meta adset edit, with --bid-strategy LOWEST_COST_WITH_MIN_ROAS: the least return on ad spend times 10000 (15000 is 1.5)
   --targeting <json>    meta adset edit: the ad set's whole new targeting spec as Graph takes it, as JSON, @file.json, or - to read it from stdin
   --optimization-goal <g>  meta adset edit: what Meta optimizes the ad set for, such as OFFSITE_CONVERSIONS or LINK_CLICKS
-  --name <name>         meta ad rename and meta adset edit: the new name; an ad's name that starts with a SKU must keep it at the front
+  --name <name>         meta ad rename and meta adset edit: the new name; an ad's name that starts with a SKU must keep it at the front;
+                        meta ad status and meta ad pause: the name you expect the ad to have, compared exactly
   --special <category>  meta campaign create: a special ad category, such as HOUSING or CREDIT; repeat for several
   --paused              meta campaign create and meta ad|adset copy: make it paused instead of on from the next midnight in the account's
                         time zone; it is also made paused, saying why, when that start would be refused
@@ -4995,12 +5124,13 @@ Options:
   --slot square|tall    meta ad edit: for an ad with a square and a tall (9:16) version, which one --file replaces
   --link <https url>    meta ad create: where the ad links; the SKU's tracking tags are added
   --cta <type>          meta ad create: the button, such as SHOP_NOW
-  --status scheduled|paused   meta ad create and meta ad promote: how the new ad starts (default scheduled: the next midnight in the account's time zone)
+  --status scheduled|paused   meta ad create and meta ad promote: how the new ad starts (default scheduled: the next midnight in the account's time zone);
+                        meta ad pause takes only paused and refuses any other
   --sku <sku>           with media list, only the output that became this creative
   --tool <tool>         with media list, only this tool's outputs, such as kie:nano-banana
   --kind image|video    with media list, only images or only videos
   --since, --until <YYYY-MM-DD | ISO time>   with media list, made at or after --since and before --until (a day: through
-                        its end, in UTC); with changes, meta changes or google-ads changes, only changes from --since on
+                        its end, in UTC); with changes, meta changes or google-ads changes, only changes from --since on; with meta ad pauses, only attempts from --since on
   --cursor <media-id>   with media list, the next page: the id it printed after "More"
   --platform, --external-id   where content status launched says it was published, and that platform's id for it
   --object-type <type>  what that platform's sync calls it (campaign_message or flow_message on klaviyo); needed where

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wrangled/cli",
-  "version": "0.3.147",
+  "version": "0.3.149",
   "description": "Command-line access to your marketing data warehouse, for people and coding agents",
   "type": "module",
   "bin": {