@koda-sl/baker-cli 0.236.0 → 0.237.0

package/README.md

@@ -1204,6 +1204,8 @@ Shared flags: `--days <n>` (default 30) or `--start-date` / `--end-date` (`YYYY-
 
 **Campaign parameters are per platform, and so are the numbers.** `baker analytics ads` returns `adPlatformTraffic` (visits, conversions and *tagged* visits for each of the nine platforms), `adParams` for the platform in `--platform` only, and `adParamsUnattributed` for names arriving on visits with no click id and no recognisable source. Read `adPlatformTraffic` first: a platform with visits and zero tagged visits has untagged ad URLs, and no mapping can fix that from Baker's side. `baker analytics map` needs `--platform` for any change, accepts a parameter name **nobody has sent yet** — which is how a tracking template is configured before its campaign runs — and takes an answer back with `--remove`. `--set <name>=ignore` says a parameter is not campaign information at all, so Baker stops storing it and stops listing it.
 
+**The one recommendation about the ad account itself.** `baker analytics ads --platform <p>` warns when that platform's traffic carries no campaign id, ad group id or ad id — the three tiers every "which ad worked" question is grouped by — and returns the exact URL suffix, in the platform's own macro language, that would start sending the missing ones. It is the only mapping gap that cannot be fixed afterwards: naming a parameter Baker already captures corrects the history, because roles are resolved when a report is read, but a parameter the ads never sent has no stored values for a meaning to apply to. The hint stays quiet for a platform with little traffic, and defers to the untagged-account finding rather than repeating it.
+
 An unrecognised `--timezone` is refused with a `VALIDATION_ERROR` rather than defaulting to UTC, and `--output` accepts only `json` or `md`. Pass `--timezone` whenever the client is not in UTC. Day boundaries are drawn in UTC by default, which moves two hours of every Spanish evening onto the following day — not a rounding error on a day-of-week comparison, but the wrong day.
 
 Reading the output:

package/dist/cli.js

@@ -11347,6 +11347,62 @@ var AD_PARAM_ROLES = [
   "other",
   "ignore"
 ];
+var AD_PARAM_ROLE_SPECS = {
+  campaign_id: { role: "campaign_id", label: "Campaign ID", description: "The top level of this account's structure." },
+  campaign_name: { role: "campaign_name", label: "Campaign name", description: "The campaign's name." },
+  adgroup_id: { role: "adgroup_id", label: "Ad group ID", description: "The targeting container inside a campaign." },
+  adgroup_name: { role: "adgroup_name", label: "Ad group name", description: "The ad group's name." },
+  ad_id: { role: "ad_id", label: "Ad ID", description: "The individual ad that was clicked." },
+  ad_name: { role: "ad_name", label: "Ad name", description: "The individual ad's name." },
+  keyword: {
+    role: "keyword",
+    label: "Keyword",
+    description: "The keyword that matched, as it is written in the account \u2014 not what the visitor typed."
+  },
+  match_type: {
+    role: "match_type",
+    label: "Match type",
+    description: "How loosely the keyword matched: broad, phrase or exact."
+  },
+  search_query: { role: "search_query", label: "Search query", description: "What the visitor actually typed." },
+  audience: {
+    role: "audience",
+    label: "Audience",
+    description: "The remarketing list or interest segment the visitor was in."
+  },
+  placement: {
+    role: "placement",
+    label: "Placement",
+    description: "Where the ad appeared \u2014 a feed, a story, a site on the display network."
+  },
+  network: {
+    role: "network",
+    label: "Network",
+    description: "Which network served it: search, a search partner, display, or a video surface."
+  },
+  site_source: {
+    role: "site_source",
+    label: "App",
+    description: "Which app the click came from, on platforms that span several."
+  },
+  device: { role: "device", label: "Device", description: "Mobile, tablet or desktop, as the platform saw it." },
+  product_id: { role: "product_id", label: "Product ID", description: "The shopping item that was clicked." },
+  account_name: {
+    role: "account_name",
+    label: "Account name",
+    description: "Which ad account paid for the click, where an agency runs several."
+  },
+  other: {
+    role: "other",
+    label: "Something else",
+    description: "Keep the values and let me filter by this name, without saying what it means."
+  },
+  ignore: {
+    role: "ignore",
+    label: "Ignore it",
+    description: "Not campaign information. Baker stops storing it and stops asking about it."
+  }
+};
 var RESERVED_PARAM_NAMES = [
   "utm_source",
   "utm_medium",
@@ -11365,6 +11421,9 @@ var AD_PLATFORMS = [
   "pinterest",
   "snapchat"
 ];
+function isAdPlatform(value) {
+  return AD_PLATFORMS.includes(value);
+}
 var GOOGLE = {
   platform: "google",
   label: "Google Ads",
@@ -11557,6 +11616,10 @@ var AD_PLATFORM_DEFINITIONS = {
   pinterest: PINTEREST,
   snapchat: SNAPCHAT
 };
+var ESSENTIAL_ROLES = ["campaign_id", "adgroup_id", "ad_id", "keyword", "match_type"];
+function essentialAdDimensions(platform) {
+  return AD_PLATFORM_DEFINITIONS[platform].dimensions.filter((entry) => ESSENTIAL_ROLES.includes(entry.role));
+}
 function normalizeAdParamName(raw) {
   return raw.trim().toLowerCase().slice(0, 64);
 }
@@ -12361,10 +12424,19 @@ var analyticsLandingRowSchema = z24.object({
    *
    * Derived from the click ids a visit arrived with, never from `utm_source`:
    * a label is whatever somebody typed into a tracking template, a `gclid` is a
-   * click. Thresholded, so one stray click from a test URL does not describe a
-   * page as advertised.
+   * click. Ordered by traffic, busiest first.
    */
-  channels: z24.array(z24.string())
+  channels: z24.array(z24.string()),
+  /**
+   * Visits per entry of {@link channels}, in the same order.
+   *
+   * The half that makes a mark readable. A mark on its own says "advertised
+   * here", which is why it used to be withheld until three visits had arrived —
+   * and withholding it is what made a page whose whole day was five Meta clicks
+   * show nothing at all. The count says how much, so one test click and a live
+   * campaign are distinguishable by reading rather than by absence.
+   */
+  channelSessions: z24.array(z24.number().int().nonnegative())
 });
 var analyticsTagRowSchema = z24.object({
   tag: z24.string(),
@@ -12923,7 +12995,14 @@ var analyticsVisitProfileSchema = z24.object({
   utmSource: z24.string(),
   utmMedium: z24.string(),
   utmCampaign: z24.string(),
-  /** Whichever click id the visit arrived with, and which platform it belongs to. */
+  /**
+   * Which platform the click id proves, in the `AD_PLATFORMS` vocabulary —
+   * `google` | `meta` | `tiktok` | `x` | `linkedin` | `microsoft` | `""`.
+   *
+   * The same spelling every mark, mapping and report uses. It briefly said
+   * `google_ads` / `meta_ads` here alone, which meant every logo lookup on the
+   * People screen missed and a paid visit drew a neutral globe.
+   */
   clickPlatform: z24.string(),
   /** Every ValueTrack-style parameter the URL carried, unresolved. */
   campaignParams: z24.record(z24.string(), z24.string()),
@@ -23060,7 +23139,22 @@ function shapeHints(data) {
   }
   return hints;
 }
-function buildAnalyticsHints(data) {
+function adHierarchyHints(data, platform) {
+  if (platform === void 0) return [];
+  const traffic = (data.adPlatformTraffic ?? []).find((entry) => entry.platform === platform);
+  if (traffic === void 0 || traffic.sessions < MIN_SESSIONS_FOR_TAGGING_CLAIM) return [];
+  if (traffic.taggedSessions === 0) return [];
+  const carried = new Set(
+    (data.adParams ?? []).filter((row) => row.role !== void 0 && row.awaitingTraffic !== true).map((row) => row.role)
+  );
+  const missing = essentialAdDimensions(platform).filter((entry) => !carried.has(entry.role));
+  if (missing.length === 0) return [];
+  const suffix = missing.map((entry) => `${entry.names[0] ?? entry.role}=${entry.macro}`).join("&");
+  return [
+    `${platform} traffic carries no ${missing.map((entry) => AD_PARAM_ROLE_SPECS[entry.role].label.toLowerCase()).join(", ")}, so no report can say which ad sent a visit \u2014 only which platform. Add \`${suffix}\` to that account's tracking template. This cannot be backfilled: a parameter's values are only stored once it starts arriving.`
+  ];
+}
+function buildAnalyticsHints(data, platform) {
   const hints = [];
   for (const funnel of data.funnels ?? []) {
     const worst = funnel.worstStep;
@@ -23086,6 +23180,7 @@ function buildAnalyticsHints(data) {
     );
   }
   hints.push(...shapeHints(data));
+  hints.push(...adHierarchyHints(data, platform));
   if ((data.topCampaigns ?? []).length === 0 && (data.topSources ?? []).length > 0) {
     hints.push(
       "No campaign tagging on any traffic \u2014 ad clicks cannot be attributed to a campaign until the destination URLs carry utm parameters."
@@ -23514,6 +23609,8 @@ function requestBody(args, options) {
 async function runPreset(args, options) {
   try {
     const response = await apiPost("/api/analytics/query", requestBody(args, options));
+    const requestedPlatform = args.platform === void 0 ? "" : String(args.platform);
+    const adPlatformScope = isAdPlatform(requestedPlatform) ? requestedPlatform : void 0;
     const format = args.output === void 0 ? "json" : String(args.output);
     if (!isAnalyticsOutputFormat(format)) {
       writeJsonEnvelope({
@@ -23527,7 +23624,11 @@ async function runPreset(args, options) {
     }
     const data = pruneForAgent(response.data, args.full === true);
     const hints = [
-      ...buildAnalyticsHints(response.data),
+      // The platform the ad blocks were scoped to, so the tagging hint can
+      // only speak about the inventory it was actually given. `adParams` is one
+      // platform's list; a hint drawn from it without knowing which platform
+      // would be a claim about Meta made from Google's URLs.
+      ...buildAnalyticsHints(response.data, adPlatformScope),
       ...missingBreakdownHint(response.data, {
         eventName: options.eventName,
         property: options.property