API reference
Every public export of @rebilder/gateway (root + /next, /shopify, /node, /edge subpaths), @rebilder/events, and @rebilder/protocols, with signatures.
@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. |
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. |
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 — no network, never throws. |
KNOWN_AGENT_DIRECTORY | AgentKeyRegistry | The built-in registry — 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. |
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 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. |
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. |
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. |
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 page. |
RebilderEventV0 (+ subtypes) | RebilderEventRequesterV0, RebilderEventRequestV0, RebilderEventResponseV0, RebilderEventOutcomeV0, RequesterKindV0, RequesterPlatformV0, ResponsePathV0 | The frozen v0 type contract — field-by-field reference on the Events page. |
EVENTS_PACKAGE_STATUS | string | Human-readable phase/status constant. |
@rebilder/protocols
Spec-versioned UCP / ACP / MCP adapters — full behavior on the 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 — the checkout verification gate. |
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).