@koda-sl/baker-cli 0.373.0 → 0.374.0

package/README.md

@@ -1306,6 +1306,9 @@ baker analytics map --platform google --set kw=keyword    # name a parameter, se
 baker analytics map --platform google --remove kw         # take that answer back
 baker analytics conversions               # what counts, what each produced, and which Forms count nothing
 baker analytics conversions --candidates --output md  # everything these pages do, and which of it is counted, as tables
+baker analytics conversions --candidates             # the same as compact JSON: one line per page event, Form keys folded onto `flows`
+baker analytics conversions --candidates --flow contact             # only that Form's event keys, one line each
+baker analytics conversions --candidates --full --output json       # every field of every candidate, Form keys unfolded
 baker analytics conversions --flow contact          # one Form's endings as event keys, traffic or not
 baker analytics conversions --event page:request_demo --name "Demo requested"
 baker analytics conversions --event page:a --event submit:b --name "Lead"   # both, as one number
@@ -1357,7 +1360,7 @@ 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 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 value that is not a whole positive number (`--page /pricing`) is refused before any request, naming `--landing` as the flag that narrows a report to one page of the site.
 
-**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.
+**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. The JSON is compact by default: each page or system event is one line (`eventKey`, `events`, `sessions`, `countedAs` when counted), and a Form's keys fold onto its `flows` row as `keys` fired and `events` — dropping that row's empty `counted` and `noConversion` — or onto a `formCandidates` row for a Form not in `flows`. `--candidates --flow <slug>` narrows the list to that Form's keys, and `--full` returns every field (`origin`, `nodeType`, `flowSlug`, `lastSeen`, `sources`, `doors`) of every key, unfolded. `--output md` always folds a Form's keys into one row per Form. `--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.
 
 **The name is the grouping, so the CLI defends it.** Repeat `--event` to count several events under one `--name` in a single call; `--rename "<old>" --to "<new>"` renames every event under an outcome, and renaming *onto* a name that already exists **merges** them into one row and one number — the fix for a company whose Forms each invented their own word for the same thing. `--remove-name` drops an outcome entirely, `--remove` a single event key. A name that differs from one already counted only by case, accent, punctuation or a plural is **refused**: Baker groups by exact name, so "Booked a Call" beside "Booked a call" is a number split in half with both halves plausible. Every answer leads with the names already in use, and a company that has named nothing gets a standard set to start from — after which the rule is reuse, in that company's own language.
 

package/dist/cli.js

@@ -9080,17 +9080,17 @@ function text(value) {
   return typeof value === "string" ? value : "";
 }
 function draftOpNormalizer(record, full) {
-  const compact3 = {
+  const compact4 = {
     kind: text(record.kind),
     name: text(record.targetName),
     ref: text(record.tempId) || text(record.targetActionId),
     tags: Array.isArray(record.tags) ? record.tags.join(",") : ""
   };
   if (!full) {
-    return compact3;
+    return compact4;
   }
   return {
-    ...compact3,
+    ...compact4,
     description: text(record.description),
     note: text(record.note),
     reason: text(record.reason),
@@ -9365,10 +9365,10 @@ var listCommand2 = defineCommand8({
         process.stdout.write(renderMarkdown(response.data, hints2, { full: args5.full === true }));
         return;
       }
-      const compact3 = !args5.full && response.ok;
-      const shaped = compact3 ? { ...response, data: compactListData(response.data) } : response;
+      const compact4 = !args5.full && response.ok;
+      const shaped = compact4 ? { ...response, data: compactListData(response.data) } : response;
       const envelope = hints2.length > 0 ? { ...shaped, hints: hints2 } : shaped;
-      if (compact3) {
+      if (compact4) {
         process.stdout.write(`${JSON.stringify(envelope)}
 `);
         return;
@@ -14759,8 +14759,8 @@ function normalizePhoneV1(raw) {
 var PHONE_PUNCTUATION = /[\s()./-]/g;
 var E164 = /^\+[1-9]\d{7,14}$/;
 function normalizePhoneV2(raw) {
-  const compact3 = raw.replace(PHONE_PUNCTUATION, "");
-  const e164 = compact3.startsWith("00") ? `+${compact3.slice(2)}` : compact3;
+  const compact4 = raw.replace(PHONE_PUNCTUATION, "");
+  const e164 = compact4.startsWith("00") ? `+${compact4.slice(2)}` : compact4;
   return E164.test(e164) ? e164 : null;
 }
 
@@ -31887,6 +31887,7 @@ function parseConversionsArgs(raw, argv) {
     removeName: onlyOnce(raw["remove-name"], "--remove-name", argv),
     flowSlug: onlyOnce(raw.flow, "--flow", argv),
     candidates: raw.candidates === true,
+    full: raw.full === true,
     days: readDays(raw.days)
   };
   checkFlagShape(args5);
@@ -31953,6 +31954,72 @@ function conversionsWrite(args5, existing) {
   return { ...set.length > 0 ? { set } : {}, ...remove.length > 0 ? { remove } : {} };
 }
 
+// src/commands/analytics/conversionCandidates.ts
+function compact2(row) {
+  return {
+    eventKey: row.eventKey,
+    events: row.events,
+    sessions: row.sessions,
+    ...row.isCounted ? { countedAs: row.countedAs } : {}
+  };
+}
+function foldByForm(rows) {
+  const byForm = /* @__PURE__ */ new Map();
+  for (const row of rows) {
+    const form = byForm.get(row.flowSlug) ?? { form: row.flowSlug, keys: 0, countedKeys: 0, events: 0 };
+    form.keys += 1;
+    if (row.isCounted) form.countedKeys += 1;
+    form.events += row.events;
+    byForm.set(row.flowSlug, form);
+  }
+  return [...byForm.values()];
+}
+function candidatesForFlow(catalogue, flowSlug) {
+  return flowSlug === void 0 ? [...catalogue] : catalogue.filter((row) => row.flowSlug === flowSlug);
+}
+var FOLDED_FORMS_HINT = "A Form's candidates are folded into its `flows` row (`keys` fired, `events`; no `counted` means it counts nothing), or a `formCandidates` row when not listed. `--candidates --flow <slug>` lists that Form's keys; `--full` adds every field of every key.";
+function candidatesView(rows, options) {
+  if (options.full) return { candidates: rows };
+  if (options.flowSlug !== void 0) return { candidates: rows.map(compact2) };
+  const forms = foldByForm(rows.filter((row) => row.flowSlug !== ""));
+  return {
+    candidates: rows.filter((row) => row.flowSlug === "").map(compact2),
+    ...forms.length > 0 ? { formCandidates: forms } : {}
+  };
+}
+function fullFlagHints(args5, format) {
+  if (!args5.full || args5.candidates && format !== "md") return [];
+  return ["`--full` only applies to `--candidates --output json`, so it changed nothing here."];
+}
+function compactConversionsEnvelope(envelope, options) {
+  const { candidates, flows, ...data } = envelope.data;
+  if (candidates === void 0) return { ...envelope };
+  const { formCandidates, ...view } = candidatesView(candidates, options);
+  const traffic = new Map(formCandidates?.map((form) => [form.form, form]));
+  const merged = flows?.map(({ slug, counted, noConversion }) => {
+    const form = traffic.get(slug);
+    traffic.delete(slug);
+    return {
+      slug,
+      ...counted.length > 0 ? { counted } : {},
+      ...noConversion !== null ? { noConversion } : {},
+      keys: form?.keys ?? 0,
+      events: form?.events ?? 0
+    };
+  });
+  const hints2 = [...envelope.hints ?? [], ...formCandidates ? [FOLDED_FORMS_HINT] : []];
+  return {
+    ...envelope,
+    data: {
+      ...data,
+      ...merged ? { flows: merged } : {},
+      ...view,
+      ...traffic.size > 0 ? { formCandidates: [...traffic.values()] } : {}
+    },
+    ...hints2.length > 0 ? { hints: hints2 } : {}
+  };
+}
+
 // src/commands/analytics/conversionHints.ts
 var NAMED_CANDIDATES = 3;
 function conversionHints(definitions, candidates, askedForCandidates) {
@@ -32278,7 +32345,7 @@ function trafficByForm(candidates) {
   return byForm;
 }
 var NO_TRAFFIC = { "endings seen": 0, "endings counted": 0, events: 0, lastSeen: "" };
-var FORM_KEYS_HINT = "A Form's candidates are one row per Form: `baker analytics conversions --flow <slug>` lists that Form's event keys, and `--candidates --output json` lists every key.";
+var FORM_KEYS_HINT = "A Form's candidates are one row per Form: `baker analytics conversions --flow <slug>` lists that Form's event keys, and `--candidates --full --output json` lists every key with every field.";
 function renderConversionsMarkdown(envelope) {
   const { definitions, flow, flows, candidates } = envelope.data;
   const data = {
@@ -32315,7 +32382,7 @@ function renderConversionsMarkdown(envelope) {
   return renderMarkdown3({ data, ...hints2.length > 0 ? { hints: hints2 } : {} });
 }
 function withFormatHint(envelope, format) {
-  const hints2 = [...envelope.hints ?? [], ...formatHint(envelope.data, format)];
+  const hints2 = [...envelope.hints ?? [], ...formatHint({ ...envelope.data }, format)];
   return { ...envelope, ...hints2.length > 0 ? { hints: hints2 } : {} };
 }
 
@@ -34473,13 +34540,13 @@ function readFlowConversions2(slug, definitions) {
     endings: joinFlowConversions(flowEventKeys(tree, slug), definitions)
   };
 }
-function conversionsEnvelope(args5, definitions, candidates, serverHints = []) {
+function conversionsEnvelope(args5, definitions, candidates, leadingHints = []) {
   const flow = args5.flowSlug === void 0 ? null : readFlowConversions2(args5.flowSlug, definitions);
   const forms = flow === null ? readWorkspaceFlows() : [];
   const coverage = flowCoverage(forms, definitions);
   const page = pageCandidates(definitions, candidates, args5.candidates);
   const hints2 = [
-    ...serverHints,
+    ...leadingHints,
     ...flow ? flowConversionHints(flow.slug, flow.endings, flow.noConversionReason) : [],
     ...flowCoverageHints(coverage),
     ...stagedHints(definitions),
@@ -34492,7 +34559,7 @@ function conversionsEnvelope(args5, definitions, candidates, serverHints = []) {
       definitions,
       ...flow ? { flow } : {},
       ...coverage.length > 0 ? { flows: coverage } : {},
-      ...args5.candidates ? { candidates: page.candidates } : {}
+      ...args5.candidates ? { candidates: candidatesForFlow(page.candidates, args5.flowSlug) } : {}
     },
     ...hints2.length > 0 ? { hints: hints2 } : {}
   };
@@ -34536,12 +34603,17 @@ var conversionsCommand3 = (() => {
     },
     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",
+      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. Compact by default in JSON: each page or system event is one line (eventKey, events, sessions, countedAs when counted) and a Form's keys fold onto its `flows` row as `keys` and `events` (or a `formCandidates` row for a Form not in `flows`). Add --flow <slug> for that Form's keys only, and --full --output json for every field of every row",
+      required: false
+    },
+    full: {
+      type: "boolean",
+      description: "With --candidates: every field of every candidate (origin, nodeType, flowSlug, lastSeen, sources, doors) and every Form key unfolded. Large on a busy company \u2014 narrow it with --flow first",
       required: false
     },
     flow: {
       type: "string",
-      description: "A Form slug. Lists that Form's own endings already spelled as event keys, each with the name Baker counts it under or nothing \u2014 read off the Form's file, so it works on a Form built minutes ago that has never been visited, which is exactly when --candidates is empty. Use it whenever you create or edit a Form: it is the only way to see that the Form counts nothing before it is published counting nothing",
+      description: "A Form slug. Lists that Form's own endings already spelled as event keys, each with the name Baker counts it under or nothing \u2014 read off the Form's file, so it works on a Form built minutes ago that has never been visited, which is exactly when --candidates is empty. With --candidates, narrows the candidates to that Form's keys. Use it whenever you create or edit a Form: it is the only way to see that the Form counts nothing before it is published counting nothing",
       required: false
     },
     days: {
@@ -34559,7 +34631,7 @@ var conversionsCommand3 = (() => {
   return defineCommand99({
     meta: {
       name: "conversions",
-      description: "What this company counts as a conversion \u2014 the numerator of every conversion rate on Measure. A page event (a Form ending, a data-baker-* event) and an event one of the client's systems sends (a HubSpot event made with `baker analytics sources --create-hubspot`, an order the server posts) both count; a system's event is credited to the last landing its person viewed. A HubSpot event is `page:<its name>` here \u2014 `--event 'page:Deal won' --name 'Deal won'`. 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. Inside a chat a change is STAGED: the person sees it under Sources in the chat's changes, on the event's own row and it applies when they publish, retroactively \u2014 the whole history is rescored, so a company that has been running for a month gets a month of correct numbers. A read shows a proposal marked `staged`. Call an event by its name when you talk to the person, never by its key. Two events given the SAME --name are one row and one number. `--remove <key>` stops counting one. `--flow <slug>` answers the other direction \u2014 what one Form counts, with every ending it has already spelled as an event key, read from the Form itself so it works before a single visitor has seen it. Run it whenever you create or edit a Form: a Form nobody named an outcome for is published converting nobody, and no report says so."
+      description: "What this company counts as a conversion \u2014 the numerator of every conversion rate on Measure. A page event (a Form ending, a data-baker-* event) and an event one of the client's systems sends (a HubSpot event made with `baker analytics sources --create-hubspot`, an order the server posts) both count; a system's event is credited to the last landing its person viewed. A HubSpot event is `page:<its name>` here \u2014 `--event 'page:Deal won' --name 'Deal won'`. 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. It is compact: a Form's keys fold onto its `flows` row, `--candidates --flow <slug>` lists one Form's keys, and `--full --output json` returns every field of every row. Then `--event <key> --name 'Booked a call'` to count it. Inside a chat a change is STAGED: the person sees it under Sources in the chat's changes, on the event's own row and it applies when they publish, retroactively \u2014 the whole history is rescored, so a company that has been running for a month gets a month of correct numbers. A read shows a proposal marked `staged`. Call an event by its name when you talk to the person, never by its key. Two events given the SAME --name are one row and one number. `--remove <key>` stops counting one. `--flow <slug>` answers the other direction \u2014 what one Form counts, with every ending it has already spelled as an event key, read from the Form itself so it works before a single visitor has seen it. Run it whenever you create or edit a Form: a Form nobody named an outcome for is published converting nobody, and no report says so."
     },
     args: args5,
     run: async ({ args: raw }) => {
@@ -34579,10 +34651,10 @@ var conversionsCommand3 = (() => {
           args6,
           mergeStoredWithCounts(stored, report.data.conversions ?? []),
           report.data.eventCatalog ?? [],
-          answer.hints ?? []
+          [...answer.hints ?? [], ...fullFlagHints(args6, format)]
         );
         if (format === "md") process.stdout.write(renderConversionsMarkdown(envelope));
-        else writeJsonEnvelope(withFormatHint(envelope, format));
+        else writeJsonEnvelope(withFormatHint(compactConversionsEnvelope(envelope, args6), format));
       } catch (err) {
         if (err instanceof ConversionArgsError) {
           handleError3(new ApiError("VALIDATION_ERROR", err.message));
@@ -54495,13 +54567,13 @@ function compactHit(hit) {
   };
 }
 function providerHitNormalizer(record, full) {
-  const compact3 = compactHit(record);
+  const compact4 = compactHit(record);
   if (!full) {
-    return compact3;
+    return compact4;
   }
   const group = asRecord2(record.group);
   return {
-    ...compact3,
+    ...compact4,
     externalUrl: str(record.externalUrl),
     externalId: str(record.externalId),
     description: str(record.description),
@@ -55263,7 +55335,7 @@ registerSchema({
   }
 });
 var POLL_INTERVAL_MS3 = 4e3;
-function compact2(doc) {
+function compact3(doc) {
   return {
     layeredImageId: doc.layeredImageId,
     imageId: doc.imageId,
@@ -55353,7 +55425,7 @@ var layerizeCommand = defineCommand157({
         });
         process.exit(1);
       }
-      writeJson({ ok: true, data: full ? settled : compact2(settled), hints: hintsFor3(settled) });
+      writeJson({ ok: true, data: full ? settled : compact3(settled), hints: hintsFor3(settled) });
     } catch (err) {
       if (err instanceof ApiError) {
         writeJson({ ok: false, error: { code: err.code, message: err.message } });
@@ -55392,7 +55464,7 @@ var layersCommand = defineCommand157({
         process.exit(1);
       }
       const doc = await apiGet("/api/images/layers", { imageId });
-      writeJson({ ok: true, data: args5.full ? doc : compact2(doc), hints: hintsFor3(doc) });
+      writeJson({ ok: true, data: args5.full ? doc : compact3(doc), hints: hintsFor3(doc) });
     } catch (err) {
       if (err instanceof ApiError) {
         writeJson({
@@ -65021,7 +65093,7 @@ function adByHandHint(input) {
 
 // src/commands/studio/batch.ts
 function projectBatch(generation, full) {
-  const compact3 = {
+  const compact4 = {
     generationId: generation.generationId,
     kind: generation.kind,
     status: generation.status,
@@ -65038,9 +65110,9 @@ function projectBatch(generation, full) {
       ...variant.error ? { error: variant.error } : {}
     }))
   };
-  if (!full) return compact3;
+  if (!full) return compact4;
   return {
-    ...compact3,
+    ...compact4,
     ...generation.skillId ? { skillId: generation.skillId } : {},
     ...generation.imageSettings ? { imageSettings: generation.imageSettings } : {},
     ...generation.clipSettings ? { clipSettings: generation.clipSettings } : {},
@@ -68240,12 +68312,12 @@ function compactAdvertiser(record) {
   };
 }
 function advertiserNormalizer(record, full) {
-  const compact3 = compactAdvertiser(record);
+  const compact4 = compactAdvertiser(record);
   if (!full) {
-    return compact3;
+    return compact4;
   }
   return {
-    ...compact3,
+    ...compact4,
     scraped_name: record.scraped_name ?? null,
     image_url: record.image_url ?? null,
     platforms: Array.isArray(record.platforms) ? record.platforms : [],
@@ -68806,12 +68878,12 @@ function followingHints(records) {
   return hints2;
 }
 function followingNormalizer(record, full) {
-  const compact3 = compactFollowed(record);
+  const compact4 = compactFollowed(record);
   if (!full) {
-    return compact3;
+    return compact4;
   }
   return {
-    ...compact3,
+    ...compact4,
     image_url: record.image_url ?? null,
     platforms: Array.isArray(record.platforms) ? record.platforms : []
   };