@koda-sl/baker-cli 0.241.0 → 0.242.0

package/dist/cli.js

@@ -12529,6 +12529,20 @@ var analyticsCampaignRowSchema = z24.object({
   utmSource: z24.string(),
   utmMedium: z24.string(),
   utmCampaign: z24.string(),
+  /**
+   * The platform a click id proves, or `""` when the visit carried none.
+   *
+   * What separates a campaign the ad breakdown already reports — with its
+   * platform proven and its ad set and ad underneath — from one nothing else
+   * can show: the newsletter, the partner link, the hand-tagged post. The two
+   * are otherwise identical, because `utm_campaign={campaignid}` is the normal
+   * tagging convention and produces the same ids in both places.
+   *
+   * Kept on the row rather than filtered out here: a CLI hint reads an empty
+   * campaign list as "no campaign tagging on any traffic", and dropping the
+   * paid ones would make that fire on a perfectly tagged account.
+   */
+  clickPlatform: z24.string(),
   sessions: z24.number().int().nonnegative(),
   conversions: z24.number().int().nonnegative(),
   conversionRate: z24.number().min(0).max(1).nullable()
@@ -13241,7 +13255,8 @@ var analyticsTrackingPlatformSchema = z24.object({
   /** The pairs to append to the account's tagging, or `""`. */
   suffix: z24.string(),
   whereItGoes: z24.string(),
-  fix: z24.string().optional()
+  /** Which level to put them at, who can write it, and how an existing value is treated. */
+  fix: z24.string()
 });
 var analyticsTrackingResponseSchema = z24.object({
   ok: z24.literal(true),
@@ -23296,8 +23311,18 @@ function buildAnalyticsHints(data, platform) {
       "No campaign tagging on any traffic \u2014 ad clicks cannot be attributed to a campaign until the destination URLs carry utm parameters."
     );
   }
+  hints.push(...campaignOriginHints(data.topCampaigns));
   return hints;
 }
+function campaignOriginHints(rows) {
+  const campaigns = rows ?? [];
+  const fromAds = campaigns.filter((row) => row.clickPlatform !== "");
+  if (fromAds.length === 0) return [];
+  const own = campaigns.length - fromAds.length;
+  return [
+    `${fromAds.length} of these campaigns arrived on an ad click (\`clickPlatform\` is set). \`baker analytics ads --role campaign_id\` MAY report the same campaigns under the platform's own ids \u2014 check before you quote both, or you will count one campaign twice. It may equally report nothing: \`ads\` only reads parameters the account tags separately, and \`utm_campaign\` is reserved and never reaches it, so an account whose only campaign signal is \`utm_campaign\` has its campaigns HERE and nowhere else. Never report "no campaigns" on the strength of an empty \`ads\`. ${own === 0 ? "Every row here came from an ad." : `The other ${own} carry no click id at all \u2014 a newsletter, a partner link, a tagged post \u2014 and only this report can show them.`}`
+  ];
+}
 
 // src/commands/analytics/presets.ts
 var ANALYTICS_PRESET_INFO = [
@@ -24019,7 +24044,7 @@ var trackingCommand = (() => {
 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
+  missing  \u2014 nothing carries it. \`fix\` says which LEVELS that platform accepts tagging at (widest first \u2014 prefer it), which Baker can stage and which the user must do by hand, and how each field treats what is already in it. \`suffix\` is only the MISSING pairs, so read the current value, add them, write the union. 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.