@koda-sl/baker-cli 0.449.0 → 0.451.0-dev.b2a4eba2b

package/dist/query-3YAOEQVH.js

@@ -0,0 +1,1341 @@
+import {
+  getFieldDescriptions
+} from "./chunk-CYEO5ZIO.js";
+import {
+  LIST_FIELDS,
+  duringLiteralExplanation,
+  equivalentBetween,
+  isDuringLiteral,
+  listFieldGuidance,
+  parseApiError
+} from "./chunk-4L3IZCFL.js";
+import "./chunk-XCM6XWOB.js";
+import {
+  buildQueryCacheKey,
+  cacheGet,
+  cacheSet,
+  getManagerIdForCustomer,
+  getQueryTtl,
+  resolveCustomerId,
+  toCsvRow,
+  writeAdsJson
+} from "./chunk-XNMSJP2X.js";
+import {
+  GOOGLE_ADS_QUERY_MAX_PAGE_SIZE
+} from "./chunk-NE4F3FHN.js";
+import {
+  ApiError,
+  apiPost
+} from "./chunk-PCKVSSVT.js";
+import "./chunk-MCM3HMNZ.js";
+import "./chunk-UW36KPPH.js";
+import {
+  registerSchema
+} from "./chunk-NU7JSWVA.js";
+import "./chunk-YQSBHWOI.js";
+
+// src/commands/ads/google/query.ts
+import { appendFileSync, existsSync, readFileSync, writeFileSync } from "fs";
+import { resolve } from "path";
+import { defineCommand } from "citty";
+
+// src/commands/ads/google/presets.ts
+var BETWEEN_RE = /^BETWEEN\s+'[0-9]{4}-[0-9]{2}-[0-9]{2}'\s+AND\s+'[0-9]{4}-[0-9]{2}-[0-9]{2}'$/i;
+function isValidDateRange(value) {
+  const trimmed = value.trim();
+  return isDuringLiteral(trimmed) || BETWEEN_RE.test(trimmed);
+}
+function dateRangeError(dateRange, now) {
+  if (/^[A-Za-z0-9_]+$/.test(dateRange.trim())) {
+    return `Invalid date range: "${dateRange}". ${duringLiteralExplanation(dateRange, equivalentBetween(dateRange, now))} Pass it as --date-range "BETWEEN 'YYYY-MM-DD' AND 'YYYY-MM-DD'".`;
+  }
+  return `Invalid date range: "${dateRange}". Use a GAQL date literal (e.g. LAST_30_DAYS, TODAY) or BETWEEN 'YYYY-MM-DD' AND 'YYYY-MM-DD'.`;
+}
+var SERVING_CHAINS = {
+  keyword_view: ["campaign.status", "ad_group.status", "ad_group_criterion.status"],
+  ad_group_criterion: ["campaign.status", "ad_group.status", "ad_group_criterion.status"],
+  ad_group_ad: ["campaign.status", "ad_group.status", "ad_group_ad.status"],
+  search_term_view: ["campaign.status", "ad_group.status"],
+  ad_group: ["campaign.status", "ad_group.status"],
+  asset_group: ["campaign.status", "asset_group.status"],
+  // An asset link carries its own status, and it is not the campaign's, the ad group's or the asset
+  // group's. Google returns a REMOVED link like any other row, so a read scoped only to its owners
+  // lists extensions that are no longer attached to anything — which is what 74 detaches were planned
+  // from on a live account, every one of them refused at publish as `RESOURCE_NOT_FOUND`.
+  // `customer_asset` is deliberately absent: one rung, no ancestor to forget.
+  asset_group_asset: ["campaign.status", "asset_group.status", "asset_group_asset.status"],
+  campaign_asset: ["campaign.status", "campaign_asset.status"],
+  ad_group_asset: ["campaign.status", "ad_group.status", "ad_group_asset.status"]
+};
+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}{statusScope} ORDER BY metrics.cost_micros DESC LIMIT {limit}`,
+    defaultDateRange: "LAST_30_DAYS",
+    defaultLimit: 200,
+    statusFields: ["campaign.status"]
+  },
+  {
+    name: "budget-limited",
+    description: "Campaigns Google reports as limited by budget, with each one's bid target next to its actual cost per conversion \u2014 the state where a target above actual now drives delivery up to the target instead of holding recent cost",
+    gaqlTemplate: `SELECT campaign.id, campaign.name, campaign.status, campaign.advertising_channel_type, campaign.bidding_strategy_type, campaign.primary_status, campaign.primary_status_reasons, campaign.target_cpa.target_cpa_micros, campaign.maximize_conversions.target_cpa_micros, campaign.target_roas.target_roas, campaign.maximize_conversion_value.target_roas, campaign.target_cpc.target_cpc_micros, campaign_budget.amount_micros, metrics.cost_micros, metrics.conversions, metrics.conversions_value, metrics.cost_per_conversion, metrics.search_budget_lost_impression_share FROM campaign WHERE campaign.primary_status_reasons CONTAINS ANY (BUDGET_CONSTRAINED) AND segments.date DURING {dateRange}{statusScope} ORDER BY metrics.cost_micros DESC LIMIT {limit}`,
+    defaultDateRange: "LAST_30_DAYS",
+    defaultLimit: 200,
+    statusFields: ["campaign.status"]
+  },
+  {
+    name: "conversions-by-action",
+    description: "Which conversion action each campaign's conversions actually are \u2014 the read that says whether two campaigns' conversion rates are measuring the same event",
+    gaqlTemplate: `SELECT campaign.id, campaign.name, segments.conversion_action_name, segments.conversion_action_category, metrics.conversions, metrics.all_conversions FROM campaign WHERE segments.date DURING {dateRange}{statusScope} ORDER BY metrics.conversions DESC LIMIT {limit}`,
+    defaultDateRange: "LAST_30_DAYS",
+    defaultLimit: 200,
+    statusFields: ["campaign.status"]
+  },
+  {
+    name: "keyword-analysis",
+    description: "Keyword performance with match type and quality",
+    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.quality_info.quality_score, 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"]
+  },
+  {
+    name: "keyword-serving",
+    description: "Why a keyword is limited \u2014 Google Ads' 'Eligible (Limited) / Below first page bid' column, with the first-page bid estimate, the current max CPC and quality score",
+    gaqlTemplate: `SELECT campaign.id, campaign.name, ad_group.id, ad_group.name, ad_group_criterion.criterion_id, ad_group_criterion.keyword.text, ad_group_criterion.keyword.match_type, ad_group_criterion.status, ad_group_criterion.primary_status, ad_group_criterion.primary_status_reasons, ad_group_criterion.system_serving_status, ad_group_criterion.approval_status, ad_group_criterion.effective_cpc_bid_micros, ad_group_criterion.effective_cpc_bid_source, ad_group_criterion.position_estimates.first_page_cpc_micros, ad_group_criterion.position_estimates.top_of_page_cpc_micros, ad_group_criterion.quality_info.quality_score, ad_group_criterion.quality_info.creative_quality_score, ad_group_criterion.quality_info.post_click_quality_score, ad_group_criterion.quality_info.search_predicted_ctr 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"]
+  },
+  {
+    name: "positive-keywords",
+    description: "Positive (targeting) keywords only \u2014 excludes negatives",
+    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"]
+  },
+  {
+    name: "negative-keywords",
+    description: "Negative keywords only \u2014 campaign and ad group level",
+    gaqlTemplate: `SELECT campaign.id, campaign.name, ad_group.name, ad_group_criterion.keyword.text, ad_group_criterion.keyword.match_type, ad_group_criterion.negative FROM ad_group_criterion WHERE ad_group_criterion.type = 'KEYWORD' AND ad_group_criterion.negative = TRUE AND campaign.status != 'REMOVED' ORDER BY campaign.name LIMIT {limit}`,
+    defaultDateRange: "ALL_TIME",
+    defaultLimit: 500
+  },
+  {
+    name: "negative-keyword-lists",
+    description: "Shared negative keyword lists and the terms inside them (SharedSet members)",
+    gaqlTemplate: `SELECT shared_set.id, shared_set.name, shared_criterion.keyword.text, shared_criterion.keyword.match_type FROM shared_criterion WHERE shared_set.type = 'NEGATIVE_KEYWORDS' AND shared_set.status = 'ENABLED' ORDER BY shared_set.name LIMIT {limit}`,
+    defaultDateRange: "ALL_TIME",
+    defaultLimit: 500
+  },
+  {
+    name: "negative-list-attachments",
+    description: "Which campaigns each shared negative keyword list is attached to",
+    gaqlTemplate: `SELECT campaign.id, campaign.name, shared_set.id, shared_set.name FROM campaign_shared_set WHERE shared_set.type = 'NEGATIVE_KEYWORDS' AND campaign_shared_set.status = 'ENABLED' ORDER BY campaign.name LIMIT {limit}`,
+    defaultDateRange: "ALL_TIME",
+    defaultLimit: 500
+  },
+  {
+    name: "search-terms",
+    description: "Actual user search queries triggering ads",
+    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,
+    statusFields: ["campaign.status", "ad_group.status"]
+  },
+  {
+    name: "ad-copy-performance",
+    description: "Ad headline and description effectiveness",
+    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,
+    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, campaign.status, asset_group.name, asset_group.status, asset_group_asset.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,
+    statusFields: ["campaign.status", "asset_group.status", "asset_group_asset.status"]
+  },
+  {
+    name: "shopping-products",
+    description: "Product-level shopping performance metrics",
+    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,
+    statusFields: ["campaign.status"]
+  },
+  {
+    name: "account-summary",
+    description: "Account-level totals for a date range",
+    gaqlTemplate: `SELECT customer.id, customer.descriptive_name, metrics.impressions, metrics.clicks, metrics.cost_micros, metrics.conversions, metrics.conversions_value FROM customer WHERE segments.date DURING {dateRange} LIMIT 1`,
+    defaultDateRange: "LAST_30_DAYS",
+    defaultLimit: 1
+  }
+];
+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, now = /* @__PURE__ */ new Date()) {
+  const dateRange = params.dateRange ?? preset.defaultDateRange;
+  const limit = params.limit ?? preset.defaultLimit;
+  if (preset.gaqlTemplate.includes("{dateRange}") && !isValidDateRange(dateRange)) {
+    return { query: "", dateRangeError: dateRangeError(dateRange, now) };
+  }
+  const statusScope = buildStatusScope(preset.statusFields, params.includePaused ?? false);
+  const range = dateRange.trim();
+  const query = preset.gaqlTemplate.replace(/DURING\s+\{dateRange\}/g, BETWEEN_RE.test(range) ? range : `DURING ${range}`).replace(/\{dateRange\}/g, range).replace(/\{limit\}/g, String(limit)).replace(/\{statusScope\}/g, statusScope);
+  return { query };
+}
+
+// src/commands/ads/google/preflight.ts
+function buildCommand(query, customerId) {
+  return `baker ads google query "${query}" --customer-id ${customerId}`;
+}
+var RUNG_PIN_FIELDS = {
+  "campaign.status": ["campaign.id", "campaign.resource_name"],
+  "ad_group.status": ["ad_group.id", "ad_group.resource_name"],
+  "ad_group_criterion.status": ["ad_group_criterion.criterion_id", "ad_group_criterion.resource_name"],
+  "ad_group_ad.status": ["ad_group_ad.ad.id", "ad_group_ad.resource_name"],
+  "asset_group.status": ["asset_group.id", "asset_group.resource_name"],
+  "asset_group_asset.status": ["asset_group_asset.resource_name"],
+  "campaign_asset.status": ["campaign_asset.resource_name"],
+  "ad_group_asset.status": ["ad_group_asset.resource_name"]
+};
+function whereClause(query) {
+  const match = query.match(/\bWHERE\b([\s\S]*)$/i);
+  if (!match?.[1]) return "";
+  let rest = match[1];
+  for (const trailing of [/\bORDER\s+BY\b/i, /\bLIMIT\b/i, /\bPARAMETERS\b/i]) {
+    const idx = rest.search(trailing);
+    if (idx !== -1) rest = rest.slice(0, idx);
+  }
+  return rest;
+}
+function selectClause(query) {
+  return query.split(/\bFROM\b/i)[0] ?? "";
+}
+function mentions(clause, field) {
+  return new RegExp(`(?<![\\w.])${field.replace(/\./g, "\\.")}\\b`, "i").test(clause);
+}
+function analyzeServingChain(query) {
+  const resource = fromResource(query);
+  const chain = resource ? SERVING_CHAINS[resource] : void 0;
+  if (!chain) return null;
+  const where = whereClause(query);
+  if (/ad_group_criterion\.negative\s*=\s*TRUE/i.test(where)) return null;
+  const unscoped = chain.filter((rung) => {
+    if (mentions(where, rung)) return false;
+    return !(RUNG_PIN_FIELDS[rung] ?? []).some((pin) => mentions(where, pin));
+  });
+  const assertsServing = chain.some(
+    (rung) => new RegExp(`${rung.replace(/\./g, "\\.")}\\s*=\\s*'ENABLED'`, "i").test(where)
+  );
+  return { chain, unscoped, assertsServing };
+}
+function rejectPartialChain(query, customerId, analysis) {
+  if (!analysis.assertsServing || analysis.unscoped.length === 0) return null;
+  const added = analysis.unscoped.map((rung) => `${rung} = 'ENABLED'`).join(" AND ");
+  const fixed = addRequiredAncestorFields(query.replace(/\bWHERE\b/i, `WHERE ${added} AND`)).query;
+  return {
+    ok: false,
+    error: {
+      code: "INCOMPLETE_STATUS_CHAIN",
+      message: `This query filters on serving status but leaves ${analysis.unscoped.join(", ")} unscoped. Google Ads has no single serving flag \u2014 a row is live only when its whole chain (${analysis.chain.join(" \u2192 ")}) is ENABLED, so rows under a paused parent will come back looking live.`,
+      fix: {
+        action: "retry_with_modified_query",
+        correctedCommand: buildCommand(fixed, customerId),
+        explanation: `Add the missing rungs: ${added}. To look at paused entities on purpose, scope every rung explicitly instead (e.g. ${analysis.unscoped.map((rung) => `${rung} != 'REMOVED'`).join(" AND ")}), or use --preset ... --include-paused.`
+      },
+      retryable: false
+    }
+  };
+}
+function annotateUnscopedChain(query, analysis) {
+  if (analysis.assertsServing || analysis.unscoped.length === 0) return { query, warnings: [] };
+  const select = selectClause(query);
+  const missing = analysis.unscoped.filter((rung) => !mentions(select, rung));
+  if (missing.length === 0) return { query, warnings: [] };
+  return {
+    query: query.replace(/SELECT\s+/i, `SELECT ${missing.join(", ")}, `),
+    warnings: [
+      {
+        code: "SERVING_STATUS_ADDED",
+        message: `Added ${missing.join(", ")} to SELECT \u2014 this query does not scope ${analysis.unscoped.join(", ")}, so it returns paused-parent rows that are not serving. Read those columns before calling any row live; filter every rung = 'ENABLED' to get serving rows only.`
+      }
+    ]
+  };
+}
+var SINGLE_ROW_RESOURCES = ["customer"];
+function fromResource(query) {
+  const match = query.match(/\bFROM\s+([A-Za-z_][A-Za-z0-9_]*)/i);
+  return match?.[1]?.toLowerCase() ?? null;
+}
+function isSingleRowRead(query) {
+  const resource = fromResource(query);
+  if (!resource || !SINGLE_ROW_RESOURCES.includes(resource)) return false;
+  return !/\bsegments\./i.test(selectClause(query));
+}
+var SEGMENTING_ANCESTORS = {
+  campaign_budget: ["campaign"],
+  campaign_asset: ["campaign"],
+  ad_group_asset: ["campaign", "ad_group"]
+};
+function missingRequiredSelectFields(query) {
+  const ancestors = SEGMENTING_ANCESTORS[fromResource(query) ?? ""];
+  if (!ancestors) return [];
+  const select = selectClause(query);
+  const where = query.split(/\bWHERE\b/i)[1] ?? "";
+  const filtered = ancestors.flatMap(
+    (ancestor) => where.match(new RegExp(`(?<![\\w.])${ancestor}\\.[\\w.]+`, "g")) ?? []
+  );
+  return [...new Set(filtered)].filter((field) => !mentions(select, field));
+}
+function addRequiredAncestorFields(query) {
+  const missing = missingRequiredSelectFields(query);
+  if (missing.length === 0) return { query, warnings: [] };
+  return {
+    query: query.replace(/SELECT\s+/i, `SELECT ${missing.join(", ")}, `),
+    warnings: [
+      {
+        code: "REQUIRED_FIELD_ADDED",
+        message: `Added ${missing.join(", ")} to SELECT \u2014 ${fromResource(query)} queries must select the ancestor fields used in WHERE`
+      }
+    ]
+  };
+}
+function applyAutoFixes(query, limit) {
+  let corrected = query;
+  const warnings = [];
+  if (/(?<![\w.])keyword\.text\b/.test(corrected)) {
+    corrected = corrected.replace(/(?<![\w.])keyword\.text\b/g, "ad_group_criterion.keyword.text");
+    warnings.push({ code: "FIELD_RENAMED", message: "keyword.text \u2192 ad_group_criterion.keyword.text" });
+  }
+  if (/(?<![\w.])keyword\.match_type\b/.test(corrected)) {
+    corrected = corrected.replace(/(?<![\w.])keyword\.match_type\b/g, "ad_group_criterion.keyword.match_type");
+    warnings.push({ code: "FIELD_RENAMED", message: "keyword.match_type \u2192 ad_group_criterion.keyword.match_type" });
+  }
+  if (/shopping_performance_view\.product_\w+/.test(corrected)) {
+    corrected = corrected.replace(/shopping_performance_view\.product_(\w+)/g, "segments.product_$1");
+    warnings.push({ code: "FIELD_RENAMED", message: "shopping_performance_view.product_* \u2192 segments.product_*" });
+  }
+  if (/asset\.\w+_asset\.final_(mobile_)?urls\b/.test(corrected)) {
+    corrected = corrected.replace(/asset\.\w+_asset\.final_(mobile_)?urls\b/g, "asset.final_$1urls");
+    warnings.push({ code: "FIELD_RENAMED", message: "asset.<type>_asset.final_urls \u2192 asset.final_urls" });
+  }
+  const ancestorFix = addRequiredAncestorFields(corrected);
+  corrected = ancestorFix.query;
+  warnings.push(...ancestorFix.warnings);
+  if (/campaign\.status\s*=\s*'ACTIVE'/i.test(corrected)) {
+    corrected = corrected.replace(/campaign\.status\s*=\s*'ACTIVE'/gi, "campaign.status = 'ENABLED'");
+    warnings.push({ code: "ENUM_CORRECTED", message: "campaign.status ACTIVE \u2192 ENABLED" });
+  }
+  if (/ad_group\.status\s*=\s*'ACTIVE'/i.test(corrected)) {
+    corrected = corrected.replace(/ad_group\.status\s*=\s*'ACTIVE'/gi, "ad_group.status = 'ENABLED'");
+    warnings.push({ code: "ENUM_CORRECTED", message: "ad_group.status ACTIVE \u2192 ENABLED" });
+  }
+  if (!/\bLIMIT\b/i.test(corrected)) {
+    const effectiveLimit = limit ?? 200;
+    corrected = `${corrected.trimEnd()} LIMIT ${effectiveLimit}`;
+    if (!isSingleRowRead(corrected)) {
+      warnings.push({ code: "AUTO_LIMIT", message: `Added LIMIT ${effectiveLimit}. Use --limit to override.` });
+    }
+  }
+  return { query: corrected, warnings };
+}
+var DURING_CLAUSE = /(?<=[a-z_]\.[a-z_.]+\s+)DURING\s+([A-Za-z0-9_]+)/gi;
+function rejectUnsupportedDuring(query, customerId) {
+  const unsupported = [...query.matchAll(DURING_CLAUSE)].map((match) => match[1] ?? "").filter((literal2) => !isDuringLiteral(literal2));
+  const literal = unsupported[0];
+  if (literal === void 0) return null;
+  const now = /* @__PURE__ */ new Date();
+  const between = equivalentBetween(literal, now);
+  const fixed = unsupported.every((l) => equivalentBetween(l, now) !== null) ? query.replace(
+    DURING_CLAUSE,
+    (clause, l) => isDuringLiteral(l) ? clause : equivalentBetween(l, now) ?? clause
+  ) : void 0;
+  return {
+    ok: false,
+    error: {
+      code: "INVALID_DATE_RANGE",
+      message: `DURING ${literal} is not a Google Ads date range, so Google would refuse this query.`,
+      fix: {
+        action: "narrow_date_range",
+        ...fixed ? { correctedCommand: buildCommand(fixed, customerId) } : {},
+        explanation: duringLiteralExplanation(literal, between)
+      },
+      retryable: false
+    }
+  };
+}
+function rejectOversizedLimit(query, customerId) {
+  const match = query.match(/\bLIMIT\s+(\d+)\s*$/i);
+  if (!match || Number(match[1]) <= GOOGLE_ADS_QUERY_MAX_PAGE_SIZE) return null;
+  const fixed = query.replace(/\bLIMIT\s+\d+\s*$/i, `LIMIT ${GOOGLE_ADS_QUERY_MAX_PAGE_SIZE}`);
+  return {
+    ok: false,
+    error: {
+      code: "VALIDATION_ERROR",
+      message: `LIMIT ${match[1]} is more rows than one read can return (${GOOGLE_ADS_QUERY_MAX_PAGE_SIZE}).`,
+      fix: {
+        action: "retry_with_flag",
+        correctedCommand: buildCommand(fixed, customerId),
+        explanation: `One query returns at most ${GOOGLE_ADS_QUERY_MAX_PAGE_SIZE} rows. For more, split the read into narrower queries \u2014 a shorter BETWEEN range each, or one campaign each \u2014 write each with --out, and combine the files.`
+      },
+      retryable: false
+    }
+  };
+}
+var WHERE_OPERATOR = /(?<![\w.])([a-z_]+(?:\.[a-z_]+)+)\s*(CONTAINS\s+(?:ALL|ANY|NONE)|IS\s+NOT\s+NULL|IS\s+NULL|NOT\s+LIKE|NOT\s+IN|NOT\s+REGEXP_MATCH|REGEXP_MATCH|LIKE|IN|BETWEEN|DURING|!=|<=|>=|=|<|>)/gi;
+function escapeRegExp(text) {
+  return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function withoutNullTest(query, field) {
+  const test = `${escapeRegExp(field)}\\s+IS\\s+(?:NOT\\s+)?NULL\\b`;
+  const dropped = query.replace(new RegExp(`\\bWHERE\\s+${test}\\s+AND\\s+`, "i"), "WHERE ").replace(new RegExp(`\\s+AND\\s+${test}`, "i"), "").replace(new RegExp(`\\s*\\bWHERE\\s+${test}`, "i"), "");
+  return mentions(selectClause(dropped), field) ? dropped : dropped.replace(/SELECT\s+/i, `SELECT ${field}, `);
+}
+function asListCondition(query, field) {
+  const condition = new RegExp(
+    `(?<![\\w.])${escapeRegExp(field)}\\s*(NOT\\s+IN\\b|IN\\b|!=|=)\\s*('[^']*'|\\([^)]*\\))`,
+    "i"
+  );
+  const match = query.match(condition);
+  if (!match) return null;
+  const [, operator = "", value = ""] = match;
+  const contains = /^(=|IN)$/i.test(operator.trim()) ? "CONTAINS ANY" : "CONTAINS NONE";
+  const values = value.startsWith("(") ? value : `(${value})`;
+  return query.replace(condition, `${field} ${contains} ${values}`);
+}
+function rejectListFieldOperator(query, customerId) {
+  const where = whereClause(query).replace(/'[^']*'/g, "''");
+  const refusals = [...where.matchAll(WHERE_OPERATOR)].map(([, field = "", operator = ""]) => ({
+    field: field.toLowerCase(),
+    operator: operator.toUpperCase().replace(/\s+/g, " ")
+  })).filter(({ field, operator }) => LIST_FIELDS.has(field) && !operator.startsWith("CONTAINS"));
+  const first = refusals[0];
+  if (!first) return null;
+  const fixed = refusals.reduce(
+    (corrected, { field, operator }) => corrected === null ? null : operator.startsWith("IS ") ? withoutNullTest(corrected, field) : asListCondition(corrected, field),
+    query
+  );
+  return {
+    ok: false,
+    error: {
+      code: "INVALID_OPERATOR",
+      message: `${first.operator} cannot be used on ${first.field}: it is a list field, so Google would refuse this query.`,
+      fix: {
+        action: "change_operator",
+        ...fixed ? { correctedCommand: buildCommand(fixed, customerId) } : {},
+        explanation: listFieldGuidance(first.field)
+      },
+      retryable: false
+    }
+  };
+}
+function rejectContainsCall(query, customerId) {
+  const containsMatch = query.match(/CONTAINS\s*\(\s*([^,]+),\s*'([^']+)'\s*\)/i);
+  if (!containsMatch) return null;
+  const field = containsMatch[1]?.trim();
+  const value = containsMatch[2] ?? "";
+  const fixed = query.replace(/CONTAINS\s*\(\s*[^,]+,\s*'[^']+'\s*\)/i, `${field} LIKE '%${value}%'`);
+  return {
+    ok: false,
+    error: {
+      code: "INVALID_OPERATOR",
+      message: "GAQL does not support CONTAINS. Use LIKE with % wildcards.",
+      fix: {
+        action: "change_operator",
+        correctedCommand: buildCommand(fixed, customerId),
+        explanation: "GAQL uses LIKE '%value%' for substring matching, not CONTAINS()"
+      },
+      retryable: false
+    }
+  };
+}
+function validatePreflight(query, customerId, limit) {
+  const warnings = [];
+  const corrected = query;
+  const firstWord = corrected.trim().split(/\s+/)[0]?.toUpperCase();
+  if (firstWord && firstWord !== "SELECT") {
+    return {
+      valid: false,
+      warnings: [],
+      error: {
+        ok: false,
+        error: {
+          code: "READ_ONLY",
+          message: `Only SELECT queries are allowed. Got: ${firstWord}`,
+          fix: {
+            action: "reject",
+            explanation: "This CLI only supports GAQL SELECT queries for reading data"
+          },
+          retryable: false
+        }
+      }
+    };
+  }
+  const openDateMatch = corrected.match(/segments\.date\s*>=\s*'(\d{4}-\d{2}-\d{2})'/i);
+  if (openDateMatch && !/BETWEEN/i.test(corrected)) {
+    const startDate = openDateMatch[1] ?? "";
+    const today = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
+    const fixed = corrected.replace(
+      /segments\.date\s*>=\s*'(\d{4}-\d{2}-\d{2})'/i,
+      `segments.date BETWEEN '${startDate}' AND '${today}'`
+    );
+    return {
+      valid: false,
+      warnings: [],
+      error: {
+        ok: false,
+        error: {
+          code: "OPEN_ENDED_DATE",
+          message: "Open-ended date ranges are not supported. Use BETWEEN or DURING.",
+          fix: {
+            action: "narrow_date_range",
+            correctedCommand: buildCommand(fixed, customerId),
+            explanation: "Use BETWEEN with explicit start and end dates"
+          },
+          retryable: false
+        }
+      }
+    };
+  }
+  for (const reject of [rejectContainsCall, rejectListFieldOperator, rejectUnsupportedDuring, rejectOversizedLimit]) {
+    const rejection2 = reject(corrected, customerId);
+    if (rejection2) return { valid: false, warnings: [], error: rejection2 };
+  }
+  if (/\bsegments\.conversion_action_name\b/i.test(corrected) && /\bmetrics\.cost_micros\b/i.test(corrected)) {
+    return {
+      valid: false,
+      warnings: [],
+      error: {
+        ok: false,
+        error: {
+          code: "INCOMPATIBLE_FIELDS",
+          message: "segments.conversion_action_name cannot be selected with metrics.cost_micros in one GAQL query.",
+          fix: {
+            action: "split_query",
+            explanation: "Run one campaign spend query with metrics.cost_micros and a separate conversion-action query without cost metrics, then join the results by campaign."
+          },
+          retryable: false
+        }
+      }
+    };
+  }
+  if (/FROM\s+ad_group_criterion\b/i.test(corrected) && !/ad_group_criterion\.negative/i.test(corrected)) {
+    warnings.push({
+      code: "NEGATIVE_FIELD_MISSING",
+      message: "ad_group_criterion returns BOTH positive and negative keywords. Add ad_group_criterion.negative to SELECT or filter with WHERE ad_group_criterion.negative = FALSE (positives) / TRUE (negatives). Use --preset positive-keywords or negative-keywords instead."
+    });
+  }
+  const { query: autoFixed, warnings: autoFixWarnings } = applyAutoFixes(corrected, limit);
+  warnings.push(...autoFixWarnings);
+  const analysis = analyzeServingChain(autoFixed);
+  if (!analysis) return { valid: true, correctedQuery: autoFixed, warnings };
+  const rejection = rejectPartialChain(autoFixed, customerId, analysis);
+  if (rejection) return { valid: false, warnings: [], error: rejection };
+  const annotated = annotateUnscopedChain(autoFixed, analysis);
+  warnings.push(...annotated.warnings);
+  return { valid: true, correctedQuery: annotated.query, warnings };
+}
+
+// src/commands/ads/google/conversion-mix.ts
+var CONVERSION_METRICS = [
+  "METRICS.CONVERSIONS",
+  "METRICS.ALL_CONVERSIONS",
+  "METRICS.CONVERSIONS_VALUE",
+  "METRICS.ALL_CONVERSIONS_VALUE",
+  "METRICS.COST_PER_CONVERSION",
+  "METRICS.COST_PER_ALL_CONVERSIONS",
+  "METRICS.CONVERSIONS_FROM_INTERACTIONS_RATE",
+  "METRICS.ALL_CONVERSIONS_FROM_INTERACTIONS_RATE",
+  "METRICS.VALUE_PER_CONVERSION",
+  "METRICS.VALUE_PER_ALL_CONVERSIONS"
+];
+var CONVERSION_SEGMENTS = ["SEGMENTS.CONVERSION_ACTION_NAME", "SEGMENTS.CONVERSION_ACTION="];
+var CAMPAIGN_EQUALITY = /\bCAMPAIGN\.(ID|NAME|RESOURCE_NAME)\s*=/;
+function whereClause2(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 conversionMixWarnings(finalQuery) {
+  const upper = ` ${finalQuery.toUpperCase().replace(/\s+/g, " ")} `;
+  const readsConversions = CONVERSION_METRICS.some((metric) => upper.includes(metric));
+  if (!readsConversions) return [];
+  if (CONVERSION_SEGMENTS.some((segment) => upper.includes(segment))) return [];
+  if (CAMPAIGN_EQUALITY.test(whereClause2(upper))) return [];
+  if (isSingleRowRead(finalQuery)) return [];
+  return [
+    {
+      code: "CONVERSION_MIX",
+      message: "MIXED CONVERSION ACTIONS \u2014 this read covers more than one campaign, and a campaign's conversion figures count whatever conversion actions are primary for it. Those differ campaign by campaign (a webinar registration, an info request, a CRM-stage SQL), so a total across these rows adds different events and a conversion rate from one campaign is not comparable with another's. Before totalling or comparing, re-run segmented by segments.conversion_action_name and check the campaigns you are putting side by side count the same action. If they do not, compare only within one action \u2014 and carry that caveat into anything you write for the user, not just the analysis."
+    }
+  ];
+}
+
+// src/commands/ads/google/keyword-serving.ts
+var BELOW_FIRST_PAGE_BID = "AD_GROUP_CRITERION_BELOW_FIRST_PAGE_BID";
+var ACTIONABLE_REASONS = {
+  [BELOW_FIRST_PAGE_BID]: {
+    label: "Below first page bid",
+    advice: "raise the max CPC (keywords update --cpc-bid) to at least the first-page estimate, or move the ad group onto a smart bidding strategy that sets the bid itself"
+  },
+  AD_GROUP_CRITERION_LOW_QUALITY: {
+    label: "Low quality score",
+    advice: "a bid raise does not lift quality \u2014 tighten ad relevance to the keyword and the landing page it points at (ad_group_criterion.quality_info.* breaks the score into its three parts)"
+  },
+  AD_GROUP_CRITERION_RARELY_SERVED: {
+    label: "Rarely served",
+    advice: "too few people search this term \u2014 broaden the match type or drop it, don't bid it up"
+  },
+  AD_GROUP_CRITERION_DISAPPROVED: {
+    label: "Disapproved",
+    advice: "select ad_group_criterion.disapproval_reasons to see which policy blocked it"
+  },
+  AD_GROUP_CRITERION_RESTRICTED: {
+    label: "Restricted",
+    advice: "policy limits where and to whom this keyword may show"
+  },
+  AD_GROUP_CRITERION_UNDER_REVIEW: {
+    label: "Under review",
+    advice: "waiting on Google's review \u2014 nothing to change yet"
+  },
+  AD_GROUP_CRITERION_PENDING_REVIEW: {
+    label: "Pending review",
+    advice: "waiting on Google's review \u2014 nothing to change yet"
+  },
+  AD_GROUP_CRITERION_PAUSED_DUE_TO_LOW_ACTIVITY: {
+    label: "Auto-paused for low activity",
+    advice: "Google paused it after prolonged low serving \u2014 resume it only alongside a change that gives it traffic"
+  }
+};
+var REASON_ORDER = Object.keys(ACTIONABLE_REASONS);
+var MAX_NAMED_KEYWORDS = 5;
+function toMicros(value) {
+  if (typeof value === "number" && Number.isFinite(value)) return value;
+  if (typeof value === "string" && value.trim() !== "" && Number.isFinite(Number(value))) return Number(value);
+  return null;
+}
+function formatMoney(micros) {
+  return (micros / 1e6).toFixed(2);
+}
+function keywordLabel(row) {
+  const text = row["ad_group_criterion.keyword.text"];
+  const id = row["ad_group_criterion.criterion_id"];
+  const name = typeof text === "string" && text !== "" ? text : id == null ? "(unnamed keyword)" : `criterion ${id}`;
+  const adGroup = row["ad_group.name"];
+  return typeof adGroup === "string" && adGroup !== "" ? `${name} (ad group ${adGroup})` : name;
+}
+function keywordKey(row) {
+  const adGroup = row["ad_group.id"] ?? row["ad_group.name"] ?? "";
+  const criterion = row["ad_group_criterion.criterion_id"] ?? row["ad_group_criterion.keyword.text"] ?? "";
+  return `${String(adGroup)}~${String(criterion)}` === "~" ? keywordLabel(row) : `${adGroup}~${criterion}`;
+}
+function reasonsOn(row) {
+  const raw = row["ad_group_criterion.primary_status_reasons"];
+  if (!Array.isArray(raw)) return null;
+  return raw.filter((r) => typeof r === "string");
+}
+function bidShortfall(row) {
+  const bid = toMicros(row["ad_group_criterion.effective_cpc_bid_micros"] ?? row["ad_group_criterion.cpc_bid_micros"]);
+  const firstPage = toMicros(row["ad_group_criterion.position_estimates.first_page_cpc_micros"]);
+  if (bid == null || firstPage == null || bid >= firstPage) return null;
+  return `bids ${formatMoney(bid)} against a ${formatMoney(firstPage)} first-page estimate`;
+}
+function limitsOn(row, options) {
+  const reasons = reasonsOn(row);
+  const shortfall = bidShortfall(row);
+  const label = keywordLabel(row);
+  const applicable = reasons ? reasons.filter((reason) => reason in ACTIONABLE_REASONS) : options.statusReasonsSelected || shortfall === null ? [] : [BELOW_FIRST_PAGE_BID];
+  return applicable.map((reason) => ({
+    reason,
+    detail: reason === BELOW_FIRST_PAGE_BID && shortfall ? `"${label}" ${shortfall}` : `"${label}"`
+  }));
+}
+function describeLimit(reason, details) {
+  const named = details.slice(0, MAX_NAMED_KEYWORDS).join("; ");
+  const rest = details.length > MAX_NAMED_KEYWORDS ? ` (+${details.length - MAX_NAMED_KEYWORDS} more)` : "";
+  const { label, advice } = ACTIONABLE_REASONS[reason];
+  return `${label} \u2014 ${details.length}: ${named}${rest}. Fix: ${advice}.`;
+}
+function collectKeywordLimits(rows, options, acc = { detailsByReason: /* @__PURE__ */ new Map(), keywords: /* @__PURE__ */ new Set() }) {
+  for (const row of rows) {
+    const limits = limitsOn(row, options);
+    if (limits.length === 0) continue;
+    acc.keywords.add(keywordKey(row));
+    for (const { reason, detail } of limits) {
+      const bucket = acc.detailsByReason.get(reason);
+      if (bucket) bucket.push(detail);
+      else acc.detailsByReason.set(reason, [detail]);
+    }
+  }
+  return acc;
+}
+function renderKeywordLimits(limits) {
+  if (limits.detailsByReason.size === 0) return [];
+  const sentences = REASON_ORDER.filter((reason) => limits.detailsByReason.has(reason)).map(
+    (reason) => describeLimit(reason, limits.detailsByReason.get(reason) ?? [])
+  );
+  const count = limits.keywords.size;
+  return [
+    {
+      code: "KEYWORD_SERVING_LIMITED",
+      message: `${count} ${count === 1 ? "keyword is" : "keywords are"} limited and not getting the traffic they could. ${sentences.join(" ")} Amounts are in the account currency (baker ads google currency).`
+    }
+  ];
+}
+function keywordServingWarnings(rows, options) {
+  return renderKeywordLimits(collectKeywordLimits(rows, options));
+}
+
+// src/commands/ads/google/query.ts
+registerSchema({
+  command: "ads.google.query",
+  description: "Run a GAQL (Google Ads Query Language) query. The most powerful command \u2014 supports any valid SELECT statement. Use --preset for common queries without writing GAQL.",
+  args: {
+    query: { type: "string", description: "GAQL SELECT query string", required: false },
+    "customer-id": {
+      type: "string",
+      description: "Google Ads customer ID (10 digits, no dashes). Falls back to BAKER_GOOGLE_ADS_CUSTOMER_ID env var.",
+      required: false
+    },
+    preset: {
+      type: "string",
+      description: "Named query preset. Reads (campaign-performance, conversions-by-action, keyword-analysis, keyword-serving, 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": {
+      type: "string",
+      description: "Date range for presets: a Google date literal (TODAY, YESTERDAY, LAST_7_DAYS, LAST_14_DAYS, LAST_30_DAYS, THIS_MONTH, LAST_MONTH \u2026) or BETWEEN 'YYYY-MM-DD' AND 'YYYY-MM-DD'. Google has no LAST_90_DAYS \u2014 use BETWEEN for any other window.",
+      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 in ONE page (default 200), AND the LIMIT added to a query that has none \u2014 so it caps the whole read with --all too. Values up to 8192 are accepted \u2014 the most one read can return. Any read that fills this cap comes back flagged TRUNCATED_RESULTS \u2014 never count or total from one.",
+      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 },
+    all: {
+      type: "boolean",
+      description: "Follow every page until the data set is exhausted (use with --out for large datasets). Needed for a read you may count or total, but not sufficient: it exhausts the pages, not the statement's LIMIT, so pair it with a LIMIT in the statement above the row count you expect (at most 8192 \u2014 split bigger reads into narrower queries) and check the read came back without TRUNCATED_RESULTS.",
+      required: false
+    },
+    out: {
+      type: "string",
+      description: "Write data to file (format from extension: .csv, .jsonl, .json)",
+      required: false
+    },
+    append: { type: "boolean", description: "Append to existing file (skip CSV headers)", required: false },
+    output: {
+      type: "string",
+      description: "Output format: json|csv|jsonl|md",
+      required: false,
+      default: "json",
+      enum: ["json", "csv", "jsonl", "md"]
+    },
+    "no-cache": { type: "boolean", description: "Skip cache, hit API directly", required: false },
+    full: {
+      type: "boolean",
+      description: "Include the field description glossary in the JSON envelope. Off by default \u2014 rows already carry the data; only ask for this when you need a field's meaning explained.",
+      required: false
+    }
+  }
+});
+function extractFields(rows) {
+  const keys = /* @__PURE__ */ new Set();
+  foldObservedFields(rows, keys);
+  return [...keys];
+}
+function resultColumns(gaql, rows) {
+  const observed = extractFields(rows);
+  const columns = [];
+  for (const field of parseSelectedFields(gaql)) {
+    const leaves = observed.filter((key) => key.startsWith(`${field}.`));
+    columns.push(...leaves.length > 0 ? leaves : [field]);
+  }
+  for (const key of observed) columns.push(key);
+  return [...new Set(columns)];
+}
+function isCsvPath(filePath) {
+  return filePath.split(".").pop()?.toLowerCase() === "csv";
+}
+function writeRowsToFile(filePath, rows, fields, append) {
+  if (isCsvPath(filePath)) {
+    if (!append || !existsSync(filePath)) {
+      writeFileSync(filePath, `${toCsvRow(fields)}
+`, "utf-8");
+    }
+    const csvRows = rows.map((row) => toCsvRow(fields.map((f) => String(row[f] ?? ""))));
+    appendFileSync(filePath, `${csvRows.join("\n")}
+`, "utf-8");
+  } else if (filePath.split(".").pop()?.toLowerCase() === "jsonl") {
+    const lines = rows.map((row) => JSON.stringify(row));
+    if (append && existsSync(filePath)) {
+      appendFileSync(filePath, `${lines.join("\n")}
+`, "utf-8");
+    } else {
+      writeFileSync(filePath, `${lines.join("\n")}
+`, "utf-8");
+    }
+  } else if (append && existsSync(filePath)) {
+    const existing = JSON.parse(readFileSync(filePath, "utf-8"));
+    writeFileSync(filePath, JSON.stringify([...existing, ...rows], null, 2), "utf-8");
+  } else {
+    writeFileSync(filePath, JSON.stringify(rows, null, 2), "utf-8");
+  }
+}
+function effectiveRowLimit(finalQuery, limit, all = false) {
+  if (isSingleRowRead(finalQuery)) return void 0;
+  const match = finalQuery.match(/\bLIMIT\s+(\d+)/i);
+  const statementLimit = match?.[1] ? Number(match[1]) : void 0;
+  if (all) return statementLimit;
+  return statementLimit === void 0 ? limit : Math.min(limit, statementLimit);
+}
+function warningLines(warnings, format) {
+  return warnings.map((w) => {
+    const message = w.message.replace(/\s*\n\s*/g, " ");
+    if (format === "jsonl") return JSON.stringify({ _baker_warning: { code: w.code, message } });
+    if (format === "md") return `> **${w.code}** \u2014 ${message}`;
+    return `# baker ${w.code}: ${message}`;
+  });
+}
+function completenessWarnings(read) {
+  const cap = read.effectiveLimit;
+  const filledTheCap = cap !== void 0 && cap > 0 && read.rowCount >= cap;
+  if (!read.hasMore && !filledTheCap) return [];
+  const cause = read.hasMore ? `More rows are waiting: the account returned a next-page cursor this run did not follow.` : `The ${read.rowCount} rows returned exactly fill the row cap in force (${cap}).`;
+  const atPageCap = cap !== void 0 && cap >= GOOGLE_ADS_QUERY_MAX_PAGE_SIZE;
+  const fix = atPageCap ? `${GOOGLE_ADS_QUERY_MAX_PAGE_SIZE} rows is the most one read can return \u2014 split it into narrower queries (a shorter BETWEEN range each, or one campaign each), write each with --out, and combine the files.` : read.all ? `Every page was followed, so the cap is the LIMIT in the statement itself \u2014 raise it above ${cap}, or drop it and pass a larger --limit (up to ${GOOGLE_ADS_QUERY_MAX_PAGE_SIZE}), then re-run.` : `Re-run with --all --out <file> to page through everything, or raise --limit above ${cap} (up to ${GOOGLE_ADS_QUERY_MAX_PAGE_SIZE}).`;
+  return [
+    {
+      code: "TRUNCATED_RESULTS",
+      message: `INCOMPLETE READ \u2014 ${cause} These rows are a page, not the data set. Don't count, total or describe them as the whole picture. ${fix}`
+    }
+  ];
+}
+function buildQueryEnvelope(rows, fieldDescs, warnings, options) {
+  const notice = summariseWarnings(warnings);
+  return {
+    ok: true,
+    ...options.cached ? { cached: true } : {},
+    ...warnings.length > 0 ? { warnings } : {},
+    ...options.nextCursor ? { pagination: { hasMore: true, cursor: options.nextCursor } } : {},
+    data: rows,
+    ...options.full && Object.keys(fieldDescs).length > 0 ? { fields: fieldDescs } : {},
+    ...notice ? { notice } : {}
+  };
+}
+function summariseWarnings(warnings) {
+  if (warnings.length === 0) return void 0;
+  const codes = [...new Set(warnings.map((w) => w.code))].join(", ");
+  return `Read the "warnings" above before using these rows: ${codes}.`;
+}
+function buildFileSummary(input) {
+  const notice = summariseWarnings(input.warnings);
+  return {
+    ok: true,
+    fields: {},
+    file: input.file,
+    rows: input.rows,
+    complete: input.complete,
+    ...input.warnings.length > 0 ? { warnings: input.warnings } : {},
+    ...notice ? { notice } : {}
+  };
+}
+var REPEAT_NOTICE_ABOVE_ROWS = 20;
+function emitToStderr(notices) {
+  for (const line of notices) process.stderr.write(`${line}
+`);
+}
+function writeLine(line) {
+  process.stdout.write(`${line}
+`);
+}
+var writeCsvRows = (rows, fields, notices) => {
+  writeLine(toCsvRow(fields));
+  for (const line of notices) writeLine(line);
+  for (const row of rows) writeLine(toCsvRow(fields.map((f) => String(row[f] ?? ""))));
+};
+var writeJsonlRows = (rows, _fields, notices) => {
+  for (const line of notices) writeLine(line);
+  for (const row of rows) writeLine(JSON.stringify(row));
+};
+var OMITTED = "(omitted)";
+var OMITTED_FALSE = `false ${OMITTED}`;
+var OMITTED_LEGEND = `> ${OMITTED} = Google left this field off the row, which is how it sends false, 0 and "not set": the field WAS read. A field with no column here was not read.`;
+function mdCell(row, field, booleanColumns) {
+  if (!(field in row)) return booleanColumns.has(field) ? OMITTED_FALSE : OMITTED;
+  return String(row[field] ?? "").replace(/\|/g, "\\|");
+}
+var writeMdRows = (rows, fields, notices) => {
+  const booleanColumns = new Set(fields.filter((f) => rows.some((row) => typeof row[f] === "boolean")));
+  for (const line of notices) writeLine(line);
+  writeLine(`| ${fields.join(" | ")} |`);
+  writeLine(`| ${fields.map(() => "---").join(" | ")} |`);
+  for (const row of rows) writeLine(`| ${fields.map((f) => mdCell(row, f, booleanColumns)).join(" | ")} |`);
+  if (rows.some((row) => fields.some((f) => !(f in row)))) writeLine(OMITTED_LEGEND);
+};
+var ROW_WRITERS = { csv: writeCsvRows, jsonl: writeJsonlRows, md: writeMdRows };
+function writeRows(format, rows, columns, notices) {
+  const write = ROW_WRITERS[format] ?? writeMdRows;
+  write(rows, columns, notices);
+  if (rows.length > REPEAT_NOTICE_ABOVE_ROWS) {
+    for (const line of notices) writeLine(line);
+  }
+}
+function outputResults(rows, fieldDescs, warnings, args, cached, read) {
+  const format = args.output || "json";
+  const allWarnings = [
+    ...warnings,
+    ...completenessWarnings({
+      rowCount: rows.length,
+      effectiveLimit: read.effectiveLimit,
+      all: read.all,
+      hasMore: Boolean(read.nextCursor)
+    })
+  ];
+  emitToStderr(warningLines(allWarnings, "csv"));
+  if (format === "json") {
+    writeAdsJson(
+      buildQueryEnvelope(rows, fieldDescs, allWarnings, {
+        full: Boolean(args.full),
+        cached,
+        nextCursor: read.nextCursor
+      })
+    );
+    return;
+  }
+  writeRows(format, rows, resultColumns(read.gaql, rows), warningLines(allWarnings, format));
+}
+function resolveGaql(args, limit) {
+  if (args.preset) {
+    const preset = getPreset(args.preset);
+    if (!preset) {
+      const available = PRESETS.map((p) => p.name).join(", ");
+      writeAdsJson({
+        ok: false,
+        error: { code: "VALIDATION_ERROR", message: `Unknown preset: "${args.preset}". Available: ${available}` }
+      });
+      return null;
+    }
+    const expanded = expandPreset(preset, {
+      dateRange: args["date-range"],
+      limit,
+      includePaused: Boolean(args["include-paused"])
+    });
+    if (expanded.dateRangeError) {
+      writeAdsJson({
+        ok: false,
+        error: { code: "VALIDATION_ERROR", message: expanded.dateRangeError }
+      });
+      return null;
+    }
+    return expanded.query;
+  }
+  const gaql = args.query ?? "";
+  if (!gaql) {
+    writeAdsJson({
+      ok: false,
+      error: {
+        code: "VALIDATION_ERROR",
+        message: "Provide a GAQL query or use --preset. Run --list-presets to see options."
+      }
+    });
+    return null;
+  }
+  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"
+].filter((resource) => !(resource in SERVING_CHAINS));
+function whereClause3(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 upper = finalQuery.toUpperCase();
+  const fromMatch = upper.match(/\bFROM\s+([A-Z_]+)/);
+  const resource = fromMatch?.[1]?.toLowerCase();
+  const hierarchical = resource ? SERVING_HIERARCHY_RESOURCES.includes(resource) : false;
+  const filtersStatus = whereClause3(upper).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 [];
+}
+function parseSelectedFields(gaql) {
+  const match = gaql.match(/\bSELECT\b([\s\S]*?)\bFROM\b/i);
+  const list = match?.[1];
+  if (!list) return [];
+  return list.split(",").map((field) => field.trim()).filter((field) => /^[A-Za-z_][A-Za-z0-9_]*(\.[A-Za-z0-9_]+)*$/.test(field));
+}
+function foldObservedFields(rows, observed) {
+  for (const row of rows) {
+    for (const key of Object.keys(row)) observed.add(key);
+  }
+}
+function unobservedSelectedFields(gaql, rows) {
+  const observed = /* @__PURE__ */ new Set();
+  foldObservedFields(rows, observed);
+  return unobservedFields(gaql, observed);
+}
+function unobservedFields(gaql, observed) {
+  return parseSelectedFields(gaql).filter((field) => {
+    if (field.endsWith(".resource_name")) return false;
+    if (observed.has(field)) return false;
+    return ![...observed].some((key) => key.startsWith(`${field}.`));
+  });
+}
+function missingFieldWarnings(gaql, rows) {
+  const observed = /* @__PURE__ */ new Set();
+  foldObservedFields(rows, observed);
+  return missingFieldWarningsFor(gaql, observed, rows.length);
+}
+function missingFieldWarningsFor(gaql, observed, rowCount) {
+  if (rowCount === 0) return [];
+  const missing = unobservedFields(gaql, observed);
+  if (missing.length === 0) return [];
+  return [
+    {
+      code: "MISSING_FIELDS",
+      message: `These SELECTed fields came back on no row: ${missing.join(", ")}. Google Ads omits a field entirely when it has no value, so this does NOT mean the setting is empty \u2014 it means this read didn't observe it. Check the level that owns the setting before concluding it is unset.`
+    }
+  ];
+}
+function unwrittenColumnWarnings(header, observed) {
+  const written = new Set(header);
+  const unwritten = [...observed].filter((key) => !written.has(key));
+  if (unwritten.length === 0) return [];
+  return [
+    {
+      code: "UNWRITTEN_COLUMNS",
+      message: `The file has no column for ${unwritten.join(", ")}: the header was fixed on the first page, which carried none of them, so their values from later pages are NOT in the file. Do not read those columns as empty. SELECT these fields by name instead of their parent, or write to a .jsonl file, then re-run.`
+    }
+  ];
+}
+function keywordServingOptions(gaql) {
+  return { statusReasonsSelected: parseSelectedFields(gaql).includes("ad_group_criterion.primary_status_reasons") };
+}
+async function fetchAllPages(gaql, body, args, servingOptions) {
+  let allRows = [];
+  let pageToken = args.cursor;
+  let totalRowsWritten = 0;
+  let keywordLimits;
+  const observedFields = /* @__PURE__ */ new Set();
+  let fileColumns;
+  do {
+    const requestBody = { ...body };
+    if (pageToken) requestBody.pageToken = pageToken;
+    const response = await apiPost("/api/ads/google/query", requestBody);
+    const rows = response.rows ?? [];
+    pageToken = response.pageToken;
+    if (args.out) {
+      const shouldAppend = args.append || totalRowsWritten > 0;
+      fileColumns ??= resultColumns(gaql, rows);
+      writeRowsToFile(resolve(args.out), rows, fileColumns, shouldAppend);
+      totalRowsWritten += rows.length;
+      keywordLimits = collectKeywordLimits(rows, servingOptions, keywordLimits);
+      foldObservedFields(rows, observedFields);
+    } else {
+      allRows = allRows.concat(rows);
+    }
+    if (!args.all) break;
+  } while (pageToken);
+  return {
+    allRows,
+    lastPageToken: pageToken,
+    totalRowsWritten,
+    keywordLimits: keywordLimits ?? collectKeywordLimits([], servingOptions),
+    observedFields,
+    fileColumns: fileColumns ?? []
+  };
+}
+async function executeQuery(finalQuery, args, customerId, limit, warnings, useCache, cacheKey) {
+  const body = { customerId, query: finalQuery, pageSize: limit };
+  const managerId = getManagerIdForCustomer(customerId);
+  if (managerId) body.managerId = managerId;
+  if (args.cursor) body.pageToken = args.cursor;
+  if (!useCache) body.skipCache = true;
+  const servingOptions = keywordServingOptions(finalQuery);
+  const { allRows, lastPageToken, totalRowsWritten, keywordLimits, observedFields, fileColumns } = await fetchAllPages(
+    finalQuery,
+    body,
+    args,
+    servingOptions
+  );
+  if (args.out) {
+    const truncation = completenessWarnings({
+      rowCount: totalRowsWritten,
+      effectiveLimit: effectiveRowLimit(finalQuery, limit, Boolean(args.all)),
+      all: Boolean(args.all),
+      hasMore: Boolean(lastPageToken)
+    });
+    const fileWarnings = [
+      ...warnings,
+      ...renderKeywordLimits(keywordLimits),
+      ...missingFieldWarningsFor(finalQuery, observedFields, totalRowsWritten),
+      // Only a CSV has a header to fall out of; json and jsonl files carry every row whole.
+      ...isCsvPath(args.out) ? unwrittenColumnWarnings(fileColumns, observedFields) : [],
+      ...conversionMixWarnings(finalQuery),
+      ...truncation
+    ];
+    emitToStderr(warningLines(fileWarnings, "csv"));
+    writeAdsJson(
+      buildFileSummary({
+        file: resolve(args.out),
+        rows: totalRowsWritten,
+        warnings: fileWarnings,
+        complete: truncation.length === 0
+      })
+    );
+    return;
+  }
+  if (useCache && allRows.length > 0) {
+    const fields2 = extractFields(allRows);
+    cacheSet("queries", cacheKey, allRows, getQueryTtl(finalQuery), getFieldDescriptions(fields2));
+  }
+  const fields = extractFields(allRows);
+  outputResults(
+    allRows,
+    getFieldDescriptions(fields),
+    [
+      ...warnings,
+      ...missingFieldWarnings(finalQuery, allRows),
+      ...keywordServingWarnings(allRows, servingOptions),
+      ...conversionMixWarnings(finalQuery)
+    ],
+    args,
+    false,
+    {
+      gaql: finalQuery,
+      effectiveLimit: effectiveRowLimit(finalQuery, limit, Boolean(args.all)),
+      all: Boolean(args.all),
+      nextCursor: lastPageToken
+    }
+  );
+}
+function shouldReadCache(args) {
+  return !args["no-cache"] && !args.out;
+}
+var DEFAULT_QUERY_LIMIT = 200;
+function parseQueryLimit(raw) {
+  if (raw === void 0 || raw === null || raw === "") return { ok: true, limit: DEFAULT_QUERY_LIMIT };
+  const limit = Number(raw);
+  if (Number.isInteger(limit) && limit >= 1 && limit <= GOOGLE_ADS_QUERY_MAX_PAGE_SIZE) return { ok: true, limit };
+  return {
+    ok: false,
+    error: {
+      ok: false,
+      error: {
+        code: "VALIDATION_ERROR",
+        message: `--limit must be a whole number from 1 to ${GOOGLE_ADS_QUERY_MAX_PAGE_SIZE}, got '${String(raw)}'.`,
+        fix: {
+          action: "retry_with_flag",
+          explanation: `One read returns at most ${GOOGLE_ADS_QUERY_MAX_PAGE_SIZE} rows. For more, split the read into narrower queries (a shorter BETWEEN range each, or one campaign each), write each with --out, and combine the files.`
+        },
+        retryable: false
+      }
+    }
+  };
+}
+async function validateArgs(args) {
+  const parsedLimit = parseQueryLimit(args.limit);
+  if (!parsedLimit.ok) {
+    writeAdsJson(parsedLimit.error);
+    process.exit(1);
+  }
+  const { limit } = parsedLimit;
+  const customerId = await resolveCustomerId(args);
+  const gaql = resolveGaql(args, limit);
+  if (!gaql) {
+    process.exit(1);
+  }
+  const preflight = validatePreflight(gaql, customerId, limit);
+  if (!preflight.valid && preflight.error) {
+    writeAdsJson(preflight.error);
+    process.exit(1);
+  }
+  const finalQuery = preflight.correctedQuery ?? gaql;
+  return {
+    customerId,
+    limit,
+    finalQuery,
+    warnings: [...preflight.warnings, ...servingScopeWarnings(args, finalQuery)],
+    useCache: !args["no-cache"],
+    cacheKey: buildQueryCacheKey(customerId, finalQuery)
+  };
+}
+function handleQueryError(err, finalQuery, customerId) {
+  if (err instanceof ApiError) {
+    const envelope = parseApiError(err.message, finalQuery, customerId, err.code);
+    envelope.error.gaqlExecuted = finalQuery;
+    writeAdsJson(envelope);
+    process.exit(1);
+  }
+  writeAdsJson({
+    ok: false,
+    error: {
+      code: "NETWORK_ERROR",
+      message: err instanceof Error ? err.message : "Unexpected error",
+      fix: { action: "wait_and_retry", explanation: "Network error \u2014 check connectivity and retry" },
+      retryable: true,
+      gaqlExecuted: finalQuery
+    }
+  });
+  process.exit(1);
+}
+var queryCommand = defineCommand({
+  meta: {
+    name: "query",
+    description: `Run GAQL queries against Google Ads. Supports raw GAQL, presets, pagination, file export, and caching.
+
+Examples:
+  baker ads google query "SELECT campaign.name, metrics.clicks FROM campaign WHERE segments.date DURING LAST_7_DAYS" --customer-id 1234567890
+  baker ads google query --preset campaign-performance --customer-id 1234567890
+  baker ads google query --preset search-terms --customer-id 1234567890 --date-range LAST_7_DAYS --out results.csv
+  baker ads google query --list-presets`
+  },
+  args: {
+    query: { type: "positional", description: "GAQL query string", required: false },
+    "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 in one page (default 200); without --all the read stops there",
+      required: false
+    },
+    "list-presets": { type: "boolean", description: "List available presets", required: false },
+    cursor: { type: "string", description: "Pagination cursor", required: false },
+    all: { type: "boolean", description: "Follow every page (use with --out for large datasets)", required: false },
+    out: { type: "string", description: "File path for output", required: false },
+    append: { type: "boolean", description: "Append to file", required: false },
+    output: { type: "string", description: "Format: json|csv|jsonl|md", required: false, default: "json" },
+    "no-cache": { type: "boolean", description: "Skip cache", required: false },
+    full: { type: "boolean", description: "Include the field description glossary", required: false }
+  },
+  run: async ({ args }) => {
+    if (args["list-presets"]) {
+      writeAdsJson({
+        ok: true,
+        data: PRESETS.map((p) => ({
+          name: p.name,
+          description: p.description,
+          defaultDateRange: p.defaultDateRange,
+          servingOnly: (p.statusFields?.length ?? 0) > 0,
+          gaql: expandPreset(p, {}).query
+        }))
+      });
+      return;
+    }
+    const validated = await validateArgs(args);
+    if (!validated) return;
+    const { customerId, limit, finalQuery, warnings, useCache, cacheKey } = validated;
+    if (shouldReadCache(args)) {
+      const cached = cacheGet("queries", cacheKey);
+      if (cached) {
+        const fields = extractFields(cached.data);
+        outputResults(
+          cached.data,
+          cached.fields ?? getFieldDescriptions(fields),
+          [
+            ...warnings,
+            ...missingFieldWarnings(finalQuery, cached.data),
+            ...keywordServingWarnings(cached.data, keywordServingOptions(finalQuery)),
+            ...conversionMixWarnings(finalQuery)
+          ],
+          args,
+          true,
+          {
+            gaql: finalQuery,
+            effectiveLimit: effectiveRowLimit(finalQuery, limit, Boolean(args.all)),
+            all: Boolean(args.all)
+          }
+        );
+        return;
+      }
+    }
+    try {
+      await executeQuery(finalQuery, args, customerId, limit, warnings, useCache, cacheKey);
+    } catch (err) {
+      handleQueryError(err, finalQuery, customerId);
+    }
+  }
+});
+export {
+  buildFileSummary,
+  buildQueryEnvelope,
+  completenessWarnings,
+  effectiveRowLimit,
+  keywordServingOptions,
+  missingFieldWarnings,
+  missingFieldWarningsFor,
+  outputResults,
+  parseQueryLimit,
+  parseSelectedFields,
+  queryCommand,
+  resultColumns,
+  servingScopeWarnings,
+  shouldReadCache,
+  summariseWarnings,
+  unobservedFields,
+  unobservedSelectedFields,
+  unwrittenColumnWarnings,
+  warningLines
+};
+//# sourceMappingURL=query-3YAOEQVH.js.map