@koda-sl/baker-cli 0.347.0 → 0.348.0

package/README.md

@@ -304,7 +304,7 @@ Read it before interpreting any null. Field coverage is folded page by page on t
 }
 ```
 
-Never total or count from a response carrying it — re-run with `--all --limit 10000 --out data.csv` (the API accepts page sizes up to 10,000) and check the re-run came back without the warning. A read that returns one row by construction — `FROM customer` with no segment selected, such as `--preset account-summary` — has no page to fill, so it never carries `TRUNCATED_RESULTS`, nor `CONVERSION_MIX`, since one account-wide row has no campaigns to total or compare. Warnings reach every output format, so no `--output` choice can hide one:
+Never total or count from a response carrying it — re-run with `--all --limit 8192 --out data.csv` (one read returns at most 8,192 rows; split a bigger data set into narrower queries — a shorter date range or one campaign each) and check the re-run came back without the warning. A read that returns one row by construction — `FROM customer` with no segment selected, such as `--preset account-summary` — has no page to fill, so it never carries `TRUNCATED_RESULTS`, nor `CONVERSION_MIX`, since one account-wide row has no campaigns to total or compare. Warnings reach every output format, so no `--output` choice can hide one:
 
 | `--output` | Where warnings land |
 |------------|---------------------|
@@ -343,11 +343,11 @@ The same lines also go to stderr. A read with nothing to report prints none of i
 |-----------------|--------------------------------------------------------------|
 | `--customer-id` | Google Ads customer ID (10 digits, no dashes). Falls back to `BAKER_GOOGLE_ADS_CUSTOMER_ID` env var. |
 | `--preset`      | Named query template (see presets below)                     |
-| `--date-range`  | Override preset date range (LAST_7_DAYS, LAST_30_DAYS, etc.) |
+| `--date-range`  | Override preset date range: a Google literal (LAST_7_DAYS, LAST_30_DAYS, LAST_MONTH, etc.) or `BETWEEN 'YYYY-MM-DD' AND 'YYYY-MM-DD'` — there is no LAST_90_DAYS |
 | `--include-paused` | Include paused entities in preset results. Off by default: presets return only actually-serving entities (enabled campaign **and** ad group **and** ad). Google Ads has no single serving flag, so the whole chain must be `ENABLED` for an entity to serve. |
-| `--limit`       | Max rows per page (default 200)                              |
+| `--limit`       | Max rows per page (default 200, at most 8,192)               |
 | `--cursor`      | Pagination cursor from previous response                     |
-| `--all`         | Auto-paginate all results. Exhausts the pages, not the statement's `LIMIT` — pair it with a `--limit` above the expected row count, and a read that still fills its cap is flagged `TRUNCATED_RESULTS` either way |
+| `--all`         | Auto-paginate all results. Exhausts the pages, not the statement's `LIMIT` — pair it with a `LIMIT` in the statement above the expected row count (at most 8,192 — split bigger reads into narrower queries), and a read that still fills its cap is flagged `TRUNCATED_RESULTS` either way |
 | `--out`         | Write data to file (format from extension: .csv, .jsonl, .json) |
 | `--append`      | Append to existing file (skip CSV headers)                   |
 | `--output`      | Output format: `json` \| `csv` \| `jsonl` \| `md`           |
@@ -391,6 +391,8 @@ The CLI rejects or automatically corrects common GAQL mistakes before hitting th
 | `shopping_performance_view.product_*` | Rewrites to `segments.product_*` | Field renamed |
 | `campaign.status = 'ACTIVE'` | Rewrites to `= 'ENABLED'` | Enum corrected |
 | `segments.conversion_action_name` with `metrics.cost_micros` | Rejects; split into separate conversion-action and spend queries | `INCOMPATIBLE_FIELDS` with `fix.action: "split_query"` |
+| `DURING` with a literal Google does not accept (`LAST_90_DAYS`, `LAST_12_MONTHS`, `THIS_YEAR` …) | Rejects before any request; `DURING` takes only `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` | `INVALID_DATE_RANGE`, with `fix.correctedCommand` spelling the same window as `BETWEEN 'YYYY-MM-DD' AND 'YYYY-MM-DD'` |
+| `--limit` outside 1–8,192, or a statement `LIMIT` above 8,192 | Rejects before any request — one read returns at most 8,192 rows | `VALIDATION_ERROR` naming the cap and how to split a bigger read; a statement `LIMIT` also gets `fix.correctedCommand` at `LIMIT 8192` |
 | `FROM ad_group_criterion` without `negative` field | Warns | `"ad_group_criterion returns BOTH positive and negative keywords. Use --preset positive-keywords or negative-keywords."` |
 
 Auto-fixed queries proceed normally. Warnings appear in the response:

package/dist/cli.js

@@ -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.`
     }
   };
 }
@@ -10087,7 +10157,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 +11984,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 +12129,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 +12296,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 +12410,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 +12622,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 +12632,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 +12640,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 +12727,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 +13062,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);