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

package/dist/cli.js

@@ -58,7 +58,7 @@ import {
   ulid,
   validateCanvasDeep,
   ytDlpBlockSignal
-} from "./chunk-CMPAHYLB.js";
+} from "./chunk-EKLAHWSF.js";
 import {
   csvOrJson,
   daysAgoIso,
@@ -4461,24 +4461,6 @@ 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",
@@ -5920,8 +5902,7 @@ var TAG_TYPES = [
   "posthog",
   "datafast",
   "recaptcha",
-  "twitterAds",
-  "microsoftAds"
+  "twitterAds"
 ];
 var tagTypeSchema = z19.enum(TAG_TYPES);
 var TAG_IDENTIFYING_FIELD = {
@@ -5942,8 +5923,7 @@ var TAG_IDENTIFYING_FIELD = {
   posthog: "projectToken",
   datafast: "websiteId",
   recaptcha: "siteKey",
-  twitterAds: "pixelId",
-  microsoftAds: "tagId"
+  twitterAds: "pixelId"
 };
 var tagDraftOpKindSchema = z19.enum(["create", "update", "delete"]);
 var tagDraftOpViewSchema = z19.object({
@@ -11922,19 +11902,22 @@ var analyticsBeaconPayloadSchema = z23.object({
 });
 
 // ../api/src/analytics/trackingTemplate.ts
-var VALUETRACK_ROLES = {
-  keyword: "keyword",
-  matchtype: "match_type",
-  campaignid: "campaign_id",
-  adgroupid: "adgroup_id",
-  creative: "ad_id",
-  placement: "placement",
-  network: "network",
-  device: "device",
-  product_id: "product_id",
-  merchant_id: "product_id",
-  product_partition_id: "product_id"
+function placeholderKey(raw) {
+  return raw.replace(/[{}]/g, "").replace(/^_+|_+$/g, "").trim().toLowerCase();
+}
+var EXTRA_PLACEHOLDER_ROLES = {
+  google: {
+    merchant_id: "product_id",
+    product_partition_id: "product_id"
+  }
 };
+function placeholderRoles(platform) {
+  const roles = {};
+  for (const dimension of AD_PLATFORM_DEFINITIONS[platform].dimensions) {
+    roles[placeholderKey(dimension.macro)] = dimension.role;
+  }
+  return { ...roles, ...EXTRA_PLACEHOLDER_ROLES[platform] ?? {} };
+}
 function paramsFromTemplate(template) {
   const start = template.indexOf("?");
   const query = start === -1 ? template : template.slice(start + 1);
@@ -11950,13 +11933,13 @@ function paramsFromTemplate(template) {
 }
 function proposeMappingFromTemplate(template, platform) {
   const builtIn = builtinAdParamMapping(platform);
+  const vocabulary = placeholderRoles(platform);
   const proposed = {};
   const unexplained = [];
   for (const param of paramsFromTemplate(template)) {
     if (RESERVED_PARAM_NAMES.includes(param.name)) continue;
     if (param.name in builtIn) continue;
-    const placeholder = param.value.startsWith("{") && param.value.endsWith("}") ? param.value.slice(1, -1).toLowerCase() : "";
-    const role = VALUETRACK_ROLES[placeholder];
+    const role = vocabulary[placeholderKey(param.value)];
     if (role) {
       proposed[param.name] = role;
       continue;
@@ -13171,10 +13154,74 @@ var analyticsMappingResponseSchema = z24.object({
      * turn configuring `keyword` to mean keyword.
      */
     builtIn: z24.array(z24.string()),
+    /**
+     * What the client's own ad account says about each parameter just staged.
+     *
+     * Present only when a Session staged a `set` on a platform whose tracking
+     * configuration Baker can read. `contradicted` is the entry worth stopping
+     * for: the account fills that name with a placeholder meaning something
+     * else, so the answer just given would produce a report that is wrong and
+     * looks entirely plausible.
+     */
+    evidence: z24.record(
+      z24.string(),
+      z24.object({
+        status: z24.enum(["confirmed", "contradicted", "unseen", "not_read"]),
+        macro: z24.string().optional(),
+        suggestedRole: adParamRoleSchema.optional(),
+        source: z24.string().optional(),
+        reason: z24.string().optional()
+      })
+    ).optional(),
     updatedAt: z24.number().nullable()
   }),
   hints: z24.array(z24.string()).optional()
 });
+var analyticsTrackingRequestSchema = z24.object({
+  platform: z24.enum(AD_PLATFORMS).optional(),
+  days: z24.number().int().min(1).max(365).optional()
+});
+var trackingDimensionSchema = z24.object({
+  role: adParamRoleSchema,
+  /** The platform's own macro for it — what goes in the URL. */
+  macro: z24.string(),
+  /** The account's own spelling where it has one, else the canonical name. */
+  name: z24.string(),
+  /**
+   * What has to happen for this dimension to reach a report.
+   *
+   * Four states rather than a boolean, because two of them need opposite fixes
+   * and one of them is not a finding at all. `unmapped` is one
+   * `baker analytics map` call and repairs the history with it; `missing` is a
+   * change to the ad account and everything before it stays unattributable;
+   * `unknown` means no visit arrived and the account could not be read, which
+   * must never be reported as untagged.
+   */
+  state: z24.enum(["covered", "unmapped", "missing", "unknown"]),
+  evidence: z24.string().optional(),
+  note: z24.string().optional()
+});
+var analyticsTrackingPlatformSchema = z24.object({
+  platform: z24.enum(AD_PLATFORMS),
+  label: z24.string(),
+  sessions: z24.number(),
+  /** Whether the ad account itself could be read, and why not when it could not. */
+  account: z24.object({ read: z24.boolean(), templates: z24.number(), reason: z24.string().optional() }),
+  dimensions: z24.array(trackingDimensionSchema),
+  /** Names the URLs already carry that Baker does not read yet. */
+  unmapped: z24.record(z24.string(), adParamRoleSchema),
+  mapCommand: z24.string(),
+  unexplained: z24.array(z24.object({ name: z24.string(), value: z24.string() })),
+  /** The pairs to append to the account's tagging, or `""`. */
+  suffix: z24.string(),
+  whereItGoes: z24.string(),
+  fix: z24.string().optional()
+});
+var analyticsTrackingResponseSchema = z24.object({
+  ok: z24.literal(true),
+  data: z24.object({ days: z24.number(), platforms: z24.array(analyticsTrackingPlatformSchema) }),
+  hints: z24.array(z24.string()).optional()
+});
 var submissionRecordRequestSchema = z24.object({
   /** Injected by the Worker from the host or the site key. Never from the page. */
   companyId: z24.string().min(1),
@@ -23883,13 +23930,13 @@ var mapCommand = (() => {
   };
   registerSchema({
     command: "analytics.map",
-    description: "Set how this company's campaign URLs spell each ad dimension",
+    description: "Stage how this company's campaign URLs spell each ad dimension, applied on publish",
     args
   });
   return defineCommand88({
     meta: {
       name: "map",
-      description: "Teach Baker how this company's campaign URLs spell each ad dimension on one platform \u2014 `--platform google --set kw=keyword`. Run it with no flags to see the whole mapping. Mappings are always per platform, because the platforms do not describe the same world: `builtIn` in the response is what that platform is already understood to send, so you do not spend a turn mapping `keyword` to keyword. Takes effect within seconds. Renaming a parameter Baker already captured fixes the history too, because roles are applied when a report is read; naming one it never read only starts collecting it, since no value was stored. You do NOT need to have seen a parameter to map it: a name nobody has sent yet is a valid --set, which is how a tracking template gets configured before the campaign that uses it runs. To drop an answer, --remove takes it back to whatever Baker knows by itself, and --set <name>=ignore says it is not campaign information at all so it stops being listed."
+      description: "Teach Baker how this company's campaign URLs spell each ad dimension on one platform \u2014 `--platform google --set kw=keyword`. Run it with no flags to see the whole mapping, including what this chat has already staged. STAGED, not applied: the answers are reviewed in the chat and take effect when it is published, so nothing you map here changes a report or what the edge stores until then; discarding the chat takes them all back. Mappings are always per platform, because the platforms do not describe the same world: `builtIn` in the response is what that platform is already understood to send, so you do not spend a turn mapping `keyword` to keyword. Each --set is checked against the client's OWN ad account \u2014 `evidence` in the response says whether their tracking template really fills that name with what you claimed. Read it: `contradicted` means the account disagrees, and mapping it your way would produce a report that is wrong and looks plausible. Renaming a parameter Baker already captured fixes the history too, because roles are applied when a report is read; naming one it never read only starts collecting it from the publish onward, since no value was stored. You do NOT need to have seen a parameter to map it: a name nobody has sent yet is a valid --set, which is how a tracking template gets configured before the campaign that uses it runs. To drop an answer, --remove takes it back to whatever Baker knows by itself, and --set <name>=ignore says it is not campaign information at all so it stops being listed."
     },
     args,
     run: async ({ args: raw }) => {
@@ -23907,6 +23954,61 @@ var mapCommand = (() => {
     }
   });
 })();
+var trackingCommand = (() => {
+  const args = {
+    platform: {
+      type: "string",
+      description: "One platform: google, meta, microsoft, linkedin, tiktok, reddit, pinterest, snapchat. Omit to check the ones worth checking \u2014 every platform sending visits, plus Google and Meta, whose accounts Baker can read directly",
+      required: false
+    },
+    days: { type: "string", description: "Lookback window for the traffic half (default: 30)", required: false }
+  };
+  registerSchema({
+    command: "analytics.tracking",
+    description: "Check whether a platform's ad URLs carry the campaign, ad group and ad a report needs",
+    args
+  });
+  return defineCommand88({
+    meta: {
+      name: "tracking",
+      description: `Check whether this company's ad URLs carry the dimensions any budget decision needs \u2014 the campaign, the ad group, the ad, and the keyword where the platform has one.
+
+Read this before auditing an ad account and before answering any "which ad performed best" question. Each dimension comes back in one of four states, and they need different things:
+  covered  \u2014 arriving and understood, nothing to do
+  unmapped \u2014 the URLs carry it under a name Baker does not read yet. Free to fix, and it repairs the traffic already collected: run the \`mapCommand\` in the response
+  missing  \u2014 nothing carries it. Add \`suffix\` to the account's tagging (\`whereItGoes\` says where, \`fix\` says whether Baker can stage it). This one cannot be filled in later \u2014 a parameter's values are only stored once it starts arriving
+  unknown  \u2014 no visit arrived AND the account could not be read. Not a finding; do not report it as untagged
+
+Baker reads the client's own Google tracking templates and Meta URL parameters, so a platform that has not run yet still gets a real answer.
+
+Examples:
+  baker analytics tracking
+  baker analytics tracking --platform meta
+  baker analytics tracking --platform google --days 90`
+    },
+    args,
+    run: async ({ args: raw }) => {
+      try {
+        const platform = raw.platform === void 0 ? void 0 : String(raw.platform);
+        if (platform !== void 0 && !isAdPlatform(platform)) {
+          writeJsonEnvelope({
+            ok: false,
+            error: { code: "BAD_REQUEST", message: `Unknown platform "${platform}"` }
+          });
+          process.exit(1);
+        }
+        const days = raw.days === void 0 ? void 0 : Number(raw.days);
+        const response = await apiPost("/api/analytics/tracking", {
+          ...platform ? { platform } : {},
+          ...days !== void 0 && Number.isFinite(days) ? { days } : {}
+        });
+        writeJsonEnvelope(response);
+      } catch (err) {
+        handleError(err);
+      }
+    }
+  });
+})();
 function parsePairs(raw) {
   if (raw === void 0) return void 0;
   const out = {};
@@ -23955,7 +24057,9 @@ Examples:
   baker analytics ads --role keyword          \u2014 keywords by conversions AND by how many bounced
   baker analytics ads --platform google --role keyword \u2014 the same, in Google's vocabulary and from Google's traffic only
   baker analytics overview --role keyword --value "solar panels" \u2014 the whole report for those visits only
-  baker analytics map --platform google --set kw=keyword   \u2014 teach it a parameter name, seen or not yet
+  baker analytics tracking                    \u2014 do the ad URLs carry the campaign, ad group and ad at all
+  baker analytics tracking --platform meta    \u2014 the same for one platform, read from their own ad account
+  baker analytics map --platform google --set kw=keyword   \u2014 stage a parameter name, seen or not yet
   baker analytics map --platform google --remove kw        \u2014 take that answer back
   baker analytics delivery --page 2 --page-size 50         \u2014 the next page of a long list
   baker analytics overview --compare          \u2014 this window against the one before it
@@ -23980,6 +24084,7 @@ Full guide: __tooling__/docs/tools/baker/analytics.md`
     devices: devicesCommand,
     ads: adsCommand3,
     map: mapCommand,
+    tracking: trackingCommand,
     presets: presetsCommand
   }
 });
@@ -33840,10 +33945,6 @@ 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 = {