API reference

new App(options?: {
  bodyLimitBytes?:        number; // default 1 MiB
  allowedContentTypes?:   string[]; // default ["application/json"]
  requestTimeoutMs?:      number; // default 30_000
  production?:            boolean; // defaults from NODE_ENV
  logger?:                Logger;
  mockMode?:              boolean;
})

app.route(def): App
app.group(prefix, opts, register): App  // mount routes under a prefix with shared tags/hooks/auth
app.use(middleware): App
app.register(plugin, opts?): App
app.decorate(key, value): App
app.ready(): Promise<void>
app.fetch(req: Request): Promise<Response>
app.request(input, init?): Promise<Response>
app.introspect(): RouteInfo[]
app.shutdown(timeoutMs?): Promise<void>

HttpError                    // base — { status, title, type?, detail?, instance? }
BadRequestError              // 400
UnauthorizedError            // 401
ForbiddenError               // 403
NotFoundError                // 404
MethodNotAllowedError        // 405 — sets Allow header
RequestTimeoutError          // 408
PayloadTooLargeError         // 413
UnsupportedMediaTypeError    // 415
ValidationError              // 422
TooManyRequestsError         // 429 — sets Retry-After
InternalError                // 500 — detail redacted in production

readBodyLimited(req, limit): Promise<Uint8Array>
safeJsonParse(text): unknown
sanitizeHeaderName(name): string
sanitizeHeaderValue(value): string
timingSafeEqual(a, b): boolean
randomId(): string

requestId({ header?, trustIncoming?, generator? })
secureHeaders({ csp?, hsts?, frameOptions?, referrerPolicy?, permissionsPolicy?, coop?, corp?, noSniff?, xssProtection? })
cors({ origin, methods?, allowedHeaders?, exposedHeaders?, credentials?, maxAgeSeconds? })
rateLimit({ windowMs, max, keyGenerator?, store?, trustProxyHeaders?, retryAfter? })
timing(headerName?)
bearerAuth({ validate, realm? })

createLogger({ level?, bindings?, write? }): Logger
noopLogger: Logger

interface Logger {
  trace(obj?, msg?): void;
  debug(obj?, msg?): void;
  info (obj?, msg?): void;
  warn (obj?, msg?): void;
  error(obj?, msg?): void;
  fatal(obj?, msg?): void;
  child(bindings): Logger;
}

generateOpenAPI(app, {
  info: { title: string; version: string; description?: string };
  servers?: { url: string; description?: string }[];
  securitySchemes?: Record<string, SecurityScheme>;
  webhooks?: Record<string, WebhookDefinition | WebhookDefinition[]>;
}): OpenAPIDocument

// Builders for OpenAPI 3.1 Security Scheme objects (also re-exported from "@daloyjs/core")
httpBearerScheme({ bearerFormat?, description? }):           HttpBearerScheme
httpBasicScheme({ description? }):                           HttpBasicScheme
apiKeyScheme({ in: "header"|"query"|"cookie", name, description? }): ApiKeyScheme
oauth2Scheme({ flows, description? }):                       OAuth2Scheme
openIdConnectScheme({ openIdConnectUrl, description? }):     OpenIdConnectScheme

// Webhook (OpenAPI 3.1 top-level webhooks). Mirrors RouteDefinition minus
// path + handler.
interface WebhookDefinition {
  method: HttpMethod;
  operationId?: string;
  summary?: string;
  description?: string;
  tags?: string[];
  deprecated?: boolean;
  request?: RequestSchemas;
  responses: ResponsesMap;
  auth?: AuthSpec;
}

createClient<App>(app, {
  baseUrl: string;
  fetch?:  typeof fetch;
  headers?: Record<string, string>;
}): Client<App>
// returns an object keyed by operationId; each method takes
// { params?, query?, headers?, body? } and returns
// { status, body, headers } as a discriminated union by status.

runContractTests(app, opts?: {
  requireOperationId?:    boolean; // default true
  allowBodyOnSafeMethods?: boolean; // default false
}): Promise<{ ok: boolean; checked: number; issues: Issue[] }>

scalarHtml({ specUrl, title, assets?, scriptNonce? }): string
swaggerUiHtml({ specUrl, title, assets?, scriptNonce? }): string
docsContentSecurityPolicy({ assetOrigins?, scriptNonce?, allowInlineStyles? }): string
htmlResponse(html, { assetOrigins?, scriptNonce?, allowInlineStyles?, contentSecurityPolicy? }): Response

serve(app, opts?: {
  port?:                number; // default 3000
  hostname?:            string; // default "0.0.0.0"
  connectionTimeoutMs?: number;
  shutdownTimeoutMs?:   number;
  handleSignals?:       boolean; // default true
  maxHeaderBytes?:      number;  // default 16 KiB
}): { port: number; close(): Promise<void> }

serve(app, opts?: {
  port?:               number; // default 3000
  hostname?:           string; // default "0.0.0.0"
  maxRequestBodySize?: number; // default 16 MiB
}): { port: number; stop(): Promise<void> }

serve(app, opts?: {
  port?:     number; // default 3000
  hostname?: string; // default "0.0.0.0"
}): { shutdown(): Promise<void> }

toFetchHandler(app): { fetch(req: Request, env?: unknown, ctx?: unknown): Promise<Response> }
toEdgeHandler (app): (req: Request) => Promise<Response>

isStandardSchema(value): boolean
validate(schema, input): { ok: true; value } | { ok: false; issues }