@koda-sl/baker-cli 0.236.0 → 0.238.0-dev.7fb8e0c69

package/dist/cli.js

@@ -58,7 +58,7 @@ import {
   ulid,
   validateCanvasDeep,
   ytDlpBlockSignal
-} from "./chunk-EKLAHWSF.js";
+} from "./chunk-CMPAHYLB.js";
 import {
   csvOrJson,
   daysAgoIso,
@@ -4461,6 +4461,24 @@ var FLOW_SIDE_EFFECT_CATALOG = [
     gotcha: "`eventTagId` comes from X Events Manager and is passed verbatim. `eventName` is an optional label only.",
     reference: TAGS_REF
   },
+  {
+    kind: "side-effect",
+    type: "microsoftAds",
+    summary: "Fires a Microsoft Ads (UET) conversion event.",
+    skeleton: {
+      ...SIDE_EFFECT_ENVELOPE,
+      type: "microsoftAds",
+      tagIds: TAG_REF_SLOT,
+      eventName: "<UET event action, e.g. lead_submitted>",
+      userMatching: matchingSlots("em", "ph"),
+      value: null,
+      currency: null,
+      transactionId: null
+    },
+    owners: { tagIds: "tags" },
+    gotcha: "`eventName` is the UET *event action*, and it only counts as a conversion once someone creates a matching custom-event conversion goal in Microsoft Advertising \u2014 the tag alone records nothing. `page_view` is refused outright (UET reserves it for SPA navigation), so pick any other action. `eventCategory` and `eventLabel` are optional plain strings (not mapped slots) \u2014 add them only when the goal filters on them. `userMatching` needs Enhanced conversions turned on for that goal, and `ph` must carry a country code (`+34\u2026`/`0034\u2026`) \u2014 map it from a phone field with the country picker, not a plain text field, or it is dropped rather than guessed at.",
+    reference: TAGS_REF
+  },
   eventSideEffect("posthog", "Captures a PostHog event.", { eventParams: [] }),
   {
     kind: "side-effect",
@@ -5902,7 +5920,8 @@ var TAG_TYPES = [
   "posthog",
   "datafast",
   "recaptcha",
-  "twitterAds"
+  "twitterAds",
+  "microsoftAds"
 ];
 var tagTypeSchema = z19.enum(TAG_TYPES);
 var TAG_IDENTIFYING_FIELD = {
@@ -5923,7 +5942,8 @@ var TAG_IDENTIFYING_FIELD = {
   posthog: "projectToken",
   datafast: "websiteId",
   recaptcha: "siteKey",
-  twitterAds: "pixelId"
+  twitterAds: "pixelId",
+  microsoftAds: "tagId"
 };
 var tagDraftOpKindSchema = z19.enum(["create", "update", "delete"]);
 var tagDraftOpViewSchema = z19.object({
@@ -11347,6 +11367,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 +11441,9 @@ var AD_PLATFORMS = [
   "pinterest",
   "snapchat"
 ];
+function isAdPlatform(value) {
+  return AD_PLATFORMS.includes(value);
+}
 var GOOGLE = {
   platform: "google",
   label: "Google Ads",
@@ -11557,6 +11636,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 +12444,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 +13015,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 +23159,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 +23200,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 +23629,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 +23644,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
@@ -33719,6 +33840,10 @@ var MAPPING_SLOTS = {
   twitterAds: [
     { kind: "record", key: "userMatching", allowed: ["em", "ph"] },
     { kind: "scalar", keys: ["value", "currency"] }
+  ],
+  microsoftAds: [
+    { kind: "record", key: "userMatching", allowed: ["em", "ph"] },
+    { kind: "scalar", keys: ["value", "currency", "transactionId"] }
   ]
 };
 var UNMAPPABLE = {