API reference
Every public export of @rebilder/gateway (root + /next, /shopify, /node, /edge, /fetch subpaths), and @rebilder/events, with signatures.
Last updated
On this page
@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), including a .md URL with markdownUrls, or a markdown 404 (X-Rebilder-Path: not-found) with notFound; 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; maxBytesBySource?: Partial<Record<SourceKind, number>>; sourceTimeoutMs?: number; protocols?: (req: Request) => Promise<Response | null>; verification?: GatewayVerification; access?: AccessPolicySource; markdownUrls?: boolean; frontmatter?: boolean; notFound?: GatewayNotFound } | The one config object, shared by every adapter. protocols is an optional hook for protocol routes, verification the Web Bot Auth registry; see Verification. markdownUrls, frontmatter and notFound are off by default; see Help agents find your markdown. |
GatewayNotFound | { links?: Array<{ title: string; url: string; note?: string }>; isMissing?: (url: URL) => boolean } | The markdown 404. isMissing is how the Next.js and Node adapters know a page does not exist; the fetch and edge adapters also use your own 404 and 410. |
markdownAlternate | (config: GatewayConfig, url: string | URL) => { rel: 'alternate'; type: 'text/markdown'; href: string } | null | The <link> for your page head. null unless the match router confirms a source. |
generateSitemapMd | (config: GatewayConfig, options: SitemapMdOptions) => Promise<string> | Deterministic /sitemap.md: sections from your sources, then yours. |
SitemapMdOptions | { baseUrl: string; title?: string; description?: string; sections?: LlmsTxtSection[] } | title defaults to Sitemap. |
markdownNotFoundResponse | (options: GatewayNotFound, requestUrl: URL, status?: 404 | 410) => Response | The markdown 404 on its own, for a route of yours that knows a page is missing. |
GatewayVerification | { keys: AgentKeyRegistry; require?: 'protocol' } | Key registry for Web Bot Auth verification on the protocol path. Populate it with the agent keys you trust. |
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. Add trusted keys before enabling verification. |
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?; document?; collection?; match? } | 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, DocumentSource, CollectionSource, 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. |
createSitemapMdRouteHandler | (config: GatewayConfig, options: SitemapMdOptions) => (req: Request) => Promise<Response> | /sitemap.md as text/markdown; charset=utf-8, with the same cache headers as llms.txt. |
markdownAlternateTypes | (config: GatewayConfig, url: string | URL) => { 'text/markdown': string } | undefined | For alternates.types in Next.js metadata. |
@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. With notFound, the origin’s 404 or 410 to a markdown request becomes the markdown 404. |
GatewayFetchHandlerOptions | { fallback?: (req: Request) => Response | Promise<Response> } | Serves every non-markdown request. Default: fetch(req), the origin pass-through. |
@rebilder/gateway/fetch#
| Export | Signature | Notes |
|---|---|---|
createFetchMiddleware | (config: GatewayConfig) => FetchMiddleware | Framework-neutral middleware; see Frameworks. |
FetchMiddleware / FetchNext | (request: Request, next: FetchNext) => Promise<Response> / () => Response | Promise<Response> | Markdown short-circuits without calling next; everything else returns next()’s response with the negotiation headers added. With notFound, your 404 or 410 to a markdown request becomes the markdown 404. |
negotiationHeaders | (config: GatewayConfig, url: URL) => Array<[string, string]> | The headers to append to a pass-through response, for hosts that cannot wrap it (Nitro, Vercel Routing Middleware). |
withNegotiationHeaders | (response: Response, config: GatewayConfig, url: URL) => Response | A copy of response with the negotiation headers; safe on immutable fetch() responses. |
handleRequest | (req: Request, config: GatewayConfig) => Promise<Response | null> | Re-exported from the root for recipes that need the core call directly. |
@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, with a field-by-field reference on the Events page. |
EVENTS_PACKAGE_STATUS | string | Human-readable phase/status constant. |