@koda-sl/baker-cli 0.494.0 → 0.495.0-dev.6b9c22aff

package/dist/chunk-SHBFBQYT.js

@@ -0,0 +1,846 @@
+import {
+  CHANGE_SCOPES,
+  CHANGE_SCOPE_MAX_DAYS,
+  DEFAULT_CHANGE_DAYS,
+  isChangeLookbackWithinReach
+} from "./chunk-V57TZQPI.js";
+import {
+  connectionFixExplanation,
+  isNotConnectedError
+} from "./chunk-2VIZ4UUZ.js";
+
+// src/commands/ads/google/during-literals.ts
+var GAQL_DURING_LITERALS = [
+  "TODAY",
+  "YESTERDAY",
+  "LAST_7_DAYS",
+  "LAST_14_DAYS",
+  "LAST_30_DAYS",
+  "LAST_BUSINESS_WEEK",
+  "THIS_MONTH",
+  "LAST_MONTH",
+  "THIS_WEEK_SUN_TODAY",
+  "THIS_WEEK_MON_TODAY",
+  "LAST_WEEK_SUN_SAT",
+  "LAST_WEEK_MON_SUN"
+];
+function isDuringLiteral(value) {
+  return GAQL_DURING_LITERALS.includes(value.toUpperCase());
+}
+function isoDay(date) {
+  return date.toISOString().slice(0, 10);
+}
+function utcDate(year, month, day) {
+  return new Date(Date.UTC(year, month, day));
+}
+function monthsBefore(date, months) {
+  const lastDayOfTarget = utcDate(date.getUTCFullYear(), date.getUTCMonth() - months + 1, 0).getUTCDate();
+  return utcDate(date.getUTCFullYear(), date.getUTCMonth() - months, Math.min(date.getUTCDate(), lastDayOfTarget));
+}
+function equivalentBetween(literal, now) {
+  const upper = literal.toUpperCase();
+  const today = utcDate(now.getUTCFullYear(), now.getUTCMonth(), now.getUTCDate());
+  const yesterday = utcDate(today.getUTCFullYear(), today.getUTCMonth(), today.getUTCDate() - 1);
+  const range = (from, to) => `BETWEEN '${isoDay(from)}' AND '${isoDay(to)}'`;
+  const year = today.getUTCFullYear();
+  const quarterStart = Math.floor(today.getUTCMonth() / 3) * 3;
+  const rolling = upper.match(/^LAST_(\d+)_(DAYS|WEEKS|MONTHS|YEARS)$/);
+  if (rolling) {
+    const n = Number(rolling[1]);
+    const unit = rolling[2];
+    if (n < 1) return null;
+    if (unit === "DAYS" || unit === "WEEKS") {
+      const days = unit === "DAYS" ? n : n * 7;
+      return range(utcDate(year, today.getUTCMonth(), today.getUTCDate() - days), yesterday);
+    }
+    const months = unit === "MONTHS" ? n : n * 12;
+    return range(monthsBefore(today, months), yesterday);
+  }
+  switch (upper) {
+    case "THIS_YEAR":
+      return range(utcDate(year, 0, 1), today);
+    case "LAST_YEAR":
+      return range(utcDate(year - 1, 0, 1), utcDate(year - 1, 11, 31));
+    case "THIS_QUARTER":
+      return range(utcDate(year, quarterStart, 1), today);
+    case "LAST_QUARTER":
+      return range(utcDate(year, quarterStart - 3, 1), utcDate(year, quarterStart, 0));
+    default:
+      return null;
+  }
+}
+function duringLiteralExplanation(literal, between) {
+  const accepted = GAQL_DURING_LITERALS.join(", ");
+  const lead = between ? `Google does not accept ${literal} after DURING. The same window as explicit dates is ${between}.` : `Google does not accept ${literal} after DURING, and it names no fixed window \u2014 use BETWEEN 'YYYY-MM-DD' AND 'YYYY-MM-DD', or drop the date filter.`;
+  return `${lead} DURING accepts only: ${accepted}. Any other window needs BETWEEN.`;
+}
+
+// src/commands/ads/google/changes-window.ts
+function monthlySpendTrendQuery(now = /* @__PURE__ */ new Date()) {
+  return `SELECT campaign.name, segments.month, metrics.cost_micros, metrics.conversions FROM campaign WHERE segments.date ${equivalentBetween("LAST_12_MONTHS", now)}`;
+}
+function isChangeScope(value) {
+  return CHANGE_SCOPES.includes(value);
+}
+function resolveChangesWindow(input) {
+  const scope = input.scope ?? "detail";
+  if (!isChangeScope(scope)) {
+    return {
+      ok: false,
+      error: {
+        code: "INVALID_SCOPE",
+        message: `Unknown scope '${scope}'. Use 'detail' (field-level changes, 30 days) or 'summary' (which resources changed, 90 days).`,
+        fix: {
+          action: "retry_with_flag",
+          explanation: "Pass --scope detail or --scope summary."
+        }
+      }
+    };
+  }
+  const days = input.days ?? DEFAULT_CHANGE_DAYS;
+  if (!Number.isInteger(days) || days < 1) {
+    return {
+      ok: false,
+      error: {
+        code: "INVALID_LOOKBACK",
+        message: `--days must be a whole number of days, got '${days}'.`,
+        fix: {
+          action: "retry_with_flag",
+          explanation: `Pass --days as a positive integer, e.g. --days ${DEFAULT_CHANGE_DAYS}.`
+        }
+      }
+    };
+  }
+  if (!isChangeLookbackWithinReach(days, scope)) {
+    return { ok: false, error: lookbackTooLong(scope, days, CHANGE_SCOPE_MAX_DAYS[scope]) };
+  }
+  return { ok: true, scope, days, hints: hintsFor(scope, days) };
+}
+function lookbackTooLong(scope, days, max) {
+  if (scope === "detail" && days <= CHANGE_SCOPE_MAX_DAYS.summary) {
+    return {
+      code: "LOOKBACK_TOO_LONG",
+      message: `Google keeps field-level change detail for ${max} days only; ${days} days is outside that window.`,
+      fix: {
+        action: "narrow_date_range",
+        explanation: `Re-run with --scope summary --days ${days} to reach back ${CHANGE_SCOPE_MAX_DAYS.summary} days. Summary tells you which campaigns, ad groups, ads and criteria changed and when, but not the old and new values \u2014 read the resource itself for current values.`
+      }
+    };
+  }
+  return {
+    code: "LOOKBACK_TOO_LONG",
+    message: `Google's account history API reaches back ${CHANGE_SCOPE_MAX_DAYS.summary} days at most; ${days} days is outside that window.`,
+    fix: {
+      action: "use_different_resource",
+      explanation: `Do not abort \u2014 infer the change from performance instead. Query monthly metrics per campaign (${monthlySpendTrendQuery()}) to see which campaigns stopped or started spending. That shows what changed and when, though not who changed it. Older history exists only in the Google Ads web UI, which has no API \u2014 ask the user to check it if the 'who' matters.`
+    }
+  };
+}
+function hintsFor(scope, days) {
+  const hints = [];
+  if (scope === "detail") {
+    hints.push(
+      `Detailed history covers the last ${CHANGE_SCOPE_MAX_DAYS.detail} days. For anything older use --scope summary (reaches ${CHANGE_SCOPE_MAX_DAYS.summary} days, reports which resources changed but not their values).`
+    );
+  } else {
+    hints.push(
+      "Summary history reports which resources changed and when, not old and new values. To see what a changed resource looks like now, query it by resource_name."
+    );
+    if (days > CHANGE_SCOPE_MAX_DAYS.detail) {
+      hints.push(
+        `Changes inside the last ${CHANGE_SCOPE_MAX_DAYS.detail} days also have field-level detail \u2014 re-run with --scope detail for those.`
+      );
+    }
+  }
+  return hints;
+}
+
+// src/commands/ads/google/list-fields.ts
+var LIST_FIELDS = /* @__PURE__ */ new Set([
+  "ad.final_mobile_urls",
+  "ad.final_urls",
+  "ad_group.excluded_parent_asset_field_types",
+  "ad_group.excluded_parent_asset_set_types",
+  "ad_group.labels",
+  "ad_group.primary_status_reasons",
+  "ad_group_ad.ad.final_mobile_urls",
+  "ad_group_ad.ad.final_urls",
+  "ad_group_ad.labels",
+  "ad_group_ad.primary_status_reasons",
+  "ad_group_asset.primary_status_reasons",
+  "ad_group_criterion.disapproval_reasons",
+  "ad_group_criterion.final_mobile_urls",
+  "ad_group_criterion.final_urls",
+  "ad_group_criterion.labels",
+  "ad_group_criterion.primary_status_reasons",
+  "ad_group_criterion.topic.path",
+  "ad_group_criterion.webpage.sample.sample_urls",
+  "asset.dynamic_custom_asset.contextual_keywords",
+  "asset.dynamic_custom_asset.similar_ids",
+  "asset.dynamic_education_asset.contextual_keywords",
+  "asset.dynamic_education_asset.similar_program_ids",
+  "asset.dynamic_flights_asset.similar_destination_ids",
+  "asset.dynamic_hotels_and_rentals_asset.contextual_keywords",
+  "asset.dynamic_hotels_and_rentals_asset.similar_property_ids",
+  "asset.dynamic_jobs_asset.contextual_keywords",
+  "asset.dynamic_jobs_asset.similar_job_ids",
+  "asset.dynamic_local_asset.contextual_keywords",
+  "asset.dynamic_local_asset.similar_deal_ids",
+  "asset.dynamic_real_estate_asset.contextual_keywords",
+  "asset.dynamic_real_estate_asset.similar_listing_ids",
+  "asset.dynamic_travel_asset.contextual_keywords",
+  "asset.dynamic_travel_asset.similar_destination_ids",
+  "asset.final_mobile_urls",
+  "asset.final_urls",
+  "asset.page_feed_asset.labels",
+  "asset.structured_snippet_asset.values",
+  "asset_group.final_mobile_urls",
+  "asset_group.final_urls",
+  "asset_group.primary_status_reasons",
+  "asset_group_asset.primary_status_reasons",
+  "asset_group_signal.disapproval_reasons",
+  "asset_set.business_profile_location_group.dynamic_business_profile_location_group_filter.label_filters",
+  "asset_set.business_profile_location_group.dynamic_business_profile_location_group_filter.listing_id_filters",
+  "asset_set.location_set.business_profile_location_set.label_filters",
+  "asset_set.location_set.business_profile_location_set.listing_id_filters",
+  "bidding_data_exclusion.advertising_channel_types",
+  "bidding_data_exclusion.campaigns",
+  "bidding_data_exclusion.devices",
+  "bidding_seasonality_adjustment.advertising_channel_types",
+  "bidding_seasonality_adjustment.campaigns",
+  "bidding_seasonality_adjustment.devices",
+  "campaign.excluded_parent_asset_field_types",
+  "campaign.excluded_parent_asset_set_types",
+  "campaign.feed_types",
+  "campaign.labels",
+  "campaign.optimization_goal_setting.optimization_goal_types",
+  "campaign.primary_status_reasons",
+  "campaign.selective_optimization.conversion_actions",
+  "campaign.shopping_setting.advertising_partner_ids",
+  "campaign.text_guidelines.term_exclusions",
+  "campaign_asset.primary_status_reasons",
+  "campaign_criterion.location_group.geo_target_constants",
+  "campaign_criterion.topic.path",
+  "campaign_criterion.webpage.sample.sample_urls",
+  "conversion_value_rule.audience_condition.user_interests",
+  "conversion_value_rule.audience_condition.user_lists",
+  "conversion_value_rule.device_condition.device_types",
+  "conversion_value_rule.geo_location_condition.excluded_geo_target_constants",
+  "conversion_value_rule.geo_location_condition.geo_target_constants",
+  "conversion_value_rule_set.conversion_value_rules",
+  "conversion_value_rule_set.dimensions",
+  "custom_conversion_goal.conversion_actions",
+  "customer.pay_per_conversion_eligibility_failure_reasons",
+  "customer_asset.primary_status_reasons",
+  "customer_client.applied_labels",
+  "experiment_arm.campaigns",
+  "experiment_arm.in_design_campaigns",
+  "keyword_plan_campaign.language_constants",
+  "lift_measurement_config.campaigns",
+  "lift_measurement_config.conversion_actions",
+  "lift_measurement_config.single_measurement_question_set.competitor_choices",
+  "lift_measurement_config.single_measurement_question_set.question_measurements",
+  "local_services_employee.category_ids",
+  "local_services_employee.languages_spoken",
+  "metrics.interaction_event_types",
+  "recommendation.campaigns",
+  "shared_criterion.webpage.sample.sample_urls",
+  "shopping_product.target_countries",
+  "topic_constant.path",
+  "user_list.lookalike_user_list.country_codes",
+  "user_list.lookalike_user_list.seed_user_list_ids"
+]);
+var LIST_FIELD_OPERATORS = "CONTAINS ALL, CONTAINS ANY, CONTAINS NONE";
+function listFieldGuidance(field) {
+  return `${field} is a list field: it takes only ${LIST_FIELD_OPERATORS} \u2014 no comparison (=, !=, IN), pattern match or null test. To find rows that have it, drop that condition, keep ${field} in SELECT and filter the rows (rows without it omit the key); to match values, use ${field} CONTAINS ANY ('value')`;
+}
+
+// src/commands/ads/google/correction-table.ts
+function buildCommand(query, ctx) {
+  return `baker ads google query "${query}" --customer-id ${ctx.customerId}`;
+}
+var CORRECTION_RULES = [
+  // 0. EXPECTED_REFERENCED_FIELD_IN_SELECT_CLAUSE — some resources (e.g. campaign_budget)
+  // require fields filtered in WHERE to also be selected. The error names the exact field,
+  // so add it to SELECT and retry. Kept first: field-specific rules below must not shadow
+  // this with an unrelated rewrite when the named field happens to match their pattern.
+  {
+    matchApiError: /must be present in SELECT clause:\s*'([\w.]+)'/i,
+    fix: (ctx) => {
+      const field = ctx.apiErrorMessage?.match(/must be present in SELECT clause:\s*'([\w.]+)'/i)?.[1];
+      if (!field) {
+        return {
+          action: "add_required_field",
+          explanation: "Add the field named in the error to the SELECT clause and retry"
+        };
+      }
+      const corrected = ctx.originalQuery.replace(/SELECT\s+/i, `SELECT ${field}, `);
+      return {
+        action: "add_required_field",
+        correctedCommand: buildCommand(corrected, ctx),
+        explanation: `${field} is used in WHERE but this resource requires it in SELECT too \u2014 added it`
+      };
+    }
+  },
+  // 0b. OPERATOR_FIELD_MISMATCH — the field refuses this operator, and Google names the
+  // ones it takes. Kept ahead of the field-specific rules for the same reason as rule 0.
+  // A repeated field (final_urls, labels, …) takes only CONTAINS ALL/ANY/NONE, so it has
+  // no null test at all: read it unfiltered and filter the rows instead.
+  {
+    matchApiError: /OPERATOR_FIELD_MISMATCH|is not a valid operator to use with/i,
+    fix: (ctx) => {
+      const message = ctx.apiErrorMessage ?? "";
+      const field = message.match(/valid operator to use with '([\w.]+)'/i)?.[1] ?? "this field";
+      const operator = message.match(/([A-Z=!<>][A-Z_ =!<>]*?) is not a valid operator/)?.[1]?.trim();
+      const valid = message.match(/Valid operators: (.+?)\.?(?:"|$)/i)?.[1]?.trim();
+      const refused = operator ? `${operator} cannot be used on ${field}` : `${field} does not take that operator`;
+      const allowed = valid ? `; its valid operators are ${valid}` : "";
+      const repeated = valid?.split(",").every((op) => /^CONTAINS (ALL|ANY|NONE)$/i.test(op.trim())) ?? false;
+      const guidance = repeated ? `. ${listFieldGuidance(field)}` : ". Rewrite that condition with one of them, or drop it and filter the rows";
+      return {
+        action: "change_operator",
+        explanation: `${refused}${allowed}${guidance}`
+      };
+    }
+  },
+  // 1. bare keyword.text → ad_group_criterion.keyword.text (leaves <resource>.keyword.text untouched)
+  {
+    matchQuery: /(?<![\w.])keyword\.text\b/,
+    matchApiError: /keyword\.text/i,
+    fix: (ctx) => {
+      const corrected = ctx.originalQuery.replace(/(?<![\w.])keyword\.text\b/g, "ad_group_criterion.keyword.text");
+      return {
+        action: "retry_with_modified_query",
+        correctedCommand: buildCommand(corrected, ctx),
+        explanation: "Use ad_group_criterion.keyword.text \u2014 keywords are accessed through the criterion resource"
+      };
+    }
+  },
+  // 2. bare keyword.match_type → ad_group_criterion.keyword.match_type (leaves <resource>.keyword.match_type untouched)
+  {
+    matchQuery: /(?<![\w.])keyword\.match_type\b/,
+    matchApiError: /keyword\.match_type/i,
+    fix: (ctx) => {
+      const corrected = ctx.originalQuery.replace(
+        /(?<![\w.])keyword\.match_type\b/g,
+        "ad_group_criterion.keyword.match_type"
+      );
+      return {
+        action: "retry_with_modified_query",
+        correctedCommand: buildCommand(corrected, ctx),
+        explanation: "Use ad_group_criterion.keyword.match_type for keyword match type"
+      };
+    }
+  },
+  // 3. campaign_budget.* queried FROM campaign
+  {
+    matchQuery: /campaign_budget\.\w+.*FROM\s+campaign\b/i,
+    matchApiError: /campaign_budget.*not.*valid.*campaign|cannot.*select.*campaign_budget/i,
+    fix: (ctx) => {
+      const corrected = ctx.originalQuery.replace(/FROM\s+campaign\b/i, "FROM campaign_budget");
+      return {
+        action: "use_different_resource",
+        correctedCommand: buildCommand(corrected, ctx),
+        explanation: "campaign_budget fields must be queried FROM campaign_budget, not FROM campaign"
+      };
+    }
+  },
+  // 4. CONTAINS → LIKE. Keyed on the query alone: Google's error envelope ("Request contains an
+  // invalid argument … Valid operators: CONTAINS ANY") matches any loose error pattern, and this
+  // advice only makes sense when the query actually wrote CONTAINS(…).
+  {
+    matchQuery: /CONTAINS\s*\(/i,
+    fix: (ctx) => {
+      const match = ctx.originalQuery.match(/CONTAINS\s*\(\s*([^,]+),\s*'([^']+)'\s*\)/i);
+      if (match) {
+        const field = match[1]?.trim();
+        const value = match[2] ?? "";
+        const corrected = ctx.originalQuery.replace(
+          /CONTAINS\s*\(\s*[^,]+,\s*'[^']+'\s*\)/i,
+          `${field} LIKE '%${value}%'`
+        );
+        return {
+          action: "change_operator",
+          correctedCommand: buildCommand(corrected, ctx),
+          explanation: "GAQL uses LIKE '%value%' for substring matching, not CONTAINS()"
+        };
+      }
+      return {
+        action: "change_operator",
+        explanation: "Replace CONTAINS(field, 'value') with field LIKE '%value%'"
+      };
+    }
+  },
+  // 5. ad_group_criterion query without negative filter — auto-add the field
+  {
+    matchQuery: /FROM\s+ad_group_criterion\b(?!.*ad_group_criterion\.negative)/i,
+    fix: (ctx) => {
+      const corrected = ctx.originalQuery.replace(/SELECT\s+/i, "SELECT ad_group_criterion.negative, ");
+      return {
+        action: "add_required_field",
+        correctedCommand: buildCommand(corrected, ctx),
+        explanation: "Added ad_group_criterion.negative to distinguish positive (targeting) from negative (blocking) keywords. Filter with WHERE ad_group_criterion.negative = FALSE for positives only."
+      };
+    }
+  },
+  // 6. Missing campaign.id in ad_group queries
+  {
+    matchQuery: /FROM\s+ad_group\b/i,
+    matchApiError: /campaign\.id.*required|must.*include.*campaign\.id/i,
+    fix: (ctx) => {
+      const corrected = ctx.originalQuery.replace(/SELECT\s+/i, "SELECT campaign.id, ");
+      return {
+        action: "add_required_field",
+        correctedCommand: buildCommand(corrected, ctx),
+        explanation: "Ad group queries require campaign.id in SELECT for parent context"
+      };
+    }
+  },
+  // 6. Missing campaign.id in keyword_view queries
+  {
+    matchQuery: /FROM\s+keyword_view\b/i,
+    matchApiError: /campaign\.id.*required.*keyword/i,
+    fix: (ctx) => {
+      const corrected = ctx.originalQuery.replace(/SELECT\s+/i, "SELECT campaign.id, ");
+      return {
+        action: "add_required_field",
+        correctedCommand: buildCommand(corrected, ctx),
+        explanation: "Keyword view queries require campaign.id in SELECT"
+      };
+    }
+  },
+  // 7. shopping_performance_view.product_* → segments.product_*
+  {
+    matchQuery: /shopping_performance_view\.product_\w+/,
+    matchApiError: /shopping_performance_view\.product/i,
+    fix: (ctx) => {
+      const corrected = ctx.originalQuery.replace(/shopping_performance_view\.product_(\w+)/g, "segments.product_$1");
+      return {
+        action: "retry_with_modified_query",
+        correctedCommand: buildCommand(corrected, ctx),
+        explanation: "Product fields are segments (segments.product_*), not fields on shopping_performance_view"
+      };
+    }
+  },
+  // 8. Open-ended date range
+  {
+    matchQuery: /segments\.date\s*>=\s*'(\d{4}-\d{2}-\d{2})'/i,
+    matchApiError: /date.*range.*must.*finite|open.*ended/i,
+    fix: (ctx) => {
+      const match = ctx.originalQuery.match(/segments\.date\s*>=\s*'(\d{4}-\d{2}-\d{2})'/i);
+      const startDate = match?.[1] ?? "2024-01-01";
+      const today = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
+      const corrected = ctx.originalQuery.replace(
+        /segments\.date\s*>=\s*'(\d{4}-\d{2}-\d{2})'/i,
+        `segments.date BETWEEN '${startDate}' AND '${today}'`
+      );
+      return {
+        action: "narrow_date_range",
+        correctedCommand: buildCommand(corrected, ctx),
+        explanation: "Use BETWEEN with explicit end date \u2014 open-ended ranges are not supported"
+      };
+    }
+  },
+  // 10a. Customer not found (wrong customer ID)
+  {
+    matchApiError: /CUSTOMER_NOT_FOUND|not.*found.*customer/i,
+    fix: () => ({
+      action: "reject",
+      explanation: "Customer ID not found. Run 'baker ads google accounts' to list valid customer IDs, then retry with a valid --customer-id."
+    })
+  },
+  // 10b. Not accessible / login-customer-id required
+  {
+    matchApiError: /not.*accessible|login.customer.id/i,
+    fix: (ctx) => ({
+      action: "reject",
+      correctedCommand: buildCommand(ctx.originalQuery, ctx),
+      explanation: "Account not accessible \u2014 may need a manager (MCC) login-customer-id. Run 'baker ads google accounts' to refresh the accounts cache, then retry."
+    })
+  },
+  // 11. Campaign type by name matching
+  {
+    matchQuery: /campaign\.name\s*LIKE\s*'%\s*(shopping|pmax|search|display|video)\s*%'/i,
+    fix: (ctx) => {
+      const match = ctx.originalQuery.match(/campaign\.name\s*LIKE\s*'%\s*(shopping|pmax|search|display|video)\s*%'/i);
+      const typeMap = {
+        shopping: "SHOPPING",
+        pmax: "PERFORMANCE_MAX",
+        search: "SEARCH",
+        display: "DISPLAY",
+        video: "VIDEO"
+      };
+      const channelType = typeMap[match?.[1]?.toLowerCase() ?? ""] ?? "SEARCH";
+      const corrected = ctx.originalQuery.replace(
+        /campaign\.name\s*LIKE\s*'%[^']*%'/i,
+        `campaign.advertising_channel_type = '${channelType}'`
+      );
+      return {
+        action: "retry_with_modified_query",
+        correctedCommand: buildCommand(corrected, ctx),
+        explanation: "Filter by campaign.advertising_channel_type enum, not by name pattern"
+      };
+    }
+  },
+  // 12. Incompatible fields
+  {
+    matchApiError: /incompatible|mutually.*exclusive|cannot.*select.*together/i,
+    fix: () => ({
+      action: "split_query",
+      explanation: "These fields cannot be in the same query \u2014 split into separate queries and join client-side"
+    })
+  },
+  // 13. campaign.status = 'ACTIVE' → 'ENABLED'
+  {
+    matchQuery: /campaign\.status\s*=\s*'ACTIVE'/i,
+    fix: (ctx) => {
+      const corrected = ctx.originalQuery.replace(/campaign\.status\s*=\s*'ACTIVE'/gi, "campaign.status = 'ENABLED'");
+      return {
+        action: "retry_with_modified_query",
+        correctedCommand: buildCommand(corrected, ctx),
+        explanation: "Campaign status uses ENABLED, not ACTIVE"
+      };
+    }
+  },
+  // 14. ad_group.status = 'ACTIVE' → 'ENABLED'
+  {
+    matchQuery: /ad_group\.status\s*=\s*'ACTIVE'/i,
+    fix: (ctx) => {
+      const corrected = ctx.originalQuery.replace(/ad_group\.status\s*=\s*'ACTIVE'/gi, "ad_group.status = 'ENABLED'");
+      return {
+        action: "retry_with_modified_query",
+        correctedCommand: buildCommand(corrected, ctx),
+        explanation: "Ad group status uses ENABLED, not ACTIVE"
+      };
+    }
+  },
+  // 15. ad.final_urls → ad_group_ad.ad.final_urls
+  {
+    matchQuery: /\bad\.final_urls\b(?!.*ad_group_ad)/,
+    matchApiError: /ad\.final_urls/i,
+    fix: (ctx) => {
+      const corrected = ctx.originalQuery.replace(/\bad\.final_urls\b/g, "ad_group_ad.ad.final_urls");
+      return {
+        action: "retry_with_modified_query",
+        correctedCommand: buildCommand(corrected, ctx),
+        explanation: "Use the full path: ad_group_ad.ad.final_urls"
+      };
+    }
+  },
+  // 15b. asset.<type>_asset.final_urls → asset.final_urls (final URLs live on the asset
+  // itself; the typed sub-message only carries type-specific fields like link_text)
+  {
+    matchQuery: /asset\.\w+_asset\.final_(mobile_)?urls\b/,
+    matchApiError: /asset\.\w+_asset\.final_(mobile_)?urls/i,
+    fix: (ctx) => {
+      const corrected = ctx.originalQuery.replace(/asset\.\w+_asset\.final_(mobile_)?urls\b/g, "asset.final_$1urls");
+      return {
+        action: "retry_with_modified_query",
+        correctedCommand: buildCommand(corrected, ctx),
+        explanation: "Final URLs are on the asset itself \u2014 use asset.final_urls, not asset.<type>_asset.final_urls"
+      };
+    }
+  },
+  // 16. Rate limit / quota
+  {
+    matchApiError: /RESOURCE_EXHAUSTED|quota.*exceeded|rate.*limit/i,
+    fix: () => ({
+      action: "wait_and_retry",
+      explanation: "API quota exceeded \u2014 wait 30 seconds before retrying"
+    })
+  },
+  // 17. WHERE on metrics
+  {
+    matchApiError: /cannot.*filter.*metric|WHERE.*metrics|prohibited.*where/i,
+    fix: () => ({
+      action: "reject",
+      explanation: "Cannot filter on metrics in WHERE clause \u2014 remove the metrics filter and filter results client-side"
+    })
+  },
+  // 18. ORDER BY field not in SELECT
+  {
+    matchApiError: /order.*by.*field.*not.*selected|must.*select.*field.*order/i,
+    fix: (ctx) => {
+      const orderMatch = ctx.originalQuery.match(/ORDER\s+BY\s+([\w.]+)/i);
+      const field = orderMatch?.[1] ?? "field";
+      const corrected = ctx.originalQuery.replace(/SELECT\s+/i, `SELECT ${field}, `);
+      return {
+        action: "add_required_field",
+        correctedCommand: buildCommand(corrected, ctx),
+        explanation: `Add ${field} to SELECT \u2014 ORDER BY fields must be selected`
+      };
+    }
+  },
+  // The change-history rules must stay ahead of rule 19: its `status.*filter`
+  // pattern also matches Google's change_status errors ("the change_status request
+  // is missing filters on ..."), and the first matching rule wins.
+  // 18a. change_event past its 30-day reach → change_status, which reaches 90 days.
+  // These three rules match on the error code only, never on the resource in the query.
+  // A `matchQuery` here would also fire in the query-pattern pass — the fallback used
+  // when no rule recognised the error — and answer every unrelated failure on a history
+  // query with "switch resources", which is never the real fix. The backend forwards the
+  // code as JSON (`"changeEventError":"START_DATE_TOO_OLD"`), so match that shape as well
+  // as the dotted enum spelling.
+  {
+    matchApiError: /changeEventError\W{0,4}START_DATE_TOO_OLD/i,
+    fix: (ctx) => {
+      const limit = ctx.originalQuery.match(/LIMIT\s+(\d+)/i)?.[1] ?? "50";
+      const requested = ctx.originalQuery.match(/change_date_time\s*>=\s*'([^']+)'/i)?.[1]?.slice(0, 10);
+      const oldestStart = new Date(Date.now() - 89 * 24 * 60 * 60 * 1e3).toISOString().slice(0, 10);
+      const start = requested && requested > oldestStart ? requested : oldestStart;
+      const corrected = `SELECT change_status.last_change_date_time, change_status.resource_type, change_status.resource_status, change_status.resource_name, change_status.campaign, change_status.ad_group FROM change_status WHERE change_status.last_change_date_time >= '${start}' ORDER BY change_status.last_change_date_time DESC LIMIT ${limit}`;
+      return {
+        action: "use_different_resource",
+        correctedCommand: buildCommand(corrected, ctx),
+        explanation: `change_event only reaches back 30 days. change_status reaches 90 (from ${start}) but reports only which resources changed and whether they were added, changed or removed \u2014 no old/new values and no user email. Read a changed resource by its resource_name to see its current values.`
+      };
+    }
+  },
+  // 18b. Past 90 days no history resource reaches — infer the change from spend instead.
+  {
+    matchApiError: /changeStatusError\W{0,4}START_DATE_TOO_OLD/i,
+    fix: () => ({
+      action: "use_different_resource",
+      explanation: `Google's account history reaches back 90 days at most, and this query asks for more. Do not abort \u2014 infer the change from performance: ${monthlySpendTrendQuery()} shows which campaigns started or stopped spending and when, though not who changed them. Anything older with attribution exists only in the Google Ads web UI, which has no API.`
+    })
+  },
+  // 18c. change_status rejects a date range it cannot bound. Google raises this both for
+  // a half-open range and for no date filter at all, so supply whichever end is missing.
+  {
+    matchApiError: /CHANGE_DATE_RANGE_INFINITE/i,
+    fix: (ctx) => {
+      const today = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
+      const oldestStart = new Date(Date.now() - 89 * 24 * 60 * 60 * 1e3).toISOString().slice(0, 10);
+      const hasLowerBound = /last_change_date_time\s*>=?/i.test(ctx.originalQuery);
+      const hasUpperBound = /last_change_date_time\s*<=?/i.test(ctx.originalQuery);
+      const bounds = [
+        ...hasLowerBound ? [] : [`change_status.last_change_date_time >= '${oldestStart}'`],
+        ...hasUpperBound ? [] : [`change_status.last_change_date_time <= '${today}'`]
+      ];
+      const hasWhere = /\bWHERE\b/i.test(ctx.originalQuery);
+      const clause = hasWhere ? ` AND ${bounds.join(" AND ")}` : ` WHERE ${bounds.join(" AND ")}`;
+      const corrected = /\s+(ORDER\s+BY|LIMIT)\b/i.test(ctx.originalQuery) ? ctx.originalQuery.replace(/(\s+)(ORDER\s+BY|LIMIT)\b/i, `${clause}$1$2`) : ctx.originalQuery.trimEnd() + clause;
+      return {
+        action: "add_required_field",
+        correctedCommand: buildCommand(corrected, ctx),
+        explanation: "change_status needs a date range bounded at both ends \u2014 added the missing bound(s) on last_change_date_time."
+      };
+    }
+  },
+  // 19. Results include REMOVED entities
+  {
+    matchApiError: /REMOVED.*entities|status.*filter/i,
+    fix: (ctx) => {
+      const resourceMatch = ctx.originalQuery.match(/FROM\s+(\w+)/i);
+      const resource = resourceMatch?.[1] ?? "campaign";
+      const hasWhere = /WHERE/i.test(ctx.originalQuery);
+      const suffix = hasWhere ? ` AND ${resource}.status != 'REMOVED'` : ` WHERE ${resource}.status != 'REMOVED'`;
+      const limitMatch = ctx.originalQuery.match(/(\s+LIMIT\s+\d+)/i);
+      let corrected;
+      if (limitMatch) {
+        corrected = ctx.originalQuery.replace(/(\s+LIMIT\s+\d+)/i, `${suffix}$1`);
+      } else {
+        corrected = ctx.originalQuery.trimEnd() + suffix;
+      }
+      return {
+        action: "retry_with_modified_query",
+        correctedCommand: buildCommand(corrected, ctx),
+        explanation: `Add status filter to exclude REMOVED ${resource}s`
+      };
+    }
+  },
+  // 20. change_event without date constraint
+  {
+    matchQuery: /FROM\s+change_event\b(?!.*change_date_time)/i,
+    matchApiError: /change_event.*date|date.*required.*change/i,
+    fix: (ctx) => {
+      const sevenDaysAgo = new Date(Date.now() - 7 * 24 * 60 * 60 * 1e3).toISOString().slice(0, 10);
+      const hasWhere = /WHERE/i.test(ctx.originalQuery);
+      const suffix = hasWhere ? ` AND change_event.change_date_time >= '${sevenDaysAgo}'` : ` WHERE change_event.change_date_time >= '${sevenDaysAgo}'`;
+      const corrected = ctx.originalQuery.trimEnd() + suffix;
+      return {
+        action: "add_required_field",
+        correctedCommand: buildCommand(corrected, ctx),
+        explanation: "change_event queries require a date constraint on change_date_time"
+      };
+    }
+  },
+  // 21. resource_name = 'customers/X/Y/Z' → resource.id = Z
+  {
+    matchQuery: /(\w+)\.resource_name\s*=\s*'customers\/\d+\/\w+\/(\d+)'/i,
+    fix: (ctx) => {
+      const match = ctx.originalQuery.match(/(\w+)\.resource_name\s*=\s*'customers\/\d+\/\w+\/(\d+)'/i);
+      const resource = match?.[1] ?? "campaign";
+      const id = match?.[2] ?? "ID";
+      const corrected = ctx.originalQuery.replace(
+        /(\w+)\.resource_name\s*=\s*'customers\/\d+\/\w+\/(\d+)'/i,
+        `${resource}.id = ${id}`
+      );
+      return {
+        action: "retry_with_modified_query",
+        correctedCommand: buildCommand(corrected, ctx),
+        explanation: `Simpler: use ${resource}.id = ${id} instead of resource_name path`
+      };
+    }
+  },
+  // 22. segments.click_type incompatibility
+  {
+    matchApiError: /click_type.*incompatible|cannot.*click_type/i,
+    fix: (ctx) => {
+      const corrected = ctx.originalQuery.replace(/,?\s*segments\.click_type/g, "");
+      return {
+        action: "split_query",
+        correctedCommand: buildCommand(corrected, ctx),
+        explanation: "segments.click_type is incompatible with other segments \u2014 remove it or query separately"
+      };
+    }
+  },
+  // 22b. A field this API version does not have (removed, renamed, or misspelled). The rules above
+  // rewrite the known renames; anything left is named back so the agent drops or replaces it —
+  // without this, "invalid argument … field" fell through to the bare-resource rule below.
+  {
+    matchApiError: /UNRECOGNIZED_FIELD|Unrecognized field in the query/i,
+    fix: (ctx) => {
+      const field = ctx.apiErrorMessage?.match(/Unrecognized field in the query:\s*\\?'([\w.]+)/i)?.[1];
+      return {
+        action: "retry_with_modified_query",
+        explanation: field ? `${field} does not exist in this Google Ads API version (removed, renamed or misspelled). Drop it, or find its replacement in Google's field reference for that resource.` : "A field in this query does not exist in this Google Ads API version. Drop it, or find its replacement in Google's field reference."
+      };
+    }
+  },
+  // 22c. A field that exists but cannot be SELECTed (only filtered on, or read through another resource).
+  {
+    matchApiError: /PROHIBITED_FIELD_IN_SELECT_CLAUSE|may not be used in SELECT clause/i,
+    fix: (ctx) => {
+      const field = ctx.apiErrorMessage?.match(/may not be used in SELECT clause:\s*\\?'([\w.]+)/i)?.[1];
+      return {
+        action: "retry_with_modified_query",
+        explanation: `${field ?? "A field in this query"} cannot be selected \u2014 Google allows it only in WHERE, or not at all on this resource. Drop it from SELECT.`
+      };
+    }
+  },
+  // 23. Bare resource in SELECT
+  {
+    matchApiError: /cannot.*select.*bare.*resource|invalid.*field/i,
+    fix: () => ({
+      action: "retry_with_modified_query",
+      explanation: "Cannot SELECT a bare resource name \u2014 use resource.id, resource.name, or resource.resource_name"
+    })
+  },
+  // 24. Authentication error
+  {
+    matchApiError: /unauthenticated|authentication.*required|invalid.*credentials/i,
+    fix: () => ({
+      action: "authenticate",
+      explanation: "Google Ads authentication failed \u2014 reconnect Google Ads in dashboard settings"
+    })
+  },
+  // 25. Timeout / deadline exceeded
+  {
+    matchApiError: /timeout|deadline.*exceeded|DEADLINE_EXCEEDED/i,
+    fix: (ctx) => ({
+      action: "retry_with_modified_query",
+      correctedCommand: buildCommand(ctx.originalQuery, ctx),
+      explanation: "Query timed out \u2014 narrow the date range, add more WHERE filters, or reduce LIMIT"
+    })
+  }
+];
+
+// src/commands/ads/google/error-parser.ts
+function mapErrorCode(message) {
+  if (/must be present in SELECT clause/i.test(message)) return "MISSING_SELECT_FIELD";
+  if (/field.*not.*found|unrecognized.*field|not.*valid.*field/i.test(message)) return "FIELD_NOT_FOUND";
+  if (/not.*valid.*resource|cannot.*select.*from/i.test(message)) return "WRONG_RESOURCE";
+  if (/operator|CONTAINS|LIKE/i.test(message)) return "INVALID_OPERATOR";
+  if (/CUSTOMER_NOT_FOUND/i.test(message)) return "CUSTOMER_NOT_FOUND";
+  if (/login.customer.id|not.*accessible/i.test(message)) return "MISSING_MANAGER_ID";
+  if (/incompatible|mutually.*exclusive|PROHIBITED_SEGMENT_WITH_METRIC/i.test(message)) return "INCOMPATIBLE_FIELDS";
+  if (/unauthenticated|authentication/i.test(message)) return "AUTH_ERROR";
+  if (/permission/i.test(message)) return "PERMISSION_DENIED";
+  if (/RESOURCE_EXHAUSTED|quota|rate.*limit/i.test(message)) return "QUOTA_EXCEEDED";
+  if (/timeout|DEADLINE_EXCEEDED/i.test(message)) return "TIMEOUT";
+  return "API_ERROR";
+}
+function isRetryable(code) {
+  return code === "QUOTA_EXCEEDED" || code === "TIMEOUT";
+}
+function getRetryDelay(code) {
+  if (code === "QUOTA_EXCEEDED") return 3e4;
+  if (code === "TIMEOUT") return 5e3;
+  return void 0;
+}
+function parseApiError(errorMessage, originalQuery, customerId, apiCode) {
+  const ctx = {
+    originalQuery,
+    customerId,
+    apiErrorMessage: errorMessage
+  };
+  if (apiCode && isNotConnectedError(apiCode, errorMessage)) {
+    return {
+      ok: false,
+      error: {
+        code: "NO_GOOGLE_ADS_CONNECTION",
+        message: errorMessage,
+        fix: { action: "request_connection", explanation: connectionFixExplanation("google_ads") },
+        retryable: false
+      }
+    };
+  }
+  for (const rule of CORRECTION_RULES) {
+    if (rule.matchApiError?.test(errorMessage)) {
+      const fix = rule.fix(ctx);
+      const code2 = mapErrorCode(errorMessage);
+      return {
+        ok: false,
+        error: {
+          code: code2,
+          message: errorMessage,
+          fix,
+          retryable: isRetryable(code2),
+          retryAfterMs: getRetryDelay(code2)
+        }
+      };
+    }
+  }
+  for (const rule of CORRECTION_RULES) {
+    if (rule.matchQuery?.test(originalQuery)) {
+      const fix = rule.fix(ctx);
+      const code2 = mapErrorCode(errorMessage);
+      return {
+        ok: false,
+        error: {
+          code: code2,
+          message: errorMessage,
+          fix,
+          retryable: isRetryable(code2),
+          retryAfterMs: getRetryDelay(code2)
+        }
+      };
+    }
+  }
+  const code = mapErrorCode(errorMessage);
+  return {
+    ok: false,
+    error: {
+      code,
+      message: errorMessage,
+      fix: {
+        action: "reject",
+        explanation: "Unrecognized error \u2014 verify query syntax against Google Ads GAQL reference"
+      },
+      retryable: isRetryable(code),
+      retryAfterMs: getRetryDelay(code)
+    }
+  };
+}
+
+export {
+  isDuringLiteral,
+  equivalentBetween,
+  duringLiteralExplanation,
+  LIST_FIELDS,
+  listFieldGuidance,
+  resolveChangesWindow,
+  parseApiError
+};
+//# sourceMappingURL=chunk-SHBFBQYT.js.map