@koda-sl/baker-cli 0.150.0 → 0.151.0-dev.1a051172a

package/dist/cli.js

@@ -36,7 +36,7 @@ import {
   toModelSafeImage,
   ulid,
   validateCanvasDeep
-} from "./chunk-OO5BDH3J.js";
+} from "./chunk-JBDSJZBZ.js";
 import {
   csvOrJson,
   daysAgoIso,
@@ -4042,11 +4042,21 @@ var FIELD_DESCRIPTIONS = {
   "asset_group.status": "ENABLED, PAUSED, or REMOVED",
   "asset_group_asset.field_type": "Where the asset is used (HEADLINE, DESCRIPTION, LOGO, etc.)",
   "asset_group_asset.performance_label": "Performance rating: BEST, GOOD, LOW, LEARNING",
-  // Change events
+  // Change events (field-level detail, last 30 days)
   "change_event.change_date_time": "When the change occurred (ISO 8601)",
   "change_event.change_resource_type": "What was changed: CAMPAIGN, AD_GROUP, AD, etc.",
   "change_event.resource_change_operation": "CREATE, UPDATE, or REMOVE",
   "change_event.user_email": "Email of user who made the change",
+  // Change status (which resources changed, last 90 days — no values, no user)
+  "change_status.last_change_date_time": "When this resource last changed (ISO 8601)",
+  "change_status.resource_type": "What changed: CAMPAIGN, AD_GROUP, AD_GROUP_AD, AD_GROUP_CRITERION, etc.",
+  "change_status.resource_status": "ADDED, CHANGED, or REMOVED \u2014 not the old or new value",
+  "change_status.resource_name": "Identifier of the changed resource; query it to read its current values",
+  "change_status.campaign": "Resource name of the campaign the change belongs to",
+  "change_status.ad_group": "Resource name of the ad group the change belongs to",
+  "change_status.ad_group_ad": "Resource name of the changed ad",
+  "change_status.ad_group_criterion": "Resource name of the changed keyword or criterion",
+  "change_status.campaign_criterion": "Resource name of the changed campaign-level criterion",
   // Landing pages
   "landing_page_view.unexpanded_final_url": "Landing page URL",
   // Geo
@@ -4064,6 +4074,89 @@ function getFieldDescriptions(fields) {
   return result;
 }
 
+// src/commands/ads/google/changes-window.ts
+var CHANGE_SCOPE_MAX_DAYS = {
+  detail: 30,
+  summary: 90
+};
+var DEFAULT_CHANGE_DAYS = 7;
+function isChangeScope(value) {
+  return value === "detail" || value === "summary";
+}
+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}.`
+        }
+      }
+    };
+  }
+  const max = CHANGE_SCOPE_MAX_DAYS[scope];
+  if (days > max) {
+    return { ok: false, error: lookbackTooLong(scope, days, max) };
+  }
+  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 (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."
+    }
+  };
+}
+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/correction-table.ts
 function buildCommand(query, ctx) {
   return `baker ads google query "${query}" --customer-id ${ctx.customerId}`;
@@ -4392,6 +4485,35 @@ var CORRECTION_RULES = [
       };
     }
   },
+  // 20a. change_event past its 30-day reach → change_status, which reaches 90 days.
+  // The enum prefix in the API message is what separates this from the change_status
+  // case below; a bare START_DATE_TOO_OLD falls through to the query-pattern pass,
+  // which routes on the resource the caller actually queried.
+  {
+    matchQuery: /FROM\s+change_event\b/i,
+    matchApiError: /ChangeEventError\.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 ninetyDaysAgo = new Date(Date.now() - 90 * 24 * 60 * 60 * 1e3).toISOString().slice(0, 10);
+      const start = requested && requested > ninetyDaysAgo ? requested : ninetyDaysAgo;
+      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.`
+      };
+    }
+  },
+  // 20b. Past 90 days no history resource reaches — infer the change from spend instead.
+  {
+    matchQuery: /FROM\s+change_status\b/i,
+    matchApiError: /ChangeStatusError\.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."
+    })
+  },
   // 20. change_event without date constraint
   {
     matchQuery: /FROM\s+change_event\b(?!.*change_date_time)/i,
@@ -4545,14 +4667,25 @@ function parseApiError(errorMessage, originalQuery, customerId) {
 // src/commands/ads/google/changes.ts
 registerSchema({
   command: "ads.google.changes",
-  description: "Get recent change logs with performance impact. Shows what changed and how it affected metrics.",
+  description: "Read the account's change history. --scope detail (default) shows what changed and to what value, back 30 days; --scope summary shows which resources changed, back 90 days.",
   args: {
     "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
     },
-    days: { type: "string", description: "Lookback days (default: 7, max: 90)", required: false, default: 7 },
+    days: {
+      type: "string",
+      description: `Lookback days (default: ${DEFAULT_CHANGE_DAYS}). Max ${CHANGE_SCOPE_MAX_DAYS.detail} with --scope detail, ${CHANGE_SCOPE_MAX_DAYS.summary} with --scope summary. Google keeps nothing older behind any API.`,
+      required: false,
+      default: DEFAULT_CHANGE_DAYS
+    },
+    scope: {
+      type: "string",
+      description: `detail|summary (default: detail). detail = old/new values plus who made the change, ${CHANGE_SCOPE_MAX_DAYS.detail} days. summary = which resources were added, changed or removed, ${CHANGE_SCOPE_MAX_DAYS.summary} days, without values.`,
+      required: false,
+      default: "detail"
+    },
     "resource-type": {
       type: "string",
       description: "Filter by type: CAMPAIGN, AD_GROUP, AD_GROUP_AD, AD_GROUP_CRITERION",
@@ -4565,15 +4698,24 @@ registerSchema({
 var changesCommand = defineCommand20({
   meta: {
     name: "changes",
-    description: `Get recent changes in a Google Ads account with performance data.
+    description: `Read the change history of a Google Ads account.
+
+Google keeps account history in two layers, and neither reaches past 90 days:
+  --scope detail  (default)  what changed, old \u2192 new value, who changed it   \u2014 last ${CHANGE_SCOPE_MAX_DAYS.detail} days
+  --scope summary            which resources were added, changed or removed  \u2014 last ${CHANGE_SCOPE_MAX_DAYS.summary} days
+
+For anything older, infer it from performance instead \u2014 a monthly spend trend per
+campaign shows what started or stopped, just not who did it.
 
 Examples:
   baker ads google changes --customer-id 1234567890
-  baker ads google changes --customer-id 1234567890 --days 14 --resource-type CAMPAIGN`
+  baker ads google changes --customer-id 1234567890 --days 14 --resource-type CAMPAIGN
+  baker ads google changes --customer-id 1234567890 --days 60 --scope summary`
   },
   args: {
     "customer-id": { type: "string", description: "Google Ads customer ID", required: false },
-    days: { type: "string", description: "Lookback days (default 7)", required: false },
+    days: { type: "string", description: `Lookback days (default ${DEFAULT_CHANGE_DAYS})`, required: false },
+    scope: { type: "string", description: "detail (30 days) or summary (90 days)", required: false },
     "resource-type": { type: "string", description: "Filter by resource type", required: false },
     limit: { type: "string", description: "Max results (default 50)", required: false },
     "no-cache": { type: "boolean", description: "Skip cache, hit API directly", required: false },
@@ -4581,9 +4723,19 @@ Examples:
   },
   run: async ({ args }) => {
     const customerId = await resolveCustomerId(args);
+    const window = resolveChangesWindow({
+      days: args.days ? Number(args.days) : void 0,
+      scope: args.scope
+    });
+    if (!window.ok) {
+      writeJsonEnvelope({ ok: false, error: { ...window.error, retryable: false } });
+      process.exit(1);
+      return;
+    }
     const body = {
       customerId,
-      days: args.days ? Number(args.days) : 7,
+      days: window.days,
+      scope: window.scope,
       limit: args.limit ? Number(args.limit) : 50
     };
     const managerId = getManagerIdForCustomer(customerId);
@@ -4600,7 +4752,7 @@ Examples:
       const first = data[0];
       const fields = first ? Object.keys(first) : [];
       const fieldDescs = getFieldDescriptions(fields);
-      writeAdsJson({ ok: true, data, fields: fieldDescs });
+      writeJsonEnvelope({ ok: true, data, fields: fieldDescs, hints: window.hints });
     } catch (err) {
       if (err instanceof ApiError) {
         writeAdsJson(parseApiError(err.message, "", customerId));