@koda-sl/baker-cli 0.257.0 → 0.258.0

package/README.md

@@ -658,17 +658,19 @@ baker tag-manager draft show --chat <chat-id> gtm_temp_ab12
 baker actions draft --chat <chat-id>
 ```
 
-Command groups: `budgets`, `campaigns`, `ad-groups`, `keywords` (add/update/remove), `negative-keywords`, `keyword-lists`, `ads`, `assets` (create/update/attach/detach), `asset-groups` (create/update/attach/detach — Performance Max), `audiences`, `conversions` (create/update/goal), `bidding-strategies`, `labels`, `campaign-criteria` (add/update/remove), and `draft`. Amounts are in major currency units (converted to micros). Money/bids: `--amount`, `--cpc-bid`, `--target-cpa`, `--target-cpc`, `--max-cpc` take major units; `--target-roas` a ratio. `--target-cpc` pairs with `--bidding-strategy TARGET_CPC` and is Demand Gen only. `--max-cpc` sets the max CPC bid ceiling for `TARGET_IMPRESSION_SHARE` / `TARGET_SPEND` / `PERCENT_CPC` and must be paired with `--bidding-strategy`. Less-common ops accept a `--file <payload.json>` (flags override file keys). Updates target a resource name or bare id as the positional argument; a target that names an op staged earlier **amends it in place**.
+Command groups: `budgets`, `campaigns`, `ad-groups`, `keywords` (add/update/remove), `negative-keywords`, `keyword-lists`, `ads`, `assets` (create/update/attach/detach), `asset-groups` (create/update/attach/detach — Performance Max), `audiences`, `conversions` (create/update/goal), `bidding-strategies`, `labels`, `campaign-criteria` (add/update/remove), and `draft`. Amounts are in major currency units (converted to micros). Money/bids: `--amount`, `--cpc-bid`, `--target-cpa`, `--target-cpc`, `--max-cpc` take major units; `--target-roas` a ratio. `--target-cpc` pairs with `--bidding-strategy TARGET_CPC` and is Demand Gen only. `--max-cpc` sets the max CPC bid ceiling for `TARGET_IMPRESSION_SHARE` / `TARGET_SPEND` / `PERCENT_CPC` and must be paired with `--bidding-strategy`. Less-common ops accept a `--file` payload — a path to a JSON file, or the JSON object written inline (flags override its keys). Updates target a resource name or bare id as the positional argument; a target that names an op staged earlier **amends it in place**.
 
 **A device criterion can be added, but never removed** — `campaign-criteria add` with a device criterion works, but Google then rejects `campaign-criteria remove` on it forever, including on a criterion you added yourself (and Baker refuses the removal before publish). Adjust it instead with `campaign-criteria update customers/<cid>/campaignCriteria/<campaignId>~<criterionId> --bid-modifier <n>`: `1` for no adjustment, `1.25` to bid 25% more, `0.9` to bid 10% less, `0` to stop serving on that device. Locations, languages and ad schedules remove normally.
 
+**Images on a Search campaign** — `assets create` with an image publishes it into the advertiser's Google Ads asset library, but Google refuses the asset link that puts an image extension on a Search campaign (`AD_IMAGE` and every marketing-image field type, at campaign, ad group and customer level alike), so `assets attach` rejects it at stage time and names what to do instead. Staging an image therefore also stages a **Task** — "Add N images to <campaign> in Google Ads" — which applies with the rest of the chat, so the one step Google keeps inside its own interface is tracked rather than mentioned. Attach the image to a Performance Max asset group (`asset-groups attach`) and the Task withdraws itself. The one image a Search campaign does take through a link is the advertiser's logo: `BUSINESS_LOGO`, at campaign or customer level, on a verified account.
+
 **Primary vs secondary conversion actions** — `conversions update <id> --primary` makes an action a primary action (automated bidding optimizes toward it); `--no-primary` (or `--primary=false`) demotes it to secondary (reported only) — the spaced form `--primary false` is rejected, since a boolean flag written with a space is set to true and the word dropped. `conversions create` stages a new action as **secondary** unless its `--file` payload sets `"primaryForGoal": true`, so a new action never silently joins the bidding target of a Maximize Conversions or Target CPA campaign. The staged card shows an "Action optimization" row with the before/after role.
 
 **Account-level conversion goals** — `conversions goal --customer-id … --category PURCHASE --origin WEBSITE --biddable` sets Google's `CustomerConversionGoal` for one (category, origin) pair; `--no-biddable` (or `--biddable=false`) excludes the category from bidding while it keeps being measured. Neither flag defaults, and the spaced form `--biddable false` is rejected. A conversion drives automated bidding only when both halves are on — the action is primary AND its category's account-level goal is biddable — so this is where "my conversion is Primary but bidding ignores it" is fixed. One staged op per pair.
 
 **Retiring a conversion action** — `status` accepts `ENABLED` and `REMOVED` only. Google denies `HIDDEN` on every conversion-action write, so to stop bidding toward an action while it keeps measuring use `--no-primary`, and to stop it counting at all use `"status": "REMOVED"`. Conversion actions **Google owns** cannot be changed at all — Smart campaign call/directions actions, the in-ad lead form's submit, YouTube subscriptions and follow-on views, Floodlight and Search Ads 360 imports, store visits, codeless webpage actions. Staging any edit to one, a rename included, is refused up front; there is no manual route either, since the Google Ads interface will not change them.
 
-**Reviewing the draft** — `baker ads google draft list` renders everything you've staged as a grouped campaign ▸ ad group ▸ ad tree (with non-blocking completeness advisories), the CLI counterpart to the dashboard's Google Ads tab. Pass `--json` for the raw envelope. Aim for a fully built campaign — 2–4 ad groups, ≥5 keywords each, 2–4 RSAs with 8–12 headlines, ≥4 sitelinks / ≥3 callouts / ≥1 structured snippet, and ≥1 shared negative list; the advisories flag what's still thin.
+**Reviewing the draft** — `baker ads google draft list` renders everything you've staged as a grouped campaign ▸ ad group ▸ ad tree (with non-blocking completeness advisories), the CLI counterpart to the dashboard's Google Ads tab. Pass `--json` for the raw envelope. Once the chat has published it reports the outcome instead — `published · N applied, M failed`, with a `✗` line naming each op that did not land and why. Aim for a fully built campaign — 2–4 ad groups, ≥5 keywords each, 2–4 RSAs with 8–12 headlines, ≥4 sitelinks / ≥3 callouts / ≥1 structured snippet, and ≥1 shared negative list; the advisories flag what's still thin.
 
 **Amending a staged op** — `draft amend <ref> (--file patch.json | --patch '<json>')` merges a JSON patch into an already-staged op's payload (objects deep-merge, `null` deletes a key, arrays/scalars replace) and re-validates it in full. Always prefer this over removing and re-staging — it preserves the op's ref (so dependents don't break) and its position in the draft. `draft show <ref>` prints the full staged payload (including warnings/annotations) so you can verify a change looks right before publish.
 

package/dist/cli.js

@@ -2309,15 +2309,24 @@ var ASSET_FIELD_TYPES = [
    * `assetLink.attach` — see that message for what Google actually does with it.
    */
   "MARKETING_IMAGE",
-  "BUSINESS_NAME"
+  "BUSINESS_NAME",
+  /**
+   * The one image link a Search campaign takes. It carries the advertiser's logo beside the ad and
+   * is the only image field type that survives Google's field-type check at all — swept live on v23
+   * and v25, campaign and customer level both answer `CUSTOMER_NOT_VERIFIED` (an account fact,
+   * fixed by advertiser verification) rather than a field-type refusal. Ad group level is not a
+   * level Google links it at — see {@link BUSINESS_LOGO_LEVEL_MESSAGE}.
+   */
+  "BUSINESS_LOGO"
 ];
+var BUSINESS_LOGO_LEVEL_MESSAGE = "Google links a BUSINESS_LOGO at campaign or customer level only \u2014 an ad group link comes back UNSUPPORTED_FIELD_TYPE. Attach it to the campaign instead.";
 var IMAGE_ASSET_LINK_FIELD_TYPES = /* @__PURE__ */ new Set([
   "MARKETING_IMAGE",
   "SQUARE_MARKETING_IMAGE",
   "PORTRAIT_MARKETING_IMAGE",
   "AD_IMAGE"
 ]);
-var IMAGE_ASSET_LINK_MESSAGE = "Google does not accept an image through an asset link. MARKETING_IMAGE is a Performance Max asset-group slot (use `asset-groups attach`), and AD_IMAGE \u2014 the field type Google names for a Search image extension \u2014 comes back UNSUPPORTED_FIELD_TYPE at campaign and ad group level alike. Image extensions are not reachable through the API: tell the user to add them in the Google Ads interface, and carry on with the rest of the job.";
+var IMAGE_ASSET_LINK_MESSAGE = "Google refuses the LINK, not the upload \u2014 so do not stop at this refusal, finish the handover. `assets create` with an image DOES publish: the image lands in the advertiser's Google Ads asset library and is theirs to use. Only this link is refused (MARKETING_IMAGE is a Performance Max asset-group slot \u2014 use `asset-groups attach`; AD_IMAGE comes back UNSUPPORTED_FIELD_TYPE at every level, on every API version). So: stage the image assets anyway, drop this link, and tell the user the images are already in their Google Ads account and only need adding to the campaign under Assets \u2014 name them. Baker stages the Task for that step itself, alongside the image, so it is already in this Session's changes \u2014 do not stage a second one with `baker actions`. Never tell them to upload the images; they are uploaded. The one image a Search campaign does take through a link is the advertiser's logo \u2014 BUSINESS_LOGO at campaign or customer level, on a verified account.";
 function isImageAssetLinkFieldType(fieldType) {
   return IMAGE_ASSET_LINK_FIELD_TYPES.has(fieldType);
 }
@@ -3214,7 +3223,9 @@ var assetLinkAttachSchema = z4.object({
       message: `parent is required for a ${value.level}-level asset link (--parent-ref)`
     });
   }
-  if (isImageAssetLinkFieldType(value.fieldType)) {
+  if (value.fieldType === "BUSINESS_LOGO" && value.level === "adGroup") {
+    ctx.addIssue({ code: z4.ZodIssueCode.custom, path: ["fieldType"], message: BUSINESS_LOGO_LEVEL_MESSAGE });
+  } else if (isImageAssetLinkFieldType(value.fieldType)) {
     ctx.addIssue({ code: z4.ZodIssueCode.custom, path: ["fieldType"], message: IMAGE_ASSET_LINK_MESSAGE });
   } else if (!ASSET_FIELD_TYPES.includes(value.fieldType)) {
     ctx.addIssue({
@@ -9909,7 +9920,7 @@ function renderSection(title, nodes, lines, showAccount) {
 }
 function renderAdvisories(data, lines) {
   const advisories = data.advisories ?? [];
-  if (advisories.length === 0) {
+  if (advisories.length === 0 || data.status === "applied") {
     return;
   }
   lines.push("");
@@ -9918,15 +9929,37 @@ function renderAdvisories(data, lines) {
     lines.push(`  \u2022 ${advisory.message}`);
   }
 }
+function renderOutcome(data, lines) {
+  const counts = /* @__PURE__ */ new Map();
+  for (const op of data.ops) {
+    const status = op.result?.status ?? "pending";
+    counts.set(status, (counts.get(status) ?? 0) + 1);
+  }
+  const summary = [...counts].map(([status, count]) => `${count} ${status}`).join(", ");
+  lines.push(`Google Ads \u2014 published \xB7 ${summary || `${data.count} op(s)`} \xB7 ${data.mode}`);
+  for (const op of data.ops) {
+    const status = op.result?.status;
+    if (status !== "failed" && status !== "skipped") {
+      continue;
+    }
+    const reason = op.result?.error ?? op.result?.skippedBecause ?? "no reason recorded";
+    lines.push(`  \u2717 ${op.summary} \u2014 ${status}: ${reason}`);
+  }
+}
 function renderDraftStatus(data) {
   if (data.status === "none" || data.count === 0) {
     return "No staged Google Ads changes on this chat.";
   }
   const modeNote = data.mode === "live" ? "Live \u2014 publishing writes directly to Google Ads." : "Simulated \u2014 publishing completes the whole draft without calling Google Ads.";
-  const lines = [
-    `Google Ads \u2014 ${data.count} staged change${data.count === 1 ? "" : "s"} \xB7 ${data.mode}`,
-    modeNote
-  ];
+  const lines = [];
+  if (data.status === "applied") {
+    renderOutcome(data, lines);
+  } else if (data.status === "publishing") {
+    lines.push(`Google Ads \u2014 publishing ${data.count} change${data.count === 1 ? "" : "s"} \xB7 ${data.mode}`);
+  } else {
+    lines.push(`Google Ads \u2014 ${data.count} staged change${data.count === 1 ? "" : "s"} \xB7 ${data.mode}`);
+  }
+  lines.push(modeNote);
   const tree = data.tree ?? [];
   const showAccount = accountsInTree(tree).size > 1;
   renderSection(
@@ -10043,15 +10076,17 @@ function loadJsonFileArg(path38) {
   if (typeof path38 !== "string" || path38.length === 0) {
     return {};
   }
+  const inline = path38.trimStart().startsWith("{");
+  const source = inline ? "inline JSON" : path38;
   try {
-    const parsed = JSON.parse(readFileSync2(path38, "utf8"));
+    const parsed = JSON.parse(inline ? path38 : readFileSync2(path38, "utf8"));
     if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
-      failWriteValidation(`${path38} must contain a JSON object`);
+      failWriteValidation(`${source} must contain a JSON object`);
     }
     return parsed;
   } catch (err) {
     if (err instanceof SyntaxError) {
-      failWriteValidation(`${path38} is not valid JSON: ${err.message}`);
+      failWriteValidation(`${source} is not valid JSON: ${err.message}`);
     }
     throw err;
   }
@@ -13877,7 +13912,10 @@ Examples:
 import { defineCommand as defineCommand30 } from "citty";
 var customerIdArg = { "customer-id": { type: "string", description: "10-digit Google Ads customer id" } };
 var fileArg = {
-  file: { type: "string", description: "JSON file with the full op payload (flags override)" }
+  file: {
+    type: "string",
+    description: "The op payload: a JSON file path, or the JSON object inline (flags override it)"
+  }
 };
 var BUDGET_DEMAND_HINTS = [
   "Check this daily budget against the search volume you measured for these keywords, not against the plan you had before you measured it. A budget many times larger than the traffic the target pool can absorb never spends, and reads to the client as a number nobody costed.",
@@ -14877,10 +14915,19 @@ function fileCreateCommand(name, kind, description, hints2) {
       if (Object.keys(payload).length === 0) {
         failWriteValidation(`${kind} needs --file with the op payload`);
       }
-      await stageGoogleOp({ kind, customerId, payload }, hints2);
+      await stageGoogleOp({ kind, customerId, payload }, typeof hints2 === "function" ? hints2(payload) : hints2);
     }
   });
 }
+function imageAssetHints(payload) {
+  if (payload.type !== "image") {
+    return [];
+  }
+  return [
+    "This image publishes into the advertiser's Google Ads asset library \u2014 that half works. What Google refuses is the link that puts it on a Search campaign, so do not stage an `assets attach` for it.",
+    "Finish the handover rather than reporting a limitation: tell the user the images are already in their Google Ads account and only need adding to the campaign under Assets, and name the ones you staged. Baker stages the Task for that step itself the moment you stage the image, so it is already in this chat's changes \u2014 do not stage a second one with `baker actions`. Never tell them to upload images they already have. (A Performance Max asset group is different \u2014 images do link there, with `asset-groups attach`.)"
+  ];
+}
 var assetsUpdateCommand = defineCommand30({
   meta: {
     name: "update",
@@ -14921,17 +14968,18 @@ var assetsUpdateCommand = defineCommand30({
 var assetsCommand = defineCommand30({
   meta: {
     name: "assets",
-    description: "Stage asset create/update + asset-link attach/detach (via --file). For a high-performance Search campaign add \u22654 sitelinks, \u22653 callouts and \u22651 structured snippet per campaign. Images are not among them: Google refuses every image asset link, so image extensions have to be added in the Google Ads interface."
+    description: "Stage asset create/update + asset-link attach/detach (via --file). For a high-performance Search campaign add \u22654 sitelinks, \u22653 callouts and \u22651 structured snippet per campaign. Image extensions are the one thing you cannot finish here \u2014 `create` uploads the image into the advertiser's account, but Google refuses the link that puts it on a Search campaign, so hand that one step over rather than telling them to upload anything. The image a Search campaign does take through a link is the advertiser's logo \u2014 BUSINESS_LOGO, at campaign or customer level, on a verified account."
   },
   subCommands: {
     create: fileCreateCommand(
       "create",
       "google.asset.create",
-      "Stage an asset (text/image/sitelink/callout/structuredSnippet/\u2026)"
+      "Stage an asset (text/image/sitelink/callout/structuredSnippet/\u2026)",
+      imageAssetHints
     ),
     update: assetsUpdateCommand,
     attach: fileCreateCommand("attach", "google.assetLink.attach", "Attach an asset to a campaign/adGroup/customer", [
-      "Images are not attachable here at all \u2014 Google refuses every image field type through an asset link, at every level. Image extensions have to be added in the Google Ads interface; say so and carry on. Performance Max asset-group images are a different mechanism and do work (`asset-groups attach`)."
+      "Image extensions are not attachable here \u2014 Google refuses AD_IMAGE and every marketing-image field type at every level, on every API version. The upload is not refused, though: stage the images with `assets create`, then tell the user they are already in their Google Ads account and only need adding to the campaign under Assets. Baker stages that Task by itself when the image is staged. Two images that DO work: the advertiser's logo through this command (`BUSINESS_LOGO`, campaign or customer level, on a verified account), and Performance Max asset-group images, which are a different mechanism (`asset-groups attach`)."
     ]),
     detach: statusCommand2("google.assetLink.detach", "asset link")
   }
@@ -18714,7 +18762,7 @@ function renderSection2(title, nodes, lines, showAccount) {
   }
 }
 var CAMPAIGN_TREE_ENTITIES = /* @__PURE__ */ new Set(["campaignGroup", "campaign", "creative"]);
-function renderOutcome(data, lines) {
+function renderOutcome2(data, lines) {
   const counts = /* @__PURE__ */ new Map();
   for (const op of data.ops ?? []) {
     const status = op.result?.status ?? "pending";
@@ -18738,7 +18786,7 @@ function renderDraftStatus2(data) {
   const modeNote = data.mode === "live" ? "Live \u2014 publishing writes directly to LinkedIn." : "Simulated \u2014 publishing completes the whole draft without calling LinkedIn.";
   const lines = [];
   if (data.status === "applied") {
-    renderOutcome(data, lines);
+    renderOutcome2(data, lines);
   } else if (data.status === "publishing") {
     lines.push(`LinkedIn Ads \u2014 publishing ${data.count} change${data.count === 1 ? "" : "s"} \xB7 ${data.mode}`);
   } else {