@koda-sl/baker-cli 0.513.0 → 0.514.0-dev.555f7007e

package/dist/chunk-NEYWS2DQ.js

@@ -0,0 +1,479 @@
+import {
+  INGEST_MODES,
+  INGEST_MODE_HEADER
+} from "./chunk-GRQ2AXDX.js";
+import {
+  EVENT_ITEMS_MAX
+} from "./chunk-JOE42ZW6.js";
+import {
+  EVENT_INGEST_BATCH_MAX,
+  EVENT_INGEST_BODY_MAX_BYTES,
+  EVENT_INGEST_REQUESTS_PER_MINUTE,
+  FUTURE_TOLERANCE_MS,
+  MAX_EVENT_NAME,
+  MAX_ITEM_QUANTITY,
+  REJECTION_CODES,
+  STANDARD_EVENT_NAMES
+} from "./chunk-NZ34KM46.js";
+import {
+  MATCH_FIELD_FORWARDING
+} from "./chunk-G4FG5EQO.js";
+
+// ../api/src/event-ingest/arrivals.ts
+import { z } from "zod";
+var INGEST_ARRIVALS_MAX = 200;
+var INGEST_ARRIVALS_DEFAULT = 25;
+var ingestArrivalsRequestSchema = z.object({
+  /** `test` shows only rehearsals, `live` only real traffic. Absent shows both. */
+  mode: z.enum(INGEST_MODES).optional(),
+  /** `rejected` is the one worth asking for on its own — it is the whole reason to look. */
+  outcome: z.enum(["accepted", "rejected"]).optional(),
+  /** Narrow to one event name, for a company posting several kinds. */
+  eventName: z.string().max(120).optional(),
+  limit: z.coerce.number().int().positive().max(INGEST_ARRIVALS_MAX).optional().default(INGEST_ARRIVALS_DEFAULT),
+  /** Include the masked raw body and the per-field previews. Off by default — it is most of the bytes. */
+  full: z.boolean().optional()
+});
+
+// ../api/src/event-ingest/endpoint.ts
+var EVENT_INGEST_PATH = "/v1/events";
+function eventIngestUrl(brandedUrl, convexSiteUrl) {
+  if (brandedUrl) return `${brandedUrl.replace(/\/$/, "")}${EVENT_INGEST_PATH}`;
+  return `${convexSiteUrl.replace(/\/$/, "")}${EVENT_INGEST_PATH}`;
+}
+var MODE_HINT = `
+# Rehearse the same request: add -H '${INGEST_MODE_HEADER}: test'
+# It is validated and answered exactly the same way, and nothing is written.`;
+function eventIngestCurl(url, apiKey) {
+  const body = JSON.stringify({
+    events: [
+      {
+        event_name: "deal_won",
+        user_data: { email: "person@example.com" },
+        value: "1200.00",
+        currency: "EUR"
+      }
+    ]
+  });
+  return [
+    `curl -X POST ${url} \\`,
+    `  -H 'Authorization: Bearer ${apiKey}' \\`,
+    `  -H 'Content-Type: application/json' \\`,
+    `  -d '${body}'`
+  ].join("\n") + MODE_HINT;
+}
+function eventSourceCurl(url) {
+  const body = JSON.stringify({
+    events: [
+      {
+        event_name: "deal_won",
+        user_data: { email: "person@example.com" },
+        value: "1200.00",
+        currency: "EUR"
+      }
+    ]
+  });
+  return [`curl -X POST ${url} \\`, `  -H 'Content-Type: application/json' \\`, `  -d '${body}'`].join("\n");
+}
+
+// ../api/src/event-ingest/fields.ts
+var BODY_MAX_MB = EVENT_INGEST_BODY_MAX_BYTES / (1024 * 1024);
+var FUTURE_TOLERANCE_MINUTES = FUTURE_TOLERANCE_MS / 6e4;
+var HEADER_FIELDS = [
+  { name: "Authorization", need: "required", takes: "Bearer <your sending key>" },
+  { name: "Content-Type", need: "required", takes: "application/json" },
+  {
+    name: "X-Baker-Mode",
+    need: "optional",
+    takes: "live (the default) or test.",
+    // Deliberately says what a test send *is* rather than "see step 4". Every
+    // note here is read twice — on this screen, where the step below explains
+    // it in full, and inside the Markdown brief, where there are no steps and
+    // a cross-reference points at nothing.
+    note: "A test send is authenticated and validated identically and stores nothing. An unrecognised value is refused rather than assumed."
+  }
+];
+var EVENT_FIELDS = [
+  {
+    name: "event_name",
+    need: "required",
+    takes: `What happened. Up to ${MAX_EVENT_NAME} characters of letters, digits, spaces, . _ and -, starting with a letter or a digit`,
+    note: 'The only required field. Use one of the standard names below wherever one fits \u2014 anything else is yours to invent, in whatever language you name things in: a letter is a letter in any script, and "Matr\xEDcula Realizada" is a name.'
+  },
+  {
+    name: "event_time",
+    need: "optional",
+    takes: "ISO-8601 with an offset (2026-09-08T13:23:41Z), or Unix seconds (1757337821).",
+    note: `Left out, it is the moment we received it. Nothing is refused for being old \u2014 a backfill of last year's history is what this is for. More than ${FUTURE_TOLERANCE_MINUTES} minutes in the future is refused.`
+  },
+  {
+    name: "event_id",
+    need: "optional",
+    takes: "Your own id for this event: 1\u2013128 characters of letters, digits, and . _ : -",
+    note: "Send one only if you want it deduplicated \u2014 the same id twice is counted once. Send none and every post is its own event."
+  },
+  {
+    name: "user_data",
+    need: "required",
+    takes: "Who it was about. At least one field below \u2014 this is the whole of how a server event finds the person who visited a Baker page or your website.",
+    note: "No field is required on its own and the block is: an event naming nobody is refused with missing_identity. The one exception is a page_view carrying a url, because a page serve is a fact about a page."
+  },
+  {
+    name: "email",
+    need: "optional",
+    under: true,
+    takes: "The address, or its SHA-256 digest if you already hash. Either \u2014 we tell them apart.",
+    note: "Send this one if you can. It is the road that cannot silently fail: we normalise and hash it here, so it lands on exactly the person a Baker page or the pixel already recorded."
+  },
+  {
+    name: "phone",
+    need: "optional",
+    under: true,
+    takes: "The number with its country code, or its digest. Same treatment as email."
+  },
+  {
+    name: "external_id",
+    need: "optional",
+    under: true,
+    takes: "Your own id for the person \u2014 a CRM contact key.",
+    note: "Kept exactly as you send it, and hashed alongside so it joins: your own events to each other, and to a browser once one event carries it beside an email or a baker_id."
+  },
+  {
+    name: "baker_id",
+    need: "optional",
+    under: true,
+    takes: "The Baker ID one of our pages already gave this browser, if you kept it.",
+    note: "The strongest of all of them: it names the visit, so the event lands on that person's timeline rather than beside it."
+  },
+  {
+    name: "the ad click ids",
+    need: "optional",
+    under: true,
+    takes: "The click id that brought them, if you kept it, under the name the platform stamps on the link: gclid, wbraid, gbraid, dclid, fbclid, ttclid, twclid, li_fat_id, msclkid, rdt_cid, epik, sccid (Snapchat's ScCid, in any case), oppref (ChatGPT Ads).",
+    note: "A click id names a person too \u2014 it is enough on its own, and it attributes the event to the campaign that earned it."
+  },
+  {
+    name: "fbp, fbc",
+    need: "optional",
+    under: true,
+    takes: "Meta's own browser cookies (_fbp, _fbc), exactly as your site stored them.",
+    note: "Enough on their own, and worth sending: they are what Meta matches a server event on. We read the click id out of an fbc for you."
+  },
+  {
+    name: "the matching fields",
+    need: "optional",
+    under: true,
+    takes: "first_name, last_name, date_of_birth, gender, city, region, postal_code, country \u2014 Meta's advanced matching and Google's enhanced conversions, in one block. Plain or already hashed.",
+    note: "They name nobody here, so they never satisfy user_data on their own. They are kept so this event can be sent on to Meta or Google later without asking you for it all again."
+  },
+  {
+    name: "url",
+    need: "optional",
+    takes: "The full page URL this happened on.",
+    note: "Its query string is where campaign parameters and ad click ids are read from. Without it the event counts, and belongs to no page."
+  },
+  {
+    name: "value",
+    need: "optional",
+    takes: "What it was worth: a decimal string or a JSON number. No thousands separator, no sign, no exponent.",
+    note: 'Rounded to what the currency holds \u2014 1200.999 EUR is stored as 1201.00. "1,200" is refused.'
+  },
+  {
+    name: "currency",
+    need: "conditional",
+    takes: "An ISO-4217 code, e.g. EUR. Required whenever value is present, and refused on its own."
+  },
+  {
+    name: "properties",
+    need: "optional",
+    takes: "A flat object of strings \u2014 anything you want to break the event down by later."
+  },
+  {
+    name: "items",
+    need: "optional",
+    takes: "What was bought, one entry per product line \u2014 for a purchase, a cart or a refund.",
+    note: `Each line names its product by at least one of the ids below. value still carries the whole event's money. An order with more than ${EVENT_ITEMS_MAX} lines keeps the first ${EVENT_ITEMS_MAX}.`
+  },
+  {
+    name: "product_id, variant_id, feed_id",
+    need: "conditional",
+    under: true,
+    takes: "Your store's product id, its variant id, or the id the product has in your ads catalog. At least one per line, up to 255 characters each."
+  },
+  {
+    name: "quantity",
+    need: "optional",
+    under: true,
+    takes: `How many: a whole number from 1 to ${MAX_ITEM_QUANTITY.toLocaleString("en-US")}.`
+  },
+  {
+    name: "price",
+    need: "optional",
+    under: true,
+    takes: "The price of one unit, in the event's currency \u2014 so it needs currency. A decimal like value."
+  },
+  {
+    name: "consent",
+    need: "optional",
+    takes: "What the person allowed, if your site asked them.",
+    note: "Send it whenever you know it. A person who said no to marketing is still counted in your reports, and is never matched or sent to an ad platform."
+  },
+  {
+    name: "analytics",
+    need: "optional",
+    under: true,
+    takes: "granted or denied \u2014 whether they allowed being measured. Denied keeps the event and forgets who it was."
+  },
+  {
+    name: "marketing",
+    need: "optional",
+    under: true,
+    takes: "granted or denied \u2014 whether they allowed their visit to be used for advertising."
+  }
+];
+var RESPONSE_FIELDS = [
+  {
+    name: "mode",
+    need: "required",
+    takes: "live or test, echoed back \u2014 so a forgotten header is visible in the reply rather than in a report next week."
+  },
+  { name: "received", need: "required", takes: "How many events we read, so you can detect a truncated body." },
+  { name: "accepted", need: "required", takes: "How many were counted." },
+  {
+    name: "rejected",
+    need: "required",
+    takes: "One entry per refused event: index, event_id, code, message.",
+    note: "index is the position in your own array, and is the one to branch on \u2014 event_id is empty for an event that sent none."
+  }
+];
+var REJECTION_CODE_LIST = REJECTION_CODES;
+var BATCH_LIMITS = {
+  events: EVENT_INGEST_BATCH_MAX,
+  megabytes: BODY_MAX_MB,
+  requestsPerMinute: EVENT_INGEST_REQUESTS_PER_MINUTE
+};
+
+// ../api/src/event-ingest/brief.ts
+var KEY_ENV_VAR = "BAKER_EVENTS_KEY";
+var KEY_PLACEHOLDER = "<your sending key>";
+var NEED_WORD = {
+  required: "required",
+  optional: "optional",
+  conditional: "conditional"
+};
+function cell(text) {
+  return text.replaceAll("<", "\\<").replaceAll("|", "\\|");
+}
+function table(fields) {
+  const rows = fields.map((field) => {
+    const name = field.under === true ? `\u21B3 \`${field.name}\`` : `\`${field.name}\``;
+    const note = field.note === void 0 ? "" : `<br>${cell(field.note)}`;
+    return `| ${name} | ${NEED_WORD[field.need]} | ${cell(field.takes)}${note} |`;
+  });
+  return ["| Field | | What it takes |", "| --- | --- | --- |", ...rows].join("\n");
+}
+function standardNames() {
+  return [
+    "| Name | Means |",
+    "| --- | --- |",
+    ...STANDARD_EVENT_NAMES.map((standard) => `| \`${standard.name}\` | ${standard.means} |`)
+  ].join("\n");
+}
+function forwarding() {
+  return [
+    "| Field | Meta | Google | Held as |",
+    "| --- | --- | --- | --- |",
+    ...MATCH_FIELD_FORWARDING.map(
+      (row) => `| \`${row.field}\` | \`${row.meta}\` | ${row.google === null ? "\u2014" : `\`${row.google}\``} | ${row.hashed ? "SHA-256" : "plain text"} |`
+    )
+  ].join("\n");
+}
+function ingestBrief(endpointUrl) {
+  return brief(endpointUrl, "key");
+}
+function keyRules(door) {
+  if (door === "address") {
+    return `1. **The address is the credential. Never put it in source, and never paste it into a chat.**
+   Read it from \`BAKER_EVENTS_URL\` and ask the person for the value \u2014 they can copy it
+   from Baker \u2192 Measure \u2192 Sources, on the source's own page.
+2. **The first send is a rehearsal.** While the source reads "Waiting for your first event"
+   in Baker, every request is parsed, validated and answered exactly as a live one and
+   **stores nothing**; the person then confirms what to read from it and it counts from
+   there. Nothing about the integration changes when it does.`;
+  }
+  return `1. **Never put the sending key in source, and never paste it into a chat.** It is
+   deliberately not in this document. Read it from \`${KEY_ENV_VAR}\` and ask the person
+   for the value \u2014 they can copy it from Baker \u2192 Measure \u2192 Events \u2192 Sending events.
+2. **Send \`X-Baker-Mode: test\` while you build.** A test request is authenticated,
+   parsed and validated in exactly the same way and answers in exactly the same shape,
+   and **stores nothing**. Remove the header to go live. There is no separate test key
+   and no separate endpoint, so nothing about the integration changes when it does.`;
+}
+function brief(endpointUrl, door) {
+  const { events, megabytes, requestsPerMinute } = BATCH_LIMITS;
+  const headers = door === "address" ? HEADER_FIELDS.filter((field) => field.name === "Content-Type") : HEADER_FIELDS;
+  const credentialRow = door === "address" ? "| `404` | Nothing is listening at this address: it is wrong, or the source was removed. | Fix the address. Do not retry. |" : "| `401` | The key is missing, wrong, or not a sending key. | Fix the credential. Do not retry. |";
+  const request = door === "address" ? eventSourceCurl(endpointUrl) : eventIngestCurl(endpointUrl, KEY_PLACEHOLDER);
+  return `# Send events to Baker's API from your server
+
+You are being handed this by somebody who wants an integration built against it. It is
+the complete contract for ${door === "address" ? "a Baker source's address" : "`POST /v1/events`"} on **their own Baker endpoint**, taken from
+the code that enforces it. Build from this document; you should not need to look
+anything else up.
+
+Baker measures what happens on the pages it publishes. This endpoint is how everything
+that happens *away* from those pages \u2014 a deal closing in a CRM, a subscription starting,
+an order shipping \u2014 reaches the same reports, joined to the same person.
+
+## Read this before you write anything
+
+${keyRules(door)}
+3. **A \`200\` does not mean it counted.** The body carries \`rejected[]\`, one entry per
+   refused event. Read it and log it on every response. Throwing it away is the single
+   most common way an integration against this endpoint is wrong and looks right.
+4. **Batch.** Up to ${events} events and ${megabytes} MB per request, and at most
+   ${requestsPerMinute} requests per minute for the whole company. One event per request
+   works and will exhaust that budget on any real backfill. Every event is judged on its
+   own, so one bad row is refused and the rest of the batch still counts.
+5. **Retry \`5xx\` and \`429\`, never \`4xx\`.** A \`4xx\` means the request is wrong and
+   will be wrong again. If you retry, send the same \`event_id\` \u2014 that is what makes the
+   retry count once.
+6. **A refund is its own event, not a negative amount.** \`value\` may not be negative.
+   Send an event with its own name and let the reports subtract.
+7. **You cannot declare a conversion.** Whether an event counts as one is a decision the
+   client makes in Baker, against the event's name, and it applies retroactively to
+   everything already sent under that name. Nothing in the payload can assert it.
+8. **Ask, do not guess.** Which events matter and where the person's email lives in their
+   system are things this document cannot tell you. Ask.
+
+## Endpoint
+
+\`\`\`
+POST ${endpointUrl}
+\`\`\`
+
+### Headers
+
+${table(headers)}
+
+### Body
+
+\`\`\`json
+{ "events": [ { "event_name": "..." } ] }
+\`\`\`
+
+Up to ${events} events and ${megabytes} MB per request.
+
+## The event
+
+The field names are Meta's. If you have written an integration against Meta's Conversions
+API or Google Ads' offline conversion upload, this is the same payload: \`event_name\`,
+\`event_time\`, \`event_id\`, \`user_data\`, \`value\`, \`currency\`.
+
+${table(EVENT_FIELDS)}
+
+### Naming the person is the part that matters
+
+\`user_data\` is required and every field in it is optional, which is not a contradiction:
+the event has to name **somebody**, and there are several ways to do it. An event that
+names nobody is refused with \`missing_identity\`.
+
+Ranked by how well each works, best first:
+
+1. \`baker_id\` \u2014 the id a Baker page already gave that browser. It names the *visit*, so
+   the event lands on a real session's timeline. Send it if the client's system kept it.
+2. \`email\` or \`phone\` \u2014 the road that cannot silently fail. Send the plain value if you
+   can: we normalise and hash it here under the same rule the browser uses, so it lands
+   on exactly the person the pages already recorded. If policy forbids sending it plain,
+   send the SHA-256 digest **in the same field** \u2014 we detect which it is. Hash the
+   trimmed, lower-cased address; for a phone, digits with a leading \`+\`.
+3. \`external_id\` \u2014 the client's own key for the person, a CRM contact id. Stored as sent,
+   and hashed alongside so it joins.
+   On its own it joins that system's events to each other; send it **once** alongside an
+   email or a \`baker_id\` and every later event carrying only the contact id joins the
+   person too. That link is retroactive: it reaches back to everything already sent.
+4. A click id, \`fbp\` or \`fbc\` \u2014 names the click or the browser that brought them, which
+   is what a report attributes the event to.
+
+Send every one you have, not just the best. They cost nothing extra and each is a
+separate chance to match.
+
+### The matching fields, and where they go afterwards
+
+\`first_name\` \u2026 \`country\` never satisfy \`user_data\` on their own \u2014 they describe a
+person and name nobody. They are worth sending anyway: they are exactly what Meta's
+advanced matching and Google's enhanced conversions match on, and keeping them means the
+event can be forwarded later without going back to the client's CRM for it.
+
+${forwarding()}
+
+## Standard event names
+
+Nothing is refused for being absent from this list \u2014 send whatever the business calls a
+thing. These are the spellings Baker publishes so that two companies measuring the same
+thing measure it under the same word. \`page_view\` is the one with behaviour: it becomes
+a page view rather than a named event, and it is the only event that may arrive without a
+person as long as it carries a \`url\`.
+
+${standardNames()}
+
+## The response
+
+\`\`\`json
+{ "ok": true, "data": { "mode": "live", "received": 2, "accepted": 1,
+  "rejected": [ { "index": 1, "event_id": "", "code": "invalid_value",
+    "message": "value and currency go together: a non-negative decimal and an ISO-4217 code" } ] } }
+\`\`\`
+
+${table(RESPONSE_FIELDS)}
+
+\`code\` is a closed set \u2014 branch on it, not on \`message\`:
+
+${REJECTION_CODE_LIST.map((code) => `- \`${code}\``).join("\n")}
+
+There is no duplicate count, on purpose. A repeated \`event_id\` is accepted like any other
+event and counted **once** \u2014 one conversion, one event, its value added once \u2014 so a retry
+is safe and needs no branch of its own. Both requests are shown in Baker, with the later
+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.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,
+with nothing anywhere reporting an error.
+
+### HTTP statuses
+
+| Status | Means | Do |
+| --- | --- | --- |
+| \`200\` | The request was read. Individual events may still have been refused. | Read \`rejected[]\`. |
+| \`400\` | The body is not the shape above \u2014 an unknown field, or the wrong JSON type. | Fix the payload. Do not retry. |
+${credentialRow}
+| \`413\` | Over ${events} events or ${megabytes} MB. | Split the batch and re-post. |
+| \`429\` | Over ${requestsPerMinute} requests a minute for this company. | Back off and retry. |
+| \`5xx\` | Nothing was written. | Retry with the same \`event_id\`s. |
+
+## A request that works
+
+\`\`\`bash
+${request}
+\`\`\`
+
+## Once it is sending
+
+Every accepted event appears in Baker under **Measure \u2192 Events**, live, with what was
+sent. Test sends and refusals appear there too, filed separately and marked, with the
+payload \u2014 so "did my request arrive and what did it say" is answered on the screen rather
+than in the client's own logs. To make an event count as a conversion, the client marks
+it by name under **Conversions**.
+`;
+}
+
+export {
+  INGEST_ARRIVALS_MAX,
+  eventIngestUrl,
+  ingestBrief
+};
+//# sourceMappingURL=chunk-NEYWS2DQ.js.map

package/dist/chunk-NKQWDEB7.js

@@ -0,0 +1,115 @@
+import {
+  MATCH_FIELDS
+} from "./chunk-G4FG5EQO.js";
+
+// ../api/src/event-ingest/vocabulary.ts
+var INGEST_CLICK_ID_PARAMS = [
+  "gclid",
+  "wbraid",
+  "gbraid",
+  "dclid",
+  "fbclid",
+  "ttclid",
+  "twclid",
+  "li_fat_id",
+  "msclkid",
+  "rdt_cid",
+  "epik",
+  "sccid",
+  "oppref"
+];
+
+// ../api/src/event-sources/fields.ts
+var MATCH_LABELS = {
+  first_name: "First name",
+  last_name: "Last name",
+  date_of_birth: "Date of birth",
+  gender: "Gender",
+  city: "City",
+  region: "Region",
+  postal_code: "Postcode",
+  country: "Country"
+};
+var CLICK_LABELS = {
+  gclid: "Google click id",
+  wbraid: "Google click id (iOS, web to app)",
+  gbraid: "Google click id (iOS, app)",
+  dclid: "Google click id (Display & Video)",
+  fbclid: "Meta click id",
+  ttclid: "TikTok click id",
+  twclid: "X click id",
+  li_fat_id: "LinkedIn click id",
+  msclkid: "Microsoft click id",
+  rdt_cid: "Reddit click id",
+  epik: "Pinterest click id",
+  sccid: "Snapchat click id",
+  oppref: "ChatGPT Ads click id"
+};
+var SOURCE_FIELDS = [
+  { field: "event_name", label: "What happened", group: "event" },
+  { field: "event_time", label: "When it happened", group: "event" },
+  { field: "event_id", label: "Its id", group: "event" },
+  { field: "email", label: "Email", group: "person" },
+  { field: "phone", label: "Phone", group: "person" },
+  { field: "external_id", label: "Your own id for the person", group: "person" },
+  ...MATCH_FIELDS.map((field) => ({ field, label: MATCH_LABELS[field], group: "person" })),
+  { field: "value", label: "Amount", group: "money" },
+  { field: "currency", label: "Currency", group: "money" },
+  ...INGEST_CLICK_ID_PARAMS.map((field) => ({ field, label: CLICK_LABELS[field], group: "click" }))
+];
+var SOURCE_FIELD_NAMES = SOURCE_FIELDS.map((spec) => spec.field);
+var FIELD_SET = new Set(SOURCE_FIELD_NAMES);
+function isSourceField(value) {
+  return FIELD_SET.has(value);
+}
+var PROPERTY_ROW_PREFIX = "properties.";
+var PROPERTY_KEY_MAX = 64;
+var PROPERTY_KEY = /^[A-Za-z0-9_][A-Za-z0-9_.-]*$/;
+var RESERVED_PROPERTY_KEYS = ["baker_source", "hubspot_property", "hubspot_value"];
+function isPropertyRow(row) {
+  return row.startsWith(PROPERTY_ROW_PREFIX);
+}
+function propertyKeyOf(row) {
+  return isPropertyRow(row) ? row.slice(PROPERTY_ROW_PREFIX.length) : null;
+}
+function propertyKeyProblem(key) {
+  const trimmed = key.trim();
+  if (trimmed === "") return "A property needs a name.";
+  if (trimmed.length > PROPERTY_KEY_MAX) return `A property name is at most ${PROPERTY_KEY_MAX} characters.`;
+  if (!PROPERTY_KEY.test(trimmed)) {
+    return `"${trimmed}" is not a property name: letters, digits, underscore, dash and dot only, starting with a letter or digit.`;
+  }
+  if (RESERVED_PROPERTY_KEYS.includes(trimmed)) return `"${trimmed}" is written by Baker itself; pick another name.`;
+  return null;
+}
+function mappingRowProblem(row) {
+  if (isSourceField(row)) return null;
+  const key = propertyKeyOf(row);
+  if (key === null) {
+    return `"${row}" is not a field an event can carry. A field is one of ${SOURCE_FIELD_NAMES.join(", ")}; an extra property is spelled properties.<name>.`;
+  }
+  return propertyKeyProblem(key);
+}
+
+// ../api/src/event-sources/template.ts
+var MENTION = /\{\{\s*([^{}]+?)\s*\}\}/g;
+function mentionOf(path) {
+  return `{{${path}}}`;
+}
+function templateMentions(template) {
+  const seen = [];
+  for (const match of template.matchAll(MENTION)) {
+    const path = (match[1] ?? "").trim();
+    if (path !== "" && !seen.includes(path)) seen.push(path);
+  }
+  return seen;
+}
+
+export {
+  INGEST_CLICK_ID_PARAMS,
+  SOURCE_FIELD_NAMES,
+  mappingRowProblem,
+  mentionOf,
+  templateMentions
+};
+//# sourceMappingURL=chunk-NKQWDEB7.js.map

package/dist/chunk-NKQWDEB7.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../api/src/event-ingest/vocabulary.ts","../../api/src/event-sources/fields.ts","../../api/src/event-sources/template.ts"],"sourcesContent":["/**\n * The click ids a sender may hand over, named the way their own system stored\n * them.\n *\n * The wire uses the **URL parameter** spelling (`li_fat_id`) rather than the\n * analytics row's field spelling (`liFatId`), because a client's CRM captured\n * these off a landing URL and that is the name it wrote them down under.\n * {@link clickIdsFromWire} is the one place the two vocabularies meet.\n *\n * Mirrored from `CLICK_ID_FIELDS` in `../analytics/normalize.ts`, which is the\n * source of truth for which click ids the store has columns for.\n * `vocabulary.parity.test.ts` reads that file and fails if the two drift — a\n * missing entry here is an attribution a client sent and we dropped.\n */\n\nimport type { ClickIdFields } from \"../analytics/normalize\";\n\nexport const INGEST_CLICK_ID_PARAMS = [\n  \"gclid\",\n  \"wbraid\",\n  \"gbraid\",\n  \"dclid\",\n  \"fbclid\",\n  \"ttclid\",\n  \"twclid\",\n  \"li_fat_id\",\n  \"msclkid\",\n  \"rdt_cid\",\n  \"epik\",\n  \"sccid\",\n  \"oppref\",\n] as const;\nexport type IngestClickIdParam = (typeof INGEST_CLICK_ID_PARAMS)[number];\n\nconst FIELD_FOR_PARAM: Readonly<Record<IngestClickIdParam, keyof ClickIdFields>> = {\n  gclid: \"gclid\",\n  wbraid: \"wbraid\",\n  gbraid: \"gbraid\",\n  dclid: \"dclid\",\n  fbclid: \"fbclid\",\n  ttclid: \"ttclid\",\n  twclid: \"twclid\",\n  li_fat_id: \"liFatId\",\n  msclkid: \"msclkid\",\n  rdt_cid: \"rdtCid\",\n  epik: \"epik\",\n  sccid: \"sccid\",\n  oppref: \"oppref\",\n};\n\n/** The wire's click block as the analytics row builder names its fields. Empty values are dropped. */\nexport function clickIdsFromWire(click: Partial<Record<IngestClickIdParam, string | null>> | null | undefined): {\n  clickIds: ClickIdFields;\n  kinds: IngestClickIdParam[];\n} {\n  const clickIds: ClickIdFields = {};\n  const kinds: IngestClickIdParam[] = [];\n  for (const param of INGEST_CLICK_ID_PARAMS) {\n    const value = click?.[param];\n    if (typeof value !== \"string\" || value === \"\") continue;\n    clickIds[FIELD_FOR_PARAM[param]] = value;\n    kinds.push(param);\n  }\n  return { clickIds, kinds };\n}\n","/**\n * What a source can be read into: the fields of an event, named the way\n * `POST /v1/events` already names them.\n *\n * Assembled from the ingest vocabulary rather than spelled a fourth time. A\n * mapping is `SourceField → dotted path`, and the field half of that pair has\n * to be a name the wire already accepts, because the whole of what a source\n * does is build an `IngestEventInput` and hand it to the same door the\n * client's own server would have used. A field that existed only here would be\n * a field the event could not carry.\n */\n\nimport { MATCH_FIELDS, type MatchField } from \"../event-ingest/matching\";\nimport type { IngestClickIdParam } from \"../event-ingest/vocabulary\";\nimport { INGEST_CLICK_ID_PARAMS } from \"../event-ingest/vocabulary\";\n\n/** Where a field sits on the sheet: one row per group, in this order. */\nexport type SourceFieldGroup = \"event\" | \"person\" | \"money\" | \"click\";\n\nexport type SourceField =\n  | \"event_name\"\n  | \"event_time\"\n  | \"event_id\"\n  | \"email\"\n  | \"phone\"\n  | \"external_id\"\n  | MatchField\n  | \"value\"\n  | \"currency\"\n  | IngestClickIdParam;\n\nexport interface SourceFieldSpec {\n  field: SourceField;\n  /** The product word for it — what the sheet and the CLI show. */\n  label: string;\n  group: SourceFieldGroup;\n}\n\nconst MATCH_LABELS: Readonly<Record<MatchField, string>> = {\n  first_name: \"First name\",\n  last_name: \"Last name\",\n  date_of_birth: \"Date of birth\",\n  gender: \"Gender\",\n  city: \"City\",\n  region: \"Region\",\n  postal_code: \"Postcode\",\n  country: \"Country\",\n};\n\nconst CLICK_LABELS: Readonly<Record<IngestClickIdParam, string>> = {\n  gclid: \"Google click id\",\n  wbraid: \"Google click id (iOS, web to app)\",\n  gbraid: \"Google click id (iOS, app)\",\n  dclid: \"Google click id (Display & Video)\",\n  fbclid: \"Meta click id\",\n  ttclid: \"TikTok click id\",\n  twclid: \"X click id\",\n  li_fat_id: \"LinkedIn click id\",\n  msclkid: \"Microsoft click id\",\n  rdt_cid: \"Reddit click id\",\n  epik: \"Pinterest click id\",\n  sccid: \"Snapchat click id\",\n  oppref: \"ChatGPT Ads click id\",\n};\n\nexport const SOURCE_FIELDS: readonly SourceFieldSpec[] = [\n  { field: \"event_name\", label: \"What happened\", group: \"event\" },\n  { field: \"event_time\", label: \"When it happened\", group: \"event\" },\n  { field: \"event_id\", label: \"Its id\", group: \"event\" },\n  { field: \"email\", label: \"Email\", group: \"person\" },\n  { field: \"phone\", label: \"Phone\", group: \"person\" },\n  { field: \"external_id\", label: \"Your own id for the person\", group: \"person\" },\n  ...MATCH_FIELDS.map((field) => ({ field, label: MATCH_LABELS[field], group: \"person\" as const })),\n  { field: \"value\", label: \"Amount\", group: \"money\" },\n  { field: \"currency\", label: \"Currency\", group: \"money\" },\n  ...INGEST_CLICK_ID_PARAMS.map((field) => ({ field, label: CLICK_LABELS[field], group: \"click\" as const })),\n];\n\nexport const SOURCE_FIELD_NAMES: readonly SourceField[] = SOURCE_FIELDS.map((spec) => spec.field);\n\nconst FIELD_SET: ReadonlySet<string> = new Set(SOURCE_FIELD_NAMES);\n\nexport function isSourceField(value: string): value is SourceField {\n  return FIELD_SET.has(value);\n}\n\nexport const SOURCE_FIELD_GROUPS: readonly { group: SourceFieldGroup; label: string; detail: string }[] = [\n  { group: \"event\", label: \"The event\", detail: \"What it is called, when it happened, and its own id.\" },\n  {\n    group: \"person\",\n    label: \"Who it is about\",\n    detail: \"How the platforms find the person. Email or phone is the one that matters.\",\n  },\n  {\n    group: \"money\",\n    label: \"What it was worth\",\n    detail: \"The amount and its currency, for revenue and for the platforms.\",\n  },\n  {\n    group: \"click\",\n    label: \"The ad click that brought them\",\n    detail: \"When the source keeps the click id, the campaign gets the credit.\",\n  },\n];\n\n/**\n * A row that is not a field of the event but one of its own **properties** —\n * the flat `properties` object every event carries, which Measure → Events\n * breaks an event down by and which a send can forward to a platform as an\n * extra parameter (Meta's `custom_data`, a GA4 event parameter).\n *\n * Spelled `properties.<key>` in the mapping so the row shares the table with\n * the fields and the CLI's `--field` takes it unchanged, while an unknown bare\n * key is still refused: the namespace is what tells a deliberate extra\n * property from a typo that would otherwise silently map nothing.\n */\nexport const PROPERTY_ROW_PREFIX = \"properties.\";\n\n/** The longest a property's key may be. Keys are a shared dictionary in the store, so they are kept short and plain. */\nexport const PROPERTY_KEY_MAX = 64;\n\n/** Letters, digits, underscore, dash and dot — what a property key of `POST /v1/events` may be, and what a platform parameter name may be. */\nconst PROPERTY_KEY = /^[A-Za-z0-9_][A-Za-z0-9_.-]*$/;\n\n/** Keys a source writes itself; a row naming one would be overwritten in silence. */\nexport const RESERVED_PROPERTY_KEYS: readonly string[] = [\"baker_source\", \"hubspot_property\", \"hubspot_value\"];\n\n/** Whether a mapping row names a property rather than a field. */\nexport function isPropertyRow(row: string): boolean {\n  return row.startsWith(PROPERTY_ROW_PREFIX);\n}\n\n/** The property's own key, for a `properties.<key>` row; null for anything else. */\nexport function propertyKeyOf(row: string): string | null {\n  return isPropertyRow(row) ? row.slice(PROPERTY_ROW_PREFIX.length) : null;\n}\n\n/** The mapping row for a property key. */\nexport function propertyRow(key: string): string {\n  return `${PROPERTY_ROW_PREFIX}${key}`;\n}\n\n/**\n * Why a property key cannot be used, in one sentence, or null when it can.\n * The same rule for a source's extra properties and for a send's parameters.\n */\nexport function propertyKeyProblem(key: string): string | null {\n  const trimmed = key.trim();\n  if (trimmed === \"\") return \"A property needs a name.\";\n  if (trimmed.length > PROPERTY_KEY_MAX) return `A property name is at most ${PROPERTY_KEY_MAX} characters.`;\n  if (!PROPERTY_KEY.test(trimmed)) {\n    return `\"${trimmed}\" is not a property name: letters, digits, underscore, dash and dot only, starting with a letter or digit.`;\n  }\n  if (RESERVED_PROPERTY_KEYS.includes(trimmed)) return `\"${trimmed}\" is written by Baker itself; pick another name.`;\n  return null;\n}\n\n/**\n * Whether a mapping row is one a source can hold: a field of the event, or a\n * well-named property. The reason when it is not.\n */\nexport function mappingRowProblem(row: string): string | null {\n  if (isSourceField(row)) return null;\n  const key = propertyKeyOf(row);\n  if (key === null) {\n    return `\"${row}\" is not a field an event can carry. A field is one of ${SOURCE_FIELD_NAMES.join(\", \")}; an extra property is spelled properties.<name>.`;\n  }\n  return propertyKeyProblem(key);\n}\n\n/** The property rows of a mapping, as `key → template`, in the order stored. */\nexport function propertyRows(mapping: Readonly<Record<string, string>>): { key: string; template: string }[] {\n  return Object.entries(mapping).flatMap(([row, template]) => {\n    const key = propertyKeyOf(row);\n    return key === null ? [] : [{ key, template }];\n  });\n}\n","/**\n * A mapping row is a template: literal text with `{{mentions}}` in it.\n *\n * ## Why a template and not a path\n *\n * A row used to hold one dotted path, and one path answers one question —\n * \"which field of the payload is the email\". It cannot answer the next three:\n * a currency the tool never sends but the company knows (`EUR`), a name split\n * over two fields (`{{firstname}} {{lastname}}`), or an amount a HubSpot\n * contact carries under a property nobody would guess. A template answers all\n * of them with one rule the Forms builder already teaches: type text, insert\n * a variable. The same spelling is what the CLI takes, so an agent and a\n * person write the same thing.\n *\n * ## What a mention points at\n *\n * Whatever the source can read. For an address it is a dotted path into the\n * payload (`contact.email`, `deal.contacts.0.email`); for a HubSpot read it\n * is a contact property's internal name (`hs_google_click_id`), plus `id` for\n * the contact's own id. The template does not know which — the lookup passed\n * to `renderTemplate` does.\n *\n * A mention names exactly one thing. There was a `{{phone|mobilephone}}`\n * spelling for \"the first that holds anything\"; it is gone, because it was a\n * rule the Forms builder's variables do not have, and a row that reads\n * differently from every other variable field in the product is a row nobody\n * can predict. A person who wants the mobile picks the mobile.\n */\n\nconst MENTION = /\\{\\{\\s*([^{}]+?)\\s*\\}\\}/g;\n\n/** The path a mention names, with the braces on. */\nexport function mentionOf(path: string): string {\n  return `{{${path}}}`;\n}\n\n/** Every path a template reads, in order, once each. */\nexport function templateMentions(template: string): string[] {\n  const seen: string[] = [];\n  for (const match of template.matchAll(MENTION)) {\n    const path = (match[1] ?? \"\").trim();\n    if (path !== \"\" && !seen.includes(path)) seen.push(path);\n  }\n  return seen;\n}\n\n/**\n * The template with every mention replaced by what it points at, trimmed —\n * or nothing, when what is left is empty. An empty mention reads as empty\n * text rather than as its own spelling, so a template made only of mentions\n * the payload did not fill is \"not sent\", not the literal `{{phone}}`.\n */\nexport function renderTemplate(template: string, lookup: (path: string) => string | undefined): string | undefined {\n  const rendered = template.replace(MENTION, (_whole, path: string) => lookup(path.trim()) ?? \"\").trim();\n  return rendered === \"\" ? undefined : rendered;\n}\n\n/** The one path a template is, when it is exactly one mention and nothing else. */\nexport function isBareMention(template: string): string | null {\n  const match = /^\\{\\{\\s*([^{}]+?)\\s*\\}\\}$/.exec(template.trim());\n  return match === null ? null : (match[1] ?? null);\n}\n"],"mappings":";;;;;AAiBO,IAAM,yBAAyB;AAAA,EACpC;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF;;;ACOA,IAAM,eAAqD;AAAA,EACzD,YAAY;AAAA,EACZ,WAAW;AAAA,EACX,eAAe;AAAA,EACf,QAAQ;AAAA,EACR,MAAM;AAAA,EACN,QAAQ;AAAA,EACR,aAAa;AAAA,EACb,SAAS;AACX;AAEA,IAAM,eAA6D;AAAA,EACjE,OAAO;AAAA,EACP,QAAQ;AAAA,EACR,QAAQ;AAAA,EACR,OAAO;AAAA,EACP,QAAQ;AAAA,EACR,QAAQ;AAAA,EACR,QAAQ;AAAA,EACR,WAAW;AAAA,EACX,SAAS;AAAA,EACT,SAAS;AAAA,EACT,MAAM;AAAA,EACN,OAAO;AAAA,EACP,QAAQ;AACV;AAEO,IAAM,gBAA4C;AAAA,EACvD,EAAE,OAAO,cAAc,OAAO,iBAAiB,OAAO,QAAQ;AAAA,EAC9D,EAAE,OAAO,cAAc,OAAO,oBAAoB,OAAO,QAAQ;AAAA,EACjE,EAAE,OAAO,YAAY,OAAO,UAAU,OAAO,QAAQ;AAAA,EACrD,EAAE,OAAO,SAAS,OAAO,SAAS,OAAO,SAAS;AAAA,EAClD,EAAE,OAAO,SAAS,OAAO,SAAS,OAAO,SAAS;AAAA,EAClD,EAAE,OAAO,eAAe,OAAO,8BAA8B,OAAO,SAAS;AAAA,EAC7E,GAAG,aAAa,IAAI,CAAC,WAAW,EAAE,OAAO,OAAO,aAAa,KAAK,GAAG,OAAO,SAAkB,EAAE;AAAA,EAChG,EAAE,OAAO,SAAS,OAAO,UAAU,OAAO,QAAQ;AAAA,EAClD,EAAE,OAAO,YAAY,OAAO,YAAY,OAAO,QAAQ;AAAA,EACvD,GAAG,uBAAuB,IAAI,CAAC,WAAW,EAAE,OAAO,OAAO,aAAa,KAAK,GAAG,OAAO,QAAiB,EAAE;AAC3G;AAEO,IAAM,qBAA6C,cAAc,IAAI,CAAC,SAAS,KAAK,KAAK;AAEhG,IAAM,YAAiC,IAAI,IAAI,kBAAkB;AAE1D,SAAS,cAAc,OAAqC;AACjE,SAAO,UAAU,IAAI,KAAK;AAC5B;AAgCO,IAAM,sBAAsB;AAG5B,IAAM,mBAAmB;AAGhC,IAAM,eAAe;AAGd,IAAM,yBAA4C,CAAC,gBAAgB,oBAAoB,eAAe;AAGtG,SAAS,cAAc,KAAsB;AAClD,SAAO,IAAI,WAAW,mBAAmB;AAC3C;AAGO,SAAS,cAAc,KAA4B;AACxD,SAAO,cAAc,GAAG,IAAI,IAAI,MAAM,oBAAoB,MAAM,IAAI;AACtE;AAWO,SAAS,mBAAmB,KAA4B;AAC7D,QAAM,UAAU,IAAI,KAAK;AACzB,MAAI,YAAY,GAAI,QAAO;AAC3B,MAAI,QAAQ,SAAS,iBAAkB,QAAO,8BAA8B,gBAAgB;AAC5F,MAAI,CAAC,aAAa,KAAK,OAAO,GAAG;AAC/B,WAAO,IAAI,OAAO;AAAA,EACpB;AACA,MAAI,uBAAuB,SAAS,OAAO,EAAG,QAAO,IAAI,OAAO;AAChE,SAAO;AACT;AAMO,SAAS,kBAAkB,KAA4B;AAC5D,MAAI,cAAc,GAAG,EAAG,QAAO;AAC/B,QAAM,MAAM,cAAc,GAAG;AAC7B,MAAI,QAAQ,MAAM;AAChB,WAAO,IAAI,GAAG,0DAA0D,mBAAmB,KAAK,IAAI,CAAC;AAAA,EACvG;AACA,SAAO,mBAAmB,GAAG;AAC/B;;;AC3IA,IAAM,UAAU;AAGT,SAAS,UAAU,MAAsB;AAC9C,SAAO,KAAK,IAAI;AAClB;AAGO,SAAS,iBAAiB,UAA4B;AAC3D,QAAM,OAAiB,CAAC;AACxB,aAAW,SAAS,SAAS,SAAS,OAAO,GAAG;AAC9C,UAAM,QAAQ,MAAM,CAAC,KAAK,IAAI,KAAK;AACnC,QAAI,SAAS,MAAM,CAAC,KAAK,SAAS,IAAI,EAAG,MAAK,KAAK,IAAI;AAAA,EACzD;AACA,SAAO;AACT;","names":[]}