@koda-sl/baker-cli 0.293.0 → 0.294.0-dev.ae1dcf96d

package/dist/cli.js

@@ -58,7 +58,7 @@ import {
   ulid,
   validateCanvasDeep,
   ytDlpBlockSignal
-} from "./chunk-NNQDWCFG.js";
+} from "./chunk-2IHIUOJX.js";
 import {
   csvOrJson,
   daysAgoIso,
@@ -11431,6 +11431,45 @@ import { appendFileSync, existsSync as existsSync2, readFileSync as readFileSync
 import { resolve } from "path";
 import { defineCommand as defineCommand28 } from "citty";
 
+// src/commands/ads/google/conversion-mix.ts
+var CONVERSION_METRICS = [
+  "METRICS.CONVERSIONS",
+  "METRICS.ALL_CONVERSIONS",
+  "METRICS.CONVERSIONS_VALUE",
+  "METRICS.ALL_CONVERSIONS_VALUE",
+  "METRICS.COST_PER_CONVERSION",
+  "METRICS.COST_PER_ALL_CONVERSIONS",
+  "METRICS.CONVERSIONS_FROM_INTERACTIONS_RATE",
+  "METRICS.ALL_CONVERSIONS_FROM_INTERACTIONS_RATE",
+  "METRICS.VALUE_PER_CONVERSION",
+  "METRICS.VALUE_PER_ALL_CONVERSIONS"
+];
+var CONVERSION_SEGMENTS = ["SEGMENTS.CONVERSION_ACTION_NAME", "SEGMENTS.CONVERSION_ACTION="];
+var CAMPAIGN_EQUALITY = /\bCAMPAIGN\.(ID|NAME|RESOURCE_NAME)\s*=/;
+function whereClause(upperQuery) {
+  const whereIdx = upperQuery.indexOf(" WHERE ");
+  if (whereIdx === -1) return "";
+  let rest = upperQuery.slice(whereIdx + 7);
+  for (const trailing of [" ORDER BY ", " GROUP BY ", " LIMIT ", " PARAMETERS "]) {
+    const idx = rest.indexOf(trailing);
+    if (idx !== -1) rest = rest.slice(0, idx);
+  }
+  return rest;
+}
+function conversionMixWarnings(finalQuery) {
+  const upper2 = ` ${finalQuery.toUpperCase().replace(/\s+/g, " ")} `;
+  const readsConversions = CONVERSION_METRICS.some((metric) => upper2.includes(metric));
+  if (!readsConversions) return [];
+  if (CONVERSION_SEGMENTS.some((segment) => upper2.includes(segment))) return [];
+  if (CAMPAIGN_EQUALITY.test(whereClause(upper2))) return [];
+  return [
+    {
+      code: "CONVERSION_MIX",
+      message: "MIXED CONVERSION ACTIONS \u2014 this read covers more than one campaign, and a campaign's conversion figures count whatever conversion actions are primary for it. Those differ campaign by campaign (a webinar registration, an info request, a CRM-stage SQL), so a total across these rows adds different events and a conversion rate from one campaign is not comparable with another's. Before totalling or comparing, re-run segmented by segments.conversion_action_name and check the campaigns you are putting side by side count the same action. If they do not, compare only within one action \u2014 and carry that caveat into anything you write for the user, not just the analysis."
+    }
+  ];
+}
+
 // src/commands/ads/google/keyword-serving.ts
 var BELOW_FIRST_PAGE_BID = "AD_GROUP_CRITERION_BELOW_FIRST_PAGE_BID";
 var ACTIONABLE_REASONS = {
@@ -11584,6 +11623,14 @@ var PRESETS = [
     defaultLimit: 200,
     statusFields: ["campaign.status"]
   },
+  {
+    name: "conversions-by-action",
+    description: "Which conversion action each campaign's conversions actually are \u2014 the read that says whether two campaigns' conversion rates are measuring the same event",
+    gaqlTemplate: `SELECT campaign.id, campaign.name, segments.conversion_action_name, segments.conversion_action_category, metrics.conversions, metrics.all_conversions FROM campaign WHERE segments.date DURING {dateRange}{statusScope} ORDER BY metrics.conversions DESC LIMIT {limit}`,
+    defaultDateRange: "LAST_30_DAYS",
+    defaultLimit: 200,
+    statusFields: ["campaign.status"]
+  },
   {
     name: "keyword-analysis",
     description: "Keyword performance with match type and quality",
@@ -11705,7 +11752,7 @@ var RUNG_PIN_FIELDS = {
   "campaign_asset.status": ["campaign_asset.resource_name"],
   "ad_group_asset.status": ["ad_group_asset.resource_name"]
 };
-function whereClause(query) {
+function whereClause2(query) {
   const match = query.match(/\bWHERE\b([\s\S]*)$/i);
   if (!match?.[1]) return "";
   let rest = match[1];
@@ -11725,7 +11772,7 @@ function analyzeServingChain(query) {
   const resource = fromResource(query);
   const chain = resource ? SERVING_CHAINS[resource] : void 0;
   if (!chain) return null;
-  const where = whereClause(query);
+  const where = whereClause2(query);
   if (/ad_group_criterion\.negative\s*=\s*TRUE/i.test(where)) return null;
   const unscoped = chain.filter((rung) => {
     if (mentions(where, rung)) return false;
@@ -11965,7 +12012,7 @@ registerSchema({
     },
     preset: {
       type: "string",
-      description: "Named query preset. Reads (campaign-performance, keyword-analysis, keyword-serving, positive-keywords, negative-keywords, negative-keyword-lists, negative-list-attachments, search-terms, ad-copy-performance, asset-performance, shopping-products, account-summary). Presets return only actually-serving entities (enabled campaign AND ad group AND ad) by default \u2014 pass --include-paused to include paused ones.",
+      description: "Named query preset. Reads (campaign-performance, conversions-by-action, keyword-analysis, keyword-serving, positive-keywords, negative-keywords, negative-keyword-lists, negative-list-attachments, search-terms, ad-copy-performance, asset-performance, shopping-products, account-summary). Presets return only actually-serving entities (enabled campaign AND ad group AND ad) by default \u2014 pass --include-paused to include paused ones.",
       required: false
     },
     "date-range": {
@@ -12203,7 +12250,7 @@ var SERVING_HIERARCHY_RESOURCES = [
   "shopping_performance_view",
   "asset_group_asset"
 ].filter((resource) => !(resource in SERVING_CHAINS));
-function whereClause2(upperQuery) {
+function whereClause3(upperQuery) {
   const whereIdx = upperQuery.indexOf(" WHERE ");
   if (whereIdx === -1) return "";
   let rest = upperQuery.slice(whereIdx + 7);
@@ -12227,7 +12274,7 @@ function servingScopeWarnings(args, finalQuery) {
   const fromMatch = upper2.match(/\bFROM\s+([A-Z_]+)/);
   const resource = fromMatch?.[1]?.toLowerCase();
   const hierarchical = resource ? SERVING_HIERARCHY_RESOURCES.includes(resource) : false;
-  const filtersStatus = whereClause2(upper2).includes(".STATUS");
+  const filtersStatus = whereClause3(upper2).includes(".STATUS");
   if (hierarchical && !filtersStatus) {
     return [
       {
@@ -12329,6 +12376,7 @@ async function executeQuery(finalQuery, args, customerId, limit, warnings, useCa
       ...warnings,
       ...renderKeywordLimits(keywordLimits),
       ...missingFieldWarningsFor(finalQuery, observedFields, totalRowsWritten),
+      ...conversionMixWarnings(finalQuery),
       ...truncation
     ];
     emitToStderr(warningLines(fileWarnings, "csv"));
@@ -12350,7 +12398,12 @@ async function executeQuery(finalQuery, args, customerId, limit, warnings, useCa
   outputResults(
     allRows,
     getFieldDescriptions(fields),
-    [...warnings, ...missingFieldWarnings(finalQuery, allRows), ...keywordServingWarnings(allRows, servingOptions)],
+    [
+      ...warnings,
+      ...missingFieldWarnings(finalQuery, allRows),
+      ...keywordServingWarnings(allRows, servingOptions),
+      ...conversionMixWarnings(finalQuery)
+    ],
     args,
     false,
     {
@@ -12466,7 +12519,8 @@ Examples:
           [
             ...warnings,
             ...missingFieldWarnings(finalQuery, cached.data),
-            ...keywordServingWarnings(cached.data, keywordServingOptions(finalQuery))
+            ...keywordServingWarnings(cached.data, keywordServingOptions(finalQuery)),
+            ...conversionMixWarnings(finalQuery)
           ],
           args,
           true,
@@ -13273,10 +13327,52 @@ function mappingCommandFor(platform, proposed) {
 
 // ../api/src/analytics/websiteTag.ts
 import { z as z27 } from "zod";
+var websiteTagRequestSchema = z27.object({
+  measure: z27.enum(["campaigns", "outcomes", "all"]).optional()
+});
+var analyticsSitesRequestSchema = z27.object({
+  add: z27.array(z27.string()).optional(),
+  remove: z27.array(z27.string()).optional()
+});
+var analyticsSitesResponseSchema = z27.object({
+  /** Every declared website after the change, which is the answer to a bare read. */
+  origins: z27.array(z27.string()),
+  /** Normalized and actually new — an entry already present is reported in neither list. */
+  added: z27.array(z27.string()),
+  removed: z27.array(z27.string()),
+  /** Still-undeclared domains this company owns. See {@link suggestedPixelOrigins}. */
+  suggestedOrigins: z27.array(z27.string())
+});
 var websiteTagResponseSchema = z27.object({
   host: z27.string(),
   siteKey: z27.string(),
   origins: z27.array(z27.string()),
+  /** Echoed back, so a caller that asked for nothing can see what it got. */
+  measure: z27.enum(["campaigns", "outcomes", "all"]),
+  /**
+   * Whether `campaigns` scope can recognise anybody here — see
+   * {@link campaignsScopeCanMatch}. `false` means the default measures nobody
+   * on this company's install, however correctly the tag is pasted.
+   */
+  campaignsCanMatch: z27.boolean(),
+  /**
+   * Whether `host` is one of the company's own domains rather than Baker's.
+   *
+   * Worth answering because it is the difference between an install a content
+   * blocker removes and one it has no list entry for — the pixel takes its
+   * collect endpoint from its own `src`, so this decides the fate of the event
+   * stream and not just the script load. See {@link pixelHost}.
+   */
+  firstParty: z27.boolean(),
+  /**
+   * Websites this company plainly owns and has not declared — the registrable
+   * domains of its own landing domains. See {@link suggestedPixelOrigins}.
+   *
+   * A suggestion for somebody to accept, never a scope already granted: nothing
+   * in Baker reads this list, and `baker analytics sites --add` is what acts on
+   * it.
+   */
+  suggestedOrigins: z27.array(z27.string()),
   tag: z27.string(),
   brief: z27.string()
 });
@@ -27901,7 +27997,7 @@ one marked "Already counted", so a retry is visible without being counted.
 
 The same holds **across connections**, which is the reason to use it. If the page also
 reports this outcome with Baker's website tag, pass one string as \`event_id\` here and as
-\`eventId\` in \`window.baker.conversion(name, { eventId })\`: the browser event and the
+\`eventId\` in \`window.baker.track(name, { eventId })\`: the browser event and the
 server event are then one event and count once, whichever arrives first and whether or not
 the other ever does. Report an important outcome from both \u2014 a browser can be blocked, a
 server cannot \u2014 and always pair them with an id. Send no id and the two are two conversions,
@@ -28990,6 +29086,73 @@ function formatHint(data, format) {
   ];
 }
 
+// src/commands/analytics/websiteTagHints.ts
+function asTyped(origin) {
+  return origin.replace(/^https?:\/\//, "");
+}
+function suggestionHint(suggested) {
+  if (suggested.length === 0) return [];
+  const commands = suggested.map((origin) => `baker analytics sites --add ${asTyped(origin)}`).join("  \xB7  ");
+  return [
+    `Baker publishes landing pages on ${suggested.map(asTyped).join(", ")} for this company, and no declared website covers ${suggested.length === 1 ? "it" : "them"}. Declaring the domain covers every subdomain of it \u2014 the marketing site, the shop, the booking page, and the ones that do not exist yet: ${commands}`
+  ];
+}
+function websiteTagHints(response) {
+  const hints2 = [];
+  if (response.origins.length === 0) {
+    hints2.push(
+      "NO WEBSITE DECLARED \u2014 this tag will be ignored everywhere it is installed, silently, with no failing request to find. Declare the site before installing anything: baker analytics sites --add <the client's domain>. It takes effect at once and needs no republish."
+    );
+  }
+  hints2.push(...suggestionHint(response.suggestedOrigins));
+  if (response.firstParty) {
+    hints2.push(
+      `This tag loads from ${response.host} \u2014 the client's own domain, not Baker's \u2014 so the script and every event it sends travel first-party, which a content blocker has no list entry for. The trade is a dependency: if that domain is ever removed from Baker, this tag 404s and measurement stops. Re-run this command after any domain change.`
+    );
+  }
+  if (response.measure === "all") {
+    hints2.push(
+      "This tag measures the client's WHOLE WEBSITE \u2014 every visitor and every page view, not only the people your campaigns brought. Their reports will describe their business rather than their campaigns, and outcomes their site produces from organic, email and direct traffic will land in their conversion numbers. Only correct if somebody asked for that; otherwise re-run without --measure."
+    );
+  }
+  if (response.measure === "campaigns" && !response.campaignsCanMatch) {
+    hints2.push(
+      "THIS TAG WILL MEASURE NOBODY \u2014 and will look installed. `campaigns` scope recognises a visitor by a first-party cookie, and a browser does not carry one between two different registrable domains. This company's landings are not on a subdomain of the site this tag goes on, so no visitor can ever match. Two fixes: put the landings on a subdomain of the client's own domain (a custom domain in Baker), or install with --measure outcomes, which measures no browsing and reports the outcomes the site tells Baker about."
+    );
+  } else if (response.measure === "campaigns") {
+    hints2.push(
+      "This tag measures only visitors who have been on one of this company's Baker landing pages \u2014 their whole journey through the site, to the outcome. Anybody else is not measured at all. Use --measure all only if the client asked for their whole website measured."
+    );
+  }
+  hints2.push(
+    'Reporting an outcome is not the same as counting it. After a `window.baker.track("name")` call is live, name it with: baker analytics conversions --event page:<name> --name "<what to call it>". That applies immediately and counts everything already collected.'
+  );
+  return hints2;
+}
+function analyticsSitesHints(response) {
+  const hints2 = [];
+  if (response.origins.length === 0) {
+    hints2.push(
+      "No website is declared, so this company's measurement tag is ignored wherever it is installed \u2014 silently, with no failing request to find. Add one with: baker analytics sites --add <the client's domain>"
+    );
+  }
+  hints2.push(...suggestionHint(response.suggestedOrigins));
+  if (response.added.length > 0) {
+    hints2.push(
+      `Live now. A tag already installed on ${response.added.map(asTyped).join(", ")} starts being accepted immediately \u2014 there is no new tag to paste and nothing to publish. Only events sent from here on are kept; the ones refused before this were never stored and cannot be recovered.`
+    );
+  }
+  if (response.removed.length > 0) {
+    hints2.push(
+      `Measurement from ${response.removed.map(asTyped).join(", ")} will stop at once, with no error on that site \u2014 a tag still installed there goes quiet. Everything already collected from it is kept.`
+    );
+  }
+  hints2.push(
+    "One entry covers everything under it: example.com answers for www., go. and shop.eu. It never widens upward, so declaring go.example.com leaves example.com uncovered \u2014 declare the domain, not the subdomain you are installing on today."
+  );
+  return hints2;
+}
+
 // src/commands/analytics/index.ts
 var SHARED_ARGS = {
   days: { type: "string", description: "Lookback window in days (default: 30)", required: false },
@@ -29718,7 +29881,13 @@ var websiteTagCommand = (() => {
   registerSchema({
     command: "analytics.website-tag",
     description: "The measurement tag for a website Baker does not publish, with this company's key in it",
-    args: {}
+    args: {
+      measure: {
+        type: "string",
+        required: false,
+        description: 'Whose activity to measure: "campaigns" (default), "outcomes" or "all"'
+      }
+    }
   });
   return defineCommand95({
     meta: {
@@ -29727,18 +29896,83 @@ var websiteTagCommand = (() => {
 
 Reach for it whenever measurement has to reach a page Baker did not build. What it returns is real and complete: the tag, the websites the key is accepted from, and the rules for the hidden form fields, the identify call and the conversion call.
 
-Two things worth knowing before you install it:
+Three things worth knowing before you install it:
   the origins list                    \u2014 the key is IGNORED from any origin not on it, silently. An empty list means the tag will measure nothing.
   Tag Manager is usually the way in   \u2014 a Custom HTML tag on All Pages. If the client has a container connected, you can stage that yourself (baker tag-manager).
+  --measure decides the BILL          \u2014 the tag goes on every page whatever you do; this decides whose activity is measured. Leave it alone unless the client asked for their whole website.
+
+  --measure campaigns  (default)  people your Baker campaigns brought to the site. Their whole journey, through to the outcome. Nobody else is measured at all.
+  --measure outcomes              nobody's browsing. Only what the site reports with window.baker.track(...), and forms it wired to Baker.
+  --measure all                   every visitor and every page view of the whole website. Their reports then describe their business, not their campaigns, and outcomes from organic, email and direct land in their conversion numbers. A decision, never a default.
 
 Examples:
   baker analytics website-tag                   \u2014 the tag, the origins and the install brief
+  baker analytics website-tag --measure all     \u2014 measure their whole website, because they asked for that
   baker analytics events --origin site          \u2014 after it is live, what that website is reporting`
     },
-    args: {},
-    run: async () => {
+    args: {
+      measure: {
+        type: "string",
+        description: 'Whose activity to measure: "campaigns" (default), "outcomes" or "all". Widening is a decision \u2014 see above.'
+      }
+    },
+    run: async (ctx) => {
       try {
-        writeJsonEnvelope(await apiPost("/api/analytics/website-tag", {}));
+        const measure = typeof ctx.args.measure === "string" ? ctx.args.measure : void 0;
+        const envelope = await apiPost(
+          "/api/analytics/website-tag",
+          measure ? { measure } : {}
+        );
+        writeJsonEnvelope({ ...envelope, hints: websiteTagHints(envelope.data) });
+      } catch (err) {
+        handleError(err);
+      }
+    }
+  });
+})();
+var sitesCommand = (() => {
+  registerSchema({
+    command: "analytics.sites",
+    description: "The websites this company's measurement tag is accepted from, and adding or removing one",
+    args: {
+      add: { type: "string", required: false, description: "Website address to accept measurement from" },
+      remove: { type: "string", required: false, description: "Website address to stop accepting measurement from" }
+    }
+  });
+  return defineCommand95({
+    meta: {
+      name: "sites",
+      description: `Which websites this company's measurement tag is accepted from \u2014 and the command that changes it.
+
+The site key ships in the source of every page it is pasted on, so this list is the whole of what stops a stranger who read it appending forged conversions to these numbers. A tag on a website that is NOT on this list is ignored, silently, with no failing request anywhere. That is the single most common reason an install measures nothing.
+
+One entry covers the estate under it: example.com answers for www.example.com, go.example.com and shop.eu.example.com. It never widens upward \u2014 declaring go.example.com does NOT cover example.com \u2014 so declare the DOMAIN, not the subdomain you happen to be installing on today.
+
+Start here:
+  baker analytics sites                              \u2014 what is declared now, and what is worth adding
+  baker analytics sites --add example.com            \u2014 accept measurement from that site and everything under it
+  baker analytics sites --remove old-site.com
+
+Examples:
+  baker analytics website-tag                        \u2014 get the tag; if its origins are empty, come here first
+  baker analytics sites --add foodforjoe.es          \u2014 one entry covering www., go. and shop.`
+    },
+    args: {
+      add: {
+        type: "string",
+        description: "Website address to accept measurement from, e.g. example.com \u2014 covers every subdomain of it. Repeat for several"
+      },
+      remove: { type: "string", description: "Website address to stop accepting measurement from" }
+    },
+    run: async (ctx) => {
+      try {
+        const raw = ctx.rawArgs;
+        const body = {
+          add: repeatedValues(raw, "add", ctx.args.add),
+          remove: repeatedValues(raw, "remove", ctx.args.remove)
+        };
+        const envelope = await apiPost("/api/analytics/sites", body);
+        writeJsonEnvelope({ ...envelope, hints: analyticsSitesHints(envelope.data) });
       } catch (err) {
         handleError(err);
       }
@@ -29815,6 +30049,7 @@ Full guide: __tooling__/docs/tools/baker/analytics.md`
     arrivals: arrivalsCommand,
     "sending-events": sendingEventsCommand,
     "website-tag": websiteTagCommand,
+    sites: sitesCommand,
     presets: presetsCommand
   }
 });
@@ -44110,7 +44345,7 @@ function siteHints(sites) {
     resources: sites.map((site) => ({ id: site.siteUrl, label: site.permissionLevel }))
   });
 }
-var sitesCommand = defineCommand134({
+var sitesCommand2 = defineCommand134({
   meta: {
     name: "sites",
     description: `List verified Search Console sites.
@@ -44175,7 +44410,7 @@ Examples:
 Full guide: __tooling__/docs/tools/baker/gsc.md`
   },
   subCommands: {
-    sites: sitesCommand,
+    sites: sitesCommand2,
     query: queryCommand3,
     sitemaps: sitemapsCommand
   }