@wrangled/cli 0.3.49 → 0.3.51

package/dist/api.js

@@ -21,6 +21,8 @@ export class UnreadableCredentialsError extends CliError {
  * in src/lib/knowledge/tags.ts. format's flag is --ad-format, because --format picks the output.
  */
 export const entryTagFlags = { angle: "angle", hook_kind: "hook-kind", format: "ad-format", awareness: "awareness" };
+/** The most ads or ad sets one meta ads|adset pause|resume sends; the server refuses more. */
+export const META_IDS_MAX = 10;
 /** The days before a sale in which a click or reply helps it, as the app counts them (MESSAGE_CREDIT_DAYS). */
 export const MESSAGE_CREDIT_DAYS = 7;
 /** Copies of the server's IMPORT_LIMITS and import name rule; src/lib/cli-consistency.test.ts keeps them in step. */

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,7 @@ ${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} 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

package/dist/main.js

@@ -1,11 +1,13 @@
 #!/usr/bin/env node
 import { spawn } from "node:child_process";
+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, IMPORT_NAME_PATTERN, putSigned, CLIENT_FILE, parseClientName, readSavedLogins, removeCredentials, resolveApiUrl, resolveConnection, resolveLogin, UnreadableCredentialsError, writeCredentials, entryTagFlags, streamSigned, } from "./api.js";
+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";
@@ -17,6 +19,7 @@ import { AGENT_ENV, HARNESS_COMMAND_ENV, RUNNER_TOKEN_ENV, runLoop, runOnce } fr
 import { SKILL_NAME_PATTERN } from "./skill-zip.js";
 import { installSkillFolder, operatorConnection, packSkill, parseSkillRef, readSkillFolder, unpackSkill, } from "./skills.js";
 const DEFAULT_WAIT_SECONDS = 300;
+const META_CHANGE_COLUMNS = ["id", "level", "object", "change", "status", "when", "by", "reason"];
 const SERVER_WAIT_CAP = 50;
 const VOICE_USAGE = "voice [--kind opener|objection|pain|desire|phrase] [--since <YYYY-MM-DD>] [--sort common|useful] [--limit <n>] [--json]";
 const commands = {
@@ -997,6 +1000,71 @@ 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 changes": {
+        usage: "meta changes [--since <YYYY-MM-DD>]   the log of Meta ads and ad sets turned on or off, newest first",
+        async run(args, options) {
+            if (args.length !== 0)
+                throw new CliError("Usage: meta changes [--since <YYYY-MM-DD>]", exitCodes.usage);
+            const query = new URLSearchParams();
+            if (options.since)
+                query.set("since", options.since);
+            const { changes } = await api(await resolveConnection(options), `/api/v1/meta/changes${query.size ? `?${query}` : ""}`);
+            if (options.format === "json")
+                return printJson({ changes });
+            console.log(changes.length ? renderTable(META_CHANGE_COLUMNS, changes.map(metaChangeRow)) : "No Meta changes yet.");
+        },
+    },
+    "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',
+        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);
+            const idempotencyKey = options.idempotencyKey ?? announceKey(`undo-${randomUUID()}`);
+            const result = await api(await resolveConnection(options), `/api/v1/meta/changes/${encodeURIComponent(args[0])}/undo`, {
+                reason: options.reason,
+                idempotencyKey,
+            });
+            printMetaStatusResult(result, options.format);
+        },
+    },
+    "meta changes reconcile": {
+        usage: "meta changes reconcile <change-id>   settle a change Meta's answer was lost for, from what Meta reads now",
+        async run(args, options) {
+            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);
+        },
+    },
     "content unpublish": {
         usage: "content unpublish <deployment-id> [--force]",
         async run(args, options) {
@@ -2817,13 +2885,20 @@ Options:
   --source <text>       where the content content capture saves came from, in words
   --url <url>           the address of the content content capture saves
   --tool-run <id>       a succeeded tool run content create and edit link; repeat for several
-  --run <id>            the agent run making the content (content), the tool run to record (creatives create), or the tool
-                        run whose outputs media list shows
+  --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, meta changes undo and meta ad create --status active record in the change log
+  --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
   --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)
+                        its end, in UTC); with meta changes, only changes 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
@@ -2916,6 +2991,7 @@ function parseOptions(argv) {
             ad: { type: "string" },
             limit: { type: "string" },
             run: { type: "string" },
+            reason: { type: "string" },
             lineage: { type: "string" },
             tags: { type: "string" },
             sources: { type: "string" },
@@ -2943,6 +3019,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" },
@@ -3041,6 +3121,7 @@ function parseOptions(argv) {
             ad: values.ad,
             limit: values.limit,
             run: values.run,
+            reason: values.reason,
             lineage: values.lineage,
             tags: values.tags,
             sources: values.sources,
@@ -3069,6 +3150,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,
@@ -3319,21 +3404,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,
@@ -3355,6 +3426,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);
@@ -3581,6 +3676,54 @@ function printPublication(publication, format) {
         finished: publication.finishedAt,
     });
 }
+function metaStatusCommand(noun, verb) {
+    const usage = `meta ${noun} ${verb} <${noun === "ads" ? "ad" : "adset"}-id>... --reason "<why>" [--run <run-id>] [--idempotency-key <key>]`;
+    return {
+        usage: `${usage}   ${verb === "pause" ? "turn off" : "turn on"} up to ${META_IDS_MAX} ${noun === "ads" ? "ads" : "ad sets"} on the control list`,
+        async run(args, options) {
+            if (args.length === 0 || args.length > META_IDS_MAX || !options.reason)
+                throw new CliError(`Usage: ${usage}`, exitCodes.usage);
+            const idempotencyKey = options.idempotencyKey ?? announceKey(`${verb}-${randomUUID()}`);
+            const result = await api(await resolveConnection(options), "/api/v1/meta/changes", {
+                level: noun === "ads" ? "ad" : "adset",
+                ids: args,
+                status: verb === "pause" ? "paused" : "active",
+                reason: options.reason,
+                idempotencyKey,
+                ...(options.run === undefined ? {} : { runId: options.run }),
+            });
+            printMetaStatusResult(result, options.format);
+        },
+    };
+}
+function metaChangeRow(c) {
+    return {
+        id: c.id,
+        level: c.level,
+        object: c.objectId,
+        change: `${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,
+        reason: excerpt(c.reason, 60),
+    };
+}
+/** Told on stderr before the request goes out, so a request whose answer is lost can be sent again with the same key. */
+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) {
+    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 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.`);
+    }
+}
 function printAdSetPublication(publication, format) {
     if (format === "json")
         return printJson({ adsetPublication: publication });

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.49",
+  "version": "0.3.51",
   "description": "Command-line access to your marketing data warehouse, for people and coding agents",
   "type": "module",
   "bin": {