@koda-sl/baker-cli 0.137.0 → 0.138.0

package/README.md

@@ -168,9 +168,12 @@ Run arbitrary GAQL queries. The most powerful command.
 # Raw GAQL
 baker ads google query "SELECT campaign.name, metrics.clicks, metrics.cost_micros FROM campaign WHERE segments.date DURING LAST_7_DAYS AND campaign.status = 'ENABLED' ORDER BY metrics.cost_micros DESC" --customer-id 1234567890
 
-# Use a preset (saves tokens)
+# Use a preset (saves tokens) — returns only actually-serving entities by default
 baker ads google query --preset campaign-performance --customer-id 1234567890
 
+# Include paused entities too (default is serving-only)
+baker ads google query --preset ad-copy-performance --customer-id 1234567890 --include-paused
+
 # Export to CSV
 baker ads google query --preset search-terms --customer-id 1234567890 --out results.csv
 
@@ -226,6 +229,7 @@ baker ads google query --list-presets
 | `--customer-id` | Google Ads customer ID (10 digits, no dashes). Falls back to `BAKER_GOOGLE_ADS_CUSTOMER_ID` env var. |
 | `--preset`      | Named query template (see presets below)                     |
 | `--date-range`  | Override preset date range (LAST_7_DAYS, LAST_30_DAYS, etc.) |
+| `--include-paused` | Include paused entities in preset results. Off by default: presets return only actually-serving entities (enabled campaign **and** ad group **and** ad). Google Ads has no single serving flag, so the whole chain must be `ENABLED` for an entity to serve. |
 | `--limit`       | Max rows per page (default 200)                              |
 | `--cursor`      | Pagination cursor from previous response                     |
 | `--all`         | Auto-paginate all results                                    |
@@ -251,6 +255,8 @@ baker ads google query --list-presets
 | `shopping-products`    | Product-level shopping metrics           | LAST_30_DAYS       |
 | `account-summary`      | Account-level totals                     | LAST_30_DAYS       |
 
+Every preset except the negatives lists and `account-summary` filters to **actually-serving entities** by default — the full status chain (`campaign.status = 'ENABLED' AND ad_group.status = 'ENABLED' AND ad_group_ad.status = 'ENABLED'`, as applicable) — and selects the status columns so you can see them. Pass `--include-paused` to widen to `!= 'REMOVED'` (keeps paused, still drops removed). Raw GAQL (no `--preset`) has no such default: a query over a serving-hierarchy resource without a status filter emits a `SERVING_SCOPE` warning reminding you to add the chain, because Google Ads has no single serving flag.
+
 **Pre-flight checks and auto-fixes:**
 
 The CLI rejects or automatically corrects common GAQL mistakes before hitting the API:

package/dist/cli.js

@@ -3814,6 +3814,7 @@ var FIELD_DESCRIPTIONS = {
   // Keywords
   "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",
   "ad_group_criterion.quality_info.quality_score": "Quality score 1-10 (higher is better)",
   // Search terms
   "search_term_view.search_term": "Actual user search query that triggered the ad",
@@ -3850,6 +3851,7 @@ var FIELD_DESCRIPTIONS = {
   "asset.youtube_video_asset.youtube_video_id": "YouTube video ID",
   "asset.youtube_video_asset.youtube_video_title": "YouTube video title",
   "asset_group.name": "Asset group display name",
+  "asset_group.status": "ENABLED, PAUSED, or REMOVED",
   "asset_group_asset.field_type": "Where the asset is used (HEADLINE, DESCRIPTION, LOGO, etc.)",
   "asset_group_asset.performance_label": "Performance rating: BEST, GOOD, LOW, LEARNING",
   // Change events
@@ -6267,10 +6269,10 @@ function applyAutoFixes(query, limit) {
     warnings.push({ code: "FIELD_RENAMED", message: "asset.<type>_asset.final_urls \u2192 asset.final_urls" });
   }
   if (/FROM\s+campaign_budget\b/i.test(corrected)) {
-    const whereClause = corrected.split(/\bWHERE\b/i)[1] ?? "";
+    const whereClause2 = corrected.split(/\bWHERE\b/i)[1] ?? "";
     const selectClause = corrected.split(/\bFROM\b/i)[0] ?? "";
     const selectFields = new Set(selectClause.match(/campaign\.[\w.]+/g) ?? []);
-    const missing = [...new Set(whereClause.match(/campaign\.[\w.]+/g) ?? [])].filter(
+    const missing = [...new Set(whereClause2.match(/campaign\.[\w.]+/g) ?? [])].filter(
       (field) => !selectFields.has(field)
     );
     if (missing.length > 0) {
@@ -6405,23 +6407,26 @@ var PRESETS = [
   {
     name: "campaign-performance",
     description: "Campaign-level metrics overview",
-    gaqlTemplate: `SELECT campaign.id, campaign.name, campaign.status, campaign.advertising_channel_type, metrics.impressions, metrics.clicks, metrics.cost_micros, metrics.conversions, metrics.conversions_value, metrics.ctr, metrics.average_cpc FROM campaign WHERE segments.date DURING {dateRange} AND campaign.status != 'REMOVED' ORDER BY metrics.cost_micros DESC LIMIT {limit}`,
+    gaqlTemplate: `SELECT campaign.id, campaign.name, campaign.status, campaign.advertising_channel_type, metrics.impressions, metrics.clicks, metrics.cost_micros, metrics.conversions, metrics.conversions_value, metrics.ctr, metrics.average_cpc FROM campaign WHERE segments.date DURING {dateRange}{statusScope} ORDER BY metrics.cost_micros DESC LIMIT {limit}`,
     defaultDateRange: "LAST_30_DAYS",
-    defaultLimit: 200
+    defaultLimit: 200,
+    statusFields: ["campaign.status"]
   },
   {
     name: "keyword-analysis",
     description: "Keyword performance with match type and quality",
-    gaqlTemplate: `SELECT campaign.id, campaign.name, ad_group.name, ad_group_criterion.keyword.text, ad_group_criterion.keyword.match_type, metrics.impressions, metrics.clicks, metrics.cost_micros, metrics.conversions, metrics.ctr FROM keyword_view WHERE segments.date DURING {dateRange} AND campaign.status = 'ENABLED' ORDER BY metrics.impressions DESC LIMIT {limit}`,
+    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}`,
     defaultDateRange: "LAST_30_DAYS",
-    defaultLimit: 200
+    defaultLimit: 200,
+    statusFields: ["campaign.status", "ad_group.status", "ad_group_criterion.status"]
   },
   {
     name: "positive-keywords",
     description: "Positive (targeting) keywords only \u2014 excludes negatives",
-    gaqlTemplate: `SELECT campaign.id, campaign.name, ad_group.name, 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 AND campaign.status != 'REMOVED' AND ad_group_criterion.status != 'REMOVED' ORDER BY campaign.name LIMIT {limit}`,
+    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}`,
     defaultDateRange: "ALL_TIME",
-    defaultLimit: 500
+    defaultLimit: 500,
+    statusFields: ["campaign.status", "ad_group.status", "ad_group_criterion.status"]
   },
   {
     name: "negative-keywords",
@@ -6447,30 +6452,34 @@ var PRESETS = [
   {
     name: "search-terms",
     description: "Actual user search queries triggering ads",
-    gaqlTemplate: `SELECT campaign.id, campaign.name, ad_group.name, search_term_view.search_term, metrics.impressions, metrics.clicks, metrics.cost_micros, metrics.conversions FROM search_term_view WHERE segments.date DURING {dateRange} AND campaign.status = 'ENABLED' ORDER BY metrics.impressions DESC LIMIT {limit}`,
+    gaqlTemplate: `SELECT campaign.id, campaign.name, campaign.status, ad_group.name, ad_group.status, search_term_view.search_term, metrics.impressions, metrics.clicks, metrics.cost_micros, metrics.conversions FROM search_term_view WHERE segments.date DURING {dateRange}{statusScope} ORDER BY metrics.impressions DESC LIMIT {limit}`,
     defaultDateRange: "LAST_7_DAYS",
-    defaultLimit: 200
+    defaultLimit: 200,
+    statusFields: ["campaign.status", "ad_group.status"]
   },
   {
     name: "ad-copy-performance",
     description: "Ad headline and description effectiveness",
-    gaqlTemplate: `SELECT campaign.id, campaign.name, ad_group_ad.ad.responsive_search_ad.headlines, ad_group_ad.ad.responsive_search_ad.descriptions, ad_group_ad.ad.final_urls, metrics.impressions, metrics.clicks, metrics.conversions, metrics.ctr FROM ad_group_ad WHERE segments.date DURING {dateRange} AND ad_group_ad.status = 'ENABLED' ORDER BY metrics.impressions DESC LIMIT {limit}`,
+    gaqlTemplate: `SELECT campaign.id, campaign.name, campaign.status, ad_group.status, ad_group_ad.status, ad_group_ad.ad.responsive_search_ad.headlines, ad_group_ad.ad.responsive_search_ad.descriptions, ad_group_ad.ad.final_urls, metrics.impressions, metrics.clicks, metrics.conversions, metrics.ctr FROM ad_group_ad WHERE segments.date DURING {dateRange}{statusScope} ORDER BY metrics.impressions DESC LIMIT {limit}`,
     defaultDateRange: "LAST_30_DAYS",
-    defaultLimit: 200
+    defaultLimit: 200,
+    statusFields: ["campaign.status", "ad_group.status", "ad_group_ad.status"]
   },
   {
     name: "asset-performance",
     description: "Performance Max asset performance labels",
-    gaqlTemplate: `SELECT campaign.id, campaign.name, asset_group.name, asset_group_asset.field_type, asset_group_asset.performance_label, asset.type, asset.text_asset.text, asset.image_asset.full_size.url FROM asset_group_asset WHERE campaign.advertising_channel_type = 'PERFORMANCE_MAX' AND segments.date DURING {dateRange} LIMIT {limit}`,
+    gaqlTemplate: `SELECT campaign.id, campaign.name, campaign.status, asset_group.name, asset_group.status, asset_group_asset.field_type, asset_group_asset.performance_label, asset.type, asset.text_asset.text, asset.image_asset.full_size.url FROM asset_group_asset WHERE campaign.advertising_channel_type = 'PERFORMANCE_MAX' AND segments.date DURING {dateRange}{statusScope} LIMIT {limit}`,
     defaultDateRange: "LAST_30_DAYS",
-    defaultLimit: 200
+    defaultLimit: 200,
+    statusFields: ["campaign.status", "asset_group.status"]
   },
   {
     name: "shopping-products",
     description: "Product-level shopping performance metrics",
-    gaqlTemplate: `SELECT campaign.id, campaign.name, segments.product_title, segments.product_item_id, segments.product_brand, segments.product_type_l1, metrics.clicks, metrics.impressions, metrics.cost_micros, metrics.conversions FROM shopping_performance_view WHERE segments.date DURING {dateRange} ORDER BY metrics.cost_micros DESC LIMIT {limit}`,
+    gaqlTemplate: `SELECT campaign.id, campaign.name, campaign.status, segments.product_title, segments.product_item_id, segments.product_brand, segments.product_type_l1, metrics.clicks, metrics.impressions, metrics.cost_micros, metrics.conversions FROM shopping_performance_view WHERE segments.date DURING {dateRange}{statusScope} ORDER BY metrics.cost_micros DESC LIMIT {limit}`,
     defaultDateRange: "LAST_30_DAYS",
-    defaultLimit: 200
+    defaultLimit: 200,
+    statusFields: ["campaign.status"]
   },
   {
     name: "account-summary",
@@ -6483,6 +6492,11 @@ var PRESETS = [
 function getPreset(name) {
   return PRESETS.find((p) => p.name === name);
 }
+function buildStatusScope(statusFields, includePaused) {
+  if (!statusFields || statusFields.length === 0) return "";
+  const predicate = includePaused ? "!= 'REMOVED'" : "= 'ENABLED'";
+  return statusFields.map((field) => ` AND ${field} ${predicate}`).join("");
+}
 function expandPreset(preset, params) {
   const dateRange = params.dateRange ?? preset.defaultDateRange;
   const limit = params.limit ?? preset.defaultLimit;
@@ -6492,7 +6506,8 @@ function expandPreset(preset, params) {
       dateRangeError: `Invalid date range: "${dateRange}". Use a GAQL date literal (e.g. LAST_30_DAYS, TODAY) or BETWEEN 'YYYY-MM-DD' AND 'YYYY-MM-DD'.`
     };
   }
-  const query = preset.gaqlTemplate.replace(/\{dateRange\}/g, dateRange).replace(/\{limit\}/g, String(limit));
+  const statusScope = buildStatusScope(preset.statusFields, params.includePaused ?? false);
+  const query = preset.gaqlTemplate.replace(/\{dateRange\}/g, dateRange).replace(/\{limit\}/g, String(limit)).replace(/\{statusScope\}/g, statusScope);
   return { query };
 }
 
@@ -6509,7 +6524,7 @@ registerSchema({
     },
     preset: {
       type: "string",
-      description: "Named query preset (campaign-performance, keyword-analysis, search-terms, ad-copy-performance, asset-performance, shopping-products, account-summary)",
+      description: "Named query preset. Reads (campaign-performance, keyword-analysis, positive-keywords, negative-keywords, negative-keyword-lists, negative-list-attachments, search-terms, ad-copy-performance, asset-performance, shopping-products, account-summary). Presets return only actually-serving entities (enabled campaign AND ad group AND ad) by default \u2014 pass --include-paused to include paused ones.",
       required: false
     },
     "date-range": {
@@ -6517,6 +6532,11 @@ registerSchema({
       description: "Date range for presets (LAST_7_DAYS, LAST_30_DAYS, LAST_90_DAYS, or BETWEEN 'X' AND 'Y')",
       required: false
     },
+    "include-paused": {
+      type: "boolean",
+      description: "Include paused entities in preset results. Off by default: presets return only actually-serving entities. Google Ads has no single serving flag \u2014 an entity serves only when its whole chain (campaign, ad group, ad) is ENABLED, so recommendations should target serving entities unless the user asks about paused ones.",
+      required: false
+    },
     limit: { type: "number", description: "Max rows (default 200)", required: false, default: 200 },
     "list-presets": { type: "boolean", description: "List all available query presets", required: false },
     cursor: { type: "string", description: "Pagination cursor from previous response", required: false },
@@ -6625,7 +6645,11 @@ function resolveGaql(args, limit) {
       });
       return null;
     }
-    const expanded = expandPreset(preset, { dateRange: args["date-range"], limit });
+    const expanded = expandPreset(preset, {
+      dateRange: args["date-range"],
+      limit,
+      includePaused: Boolean(args["include-paused"])
+    });
     if (expanded.dateRangeError) {
       writeAdsJson({
         ok: false,
@@ -6648,6 +6672,51 @@ function resolveGaql(args, limit) {
   }
   return gaql;
 }
+var SERVING_HIERARCHY_RESOURCES = [
+  "campaign",
+  "ad_group",
+  "ad_group_ad",
+  "ad_group_criterion",
+  "keyword_view",
+  "search_term_view",
+  "shopping_performance_view",
+  "asset_group_asset"
+];
+function whereClause(upperQuery) {
+  const whereIdx = upperQuery.indexOf(" WHERE ");
+  if (whereIdx === -1) return "";
+  let rest = upperQuery.slice(whereIdx + 7);
+  for (const trailing of [" ORDER BY ", " GROUP BY ", " LIMIT ", " PARAMETERS "]) {
+    const idx = rest.indexOf(trailing);
+    if (idx !== -1) rest = rest.slice(0, idx);
+  }
+  return rest;
+}
+function servingScopeWarnings(args, finalQuery) {
+  if (args.preset) {
+    if (!args["include-paused"]) return [];
+    return [
+      {
+        code: "SERVING_SCOPE",
+        message: "Paused entities are included (--include-paused). Only recommend changes for actually-serving entities (enabled campaign, ad group, and ad) unless the user asked about paused ones."
+      }
+    ];
+  }
+  const upper2 = finalQuery.toUpperCase();
+  const fromMatch = upper2.match(/\bFROM\s+([A-Z_]+)/);
+  const resource = fromMatch?.[1]?.toLowerCase();
+  const hierarchical = resource ? SERVING_HIERARCHY_RESOURCES.includes(resource) : false;
+  const filtersStatus = whereClause(upper2).includes(".STATUS");
+  if (hierarchical && !filtersStatus) {
+    return [
+      {
+        code: "SERVING_SCOPE",
+        message: "This query has no status filter, so it may return paused entities that aren't actually serving. Google Ads has no single serving flag \u2014 an entity serves only when its whole chain is ENABLED. Add campaign.status = 'ENABLED' AND ad_group.status = 'ENABLED' AND ad_group_ad.status = 'ENABLED' (as applicable), or use a --preset, unless you intend to include paused entities."
+      }
+    ];
+  }
+  return [];
+}
 async function fetchAllPages(body, args) {
   let allRows = [];
   let pageToken = args.cursor;
@@ -6706,7 +6775,7 @@ async function validateArgs(args) {
     customerId,
     limit,
     finalQuery,
-    warnings: preflight.warnings,
+    warnings: [...preflight.warnings, ...servingScopeWarnings(args, finalQuery)],
     useCache: !args["no-cache"],
     cacheKey: buildQueryCacheKey(customerId, finalQuery)
   };
@@ -6746,6 +6815,11 @@ Examples:
     "customer-id": { type: "string", description: "Google Ads customer ID (10 digits, no dashes)", required: false },
     preset: { type: "string", description: "Named query preset", required: false },
     "date-range": { type: "string", description: "Date range override for presets", required: false },
+    "include-paused": {
+      type: "boolean",
+      description: "Include paused entities in preset results (default: serving entities only)",
+      required: false
+    },
     limit: { type: "string", description: "Max rows (default 200)", required: false },
     "list-presets": { type: "boolean", description: "List available presets", required: false },
     cursor: { type: "string", description: "Pagination cursor", required: false },
@@ -6763,7 +6837,8 @@ Examples:
           name: p.name,
           description: p.description,
           defaultDateRange: p.defaultDateRange,
-          gaql: p.gaqlTemplate
+          servingOnly: (p.statusFields?.length ?? 0) > 0,
+          gaql: expandPreset(p, {}).query
         }))
       });
       return;