@wrangled/cli 0.3.50 → 0.3.52

package/dist/guide.js

@@ -185,6 +185,8 @@ Save anything you make before it goes anywhere: an ad written without a tool, an
 
 The \`meta_ads\` publisher puts an approved ad on Facebook, always paused, in an ad set that already exists, \`--to meta_ads --target '{"accountId": "act_<id>", "adsetId": "<id>"}'\`, or in one made with \`${cli} meta adset publish\` (below), \`"adsetPublicationId": "<id>"\` in place of \`adsetId\`. \`"urlTags": "sku"\` (the default) adds the SKU tracking tags to the link; \`"urlTags": "none"\` sends the link exactly as written, Meta macros such as \`{{ad.name}}\` included. The ad needs pictures or a video (not both), body text and an https link in \`fields.link_urls\` (\`fields.cta\`, such as "Shop now", sets the button; \`fields.bodies\`, \`fields.titles\` and \`fields.descriptions\` add variations). The account, the ad set's campaign and the ad set must all be on the hand's publish list, which only an operator sets, and the ad set and campaign must be in the last Meta sync and not archived. A live send also needs a run of the Facebook ads hand, Meta numbers pulled under 12 hours ago, and room under the daily limit of new ads. The ad is named \`<SKU> | <name>\` and its creative's \`url_tags\` carry the SKU. In practice mode the same command stores the full request for review and sends nothing. Each publication's \`targetSnapshot\` names the campaign and ad set as they were at publish time.
 
+\`${cli} meta ad create --account act_<id> --adset <id> --file ad.png --text "<primary text>" --headline "<headline>" --link <https url>\` does all of that in one step: it saves the files and words as an ad with a new SKU, approves it and publishes it with \`meta_ads\` into the ad set, then prints the SKU, the publication, the Meta ad id and its status. Repeat \`--file\` for more pictures; a big file is uploaded first. \`--cta SHOP_NOW\` sets the button and \`--name\` names the ad (the headline otherwise). The same rules apply and are all checked before anything is saved, so a refusal leaves nothing behind. Your own key sends to Facebook without \`--run\`, but the account and campaign must also be on the workspace's control list; from a hand's run in practice mode it is recorded and nothing is sent. The ad starts paused; \`--status active --reason "<why>"\` switches it on 15 seconds after it is made, as a change in the change log that \`${cli} meta changes undo <change-id>\` reverses, and needs room under the day's limit of on/off changes. Without \`--idempotency-key\` the key comes from the files and the flags, so the same command run twice makes one ad.
+
 \`${cli} meta adset publish --plan '<json>' --idempotency-key <key> --run <run-id>\` makes one new Meta ad set, always paused, for ads to go into. A copy, \`{"kind": "copy", "accountId": "act_<id>", "campaignId": "<id>", "sourceAdsetId": "<id>", "name": "<new name>"}\`, copies a proven ad set without its ads; the source must be on the hand's list of ad sets that may be copied. A new one from settings is \`{"kind": "create", "accountId": ..., "campaignId": ..., "name": ..., "settings": {"optimizationGoal": "...", "billingEvent": "...", "targeting": {...}, "dailyBudget": 5000}}\`, with the budget in the currency's smallest unit (5000 is 50.00 USD) and left out when the campaign holds it. The account and campaign must be on the publish list, the name unused in the campaign, and the day under the limit of new ad sets (3 unless an operator sets another). Ad sets and ads share one account's turn: one unfinished send at a time, and at least 15 seconds apart. ${brand.name} reads the new ad set back and checks it: paused, in the right campaign, with the right name, and for a copy, targeting equal to the source's. Its \`verification.ok\` must be true before you add ads; an ad set that fails the check stays paused and takes none. In practice mode nothing is sent and the ad set is recorded as \`not_sent_practice\`, and ads published into it are practice too. \`${cli} meta adset show <id>\` prints it with its budget. One left \`sending\` or \`unknown\` is never sent again; \`${cli} meta adset reconcile <id>\` looks for it in the campaign by its exact name.
 
 When you send something yourself instead, record it in ${brand.name} before anything is sent, so the record never depends on the platform remembering it:
@@ -382,6 +384,8 @@ ${cli} content reconcile <publication-id>   check whether a publish left sending
 ${cli} content unpublish <deployment-id> [--force]   take one deployed landing page down
 ${cli} meta adset publish --plan '<json>' --idempotency-key <key> [--run <run-id>]   make a paused Meta ad set to add ads to
 ${cli} meta adset show <id> | meta adset reconcile <id>   read an ad set publication, or check whether one left sending landed
+${cli} meta ad create --account act_<id> --adset <id> --file <path> --text "<words>" --headline "<h>" --link <url> [--cta <type>] [--name <n>] [--status paused|active --reason "<why>"] [--run <run-id>]   make a Facebook ad from files in one step
+${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} content publish-record <sku> --file <publication.json>   record a publish before sending it
 ${cli} content publish-finish <publication-id> --status sending|published|failed|not_sent_practice [--input '<json>']
 ${cli} content track-link <sku> <url> [--channel facebook|email|sms|web] [--campaign <id>]   tag a link with its SKU
@@ -389,6 +393,7 @@ ${cli} agent start | show <run-id> | runs | finish <run-id> --status <s> --file
 ${cli} agent draft --agent p3_refresh   the P3 refresh hand's counted draft
 ${cli} brand get | brand set --file <path> [--sources '<json>' | @file.json]
 ${cli} proposals create --input '<json>' | proposals list [--status <s>] [--run <run-id>]
+${cli} proposals execute <proposal-id>   apply an approved pause or budget proposal to Meta, in live mode only
 ${cli} content add-page <url>      add a landing page and read it now
 ${cli} plans create --name <name> --goal <text> --channel meta|ghl|klaviyo|web [--target '<json>'] [--landing <sku> | --landing-url <url>] [--funnel <key> --step <key>] [--run <agent-run-id>]   plan a campaign push
 ${cli} plans show <plan-id> | plans add <plan-id> <sku> [--role <role>] [--position <n>] | plans remove <plan-id> <sku>

package/dist/main.js

@@ -1,12 +1,13 @@
 #!/usr/bin/env node
 import { spawn } from "node:child_process";
-import { randomUUID } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
 import { mkdir, readFile, stat } from "node:fs/promises";
 import { homedir } from "node:os";
 import { basename, dirname, extname, join, resolve } from "node:path";
 import { parseArgs } from "node:util";
 import { api, ApiError, apiDownload, apiText, apiUpload, CliError, exitCodes, getSigned, IMPORT_LIMITS, META_IDS_MAX, IMPORT_NAME_PATTERN, putSigned, CLIENT_FILE, parseClientName, readSavedLogins, removeCredentials, resolveApiUrl, resolveConnection, resolveLogin, UnreadableCredentialsError, writeCredentials, entryTagFlags, streamSigned, } from "./api.js";
 import { brand, envPrefix } from "./brand.js";
+import { META_AD_CREATE_USAGE, metaAdCreateBody } from "./meta-ad.js";
 import { firstSymlink, inRunFolder, writeFileAtomic } from "./files.js";
 import { scheduleCreateBody, scheduleIdFor, SCHEDULES_CREATE_USAGE } from "./schedules.js";
 import { secretBody, secretProvider, SECRETS_SET_USAGE } from "./secrets.js";
@@ -999,12 +1000,39 @@ const commands = {
             printAdSetPublication(adsetPublication, options.format);
         },
     },
+    "meta ad create": {
+        usage: `${META_AD_CREATE_USAGE}   make a Facebook ad from pictures or a video in one step`,
+        async run(args, options) {
+            if (args.length !== 0)
+                throw new CliError(`Usage: ${META_AD_CREATE_USAGE}`, exitCodes.usage);
+            const read = await readContentFiles(options.files);
+            const body = metaAdCreateBody({ ...options, text: options.text === undefined ? undefined : await textOrFile(options.text) }, read.map(({ data }) => createHash("sha256").update(data).digest("hex")));
+            const connection = await resolveConnection(options);
+            const created = await api(connection, "/api/v1/meta/ads", { ...body, files: await sendableFiles(read, connection, 0) });
+            if (options.format === "json")
+                return printJson(created);
+            const { publication, change } = created;
+            printFields({
+                sku: created.sku,
+                publication: publication.id,
+                "meta ad": publication.externalId,
+                status: publication.status,
+                error: publication.error,
+                change: change && `${change.id} (${change.before.status} -> ${change.after.status}, ${change.status})`,
+                "idempotency key": body.idempotencyKey,
+            });
+            if (publication.status === "not_sent_practice")
+                console.log("Practice mode: the ad was recorded with its full request and nothing was sent to Meta.");
+        },
+    },
     "meta ads pause": metaStatusCommand("ads", "pause"),
     "meta ads resume": metaStatusCommand("ads", "resume"),
     "meta adset pause": metaStatusCommand("adset", "pause"),
     "meta adset resume": metaStatusCommand("adset", "resume"),
+    "meta adset budget": metaBudgetCommand("adset"),
+    "meta campaign budget": metaBudgetCommand("campaign"),
     "meta changes": {
-        usage: "meta changes [--since <YYYY-MM-DD>]   the log of Meta ads and ad sets turned on or off, newest first",
+        usage: "meta changes [--since <YYYY-MM-DD>]   the log of Meta ads and ad sets turned on or off and budgets changed, newest first",
         async run(args, options) {
             if (args.length !== 0)
                 throw new CliError("Usage: meta changes [--since <YYYY-MM-DD>]", exitCodes.usage);
@@ -1018,7 +1046,7 @@ const commands = {
         },
     },
     "meta changes undo": {
-        usage: 'meta changes undo <change-id> --reason "<why>" [--idempotency-key <key>]   put the ad or ad set back the way it was',
+        usage: 'meta changes undo <change-id> --reason "<why>" [--idempotency-key <key>]   put the ad, ad set or budget back the way it was',
         async run(args, options) {
             if (args.length !== 1 || !options.reason)
                 throw new CliError('Usage: meta changes undo <change-id> --reason "<why>" [--idempotency-key <key>]', exitCodes.usage);
@@ -1027,7 +1055,7 @@ const commands = {
                 reason: options.reason,
                 idempotencyKey,
             });
-            printMetaStatusResult(result, options.format);
+            printMetaChangeResult(result, options.format);
         },
     },
     "meta changes reconcile": {
@@ -1036,7 +1064,7 @@ const commands = {
             if (args.length !== 1)
                 throw new CliError("Usage: meta changes reconcile <change-id>", exitCodes.usage);
             const { change } = await api(await resolveConnection(options), `/api/v1/meta/changes/${encodeURIComponent(args[0])}/reconcile`, {});
-            printMetaStatusResult({ changes: [change], unchanged: [] }, options.format);
+            printMetaChangeResult({ changes: [change], unchanged: [] }, options.format);
         },
     },
     "content unpublish": {
@@ -2032,6 +2060,15 @@ const commands = {
             console.log(renderTable(PROPOSAL_COLUMNS, proposals.map(proposalRow)));
         },
     },
+    "proposals execute": {
+        usage: "proposals execute <proposal-id>   apply an approved pause or budget proposal to Meta (live mode only), within the control list",
+        async run(args, options) {
+            if (args.length !== 1)
+                throw new CliError("Usage: proposals execute <proposal-id>", exitCodes.usage);
+            const result = await api(await resolveConnection(options), `/api/v1/proposals/${encodeURIComponent(args[0])}/execute`, {});
+            printMetaChangeResult(result, options.format);
+        },
+    },
     "skill publish": {
         usage: "skill publish <dir> [--notes <text>] [--harness claude,codex]",
         async run(args, options) {
@@ -2861,7 +2898,15 @@ Options:
   --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
                         record (creatives create), or the tool run whose outputs media list shows
-  --reason <why>        why: what meta ads|adset pause|resume and meta changes undo record in the change log
+  --reason <why>        why: what meta ads|adset pause|resume, meta adset|campaign budget, meta changes undo and meta ad create --status active record in the change log
+  --percent <n>         with meta adset|campaign budget, the whole-number percent change from Meta's daily budget now (--percent=-10 lowers it)
+  --daily <n>           with meta adset|campaign budget, the new daily budget in the currency's smallest unit (6000 is 60.00 USD)
+  --account <act_id>    meta ad create: the ad account
+  --adset <id>          meta ad create: the ad set the new ad goes into
+  --text <text | @file> meta ad create: the ad's primary text
+  --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 paused|active   meta ad create: how the new ad starts (default paused)
   --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
@@ -2960,6 +3005,8 @@ function parseOptions(argv) {
             limit: { type: "string" },
             run: { type: "string" },
             reason: { type: "string" },
+            percent: { type: "string" },
+            daily: { type: "string" },
             lineage: { type: "string" },
             tags: { type: "string" },
             sources: { type: "string" },
@@ -2987,6 +3034,10 @@ function parseOptions(argv) {
             grain: { type: "string" },
             channel: { type: "string" },
             campaign: { type: "string" },
+            account: { type: "string" },
+            adset: { type: "string" },
+            link: { type: "string" },
+            cta: { type: "string" },
             top: { type: "string" },
             week: { type: "string" },
             days: { type: "string" },
@@ -3086,6 +3137,8 @@ function parseOptions(argv) {
             limit: values.limit,
             run: values.run,
             reason: values.reason,
+            percent: values.percent,
+            daily: values.daily,
             lineage: values.lineage,
             tags: values.tags,
             sources: values.sources,
@@ -3114,6 +3167,10 @@ function parseOptions(argv) {
             grain: values.grain,
             channel: values.channel,
             campaign: values.campaign,
+            account: values.account,
+            adset: values.adset,
+            link: values.link,
+            cta: values.cta,
             top: values.top,
             week: values.week,
             days: values.days,
@@ -3364,21 +3421,7 @@ const INLINE_CONTENT_BYTES = 3 * 1024 * 1024;
  */
 async function contentInput(options, connection) {
     const html = options.html === undefined ? undefined : await textOrFile(options.html);
-    let inline = html === undefined ? 0 : Buffer.byteLength(html);
-    const files = [];
-    for (const path of options.files) {
-        const contentType = FILE_TYPES[extname(path).toLowerCase()];
-        if (!contentType)
-            throw new CliError(`${path}: --file takes ${Object.keys(FILE_TYPES).join(", ")} files.`, exitCodes.usage);
-        const data = await readFile(await inRunFolder(path));
-        if (inline + data.byteLength <= INLINE_CONTENT_BYTES) {
-            inline += data.byteLength;
-            files.push({ base64: data.toString("base64"), contentType });
-        }
-        else {
-            files.push({ uploadId: await uploadContentFile(connection, data, contentType) });
-        }
-    }
+    const files = await sendableFiles(await readContentFiles(options.files), connection, html === undefined ? 0 : Buffer.byteLength(html));
     const input = {
         name: options.name,
         subject: options.subject,
@@ -3400,6 +3443,30 @@ function deploymentLine(d) {
         return line;
     return `${line}, read as ${d.pageItemId} v${d.currentPageVersion}, edited on the host ${d.editedOnHost} ${d.editedOnHost === 1 ? "time" : "times"} since it went live`;
 }
+async function readContentFiles(paths) {
+    const read = [];
+    for (const path of paths) {
+        const contentType = FILE_TYPES[extname(path).toLowerCase()];
+        if (!contentType)
+            throw new CliError(`${path}: --file takes ${Object.keys(FILE_TYPES).join(", ")} files.`, exitCodes.usage);
+        read.push({ contentType, data: await readFile(await inRunFolder(path)) });
+    }
+    return read;
+}
+/** Files go base64 while they fit in one request beside `inline` bytes already in it; any other file goes to storage first. */
+async function sendableFiles(read, connection, inline) {
+    const files = [];
+    for (const { contentType, data } of read) {
+        if (inline + data.byteLength <= INLINE_CONTENT_BYTES) {
+            inline += data.byteLength;
+            files.push({ base64: data.toString("base64"), contentType });
+        }
+        else {
+            files.push({ uploadId: await uploadContentFile(connection, data, contentType) });
+        }
+    }
+    return files;
+}
 async function uploadContentFile(connection, data, contentType) {
     const upload = await api(connection, "/api/v1/content/uploads", { contentType, bytes: data.byteLength });
     await putSigned(upload.url, data, contentType);
@@ -3642,7 +3709,35 @@ function metaStatusCommand(noun, verb) {
                 idempotencyKey,
                 ...(options.run === undefined ? {} : { runId: options.run }),
             });
-            printMetaStatusResult(result, options.format);
+            printMetaChangeResult(result, options.format);
+        },
+    };
+}
+/** A daily budget change, for agents to compute from Meta's budget now (--percent) or to set outright in the currency's smallest unit (--daily). */
+function metaBudgetCommand(level) {
+    const usage = `meta ${level} budget <${level}-id> (--percent <n> | --daily <smallest units>) --reason "<why>" [--run <run-id>] [--idempotency-key <key>]`;
+    return {
+        usage: `${usage}   change ${level === "adset" ? "an ad set's" : "a campaign's"} daily budget on the control list, within the workspace's limits`,
+        async run(args, options) {
+            if (args.length !== 1 || !options.reason || (options.percent === undefined) === (options.daily === undefined))
+                throw new CliError(`Usage: ${usage}`, exitCodes.usage);
+            const whole = (text, flag) => {
+                const n = Number(text);
+                if (text.trim() === "" || !Number.isInteger(n))
+                    throw new CliError(`${flag} must be a whole number.`, exitCodes.usage);
+                return n;
+            };
+            const amount = options.percent !== undefined ? { changePercent: whole(options.percent, "--percent") } : { dailyBudget: whole(options.daily, "--daily") };
+            const idempotencyKey = options.idempotencyKey ?? announceKey(`budget-${randomUUID()}`);
+            const result = await api(await resolveConnection(options), "/api/v1/meta/budgets", {
+                level,
+                id: args[0],
+                ...amount,
+                reason: options.reason,
+                idempotencyKey,
+                ...(options.run === undefined ? {} : { runId: options.run }),
+            });
+            printMetaChangeResult(result, options.format);
         },
     };
 }
@@ -3651,7 +3746,7 @@ function metaChangeRow(c) {
         id: c.id,
         level: c.level,
         object: c.objectId,
-        change: `${c.before.status} -> ${c.after.status}`,
+        change: c.kind === "budget" ? `daily budget ${c.before.dailyBudget} -> ${c.after.dailyBudget}` : `${c.before.status} -> ${c.after.status}`,
         status: c.undoneBy ? `${c.status} (undone by ${c.undoneBy})` : c.error ? `${c.status}: ${c.error}` : c.status,
         when: c.createdAt,
         by: c.requestedBy,
@@ -3663,13 +3758,15 @@ function announceKey(key) {
     console.error(`Idempotency key: ${key} (if no answer comes, send the same command again with --idempotency-key ${key})`);
     return key;
 }
-function printMetaStatusResult(result, format) {
+function printMetaChangeResult(result, format) {
     if (format === "json")
         return printJson(result);
     if (result.changes.length > 0)
         console.log(renderTable(META_CHANGE_COLUMNS, result.changes.map(metaChangeRow)));
-    for (const u of result.unchanged)
-        console.log(`${u.level === "ad" ? "Ad" : "Ad set"} ${u.objectId} was already ${u.status}; nothing was sent.`);
+    for (const u of result.unchanged) {
+        const what = { ad: "Ad", adset: "Ad set", campaign: "Campaign" }[u.level];
+        console.log("status" in u ? `${what} ${u.objectId} was already ${u.status}; nothing was sent.` : `${what} ${u.objectId}'s daily budget is already ${u.dailyBudget}; nothing was sent.`);
+    }
     for (const c of result.changes.filter((c) => c.status === "sending")) {
         console.log(`Meta's answer for change ${c.id} was lost. Run \`${brand.slug} meta changes reconcile ${c.id}\` in a minute to settle it.`);
     }

package/dist/meta-ad.js

@@ -0,0 +1,35 @@
+import { createHash } from "node:crypto";
+import { CliError, exitCodes } from "./api.js";
+export const META_AD_CREATE_USAGE = 'meta ad create --account act_<id> --adset <id> --file <path> [--file <path>...] --text "<primary text>" --headline "<headline>" --link <https url> ' +
+    '[--cta SHOP_NOW] [--name "<name>"] [--status paused|active] [--reason "<why>"] [--run <run-id>] [--idempotency-key <key>]';
+const usage = (problem) => new CliError(`${problem}\nUsage: ${META_AD_CREATE_USAGE}`, exitCodes.usage);
+/**
+ * The request for `meta ad create`. Without --idempotency-key the key comes from the files' sha256 and every flag that
+ * shapes the ad, so the same command sent again returns the ad it made instead of making a second.
+ */
+export function metaAdCreateBody(flags, fileSha256s) {
+    const { account, adset, text, headline, link } = flags;
+    if (!account || !adset || !text || !headline || !link || fileSha256s.length === 0) {
+        throw usage("meta ad create needs --account, --adset, at least one --file, --text, --headline and --link.");
+    }
+    const status = flags.status ?? "paused";
+    if (status !== "paused" && status !== "active")
+        throw usage(`--status must be paused or active; got '${status}'.`);
+    if (status === "active" && !flags.reason)
+        throw usage("--status active needs --reason, which goes in the change log.");
+    const shape = { accountId: account, adsetId: adset, primaryText: text, headline, linkUrl: link, cta: flags.cta ?? null, name: flags.name ?? null, status };
+    const derived = `meta-ad-${createHash("sha256").update(JSON.stringify({ files: fileSha256s, ...shape })).digest("hex")}`;
+    return {
+        accountId: account,
+        adsetId: adset,
+        primaryText: text,
+        headline,
+        linkUrl: link,
+        ...(flags.cta === undefined ? {} : { cta: flags.cta }),
+        ...(flags.name === undefined ? {} : { name: flags.name }),
+        status,
+        ...(flags.reason === undefined ? {} : { reason: flags.reason }),
+        ...(flags.run === undefined ? {} : { runId: flags.run }),
+        idempotencyKey: flags.idempotencyKey ?? derived,
+    };
+}

package/package.json

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