@koda-sl/baker-cli 0.242.0 → 0.244.0

package/README.md

@@ -1186,6 +1186,8 @@ baker analytics geo --grain postal_code --country ES
 baker analytics bots                      # which crawlers fetch the site
 baker analytics presets                   # what each report answers
 baker analytics ads --platform google     # what Google's traffic carries, in Google's vocabulary
+baker analytics tracking                  # do the ad URLs carry the campaign, ad group and ad at all
+baker analytics tracking --platform meta  # the same for one platform, read from their own ad account
 baker analytics map --platform google --set kw=keyword    # name a parameter, seen or not yet
 baker analytics map --platform google --remove kw         # take that answer back
 baker analytics delivery --page 2         # the next page of a long list
@@ -1208,6 +1210,10 @@ Shared flags: `--days <n>` (default 30) or `--start-date` / `--end-date` (`YYYY-
 
 **And each `--set` is checked against the client's own ad account.** Baker reads their Google Ads tracking templates and final URL suffixes (or their Meta ads' URL parameters) and returns `evidence` per parameter: `confirmed` (their template really does fill that name with what you claimed), `contradicted` (it fills it with something else — `suggestedRole` says what), `unseen` (no template Baker can read mentions it, which is normal), `not_read` (no connection, or a platform with no template to read, with the reason). **`contradicted` is the one to stop for**: mapping a name your way when the account fills it another way produces a report that is wrong and looks entirely plausible.
 
+**`tracking` answers "can this account be reported on at all", and it reads the ad account to do it.** `analytics ads` can only describe parameters that have already arrived, which leaves two blind spots that mislead in the expensive direction: a platform with no traffic in the window looks exactly like a platform whose ads carry nothing, and a dimension arriving under a name nobody has mapped looks exactly like one nothing carries. `baker analytics tracking` reads the mapping, the traffic **and** the client's own Google tracking templates / Meta URL parameters, so it can answer for a platform that has not had a click yet. Every dimension comes back in one of four states, and they are four different jobs: `covered` is done; `unmapped` means the URLs already carry it under a name Baker does not read, so run the `mapCommand` in the response — free, and it repairs the traffic already collected; `missing` means nothing carries it; `unknown` means no visit arrived *and* the account could not be read, which is not a finding and must never be reported as untagged.
+
+**`fix` says which level to put the missing pairs at, and who can write it.** Not a field name — the levels that platform accepts tagging at, widest first (the widest is the one to prefer: it covers campaigns nobody has created yet), which of them Baker can stage and which the user has to do by hand, and how each field treats a value already in it. That last part is the one people skip and it differs per platform: a Google **campaign** final URL suffix *replaces* the account one rather than merging, LinkedIn's `url-params` call *sets the ad set's whole parameter set* and Baker cannot read back what is in it, and a Meta creative is immutable so a live ad cannot be retagged through Baker at all. `suffix` is only ever the **missing** pairs, so the rule everywhere is the same: read what is there, work out what is missing, write the union. Where `fix` says Baker has no write surface — Microsoft, TikTok, Reddit, Pinterest, Snapchat — that is a request to hand the user with the exact string and the exact screen, never a reason to stop on the platforms it can write.
+
 **The one recommendation about the ad account itself.** `baker analytics ads --platform <p>` warns when that platform's traffic carries no campaign id, ad group id or ad id — the three tiers every "which ad worked" question is grouped by — and returns the exact URL suffix, in the platform's own macro language, that would start sending the missing ones. It is the only mapping gap that cannot be fixed afterwards: naming a parameter Baker already captures corrects the history, because roles are resolved when a report is read, but a parameter the ads never sent has no stored values for a meaning to apply to. The hint stays quiet for a platform with little traffic, and defers to the untagged-account finding rather than repeating it.
 
 An unrecognised `--timezone` is refused with a `VALIDATION_ERROR` rather than defaulting to UTC, and `--output` accepts only `json` or `md`. Pass `--timezone` whenever the client is not in UTC. Day boundaries are drawn in UTC by default, which moves two hours of every Spanish evening onto the following day — not a rounding error on a day-of-week comparison, but the wrong day.

package/dist/cli.js

@@ -2122,6 +2122,18 @@ var BIDDING_STRATEGY_TYPES = [
   "MANUAL_CPV",
   "PERCENT_CPC"
 ];
+var MERGED_TARGET_STRATEGY_CHANNELS = /* @__PURE__ */ new Set(["SEARCH"]);
+var MERGED_TARGET_CPA_MESSAGE = "Google doesn't accept Target CPA as a bidding strategy of its own on a Search campaign \u2014 the target sits inside Maximize conversions. Choose Maximize conversions and give it the same target CPA; it bids exactly the same.";
+var MERGED_TARGET_ROAS_MESSAGE = "Google doesn't accept Target ROAS as a bidding strategy of its own on a Search campaign \u2014 the target sits inside Maximize conversion value. Choose Maximize conversion value and give it the same target ROAS; it bids exactly the same.";
+function mergedTargetStrategyRefusal(channelType, biddingType) {
+  if (channelType === void 0 || !MERGED_TARGET_STRATEGY_CHANNELS.has(channelType)) {
+    return void 0;
+  }
+  if (biddingType === "TARGET_CPA") {
+    return MERGED_TARGET_CPA_MESSAGE;
+  }
+  return biddingType === "TARGET_ROAS" ? MERGED_TARGET_ROAS_MESSAGE : void 0;
+}
 var POSITIVE_GEO_TARGET_TYPES = ["PRESENCE_OR_INTEREST", "PRESENCE"];
 var NEGATIVE_GEO_TARGET_TYPES = ["PRESENCE_OR_INTEREST", "PRESENCE"];
 var BUDGET_DELIVERY_METHODS = ["STANDARD", "ACCELERATED"];
@@ -2846,6 +2858,10 @@ var campaignCreateSchema2 = z4.strictObject({
   if (p.channelType === "PERFORMANCE_MAX" && p.bidding && p.bidding.type === "MANUAL_CPC") {
     ctx.addIssue({ code: "custom", path: ["bidding"], message: "Performance Max does not support Manual CPC" });
   }
+  const mergedTarget = mergedTargetStrategyRefusal(p.channelType, p.bidding?.type);
+  if (mergedTarget) {
+    ctx.addIssue({ code: "custom", path: ["bidding"], message: mergedTarget });
+  }
   if (p.startDate && p.endDate && p.endDate <= p.startDate) {
     ctx.addIssue({ code: "custom", path: ["endDate"], message: "endDate must be after startDate" });
   }
@@ -13628,10 +13644,16 @@ var campaignsCommand = defineCommand30({
         "budget-ref": { type: "string", description: "Budget ref (g_temp_*, id, or resource name)" },
         "bidding-strategy": {
           type: "string",
-          description: "MANUAL_CPC | MAXIMIZE_CONVERSIONS | TARGET_CPA | TARGET_ROAS | \u2026"
+          description: "MANUAL_CPC | MAXIMIZE_CONVERSIONS | MAXIMIZE_CONVERSION_VALUE | TARGET_SPEND | \u2026"
+        },
+        "target-cpa": {
+          type: "string",
+          description: "Target CPA (major units). On a Search campaign pair it with --bidding-strategy MAXIMIZE_CONVERSIONS \u2014 Google keeps the target inside that strategy and rejects a standalone TARGET_CPA."
+        },
+        "target-roas": {
+          type: "string",
+          description: "Target ROAS (e.g. 4.0). On a Search campaign pair it with --bidding-strategy MAXIMIZE_CONVERSION_VALUE \u2014 Google keeps the target inside that strategy and rejects a standalone TARGET_ROAS."
         },
-        "target-cpa": { type: "string", description: "Target CPA (major units) for TARGET_CPA" },
-        "target-roas": { type: "string", description: "Target ROAS (e.g. 4.0) for TARGET_ROAS" },
         ...maxCpcArg,
         ...finalUrlSuffixArg,
         ...urlOptionsArgs,
@@ -13678,9 +13700,18 @@ var campaignsCommand = defineCommand30({
         ...fileArg,
         name: { type: "string" },
         "budget-ref": { type: "string" },
-        "bidding-strategy": { type: "string" },
-        "target-cpa": { type: "string" },
-        "target-roas": { type: "string" },
+        "bidding-strategy": {
+          type: "string",
+          description: "MANUAL_CPC | MAXIMIZE_CONVERSIONS | MAXIMIZE_CONVERSION_VALUE | TARGET_SPEND | \u2026"
+        },
+        "target-cpa": {
+          type: "string",
+          description: "Target CPA (major units). On a Search campaign pair it with --bidding-strategy MAXIMIZE_CONVERSIONS \u2014 Google keeps the target inside that strategy and rejects a standalone TARGET_CPA."
+        },
+        "target-roas": {
+          type: "string",
+          description: "Target ROAS (e.g. 4.0). On a Search campaign pair it with --bidding-strategy MAXIMIZE_CONVERSION_VALUE \u2014 Google keeps the target inside that strategy and rejects a standalone TARGET_ROAS."
+        },
         ...maxCpcArg,
         ...finalUrlSuffixArg,
         ...urlOptionsArgs,
@@ -14425,7 +14456,8 @@ function requireAudienceLevel(value) {
   return level;
 }
 var AUDIENCE_ATTACH_HINTS = [
-  '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.'
+  '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.',
+  "Staging checks the list is big enough to serve on this campaign's network (1,000 users on search, 100 on display) 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."
 ];
 var audiencesAttachCommand = defineCommand30({
   meta: {