@koda-sl/baker-cli 0.165.0 → 0.166.0

package/README.md

@@ -296,7 +296,7 @@ Read it before interpreting any null. It does not fire on the `--out` path (rows
 | Preset                 | Description                              | Default date range |
 |------------------------|------------------------------------------|--------------------|
 | `campaign-performance` | Campaign metrics overview                | LAST_30_DAYS       |
-| `keyword-analysis`     | Keyword performance with match type      | LAST_30_DAYS       |
+| `keyword-analysis`     | Keyword performance per ad group         | LAST_30_DAYS       |
 | `positive-keywords`    | Positive (targeting) keywords only       | ALL_TIME           |
 | `negative-keywords`    | Negative (blocking) keywords only        | ALL_TIME           |
 | `negative-keyword-lists`   | Shared negative lists + their terms  | ALL_TIME           |
@@ -582,6 +582,8 @@ Command groups: `budgets`, `campaigns`, `ad-groups`, `keywords` (add/update/remo
 
 **Batch keyword adds** — `keywords add`, `negative-keywords add`, and `keyword-lists add` take a whole batch in one command: comma-separate `--text` entries and/or pass `--file <list.txt>` (one keyword per line). A `:EXACT`/`:PHRASE`/`:BROAD` suffix per entry overrides the `--match-type` default. Batches stage all-or-nothing as one request (limit 500); each keyword still lands as its own draft op, so it stays individually removable/amendable.
 
+**Pausing or removing a keyword returns a per-ad-group hint** — `keywords update --status PAUSED|REMOVED` and `keywords remove` come back with hints telling you to base the decision on `keyword_view` rows carrying `ad_group.id` + `ad_group_criterion.criterion_id`, never on campaign totals. A keyword's criterion id is derived from its text + match type, so every copy of the same keyword across ad groups shares one id and any aggregate blends the copy holding the history with the copies that never served. The `keyword-analysis` and `positive-keywords` presets select both ids so one query identifies each copy. A bid or URL edit gets no hint — only a pause/removal can strand history.
+
 ---
 
 ### Caching

package/dist/cli.js

@@ -4436,6 +4436,7 @@ var FIELD_DESCRIPTIONS = {
   "ad_group_ad.ad.responsive_search_ad.headlines": "Ad headline variations (array)",
   "ad_group_ad.ad.responsive_search_ad.descriptions": "Ad description variations (array)",
   // Keywords
+  "ad_group_criterion.criterion_id": "Keyword criterion id \u2014 derived from text + match type, so every copy of the same keyword across ad groups shares it. Pair with ad_group.id to identify one copy (writes take customers/<cid>/adGroupCriteria/<adGroupId>~<criterionId>)",
   "ad_group_criterion.keyword.text": "The keyword text",
   "ad_group_criterion.keyword.match_type": "EXACT, PHRASE, or BROAD",
   "ad_group_criterion.status": "ENABLED, PAUSED, or REMOVED",
@@ -7083,8 +7084,8 @@ async function stageGoogleOps(rawOps, hints) {
 async function stageUpdate(kind, customerId, target, payload, hints) {
   await stageGoogleOp({ kind, customerId, target, payload }, hints);
 }
-async function stageTarget(kind, customerId, target) {
-  await stageGoogleOp({ kind, customerId, target });
+async function stageTarget(kind, customerId, target, hints) {
+  await stageGoogleOp({ kind, customerId, target }, hints);
 }
 async function draftAction(path28, body) {
   try {
@@ -7894,7 +7895,7 @@ var PRESETS = [
   {
     name: "keyword-analysis",
     description: "Keyword performance with match type and quality",
-    gaqlTemplate: `SELECT campaign.id, campaign.name, campaign.status, ad_group.name, ad_group.status, ad_group_criterion.keyword.text, ad_group_criterion.keyword.match_type, ad_group_criterion.status, metrics.impressions, metrics.clicks, metrics.cost_micros, metrics.conversions, metrics.ctr FROM keyword_view WHERE segments.date DURING {dateRange}{statusScope} ORDER BY metrics.impressions DESC LIMIT {limit}`,
+    gaqlTemplate: `SELECT campaign.id, campaign.name, campaign.status, ad_group.id, ad_group.name, ad_group.status, ad_group_criterion.criterion_id, ad_group_criterion.keyword.text, ad_group_criterion.keyword.match_type, ad_group_criterion.status, metrics.impressions, metrics.clicks, metrics.cost_micros, metrics.conversions, metrics.ctr FROM keyword_view WHERE segments.date DURING {dateRange}{statusScope} ORDER BY metrics.impressions DESC LIMIT {limit}`,
     defaultDateRange: "LAST_30_DAYS",
     defaultLimit: 200,
     statusFields: ["campaign.status", "ad_group.status", "ad_group_criterion.status"]
@@ -7902,7 +7903,7 @@ var PRESETS = [
   {
     name: "positive-keywords",
     description: "Positive (targeting) keywords only \u2014 excludes negatives",
-    gaqlTemplate: `SELECT campaign.id, campaign.name, campaign.status, ad_group.name, ad_group.status, ad_group_criterion.keyword.text, ad_group_criterion.keyword.match_type, ad_group_criterion.status, ad_group_criterion.negative FROM ad_group_criterion WHERE ad_group_criterion.type = 'KEYWORD' AND ad_group_criterion.negative = FALSE{statusScope} ORDER BY campaign.name LIMIT {limit}`,
+    gaqlTemplate: `SELECT campaign.id, campaign.name, campaign.status, ad_group.id, ad_group.name, ad_group.status, ad_group_criterion.criterion_id, ad_group_criterion.keyword.text, ad_group_criterion.keyword.match_type, ad_group_criterion.status, ad_group_criterion.negative FROM ad_group_criterion WHERE ad_group_criterion.type = 'KEYWORD' AND ad_group_criterion.negative = FALSE{statusScope} ORDER BY campaign.name LIMIT {limit}`,
     defaultDateRange: "ALL_TIME",
     defaultLimit: 500,
     statusFields: ["campaign.status", "ad_group.status", "ad_group_criterion.status"]
@@ -8743,7 +8744,7 @@ var campaignsCommand = defineCommand30({
     remove: statusCommand2("google.campaign.remove", "campaign")
   }
 });
-function statusCommand2(kind, entity) {
+function statusCommand2(kind, entity, hints) {
   return defineCommand30({
     meta: { name: kind.split(".")[2], description: `Stage a ${entity} ${kind.split(".")[2]}` },
     args: {
@@ -8752,7 +8753,7 @@ function statusCommand2(kind, entity) {
     },
     run: async ({ args }) => {
       const customerId = requireCustomerId(args);
-      await stageTarget(kind, customerId, requireTarget(args, entity));
+      await stageTarget(kind, customerId, requireTarget(args, entity), hints);
     }
   });
 }
@@ -8807,6 +8808,14 @@ var adGroupsCommand = defineCommand30({
     remove: statusCommand2("google.adGroup.remove", "ad group")
   }
 });
+var KEYWORD_KILL_HINTS = [
+  "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.",
+  "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."
+];
+function keywordKillHints(status) {
+  const kills = typeof status === "string" && ["PAUSED", "REMOVED"].includes(status.toUpperCase());
+  return kills ? KEYWORD_KILL_HINTS : [];
+}
 var keywordWriteSubcommands = {
   add: defineCommand30({
     meta: { name: "add", description: "Add keyword(s) to an ad group \u2014 one --text or a whole batch" },
@@ -8841,13 +8850,16 @@ var keywordWriteSubcommands = {
     args: { ...customerIdArg, "cpc-bid": { type: "string" }, status: { type: "string" } },
     run: async ({ args }) => {
       const customerId = requireCustomerId(args);
-      await stageUpdate("google.keyword.update", customerId, requireTarget(args, "keyword"), {
-        cpcBidMicros: microsFlag(args["cpc-bid"], "--cpc-bid"),
-        status: args.status
-      });
+      await stageUpdate(
+        "google.keyword.update",
+        customerId,
+        requireTarget(args, "keyword"),
+        { cpcBidMicros: microsFlag(args["cpc-bid"], "--cpc-bid"), status: args.status },
+        keywordKillHints(args.status)
+      );
     }
   }),
-  remove: statusCommand2("google.keyword.remove", "keyword")
+  remove: statusCommand2("google.keyword.remove", "keyword", KEYWORD_KILL_HINTS)
 };
 var NEGATIVE_COVERAGE_HINTS = [
   "Before publishing, confirm each term isn't already blocked: run `baker ads google query --preset negative-keyword-lists` (shared-list terms) and `--preset negative-keywords` (campaign/ad-group negatives).",