@koda-sl/baker-cli 0.163.0 → 0.164.0

package/README.md

@@ -502,7 +502,17 @@ Reference not-yet-created resources with `g_temp_*` refs returned by earlier `cr
 baker ads google budgets create --customer-id 1234567890 --name "Search budget" --amount 50
 # → { ref: "g_temp_ab12", ... }
 baker ads google campaigns create --customer-id 1234567890 --name "Brand — Search" \
-  --channel-type SEARCH --budget-ref g_temp_ab12 --bidding-strategy MANUAL_CPC
+  --channel-type SEARCH --budget-ref g_temp_ab12 --bidding-strategy MANUAL_CPC \
+  --geo-target-type PRESENCE
+# --geo-target-type is the campaign's location option: PRESENCE (only people in your targeted
+# locations) or PRESENCE_OR_INTEREST (also people interested in them). Google applies
+# PRESENCE_OR_INTEREST when the flag is omitted, so pass PRESENCE for local/in-store/service-area
+# campaigns; --negative-geo-target-type does the same for excluded locations.
+# Campaign URL options stage on create and update: --final-url-suffix (bare query params),
+# --tracking-template "https://tracker.example/?url={lpurl}" (must carry {lpurl}), and
+# --custom-param key=value (repeatable, up to 8; --clear-custom-params empties the set).
+# "" clears the suffix or template back to the account value. The ACCOUNT level is not
+# stageable — Google writes it through a different service than the atomic publish batch.
 # New campaigns are declared as NOT containing EU political advertising (Google requires the
 # declaration on every create); pass --eu-political-ads only when the campaign does contain it.
 # On update, --eu-political-ads / --eu-political-ads=false corrects an existing declaration.

package/dist/cli.js

@@ -4489,7 +4489,13 @@ var GOOGLE_ADS_LIMITS = {
   campaign: {
     nameMax: 255,
     /** `campaign.final_url_suffix` — the query string appended to every final URL under the campaign. */
-    finalUrlSuffixMax: 2048
+    finalUrlSuffixMax: 2048,
+    /** `campaign.tracking_url_template` — the click-measurement URL every ad routes through. */
+    trackingUrlTemplateMax: 2048,
+    /** `campaign.url_custom_parameters` — Google caps a single entity at 8 `{_name}` parameters. */
+    urlCustomParametersMax: 8,
+    urlCustomParameterKeyMax: 16,
+    urlCustomParameterValueMax: 250
   },
   adGroup: {
     nameMax: 255
@@ -4609,6 +4615,8 @@ var BIDDING_STRATEGY_TYPES = [
   "MANUAL_CPV",
   "PERCENT_CPC"
 ];
+var POSITIVE_GEO_TARGET_TYPES = ["PRESENCE_OR_INTEREST", "PRESENCE"];
+var NEGATIVE_GEO_TARGET_TYPES = ["PRESENCE_OR_INTEREST", "PRESENCE"];
 var BUDGET_DELIVERY_METHODS = ["STANDARD", "ACCELERATED"];
 var AD_GROUP_TYPES = [
   "SEARCH_STANDARD",
@@ -4704,6 +4712,23 @@ var customerIdSchema = z13.string().regex(NUMERIC_ID_REGEX2, "customerId must be
 var stageableStatusSchema2 = z13.enum(STAGEABLE_CREATE_STATUSES2);
 var matchTypeSchema = z13.enum(KEYWORD_MATCH_TYPES);
 var finalUrlSuffixSchema = z13.string().max(GOOGLE_ADS_LIMITS.campaign.finalUrlSuffixMax).refine((s) => !/^[?&]/.test(s), "drop the leading ? or & \u2014 a final URL suffix is bare query parameters").refine((s) => !s.includes("{lpurl}"), "{lpurl} belongs in a tracking template, not in a final URL suffix").refine((s) => !/\s/.test(s), "a final URL suffix cannot contain whitespace").refine((s) => s === "" || s.includes("="), 'expected key=value pairs, e.g. "utm_source=google&utm_agency=baker"');
+var LANDING_PAGE_TAGS = ["{lpurl}", "{unescapedlpurl}", "{escapedlpurl}", "{lpurl+2}", "{lpurl+3}"];
+var trackingUrlTemplateSchema = z13.string().max(GOOGLE_ADS_LIMITS.campaign.trackingUrlTemplateMax).refine((t) => !/\s/.test(t), "a tracking template cannot contain whitespace").refine(
+  (t) => t === "" || LANDING_PAGE_TAGS.some((tag) => t.includes(tag)),
+  `a tracking template must carry the landing page through one of ${LANDING_PAGE_TAGS.join(", ")}, e.g. "https://tracker.example/?url={lpurl}"`
+).refine(
+  (t) => t === "" || /^(https?:\/\/|\{)/.test(t),
+  "a tracking template must start with http://, https:// or a {lpurl} tag"
+);
+var urlCustomParametersSchema = z13.array(
+  z13.strictObject({
+    key: z13.string().min(1).max(GOOGLE_ADS_LIMITS.campaign.urlCustomParameterKeyMax).regex(/^[A-Za-z0-9_]+$/, "a custom parameter key is letters, digits and underscores only"),
+    value: z13.string().max(GOOGLE_ADS_LIMITS.campaign.urlCustomParameterValueMax)
+  })
+).max(GOOGLE_ADS_LIMITS.campaign.urlCustomParametersMax).refine(
+  (params) => new Set(params.map((p) => p.key)).size === params.length,
+  "each custom parameter key can appear only once"
+);
 var keywordTextSchema = z13.string().min(1).max(GOOGLE_ADS_LIMITS.keyword.textMax).refine((t) => t.trim().split(/\s+/).length <= GOOGLE_ADS_LIMITS.keyword.wordsMax, "keyword exceeds 10 words");
 var budgetCreateSchema = z13.object({
   name: z13.string().min(1).max(GOOGLE_ADS_LIMITS.budget.nameMax),
@@ -4737,7 +4762,14 @@ var networkSettingsSchema = z13.object({
   targetPartnerSearchNetwork: z13.boolean().optional()
 });
 var dateSchema = z13.string().regex(/^\d{4}-\d{2}-\d{2}$/, "expected a YYYY-MM-DD date");
-var campaignCreateSchema2 = z13.object({
+var geoTargetTypeSettingSchema = z13.strictObject({
+  positiveGeoTargetType: z13.enum(POSITIVE_GEO_TARGET_TYPES).optional(),
+  negativeGeoTargetType: z13.enum(NEGATIVE_GEO_TARGET_TYPES).optional()
+}).refine(
+  (p) => p.positiveGeoTargetType !== void 0 || p.negativeGeoTargetType !== void 0,
+  "geoTargetTypeSetting needs positiveGeoTargetType and/or negativeGeoTargetType"
+);
+var campaignCreateSchema2 = z13.strictObject({
   name: z13.string().min(1).max(GOOGLE_ADS_LIMITS.campaign.nameMax),
   channelType: z13.enum(ADVERTISING_CHANNEL_TYPES),
   channelSubType: z13.enum(ADVERTISING_CHANNEL_SUB_TYPES).optional(),
@@ -4746,10 +4778,19 @@ var campaignCreateSchema2 = z13.object({
   bidding: biddingConfigSchema.optional(),
   biddingStrategy: refSchema.optional(),
   networkSettings: networkSettingsSchema.optional(),
+  /**
+   * "Location options". Omitted stages Google's own default — reach people *in or interested in*
+   * the targeted locations — so pass `PRESENCE` explicitly when only people physically there count.
+   */
+  geoTargetTypeSetting: geoTargetTypeSettingSchema.optional(),
   startDate: dateSchema.optional(),
   endDate: dateSchema.optional(),
   /** Campaign-level override of the account's final URL suffix — REPLACES it, never merges. */
   finalUrlSuffix: finalUrlSuffixSchema.optional(),
+  /** Campaign-level override of the account's tracking template — REPLACES it, never merges. */
+  trackingUrlTemplate: trackingUrlTemplateSchema.optional(),
+  /** The `{_name}` parameters this campaign's tracking template and final URLs can reference. */
+  urlCustomParameters: urlCustomParametersSchema.optional(),
   /** Advisory Google Ads UI objective — drives warnings, not sent to the API. */
   objective: z13.enum(CAMPAIGN_OBJECTIVES).optional(),
   /**
@@ -4780,15 +4821,21 @@ var campaignCreateSchema2 = z13.object({
     ctx.addIssue({ code: "custom", path: ["endDate"], message: "endDate must be after startDate" });
   }
 });
-var campaignUpdateSchema2 = z13.object({
+var campaignUpdateSchema2 = z13.strictObject({
   name: z13.string().min(1).max(GOOGLE_ADS_LIMITS.campaign.nameMax).optional(),
   budget: refSchema.optional(),
   bidding: biddingConfigSchema.optional(),
   networkSettings: networkSettingsSchema.optional(),
+  /** Switches an existing campaign between "Presence or interest" and "Presence". */
+  geoTargetTypeSetting: geoTargetTypeSettingSchema.optional(),
   startDate: dateSchema.optional(),
   endDate: dateSchema.optional(),
   /** Campaign-level override of the account's final URL suffix. `""` clears it back to the account value. */
   finalUrlSuffix: finalUrlSuffixSchema.optional(),
+  /** Campaign-level tracking template. `""` clears it back to the account value. */
+  trackingUrlTemplate: trackingUrlTemplateSchema.optional(),
+  /** Replaces the campaign's custom parameters wholesale; `[]` removes them all. */
+  urlCustomParameters: urlCustomParametersSchema.optional(),
   /** Corrects the campaign's EU political advertising declaration (true = contains, false = does not). */
   euPoliticalAds: z13.boolean().optional(),
   status: z13.enum(["ENABLED", "PAUSED", "REMOVED"]).optional()
@@ -6947,8 +6994,8 @@ async function stageGoogleOp(raw, hints) {
     handleGoogleError(err);
   }
 }
-async function stageCreate(kind, customerId, payload) {
-  await stageGoogleOp({ kind, customerId, payload });
+async function stageCreate(kind, customerId, payload, hints) {
+  await stageGoogleOp({ kind, customerId, payload }, hints);
 }
 async function stageGoogleOps(rawOps, hints) {
   if (rawOps.length === 1 && rawOps[0]) {
@@ -8451,6 +8498,81 @@ var finalUrlSuffixArg = {
     description: 'Final URL suffix for this campaign \u2014 bare query params, no leading "?" (e.g. "utm_source=google&utm_agency=baker"). REPLACES the account-level suffix for this campaign; pass "" to clear it back to the account value. Account-wide tagging belongs at the account level: --level account tells you where.'
   }
 };
+var urlOptionsArgs = {
+  "tracking-template": {
+    type: "string",
+    description: 'Campaign tracking template \u2014 the click-measurement URL every ad routes through. Must carry the landing page through {lpurl}, e.g. "https://tracker.example/?url={lpurl}". REPLACES the account-level template for this campaign; pass "" to clear it back to the account value.'
+  },
+  "custom-param": {
+    type: "string",
+    description: "Custom parameter as key=value, referenced in a template or final URL as {_key} (e.g. --custom-param season=summer). Repeat for several; Google allows 8. REPLACES the campaign's whole set."
+  },
+  "clear-custom-params": {
+    type: "boolean",
+    description: "Remove every custom parameter from this campaign (Google replaces the set wholesale)."
+  }
+};
+function urlCustomParametersFromFlags(args) {
+  const raw = args["custom-param"];
+  const entries = (Array.isArray(raw) ? raw : typeof raw === "string" ? [raw] : []).filter(
+    (v) => typeof v === "string" && v.length > 0
+  );
+  if (entries.length === 0) {
+    return args["clear-custom-params"] === true ? [] : void 0;
+  }
+  if (args["clear-custom-params"] === true) {
+    failWriteValidation("--clear-custom-params removes every parameter \u2014 pass it OR --custom-param, not both");
+  }
+  return entries.map((entry) => {
+    const split = entry.indexOf("=");
+    if (split <= 0) {
+      failWriteValidation(`--custom-param "${entry}" must be key=value (e.g. --custom-param season=summer)`);
+    }
+    return { key: entry.slice(0, split), value: entry.slice(split + 1) };
+  });
+}
+var geoTargetTypeArgs = {
+  "geo-target-type": {
+    type: "string",
+    description: 'Location option \u2014 PRESENCE (only people in your targeted locations) or PRESENCE_OR_INTEREST (also people interested in them). Google applies PRESENCE_OR_INTEREST when this is left out, so pass PRESENCE explicitly for local-service, delivery-radius or in-store campaigns. Sets the same "Location options" as the Google Ads UI.'
+  },
+  "negative-geo-target-type": {
+    type: "string",
+    description: "How EXCLUDED locations are matched \u2014 PRESENCE (default: excludes people in the location) or PRESENCE_OR_INTEREST (also excludes people interested in it)."
+  }
+};
+function enumFlag(value, flag, allowed) {
+  if (typeof value !== "string" || value.length === 0) {
+    return void 0;
+  }
+  const upper2 = value.toUpperCase();
+  if (!allowed.includes(upper2)) {
+    failWriteValidation(`${flag} must be one of ${allowed.join(" | ")}`);
+  }
+  return upper2;
+}
+function geoTargetTypeFromFlags(args) {
+  const positiveGeoTargetType = enumFlag(args["geo-target-type"], "--geo-target-type", POSITIVE_GEO_TARGET_TYPES);
+  const negativeGeoTargetType = enumFlag(
+    args["negative-geo-target-type"],
+    "--negative-geo-target-type",
+    NEGATIVE_GEO_TARGET_TYPES
+  );
+  if (positiveGeoTargetType === void 0 && negativeGeoTargetType === void 0) {
+    return void 0;
+  }
+  return Object.fromEntries(
+    Object.entries({ positiveGeoTargetType, negativeGeoTargetType }).filter(([, v]) => v !== void 0)
+  );
+}
+function geoTargetTypeHints(payload) {
+  if (payload.geoTargetTypeSetting !== void 0) {
+    return [];
+  }
+  return [
+    `No --geo-target-type set, so this campaign will use Google's default location option "Presence or interest" \u2014 it reaches people interested in your locations, not only people in them. Re-stage with --geo-target-type PRESENCE if the offer is local (in-store, delivery radius, service area), and tell the user which of the two this campaign uses.`
+  ];
+}
 function accountLevelNotStageable(customerId, suffix) {
   writeJsonEnvelope({
     ok: false,
@@ -8494,6 +8616,8 @@ var campaignsCommand = defineCommand30({
         "target-roas": { type: "string", description: "Target ROAS (e.g. 4.0) for TARGET_ROAS" },
         ...maxCpcArg,
         ...finalUrlSuffixArg,
+        ...urlOptionsArgs,
+        ...geoTargetTypeArgs,
         objective: { type: "string", description: "Advisory UI objective (SALES, LEADS, \u2026)" },
         "start-date": { type: "string", description: "YYYY-MM-DD" },
         "end-date": { type: "string", description: "YYYY-MM-DD" },
@@ -8511,14 +8635,17 @@ var campaignsCommand = defineCommand30({
           channelSubType: args["sub-type"],
           budget: args["budget-ref"],
           bidding: biddingFromFlags(args),
+          geoTargetTypeSetting: geoTargetTypeFromFlags(args),
           finalUrlSuffix: args["final-url-suffix"],
+          trackingUrlTemplate: args["tracking-template"],
+          urlCustomParameters: urlCustomParametersFromFlags(args),
           objective: args.objective,
           startDate: args["start-date"],
           endDate: args["end-date"],
           euPoliticalAds: args["eu-political-ads"],
           status: args.status
         });
-        await stageCreate("google.campaign.create", customerId, payload);
+        await stageCreate("google.campaign.create", customerId, payload, geoTargetTypeHints(payload));
       }
     }),
     update: defineCommand30({
@@ -8533,6 +8660,8 @@ var campaignsCommand = defineCommand30({
         "target-roas": { type: "string" },
         ...maxCpcArg,
         ...finalUrlSuffixArg,
+        ...urlOptionsArgs,
+        ...geoTargetTypeArgs,
         "eu-political-ads": {
           type: "boolean",
           description: "Corrects the campaign's EU political advertising declaration: --eu-political-ads if it contains EU political ads, --eu-political-ads=false if it does not. Existing campaigns without a declaration block location-targeting changes until one is set."
@@ -8557,7 +8686,10 @@ var campaignsCommand = defineCommand30({
           name: args.name,
           budget: args["budget-ref"],
           bidding: biddingFromFlags(args),
+          geoTargetTypeSetting: geoTargetTypeFromFlags(args),
           finalUrlSuffix: args["final-url-suffix"],
+          trackingUrlTemplate: args["tracking-template"],
+          urlCustomParameters: urlCustomParametersFromFlags(args),
           euPoliticalAds: args["eu-political-ads"],
           status: args.status
         });