@wrangled/cli 0.3.52 → 0.3.53

package/dist/api.js

@@ -23,6 +23,8 @@ export class UnreadableCredentialsError extends CliError {
 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 most ads or ad groups one google-ads ads|adgroup pause|resume sends; the server refuses more. */
+export const GOOGLE_ADS_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

@@ -187,6 +187,8 @@ The \`meta_ads\` publisher puts an approved ad on Facebook, always paused, in an
 
 \`${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.
 
+Google Ads has the same controls. \`${cli} google-ads ads pause <adgroup-id>~<ad-id> --reason "<why>"\` (ids from \`gads_ads\`) and \`${cli} google-ads adgroup pause|resume <adgroup-id>\` turn ads and ad groups off or on, and \`${cli} google-ads campaign budget <campaign-id> --percent 10 --reason "<why>"\` (or \`--daily 60.50\`, in the account's currency) changes a campaign's daily budget. The account and campaign must be on the workspace's Google Ads control list, which an Admin sets on the Settings page, and the same daily limits, largest budget step, total daily budget limit and approval rule apply; a shared budget is never changed. With approval on (the default), a hand proposes \`gads_budget_change\` and the change goes out once a person approves it. Only your own key writes to Google Ads: no hand does yet. \`${cli} google-ads changes\` lists every change with who asked and why, \`${cli} google-ads changes undo <id>\` puts one back, and \`${cli} google-ads changes reconcile <id>\` settles one whose answer was lost.
+
 \`${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:
@@ -386,6 +388,9 @@ ${cli} meta adset publish --plan '<json>' --idempotency-key <key> [--run <run-id
 ${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} google-ads ads pause|resume <adgroup-id~ad-id>... | google-ads adgroup pause|resume <adgroup-id>... --reason "<why>"   turn Google ads or ad groups on or off
+${cli} google-ads campaign budget <id> (--percent <n> | --daily <amount>) --reason "<why>"   change a Google Ads daily budget within the workspace's limits
+${cli} google-ads changes [--since <date>] | google-ads changes undo <id> --reason "<why>" | google-ads changes reconcile <id>   the Google Ads change log
 ${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

@@ -5,7 +5,7 @@ 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 { api, ApiError, apiDownload, apiText, apiUpload, CliError, exitCodes, getSigned, IMPORT_LIMITS, META_IDS_MAX, GOOGLE_ADS_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";
@@ -20,6 +20,7 @@ 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 GOOGLE_ADS_CHANGE_COLUMNS = ["id", "account", "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 = {
@@ -1067,6 +1068,74 @@ const commands = {
             printMetaChangeResult({ changes: [change], unchanged: [] }, options.format);
         },
     },
+    "google-ads ads pause": googleAdsStatusCommand("ads", "pause"),
+    "google-ads ads resume": googleAdsStatusCommand("ads", "resume"),
+    "google-ads adgroup pause": googleAdsStatusCommand("adgroup", "pause"),
+    "google-ads adgroup resume": googleAdsStatusCommand("adgroup", "resume"),
+    "google-ads campaign budget": {
+        usage: 'google-ads campaign budget <campaign-id> (--percent <n> | --daily <amount>) --reason "<why>" [--idempotency-key <key>]   change a Google Ads campaign\'s daily budget on the control list, within the workspace\'s limits',
+        async run(args, options) {
+            const usage = 'Usage: google-ads campaign budget <campaign-id> (--percent <n> | --daily <amount>) --reason "<why>" [--idempotency-key <key>]';
+            if (args.length !== 1 || !options.reason || (options.percent === undefined) === (options.daily === undefined))
+                throw new CliError(usage, exitCodes.usage);
+            let amount;
+            if (options.percent !== undefined) {
+                const n = Number(options.percent);
+                if (options.percent.trim() === "" || !Number.isInteger(n))
+                    throw new CliError("--percent must be a whole number.", exitCodes.usage);
+                amount = { changePercent: n };
+            }
+            else {
+                if (!/^\d+(\.\d{1,6})?$/.test(options.daily.trim()))
+                    throw new CliError("--daily must be an amount such as 60 or 60.50.", exitCodes.usage);
+                amount = { dailyBudget: options.daily.trim() };
+            }
+            const idempotencyKey = options.idempotencyKey ?? announceKey(`budget-${randomUUID()}`);
+            const result = await api(await resolveConnection(options), "/api/v1/google-ads/budgets", {
+                campaignId: args[0],
+                ...amount,
+                reason: options.reason,
+                idempotencyKey,
+            });
+            printGoogleAdsChangeResult(result, options.format);
+        },
+    },
+    "google-ads changes": {
+        usage: "google-ads changes [--since <YYYY-MM-DD>]   the log of Google ads and ad groups turned on or off and budgets changed, newest first",
+        async run(args, options) {
+            if (args.length !== 0)
+                throw new CliError("Usage: google-ads 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/google-ads/changes${query.size ? `?${query}` : ""}`);
+            if (options.format === "json")
+                return printJson({ changes });
+            console.log(changes.length ? renderTable(GOOGLE_ADS_CHANGE_COLUMNS, changes.map(googleAdsChangeRow)) : "No Google Ads changes yet.");
+        },
+    },
+    "google-ads changes undo": {
+        usage: 'google-ads changes undo <change-id> --reason "<why>" [--idempotency-key <key>]   put the ad, ad group or budget back the way it was',
+        async run(args, options) {
+            if (args.length !== 1 || !options.reason)
+                throw new CliError('Usage: google-ads 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/google-ads/changes/${encodeURIComponent(args[0])}/undo`, {
+                reason: options.reason,
+                idempotencyKey,
+            });
+            printGoogleAdsChangeResult(result, options.format);
+        },
+    },
+    "google-ads changes reconcile": {
+        usage: "google-ads changes reconcile <change-id>   settle a change Google's answer was lost for, from what Google reads now",
+        async run(args, options) {
+            if (args.length !== 1)
+                throw new CliError("Usage: google-ads changes reconcile <change-id>", exitCodes.usage);
+            const { change } = await api(await resolveConnection(options), `/api/v1/google-ads/changes/${encodeURIComponent(args[0])}/reconcile`, {});
+            printGoogleAdsChangeResult({ changes: [change], unchanged: [] }, options.format);
+        },
+    },
     "content unpublish": {
         usage: "content unpublish <deployment-id> [--force]",
         async run(args, options) {
@@ -2061,12 +2130,16 @@ const commands = {
         },
     },
     "proposals execute": {
-        usage: "proposals execute <proposal-id>   apply an approved pause or budget proposal to Meta (live mode only), within the control list",
+        usage: "proposals execute <proposal-id>   apply an approved pause or budget proposal to Meta or Google Ads (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);
+            const google = result.changes.some((c) => "customerId" in c) || result.unchanged.some((u) => "amountMicros" in u);
+            if (google)
+                printGoogleAdsChangeResult(result, options.format);
+            else
+                printMetaChangeResult(result, options.format);
         },
     },
     "skill publish": {
@@ -2898,9 +2971,11 @@ 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, 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)
+  --reason <why>        why: what meta ads|adset pause|resume, meta adset|campaign budget, 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)
+  --daily <n>           with meta adset|campaign budget, the new daily budget in the currency's smallest unit (6000 is 60.00 USD); with
+                        google-ads campaign budget, in the currency itself (60.50 is 60.50 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
@@ -2911,7 +2986,7 @@ Options:
   --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 meta changes, only changes from --since on
+                        its end, in UTC); with meta changes or google-ads 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
@@ -3771,6 +3846,53 @@ function printMetaChangeResult(result, format) {
         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 googleAdsStatusCommand(noun, verb) {
+    const usage = `google-ads ${noun} ${verb} <${noun === "ads" ? "adgroup-id~ad-id" : "adgroup-id"}>... --reason "<why>" [--idempotency-key <key>]`;
+    return {
+        usage: `${usage}   ${verb === "pause" ? "turn off" : "turn on"} up to ${GOOGLE_ADS_IDS_MAX} Google ${noun === "ads" ? "ads" : "ad groups"} on the control list`,
+        async run(args, options) {
+            if (args.length === 0 || args.length > GOOGLE_ADS_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/google-ads/changes", {
+                level: noun === "ads" ? "ad" : "ad_group",
+                ids: args,
+                status: verb === "pause" ? "paused" : "enabled",
+                reason: options.reason,
+                idempotencyKey,
+            });
+            printGoogleAdsChangeResult(result, options.format);
+        },
+    };
+}
+/** Micros as the account's currency amount, e.g. 60500000 is 60.50. */
+const fromMicros = (micros) => (Number(micros) / 1_000_000).toFixed(2);
+function googleAdsChangeRow(c) {
+    return {
+        id: c.id,
+        account: c.customerId,
+        level: c.level,
+        object: c.objectId,
+        change: c.kind === "budget" ? `daily budget ${fromMicros(c.before.amountMicros)} -> ${fromMicros(c.after.amountMicros)}` : `${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),
+    };
+}
+function printGoogleAdsChangeResult(result, format) {
+    if (format === "json")
+        return printJson(result);
+    if (result.changes.length > 0)
+        console.log(renderTable(GOOGLE_ADS_CHANGE_COLUMNS, result.changes.map(googleAdsChangeRow)));
+    for (const u of result.unchanged) {
+        const what = { ad: "Ad", ad_group: "Ad group", 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 ${fromMicros(u.amountMicros)}; nothing was sent.`);
+    }
+    for (const c of result.changes.filter((c) => c.status === "sending")) {
+        console.log(`Google's answer for change ${c.id} was lost. Run \`${brand.slug} google-ads changes reconcile ${c.id}\` in a minute to settle it.`);
+    }
+}
 function printAdSetPublication(publication, format) {
     if (format === "json")
         return printJson({ adsetPublication: publication });

package/package.json

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