@koda-sl/baker-cli 0.236.0 → 0.237.0-dev.b9732c021

package/dist/cli.js

@@ -58,7 +58,7 @@ import {
   ulid,
   validateCanvasDeep,
   ytDlpBlockSignal
-} from "./chunk-EKLAHWSF.js";
+} from "./chunk-CMPAHYLB.js";
 import {
   csvOrJson,
   daysAgoIso,
@@ -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()),
+  /**
+   * 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.
    */
-  channels: z24.array(z24.string())
+  channelSessions: z24.array(z24.number().int().nonnegative())
 });
 var analyticsTagRowSchema = z24.object({
   tag: z24.string(),
@@ -12487,7 +12559,9 @@ var analyticsDimensionRowSchema = z24.object({
 var analyticsFunnelStepSchema = z24.object({
   stepId: z24.string(),
   stepIndex: z24.number().int().nonnegative(),
+  /** Visits that moved forward into this step. Never events — see `visits`. */
   views: z24.number().int().nonnegative(),
+  /** Visits that finished this step and moved on. */
   completions: z24.number().int().nonnegative(),
   /** Share of viewers who did not complete this step, 0–1. */
   dropRate: z24.number().min(0).max(1).nullable(),
@@ -12503,9 +12577,25 @@ var analyticsFunnelStepSchema = z24.object({
 });
 var analyticsFunnelSchema = z24.object({
   flowSlug: z24.string(),
+  /**
+   * Visits that saw the Form at all — the denominator for every share here.
+   *
+   * Read this, not `starts`, whenever the question is "out of how many". A
+   * start is recorded at the visitor's FIRST INTERACTION, so the two differ by
+   * exactly the people who looked at the Form and never touched it — usually
+   * most of them, and always the group a drop-off chart exists to find.
+   *
+   * Every count in this object is distinct visits, including each step's
+   * `views` and `completions`. That is load-bearing rather than incidental:
+   * the screen divides these by each other, and while the steps counted events
+   * a Form four people had opened reported one step reached fifteen times and
+   * fourteen people lost.
+   */
+  visits: z24.number().int().nonnegative(),
+  /** Visits that interacted with the Form at all — typed, picked, or advanced. */
   starts: z24.number().int().nonnegative(),
   submits: z24.number().int().nonnegative(),
-  /** Submits per start, 0–1. */
+  /** Conversions per visit that opened the Form, 0–1. */
   completionRate: z24.number().min(0).max(1).nullable(),
   /** The step losing the most people. The single most useful field here. */
   worstStep: analyticsFunnelStepSchema.nullable(),
@@ -12923,7 +13013,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 +23157,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 +23198,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 +23627,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 +23642,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
@@ -23586,7 +23705,7 @@ var funnelCommand = presetCommand({
 var flowCommand = presetCommand({
   name: "flow",
   preset: "flow",
-  description: "One Form in depth: how many people it converted, where they went between steps, the per-step table, and every trigger it raised. Read `flowSummary.convertedSessions`, not `submits` \u2014 a Form that books a call on a scheduling node in the MIDDLE of the flow never emits a submit, so it reports zero submits and every one of its real bookings as conversions. `flowPaths` is the flow as edges between steps, bracketed by __flow_start__, __flow_converted__ and __flow_exit__, which is how a branching Form is read at all: a per-step table cannot say that of the people who left step two, forty went to the booking branch and ninety went nowhere.",
+  description: "One Form in depth: how many people it converted, where they went between steps, the per-step table, and every trigger it raised. Every count is DISTINCT VISITS, so quote shares against `funnels[].visits` \u2014 the visits that opened the Form \u2014 and never against `starts`, which is only the visits that touched it. The gap between the two is people who read the Form and left, and on most Forms it is the largest loss there is. Read `flowSummary.convertedSessions`, not `submits` \u2014 a Form that books a call on a scheduling node in the MIDDLE of the flow never emits a submit, so it reports zero submits and every one of its real bookings as conversions. `flowPaths` is the flow as edges between steps, bracketed by __flow_start__, __flow_converted__ and __flow_exit__, which is how a branching Form is read at all: a per-step table cannot say that of the people who left step two, forty went to the booking branch and ninety went nowhere.",
   extraArgs: { flow: { type: "string", description: "Form slug (default: every Form)", required: false } },
   resolve: (args) => ({ preset: "flow", flowSlug: args.flow ? String(args.flow) : void 0 })
 });