@koda-sl/baker-cli 0.504.0 → 0.506.0

package/README.md

@@ -1818,6 +1818,9 @@ 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
 baker analytics feed --source Zapier      # the raw event feed, newest first, narrowed to what one source sent
 baker analytics feed --sends failed       # only the uploads a conversion's sends made and the platform refused
+baker analytics feed --bots               # only the events taken for machine traffic (a headless browser such as agent-browser), hidden everywhere else
+baker analytics website-tag --check       # every event the website's Tag Manager sends Baker, and which no real visit has brought
+baker analytics debug --start --url https://client.com/   # a link that records what the person's own browser heard; read it with `baker analytics debug <code>`
 baker analytics feed --person 'ana@empresa.com, +34600111222, deal:40001234567' --days 90   # everything these people did; emails and phones are hashed by Baker
 baker analytics lookup --person 'ana@empresa.com, 90001234567'   # what Baker saw of each person in a list, all time — found or not, pages, CRM stages, uploads
 baker analytics lookup --people-file leads.txt   # one per line: emails, phones, HubSpot contact or deal:<id>, gclid/fbclid, browser ids

package/dist/{ads-MAPZYX6F.js → ads-T5RPISTB.js}

@@ -33,16 +33,16 @@ Examples:
 Full guides: __tooling__/docs/tools/baker/ads-<platform>.md (google|meta|linkedin|x|chatgpt|performance|terms)`
   },
   subCommands: {
-    google: () => import("./google-VPL4KZDP.js").then((m) => m.googleCommand),
+    google: () => import("./google-3GSINSOV.js").then((m) => m.googleCommand),
     meta: () => import("./meta-KS3SQSYZ.js").then((m) => m.metaCommand),
     linkedin: () => import("./linkedin-4MGRSWXZ.js").then((m) => m.linkedinCommand),
     x: () => import("./x-7VY6K7JS.js").then((m) => m.xCommand),
     chatgpt: () => import("./chatgpt-SVGWMEQD.js").then((m) => m.chatgptCommand),
-    performance: () => import("./performance-CIUVIFD7.js").then((m) => m.performanceCommand),
+    performance: () => import("./performance-WPFGEJTE.js").then((m) => m.performanceCommand),
     terms: () => import("./terms-O6ODXEOK.js").then((m) => m.termsCommand)
   }
 });
 export {
   adsCommand
 };
-//# sourceMappingURL=ads-MAPZYX6F.js.map
+//# sourceMappingURL=ads-T5RPISTB.js.map

package/dist/{analytics-4CCQYY7Z.js → analytics-P5UFA6I4.js}

@@ -5,7 +5,7 @@ import "./chunk-MGYC2IRC.js";
 import {
   flowEventKeys,
   flowNodes
-} from "./chunk-S3FFLLYF.js";
+} from "./chunk-LIRX2Q66.js";
 import {
   flowDataPath,
   flowExists,
@@ -16,20 +16,23 @@ import {
   INGEST_ARRIVALS_MAX,
   eventIngestUrl,
   ingestBrief
-} from "./chunk-GJCB46L6.js";
+} from "./chunk-HWDRW36T.js";
 import "./chunk-GRQ2AXDX.js";
+import {
+  TAG_MANAGER_TIMEOUT_MS
+} from "./chunk-3GAR4AZK.js";
 import {
   peopleArgs,
   peopleLimitError
-} from "./chunk-ZEGNIP3Y.js";
+} from "./chunk-TVTSA4EN.js";
 import {
   ConversionArgsError,
   conversionsWrite,
   parseConversionsArgs
-} from "./chunk-DX46OE4U.js";
+} from "./chunk-OJGYYH6K.js";
 import {
   analyticsErrorEnvelope
-} from "./chunk-VU5Z2V4S.js";
+} from "./chunk-D3KLDIPQ.js";
 import {
   AD_PARAM_ROLE_SPECS,
   ANALYTICS_EVENT_DOORS,
@@ -42,11 +45,12 @@ import {
   isBookkeepingRow,
   parseEventKey,
   rowMatchKeys
-} from "./chunk-DI44SZVP.js";
+} from "./chunk-7J3NZBPV.js";
 import "./chunk-EDLZGTGN.js";
 import {
   repeatedValues
 } from "./chunk-ERSX3MKH.js";
+import "./chunk-D5FY4FAK.js";
 import {
   writeJsonEnvelope
 } from "./chunk-ZRP7Y2DM.js";
@@ -507,6 +511,84 @@ function withFormatHint(envelope, format) {
   return { ...envelope, ...hints.length > 0 ? { hints } : {} };
 }
 
+// src/commands/analytics/debugLink.ts
+function debugStartHints(started) {
+  if (started.link === null) {
+    return [
+      `Code ${started.code} records for two hours. Run it again with --url <the page to test> for a link to send, or add ?baker_debug=${started.code} to that page's address yourself.`
+    ];
+  }
+  return [
+    `Send the person this link: ${started.link} \u2014 they open it in the browser they normally use, accept the cookie banner, do exactly what did not work (open the widget, start the call, submit the form), then tell you they are done. Then run \`baker analytics debug ${started.code}\`. It records for two hours, nothing it records is counted anywhere, and emails and phone numbers are masked.`
+  ];
+}
+function inner(row) {
+  if (!row.data) return "";
+  try {
+    const parsed = JSON.parse(row.data);
+    const name = parsed.event ?? parsed.action ?? parsed.name;
+    return typeof name === "string" ? name : "";
+  } catch {
+    return "";
+  }
+}
+function isTagManagerNoise(label) {
+  return label.startsWith("gtm.") || label.startsWith("cookie_consent") || label === "consent" || label === "set";
+}
+var FOLLOWS_WITHIN_MS = 2e3;
+function debugReadHints(read) {
+  if (read.records.length === 0) {
+    return [
+      `Nothing recorded under ${read.code}: the Baker tag never loaded on a visit with this link. Either the link was not opened yet, the cookie banner was not accepted (on a site that loads Tag Manager only after consent, the tag never starts), or the site dropped ?baker_debug from the address before the tag ran. ${read.active ? "The link still records \u2014 ask them to try again." : "The link has expired; start a new one."}`
+    ];
+  }
+  const hints = [];
+  const boot = read.records.find((row) => row.kind === "pixel" && row.label === "boot");
+  if (boot?.data?.includes('"measuring":false')) {
+    hints.push(
+      "The tag did not measure this visit (its scope or the visitor's consent ruled it out), so its `track` calls sent nothing to Baker. The records below are still what the page heard."
+    );
+  }
+  const messages = read.records.filter((row) => row.kind === "message" && row.from && row.from !== "null");
+  const byOrigin = /* @__PURE__ */ new Map();
+  for (const row of messages) {
+    const said = byOrigin.get(row.from ?? "") ?? /* @__PURE__ */ new Map();
+    const what = inner(row) ? `${row.label} (${inner(row)})` : row.label;
+    said.set(what, (said.get(what) ?? 0) + 1);
+    byOrigin.set(row.from ?? "", said);
+  }
+  for (const [origin, said] of byOrigin) {
+    hints.push(
+      `${origin} sent: ${[...said].map(([what, count]) => count > 1 ? `${what} \xD7${count}` : what).join(", ")}. An event that is not on this list was never sent by that frame on this visit \u2014 the tag manager could not have passed it on.`
+    );
+  }
+  const unanswered = messages.filter(
+    (message) => !read.records.some(
+      (row) => row.kind === "dataLayer" && !isTagManagerNoise(row.label) && // Either side of it: a listener the site registered before the tag
+      // ran first, so its push is stamped before the message is.
+      Math.abs(row.t - message.t) <= FOLLOWS_WITHIN_MS
+    )
+  );
+  if (unanswered.length > 0) {
+    hints.push(
+      `${[...new Set(unanswered.map((row) => row.label))].join(", ")}: arrived as a message and no dataLayer event followed, so no tag listening for one could fire. Compare the message (--full) with the listener in the container (\`baker tag-manager read --entities tag --full\`) \u2014 a different \`type\` or event name is the usual cause.`
+    );
+  }
+  const tracked = read.records.filter((row) => row.kind === "track").map((row) => row.label);
+  if (tracked.length > 0) {
+    hints.push(
+      `The tag was asked to send: ${[...new Set(tracked)].join(", ")}. These reach Baker's feed within a minute or two (\`baker analytics feed --origin website --days 1\`).`
+    );
+  }
+  if (read.dropped > 0)
+    hints.push(`${read.dropped} records arrived after this link had kept its maximum and were not kept.`);
+  return hints;
+}
+function compactDebugRead(read, full) {
+  if (full) return read;
+  return { ...read, records: read.records.map(({ data: _data, ...row }) => row) };
+}
+
 // src/commands/analytics/feedRows.ts
 function isStreamRow(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
@@ -540,6 +622,14 @@ function feedHints(shape) {
   }
   return hints;
 }
+function hiddenMachinesHints(hidden) {
+  if (hidden === void 0 || hidden.events === 0) return [];
+  const headless = hidden.reasons.some((share) => share.reason === "ua");
+  const why = headless ? "a headless browser, which is what agent-browser is, so a check you ran on the site lands here" : "a datacenter or crawler network, or headers no real browser sends";
+  return [
+    `${hidden.events} events in this window came from machines and are not listed \u2014 stored, but left out of the feed and every report (${why}). They arrived; this is not lost data. \`baker analytics feed --bots\` lists them, each with its \`botReason\`. Never present them to the client as visits.`
+  ];
+}
 function peopleSearchHints(search, rows) {
   const found = new Set(rows.flatMap((row) => Array.isArray(row.personTerms) ? row.personTerms : []));
   return search.filter((term) => !found.has(term.term)).map(
@@ -938,6 +1028,61 @@ function refineCompaniesReport(data, companies, targets) {
   return [...visitorCompanyHints(matched.companies.length > 0 ? matched.companies : companies), ...skipped, ...cut];
 }
 
+// src/commands/analytics/websiteTagCheck.ts
+var BAKER_CALL = /baker\s*\.\s*(?:track|conversion)\s*\(\s*(["'])([^"'\n]{1,120})\1/g;
+function tagHtml(raw) {
+  if (typeof raw !== "object" || raw === null) return "";
+  const parameters = raw.parameter;
+  if (!Array.isArray(parameters)) return "";
+  const html = parameters.find(
+    (parameter) => typeof parameter === "object" && parameter !== null && parameter.key === "html" && typeof parameter.value === "string"
+  );
+  return html?.value ?? "";
+}
+function checkWebsiteEvents(tags, catalog) {
+  const expected = /* @__PURE__ */ new Map();
+  for (const tag of tags) {
+    for (const match of tagHtml(tag.raw).matchAll(BAKER_CALL)) {
+      const name = match[2];
+      if (name === void 0) continue;
+      const entry = expected.get(name) ?? { tags: [], paused: true };
+      entry.tags.push(tag.name);
+      entry.paused = entry.paused && tag.paused === true;
+      expected.set(name, entry);
+    }
+  }
+  const seen = new Map((catalog ?? []).map((row) => [row.eventKey, row]));
+  const events = [...expected].map(([name, { tags: sentBy, paused }]) => {
+    const arrived = seen.get(`page:${name}`);
+    const events2 = arrived?.events ?? 0;
+    const status = paused ? "paused" : catalog === null ? "not_checked" : events2 > 0 ? "arriving" : "never_seen";
+    return { name, tags: sentBy, paused, status, events: events2, lastSeen: arrived?.lastSeen ?? null };
+  });
+  return { events };
+}
+function websiteEventCheckHints(events, days) {
+  const hints = [];
+  const missing = events.filter((event) => event.status === "never_seen");
+  if (missing.length > 0) {
+    hints.push(
+      `${missing.map((event) => `\`${event.name}\``).join(", ")}: a tag sends ${missing.length === 1 ? "it" : "them"} and no real visit brought one in ${days} days. Tag Manager only fires the tag when something on the page pushes its trigger \u2014 find out whether the page ever does: \`baker analytics debug --start\` gives the person a link that records what their browser hears, and the agent-browser recipe "what a live site tells its tag manager" reads a widget's code for when it sends each event.`
+    );
+  }
+  const paused = events.filter((event) => event.status === "paused");
+  if (paused.length > 0) {
+    hints.push(
+      `${paused.map((event) => `\`${event.name}\``).join(", ")}: every tag sending ${paused.length === 1 ? "it is" : "them is"} paused in Tag Manager, so nothing is sent. That is a setting in the container, not a fault on the site.`
+    );
+  }
+  const doubled = events.filter((event) => event.tags.length > 1);
+  if (doubled.length > 0) {
+    hints.push(
+      `${doubled.map((event) => `\`${event.name}\` (${event.tags.join(", ")})`).join("; ")}: sent by more than one tag, so one moment can arrive twice. Give each call the same \`eventId\` or keep one tag.`
+    );
+  }
+  return hints;
+}
+
 // src/commands/analytics/websiteTagHints.ts
 function asTyped(origin) {
   return origin.replace(/^https?:\/\//, "");
@@ -1136,6 +1281,7 @@ function requestBody(args, options) {
     sentTo: options.sentTo,
     eventUid: options.eventUid,
     people: options.people,
+    machines: options.machines,
     ...pageOf(args)
   };
   return Object.fromEntries(
@@ -1143,9 +1289,13 @@ function requestBody(args, options) {
   );
 }
 var EVENT_ORIGINS = ANALYTICS_EVENT_DOORS;
-function feedReportHints(feed, peopleSearch) {
+function feedReportHints(feed, data) {
   if (feed === void 0) return [];
-  return [...feedHints(feed), ...peopleSearchHints(peopleSearch ?? [], feed.rows)];
+  return [
+    ...feedHints(feed),
+    ...hiddenMachinesHints(data.hiddenMachines),
+    ...peopleSearchHints(data.peopleSearch ?? [], feed.rows)
+  ];
 }
 async function runPreset(args, options, refine) {
   const origin = args.origin === void 0 ? "" : String(args.origin);
@@ -1174,7 +1324,7 @@ async function runPreset(args, options, refine) {
     if (feed !== void 0) data.stream = feed.rows;
     const refinedHints = refine ? refine(data, response.data) : [];
     const hints = [
-      ...feedReportHints(feed, response.data.peopleSearch),
+      ...feedReportHints(feed, response.data),
       // The platform the ad blocks were scoped to, so the tagging hint can
       // only speak about the inventory it was actually given. `adParams` is one
       // platform's list; a hint drawn from it without knowing which platform
@@ -1459,6 +1609,7 @@ function feedNarrowing(args) {
     ...args.send ? { sendId: String(args.send) } : {},
     ...args["sent-to"] ? { sentTo: String(args["sent-to"]) } : {},
     ...args.uid ? { eventUid: String(args.uid) } : {},
+    ...args.bots === true ? { machines: true } : {},
     ...peopleArgs(args)
   };
 }
@@ -1512,6 +1663,11 @@ var feedCommand = presetCommand({
       description: "A file with one person per line, read like --person \u2014 a column pasted from a CRM export",
       required: false
     },
+    bots: {
+      type: "boolean",
+      description: "List ONLY the events taken for machine traffic \u2014 a headless browser (agent-browser is one: every check you run on a site from it lands here), a datacenter network \u2014 each with its `botReason`. Stored, but left out of the feed and every report. Reach for it to confirm a test visit you just made arrived; never quote these rows to the client as visitors",
+      required: false
+    },
     everything: {
       type: "boolean",
       description: "Include the rows held back by default: the ones recorded so the reports can be worked out (identifications, step views, session starts, a destination's answer already folded onto its dispatch) and embedded forms and calendars announcing that they drew. Reach for it when debugging the collector rather than an integration \u2014 an embed that draws and never fires again is only visible here",
@@ -1946,7 +2102,13 @@ var websiteTagCommand = (() => {
         type: "string",
         required: false,
         description: 'Whose activity to measure: "campaigns" (default), "outcomes" or "all"'
-      }
+      },
+      check: {
+        type: "boolean",
+        required: false,
+        description: "Every event the Tag Manager container sends Baker, and whether a real visit has brought it"
+      },
+      days: { type: "string", required: false, description: "With --check: how far back to look (default 30)" }
     }
   });
   return defineCommand({
@@ -1969,15 +2131,25 @@ Three things worth knowing before you install it:
 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 website-tag --check           \u2014 every event Tag Manager sends Baker, and which never arrived
   baker analytics events --origin website       \u2014 after it is live, what that website is reporting`
     },
     args: {
       measure: {
         type: "string",
         description: 'Whose activity to measure: "campaigns" (default), "outcomes" or "all". Widening is a decision \u2014 see above.'
-      }
+      },
+      check: {
+        type: "boolean",
+        description: 'Read the connected Tag Manager container for every window.baker.track call its tags make, and say which events a real visit has brought in the window and which never arrived. Start here when "an event is missing": an event the container sends and nobody has seen is invisible on every other report'
+      },
+      days: { type: "string", description: "With --check: how many days back to look for each event (default 30)" }
     },
     run: async (ctx) => {
+      if (ctx.args.check === true) {
+        await runWebsiteEventCheck(Number(ctx.args.days ?? 30) || 30);
+        return;
+      }
       try {
         const measure = typeof ctx.args.measure === "string" ? ctx.args.measure : void 0;
         const envelope = await apiPost(
@@ -1991,6 +2163,130 @@ Examples:
     }
   });
 })();
+async function runWebsiteEventCheck(days) {
+  let tags;
+  try {
+    tags = (await apiPost(
+      "/api/tag-manager/read",
+      { entities: ["tag"], full: true },
+      { timeoutMs: TAG_MANAGER_TIMEOUT_MS }
+    )).tags;
+  } catch (err) {
+    writeJsonEnvelope({
+      ok: false,
+      error: {
+        code: "TAG_MANAGER_UNAVAILABLE",
+        message: `The check reads the website's Tag Manager container, and it could not: ${err instanceof Error ? err.message : String(err)}`,
+        fix: {
+          action: "continue_without",
+          explanation: "Without a connected container there is no list of what the site is wired to send. Read what did arrive with `baker analytics feed --origin website`, and ask the person to connect Tag Manager if the site uses it."
+        }
+      }
+    });
+    process.exit(1);
+  }
+  try {
+    let catalog;
+    let unread = "";
+    try {
+      const response = await apiPost("/api/analytics/query", {
+        preset: "conversions",
+        eventOrigin: "website",
+        days
+      });
+      catalog = response.data.eventCatalog ?? [];
+    } catch (err) {
+      catalog = null;
+      unread = err instanceof Error ? err.message : String(err);
+    }
+    const { events } = checkWebsiteEvents(tags, catalog);
+    const hints = websiteEventCheckHints(events, days);
+    if (catalog === null) {
+      hints.push(
+        `What arrived could not be read (${unread}), so this lists what the container sends, unchecked. \`baker analytics feed --origin website\` is the other half once reading works.`
+      );
+    }
+    if (events.length === 0) {
+      hints.push(
+        "No tag in the container calls window.baker.track, so the website sends Baker page views and nothing else. Outcomes come from tags you stage with `baker tag-manager`."
+      );
+    }
+    writeJsonEnvelope({ ok: true, data: { days, events }, hints });
+  } catch (err) {
+    handleError(err);
+  }
+}
+var DEBUG_ARGS = {
+  code: {
+    type: "positional",
+    required: false,
+    description: "The code `--start` returned: read what was recorded under it"
+  },
+  start: {
+    type: "boolean",
+    required: false,
+    description: "Mint a debug link for the person to open in their own browser"
+  },
+  url: {
+    type: "string",
+    required: false,
+    description: "With --start: the page the person should open (the link is built on it)"
+  },
+  full: { type: "boolean", required: false, description: "Every record's payload, masked, not just what it was" }
+};
+registerSchema({
+  command: "analytics.debug",
+  description: "A link that records what a person's own browser heard on their website, and the read of it",
+  args: DEBUG_ARGS
+});
+var debugCommand = defineCommand({
+  meta: {
+    name: "debug",
+    description: `Watch a real visit from the person's own browser: what the page heard \u2014 messages from its iframes, custom events, dataLayer pushes \u2014 and what Baker's website tag did with it.
+
+Start here when an event from the client's own website never arrives and a test from your browser cannot settle it: a voice, video or chat widget your headless browser cannot run, a login that is theirs, a cookie banner only they answer. Your own browser is flagged as a bot and in no report, so their visit is the test that counts.
+
+  baker analytics debug --start --url https://client.com/   \u2014 a link to send them; it records for two hours
+  baker analytics debug <code>                               \u2014 what their visit recorded, in order, with what to read first
+  baker analytics debug <code> --full                        \u2014 every record's payload (emails and phones masked)
+
+Nothing recorded is counted or shown in Baker; it is purged a day later.`
+  },
+  args: DEBUG_ARGS,
+  run: async ({ args }) => {
+    try {
+      if (args.start === true) {
+        const response2 = await apiPost("/api/analytics/debug", {
+          start: true,
+          ...typeof args.url === "string" && args.url !== "" ? { url: args.url } : {}
+        });
+        writeJsonEnvelope({ ok: true, data: response2.data, hints: debugStartHints(response2.data) });
+        return;
+      }
+      if (typeof args.code !== "string" || args.code === "") {
+        writeJsonEnvelope({
+          ok: false,
+          error: {
+            code: "VALIDATION_ERROR",
+            message: "Pass --start to mint a debug link, or the code it returned to read it."
+          }
+        });
+        process.exit(1);
+      }
+      const response = await apiPost("/api/analytics/debug", {
+        code: args.code,
+        full: true
+      });
+      writeJsonEnvelope({
+        ok: true,
+        data: compactDebugRead(response.data, args.full === true),
+        hints: debugReadHints(response.data)
+      });
+    } catch (err) {
+      handleError(err);
+    }
+  }
+});
 var sitesCommand = (() => {
   registerSchema({
     command: "analytics.sites",
@@ -2108,21 +2404,22 @@ Full guide: __tooling__/docs/tools/baker/analytics.md`
     tags: tagsCommand,
     events: eventsCommand,
     feed: feedCommand,
-    lookup: () => import("./lookup-LWJMDEEL.js").then((m) => m.lookupCommand),
+    lookup: () => import("./lookup-ZJIP2M4X.js").then((m) => m.lookupCommand),
     devices: devicesCommand,
     ads: adsCommand,
     conversions: conversionsCommand,
-    sends: () => import("./sends-OLVQGOAE.js").then((m) => m.sendsCommand),
+    sends: () => import("./sends-6FI7WELX.js").then((m) => m.sendsCommand),
     map: mapCommand,
-    unstage: () => import("./unstage-QFVL7AZ4.js").then((m) => m.unstageCommand),
+    unstage: () => import("./unstage-MDSSPUKV.js").then((m) => m.unstageCommand),
     tracking: trackingCommand,
     arrivals: arrivalsCommand,
     "sending-events": sendingEventsCommand,
-    sources: () => import("./sources-PSM2A5QD.js").then((m) => m.sourcesCommand),
+    sources: () => import("./sources-L3KNVLIB.js").then((m) => m.sourcesCommand),
     "website-tag": websiteTagCommand,
+    debug: debugCommand,
     sites: sitesCommand,
-    plan: () => import("./plan-O2TTEUIW.js").then((m) => m.planCommand),
-    questionnaire: () => import("./questionnaire-VE42SW77.js").then((m) => m.questionnaireCommand),
+    plan: () => import("./plan-TVQSEKYL.js").then((m) => m.planCommand),
+    questionnaire: () => import("./questionnaire-LEZJLMAV.js").then((m) => m.questionnaireCommand),
     presets: presetsCommand
   }
 });
@@ -2135,4 +2432,4 @@ export {
   requestBody,
   sendingEventsAddress
 };
-//# sourceMappingURL=analytics-4CCQYY7Z.js.map
+//# sourceMappingURL=analytics-P5UFA6I4.js.map