@koda-sl/baker-cli 0.295.1 → 0.296.0

package/README.md

@@ -1268,6 +1268,9 @@ baker analytics conversions --event page:a --count-mode every_time          # re
 baker analytics conversions --rename "Lead form" --to "Lead"                # merge two into one row
 baker analytics conversions --remove page:request_demo
 baker analytics conversions --remove-name "Lead"
+baker analytics sites                     # the websites the measurement tag is accepted from
+baker analytics sites --add example.com   # and every subdomain of it — applies at once, no publish
+baker analytics website-tag               # the tag for a site Baker does not publish, with the key in it
 baker analytics delivery --page 2         # the next page of a long list
 baker analytics submissions --flow contact  # every attempt at a Form, delivered or not
 ```
@@ -1280,6 +1283,13 @@ Shared flags: `--days <n>` (default 30) or `--start-date` / `--end-date` (`YYYY-
 - The `sparkline` on `landings` is dropped unless `--full`, and resampled to 30 points when present. It is bucketed by `--granularity` upstream, so ninety days at `hour` is 2,160 numbers per page.
 - Past ~25 rows the response carries a hint naming the row count and pointing at `--output md`.
 
+**Measuring a website Baker does not publish.** `baker analytics website-tag` returns the tag with this company's site key in it, the websites it is accepted from, and the whole install as Markdown. Two things decide whether it does anything:
+
+- **`baker analytics sites` first.** The key is public and is **silently ignored** from any origin not on the declared list, so a tag on an undeclared website is a perfect install that measures nothing, with no failing request anywhere. `--add` / `--remove` are repeatable, apply immediately, need no publish, and a tag already installed starts being accepted at once. Declare the **domain**, not the subdomain you happen to be installing on: one entry covers everything under it (`example.com` answers for `www.`, `go.` and `shop.eu.`) and it never widens upward. The response also carries `suggestedOrigins` — domains Baker already serves this company's landings on that nothing covers yet.
+- **The snippet is two scripts and both are required.** The first creates `window.baker` synchronously and queues calls; the second is the tag, which is async. Paste only the second and any outcome reported before it finishes loading reaches nothing — which on a thank-you page is the normal case. For the same reason, never guard a call with `if (!window.baker) return`: on the fastest pages that is always true, and it throws the conversion away with no error anywhere. Call `window.baker.track(…)` directly.
+
+`--measure` decides whose activity is measured and defaults to `campaigns` (only visitors a Baker landing brought). `--measure all` measures the client's entire website and is a decision somebody has to ask for. `host` is the client's own landing domain when one shares a domain with the site being measured, so the script and its events stay first-party; `firstParty` in the response says which, and removing that domain from Baker means re-running this command.
+
 **Paging the list reports.** `people`, `submissions` and `delivery` are lists of individual things rather than breakdowns — `delivery` and `submissions` are the ones the CLI exposes, `people` backs the People section of the dashboard's landing Analytics screen over the same wire — and only they take `--page <n>` (1-based) and `--page-size <n>` (up to 200, default 50). The response carries `pageInfo` with `hasMore` — when it is true there **are** more rows, so a total must never be reported from one page. Pass neither flag and a list comes back at the size it always did.
 
 **A conversion is a company-level named event, not a property of a Form.** `baker analytics conversions` is the only place "what counts" is decided, and an empty `definitions` list means every conversion number in every other report is zero — not because nobody converted, but because nothing is named as an outcome and Baker never guesses which event is the point of a page. `--candidates` lists every event these pages actually produced — each Form step and trigger, every `data-baker-*` event, every outbound destination — with volume and whether it is already counted; that list is where an event key comes from, so never invent one. `--event <key> --name "Booked a call"` starts counting it **immediately and retroactively**: the whole stored history is rescored, so naming the right event today also fixes last month. Nothing here is staged and publishing is not involved. Two events given the same `--name` become one row and one number, which is how a call booked on three different Forms reads as one outcome. `--count-mode every_time` is for the outcomes people genuinely repeat (a guide downloaded twice is two downloads); the default counts once per visit.

package/dist/cli.js

@@ -13327,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(),
   tagManagerTag: z27.string(),
   brief: z27.string()
@@ -13548,6 +13590,7 @@ var analyticsPresetSchema = z28.enum([
   "stream"
 ]);
 var ANALYTICS_PRESETS = analyticsPresetSchema.options;
+var ANALYTICS_EVENT_DOORS = ["pages", "website", "server"];
 var analyticsQueryRequestSchema = z28.object({
   preset: analyticsPresetSchema,
   /** Lookback in days. Ignored when `startDate` is given. */
@@ -13606,9 +13649,7 @@ var analyticsQueryRequestSchema = z28.object({
    */
   adPlatform: z28.enum(AD_PLATFORMS).optional(),
   /**
-   * Read only what one collector produced: `site` for everything Baker
-   * measured itself, `systems` for what a client's own server posted to
-   * `POST /v1/events`.
+   * Read only what came in by one door. See {@link ANALYTICS_EVENT_DOORS}.
    *
    * Omit it for all of it, which is the default and the honest superset.
    * Only the reads where the split is a question somebody asks honour it —
@@ -13617,7 +13658,7 @@ var analyticsQueryRequestSchema = z28.object({
    * ingest row carries no `session_id`, deliberately, so there is no visit
    * for it to be counted in.
    */
-  eventOrigin: z28.enum(["site", "systems"]).optional(),
+  eventOrigin: z28.enum(ANALYTICS_EVENT_DOORS).optional(),
   /**
    * `stream` only: keep just one kind of event, named by the key
    * `conversions` hands back in its catalogue.
@@ -14399,6 +14440,17 @@ var analyticsTimelineRowSchema = z28.object({
   eventType: z28.string(),
   /** `edge`, `beacon`, `server` — where the row was written from. */
   source: z28.string(),
+  /**
+   * `baker`, `external`, `export` — where the page was, which `source` does
+   * not say. The two together are what decide the row's door; see
+   * `ANALYTICS_EVENT_DOORS`.
+   *
+   * Defaulted rather than required: the column arrived after the corpus did
+   * and carries no default of its own, so a row older than it reads `""`, and
+   * that has to mean "Baker's, as everything was then" rather than fail the
+   * whole row's parse.
+   */
+  deployment: z28.string().default(""),
   environment: z28.string(),
   /** The build the page was published from. */
   release: z28.string(),
@@ -27956,7 +28008,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,
@@ -28689,7 +28741,7 @@ function adHierarchyHints(data, platform) {
 }
 function sessionlessHint(data, origin) {
   if (data.totals.pageViews === 0 || data.totals.sessions > 0) return [];
-  if (origin === "systems") {
+  if (origin === "server") {
     return [
       "No sessions, because this report is scoped to events a client's own server posted and those carry no visit \u2014 a session would be an invented one. Every per-visitor rate here is null for the same reason; read the counts, and drop --origin for anything about behaviour."
     ];
@@ -29045,6 +29097,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 },
@@ -29102,7 +29221,7 @@ var SHARED_ARGS = {
   },
   origin: {
     type: "string",
-    description: "Read one collector only: `site` for what Baker measured on its own pages, `systems` for what the client's own server posted to POST /v1/events. Omit it for both, which is the default and the honest superset. Reach for it when a number moved and nothing on the pages changed \u2014 a CRM replaying history lands in the same totals as a visitor, and this is the only thing that separates them. Honoured by overview, traffic, events and conversions; every session-scoped report ignores it, because a server-sent event carries no visit to be counted in",
+    description: "Read one door only: `pages` for a browser on a page Baker publishes, `website` for a browser on the client's OWN website (the measurement tag), `server` for what their server posted to POST /v1/events. Omit it for all three, which is the default and the honest superset. Reach for it when a number moved and nothing on the pages changed \u2014 a CRM replaying history and a tag on the client's own site both land in the same totals as a landing page visitor, and this is the only thing that separates them. Honoured by overview, traffic, events and conversions; every session-scoped report ignores it, because a server-sent event carries no visit to be counted in",
     required: false
   },
   output: {
@@ -29167,7 +29286,7 @@ function requestBody(args, options) {
     Object.entries(candidates).filter(([key, value]) => value !== void 0 && (value !== "" || key === "adValue"))
   );
 }
-var EVENT_ORIGINS = ["site", "systems"];
+var EVENT_ORIGINS = ANALYTICS_EVENT_DOORS;
 async function runPreset(args, options) {
   const origin = args.origin === void 0 ? "" : String(args.origin);
   if (origin !== "" && !EVENT_ORIGINS.includes(origin)) {
@@ -29175,7 +29294,7 @@ async function runPreset(args, options) {
       ok: false,
       error: {
         code: "VALIDATION_ERROR",
-        message: `Unknown --origin "${origin}". Use one of: ${EVENT_ORIGINS.join(", ")}, or omit it for both.`
+        message: `Unknown --origin "${origin}". Use one of: ${EVENT_ORIGINS.join(", ")}, or omit it for all three.`
       }
     });
     process.exit(1);
@@ -29773,7 +29892,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: {
@@ -29785,16 +29910,81 @@ Reach for it whenever measurement has to reach a page Baker did not build. What
 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).
-  in a container, use tagManagerTag  \u2014 the response carries two tags. \`tag\` is for a page somebody can edit; \`tagManagerTag\` is the one to stage, because a container rebuilds a Custom HTML tag's script element from its src alone and drops the key, so \`tag\` measures nothing there, published and silent. Check it on the page afterwards: window.baker in the browser console.
+  in a container, use tagManagerTag   \u2014 the response carries two tags. \`tag\` is for a page somebody can edit; \`tagManagerTag\` is the one to stage, because a container rebuilds a Custom HTML tag's script element from its src alone and drops the key, so \`tag\` measures nothing there, published and silent. Check it on the page afterwards: window.baker in the browser console.
+  --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 events --origin site          \u2014 after it is live, what that website is reporting`
+  baker analytics website-tag --measure all     \u2014 measure their whole website, because they asked for that
+  baker analytics events --origin website       \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 {
+        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 {
-        writeJsonEnvelope(await apiPost("/api/analytics/website-tag", {}));
+        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);
       }
@@ -29844,7 +30034,7 @@ Examples:
   baker analytics website-tag                 \u2014 the tag for a website Baker does not publish, key included
   baker analytics sending-events              \u2014 the contract for a client's server to post its own events
   baker analytics arrivals --outcome rejected \u2014 what their server posted that we refused, and why
-  baker analytics events --origin systems     \u2014 the events their systems reported, not ours
+  baker analytics events --origin server      \u2014 the events their systems reported, not ours
 Full guide: __tooling__/docs/tools/baker/analytics.md`
   },
   subCommands: {
@@ -29871,6 +30061,7 @@ Full guide: __tooling__/docs/tools/baker/analytics.md`
     arrivals: arrivalsCommand,
     "sending-events": sendingEventsCommand,
     "website-tag": websiteTagCommand,
+    sites: sitesCommand,
     presets: presetsCommand
   }
 });
@@ -44166,7 +44357,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.
@@ -44231,7 +44422,7 @@ Examples:
 Full guide: __tooling__/docs/tools/baker/gsc.md`
   },
   subCommands: {
-    sites: sitesCommand,
+    sites: sitesCommand2,
     query: queryCommand3,
     sitemaps: sitemapsCommand
   }