@koda-sl/baker-cli 0.257.0 → 0.258.0-dev.d0de9190f

package/dist/cli.js

@@ -58,7 +58,7 @@ import {
   ulid,
   validateCanvasDeep,
   ytDlpBlockSignal
-} from "./chunk-SJPRTSGY.js";
+} from "./chunk-HBDGUVUH.js";
 import {
   csvOrJson,
   daysAgoIso,
@@ -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 {
@@ -19573,7 +19621,16 @@ var META_LIMITS = {
     dynamicTextsMin: 1,
     dynamicTextsMax: 5,
     /** Dynamic ads mix and match best with at least this many media assets. */
-    dynamicAssetsGoodMin: 3
+    dynamicAssetsGoodMin: 3,
+    /**
+     * Placement asset customization: "every `asset_feed_spec` needs to have more
+     * than one customization rule attached to it" — one rule is not a
+     * customization, it is an ad that serves in one place.
+     * https://developers.facebook.com/docs/marketing-api/dynamic-creative/placement-asset-customization/
+     */
+    placementRulesMin: 2,
+    /** Asset customization rules per asset feed. */
+    placementRulesMax: 50
   },
   audience: {
     nameMax: 100,
@@ -19810,6 +19867,56 @@ function positionsMissingRequiredFeed(targeting) {
   }
   return FACEBOOK_POSITIONS_REQUIRING_FEED.filter((required) => positions.includes(required));
 }
+var PLACEMENT_ASSET_CUSTOMIZATION_DOC = "https://developers.facebook.com/docs/marketing-api/dynamic-creative/placement-asset-customization/";
+var CUSTOMIZATION_POSITION_KEYS = {
+  facebook: "facebook_positions",
+  instagram: "instagram_positions",
+  messenger: "messenger_positions",
+  audience_network: "audience_network_positions",
+  threads: "threads_positions"
+};
+var CUSTOMIZATION_PLATFORMS = Object.keys(CUSTOMIZATION_POSITION_KEYS);
+var CUSTOMIZATION_POSITIONS = {
+  facebook: ["feed", "right_hand_column", "marketplace", "video_feeds", "search", "story", "notification"],
+  instagram: ["stream", "story", "explore", "explore_home", "profile_feed", "ig_search"],
+  messenger: ["sponsored_messages", "story"],
+  audience_network: ["classic", "instream_video", "rewarded_video"],
+  threads: ["threads_stream"]
+};
+function customizationPlacementKeys(spec) {
+  const keys = [];
+  for (const platform of spec.publisher_platforms) {
+    for (const position of spec[CUSTOMIZATION_POSITION_KEYS[platform]] ?? []) {
+      keys.push(`${platform}:${position}`);
+    }
+  }
+  return keys;
+}
+function customizationSpecProblems(spec) {
+  const problems = [];
+  for (const platform of spec.publisher_platforms) {
+    const key = CUSTOMIZATION_POSITION_KEYS[platform];
+    const positions = spec[key];
+    if (!positions?.length) {
+      problems.push(
+        `publisher_platforms names ${platform}, so ${key} is required \u2014 Meta rejects a customization spec that selects a platform without its positions (${PLACEMENT_ASSET_CUSTOMIZATION_DOC})`
+      );
+      continue;
+    }
+    const known = CUSTOMIZATION_POSITIONS[platform];
+    for (const position of positions) {
+      if (!known.includes(position)) {
+        problems.push(`${key} does not publish "${position}" \u2014 Meta lists ${known.join(", ")}`);
+      }
+    }
+  }
+  if (spec.publisher_platforms.includes("threads") && !spec.instagram_positions?.includes("stream")) {
+    problems.push(
+      'threads placements require instagram alongside them \u2014 add "instagram" to publisher_platforms and "stream" to instagram_positions'
+    );
+  }
+  return problems;
+}
 
 // ../api/src/ads-meta/ops.ts
 var tempRefSchema3 = z25.string().regex(TEMP_REF_REGEX3, "expected a meta_temp_* reference");
@@ -20290,9 +20397,7 @@ var dynamicCreativeSchema = z25.object({
   videos: z25.array(dynamicVideoSchema).optional(),
   ad_formats: z25.array(z25.enum(AD_FORMATS2)).min(1),
   call_to_action_types: z25.array(z25.enum(CTA_TYPES2)).optional(),
-  link_urls: z25.array(z25.object({ website_url: httpsUrlSchema3, display_url: z25.string().optional() })).min(1),
-  /** Multi-language / placement customization — structural passthrough for v1. */
-  asset_customization_rules: z25.array(z25.record(z25.string(), z25.unknown())).optional()
+  link_urls: z25.array(z25.object({ website_url: httpsUrlSchema3, display_url: z25.string().optional() })).min(1)
 }).superRefine((p, ctx) => {
   if (!(p.images?.length || p.videos?.length)) {
     ctx.addIssue({
@@ -20302,6 +20407,73 @@ var dynamicCreativeSchema = z25.object({
     });
   }
 });
+var placementRuleSchema = z25.object({
+  ...imageMediaFields,
+  videoId: videoMediaFields.videoId,
+  videoRef: videoMediaFields.videoRef,
+  thumbnailHash: videoMediaFields.thumbnailHash,
+  publisher_platforms: z25.array(z25.enum(CUSTOMIZATION_PLATFORMS)).min(1),
+  facebook_positions: z25.array(z25.string()).optional(),
+  instagram_positions: z25.array(z25.string()).optional(),
+  messenger_positions: z25.array(z25.string()).optional(),
+  audience_network_positions: z25.array(z25.string()).optional(),
+  threads_positions: z25.array(z25.string()).optional()
+}).superRefine((p, ctx) => {
+  const media = countImageRefs(p) + countVideoRefs(p);
+  if (media !== 1) {
+    ctx.addIssue({
+      code: "custom",
+      path: ["imageHash"],
+      message: "each placement rule names exactly one image or one video"
+    });
+  }
+  for (const problem of customizationSpecProblems(p)) {
+    ctx.addIssue({ code: "custom", path: ["publisher_platforms"], message: problem });
+  }
+});
+var placementCreativeSchema = z25.object({
+  creativeType: z25.literal("placement"),
+  ...creativeSharedFields,
+  message: messageSchema,
+  link: httpsUrlSchema3,
+  headline: headlineSchema2.optional(),
+  description: descriptionSchema.optional(),
+  call_to_action: callToActionSchema.optional(),
+  placements: z25.array(placementRuleSchema).min(META_LIMITS.creative.placementRulesMin).max(META_LIMITS.creative.placementRulesMax)
+}).superRefine((p, ctx) => {
+  const images = p.placements.filter((rule) => countImageRefs(rule) === 1).length;
+  if (images > 0 && images < p.placements.length) {
+    ctx.addIssue({
+      code: "custom",
+      path: ["placements"],
+      message: "one asset feed carries one format \u2014 every placement rule must name an image, or every one a video, not a mix; stage the other format as its own creative"
+    });
+  }
+  const seen = /* @__PURE__ */ new Map();
+  p.placements.forEach((rule, index) => {
+    for (const key of customizationPlacementKeys(rule)) {
+      const first = seen.get(key);
+      if (first !== void 0) {
+        ctx.addIssue({
+          code: "custom",
+          path: ["placements", index],
+          message: `${key.replace(":", " ")} is already claimed by rule ${first + 1} \u2014 a placement takes one asset, so Meta cannot resolve two rules naming it`
+        });
+      } else {
+        seen.set(key, index);
+      }
+    }
+  });
+  for (const [index, rule] of p.placements.entries()) {
+    if (rule.instagram_positions?.includes("explore_home") && countVideoRefs(rule) === 1) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["placements", index],
+        message: `Instagram explore_home only supports SINGLE_IMAGE, so it cannot take a video (${PLACEMENT_ASSET_CUSTOMIZATION_DOC})`
+      });
+    }
+  }
+});
 var existingPostCreativeSchema = z25.object({
   creativeType: z25.literal("existing_post"),
   name: creativeSharedFields.name,
@@ -20315,6 +20487,7 @@ var creativeContentSchema2 = z25.discriminatedUnion("creativeType", [
   singleCreativeSchema,
   carouselCreativeSchema2,
   dynamicCreativeSchema,
+  placementCreativeSchema,
   existingPostCreativeSchema
 ]);
 var adCreativeCreateSchema = creativeContentSchema2;
@@ -20888,13 +21061,17 @@ var adCreativesCreateCommand = defineCommand56({
   meta: {
     name: "create",
     description: `Stage a new ad creative. ${STAGED_NOTE2}
-Single-image/video via flags; carousel/dynamic via --file (creativeType carousel|dynamic).
+Single-image/video via flags; carousel/dynamic/placement via --file (creativeType carousel|dynamic|placement).
 Reference media by --image-hash (already on Meta) or --image-ref meta_temp_* (a staged media upload).
+Start here for "the feed asset is 4:5, Stories needs 9:16": creativeType "placement" puts BOTH in one ad, one asset per placement \u2014 then repoint the running ad at it (ads update <adId> --creative <ref>) instead of staging a second ad that competes with it.
 Example: baker ads meta creatives create --page 555 --message "Save now" --link https://x.com --headline "Best cover" --image-hash abc123\u2026 --cta SHOP_NOW`
   },
   args: {
     ...accountArgs2,
-    type: { type: "string", description: "single|carousel|dynamic|existing_post (default single)" },
+    type: {
+      type: "string",
+      description: "single|carousel|dynamic|placement|existing_post (default single). placement = one ad, a different asset per placement"
+    },
     name: { type: "string", description: "Creative name" },
     page: { type: "string", description: "Facebook Page id (identity)" },
     "instagram-user": { type: "string", description: "Instagram account id for IG placements" },