@koda-sl/baker-cli 0.868.0-dev.5be0a9a76 → 0.868.0-dev.dd070597a

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (34) hide show
  1. package/README.md +2 -3
  2. package/dist/{account-reads-SUWXGTGW.js → account-reads-3LP4F3L4.js} +2 -2
  3. package/dist/{add-TKHBYZF6.js → add-ZMOFKHFR.js} +2 -2
  4. package/dist/{ads-U33JFGCR.js → ads-O76TVWHX.js} +2 -2
  5. package/dist/{chunk-TY4MTOTL.js → chunk-MIIY3MVK.js} +1 -22
  6. package/dist/chunk-MIIY3MVK.js.map +1 -0
  7. package/dist/{chunk-LZ5DS4UB.js → chunk-N366L5EF.js} +32 -4
  8. package/dist/chunk-N366L5EF.js.map +1 -0
  9. package/dist/cli.js +3 -3
  10. package/dist/cli.js.map +1 -1
  11. package/dist/{conversion-upload-command-Y4ABNNAT.js → conversion-upload-command-HJOVSWZD.js} +2 -2
  12. package/dist/{draft-CLNMIQXV.js → draft-OLSFLDME.js} +2 -2
  13. package/dist/{flows-FRWZWHXZ.js → flows-PP6BRBD7.js} +3 -3
  14. package/dist/{forecast-JAPRYH4F.js → forecast-AQDB4LLG.js} +2 -2
  15. package/dist/{google-HHKFDH7I.js → google-HLE7YIYM.js} +57 -40
  16. package/dist/google-HLE7YIYM.js.map +1 -0
  17. package/dist/{search-terms-WLOW2FPP.js → search-terms-WKEPRHN2.js} +2 -2
  18. package/dist/{tags-DFCLKJX7.js → tags-IQ6BCRLE.js} +15 -26
  19. package/dist/tags-IQ6BCRLE.js.map +1 -0
  20. package/dist/{themes-Q5CSF6TJ.js → themes-2T5BOIZU.js} +2 -2
  21. package/package.json +1 -1
  22. package/dist/chunk-LZ5DS4UB.js.map +0 -1
  23. package/dist/chunk-TY4MTOTL.js.map +0 -1
  24. package/dist/google-HHKFDH7I.js.map +0 -1
  25. package/dist/tags-DFCLKJX7.js.map +0 -1
  26. /package/dist/{account-reads-SUWXGTGW.js.map → account-reads-3LP4F3L4.js.map} +0 -0
  27. /package/dist/{add-TKHBYZF6.js.map → add-ZMOFKHFR.js.map} +0 -0
  28. /package/dist/{ads-U33JFGCR.js.map → ads-O76TVWHX.js.map} +0 -0
  29. /package/dist/{conversion-upload-command-Y4ABNNAT.js.map → conversion-upload-command-HJOVSWZD.js.map} +0 -0
  30. /package/dist/{draft-CLNMIQXV.js.map → draft-OLSFLDME.js.map} +0 -0
  31. /package/dist/{flows-FRWZWHXZ.js.map → flows-PP6BRBD7.js.map} +0 -0
  32. /package/dist/{forecast-JAPRYH4F.js.map → forecast-AQDB4LLG.js.map} +0 -0
  33. /package/dist/{search-terms-WLOW2FPP.js.map → search-terms-WKEPRHN2.js.map} +0 -0
  34. /package/dist/{themes-Q5CSF6TJ.js.map → themes-2T5BOIZU.js.map} +0 -0
@@ -20,6 +20,7 @@ import {
20
20
  fileLines,
21
21
  googleStaged,
22
22
  googleStagedBatch,
23
+ guidance,
23
24
  handleGoogleError,
24
25
  keywordEntries,
25
26
  listFlag,
@@ -38,7 +39,7 @@ import {
38
39
  targetArg,
39
40
  targetEntries,
40
41
  updateTargets
41
- } from "./chunk-LZ5DS4UB.js";
42
+ } from "./chunk-N366L5EF.js";
42
43
  import "./chunk-RHN5FEWA.js";
43
44
  import {
44
45
  booleanWordPositionalError
@@ -109,8 +110,8 @@ Examples:
109
110
  subCommands: {
110
111
  discover: () => import("./discover-F4TO7A3K.js").then((m) => m.discoverCommand),
111
112
  metrics: () => import("./metrics-S5G6W36J.js").then((m) => m.metricsCommand),
112
- forecast: () => import("./forecast-JAPRYH4F.js").then((m) => m.forecastCommand),
113
- themes: () => import("./themes-Q5CSF6TJ.js").then((m) => m.themesCommand),
113
+ forecast: () => import("./forecast-AQDB4LLG.js").then((m) => m.forecastCommand),
114
+ themes: () => import("./themes-2T5BOIZU.js").then((m) => m.themesCommand),
114
115
  locations: () => import("./locations-OPMVTKHK.js").then((m) => m.locationsCommand),
115
116
  languages: () => import("./languages-AFTPOHIV.js").then((m) => m.languagesCommand)
116
117
  }
@@ -732,9 +733,9 @@ function enableBrandGuidelinesFromFlags(args) {
732
733
  // src/commands/ads/google/criteria-commands.ts
733
734
  import { defineCommand as defineCommand3 } from "citty";
734
735
  var CRITERION_FILE_HELP = 'The `criterion` object is one `criterionType` with its fields, e.g. {"criterionType":"placement","url":"example.com"}, {"criterionType":"ageRange","ageRange":"AGE_RANGE_18_24"}, {"criterionType":"topic","topicConstant":"5"} \u2014 every type with an example: __tooling__/docs/tools/baker/ads-google.md \xA7 Targeting and exclusions.';
735
- var CRITERION_HINTS = [
736
+ var CRITERION_HINTS = guidance(
736
737
  "Run `baker ads google draft validate` once the targeting is staged: Google's dry run is the only thing that proves a criterion is accepted on this campaign before the user publishes."
737
- ];
738
+ );
738
739
  var campaignCriteriaCommand = defineCommand3({
739
740
  meta: {
740
741
  name: "campaign-criteria",
@@ -1228,10 +1229,10 @@ async function readListMembers(customerId, listId) {
1228
1229
 
1229
1230
  // src/commands/ads/google/write-commands.ts
1230
1231
  var STAGED_WRITE = "Stages only \u2014 applies to the live account when the chat is published. Field contract: `baker capabilities google-ads --op <entity>`.";
1231
- var BUDGET_DEMAND_HINTS = [
1232
+ var BUDGET_DEMAND_HINTS = guidance(
1232
1233
  "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.",
1233
1234
  "No volume measured yet? Pull it first \u2014 `baker ads google query --preset search-terms` for what the account already captures, `baker ads google keywords metrics` for the market estimate (those are planner figures, never account performance)."
1234
- ];
1235
+ );
1235
1236
  function budgetAmountsFromFlags(args) {
1236
1237
  if (args.amount !== void 0 && args.total !== void 0) {
1237
1238
  failWriteValidation(
@@ -1251,9 +1252,9 @@ var totalArg = {
1251
1252
  description: "A TOTAL budget instead of a daily one: one amount in major units spent across the campaign's start and end dates (e.g. 300). Search, Performance Max and Demand Gen only; the campaign needs --end-date; never shared. A budget stays daily or total for life."
1252
1253
  }
1253
1254
  };
1254
- var BUDGET_REMOVE_HINTS = [
1255
+ var BUDGET_REMOVE_HINTS = guidance(
1255
1256
  "A budget can be removed only once no campaign uses it: staging refuses it while one does, unless this draft removes those campaigns or moves them to another budget (publish sends the campaign changes first)."
1256
- ];
1257
+ );
1257
1258
  var budgetsCommand = defineCommand4({
1258
1259
  meta: { name: "budgets", description: "Stage campaign budget create/update/remove" },
1259
1260
  subCommands: {
@@ -1934,6 +1935,7 @@ var campaignsCommand = defineCommand4({
1934
1935
  }
1935
1936
  });
1936
1937
  function statusCommand(kind, entity, hints) {
1938
+ const said = hints && guidance(...hints);
1937
1939
  return withEffect(
1938
1940
  googleStaged(kind),
1939
1941
  defineCommand4({
@@ -1947,7 +1949,7 @@ function statusCommand(kind, entity, hints) {
1947
1949
  },
1948
1950
  run: async ({ args }) => {
1949
1951
  const customerId = requireCustomerId(args);
1950
- await stageTarget(kind, customerId, requireTarget(args, entity), hints);
1952
+ await stageTarget(kind, customerId, requireTarget(args, entity), said);
1951
1953
  }
1952
1954
  })
1953
1955
  );
@@ -2090,10 +2092,10 @@ var adGroupsCommand = defineCommand4({
2090
2092
  remove: statusCommand("google.adGroup.remove", "ad group")
2091
2093
  }
2092
2094
  });
2093
- var KEYWORD_KILL_HINTS = [
2095
+ var KEYWORD_KILL_HINTS = guidance(
2094
2096
  "Keyword metrics are per ad group. Decide this from keyword_view rows carrying ad_group.id + ad_group_criterion.criterion_id (`--preset keyword-analysis` returns both) \u2014 never from campaign totals or metrics summed across ad groups.",
2095
2097
  "The same keyword text in several ad groups shares ONE criterion id, so an aggregate blends the copy that holds the history with the copies that never served. Compare the copies row by row and keep the one with the impressions/conversions; if the keyword is duplicated and only one copy performs, pause the others, not it."
2096
- ];
2098
+ );
2097
2099
  function keywordKillHints(status) {
2098
2100
  const kills = typeof status === "string" && ["PAUSED", "REMOVED"].includes(status.toUpperCase());
2099
2101
  return kills ? KEYWORD_KILL_HINTS : [];
@@ -3132,7 +3134,9 @@ var assetGroupsCommand = defineCommand4({
3132
3134
  });
3133
3135
  await stageCreate("google.assetGroup.create", customerId, payload, [
3134
3136
  ...copyListSplitHints(args),
3135
- "Performance Max has no keywords: give this group its search themes (and its audience signal, when the account has one) with `baker ads google asset-group-signals add --asset-group <its ref>` in this same draft."
3137
+ ...guidance(
3138
+ "Performance Max has no keywords: give this group its search themes (and its audience signal, when the account has one) with `baker ads google asset-group-signals add --asset-group <its ref>` in this same draft."
3139
+ )
3136
3140
  ]);
3137
3141
  }
3138
3142
  })
@@ -3185,11 +3189,16 @@ var assetGroupsCommand = defineCommand4({
3185
3189
  asset: args["asset-ref"],
3186
3190
  fieldType: args["field-type"]
3187
3191
  });
3188
- await stageCreate("google.assetGroupAsset.attach", customerId, payload, [
3189
- "Swapping a creative? Stage the matching `asset-groups detach` for the image this one replaces \u2014 an attach alone grows the group instead of refreshing it.",
3190
- "The field type must match the image's real ratio (1.91:1 \u2192 MARKETING_IMAGE, 1:1 \u2192 SQUARE_MARKETING_IMAGE, 4:5 \u2192 PORTRAIT_MARKETING_IMAGE); Google rejects a mismatch at publish.",
3191
- "Slots have ceilings as well as minimums: BUSINESS_NAME and CALL_TO_ACTION_SELECTION hold 1, LOGO 5, LONG_HEADLINE and DESCRIPTION 5, HEADLINE 15, YOUTUBE_VIDEO 15, images 20. Staging counts what the group holds plus this chat's attaches and detaches, and refuses an attach to a full slot \u2014 stage the detach alongside it; removals are sent after additions. Replacing the business name (exactly 1): stage its detach first, then this attach."
3192
- ]);
3192
+ await stageCreate(
3193
+ "google.assetGroupAsset.attach",
3194
+ customerId,
3195
+ payload,
3196
+ guidance(
3197
+ "Swapping a creative? Stage the matching `asset-groups detach` for the image this one replaces \u2014 an attach alone grows the group instead of refreshing it.",
3198
+ "The field type must match the image's real ratio (1.91:1 \u2192 MARKETING_IMAGE, 1:1 \u2192 SQUARE_MARKETING_IMAGE, 4:5 \u2192 PORTRAIT_MARKETING_IMAGE); Google rejects a mismatch at publish.",
3199
+ "Slots have ceilings as well as minimums: BUSINESS_NAME and CALL_TO_ACTION_SELECTION hold 1, LOGO 5, LONG_HEADLINE and DESCRIPTION 5, HEADLINE 15, YOUTUBE_VIDEO 15, images 20. Staging counts what the group holds plus this chat's attaches and detaches, and refuses an attach to a full slot \u2014 stage the detach alongside it; removals are sent after additions. Replacing the business name (exactly 1): stage its detach first, then this attach."
3200
+ )
3201
+ );
3193
3202
  }
3194
3203
  })
3195
3204
  ),
@@ -3203,10 +3212,10 @@ function imageAssetHints(payload) {
3203
3212
  if (payload.type !== "image") {
3204
3213
  return [];
3205
3214
  }
3206
- return [
3215
+ return guidance(
3207
3216
  "This image publishes into the advertiser's Google Ads asset library. Stage the `assets attach` too, with field type AD_IMAGE on the campaign (or ad group) it belongs on: Google opens Search image links per account, so Baker asks Google as you stage \u2014 where the account takes them the link is staged and applies at publish, and where it does not the link is skipped and names the campaign in the handover Task.",
3208
3217
  "Until a link to it is staged, Baker keeps a Task for this image in this chat's changes \u2014 the user adding it to the campaign under Assets \u2014 and withdraws it when an accepted link names the image; do not stage a second one with `baker actions`. If that Task is still there after the attach, tell the user the images are already in their Google Ads account and only need adding to the campaign under Assets, and name them. Never tell them to upload images they already have. (A Performance Max asset group is different \u2014 images link there with `asset-groups attach`.)"
3209
- ];
3218
+ );
3210
3219
  }
3211
3220
  var assetsUpdateCommand = withEffect(
3212
3221
  googleStaged("google.asset.update"),
@@ -3252,6 +3261,11 @@ var assetsUpdateCommand = withEffect(
3252
3261
  }
3253
3262
  })
3254
3263
  );
3264
+ function imageLinkHints(payload) {
3265
+ return typeof payload.fieldType === "string" && /IMAGE|LOGO/i.test(payload.fieldType) ? guidance(
3266
+ 'Search image extensions link as AD_IMAGE, at campaign or ad group level: `{"level":"campaign","parent":"<campaign id>","asset":"<image asset id or g_temp_ ref>","fieldType":"AD_IMAGE"}`. Google opens these per advertiser account, so Baker asks Google (a check that changes nothing) as you stage. The image must be 1.91:1 or 1:1 \u2014 any other shape is sent back to crop. Accepted \u2192 the link is staged and applies at publish. Refused or not confirmed \u2192 it is skipped rather than stored, the rest of a batch is unaffected, and Baker stages the handover Task naming those images and that campaign; then tell the user they are already in their Google Ads account and only need adding to the campaign under Assets, and do not stage a second Task with `baker actions`. MARKETING_IMAGE / SQUARE_MARKETING_IMAGE are Performance Max asset-group slots (`asset-groups attach`), never a Search link. The advertiser\'s logo links as `BUSINESS_LOGO` (campaign or customer level, on a verified account).'
3267
+ ) : [];
3268
+ }
3255
3269
  var assetsCommand = defineCommand4({
3256
3270
  meta: {
3257
3271
  name: "assets",
@@ -3265,9 +3279,12 @@ var assetsCommand = defineCommand4({
3265
3279
  imageAssetHints
3266
3280
  ),
3267
3281
  update: assetsUpdateCommand,
3268
- attach: fileCreateCommand("attach", "google.assetLink.attach", "Attach an asset to a campaign/adGroup/customer", [
3269
- 'Search image extensions link as AD_IMAGE, at campaign or ad group level: `{"level":"campaign","parent":"<campaign id>","asset":"<image asset id or g_temp_ ref>","fieldType":"AD_IMAGE"}`. Google opens these per advertiser account, so Baker asks Google (a check that changes nothing) as you stage. The image must be 1.91:1 or 1:1 \u2014 any other shape is sent back to crop. Accepted \u2192 the link is staged and applies at publish. Refused or not confirmed \u2192 it is skipped rather than stored, the rest of a batch is unaffected, and Baker stages the handover Task naming those images and that campaign; then tell the user they are already in their Google Ads account and only need adding to the campaign under Assets, and do not stage a second Task with `baker actions`. MARKETING_IMAGE / SQUARE_MARKETING_IMAGE are Performance Max asset-group slots (`asset-groups attach`), never a Search link. The advertiser\'s logo links as `BUSINESS_LOGO` (campaign or customer level, on a verified account).'
3270
- ]),
3282
+ attach: fileCreateCommand(
3283
+ "attach",
3284
+ "google.assetLink.attach",
3285
+ "Attach an asset to a campaign/adGroup/customer",
3286
+ imageLinkHints
3287
+ ),
3271
3288
  detach: statusCommand("google.assetLink.detach", "asset link", [
3272
3289
  "Pass the resource name Google gave you \u2014 `SELECT campaign_asset.resource_name \u2026 FROM campaign_asset WHERE campaign_asset.status != 'REMOVED'` (or `ad_group_asset` / `customer_asset`) \u2014 never one composed out of an owner id and an asset id. A link's own status is not its campaign's and not its ad group's, so an inventory read scoped only to those lists extensions that are already detached, and a link between an asset and an owner that never held it parses fine and exists nowhere. Either way the target is read back before it is staged, and a detach of a link that is not there is refused here rather than at publish."
3273
3290
  ])
@@ -3295,10 +3312,10 @@ function requireAudienceLevel(value) {
3295
3312
  }
3296
3313
  return level;
3297
3314
  }
3298
- var AUDIENCE_ATTACH_HINTS = [
3315
+ var AUDIENCE_ATTACH_HINTS = guidance(
3299
3316
  'Read back what the parent ended up with before you report: `baker ads google query "SELECT campaign.id, campaign.targeting_setting.target_restrictions FROM campaign"` (or the ad_group equivalent). A missing AUDIENCE row means TARGETING \u2014 Google does not serialize an empty setting, so absence is a value, not a gap.',
3300
3317
  "Staging checks the list is big enough to serve on this campaign's network (100 active users on search, display and YouTube) and refuses a targeting attach that is not. It does NOT check delivery afterwards, and Google reports no error when an audience stops a campaign serving \u2014 after publishing, read the campaign's impressions for the hour that follows and say what you saw."
3301
- ];
3318
+ );
3302
3319
  var audiencesAttachCommand = withEffect(
3303
3320
  googleStagedBatch("google.audienceCriterion.attach"),
3304
3321
  defineCommand4({
@@ -3408,12 +3425,12 @@ var audiencesCommand = defineCommand4({
3408
3425
  }
3409
3426
  });
3410
3427
  var PRIMARY_FOR_GOAL_QUERY = 'baker ads google query "SELECT conversion_action.name, conversion_action.primary_for_goal, conversion_action.status FROM conversion_action"';
3411
- var CONVERSION_CREATE_HINTS = [
3428
+ var CONVERSION_CREATE_HINTS = guidance(
3412
3429
  `A new conversion action is staged as SECONDARY (reported, not bid toward) unless the payload says \`"primaryForGoal": true\` \u2014 Google otherwise decides for you, and an accidentally-primary action redirects the spend of every Maximize Conversions / Target CPA campaign. Ask the user which they want rather than guessing.`
3413
- ];
3414
- var CONVERSION_ROLE_HINTS = [
3430
+ );
3431
+ var CONVERSION_ROLE_HINTS = guidance(
3415
3432
  `Primary actions are what Maximize Conversions / Target CPA campaigns bid toward. Before publishing, list what the account will be left with: ${PRIMARY_FOR_GOAL_QUERY} \u2014 and say so if this leaves no primary action, because bidding then has nothing to optimize toward.`
3416
- ];
3433
+ );
3417
3434
  function conversionGoalFromFlags(args) {
3418
3435
  const booleanWord = booleanWordPositionalError(args, "conversion goal");
3419
3436
  if (booleanWord) {
@@ -3435,16 +3452,16 @@ function conversionGoalFromFlags(args) {
3435
3452
  return { category, origin, biddable: args.biddable };
3436
3453
  }
3437
3454
  var CONVERSION_GOAL_QUERY = 'baker ads google query "SELECT customer_conversion_goal.category, customer_conversion_goal.origin, customer_conversion_goal.biddable FROM customer_conversion_goal"';
3438
- var CONVERSION_GOAL_HINTS = [
3455
+ var CONVERSION_GOAL_HINTS = guidance(
3439
3456
  `A conversion drives automated bidding only when BOTH halves are on: the action is primary (\`conversions update --primary\`) AND its category's account-level goal is included (this command). Before publishing, read back what the account will bid toward: ${CONVERSION_GOAL_QUERY} \u2014 and say plainly which conversions this leaves driving spend.`
3440
- ];
3457
+ );
3441
3458
  var conversionsCommand = defineCommand4({
3442
3459
  meta: {
3443
3460
  name: "conversions",
3444
3461
  description: "Stage conversion action create/update (via --file), the account-level goal, and manual conversion uploads for a period where tracking was broken"
3445
3462
  },
3446
3463
  subCommands: {
3447
- upload: () => import("./conversion-upload-command-Y4ABNNAT.js").then((m) => m.conversionsUploadCommand),
3464
+ upload: () => import("./conversion-upload-command-HJOVSWZD.js").then((m) => m.conversionsUploadCommand),
3448
3465
  create: fileCreateCommand(
3449
3466
  "create",
3450
3467
  "google.conversionAction.create",
@@ -3696,7 +3713,7 @@ var keywordsWithWrites = defineCommand5({
3696
3713
  }
3697
3714
  });
3698
3715
  var GROUP_READS = {
3699
- "negative-keywords": { check: () => import("./search-terms-WLOW2FPP.js").then((m) => m.negativeCheckCommand) }
3716
+ "negative-keywords": { check: () => import("./search-terms-WKEPRHN2.js").then((m) => m.negativeCheckCommand) }
3700
3717
  };
3701
3718
  function withList(thing, command) {
3702
3719
  const list2 = LIST_COMMANDS[thing];
@@ -3747,19 +3764,19 @@ Full guide: __tooling__/docs/tools/baker/ads-google.md`
3747
3764
  currency: () => import("./currency-NRI2TLP3.js").then((m) => m.currencyCommand),
3748
3765
  "url-options": () => import("./url-options-BANFHIHH.js").then((m) => m.urlOptionsCommand),
3749
3766
  changes: () => import("./changes-CNGAKH52.js").then((m) => m.changesCommand),
3750
- invoices: () => import("./account-reads-SUWXGTGW.js").then((m) => m.invoicesCommand),
3751
- "identity-verification": () => import("./account-reads-SUWXGTGW.js").then((m) => m.identityVerificationCommand),
3752
- previews: () => import("./account-reads-SUWXGTGW.js").then((m) => m.previewsCommand),
3753
- brands: () => import("./account-reads-SUWXGTGW.js").then((m) => m.brandsCommand),
3767
+ invoices: () => import("./account-reads-3LP4F3L4.js").then((m) => m.invoicesCommand),
3768
+ "identity-verification": () => import("./account-reads-3LP4F3L4.js").then((m) => m.identityVerificationCommand),
3769
+ previews: () => import("./account-reads-3LP4F3L4.js").then((m) => m.previewsCommand),
3770
+ brands: () => import("./account-reads-3LP4F3L4.js").then((m) => m.brandsCommand),
3754
3771
  query: () => import("./query-5XB5OP4B.js").then((m) => m.queryCommand),
3755
- "search-terms": () => import("./search-terms-WLOW2FPP.js").then((m) => m.searchTermsCommand),
3772
+ "search-terms": () => import("./search-terms-WKEPRHN2.js").then((m) => m.searchTermsCommand),
3756
3773
  keywords: keywordsWithWrites,
3757
3774
  ...googleWriteCommandsWithLists,
3758
3775
  "merchant-center": merchantCenterCommand,
3759
- draft: () => import("./draft-CLNMIQXV.js").then((m) => m.draftCommand)
3776
+ draft: () => import("./draft-OLSFLDME.js").then((m) => m.draftCommand)
3760
3777
  }
3761
3778
  });
3762
3779
  export {
3763
3780
  googleCommand
3764
3781
  };
3765
- //# sourceMappingURL=google-HHKFDH7I.js.map
3782
+ //# sourceMappingURL=google-HLE7YIYM.js.map