# [API reference](https://rebilder.com/docs/reference)

> Every public export of `@rebilder/gateway` (root + `/next`, `/shopify`, `/node`, `/edge` subpaths), `@rebilder/events`, and `@rebilder/protocols`, with signatures.

- **Updated:** 2026-08-15
- **Publisher:** Rebilder

## @rebilder/gateway

The framework-agnostic core, over web-standard `Request`/`Response`. Public API from the root export only; adapters are the subpath exports below.

| Export | Signature | Notes |
| --- | --- | --- |
| `classifyRequest` | `(req: Request) => GatewayDecision` | Pure compute, <1ms, no I/O. Returns `{ path, detection }`: the serving path plus the full detection result. |
| `handleRequest` | `(req: Request, config: GatewayConfig) => Promise<Response | null>` | `Response` = markdown served (`text/markdown; charset=utf-8`, `Vary: Accept`, `X-Rebilder-Path: markdown`); `null` = serve your normal HTML. |
| `generateLlmsTxt` | `(config: GatewayConfig, options: LlmsTxtOptions) => Promise<string>` | Deterministic llms.txt; see [llms.txt](/docs/llms-txt). |
| `GatewayConfig` | `{ storeId: string; sources: GatewaySources; onEvent?: (event: RebilderEventV0) => void | Promise<void>; maxBytes?: number; protocols?: (req: Request) => Promise<Response | null>; verification?: GatewayVerification }` | The one config object, shared by every adapter. `protocols` is the UCP/ACP/MCP hook, `verification` the Web Bot Auth registry; see [Protocols](/docs/protocols). |
| `GatewayVerification` | `{ keys: AgentKeyRegistry; require?: 'protocol' }` | Injected key registry for Web Bot Auth verification on the protocol path. The shipped directory is empty; the operator populates keys. |
| `verifyWebBotAuth` | `(input, options: { keys: AgentKeyRegistry; now?: Date }) => Promise<VerificationResult>` | Re-exported from detection: pure Ed25519 (RFC 9421) over injected keys, with no network, and it never throws. |
| `KNOWN_AGENT_DIRECTORY` | `AgentKeyRegistry` | The built-in registry, which **ships empty by design** (no invented production keys). |
| `AGENT_VERIFIED_HEADER` / `AGENT_VERIFIED_REASON_HEADER` | `'x-rebilder-agent-verified'` / `'x-rebilder-agent-verified-reason'` | The verdict headers the gateway stamps for the protocols hook (client-sent values always overwritten). |
| `GatewaySources` | `{ product?; policies?; catalog? }` | Each a `SourceResolver`; see [Sources](/docs/sources). |
| `SourceResolver<T>` | `(url: URL) => T | null | undefined | Promise<T | null | undefined>` | Sync or async; no slow I/O on the hot path. |
| `GatewayPath` | `'markdown' | 'protocol' | 'html'` | The serving-path union. |
| `GatewayDecision` | `{ path: GatewayPath; detection: DetectionResult }` | What `classifyRequest` returns. |
| `LlmsTxtOptions` / `LlmsTxtSection` / `LlmsTxtLink` | `{ baseUrl; siteName; description; sections? }` / `{ title; links }` / `{ title; url; note? }` | llms.txt inputs. |

**Re-exported dependency types** (so you only install `@rebilder/gateway`): `ProductSource`, `ProductVariantSource`, `ShippingSource`, `ReturnsSource`, `PolicySource`, `CatalogItemSource`, `Money`, `Availability` (from the renderer) plus `DetectionResult`, `RequesterKind`, `AgentPlatform`, `AgentKeyRegistry`, `AgentKeyRegistryEntry`, `AgentPublicKey`, `Ed25519PublicJwk`, `VerificationResult`, `VerificationFailureReason` (from detection) and `RebilderEventV0` (from events).

## @rebilder/gateway/next

| Export | Signature | Notes |
| --- | --- | --- |
| `createGatewayProxy` | `(config: GatewayConfig) => (req: Request) => Promise<Response | null>` | The middleware/proxy entry point; return `result ?? NextResponse.next()`. |
| `createGatewayRouteHandler` | `(config: GatewayConfig, options?: GatewayRouteHandlerOptions) => (req: Request) => Promise<Response>` | Always-markdown GET route. Source match → 200 markdown + event; no match → 404 `{ "error": "not_found" }`, no event. |
| `GatewayRouteHandlerOptions` | `{ stripPrefix?: string }` | Prefix stripped (whole path segments only) before consulting sources. Default: strip nothing. |
| `createLlmsTxtRouteHandler` | `(config: GatewayConfig, options: LlmsTxtOptions) => (req: Request) => Promise<Response>` | `text/plain; charset=utf-8` with `public, max-age=300, s-maxage=3600, stale-while-revalidate=86400`. |

## @rebilder/gateway/shopify

| Export | Signature | Notes |
| --- | --- | --- |
| `createShopifyAppProxyHandler` | `(config: GatewayConfig, options: ShopifyAppProxyOptions) => (req: Request) => Promise<Response>` | Signature-verified app-proxy endpoint; see [Shopify adapter](/docs/adapters/shopify) for the 401/404 semantics. |
| `ShopifyAppProxyOptions` | `{ sharedSecret: string; pathPrefix?: string }` | `pathPrefix` default `'/apps/rebilder'`; strip is a no-op if the path arrives canonical. |
| `verifyAppProxySignature` | `(url: URL, sharedSecret: string) => Promise<boolean>` | The HMAC check alone, exported for reuse. Web Crypto, constant-time comparison. |

## @rebilder/gateway/node

| Export | Signature | Notes |
| --- | --- | --- |
| `createGatewayMiddleware` | `(config: GatewayConfig) => NodeGatewayMiddleware` | Connect-style `(req, res, next) => void` for Express/Fastify; see [Node adapter](/docs/adapters/node). |
| `toWebRequest` | `(nodeReq: NodeRequestLike, options?: ToWebRequestOptions) => Request` | Builds the web-standard Request the middleware uses; exported for custom servers. |
| `NodeRequestLike` / `NodeResponseLike` | structural interfaces | Only what the adapter reads/writes; any real Node req/res satisfies them. |
| `NodeGatewayMiddleware` / `NodeNextFunction` | `(req, res, next) => void` / `() => void` | The middleware and continuation shapes. |
| `ToWebRequestOptions` | `{ fallbackHost?: string }` | Host used when no Host header is present. Default `'localhost'`. |

## @rebilder/gateway/edge

| Export | Signature | Notes |
| --- | --- | --- |
| `createGatewayFetchHandler` | `(config: GatewayConfig, options?: GatewayFetchHandlerOptions) => (req: Request) => Promise<Response>` | A complete fetch handler; see [Cloudflare & edge](/docs/adapters/cloudflare). |
| `GatewayFetchHandlerOptions` | `{ fallback?: (req: Request) => Response | Promise<Response> }` | Serves every non-markdown request. Default: `fetch(req)`, the origin pass-through. |

## @rebilder/events

The observation-layer contract: the frozen v0 schema, structural runtime validation, and the emission sinks. Zero runtime dependencies; edge-safe (web-standard `fetch`/`setTimeout` only).

| Export | Signature | Notes |
| --- | --- | --- |
| `EVENTS_SCHEMA_VERSION` | `'v0'` | The current schema version constant. |
| `validateEventV0` | `(value: unknown) => value is RebilderEventV0` | Boolean type guard; never throws. Unknown extra keys are allowed at every level (additive schema). |
| `assertEventV0` | `(value: unknown) => asserts value is RebilderEventV0` | Throws a descriptive `Error` naming the first offending field. |
| `createHttpEventSink` | `(options: HttpEventSinkOptions) => EventSink` | The batching HTTP emission client; see [Events](/docs/events). |
| `createConsoleEventSink` | `() => EventSink` | One `[rebilder-event] {json}` line per event via `console.info`. |
| `EventSink` | `{ emit(event): void; flush(): Promise<void>; close(): Promise<void> }` | `emit` never throws; `flush`/`close` never reject. |
| `HttpEventSinkOptions` | `{ url; apiKey; maxBatch?; flushIntervalMs?; fetchImpl?; onError? }` | Full option table on the [Events](/docs/events) page. |
| `RebilderEventV0` (+ subtypes) | `RebilderEventRequesterV0`, `RebilderEventRequestV0`, `RebilderEventResponseV0`, `RebilderEventOutcomeV0`, `RequesterKindV0`, `RequesterPlatformV0`, `ResponsePathV0` | The frozen v0 type contract, with a field-by-field reference on the [Events](/docs/events) page. |
| `EVENTS_PACKAGE_STATUS` | `string` | Human-readable phase/status constant. |

## @rebilder/protocols

Spec-versioned UCP / ACP / MCP adapters; full behavior is on the [Protocols](/docs/protocols) page. Public API from the root export plus the sanctioned per-version subpaths `@rebilder/protocols/ucp/v0`, `/acp/v0`, `/mcp/v0`; deeper imports are forbidden. Deliberately **not** a gateway dependency: you construct the handler and pass it in as `GatewayConfig.protocols`.

| Export | Signature | Notes |
| --- | --- | --- |
| `createProtocolHandler` | `(config: ProtocolConfig) => ProtocolHandler` | The one entry point. The returned handler is `(req: Request, decision?) => Promise<Response | null>`: `null` for non-protocol routes, and adapter throws are contained to `null`. |
| `ProtocolConfig` | `{ storeId: string; sources: ProtocolSources; checkout?: ProtocolCheckout; onEvent? }` | Same shape family as `GatewayConfig`; leave `onEvent` unset behind the gateway (it already emits one event per request). |
| `ProtocolSources` / `SourceResolver` | structurally identical to `GatewaySources` | One wiring object serves both configs. |
| `ProtocolCheckout` | `{ handoffUrl: (productUrl: URL) => string | null; requireVerified?: boolean }` | `handoffUrl` returning `null` answers 404 (a throw is contained as `null`); `requireVerified` defaults to `true`; see the [checkout verification gate](/docs/protocols#checkout-verification). |
| `AGENT_VERIFIED_HEADER` | `'x-rebilder-agent-verified'` | The gateway-stamped verdict header the checkout gate keys on. |
| `ProtocolHandler` / `ProtocolDecision` / `ProtocolName` | handler + decision types; `'ucp' | 'acp' | 'mcp'` | The protocol union names our three adapters. |
| `PROTOCOLS_PACKAGE_STATUS` | `string` | Human-readable status constant. |

**Re-exported dependency types** (mirroring the gateway’s policy, so a standalone integrator installs only `@rebilder/protocols`): `ProductSource`, `ProductVariantSource`, `PolicySource`, `CatalogItemSource`, `Money`, `Availability` (from the renderer) and `RebilderEventV0` (from events).

> **What remains phase-gated** Protocol endpoints and Web Bot Auth **verification** are live; verification enforces once the operator populates the key registry, which ships empty by design. Human variant serving (`html-variant` with a `variant_id`) has no emitter today.