@koda-sl/baker-cli 0.457.0 → 0.458.0

package/dist/chunk-EFM7OODQ.js

@@ -1,433 +0,0 @@
-import {
-  INGEST_MODES,
-  INGEST_MODE_HEADER
-} from "./chunk-GRQ2AXDX.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,
-  REJECTION_CODES,
-  STANDARD_EVENT_NAMES
-} from "./chunk-45OQOUJA.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."
-  }
-];
-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-EFM7OODQ.js.map

package/dist/chunk-EFSYTROP.js

@@ -1,94 +0,0 @@
-import {
-  ApiError
-} from "./chunk-XBOK23HI.js";
-import {
-  writeJson
-} from "./chunk-NU7JSWVA.js";
-
-// src/commands/landing/inspiration/shared.ts
-var INSPIRATION_HINTS = {
-  adapt: "Reference only. Re-express this in the client's BRAND.md palette, type and imagery register. Reusing a headline, subhead or CTA verbatim is a Tier 0 message-match failure (references/gotchas.md).",
-  structureNotCopy: "Take the structural decision, not the furniture: what the eye hits first, the grid ratio, what was deliberately left out. Your copy must come from the client's own offer."
-};
-function favoritesScopeHints(health, resultCount) {
-  if (!health) return [];
-  const hints = [];
-  if (health.savedPages === 0) {
-    hints.push(
-      "This company hasn't saved any reference pages yet, so there is no taste profile to search \u2014 an empty result here says nothing about the library. Search the whole shared library with --scope all, or save a page the client admires with `baker landing inspiration add <url>`."
-    );
-    return hints;
-  }
-  if (health.failedPages > 0) {
-    const retryable = health.failedExamples.filter((example) => example.retryable).map((example) => example.url);
-    const permanent = health.failedExamples.filter((example) => !example.retryable).map((example) => example.url);
-    hints.push(
-      `${health.failedPages} of this company's ${health.savedPages} saved pages could not be read, so they hold no sections \u2014 only ${health.usablePages} are usable, which is why this result is thin. Search the whole library with --scope all.`
-    );
-    if (retryable.length > 0) {
-      hints.push(
-        `Worth another go: ${retryable.join(", ")} \u2014 run \`baker landing inspiration add <url>\` on one of them to study it again.`
-      );
-    }
-    if (permanent.length > 0) {
-      hints.push(`Not worth retrying \u2014 these sites refuse automated readers: ${permanent.join(", ")}.`);
-    }
-  }
-  if (health.studyingPages > 0) {
-    hints.push(
-      `${health.studyingPages} saved ${health.studyingPages === 1 ? "page is" : "pages are"} still being studied and will be searchable in a few minutes. Carry on; do not wait on them.`
-    );
-  }
-  if (resultCount === 0 && health.failedPages === 0 && health.studyingPages === 0) {
-    hints.push(
-      `Nothing in this company's ${health.usablePages} readable saved pages matches. The saved set is healthy, so this is the query, not the library \u2014 loosen the filters or search everything with --scope all.`
-    );
-  }
-  return hints;
-}
-function fidelityHint(fidelity) {
-  if (fidelity == null) return null;
-  if (fidelity >= 0.9) return null;
-  if (fidelity >= 0.75) {
-    return `Reproduction fidelity ${fidelity.toFixed(2)} \u2014 the markup is close but not exact. Trust the screenshot over the code.`;
-  }
-  return `Reproduction fidelity ${fidelity.toFixed(2)} \u2014 this section is scroll- or JS-driven and the extracted markup does NOT render like the original. Use the screenshot and the notes; treat the code as a hint only.`;
-}
-var STALE_COPY_AFTER_MS = 30 * 24 * 60 * 60 * 1e3;
-function staleCopyHint(studiedAt, filedUrl, now = Date.now()) {
-  if (!studiedAt || now - studiedAt < STALE_COPY_AFTER_MS) return null;
-  const date = new Date(studiedAt).toLocaleDateString("en-US", { month: "short", day: "numeric", timeZone: "UTC" });
-  return `This copy of the page was read on ${date}. If the user says the live page looks different, run: baker landing inspiration add ${filedUrl} --refresh`;
-}
-function reportError(error) {
-  if (error instanceof ApiError) {
-    writeJson({ ok: false, error: { code: error.code, message: error.message } });
-  } else {
-    writeJson({
-      ok: false,
-      error: { code: "UNKNOWN", message: error instanceof Error ? error.message : String(error) }
-    });
-  }
-  process.exit(1);
-}
-function splitList(value) {
-  if (!value) return void 0;
-  const parts = value.split(",").map((part) => part.trim()).filter(Boolean);
-  return parts.length > 0 ? parts : void 0;
-}
-function parseNumber(value) {
-  if (value === void 0 || value === "") return void 0;
-  const parsed = Number(value);
-  return Number.isFinite(parsed) ? parsed : void 0;
-}
-
-export {
-  INSPIRATION_HINTS,
-  favoritesScopeHints,
-  fidelityHint,
-  staleCopyHint,
-  reportError,
-  splitList,
-  parseNumber
-};
-//# sourceMappingURL=chunk-EFSYTROP.js.map