@koda-sl/baker-cli 0.255.0 → 0.257.0

package/README.md

@@ -3024,7 +3024,7 @@ baker scheduled-actions create --template baker-ads --name "Weekly ad review" --
 Rules:
 
 - `--cron` and `--run-at` are mutually exclusive.
-- `--run-at` must be an ISO UTC timestamp ending in `Z`.
+- `--run-at` must be an ISO UTC timestamp ending in `Z`, and still in the future — a time that has already passed is refused when the op is staged. If a one-off's time passes while the chat is still open, publishing creates the task **switched off** with the reason on it rather than dropping it, so it is never lost.
 - Draft-created ids use `temp_sched_*`; use them with `get`, `update`, or `delete` before publish.
 - Staged commands require `BAKER_CHAT_ID` to point to an `in_progress` chat.
 - `trigger` rejects `temp_sched_*` and only accepts published scheduled-action ids.
@@ -5843,6 +5843,10 @@ Pushing to `main` with changes in `packages/cli/` triggers the GitHub Actions wo
 
   Three more things the 202608 pin brought with it. **The conversion-type enum went from 8 values to all 34 LinkedIn accepts** — `QUALIFIED_LEAD`, `BOOK_APPOINTMENT`, `SUBMIT_APPLICATION` and 23 others were rejected by our own schema before the request ever left, and 202608 adds `MARKETING_QUALIFIED_LEAD` / `SALES_QUALIFIED_LEAD` on top. **Attribution windows gained 365** (and view-through gained 90), with the type-conditional rule enforced on `conversions create`: 365 is only legal for `SUBMIT_APPLICATION`, `PURCHASE`, `ADD_TO_CART`, `QUALIFIED_LEAD`, `LEAD`. And **a 429 carrying `SEGMENT_LIMIT_EXCEEDED` is no longer reported as a throttle** — 202608 caps an ad account at 1,000 DMP segments and reuses the rate-limit status for it, so an agent that read it as "retry in a second" would have retried forever against a cap only a human can clear in Campaign Manager.
 
+- **0.256.0**: **`assets attach` no longer offers an image link, because Google accepts none.** A production publish came back with six `AssetLinkError.FIELD_TYPE_INCOMPATIBLE_WITH_CAMPAIGN_TYPE` rows (trigger `MARKETING_IMAGE,SEARCH`) on an otherwise built and live Search campaign — staged exactly as this CLI's own advisory and the scaffold's ads-google doc instructed, at `"fieldType": "MARKETING_IMAGE"`. The obvious fix was `AD_IMAGE`, which is what Google's documentation and its own forum answers name for a Search image extension. **It does not work either.** Sent to a real account on v23, all four combinations are refused: `MARKETING_IMAGE` on a Search `CampaignAsset` → `FIELD_TYPE_INCOMPATIBLE_WITH_CAMPAIGN_TYPE`; `MARKETING_IMAGE` on a Search `AdGroupAsset` → `UNSUPPORTED_FIELD_TYPE`; `AD_IMAGE` on a `CampaignAsset` → `UNSUPPORTED_FIELD_TYPE`; `AD_IMAGE` on an `AdGroupAsset` → `UNSUPPORTED_FIELD_TYPE`. Image extensions never moved to asset-based extensions, so there is no request the API takes. Every image field type is now refused at the CLI boundary with the interface named instead of another field type to try, and the **"recommend at least 3 image assets" advisory is removed** — it had been firing on every Search campaign since 0.191.0 and could not be satisfied by any draft, because the write it named has never once succeeded. Performance Max asset-group images are a different mechanism and are untouched (`asset-groups attach`). Four force-synced scaffold surfaces were saying the same wrong thing and now agree with the API: the `ads-google.md` tool doc, the `assets` command group description, the account-audit playbook's Dynamic Images row, and `staged-writes.md`. An audit should still raise a missing-images gap — it is a real SERP disadvantage — it just has to name the Google Ads interface as the fix rather than a command.
+
+- **0.256.0**: a structured snippet value over 25 characters is refused before it is staged. Google caps each VALUE at 25 and answers a longer one with a bare `Too long.` at `structured_snippet_asset.values[i]` — no header, no value, nothing to act on — and it takes the asset's campaign link down with it as `RESOURCE_NOT_FOUND`. `assets create --values` and `assets update --values` now cap each entry; the per-asset 3-10 count check was already there, and only the per-value length was missing. Found on a live publish where four of five values were fine and "Bases de datos vectoriales" (26) was not, and confirmed fixed by re-publishing the same snippet at 25 characters against a real account, where it applied and linked cleanly.
+
 ### Testing a pre-release in sandboxes
 
 ```bash

package/dist/cli.js

@@ -2113,7 +2113,14 @@ var GOOGLE_ADS_LIMITS = {
     // Google's published headers (`structured-snippet-headers.ts`), the longest
     // of which is 29 characters. Only the values are capped.
     structuredSnippetValuesMin: 3,
-    structuredSnippetValuesMax: 10
+    structuredSnippetValuesMax: 10,
+    /**
+     * Per VALUE, not per asset. Google rejects a 26-character value with a bare "Too long." at
+     * `structured_snippet_asset.values[i]` — one red row inside an otherwise clean publish, plus
+     * every link that depends on the asset. Confirmed live on v23: "Bases de datos vectoriales"
+     * (26) rejected, its four neighbours accepted.
+     */
+    structuredSnippetValueMax: 25
   },
   conversionAction: {
     nameMax: 255
@@ -2296,9 +2303,24 @@ var ASSET_FIELD_TYPES = [
   "HEADLINE",
   "DESCRIPTION",
   "LOGO",
+  /**
+   * Kept because a draft staged before {@link IMAGE_ASSET_LINK_MESSAGE} shipped may still carry one,
+   * and because it is the field type an asset-group image occupies. It is refused on an
+   * `assetLink.attach` — see that message for what Google actually does with it.
+   */
   "MARKETING_IMAGE",
   "BUSINESS_NAME"
 ];
+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.";
+function isImageAssetLinkFieldType(fieldType) {
+  return IMAGE_ASSET_LINK_FIELD_TYPES.has(fieldType);
+}
 var ASSET_GROUP_ASSET_FIELD_TYPES = [
   "MARKETING_IMAGE",
   "SQUARE_MARKETING_IMAGE",
@@ -3151,7 +3173,7 @@ var structuredSnippetHeaderSchema = z4.string().min(1).transform((header, ctx) =
 var structuredSnippetAssetSchema = z4.object({
   type: z4.literal("structuredSnippet"),
   header: structuredSnippetHeaderSchema,
-  values: z4.array(z4.string().min(1)).min(GOOGLE_ADS_LIMITS.asset.structuredSnippetValuesMin).max(GOOGLE_ADS_LIMITS.asset.structuredSnippetValuesMax)
+  values: z4.array(z4.string().min(1).max(GOOGLE_ADS_LIMITS.asset.structuredSnippetValueMax)).min(GOOGLE_ADS_LIMITS.asset.structuredSnippetValuesMin).max(GOOGLE_ADS_LIMITS.asset.structuredSnippetValuesMax)
 });
 var callToActionAssetSchema = z4.object({ type: z4.literal("callToAction"), callToAction: z4.string().min(1) });
 var assetCreateSchema = z4.discriminatedUnion("type", [
@@ -3171,7 +3193,7 @@ var assetUpdateSchema = z4.object({
   finalUrls: z4.array(httpsUrlSchema2).min(1).optional(),
   calloutText: z4.string().min(1).max(GOOGLE_ADS_LIMITS.asset.calloutTextMax).optional(),
   header: structuredSnippetHeaderSchema.optional(),
-  values: z4.array(z4.string().min(1)).min(GOOGLE_ADS_LIMITS.asset.structuredSnippetValuesMin).max(GOOGLE_ADS_LIMITS.asset.structuredSnippetValuesMax).optional(),
+  values: z4.array(z4.string().min(1).max(GOOGLE_ADS_LIMITS.asset.structuredSnippetValueMax)).min(GOOGLE_ADS_LIMITS.asset.structuredSnippetValuesMin).max(GOOGLE_ADS_LIMITS.asset.structuredSnippetValuesMax).optional(),
   callToAction: z4.string().min(1).optional(),
   text: z4.string().min(1).optional()
 }).refine((p) => Object.values(p).some((v) => v !== void 0), "update needs at least one field");
@@ -3179,7 +3201,11 @@ var assetLinkAttachSchema = z4.object({
   level: z4.enum(["campaign", "adGroup", "customer"]),
   parent: refSchema.optional(),
   asset: refSchema,
-  fieldType: z4.enum(ASSET_FIELD_TYPES)
+  // A plain string, not `z.enum(ASSET_FIELD_TYPES)`, so the image refusal below can answer with
+  // the reason instead of an enum listing. An agent reaching for AD_IMAGE is following Google's
+  // own documentation; "Invalid option: expected one of …" sends it to guess another field type,
+  // which is the failure this whole refusal exists to end.
+  fieldType: z4.string().min(1)
 }).superRefine((value, ctx) => {
   if (value.level !== "customer" && !value.parent) {
     ctx.addIssue({
@@ -3188,6 +3214,15 @@ var assetLinkAttachSchema = z4.object({
       message: `parent is required for a ${value.level}-level asset link (--parent-ref)`
     });
   }
+  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({
+      code: z4.ZodIssueCode.custom,
+      path: ["fieldType"],
+      message: `expected one of ${ASSET_FIELD_TYPES.join(" | ")}`
+    });
+  }
 });
 var assetGroupCreateSchema = z4.object({
   campaign: refSchema,
@@ -14861,7 +14896,7 @@ var assetsUpdateCommand = defineCommand30({
     "final-urls": { type: "string", description: "Comma-separated sitelink final URLs" },
     "callout-text": { type: "string", description: "Callout text" },
     header: { type: "string", description: "Structured snippet header" },
-    values: { type: "string", description: "Comma-separated structured snippet values" },
+    values: { type: "string", description: "Comma-separated structured snippet values (3-10, max 25 characters each)" },
     cta: { type: "string", description: "Call-to-action text" },
     text: { type: "string", description: "Text asset content" }
   },
@@ -14886,7 +14921,7 @@ 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, \u22651 structured snippet, and \u22653 image assets per campaign. Build the images with the creative-canvas-ads flow (platform preset `google_search`) \u2014 product or team in action, never stock, and never a logo on a plain background."
+    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."
   },
   subCommands: {
     create: fileCreateCommand(
@@ -14895,7 +14930,9 @@ var assetsCommand = defineCommand30({
       "Stage an asset (text/image/sitelink/callout/structuredSnippet/\u2026)"
     ),
     update: assetsUpdateCommand,
-    attach: fileCreateCommand("attach", "google.assetLink.attach", "Attach an asset to a campaign/adGroup/customer"),
+    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`)."
+    ]),
     detach: statusCommand2("google.assetLink.detach", "asset link")
   }
 });
@@ -47638,6 +47675,20 @@ function parseBooleanFlag(raw, flagName) {
   }
   failValidation4(`${flagName} must be true or false.`);
 }
+function validateRunAt(runAt) {
+  if (!runAt.endsWith("Z")) {
+    failValidation4("--run-at must be an ISO UTC timestamp ending in Z.");
+  }
+  const parsed = Date.parse(runAt);
+  if (!Number.isFinite(parsed)) {
+    failValidation4("--run-at must be a valid ISO timestamp.");
+  }
+  if (parsed <= Date.now()) {
+    failValidation4(
+      `--run-at ${runAt} has already passed. A one-off task only runs at a time still to come \u2014 pass a later ISO UTC timestamp, and check which timezone you converted from if you worked it out from a local time.`
+    );
+  }
+}
 function buildScheduleBody(args, options) {
   const cron = args.cron;
   const runAt = args["run-at"];
@@ -47646,12 +47697,7 @@ function buildScheduleBody(args, options) {
     failValidation4("--cron and --run-at are mutually exclusive.");
   }
   if (runAt) {
-    if (!runAt.endsWith("Z")) {
-      failValidation4("--run-at must be an ISO UTC timestamp ending in Z.");
-    }
-    if (!Number.isFinite(Date.parse(runAt))) {
-      failValidation4("--run-at must be a valid ISO timestamp.");
-    }
+    validateRunAt(runAt);
     return { runAt, ...timezone ? { timezone } : {} };
   }
   if (cron) {
@@ -47676,7 +47722,7 @@ registerSchema({
     cron: { type: "string", description: "5-field cron expression; mutually exclusive with --run-at", required: false },
     "run-at": {
       type: "string",
-      description: "ISO UTC timestamp ending in Z; mutually exclusive with --cron",
+      description: "When this runs once, as an ISO UTC timestamp ending in Z. Must still be in the future \u2014 a time that has passed is refused. Mutually exclusive with --cron.",
       required: false
     },
     timezone: { type: "string", description: "IANA timezone override; defaults to Company Timezone", required: false },
@@ -47710,7 +47756,7 @@ var createCommand3 = defineCommand181({
     name: { type: "string", description: "Scheduled action name", required: false },
     description: { type: "string", description: "Description", required: false },
     cron: { type: "string", description: "5-field cron expression", required: false },
-    "run-at": { type: "string", description: "ISO UTC timestamp ending in Z", required: false },
+    "run-at": { type: "string", description: "ISO UTC timestamp ending in Z, still in the future", required: false },
     timezone: { type: "string", description: "IANA timezone override", required: false },
     disabled: { type: "boolean", description: "Create disabled", required: false, default: false },
     mode: { type: "string", description: `One of: ${TASK_MODE_IDS.join(", ")}`, required: false },
@@ -48081,7 +48127,7 @@ registerSchema({
     cron: { type: "string", description: "5-field cron expression; mutually exclusive with --run-at", required: false },
     "run-at": {
       type: "string",
-      description: "ISO UTC timestamp ending in Z; mutually exclusive with --cron",
+      description: "New one-off run time, as an ISO UTC timestamp ending in Z. Must still be in the future \u2014 a time that has passed is refused. Mutually exclusive with --cron.",
       required: false
     },
     timezone: { type: "string", description: "IANA timezone override", required: false },
@@ -48116,7 +48162,7 @@ var updateCommand3 = defineCommand187({
     name: { type: "string", description: "New name", required: false },
     description: { type: "string", description: "New description", required: false },
     cron: { type: "string", description: "5-field cron expression", required: false },
-    "run-at": { type: "string", description: "ISO UTC timestamp ending in Z", required: false },
+    "run-at": { type: "string", description: "ISO UTC timestamp ending in Z, still in the future", required: false },
     timezone: { type: "string", description: "IANA timezone override", required: false },
     enabled: { type: "string", description: "true|false", required: false },
     mode: { type: "string", description: `One of: ${TASK_MODE_IDS.join(", ")}`, required: false },