@koda-sl/baker-cli 0.269.0 → 0.270.0

package/README.md

@@ -1232,6 +1232,10 @@ baker analytics tracking                  # do the ad URLs carry the campaign, a
 baker analytics tracking --platform meta  # the same for one platform, read from their own ad account
 baker analytics map --platform google --set kw=keyword    # name a parameter, seen or not yet
 baker analytics map --platform google --remove kw         # take that answer back
+baker analytics conversions               # what counts as a conversion, and what each one produced
+baker analytics conversions --candidates  # everything these pages do, and which of it is counted
+baker analytics conversions --event page:request_demo --name "Demo requested"
+baker analytics conversions --remove page:request_demo
 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
 ```
@@ -1246,6 +1250,8 @@ Shared flags: `--days <n>` (default 30) or `--start-date` / `--end-date` (`YYYY-
 
 **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 dashboard's People 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. One outcome per call — repeating `--event` is refused rather than silently keeping the last one.
+
 **Campaign parameters are per platform, and so are the numbers.** `baker analytics ads` returns `adPlatformTraffic` (visits, conversions and *tagged* visits for each of the nine platforms), `adParams` for the platform in `--platform` only, and `adParamsUnattributed` for names arriving on visits with no click id and no recognisable source. Read `adPlatformTraffic` first: a platform with visits and zero tagged visits has untagged ad URLs, and no mapping can fix that from Baker's side. `baker analytics map` needs `--platform` for any change, accepts a parameter name **nobody has sent yet** — which is how a tracking template is configured before its campaign runs — and takes an answer back with `--remove`. `--set <name>=ignore` says a parameter is not campaign information at all, so Baker stops storing it and stops listing it.
 
 **Mapping is staged on the chat, not applied.** Answers appear under **Campaign parameters** in the dashboard and take effect when the chat is published; a discard takes them all back, and a report run in the same turn still reads the old vocabulary. Reading the mapping back inside the chat *does* include what it has staged, so a second turn never re-maps the same parameter.

package/dist/cli.js

@@ -12291,6 +12291,7 @@ var CAPTURED_WITHOUT_ROLE = [
 ].sort();
 
 // ../api/src/analytics/conversions.ts
+var CONVERSION_COUNT_MODES = ["once_per_visit", "every_time"];
 var PRIMARY_CONVERSION_TRIGGER = {
   calendly: "calendlyEvent.eventScheduled",
   customForm: "customForm.onFormSubmitted",
@@ -12306,6 +12307,33 @@ var NON_SUBMIT_NODE_TYPES = ["link", "text"];
 var STEP_SUBMIT_TRIGGERS = Object.fromEntries(
   Object.entries(PRIMARY_CONVERSION_TRIGGER).filter(([nodeType]) => !NON_SUBMIT_NODE_TYPES.includes(nodeType))
 );
+var MAX_CONVERSION_NAME = 80;
+
+// ../api/src/analytics/eventKey.ts
+var SEP = ":";
+function parseEventKey(key) {
+  const cut = key.indexOf(SEP);
+  if (cut <= 0) return null;
+  const family = key.slice(0, cut);
+  const rest = key.slice(cut + 1);
+  if (rest === "") return null;
+  switch (family) {
+    case "form": {
+      const [flowSlug, nodeId, ...triggerParts] = rest.split(SEP);
+      const triggerId = triggerParts.join(SEP);
+      if (!flowSlug || !nodeId || triggerId === "") return null;
+      return { family: "form", flowSlug, nodeId, triggerId };
+    }
+    case "submit":
+      return { family: "submit", flowSlug: rest };
+    case "page":
+      return { family: "page", eventName: rest };
+    case "exit":
+      return { family: "exit", host: rest };
+    default:
+      return null;
+  }
+}
 
 // ../api/src/analytics/events.ts
 import { z as z24 } from "zod";
@@ -12817,7 +12845,18 @@ var analyticsPresetSchema = z25.enum([
    * would do is add a choice the agent can never usefully pick to the menu it
    * reads before picking one.
    */
-  "realtime"
+  "realtime",
+  /**
+   * What this company counts as a conversion, and everything it could count.
+   *
+   * The two halves of one question, which is why they are one preset: the list
+   * of definitions with what each produced, and the catalogue of every event
+   * these pages actually emitted with whether it is already counted. Reading
+   * the first without the second is how the previous design failed — a
+   * marketer could see that nothing was counted and had no way to find out what
+   * was available to count.
+   */
+  "conversions"
 ]);
 var ANALYTICS_PRESETS = analyticsPresetSchema.options;
 var analyticsQueryRequestSchema = z25.object({
@@ -13478,21 +13517,40 @@ var analyticsFlowEdgeSchema = z25.object({
   sessions: z25.number().int().nonnegative()
 });
 var analyticsConversionRowSchema = z25.object({
-  /** What a person calls this outcome. Falls back to the node's name. */
+  /** What a person calls this outcome. */
   name: z25.string(),
-  flowSlug: z25.string(),
-  nodeId: z25.string(),
-  triggerId: z25.string(),
-  nodeType: z25.string(),
-  /** `once_per_visit` | `every_time` — how repeats inside one visit are counted. */
+  /** Every event counted under this name. One entry unless the name is shared. */
+  eventKeys: z25.array(z25.string()),
+  /**
+   * `once_per_visit` | `every_time` — how repeats inside one visit are counted.
+   *
+   * `mixed` when a shared name spans both, which is a real state and an editing
+   * accident; saying so is what makes it findable.
+   */
   countMode: z25.string(),
-  /** Counted the way this mark asked to be counted. */
+  /** Counted the way each definition asked to be counted. */
   conversions: z25.number(),
   /** Distinct visits that produced it, never mode-adjusted. The gap between the two is the repeat behaviour. */
   convertingVisits: z25.number(),
   /** Null when it has never fired. */
   lastSeen: z25.string().nullable()
 });
+var analyticsEventCatalogRowSchema = z25.object({
+  /** `form:…` | `submit:…` | `page:…` | `exit:…` — parse with `parseEventKey`. */
+  eventKey: z25.string(),
+  events: z25.number(),
+  sessions: z25.number(),
+  /** The Form node's kind, for a `form:` key. Empty otherwise. */
+  nodeType: z25.string(),
+  /** The Form this happened in, for a `form:` or `submit:` key. Empty otherwise. */
+  flowSlug: z25.string(),
+  /** Null when it has never fired — only possible for a row we already count. */
+  lastSeen: z25.string().nullable(),
+  /** Already counted as a conversion. Shown, never hidden: a row that vanished on being counted reads as a bug. */
+  isCounted: z25.boolean(),
+  /** The name it is counted under, when it is. */
+  countedAs: z25.string()
+});
 var analyticsAdDimensionRowSchema = z25.object({
   /** The dimension's value. Empty means "arrived carrying none of these". */
   value: z25.string(),
@@ -13833,6 +13891,8 @@ var analyticsQueryDataSchema = z25.object({
   /** Present only on a report that was asked for by the page. */
   pageInfo: analyticsPageInfoSchema.optional(),
   conversions: z25.array(analyticsConversionRowSchema).optional(),
+  /** Every event these pages produced, counted or not. The "add a conversion" picker. */
+  eventCatalog: z25.array(analyticsEventCatalogRowSchema).optional(),
   timeline: z25.array(analyticsTimelineRowSchema).optional(),
   visitorSessions: z25.array(analyticsVisitorSessionSchema).optional(),
   visitProfile: analyticsVisitProfileSchema.optional(),
@@ -13855,6 +13915,31 @@ var analyticsQueryResponseSchema = z25.object({
   warnings: z25.array(analyticsWarningSchema).optional(),
   hints: z25.array(z25.string()).optional()
 });
+var analyticsConversionsRequestSchema = z25.object({
+  set: z25.array(
+    z25.object({
+      /** `form:<flow>:<step>:<trigger>` | `submit:<flow>` | `page:<name>` | `exit:<host>`. */
+      eventKey: z25.string().max(320),
+      name: z25.string().max(MAX_CONVERSION_NAME),
+      countMode: z25.enum(CONVERSION_COUNT_MODES).optional()
+    })
+  ).max(60).optional(),
+  remove: z25.array(z25.string().max(320)).max(60).optional()
+});
+var analyticsConversionsResponseSchema = z25.object({
+  ok: z25.literal(true),
+  data: z25.object({
+    definitions: z25.array(
+      z25.object({
+        eventKey: z25.string(),
+        name: z25.string(),
+        countMode: z25.string(),
+        updatedAt: z25.number()
+      })
+    )
+  }),
+  hints: z25.array(z25.string()).optional()
+});
 var analyticsMappingRequestSchema = z25.object({
   /**
    * Which platform these operations are about. Required for a change.
@@ -25004,6 +25089,88 @@ Full guides: __tooling__/docs/tools/baker/ads-<platform>.md (google|meta|linkedi
 // src/commands/analytics/index.ts
 import { defineCommand as defineCommand90 } from "citty";
 
+// src/commands/analytics/conversionArgs.ts
+var ConversionArgsError = class extends Error {
+};
+function onlyOnce(value, flag, argv) {
+  if (value === void 0) return void 0;
+  const given = argv.filter((arg) => arg === flag || arg.startsWith(`${flag}=`)).length;
+  if (given > 1) {
+    throw new ConversionArgsError(
+      `${flag} was given ${given} times and only the last would have been used. Count one outcome per call.`
+    );
+  }
+  const trimmed = String(value).trim();
+  return trimmed === "" ? void 0 : trimmed;
+}
+function parseConversionsArgs(raw, argv) {
+  const eventKey = onlyOnce(raw.event, "--event", argv);
+  const name = onlyOnce(raw.name, "--name", argv);
+  const countMode = onlyOnce(raw["count-mode"], "--count-mode", argv);
+  const remove = onlyOnce(raw.remove, "--remove", argv);
+  if (eventKey !== void 0 && name === void 0) {
+    throw new ConversionArgsError("--event needs --name: a conversion nobody named is a row labelled with a UUID.");
+  }
+  if (name !== void 0 && eventKey === void 0 && remove === void 0) {
+    throw new ConversionArgsError("--name needs --event, naming which event to count.");
+  }
+  if (eventKey !== void 0 && parseEventKey(eventKey) === null) {
+    throw new ConversionArgsError(
+      `"${eventKey}" is not an event key. Run with --candidates and copy one; they look like form:<form>:<step>:<trigger>, submit:<form>, page:<name> or exit:<host>.`
+    );
+  }
+  if (countMode !== void 0 && !CONVERSION_COUNT_MODES.includes(countMode)) {
+    throw new ConversionArgsError(`--count-mode must be one of ${CONVERSION_COUNT_MODES.join(", ")}.`);
+  }
+  const days = raw.days === void 0 ? void 0 : Number(raw.days);
+  if (days !== void 0 && (!Number.isFinite(days) || days <= 0)) {
+    throw new ConversionArgsError("--days must be a positive number of days.");
+  }
+  return { eventKey, name, countMode, remove, candidates: raw.candidates === true, days };
+}
+function conversionsWrite(args) {
+  const set = args.eventKey !== void 0 && args.name !== void 0 ? [{ eventKey: args.eventKey, name: args.name, ...args.countMode ? { countMode: args.countMode } : {} }] : void 0;
+  const remove = args.remove !== void 0 ? [args.remove] : void 0;
+  if (!set && !remove) return null;
+  return { ...set ? { set } : {}, ...remove ? { remove } : {} };
+}
+
+// src/commands/analytics/conversionHints.ts
+var NAMED_CANDIDATES = 3;
+function conversionHints(definitions, candidates, askedForCandidates) {
+  const hints2 = [];
+  if (definitions.length === 0) {
+    hints2.push(
+      "Nothing is counted as a conversion, so EVERY conversion number in every other report is zero \u2014 whatever visitors actually did. Baker never guesses which event is the point of a page. Run `baker analytics conversions --candidates` to see what these pages produce, then count the ones that are worth money."
+    );
+    if (!askedForCandidates && candidates.length > 0) {
+      const top = candidates.slice(0, NAMED_CANDIDATES).map((row) => row.eventKey).join(", ");
+      hints2.push(`${candidates.length} distinct events are available to count. Busiest: ${top}.`);
+    }
+    return hints2;
+  }
+  const silent = definitions.filter((row) => row.lastSeen === null);
+  if (silent.length > 0) {
+    hints2.push(
+      `${silent.length} counted outcome(s) have never fired in this window: ${silent.slice(0, NAMED_CANDIDATES).map((row) => row.name).join(
+        ", "
+      )}. Either the page never reaches them, or the wrong event was named \u2014 check against --candidates before reporting a conversion rate.`
+    );
+  }
+  const uncounted = candidates.filter((row) => !row.isCounted);
+  const busiest = uncounted[0];
+  if (busiest && busiest.sessions > 0) {
+    const counted = candidates.filter((row) => row.isCounted);
+    const busiestCounted = counted.reduce((max, row) => Math.max(max, row.sessions), 0);
+    if (busiest.sessions > busiestCounted) {
+      hints2.push(
+        `\`${busiest.eventKey}\` happened in ${busiest.sessions} visits and is not counted \u2014 more than anything that is. Check it is not the real outcome.`
+      );
+    }
+  }
+  return hints2;
+}
+
 // src/commands/analytics/hints.ts
 var SEVERE_STEP_DROP = 0.6;
 var MIN_SESSIONS_FOR_RATES = 100;
@@ -25183,6 +25350,11 @@ var ANALYTICS_PRESET_INFO = [
     name: "releases",
     description: "Traffic and conversions per published build, newest first. Answers whether a change to a page moved the numbers.",
     playbook: "landing \u2014 compare a page before and after a change"
+  },
+  {
+    name: "conversions",
+    description: "What this company counts as a conversion, and what each one produced. The report every other conversion number is derived from, so read it FIRST whenever a conversion figure looks wrong or reads zero: an empty list means nothing is counted and every conversion number everywhere is zero, whatever visitors did. `baker analytics conversions --candidates` lists everything these pages actually produce \u2014 every Form step, every data-baker-* event, every outbound destination \u2014 and counting one applies immediately and rescores the whole history, with no publish. Anything can be counted, not just a Form.",
+    playbook: "run `baker analytics conversions` \u2014 this one is fixed with the command, not with a skill"
   }
 ];
 
@@ -25855,6 +26027,79 @@ Examples:
     }
   });
 })();
+var conversionsCommand3 = (() => {
+  const args = {
+    event: {
+      type: "string",
+      description: "The event to start counting, from the `candidates` list: form:<form>:<step>:<trigger>, submit:<form>, page:<name>, or exit:<host>. Requires --name. Applies immediately and scores the WHOLE history, not just from now on \u2014 so counting the right event today also corrects last month's reports",
+      required: false
+    },
+    name: {
+      type: "string",
+      description: "What to call this outcome on every report \u2014 'Booked a call', 'Quote requested'. Reuse the SAME name on two events and they become one row and one number, which is how a call booked on three different Forms reads as one outcome rather than three",
+      required: false
+    },
+    "count-mode": {
+      type: "string",
+      description: "once_per_visit (default) or every_time. Ask whether doing it twice in one visit is one outcome or two: a booking clicked twice is one booking, a guide downloaded twice is two downloads. Getting this wrong inflates the rate every budget is set by",
+      required: false
+    },
+    remove: {
+      type: "string",
+      description: "An event key to stop counting. Removes it from the history too, for the same reason adding it fills the history in",
+      required: false
+    },
+    candidates: {
+      type: "boolean",
+      description: "Also list every event these pages actually produced, ranked by volume, with whether it is already counted. This is where an event key comes from \u2014 do not invent one. Off by default because a busy company produces hundreds of rows",
+      required: false
+    },
+    days: {
+      type: "string",
+      description: "Lookback for the counts and for --candidates. Default 30",
+      required: false
+    }
+  };
+  registerSchema({
+    command: "analytics.conversions",
+    description: "Read or change what this company counts as a conversion",
+    args
+  });
+  return defineCommand90({
+    meta: {
+      name: "conversions",
+      description: "What this company counts as a conversion, and what each one produced. Run with no flags first: an empty `definitions` list means every conversion number in every other report is zero \u2014 not because nobody converted, but because nothing is marked as converting, and Baker never guesses. Add `--candidates` to see everything these pages actually do (every Form step, every data-baker-* event, every outbound destination) with counts and whether it is already counted; that list is where an event key comes from, so never invent one. Then `--event <key> --name 'Booked a call'` to count it. It applies IMMEDIATELY and retroactively \u2014 the whole history is rescored, so a company that has been running for a month gets a month of correct numbers the moment you name the right event. Nothing here is staged and publishing is not involved. Two events given the SAME --name are one row and one number. `--remove <key>` stops counting one."
+    },
+    args,
+    run: async ({ args: raw }) => {
+      try {
+        const args2 = parseConversionsArgs(raw, process.argv);
+        const write2 = conversionsWrite(args2);
+        if (write2) {
+          await apiPost("/api/analytics/conversions", write2);
+        }
+        const report = await apiPost("/api/analytics/query", {
+          preset: "conversions",
+          days: args2.days
+        });
+        const definitions = report.data.conversions ?? [];
+        const candidates = report.data.eventCatalog ?? [];
+        const hints2 = conversionHints(definitions, candidates, args2.candidates);
+        writeJsonEnvelope({
+          ok: true,
+          data: { definitions, ...args2.candidates ? { candidates } : {} },
+          ...hints2.length > 0 ? { hints: hints2 } : {}
+        });
+      } catch (err) {
+        if (err instanceof ConversionArgsError) {
+          handleError(new ApiError("VALIDATION_ERROR", err.message));
+          return;
+        }
+        handleError(err);
+      }
+    }
+  });
+})();
 function parsePairs(raw) {
   if (raw === void 0) return void 0;
   const out = {};
@@ -25929,6 +26174,7 @@ Full guide: __tooling__/docs/tools/baker/analytics.md`
     events: eventsCommand,
     devices: devicesCommand,
     ads: adsCommand3,
+    conversions: conversionsCommand3,
     map: mapCommand,
     tracking: trackingCommand,
     presets: presetsCommand