@koda-sl/baker-cli 0.233.0 → 0.234.0

package/README.md

@@ -1155,7 +1155,7 @@ Each finding: `{id, area, check, status, severity, evidence, fix: {explanation,
 
 GA4 commands for multi-channel audits **and** for configuring what the property measures. Playbook-aligned report presets, property health audits, free-form Data API queries, and staged Admin API writes.
 
-Reads (`properties`, `config`, `audit`, `query`) happen immediately. Writes (`key-event`, `custom-dimension`, `custom-metric`, `custom-event`, `data-retention`) are **staged** onto the chat, reviewed in the dashboard's Analytics tab, and applied when the chat completes — at which point they take effect on the property immediately. There is no simulated mode and no undo.
+Reads (`properties`, `config`, `audit`, `query`) happen immediately. Writes (`key-event`, `custom-dimension`, `custom-metric`, `custom-event`, `data-retention`, `audience`, `property`, `ads-link`, `enhanced-measurement`) are **staged** onto the chat, reviewed in the dashboard's Analytics tab, and applied when the chat completes — at which point they take effect on the property immediately. There is no simulated mode and no undo.
 
 A Google Analytics connection made before writes shipped is read-only and every write command refuses with a message saying to reconnect. `baker ga4 config` reports `canWrite`.
 
@@ -1277,12 +1277,31 @@ baker ga4 custom-event delete 7
 # How long data is kept (months: 2, 14, 26, 38, 50 — over 14 needs Analytics 360)
 baker ga4 data-retention set --event-data 14 --user-data 14
 
+# An audience — a saved group of users, for retargeting and analysis
+baker ga4 audience create --json '{"displayName":"Started demo without finishing","description":"Triggered demo_started and never submitted the demo form","membershipDurationDays":90,"filterClauses":[{"clauseType":"INCLUDE","simpleFilter":{"scope":"AUDIENCE_FILTER_SCOPE_ACROSS_ALL_SESSIONS","filterExpression":{"eventFilter":{"eventName":"demo_started"}}}},{"clauseType":"EXCLUDE","simpleFilter":{"scope":"AUDIENCE_FILTER_SCOPE_ACROSS_ALL_SESSIONS","filterExpression":{"eventFilter":{"eventName":"demo_form_submitted"}}}}]}'
+baker ga4 audience update 8813 --json '{"displayName":"Started demo without finishing (90d)"}'
+baker ga4 audience archive 8813
+
+# The property's own settings — the industry decides its benchmarking cohort
+baker ga4 property set --industry TECHNOLOGY
+
+# The automatic web-stream events — no tag to add
+baker ga4 enhanced-measurement set --scrolls true --outbound-clicks true --file-downloads true
+baker ga4 enhanced-measurement set --site-search true --search-parameters "q,s,search,query,keyword"
+
+# Link to Google Ads — what makes audiences targetable and key events importable
+baker ga4 ads-link create --customer-id 123-456-7890
+baker ga4 ads-link update L1234 --ads-personalization false
+baker ga4 ads-link delete L1234
+
 # Several definitions in one call — one read of the property instead of one per definition
 baker ga4 custom-dimension create --json '[{"parameterName":"plan_tier","displayName":"Plan tier","scope":"EVENT"},{"parameterName":"lead_source","displayName":"Lead source","scope":"EVENT"}]'
 ```
 
 Every `create` accepts a JSON array as well as a single object, and stages the whole list in one request (all-or-nothing). Prefer it for bulk work: each stage reads the property's full configuration first, so separate calls multiply that read.
 
+An **audience is permanent once created**: its conditions, membership window and exclusion mode are immutable, so `audience update` takes only a name and a description, and fixing a definition means archiving it and building a replacement that starts with no users. Staging also warns when the property has no Google Ads link, because an audience without one can never be retargeted. `enhanced-measurement` sets the events GA4 collects on a website stream by itself; `--site-search true` requires `--search-parameters`, and staging refuses without them rather than letting the publish fail. `ads-link` is the only GA4 command that reaches outside Analytics — it starts a flow of the client's data between their Analytics property and their Google Ads account, so staging warns and the agent is told to agree it with the user first. `property set` covers the display name and the industry category only — time zone and currency are excluded on purpose, since both re-bucket every future day without reprocessing history. Sequence-based audiences are not supported.
+
 Custom dimensions and metrics are **archived**, not deleted (the slot frees, past data stays); key events and custom events are **deleted**. Neither is reversible from Baker. Because `parameterName` and `scope` are immutable, changing one is an archive plus a create staged on the same chat — the removal applies first and frees the name. `--property-id` is required when more than one property is connected, and one chat stages changes for one property; `--data-stream` is required for a custom event when the property has more than one website stream.
 
 ---

package/dist/cli.js

@@ -32003,10 +32003,14 @@ async function draftList(json, chat) {
 // src/commands/ga4/config.ts
 registerSchema({
   command: "ga4.config",
-  description: "Read how a Google Analytics property is configured to measure: key events (conversions), custom dimensions and metrics, custom events, data streams and the data retention window. Start here before staging any change \u2014 every id an update or removal targets comes from this, and `canWrite` says whether this connection may change anything at all. Compact by default; pass --full for the raw Analytics objects.",
+  description: "Read how a Google Analytics property is configured to measure: key events (conversions), custom dimensions and metrics, custom events, audiences, linked Google Ads accounts, data streams and the data retention window. Start here before staging any change \u2014 every id an update or removal targets comes from this, and `canWrite` says whether this connection may change anything at all. Compact by default; pass --full for the raw Analytics objects AND each website stream's enhanced measurement settings (the automatic events), which are the only way to see what is on before changing a toggle.",
   args: {
     "property-id": { type: "string", description: "GA4 property id (optional when one is connected)", required: false },
-    full: { type: "boolean", description: "Include the raw Analytics object for each entity", required: false }
+    full: {
+      type: "boolean",
+      description: "Include the raw Analytics object for each entity, plus each website stream's enhanced measurement settings",
+      required: false
+    }
   }
 });
 function configHints(config) {
@@ -32039,11 +32043,15 @@ var configCommand = defineCommand116({
 Examples:
   baker ga4 config
   baker ga4 config --property-id 123456789
-  baker ga4 config --full`
+  baker ga4 config --full          # + the automatic events each website stream collects today`
   },
   args: {
     "property-id": { type: "string", description: "GA4 property id", required: false },
-    full: { type: "boolean", description: "Include raw Analytics objects", required: false }
+    full: {
+      type: "boolean",
+      description: "Include raw Analytics objects and enhanced measurement settings",
+      required: false
+    }
   },
   run: async ({ args }) => {
     try {
@@ -32769,6 +32777,327 @@ Examples:
     })
   }
 });
+registerSchema({
+  command: "ga4.audience",
+  description: "Create an audience (a saved group of users, e.g. everyone who started a demo but never finished), rename one, or archive one. Read `baker ga4 config` first to see the audiences that already exist. IMPORTANT: everything that defines who is in an audience \u2014 the conditions, the membership window \u2014 is frozen the moment it is created and cannot be edited afterwards, so get it right in one go. An audience only reaches Google Ads for retargeting if the property is linked to a Google Ads account.",
+  args: {
+    json: { type: "string", description: createJsonDescription("audience"), required: false },
+    file: { type: "string", description: "Path to a JSON file with the definition", required: false },
+    "property-id": { type: "string", description: PROPERTY_ARG_DESCRIPTION, required: false }
+  }
+});
+var audienceCommand = defineCommand120({
+  meta: {
+    name: "audience",
+    description: `Stage audience changes (saved groups of users, for retargeting and analysis)
+
+The definition is PERMANENT: conditions and membership window cannot be edited after creation.
+Fixing one means archiving it and building a replacement, which does not carry its users over.
+
+Examples:
+  # Everyone who visited but never submitted the demo form, kept for 90 days
+  baker ga4 audience create --json '{
+    "displayName":"Visited without demo",
+    "description":"Reached the site, never submitted the demo form",
+    "membershipDurationDays":90,
+    "filterClauses":[
+      {"clauseType":"INCLUDE","simpleFilter":{"scope":"AUDIENCE_FILTER_SCOPE_ACROSS_ALL_SESSIONS",
+        "filterExpression":{"eventFilter":{"eventName":"page_view"}}}},
+      {"clauseType":"EXCLUDE","simpleFilter":{"scope":"AUDIENCE_FILTER_SCOPE_ACROSS_ALL_SESSIONS",
+        "filterExpression":{"eventFilter":{"eventName":"demo_form_submitted"}}}}
+    ]}'
+
+  # Everyone who landed on a pricing page
+  baker ga4 audience create --json '{"displayName":"Saw pricing","description":"Viewed a pricing page",
+    "membershipDurationDays":60,
+    "filterClauses":[{"clauseType":"INCLUDE","simpleFilter":{"scope":"AUDIENCE_FILTER_SCOPE_ACROSS_ALL_SESSIONS",
+      "filterExpression":{"dimensionOrMetricFilter":{"fieldName":"pagePath",
+        "stringFilter":{"matchType":"CONTAINS","value":"/pricing"}}}}}]}'
+
+  baker ga4 audience update 8813 --json '{"displayName":"Visited without demo (90d)"}'   \u2014 name/description only
+  baker ga4 audience archive 8813`
+  },
+  subCommands: {
+    create: defineCommand120({
+      meta: { name: "create", description: createJsonDescription("audience") },
+      args: {
+        json: { type: "string", description: createJsonDescription("audience"), required: false },
+        file: { type: "string", description: "Path to a JSON file", required: false },
+        "property-id": propertyArg
+      },
+      run: async ({ args }) => {
+        const payloads = loadJsonPayloads(args);
+        await stageOps(
+          payloads.map((payload) => ({
+            kind: "ga4.audience.create",
+            payload,
+            ...withProperty(args)
+          }))
+        );
+      }
+    }),
+    update: defineCommand120({
+      meta: {
+        name: "update",
+        description: "Stage a new name or description (pass the audience id). Who is in it cannot be changed."
+      },
+      args: {
+        json: { type: "string", description: 'Inline JSON, e.g. {"displayName":"\u2026"}', required: false },
+        file: { type: "string", description: "Path to a JSON file", required: false },
+        "property-id": propertyArg
+      },
+      run: async ({ args }) => {
+        const target = requireTarget4(args, "audience id");
+        const payload = loadJsonArg(args);
+        await stageOp3({
+          kind: "ga4.audience.update",
+          target,
+          payload,
+          ...withProperty(args)
+        });
+      }
+    }),
+    archive: defineCommand120({
+      meta: {
+        name: "archive",
+        description: "Stage retiring an audience. Cannot be undone \u2014 the users it gathered do not come back."
+      },
+      args: { "property-id": propertyArg },
+      run: async ({ args }) => {
+        await stageOp3({
+          kind: "ga4.audience.archive",
+          target: requireTarget4(args, "audience id"),
+          ...withProperty(args)
+        });
+      }
+    })
+  }
+});
+registerSchema({
+  command: "ga4.property",
+  description: "Set the property's name or industry category. The industry decides which businesses Google benchmarks this property against, so a property left on OTHER is being compared to nothing useful. Time zone and currency are deliberately not changeable here \u2014 both re-bucket every future day without reprocessing history, so they belong to a person who knows the reporting calendar.",
+  args: {
+    name: { type: "string", description: "New property display name", required: false },
+    industry: {
+      type: "string",
+      description: "Industry category, e.g. TECHNOLOGY, FINANCE, HEALTHCARE, REAL_ESTATE, JOBS_AND_EDUCATION",
+      required: false
+    },
+    "property-id": { type: "string", description: PROPERTY_ARG_DESCRIPTION, required: false }
+  }
+});
+var propertyCommand = defineCommand120({
+  meta: {
+    name: "property",
+    description: `Stage a change to the property's own settings
+
+Examples:
+  baker ga4 property set --industry TECHNOLOGY
+  baker ga4 property set --name "Acme \u2014 Web" --industry REAL_ESTATE`
+  },
+  subCommands: {
+    set: defineCommand120({
+      meta: { name: "set", description: "Stage the property name and/or industry category" },
+      args: {
+        name: { type: "string", description: "New property display name", required: false },
+        industry: { type: "string", description: "Industry category, e.g. TECHNOLOGY", required: false },
+        "property-id": propertyArg
+      },
+      run: async ({ args }) => {
+        const payload = {};
+        if (typeof args.name === "string" && args.name.length > 0) {
+          payload.displayName = args.name;
+        }
+        if (typeof args.industry === "string" && args.industry.length > 0) {
+          payload.industryCategory = args.industry.trim().toUpperCase();
+        }
+        if (Object.keys(payload).length === 0) {
+          failValidation3("pass --name, --industry, or both");
+        }
+        await stageOp3({ kind: "ga4.property.update", payload, ...withProperty(args) });
+      }
+    })
+  }
+});
+registerSchema({
+  command: "ga4.adsLink",
+  description: "Link this Analytics property to a Google Ads account, or unlink it. This is what lets Google Ads import the property's key events for bidding and makes audiences built here targetable \u2014 `baker ga4 audit` reports the gap as NO_ADS_LINK. It reaches outside Analytics and moves the client's data between two products, so agree it with the user before staging it.",
+  args: {
+    "customer-id": {
+      type: "string",
+      description: "Google Ads customer id, with or without dashes (123-456-7890)",
+      required: false
+    },
+    "ads-personalization": {
+      type: "string",
+      description: "true|false \u2014 may this property's audiences be used for ads personalisation",
+      required: false
+    },
+    "property-id": { type: "string", description: PROPERTY_ARG_DESCRIPTION, required: false }
+  }
+});
+var adsLinkCommand = defineCommand120({
+  meta: {
+    name: "ads-link",
+    description: `Stage linking this property to a Google Ads account
+
+Without this link, Google Ads imports no key events from the property and audiences built
+here cannot be retargeted. It moves the client's data between two products \u2014 agree it first.
+
+Examples:
+  baker ga4 ads-link create --customer-id 123-456-7890
+  baker ga4 ads-link create --customer-id 1234567890 --ads-personalization true
+  baker ga4 ads-link update L1234 --ads-personalization false
+  baker ga4 ads-link delete L1234`
+  },
+  subCommands: {
+    create: defineCommand120({
+      meta: { name: "create", description: "Stage linking the property to a Google Ads account" },
+      args: {
+        "customer-id": { type: "string", description: "Google Ads customer id (123-456-7890)", required: false },
+        "ads-personalization": { type: "string", description: "true|false", required: false },
+        "property-id": propertyArg
+      },
+      run: async ({ args }) => {
+        const customerId = args["customer-id"];
+        if (typeof customerId !== "string" || customerId.length === 0) {
+          failValidation3("pass --customer-id, the Google Ads account to link (123-456-7890)");
+        }
+        const payload = { customerId };
+        if (typeof args["ads-personalization"] === "string") {
+          payload.adsPersonalizationEnabled = booleanArg(args["ads-personalization"], "ads-personalization");
+        }
+        await stageOp3({ kind: "ga4.googleAdsLink.create", payload, ...withProperty(args) });
+      }
+    }),
+    update: defineCommand120({
+      meta: {
+        name: "update",
+        description: "Stage the ads-personalisation setting on an existing link (pass its id)"
+      },
+      args: {
+        "ads-personalization": { type: "string", description: "true|false", required: false },
+        "property-id": propertyArg
+      },
+      run: async ({ args }) => {
+        const target = requireTarget4(args, "Google Ads link id");
+        if (typeof args["ads-personalization"] !== "string") {
+          failValidation3("pass --ads-personalization true|false \u2014 it is the only thing a link update can change");
+        }
+        await stageOp3({
+          kind: "ga4.googleAdsLink.update",
+          target,
+          payload: { adsPersonalizationEnabled: booleanArg(args["ads-personalization"], "ads-personalization") },
+          ...withProperty(args)
+        });
+      }
+    }),
+    delete: defineCommand120({
+      meta: {
+        name: "delete",
+        description: "Stage unlinking. Stops conversion imports and strands every audience on this property."
+      },
+      args: { "property-id": propertyArg },
+      run: async ({ args }) => {
+        await stageOp3({
+          kind: "ga4.googleAdsLink.delete",
+          target: requireTarget4(args, "Google Ads link id"),
+          ...withProperty(args)
+        });
+      }
+    })
+  }
+});
+registerSchema({
+  command: "ga4.enhancedMeasurement",
+  description: "Turn the automatic web-stream events on or off: scrolls, outbound clicks, site search, video engagement, file downloads, page changes (single-page apps), form interactions. These are collected by Google Analytics itself with no tag to add, so this is usually the cheapest measurement win available. Run `baker ga4 config --full` to see what is on today.",
+  args: {
+    scrolls: { type: "string", description: "true|false", required: false },
+    "outbound-clicks": { type: "string", description: "true|false", required: false },
+    "site-search": { type: "string", description: "true|false \u2014 needs --search-parameters", required: false },
+    "search-parameters": {
+      type: "string",
+      description: "URL parameters carrying the search term, e.g. q,s,search,query,keyword",
+      required: false
+    },
+    video: { type: "string", description: "true|false", required: false },
+    "file-downloads": { type: "string", description: "true|false", required: false },
+    "page-changes": { type: "string", description: "true|false \u2014 page views in a single-page app", required: false },
+    "form-interactions": { type: "string", description: "true|false", required: false },
+    enabled: { type: "string", description: "true|false \u2014 the master switch for the whole feature", required: false },
+    "data-stream": {
+      type: "string",
+      description: "Only when the property has several website streams",
+      required: false
+    },
+    "property-id": { type: "string", description: PROPERTY_ARG_DESCRIPTION, required: false }
+  }
+});
+var MEASUREMENT_FLAGS = {
+  enabled: "streamEnabled",
+  scrolls: "scrollsEnabled",
+  "outbound-clicks": "outboundClicksEnabled",
+  "site-search": "siteSearchEnabled",
+  video: "videoEngagementEnabled",
+  "file-downloads": "fileDownloadsEnabled",
+  "page-changes": "pageChangesEnabled",
+  "form-interactions": "formInteractionsEnabled"
+};
+var enhancedMeasurementCommand = defineCommand120({
+  meta: {
+    name: "enhanced-measurement",
+    description: `Stage the automatic events GA4 collects on a website stream
+
+No tag to add \u2014 Google Analytics collects these itself. Usually the cheapest measurement win there is.
+
+Examples:
+  baker ga4 enhanced-measurement set --scrolls true --outbound-clicks true --file-downloads true
+  baker ga4 enhanced-measurement set --site-search true --search-parameters "q,s,search,query,keyword"
+  baker ga4 enhanced-measurement set --page-changes true     # page views in a single-page app
+  baker ga4 enhanced-measurement set --video false`
+  },
+  subCommands: {
+    set: defineCommand120({
+      meta: { name: "set", description: "Stage which automatic events the website stream collects" },
+      args: {
+        scrolls: { type: "string", description: "true|false", required: false },
+        "outbound-clicks": { type: "string", description: "true|false", required: false },
+        "site-search": { type: "string", description: "true|false", required: false },
+        "search-parameters": { type: "string", description: "e.g. q,s,search,query,keyword", required: false },
+        video: { type: "string", description: "true|false", required: false },
+        "file-downloads": { type: "string", description: "true|false", required: false },
+        "page-changes": { type: "string", description: "true|false", required: false },
+        "form-interactions": { type: "string", description: "true|false", required: false },
+        enabled: { type: "string", description: "true|false \u2014 master switch", required: false },
+        "data-stream": { type: "string", description: "Stream id, when there are several", required: false },
+        "property-id": propertyArg
+      },
+      run: async ({ args }) => {
+        const payload = {};
+        for (const [flag, field] of Object.entries(MEASUREMENT_FLAGS)) {
+          const value = args[flag];
+          if (typeof value === "string") {
+            payload[field] = booleanArg(value, flag);
+          }
+        }
+        if (typeof args["search-parameters"] === "string" && args["search-parameters"].length > 0) {
+          payload.searchQueryParameter = args["search-parameters"];
+        }
+        if (Object.keys(payload).length === 0) {
+          failValidation3(
+            "pass at least one setting, e.g. --scrolls true --outbound-clicks true. Run `baker ga4 config --full` to see what is on today."
+          );
+        }
+        await stageOp3({
+          kind: "ga4.enhancedMeasurement.update",
+          payload,
+          ...typeof args["data-stream"] === "string" ? { dataStream: args["data-stream"] } : {},
+          ...withProperty(args)
+        });
+      }
+    })
+  }
+});
 
 // src/commands/ga4/index.ts
 var ga4Command = defineCommand121({
@@ -32790,6 +33119,10 @@ Then stage changes (nothing is sent to Google Analytics until the chat completes
   baker ga4 key-event create --json '{"eventName":"generate_lead","countingMethod":"ONCE_PER_EVENT"}'
   baker ga4 custom-event create --json '{"destinationEvent":"quote_request","eventConditions":[...]}'
   baker ga4 custom-dimension create --json '{"parameterName":"plan_tier","displayName":"Plan tier","scope":"EVENT"}'
+  baker ga4 audience create --json '{"displayName":"Visited without demo", \u2026}'   \u2014 a group to retarget
+  baker ga4 property set --industry TECHNOLOGY                                   \u2014 benchmarking cohort
+  baker ga4 ads-link create --customer-id 123-456-7890                           \u2014 what makes audiences targetable
+  baker ga4 enhanced-measurement set --scrolls true --outbound-clicks true        \u2014 automatic events, no tag needed
   baker ga4 draft list                    \u2014 review everything staged
 
 An applied change takes effect on the property immediately \u2014 there is no version to publish afterwards
@@ -32807,6 +33140,10 @@ Full guide: __tooling__/docs/tools/baker/ga4.md`
     "custom-metric": customMetricCommand,
     "custom-event": customEventCommand,
     "data-retention": dataRetentionCommand,
+    audience: audienceCommand,
+    property: propertyCommand,
+    "ads-link": adsLinkCommand,
+    "enhanced-measurement": enhancedMeasurementCommand,
     draft: draftCommand3
   }
 });