@koda-sl/baker-cli 0.347.0 → 0.349.0-dev.c05788ee3

package/dist/cli.js

@@ -67,7 +67,7 @@ import {
   validateCanvasDeep,
   withoutCastName,
   ytDlpBlockSignal
-} from "./chunk-YBD3W4M7.js";
+} from "./chunk-CEFJ5YSG.js";
 import {
   csvOrJson,
   daysAgoIso,
@@ -1957,6 +1957,7 @@ var GOOGLE_ADS_LIMITS = {
     businessNameMax: 25
   }
 };
+var GOOGLE_ADS_QUERY_MAX_PAGE_SIZE = 8192;
 var KEYWORD_MATCH_TYPES = ["EXACT", "PHRASE", "BROAD"];
 var ADVERTISING_CHANNEL_TYPES = [
   "SEARCH",
@@ -9674,7 +9675,76 @@ function urlOptionsHints(report) {
   return hints2;
 }
 
+// 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 upper2 = 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 = upper2.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 (upper2) {
+    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);
 }
@@ -9728,7 +9798,7 @@ function lookbackTooLong(scope, days, max) {
     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 (SELECT campaign.name, segments.month, metrics.cost_micros, metrics.conversions FROM campaign WHERE segments.date DURING LAST_12_MONTHS) 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."
+      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.`
     }
   };
 }
@@ -9778,6 +9848,27 @@ var CORRECTION_RULES = [
       };
     }
   },
+  // 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 ? `. ${field} is a list field, so it cannot be tested for null or compared with =: 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')` : ". 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/,
@@ -9820,10 +9911,11 @@ var CORRECTION_RULES = [
       };
     }
   },
-  // 4. CONTAINS → LIKE
+  // 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,
-    matchApiError: /CONTAINS.*not.*supported|invalid.*operator.*CONTAINS/i,
     fix: (ctx) => {
       const match = ctx.originalQuery.match(/CONTAINS\s*\(\s*([^,]+),\s*'([^']+)'\s*\)/i);
       if (match) {
@@ -10087,7 +10179,7 @@ var CORRECTION_RULES = [
     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: SELECT campaign.name, segments.month, metrics.cost_micros, metrics.conversions FROM campaign WHERE segments.date DURING LAST_12_MONTHS 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."
+      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
@@ -11914,9 +12006,16 @@ import { resolve } from "path";
 import { defineCommand as defineCommand28 } from "citty";
 
 // src/commands/ads/google/presets.ts
-var GAQL_DATE_RANGE_RE = /^(?:TODAY|YESTERDAY|LAST_7_DAYS|LAST_14_DAYS|LAST_30_DAYS|LAST_90_DAYS|THIS_MONTH|LAST_MONTH|THIS_QUARTER|LAST_QUARTER|THIS_YEAR|LAST_YEAR|ALL_TIME|BETWEEN\s+'[0-9]{4}-[0-9]{2}-[0-9]{2}'\s+AND\s+'[0-9]{4}-[0-9]{2}-[0-9]{2}')$/i;
+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) {
-  return GAQL_DATE_RANGE_RE.test(value.trim());
+  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"],
@@ -12052,17 +12151,15 @@ function buildStatusScope(statusFields, includePaused) {
   const predicate = includePaused ? "!= 'REMOVED'" : "= 'ENABLED'";
   return statusFields.map((field) => ` AND ${field} ${predicate}`).join("");
 }
-function expandPreset(preset, params) {
+function expandPreset(preset, params, now = /* @__PURE__ */ new Date()) {
   const dateRange = params.dateRange ?? preset.defaultDateRange;
   const limit = params.limit ?? preset.defaultLimit;
-  if (!isValidDateRange(dateRange)) {
-    return {
-      query: "",
-      dateRangeError: `Invalid date range: "${dateRange}". Use a GAQL date literal (e.g. LAST_30_DAYS, TODAY) or BETWEEN 'YYYY-MM-DD' AND 'YYYY-MM-DD'.`
-    };
+  if (preset.gaqlTemplate.includes("{dateRange}") && !isValidDateRange(dateRange)) {
+    return { query: "", dateRangeError: dateRangeError(dateRange, now) };
   }
   const statusScope = buildStatusScope(preset.statusFields, params.includePaused ?? false);
-  const query = preset.gaqlTemplate.replace(/\{dateRange\}/g, dateRange).replace(/\{limit\}/g, String(limit)).replace(/\{statusScope\}/g, statusScope);
+  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 };
 }
 
@@ -12221,6 +12318,49 @@ function applyAutoFixes(query, limit) {
   }
   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: buildCommand2(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: buildCommand2(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
+    }
+  };
+}
 function validatePreflight(query, customerId, limit) {
   const warnings = [];
   const corrected = query;
@@ -12292,6 +12432,10 @@ function validatePreflight(query, customerId, limit) {
       }
     };
   }
+  const duringRejection = rejectUnsupportedDuring(corrected, customerId);
+  if (duringRejection) return { valid: false, warnings: [], error: duringRejection };
+  const limitRejection = rejectOversizedLimit(corrected, customerId);
+  if (limitRejection) return { valid: false, warnings: [], error: limitRejection };
   if (/\bsegments\.conversion_action_name\b/i.test(corrected) && /\bmetrics\.cost_micros\b/i.test(corrected)) {
     return {
       valid: false,
@@ -12500,7 +12644,7 @@ registerSchema({
     },
     "date-range": {
       type: "string",
-      description: "Date range for presets (LAST_7_DAYS, LAST_30_DAYS, LAST_90_DAYS, or BETWEEN 'X' AND 'Y')",
+      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": {
@@ -12510,7 +12654,7 @@ registerSchema({
     },
     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 10000 are accepted. Any read that fills this cap comes back flagged TRUNCATED_RESULTS \u2014 never count or total from one.",
+      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
     },
@@ -12518,7 +12662,7 @@ registerSchema({
     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 above the row count you expect (or your own LIMIT) and check the read came back without TRUNCATED_RESULTS.",
+      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: {
@@ -12605,7 +12749,8 @@ function completenessWarnings(read) {
   const filledTheCap = cap3 !== void 0 && cap3 > 0 && read.rowCount >= cap3;
   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 (${cap3}).`;
-  const fix = read.all ? `Every page was followed, so the cap is the LIMIT in the statement itself \u2014 raise it above ${cap3}, or drop it and pass a larger --limit, then re-run.` : `Re-run with --all --out <file> to page through everything, or raise --limit above ${cap3}.`;
+  const atPageCap = cap3 !== void 0 && cap3 >= 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 ${cap3}, 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 ${cap3} (up to ${GOOGLE_ADS_QUERY_MAX_PAGE_SIZE}).`;
   return [
     {
       code: "TRUNCATED_RESULTS",
@@ -12939,9 +13084,35 @@ async function executeQuery(finalQuery, args5, customerId, limit, warnings, useC
 function shouldReadCache(args5) {
   return !args5["no-cache"] && !args5.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(args5) {
+  const parsedLimit = parseQueryLimit(args5.limit);
+  if (!parsedLimit.ok) {
+    writeAdsJson(parsedLimit.error);
+    process.exit(1);
+  }
+  const { limit } = parsedLimit;
   const customerId = await resolveCustomerId(args5);
-  const limit = args5.limit ? Number(args5.limit) : 200;
   const gaql = resolveGaql(args5, limit);
   if (!gaql) {
     process.exit(1);