Events

Every request the gateway handles — including pass-throughs — emits exactly one RebilderEventV0 when onEvent is configured: requester from detection, request (url, accept, referrer), and response.path with measured render_ms. Emission is fire-and-forget: never awaited, sync throws and async rejections are swallowed; a broken or slow event sink can neither block nor break a response.

The schema is frozen at v0 and additive-only: new fields extend a version or start a new one, and a v0 consumer must accept events produced by a later additive revision (unknown extra keys are allowed at every level). This feed is what the Console renders — agent visits by platform, what they saw, how fast.

Events record visits; orders arrive separately and are joined at read time with labeled evidence — the contract for reporting them (the POST /v1/outcomes API and the Shopify orders webhook) lives on the Outcomes page.

Any conforming ingest implementation must accept exactly this:

POST {url}/v1/events
Authorization: Bearer <apiKey>
Content-Type: application/json

{ "events": RebilderEventV0[] }

• Success: 202 Accepted with body { "accepted": <n> } — the client treats any 2xx as accepted and does not parse the body.
• event_id is the idempotency key through the queue: the client retries a batch at most once, so the ingest side deduplicates on event_id.
• 5xx / network error: the client retries the identical batch once after 500ms, then drops it.
• 4xx: the client drops the batch immediately without retrying.

The hosted ingest API (https://api.rebilder.com) additionally responds 401 for an unknown, revoked, or missing API key; 400 for a malformed body (not an array, more than 500 events per request, or structural failure); and 503 when events ingest is not configured on that deployment. Keys are store-scoped: the resolved store_id always overrides any store_id in the payload, so a key can never write another store’s events.

import { createHttpEventSink } from '@rebilder/events'

const sink = createHttpEventSink({
  url: 'https://api.rebilder.com', // ingest base — the sink POSTs to `${url}/v1/events`
  apiKey: process.env.REBILDER_API_KEY!, // sent as `Authorization: Bearer <apiKey>`
  // maxBatch: 20,          — flush as soon as the queue reaches this many events
  // flushIntervalMs: 2000, — flush timer while the queue is non-empty
  // fetchImpl: fetch,      — injectable for tests; defaults to globalThis.fetch
  // onError: console.warn, — called for every dropped event/batch; never rethrown
})

sink.emit(event) // sync enqueue; invalid events dropped via onError, never thrown
await sink.flush() // send the queue now; resolves even on failure
await sink.close() // flush remaining events + stop the timer; later emits are dropped

Delivery semantics — observation must never break serving. emit() never throws, flush()/close() never reject; failures are reported through onError and the batch is dropped. The queue is capped at 1000 events — beyond that the oldest event is dropped via onError. emit() after close() drops the event.

import { createConsoleEventSink } from '@rebilder/events'

const sink = createConsoleEventSink()
sink.emit(event) // console.info('[rebilder-event] {"event_id":...}')

One structured [rebilder-event] {json} line per event via console.info — useful before you have an API key (a log drain captures them). Upgrade path: swap createConsoleEventSink() for createHttpEventSink({...}) once you have ingest credentials; the event shape is already the v0 contract, so nothing else changes.

API keys are store-scoped and issued in the Console: create an account, add your store, and the onboarding flow issues a key (shown once — store it in your secret manager). Rotate or revoke any time in Console → Settings; a rotated key’s predecessor starts returning 401 immediately. The Help Center has a step-by-step walkthrough with screenshots.