@koda-sl/baker-cli 0.238.0-dev.7fb8e0c69 → 0.239.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;
@@ -12579,7 +12562,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(),
@@ -12591,13 +12576,37 @@ var analyticsFunnelStepSchema = z24.object({
    * conversion, and knowing which step owns it is what stops a drop-off chart
    * treating the booking widget's "profile viewed" as a funnel stage.
    */
-  convertedSessions: z24.number().int().nonnegative()
+  convertedSessions: z24.number().int().nonnegative(),
+  /**
+   * This step is where the Form ends — a confirmation screen, not a loss.
+   *
+   * Stated rather than left to be inferred. The dashboard used to read it off
+   * `dropRate === null`, which is also how a step nobody viewed arrives, so a
+   * converting link node in the middle of a Form was labelled its ending.
+   */
+  isEnding: z24.boolean()
 });
 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(),
@@ -13171,10 +13180,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),
@@ -23707,7 +23780,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 })
 });
@@ -23883,13 +23956,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 +23980,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 +24083,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 +24110,7 @@ Full guide: __tooling__/docs/tools/baker/analytics.md`
     devices: devicesCommand,
     ads: adsCommand3,
     map: mapCommand,
+    tracking: trackingCommand,
     presets: presetsCommand
   }
 });
@@ -33840,10 +33971,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 = {