@koda-sl/baker-cli 0.497.0 → 0.498.0

package/dist/chunk-UWABLMIK.js

@@ -0,0 +1,479 @@
+import {
+  INGEST_MODES,
+  INGEST_MODE_HEADER
+} from "./chunk-GRQ2AXDX.js";
+import {
+  EVENT_ITEMS_MAX
+} from "./chunk-TEX7Z7WC.js";
+import {
+  MATCH_FIELD_FORWARDING
+} from "./chunk-EDLZGTGN.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-K5X62YHZ.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-UWABLMIK.js.map

package/dist/chunk-UWABLMIK.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../api/src/event-ingest/arrivals.ts","../../api/src/event-ingest/endpoint.ts","../../api/src/event-ingest/fields.ts","../../api/src/event-ingest/brief.ts"],"sourcesContent":["/**\n * The 48-hour arrival log, as the CLI asks for it and gets it back.\n *\n * ## The question this answers, and where it used to have to be answered\n *\n * \"My server posts to `/v1/events` and nothing shows up.\" Every part of that\n * sentence can be wrong in a different place, and the endpoint is deliberately\n * quiet about all of them: a refused event comes back inside a `200` as\n * `rejected: [{ code }]`, which every HTTP client on earth throws away, and a\n * rehearsal is accepted, answered identically, and writes nothing at all.\n *\n * So the log is the only record of what actually arrived — and until this\n * existed it could only be read on the dashboard. The agent a client asks to\n * fix the integration had no way to look at it, which meant the one surface\n * built for debugging this was invisible to the one reader most often asked to\n * debug it.\n *\n * ## Names, never values\n *\n * The log's own rule, and it survives the trip out here: `identityKeys` says\n * *which* fields the request carried, `preview` shows only as much of one as\n * `./preview` allows (`l***@empresa.com`), and the raw body — already masked\n * before it was ever persisted — is behind `--full`. Nothing here can recover a\n * person, which is what makes it safe to hand to an agent whose output lands in\n * a chat log.\n */\n\nimport { z } from \"zod\";\nimport { INGEST_MODES } from \"./mode\";\n\n/** How many arrivals one call may return. The table is 48 hours of one company's requests. */\nexport const INGEST_ARRIVALS_MAX = 200;\nconst INGEST_ARRIVALS_DEFAULT = 25;\n\nexport const ingestArrivalsRequestSchema = z.object({\n  /** `test` shows only rehearsals, `live` only real traffic. Absent shows both. */\n  mode: z.enum(INGEST_MODES).optional(),\n  /** `rejected` is the one worth asking for on its own — it is the whole reason to look. */\n  outcome: z.enum([\"accepted\", \"rejected\"]).optional(),\n  /** Narrow to one event name, for a company posting several kinds. */\n  eventName: z.string().max(120).optional(),\n  limit: z.coerce.number().int().positive().max(INGEST_ARRIVALS_MAX).optional().default(INGEST_ARRIVALS_DEFAULT),\n  /** Include the masked raw body and the per-field previews. Off by default — it is most of the bytes. */\n  full: z.boolean().optional(),\n});\nexport type IngestArrivalsRequest = z.infer<typeof ingestArrivalsRequestSchema>;\n\n/**\n * One request, as it was received.\n *\n * A `type` rather than an `interface`, and not by accident: the CLI writes the\n * whole envelope through `writeJsonEnvelope(Record<string, unknown>)`, and\n * TypeScript gives a type alias an implicit index signature where an interface\n * gets none. Every sibling response in `@baker/api` is a `z.infer`, which is a\n * type alias, which is why none of them ever hit this.\n */\nexport type IngestArrivalRow = {\n  /** ISO-8601, UTC — when we received it, which is not necessarily when it happened. */\n  receivedAt: string;\n  mode: string;\n  outcome: string;\n  eventName: string;\n  /** The sender's own id, when they sent one. Empty means every post is its own event. */\n  eventId: string;\n  /** ISO-8601 of `event_time`, or empty when the sender let it default to arrival. */\n  occurredAt: string;\n  /** Closed set — see `REJECTION_CODES`. Empty on an accepted request. */\n  rejectCode: string;\n  rejectMessage: string;\n  /** Which `user_data` fields the request carried. Names only. */\n  identityKeys: string[];\n  /** `{ key, preview }` per field — `--full` only. */\n  identityPreview?: { key: string; preview: string }[];\n  value: string;\n  currency: string;\n  /** The body as it arrived, with every sensitive value already replaced. `--full` only. */\n  payload?: string;\n};\n\nexport type IngestArrivalsData = {\n  arrivals: IngestArrivalRow[];\n  /** How many of the returned rows were refused, so a caller need not count them. */\n  rejected: number;\n  /** How many were rehearsals, which are accepted and deliberately write nothing. */\n  rehearsals: number;\n  hints: string[];\n};\n\n/** The envelope, as every `baker` command returns one. */\nexport type IngestArrivalsResponse = { ok: true; data: IngestArrivalsData };\n\n/**\n * What to say about a page of arrivals.\n *\n * Every one of these is a conclusion somebody would otherwise have to reach by\n * reading the rows and already knowing how the endpoint behaves — and the two\n * that matter most are the ones where the log looks *healthy*: an empty list\n * after a client swears they are posting, and a wall of accepted rehearsals\n * that were never going to appear in a report.\n */\nexport function arrivalHints(rows: readonly IngestArrivalRow[], asked: { mode?: string }): string[] {\n  const hints: string[] = [];\n  if (rows.length === 0) {\n    hints.push(\n      asked.mode\n        ? `Nothing arrived in the last 48 hours under mode=${asked.mode}. Drop --mode to see the other kind before concluding the integration is silent.`\n        : \"Nothing has arrived in the last 48 hours. The log only records requests that REACHED us, so an empty list means the key, the URL or the client's own dispatch — not the payload. `baker analytics sending-events` has the endpoint and a runnable request.\",\n    );\n    return hints;\n  }\n\n  const rejected = rows.filter((row) => row.outcome === \"rejected\");\n  // The single most useful thing this command can say: when every refusal\n  // shares a code, the fix is one fix, and naming it beats listing the rows.\n  const codes = new Set(rejected.map((row) => row.rejectCode).filter((code) => code !== \"\"));\n  if (rejected.length > 0 && codes.size === 1) {\n    const [code] = [...codes];\n    hints.push(\n      `All ${rejected.length} refused ${rejected.length === 1 ? \"request was\" : \"requests were\"} refused for the same reason (${code}) — one fix, not ${rejected.length}. The message on the row says what the field had to be.`,\n    );\n  } else if (rejected.length > 0) {\n    hints.push(`${rejected.length} of ${rows.length} were refused, for ${codes.size} different reasons.`);\n  }\n\n  // Gated on the ACCEPTED rows, not on the page. The confusion this exists to\n  // prevent is \"it was accepted and nothing appeared\" — on a page of refusals\n  // the reason nothing appeared is the refusal, and saying \"these deliberately\n  // write nothing\" there points away from the error that is right beside it.\n  // Found by running the command: a `--outcome rejected` page whose rows all\n  // happened to be rehearsals got this hint on top of its own codes.\n  const accepted = rows.filter((row) => row.outcome === \"accepted\");\n  if (accepted.length > 0 && accepted.every((row) => row.mode === \"test\")) {\n    hints.push(\n      \"Every request that was accepted here is a rehearsal (X-Baker-Mode: test). They are validated and answered exactly like live traffic and deliberately write nothing, so they will never appear in a report — which is the usual reason somebody thinks the endpoint is broken when it is working.\",\n    );\n  }\n\n  // An accepted event with no `event_id` is not a defect, and saying so once\n  // stops it being reported as one. Saying it when a retry has already happened\n  // would be noise, so it is only raised where the whole page is id-less.\n  if (accepted.length > 0 && accepted.every((row) => row.eventId === \"\")) {\n    hints.push(\n      \"None of the accepted requests carried an event_id, so every retry counts again. Send one per event if the client's system can retry — it is the only thing that makes a repeat collapse to one.\",\n    );\n  }\n  return hints;\n}\n","/**\n * Where the contract is served, and the request a client can paste.\n *\n * The host is a Baker one so that no client integration is ever written against\n * a `*.convex.site` deployment it would have to change when we move. It is a\n * Convex custom domain mapped straight onto the production deployment's HTTP\n * router — no proxy in between. If the backend ever moves, the domain\n * re-points then; the API key still resolves the Company.\n */\nimport { INGEST_MODE_HEADER } from \"./mode\";\n\nexport const EVENT_INGEST_PATH = \"/v1/events\";\n\n/**\n * The endpoint to show an integrator, given the branded host published for this\n * environment.\n *\n * Development has no branded host — the domain fronts one deployment — so it\n * falls back to the Convex site the dashboard already knows, and the guide\n * stays a request you can actually run. A guide whose curl 404s teaches a\n * client that the docs are wrong, which is more expensive than the ugly URL.\n */\nexport function eventIngestUrl(brandedUrl: string | undefined, convexSiteUrl: string): string {\n  if (brandedUrl) return `${brandedUrl.replace(/\\/$/, \"\")}${EVENT_INGEST_PATH}`;\n  return `${convexSiteUrl.replace(/\\/$/, \"\")}${EVENT_INGEST_PATH}`;\n}\n\n/**\n * A request that runs as written, with this company's own endpoint and key.\n *\n * Built here rather than in the dashboard component so the one thing an\n * integrator copies is covered by a test: a snippet with a stale field name is\n * indistinguishable from a broken endpoint from where they are standing.\n *\n * ## The rehearsal is a header, so there is one snippet and not two\n *\n * `X-Baker-Mode: test` validates and answers identically while writing no\n * analytics row. It is shown as a trailing hint beside the live request rather\n * than as a second snippet, because that is the actual shape of the decision:\n * the same integration, the same credential, one line different. A second\n * snippet would imply a second setup, which is what having a separate test\n * *key* used to imply and why it was wrong.\n *\n * ## What the example sends, and what it deliberately leaves out\n *\n * A `deal_won` with money on it and an email in `user_data` — the case this\n * door exists for, and the shortest body that exercises every part that can go\n * wrong. It carries neither an `event_id` nor an\n * `event_time`, and both absences are the point: they are optional, and an\n * example that pins an id would count once however many times it is pasted —\n * which is the deduplication working, and looks exactly like a broken key.\n */\nconst MODE_HINT = `\\n# Rehearse the same request: add -H '${INGEST_MODE_HEADER}: test'\\n# It is validated and answered exactly the same way, and nothing is written.`;\n\nexport function eventIngestCurl(url: string, apiKey: string): string {\n  const body = JSON.stringify({\n    events: [\n      {\n        event_name: \"deal_won\",\n        user_data: { email: \"person@example.com\" },\n        value: \"1200.00\",\n        currency: \"EUR\",\n      },\n    ],\n  });\n\n  return (\n    [\n      `curl -X POST ${url} \\\\`,\n      `  -H 'Authorization: Bearer ${apiKey}' \\\\`,\n      `  -H 'Content-Type: application/json' \\\\`,\n      `  -d '${body}'`,\n    ].join(\"\\n\") + MODE_HINT\n  );\n}\n\n/**\n * The same request against a source's address: no key, because the address\n * is the credential, and no mode header, because an address rehearses while\n * the source is waiting for its first send and counts once it is confirmed.\n */\nexport function eventSourceCurl(url: string): string {\n  const body = JSON.stringify({\n    events: [\n      {\n        event_name: \"deal_won\",\n        user_data: { email: \"person@example.com\" },\n        value: \"1200.00\",\n        currency: \"EUR\",\n      },\n    ],\n  });\n  return [`curl -X POST ${url} \\\\`, `  -H 'Content-Type: application/json' \\\\`, `  -d '${body}'`].join(\"\\n\");\n}\n","/**\n * The sending-events contract as data: the three tables the dialog draws, and\n * nothing about how they are drawn.\n *\n * Lifted out of the dialog when the same reference had to exist twice — once as\n * a table somebody reads, and once as Markdown somebody hands to a coding\n * assistant. Two hand-written copies of a contract is the failure this file\n * exists to prevent: the screen would go on being right while the copy an agent\n * actually writes code from quietly aged, and nothing would catch it, because\n * the wrong one is never rendered.\n *\n * ## Why it is in the contract package rather than beside the dialog\n *\n * There is a **third** reader, and it is the one that could not reach this at\n * all while it lived in `apps/dashboard`: the sandbox agent, through\n * `baker analytics sending-events`. That agent is who a client asks to wire\n * their CRM up, and until this moved its only options were to invent the\n * payload shape or to ask somebody to paste the dialog into chat. A contract\n * that only a browser can read is a contract the agent writing the integration\n * has never seen.\n *\n * Every bound and every code here is imported from its own module rather than\n * typed out, for the same reason one layer down. What is written out is the\n * prose, which no module can generate: what a field is *for*, and which of two\n * reasonable expectations is the wrong one.\n */\n\nimport { EVENT_ITEMS_MAX } from \"../analytics/row\";\nimport {\n  EVENT_INGEST_BATCH_MAX,\n  EVENT_INGEST_BODY_MAX_BYTES,\n  EVENT_INGEST_REQUESTS_PER_MINUTE,\n  FUTURE_TOLERANCE_MS,\n  MAX_EVENT_NAME,\n  MAX_ITEM_QUANTITY,\n  REJECTION_CODES,\n} from \"./validation\";\n\n/**\n * One row of the contract: the field, whether it is required, and what it takes.\n *\n * A table rather than prose because that is the shape of the question. Nobody\n * reads this top to bottom — they arrive knowing which field they are unsure\n * about and want the one line about it, and a paragraph makes them read six\n * lines to find out whether `value` may be a number.\n *\n * `note` is a plain string, deliberately: it is rendered on screen *and*\n * written into the Markdown brief, and the moment one of these holds JSX the\n * brief either loses it silently or has to reimplement it.\n */\nexport interface FieldSpec {\n  name: string;\n  need: \"required\" | \"optional\" | \"conditional\";\n  takes: string;\n  note?: string;\n  /** A field of the block above it, drawn inside its parent's row. */\n  under?: true;\n}\n\n/** How many megabytes a request may carry, for prose that has to say it. */\nexport const BODY_MAX_MB = EVENT_INGEST_BODY_MAX_BYTES / (1024 * 1024);\n\n/** How far into the future a timestamp may be before it is refused, in minutes. */\nexport const FUTURE_TOLERANCE_MINUTES = FUTURE_TOLERANCE_MS / 60_000;\n\nexport const HEADER_FIELDS: readonly FieldSpec[] = [\n  { name: \"Authorization\", need: \"required\", takes: \"Bearer <your sending key>\" },\n  { name: \"Content-Type\", need: \"required\", takes: \"application/json\" },\n  {\n    name: \"X-Baker-Mode\",\n    need: \"optional\",\n    takes: \"live (the default) or test.\",\n    // Deliberately says what a test send *is* rather than \"see step 4\". Every\n    // note here is read twice — on this screen, where the step below explains\n    // it in full, and inside the Markdown brief, where there are no steps and\n    // a cross-reference points at nothing.\n    note: \"A test send is authenticated and validated identically and stores nothing. An unrecognised value is refused rather than assumed.\",\n  },\n];\n\n/**\n * The event body, field by field — with `user_data` opened out in place.\n *\n * It used to be one row saying \"who it was about — see the identity fields\n * below\", and a second table further down. Nobody reading a contract wants to\n * be told where the rest of it is: the question \"what can I put in here\" was\n * asked *at* that row, and the answer was a scroll away under a heading whose\n * name (`identity`) did not appear in the payload at all.\n *\n * Two fields deserve calling out, because both are places a reasonable person\n * expects the opposite:\n *\n * - `event_id` is **optional**, and only ever means \"deduplicate me\".\n * - `event_time` is optional too, and defaults to the moment the request\n *   arrived — which is right for a webhook and wrong for a backfill.\n */\nexport const EVENT_FIELDS: readonly FieldSpec[] = [\n  {\n    name: \"event_name\",\n    need: \"required\",\n    takes: `What happened. Up to ${MAX_EVENT_NAME} characters of letters, digits, spaces, . _ and -, starting with a letter or a digit`,\n    note: 'The only required field. Use one of the standard names below wherever one fits — anything else is yours to invent, in whatever language you name things in: a letter is a letter in any script, and \"Matrícula Realizada\" is a name.',\n  },\n  {\n    name: \"event_time\",\n    need: \"optional\",\n    takes: \"ISO-8601 with an offset (2026-09-08T13:23:41Z), or Unix seconds (1757337821).\",\n    note: `Left out, it is the moment we received it. Nothing is refused for being old — a backfill of last year's history is what this is for. More than ${FUTURE_TOLERANCE_MINUTES} minutes in the future is refused.`,\n  },\n  {\n    name: \"event_id\",\n    need: \"optional\",\n    takes: \"Your own id for this event: 1–128 characters of letters, digits, and . _ : -\",\n    note: \"Send one only if you want it deduplicated — the same id twice is counted once. Send none and every post is its own event.\",\n  },\n  {\n    name: \"user_data\",\n    need: \"required\",\n    takes:\n      \"Who it was about. At least one field below — this is the whole of how a server event finds the person who visited a Baker page or your website.\",\n    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.\",\n  },\n  {\n    name: \"email\",\n    need: \"optional\",\n    under: true,\n    takes: \"The address, or its SHA-256 digest if you already hash. Either — we tell them apart.\",\n    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.\",\n  },\n  {\n    name: \"phone\",\n    need: \"optional\",\n    under: true,\n    takes: \"The number with its country code, or its digest. Same treatment as email.\",\n  },\n  {\n    name: \"external_id\",\n    need: \"optional\",\n    under: true,\n    takes: \"Your own id for the person — a CRM contact key.\",\n    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.\",\n  },\n  {\n    name: \"baker_id\",\n    need: \"optional\",\n    under: true,\n    takes: \"The Baker ID one of our pages already gave this browser, if you kept it.\",\n    note: \"The strongest of all of them: it names the visit, so the event lands on that person's timeline rather than beside it.\",\n  },\n  {\n    name: \"the ad click ids\",\n    need: \"optional\",\n    under: true,\n    takes:\n      \"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).\",\n    note: \"A click id names a person too — it is enough on its own, and it attributes the event to the campaign that earned it.\",\n  },\n  {\n    name: \"fbp, fbc\",\n    need: \"optional\",\n    under: true,\n    takes: \"Meta's own browser cookies (_fbp, _fbc), exactly as your site stored them.\",\n    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.\",\n  },\n  {\n    name: \"the matching fields\",\n    need: \"optional\",\n    under: true,\n    takes:\n      \"first_name, last_name, date_of_birth, gender, city, region, postal_code, country — Meta's advanced matching and Google's enhanced conversions, in one block. Plain or already hashed.\",\n    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.\",\n  },\n  {\n    name: \"url\",\n    need: \"optional\",\n    takes: \"The full page URL this happened on.\",\n    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.\",\n  },\n  {\n    name: \"value\",\n    need: \"optional\",\n    takes: \"What it was worth: a decimal string or a JSON number. No thousands separator, no sign, no exponent.\",\n    note: 'Rounded to what the currency holds — 1200.999 EUR is stored as 1201.00. \"1,200\" is refused.',\n  },\n  {\n    name: \"currency\",\n    need: \"conditional\",\n    takes: \"An ISO-4217 code, e.g. EUR. Required whenever value is present, and refused on its own.\",\n  },\n  {\n    name: \"properties\",\n    need: \"optional\",\n    takes: \"A flat object of strings — anything you want to break the event down by later.\",\n  },\n  {\n    name: \"items\",\n    need: \"optional\",\n    takes: \"What was bought, one entry per product line — for a purchase, a cart or a refund.\",\n    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}.`,\n  },\n  {\n    name: \"product_id, variant_id, feed_id\",\n    need: \"conditional\",\n    under: true,\n    takes:\n      \"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.\",\n  },\n  {\n    name: \"quantity\",\n    need: \"optional\",\n    under: true,\n    takes: `How many: a whole number from 1 to ${MAX_ITEM_QUANTITY.toLocaleString(\"en-US\")}.`,\n  },\n  {\n    name: \"price\",\n    need: \"optional\",\n    under: true,\n    takes: \"The price of one unit, in the event's currency — so it needs currency. A decimal like value.\",\n  },\n  {\n    name: \"consent\",\n    need: \"optional\",\n    takes: \"What the person allowed, if your site asked them.\",\n    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.\",\n  },\n  {\n    name: \"analytics\",\n    need: \"optional\",\n    under: true,\n    takes: \"granted or denied — whether they allowed being measured. Denied keeps the event and forgets who it was.\",\n  },\n  {\n    name: \"marketing\",\n    need: \"optional\",\n    under: true,\n    takes: \"granted or denied — whether they allowed their visit to be used for advertising.\",\n  },\n];\n\nexport const RESPONSE_FIELDS: readonly FieldSpec[] = [\n  {\n    name: \"mode\",\n    need: \"required\",\n    takes:\n      \"live or test, echoed back — so a forgotten header is visible in the reply rather than in a report next week.\",\n  },\n  { name: \"received\", need: \"required\", takes: \"How many events we read, so you can detect a truncated body.\" },\n  { name: \"accepted\", need: \"required\", takes: \"How many were counted.\" },\n  {\n    name: \"rejected\",\n    need: \"required\",\n    takes: \"One entry per refused event: index, event_id, code, message.\",\n    note: \"index is the position in your own array, and is the one to branch on — event_id is empty for an event that sent none.\",\n  },\n];\n\n/** The closed set a client branches on, straight from the module that closes it. */\nexport const REJECTION_CODE_LIST: readonly string[] = REJECTION_CODES;\n\n/** The batch bounds, in one place so prose and Markdown quote the same numbers. */\nexport const BATCH_LIMITS = {\n  events: EVENT_INGEST_BATCH_MAX,\n  megabytes: BODY_MAX_MB,\n  requestsPerMinute: EVENT_INGEST_REQUESTS_PER_MINUTE,\n} as const;\n","/**\n * The whole sending-events reference, as Markdown for a coding assistant.\n *\n * ## Why a brief and not \"copy the page\"\n *\n * The dialog beside this is written for a person deciding whether to build the\n * integration: it is staged, it explains itself, and half of it is reassurance.\n * An assistant that has already been told to build it needs the opposite —\n * every bound, every code and every rule in one pass, with the mistakes called\n * out *before* it makes them rather than explained afterwards. So this is the\n * same contract in the shape the second reader needs, built from the same\n * `./ingestContract` tables the screen draws, so neither can quietly age.\n *\n * ## The key is not in here, and that is the feature\n *\n * Everything else on the dialog can be copied whole. This one thing cannot: the\n * destination of a \"copy for AI\" button is a chat window, and a chat window is\n * a third party's log. So the brief carries `<your sending key>` and, more\n * usefully, *tells the assistant what to do instead* — read it from an\n * environment variable, and ask the person for the value. An agent given a\n * placeholder with no instruction invents `const KEY = \"...\"` and puts it in\n * source; an agent told where the value belongs writes the right thing without\n * ever seeing it.\n *\n * ## What the instruction block is for\n *\n * Nine tenths of a wrong integration against this endpoint is one of six\n * mistakes, and every one of them produces a `200`: not reading `rejected[]`,\n * one request per event, a negative amount for a refund, a key in source, a\n * test header left on, and treating a repeated `event_id` as an error. None of\n * those is discoverable from a field table — they are all things the reader has\n * to be told before they start — which is why the document opens with them\n * instead of ending with them.\n */\n\nimport { eventIngestCurl, eventSourceCurl } from \"./endpoint\";\nimport {\n  BATCH_LIMITS,\n  EVENT_FIELDS,\n  type FieldSpec,\n  HEADER_FIELDS,\n  REJECTION_CODE_LIST,\n  RESPONSE_FIELDS,\n} from \"./fields\";\nimport { MATCH_FIELD_FORWARDING } from \"./matching\";\nimport { STANDARD_EVENT_NAMES } from \"./names\";\n\n/** The env var the brief tells an assistant to read the key from. */\nconst KEY_ENV_VAR = \"BAKER_EVENTS_KEY\";\n\n/** The placeholder that stands where the key would be. Never the key itself. */\nconst KEY_PLACEHOLDER = \"<your sending key>\";\n\nconst NEED_WORD: Readonly<Record<FieldSpec[\"need\"], string>> = {\n  required: \"required\",\n  optional: \"optional\",\n  conditional: \"conditional\",\n};\n\n/**\n * Markdown-safe text for a table cell.\n *\n * Two things a contract written for humans puts in prose and a Markdown table\n * cannot hold literally: a `<placeholder>`, which a renderer reads as a tag and\n * swallows — losing exactly the words telling somebody what to substitute — and\n * a `|`, which ends the cell.\n */\nfunction cell(text: string): string {\n  return text.replaceAll(\"<\", \"\\\\<\").replaceAll(\"|\", \"\\\\|\");\n}\n\n/**\n * One field table, as Markdown.\n *\n * The note is separated with a `<br>` rather than a space, because a `takes`\n * that ends in `and -` running straight into `The only required field` reads as\n * one broken sentence. Nested fields keep their indent as a prefix on the name,\n * since Markdown has no nested table and the relationship is the load-bearing\n * part of `user_data`.\n */\nfunction table(fields: readonly FieldSpec[]): string {\n  const rows = fields.map((field) => {\n    const name = field.under === true ? `↳ \\`${field.name}\\`` : `\\`${field.name}\\``;\n    const note = field.note === undefined ? \"\" : `<br>${cell(field.note)}`;\n    return `| ${name} | ${NEED_WORD[field.need]} | ${cell(field.takes)}${note} |`;\n  });\n  return [\"| Field | | What it takes |\", \"| --- | --- | --- |\", ...rows].join(\"\\n\");\n}\n\nfunction standardNames(): string {\n  return [\n    \"| Name | Means |\",\n    \"| --- | --- |\",\n    ...STANDARD_EVENT_NAMES.map((standard) => `| \\`${standard.name}\\` | ${standard.means} |`),\n  ].join(\"\\n\");\n}\n\n/**\n * Where each field of the matching block goes at each destination.\n *\n * Published here as well as on the screen because it is the answer to the\n * question an assistant asks second — \"why would I send a postcode to an\n * analytics endpoint\" — and the answer is that this event can be forwarded to\n * Meta or Google later without going back to the client's CRM for it.\n */\nfunction forwarding(): string {\n  return [\n    \"| Field | Meta | Google | Held as |\",\n    \"| --- | --- | --- | --- |\",\n    ...MATCH_FIELD_FORWARDING.map(\n      (row) =>\n        `| \\`${row.field}\\` | \\`${row.meta}\\` | ${row.google === null ? \"—\" : `\\`${row.google}\\``} | ${row.hashed ? \"SHA-256\" : \"plain text\"} |`,\n    ),\n  ].join(\"\\n\");\n}\n\n/**\n * The whole reference, for one company's endpoint.\n *\n * `endpointUrl` is this company's own, so the document an assistant receives\n * needs no substitution and cannot be pointed at the wrong deployment by\n * somebody copying an example out of a doc site.\n */\nexport function ingestBrief(endpointUrl: string): string {\n  return brief(endpointUrl, \"key\");\n}\n\n/**\n * The same contract for a source's address — the door a company's own\n * developers get from Measure → Sources. The address is the credential, so\n * there is no key and no `Authorization` header; and a source rehearses\n * while it is waiting for its first send and counts once confirmed, so the\n * mode header is not read. Everything about the event is identical.\n */\nexport function sourceBrief(addressUrl: string): string {\n  return brief(addressUrl, \"address\");\n}\n\ntype Door = \"key\" | \"address\";\n\nfunction keyRules(door: Door): string {\n  if (door === \"address\") {\n    return `1. **The address is the credential. Never put it in source, and never paste it into a chat.**\n   Read it from \\`BAKER_EVENTS_URL\\` and ask the person for the value — they can copy it\n   from Baker → Measure → Sources, on the source's own page.\n2. **The first send is a rehearsal.** While the source reads \"Waiting for your first event\"\n   in Baker, every request is parsed, validated and answered exactly as a live one and\n   **stores nothing**; the person then confirms what to read from it and it counts from\n   there. Nothing about the integration changes when it does.`;\n  }\n  return `1. **Never put the sending key in source, and never paste it into a chat.** It is\n   deliberately not in this document. Read it from \\`${KEY_ENV_VAR}\\` and ask the person\n   for the value — they can copy it from Baker → Measure → Events → Sending events.\n2. **Send \\`X-Baker-Mode: test\\` while you build.** A test request is authenticated,\n   parsed and validated in exactly the same way and answers in exactly the same shape,\n   and **stores nothing**. Remove the header to go live. There is no separate test key\n   and no separate endpoint, so nothing about the integration changes when it does.`;\n}\n\nfunction brief(endpointUrl: string, door: Door): string {\n  const { events, megabytes, requestsPerMinute } = BATCH_LIMITS;\n  const headers = door === \"address\" ? HEADER_FIELDS.filter((field) => field.name === \"Content-Type\") : HEADER_FIELDS;\n  const credentialRow =\n    door === \"address\"\n      ? \"| `404` | Nothing is listening at this address: it is wrong, or the source was removed. | Fix the address. Do not retry. |\"\n      : \"| `401` | The key is missing, wrong, or not a sending key. | Fix the credential. Do not retry. |\";\n  const request = door === \"address\" ? eventSourceCurl(endpointUrl) : eventIngestCurl(endpointUrl, KEY_PLACEHOLDER);\n  return `# Send events to Baker's API from your server\n\nYou are being handed this by somebody who wants an integration built against it. It is\nthe complete contract for ${door === \"address\" ? \"a Baker source's address\" : \"`POST /v1/events`\"} on **their own Baker endpoint**, taken from\nthe code that enforces it. Build from this document; you should not need to look\nanything else up.\n\nBaker measures what happens on the pages it publishes. This endpoint is how everything\nthat happens *away* from those pages — a deal closing in a CRM, a subscription starting,\nan order shipping — reaches the same reports, joined to the same person.\n\n## Read this before you write anything\n\n${keyRules(door)}\n3. **A \\`200\\` does not mean it counted.** The body carries \\`rejected[]\\`, one entry per\n   refused event. Read it and log it on every response. Throwing it away is the single\n   most common way an integration against this endpoint is wrong and looks right.\n4. **Batch.** Up to ${events} events and ${megabytes} MB per request, and at most\n   ${requestsPerMinute} requests per minute for the whole company. One event per request\n   works and will exhaust that budget on any real backfill. Every event is judged on its\n   own, so one bad row is refused and the rest of the batch still counts.\n5. **Retry \\`5xx\\` and \\`429\\`, never \\`4xx\\`.** A \\`4xx\\` means the request is wrong and\n   will be wrong again. If you retry, send the same \\`event_id\\` — that is what makes the\n   retry count once.\n6. **A refund is its own event, not a negative amount.** \\`value\\` may not be negative.\n   Send an event with its own name and let the reports subtract.\n7. **You cannot declare a conversion.** Whether an event counts as one is a decision the\n   client makes in Baker, against the event's name, and it applies retroactively to\n   everything already sent under that name. Nothing in the payload can assert it.\n8. **Ask, do not guess.** Which events matter and where the person's email lives in their\n   system are things this document cannot tell you. Ask.\n\n## Endpoint\n\n\\`\\`\\`\nPOST ${endpointUrl}\n\\`\\`\\`\n\n### Headers\n\n${table(headers)}\n\n### Body\n\n\\`\\`\\`json\n{ \"events\": [ { \"event_name\": \"...\" } ] }\n\\`\\`\\`\n\nUp to ${events} events and ${megabytes} MB per request.\n\n## The event\n\nThe field names are Meta's. If you have written an integration against Meta's Conversions\nAPI or Google Ads' offline conversion upload, this is the same payload: \\`event_name\\`,\n\\`event_time\\`, \\`event_id\\`, \\`user_data\\`, \\`value\\`, \\`currency\\`.\n\n${table(EVENT_FIELDS)}\n\n### Naming the person is the part that matters\n\n\\`user_data\\` is required and every field in it is optional, which is not a contradiction:\nthe event has to name **somebody**, and there are several ways to do it. An event that\nnames nobody is refused with \\`missing_identity\\`.\n\nRanked by how well each works, best first:\n\n1. \\`baker_id\\` — the id a Baker page already gave that browser. It names the *visit*, so\n   the event lands on a real session's timeline. Send it if the client's system kept it.\n2. \\`email\\` or \\`phone\\` — the road that cannot silently fail. Send the plain value if you\n   can: we normalise and hash it here under the same rule the browser uses, so it lands\n   on exactly the person the pages already recorded. If policy forbids sending it plain,\n   send the SHA-256 digest **in the same field** — we detect which it is. Hash the\n   trimmed, lower-cased address; for a phone, digits with a leading \\`+\\`.\n3. \\`external_id\\` — the client's own key for the person, a CRM contact id. Stored as sent,\n   and hashed alongside so it joins.\n   On its own it joins that system's events to each other; send it **once** alongside an\n   email or a \\`baker_id\\` and every later event carrying only the contact id joins the\n   person too. That link is retroactive: it reaches back to everything already sent.\n4. A click id, \\`fbp\\` or \\`fbc\\` — names the click or the browser that brought them, which\n   is what a report attributes the event to.\n\nSend every one you have, not just the best. They cost nothing extra and each is a\nseparate chance to match.\n\n### The matching fields, and where they go afterwards\n\n\\`first_name\\` … \\`country\\` never satisfy \\`user_data\\` on their own — they describe a\nperson and name nobody. They are worth sending anyway: they are exactly what Meta's\nadvanced matching and Google's enhanced conversions match on, and keeping them means the\nevent can be forwarded later without going back to the client's CRM for it.\n\n${forwarding()}\n\n## Standard event names\n\nNothing is refused for being absent from this list — send whatever the business calls a\nthing. These are the spellings Baker publishes so that two companies measuring the same\nthing measure it under the same word. \\`page_view\\` is the one with behaviour: it becomes\na page view rather than a named event, and it is the only event that may arrive without a\nperson as long as it carries a \\`url\\`.\n\n${standardNames()}\n\n## The response\n\n\\`\\`\\`json\n{ \"ok\": true, \"data\": { \"mode\": \"live\", \"received\": 2, \"accepted\": 1,\n  \"rejected\": [ { \"index\": 1, \"event_id\": \"\", \"code\": \"invalid_value\",\n    \"message\": \"value and currency go together: a non-negative decimal and an ISO-4217 code\" } ] } }\n\\`\\`\\`\n\n${table(RESPONSE_FIELDS)}\n\n\\`code\\` is a closed set — branch on it, not on \\`message\\`:\n\n${REJECTION_CODE_LIST.map((code) => `- \\`${code}\\``).join(\"\\n\")}\n\nThere is no duplicate count, on purpose. A repeated \\`event_id\\` is accepted like any other\nevent and counted **once** — one conversion, one event, its value added once — so a retry\nis safe and needs no branch of its own. Both requests are shown in Baker, with the later\none marked \"Already counted\", so a retry is visible without being counted.\n\nThe same holds **across connections**, which is the reason to use it. If the page also\nreports this outcome with Baker's website tag, pass one string as \\`event_id\\` here and as\n\\`eventId\\` in \\`window.baker.track(name, { eventId })\\`: the browser event and the\nserver event are then one event and count once, whichever arrives first and whether or not\nthe other ever does. Report an important outcome from both — a browser can be blocked, a\nserver cannot — and always pair them with an id. Send no id and the two are two conversions,\nwith nothing anywhere reporting an error.\n\n### HTTP statuses\n\n| Status | Means | Do |\n| --- | --- | --- |\n| \\`200\\` | The request was read. Individual events may still have been refused. | Read \\`rejected[]\\`. |\n| \\`400\\` | The body is not the shape above — an unknown field, or the wrong JSON type. | Fix the payload. Do not retry. |\n${credentialRow}\n| \\`413\\` | Over ${events} events or ${megabytes} MB. | Split the batch and re-post. |\n| \\`429\\` | Over ${requestsPerMinute} requests a minute for this company. | Back off and retry. |\n| \\`5xx\\` | Nothing was written. | Retry with the same \\`event_id\\`s. |\n\n## A request that works\n\n\\`\\`\\`bash\n${request}\n\\`\\`\\`\n\n## Once it is sending\n\nEvery accepted event appears in Baker under **Measure → Events**, live, with what was\nsent. Test sends and refusals appear there too, filed separately and marked, with the\npayload — so \"did my request arrive and what did it say\" is answered on the screen rather\nthan in the client's own logs. To make an event count as a conversion, the client marks\nit by name under **Conversions**.\n`;\n}\n"],"mappings":"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","names":[]}