@cleverbrush/server 0.0.0-beta-20260413195755

package/README.md

@@ -0,0 +1,230 @@
+# @cleverbrush/server
+
+[![CI](https://github.com/cleverbrush/framework/actions/workflows/ci.yml/badge.svg)](https://github.com/cleverbrush/framework/actions/workflows/ci.yml)
+[![License: BSD-3-Clause](https://img.shields.io/badge/license-BSD--3--Clause-blue.svg)](../../LICENSE)
+
+A schema-first HTTP server framework for Node.js. Combines [`@cleverbrush/schema`](../schema) for request validation, [`@cleverbrush/di`](../di) for dependency injection, and [`@cleverbrush/auth`](../auth) for authentication — all wired together through a fluent builder API.
+
+## Features
+
+- **Fluent endpoint builder** — `endpoint.get('/users').body(schema).query(schema).authorize()` with fully typed handler context.
+- **Action results** — `ActionResult.ok()`, `.created()`, `.noContent()`, `.redirect()`, `.file()`, `.stream()`, `.status()` — no manual `res.write()` / `res.end()`.
+- **Content negotiation** — pluggable `ContentTypeHandler` registry; JSON registered by default; honours the `Accept` request header.
+- **Middleware pipeline** — `server.use(middleware)` for global middleware; per-endpoint middleware via `handle(ep, handler, { middlewares })`.
+- **DI integration** — `endpoint.inject({ db: IDbContext })` resolves services per-request from a `@cleverbrush/di` container.
+- **Authentication & authorization** — `server.useAuthentication()` / `server.useAuthorization()` wired to `@cleverbrush/auth` schemes and policies.
+- **RFC 9457 Problem Details** — validation errors and `HttpError` subclasses are serialized as `application/problem+json`.
+- **Type-safe routes** — `route()` builds typed path parameters using `ParseStringSchemaBuilder` segments.
+- **OpenAPI-ready** — `getRegistrations()` exposes endpoint metadata for `@cleverbrush/server-openapi`.
+- **Health check** — optional `/health` endpoint via `server.withHealthcheck()`.
+
+## Installation
+
+```bash
+npm install @cleverbrush/server @cleverbrush/schema
+```
+
+## Quick Start
+
+```ts
+import { ServerBuilder, endpoint, ActionResult } from '@cleverbrush/server';
+import { object, string, number } from '@cleverbrush/schema';
+
+const CreateUserBody = object({ name: string(), age: number() });
+
+const createUser = endpoint
+    .post('/api/users')
+    .body(CreateUserBody);
+
+const server = new ServerBuilder();
+
+server.handle(createUser, ({ body }) => {
+    // body is fully typed: { name: string; age: number }
+    return ActionResult.created({ id: 1, ...body }, '/api/users/1');
+});
+
+await server.listen(3000);
+```
+
+## Defining Endpoints
+
+### HTTP Methods
+
+Use the `endpoint` singleton to start a builder chain:
+
+```ts
+import { endpoint } from '@cleverbrush/server';
+
+const getUser  = endpoint.get('/api/users/:id');
+const postUser = endpoint.post('/api/users');
+const putUser  = endpoint.put('/api/users/:id');
+const delUser  = endpoint.delete('/api/users/:id');
+```
+
+### Request Validation
+
+Attach schemas for body, query string, and headers. Validation errors automatically produce a 400 Problem Details response.
+
+```ts
+import { object, string, number } from '@cleverbrush/schema';
+
+const ListUsers = endpoint
+    .get('/api/users')
+    .query(object({ page: number().coerce().optional(), search: string().optional() }));
+
+const CreateUser = endpoint
+    .post('/api/users')
+    .body(object({ name: string(), email: string() }));
+```
+
+### Type-Safe Path Parameters
+
+Use `route()` to define path parameters with the full schema type system:
+
+```ts
+import { route } from '@cleverbrush/server';
+import { number } from '@cleverbrush/schema';
+
+const GetUser = endpoint.get(
+    route({ id: number().coerce() })`/api/users/${t => t.id}`
+);
+
+server.handle(GetUser, ({ params }) => {
+    params.id; // number (already coerced from the URL)
+});
+```
+
+### Authorization
+
+```ts
+import { object, string } from '@cleverbrush/schema';
+
+const UserPrincipal = object({ sub: string(), role: string() });
+
+// Any authenticated user
+const ProtectedEp = endpoint.get('/api/profile').authorize(UserPrincipal);
+
+// Specific roles
+const AdminEp = endpoint.delete('/api/users/:id').authorize(UserPrincipal, 'admin');
+```
+
+### OpenAPI Metadata
+
+```ts
+const CreateUser = endpoint
+    .post('/api/users')
+    .body(CreateUserBody)
+    .returns(UserSchema)
+    .summary('Create a new user')
+    .description('Creates a user and returns the full record.')
+    .tags('users')
+    .operationId('createUser');
+```
+
+## Registering and Handling Endpoints
+
+```ts
+const server = new ServerBuilder();
+
+server.handle(CreateUser, ({ body, context }) => {
+    return ActionResult.created({ id: 42, ...body }, `/api/users/42`);
+});
+
+// Per-endpoint middleware
+server.handle(AdminEp, ({ params }) => { /* … */ }, {
+    middlewares: [loggingMiddleware]
+});
+
+await server.listen(3000);
+```
+
+## Action Results
+
+| Method | Status | Notes |
+|---|---|---|
+| `ActionResult.ok(body)` | 200 | Content-negotiated JSON |
+| `ActionResult.created(body, location?)` | 201 | Sets `Location` header |
+| `ActionResult.noContent()` | 204 | No body |
+| `ActionResult.redirect(url, permanent?)` | 302 / 301 | |
+| `ActionResult.json(body, status?)` | any | Forces `application/json` |
+| `ActionResult.file(buffer, fileName)` | 200 | Attachment download |
+| `ActionResult.content(body, contentType)` | 200 | Arbitrary string body |
+| `ActionResult.stream(readable, contentType)` | 200 | Pipes a `Readable` |
+| `ActionResult.status(status)` | any | Bare status, no body |
+
+## Middleware
+
+```ts
+import type { Middleware } from '@cleverbrush/server';
+
+const logger: Middleware = async (ctx, next) => {
+    console.log(ctx.method, ctx.url.pathname);
+    await next();
+};
+
+server.use(logger);
+```
+
+## Dependency Injection
+
+```ts
+import { ServiceCollection } from '@cleverbrush/di';
+import { object, func, string } from '@cleverbrush/schema';
+
+const IUserRepo = object({ findById: func() });
+
+const GetUser = endpoint
+    .get('/api/users/:id')
+    .inject({ repo: IUserRepo });
+
+server
+    .services(svc => svc.addSingleton(IUserRepo, () => new UserRepository()))
+    .handle(GetUser, ({ params }, { repo }) => {
+        return repo.findById(params.id);
+    });
+```
+
+## Authentication
+
+```ts
+import { jwtScheme } from '@cleverbrush/auth';
+
+server.useAuthentication({
+    defaultScheme: 'jwt',
+    schemes: [
+        jwtScheme({
+            secret: process.env.JWT_SECRET!,
+            mapClaims: claims => ({ sub: claims.sub as string, role: claims.role as string })
+        })
+    ]
+});
+
+server.useAuthorization();
+```
+
+## HTTP Errors
+
+Throw any `HttpError` subclass from a handler — it becomes a Problem Details response automatically:
+
+```ts
+import { NotFoundError, BadRequestError, ForbiddenError } from '@cleverbrush/server';
+
+server.handle(GetUser, ({ params }) => {
+    const user = db.find(params.id);
+    if (!user) throw new NotFoundError(`User ${params.id} not found`);
+    return user;
+});
+```
+
+| Class | Status |
+|---|---|
+| `BadRequestError` | 400 |
+| `UnauthorizedError` | 401 |
+| `ForbiddenError` | 403 |
+| `NotFoundError` | 404 |
+| `ConflictError` | 409 |
+| `HttpError` | any (base class) |
+
+## License
+
+BSD-3-Clause — see [LICENSE](../../LICENSE).

package/dist/ActionResult.d.ts

@@ -0,0 +1,119 @@
+import type * as http from 'node:http';
+import type { Readable } from 'node:stream';
+import type { ContentNegotiator } from './ContentNegotiator.js';
+/**
+ * Abstract base for all HTTP action results.
+ *
+ * Instead of writing directly to `res`, handlers return an `ActionResult`
+ * instance. The server calls `executeAsync()` after the middleware pipeline
+ * completes, ensuring consistent error handling and content negotiation.
+ *
+ * Use the static factory methods (`ActionResult.ok()`, `.created()`, etc.)
+ * rather than constructing subclasses directly.
+ *
+ * @example
+ * ```ts
+ * server.handle(GetUser, ({ params }) => {
+ *     const user = db.find(params.id);
+ *     if (!user) throw new NotFoundError();
+ *     return ActionResult.ok(user);
+ * });
+ * ```
+ */
+export declare abstract class ActionResult {
+    abstract executeAsync(req: http.IncomingMessage, res: http.ServerResponse, contentNegotiator: ContentNegotiator): Promise<void>;
+    /** 200 OK — serializes value using content negotiation. */
+    static ok(body: unknown, headers?: Record<string, string>): JsonResult;
+    /** 201 Created — serializes value using content negotiation. */
+    static created(body: unknown, location?: string, headers?: Record<string, string>): JsonResult;
+    /** 204 No Content. */
+    static noContent(): NoContentResult;
+    /** Temporary (302) or permanent (301) redirect. */
+    static redirect(url: string, permanent?: boolean): RedirectResult;
+    /** Explicit JSON response — always uses application/json regardless of Accept. */
+    static json(body: unknown, status?: number, headers?: Record<string, string>): JsonResult;
+    /** Send a file buffer as a download attachment. */
+    static file(content: Buffer | Uint8Array, fileName: string, contentType?: string): FileResult;
+    /** Arbitrary string body with an explicit content type. */
+    static content(body: string, contentType: string, status?: number): ContentResult;
+    /** Pipe a Readable stream to the response. */
+    static stream(readable: Readable, contentType: string, fileName?: string): StreamResult;
+    /** Bare status code with no body. */
+    static status(status: number, headers?: Record<string, string>): StatusCodeResult;
+}
+/**
+ * Serializes a value and writes it as JSON with `content-type: application/json`,
+ * bypassing content negotiation entirely.
+ *
+ * Created by `ActionResult.json()`.
+ * `ActionResult.ok()` and `ActionResult.created()` produce a {@link JsonResult}
+ * that goes through content negotiation instead.
+ */
+export declare class JsonResult extends ActionResult {
+    readonly body: unknown;
+    readonly status: number;
+    readonly headers: Record<string, string>;
+    constructor(body: unknown, status?: number, headers?: Record<string, string>);
+    executeAsync(_req: http.IncomingMessage, res: http.ServerResponse, _contentNegotiator: ContentNegotiator): Promise<void>;
+}
+/**
+ * Sends a binary buffer as a file download attachment.
+ * Created by `ActionResult.file()`.
+ */
+export declare class FileResult extends ActionResult {
+    readonly content: Buffer | Uint8Array;
+    readonly fileName: string;
+    readonly contentType: string;
+    constructor(content: Buffer | Uint8Array, fileName: string, contentType?: string);
+    executeAsync(_req: http.IncomingMessage, res: http.ServerResponse, _contentNegotiator: ContentNegotiator): Promise<void>;
+}
+/**
+ * Writes an arbitrary string body with a specific content type and status.
+ * Created by `ActionResult.content()`.
+ */
+export declare class ContentResult extends ActionResult {
+    readonly body: string;
+    readonly contentType: string;
+    readonly status: number;
+    constructor(body: string, contentType: string, status?: number);
+    executeAsync(_req: http.IncomingMessage, res: http.ServerResponse, _contentNegotiator: ContentNegotiator): Promise<void>;
+}
+/**
+ * Pipes a `Readable` stream to the HTTP response.
+ * Created by `ActionResult.stream()`.
+ */
+export declare class StreamResult extends ActionResult {
+    readonly readable: Readable;
+    readonly contentType: string;
+    readonly fileName: string | undefined;
+    constructor(readable: Readable, contentType: string, fileName?: string);
+    executeAsync(_req: http.IncomingMessage, res: http.ServerResponse, _contentNegotiator: ContentNegotiator): Promise<void>;
+}
+/**
+ * Responds with a bare HTTP status code and no body.
+ * Created by `ActionResult.status()`.
+ */
+export declare class StatusCodeResult extends ActionResult {
+    readonly status: number;
+    readonly headers: Record<string, string>;
+    constructor(status: number, headers?: Record<string, string>);
+    executeAsync(_req: http.IncomingMessage, res: http.ServerResponse, _contentNegotiator: ContentNegotiator): Promise<void>;
+}
+/**
+ * Redirects the client to a new URL.
+ * Uses 302 (temporary) by default; pass `permanent = true` for 301.
+ * Created by `ActionResult.redirect()`.
+ */
+export declare class RedirectResult extends ActionResult {
+    readonly url: string;
+    readonly permanent: boolean;
+    constructor(url: string, permanent?: boolean);
+    executeAsync(_req: http.IncomingMessage, res: http.ServerResponse, _contentNegotiator: ContentNegotiator): Promise<void>;
+}
+/**
+ * Responds with 204 No Content and no body.
+ * Created by `ActionResult.noContent()`.
+ */
+export declare class NoContentResult extends ActionResult {
+    executeAsync(_req: http.IncomingMessage, res: http.ServerResponse, _contentNegotiator: ContentNegotiator): Promise<void>;
+}

package/dist/ContentNegotiator.d.ts

@@ -0,0 +1,31 @@
+import type { ContentTypeHandler } from './types.js';
+/**
+ * Selects the appropriate serializer/deserializer for a request or response
+ * based on the `Accept` / `Content-Type` HTTP headers.
+ *
+ * JSON is registered by default. Additional handlers can be added with
+ * `register()` or via `ServerBuilder.contentType()`.
+ */
+export declare class ContentNegotiator {
+    #private;
+    constructor();
+    /**
+     * Register a new content type handler.
+     * If a handler for the same MIME type was already registered it is replaced.
+     */
+    register(handler: ContentTypeHandler): void;
+    /**
+     * Select the best response serializer for the given `Accept` header value.
+     *
+     * Returns `null` if no registered handler can satisfy the request;
+     * the server will respond with 406 Not Acceptable in that case.
+     */
+    selectResponseHandler(acceptHeader?: string): ContentTypeHandler | null;
+    /**
+     * Select the deserializer for an incoming `Content-Type` header.
+     *
+     * Returns `null` if the content type is not recognised; the server will
+     * respond with 415 Unsupported Media Type in that case.
+     */
+    selectRequestHandler(contentTypeHeader?: string): ContentTypeHandler | null;
+}

package/dist/Endpoint.d.ts

@@ -0,0 +1,203 @@
+import type { InferType, ObjectSchemaBuilder, ParseStringSchemaBuilder, SchemaBuilder } from '@cleverbrush/schema';
+import type { ActionResult } from './ActionResult.js';
+import type { RequestContext } from './RequestContext.js';
+type Simplify<T> = {
+    [K in keyof T]: T[K];
+} & {};
+type HasKeys<T> = keyof T extends never ? false : true;
+type ActionContextParts<TParams, TBody, TQuery, THeaders, TPrincipal> = {
+    context: RequestContext;
+} & (HasKeys<TParams> extends true ? {
+    params: TParams;
+} : {}) & (TBody extends undefined ? {} : {
+    body: TBody;
+}) & (HasKeys<TQuery> extends true ? {
+    query: TQuery;
+} : {}) & (HasKeys<THeaders> extends true ? {
+    headers: THeaders;
+} : {}) & (TPrincipal extends undefined ? {} : {
+    principal: TPrincipal;
+});
+/**
+ * The fully-typed argument object passed to endpoint handlers.
+ *
+ * The shape is inferred from the `EndpointBuilder` chain — only the keys
+ * actually configured (body, query, headers, params, principal) are present.
+ */
+export type ActionContext<E> = E extends EndpointBuilder<infer TParams, infer TBody, infer TQuery, infer THeaders, any, infer TPrincipal, any, any> ? Simplify<ActionContextParts<TParams, TBody, TQuery, THeaders, TPrincipal>> : never;
+type InferServices<T> = {
+    [K in keyof T]: T[K] extends SchemaBuilder<any, any, any, any, any> ? InferType<T[K]> : never;
+};
+/**
+ * Extracts the injected service schemas map from an `EndpointBuilder` type.
+ * Used internally by the `Handler` type to derive the `services` argument.
+ */
+export type ServiceSchemas<E> = E extends EndpointBuilder<any, any, any, any, infer TServices, any, any, any> ? TServices : {};
+type ResponseType<E> = E extends EndpointBuilder<any, any, any, any, any, any, any, infer TResponse> ? TResponse : any;
+/**
+ * The handler function type inferred from an `EndpointBuilder`.
+ *
+ * When the endpoint has injected services, the handler receives a second
+ * `services` argument with all resolved service instances.
+ */
+export type Handler<E> = HasKeys<ServiceSchemas<E>> extends true ? (arg: ActionContext<E>, services: Simplify<InferServices<ServiceSchemas<E>>>) => ResponseType<E> | ActionResult | Promise<ResponseType<E> | ActionResult> : (arg: ActionContext<E>) => ResponseType<E> | ActionResult | Promise<ResponseType<E> | ActionResult>;
+type RoutePath = string | ParseStringSchemaBuilder<any, any, any, any, any>;
+/**
+ * Snapshot of all configuration set on an `EndpointBuilder`.
+ * Used by the server for routing and by `@cleverbrush/server-openapi` for
+ * spec generation.
+ */
+export interface EndpointMetadata {
+    readonly method: string;
+    readonly basePath: string;
+    readonly pathTemplate: RoutePath;
+    readonly bodySchema: SchemaBuilder<any, any, any, any, any> | null;
+    readonly querySchema: ObjectSchemaBuilder<any, any, any, any, any, any, any> | null;
+    readonly headerSchema: ObjectSchemaBuilder<any, any, any, any, any, any, any> | null;
+    readonly serviceSchemas: Record<string, SchemaBuilder<any, any, any, any, any>> | null;
+    /**
+     * Authorization roles required for this endpoint.
+     * - `null` → no authorization required (public)
+     * - `[]` → any authenticated user
+     * - `['admin', ...]` → user must have at least one of these roles
+     */
+    readonly authRoles: readonly string[] | null;
+    readonly summary: string | null;
+    readonly description: string | null;
+    readonly tags: readonly string[];
+    readonly operationId: string | null;
+    readonly deprecated: boolean;
+    readonly responseSchema: SchemaBuilder<any, any, any, any, any> | null;
+}
+/**
+ * Immutable, fluent builder for HTTP endpoint definitions.
+ *
+ * All methods return a new builder instance — the original is never mutated.
+ * Use the {@link endpoint} singleton (or {@link createEndpoints}) to obtain
+ * the first builder in the chain.
+ *
+ * @example
+ * ```ts
+ * const GetUser = endpoint
+ *     .get('/api/users')
+ *     .query(object({ id: number().coerce() }))
+ *     .authorize(UserPrincipal, 'admin')
+ *     .returns(UserSchema)
+ *     .summary('Get a user by ID');
+ * ```
+ */
+export declare class EndpointBuilder<TParams = {}, TBody = undefined, TQuery = {}, THeaders = {}, TServices = {}, TPrincipal = undefined, TRoles extends string = string, TResponse = any> {
+    #private;
+    constructor(method: string, basePath: string, pathTemplate: RoutePath, bodySchema: SchemaBuilder<any, any, any, any, any> | null, querySchema: ObjectSchemaBuilder<any, any, any, any, any, any, any> | null, headerSchema: ObjectSchemaBuilder<any, any, any, any, any, any, any> | null, serviceSchemas?: Record<string, SchemaBuilder<any, any, any, any, any>> | null, authRoles?: readonly string[] | null, summary?: string | null, description?: string | null, tags?: readonly string[], operationId?: string | null, deprecated?: boolean, responseSchema?: SchemaBuilder<any, any, any, any, any> | null);
+    /** Define the request body schema. Validation failures return 422 Problem Details. */
+    /** Define the request body schema. Validation failures return 422 Problem Details. */
+    body<TSchema extends SchemaBuilder<any, any, any, any, any>>(schema: TSchema): EndpointBuilder<TParams, InferType<TSchema>, TQuery, THeaders, TServices, TPrincipal, TRoles, TResponse>;
+    /** Define the query string schema (must be an object schema). Validation failures return 422. */
+    query<TSchema extends ObjectSchemaBuilder<any, any, any, any, any, any, any>>(schema: TSchema): EndpointBuilder<TParams, TBody, InferType<TSchema>, THeaders, TServices, TPrincipal, TRoles, TResponse>;
+    /** Define an expected request headers schema (must be an object schema). */
+    headers<TSchema extends ObjectSchemaBuilder<any, any, any, any, any, any, any>>(schema: TSchema): EndpointBuilder<TParams, TBody, TQuery, InferType<TSchema>, TServices, TPrincipal, TRoles, TResponse>;
+    /** Declare DI services to be resolved per-request and passed as the second handler argument. */
+    inject<TSchemas extends Record<string, SchemaBuilder<any, any, any, any, any>>>(schemas: TSchemas): EndpointBuilder<TParams, TBody, TQuery, THeaders, TSchemas, TPrincipal, TRoles, TResponse>;
+    /**
+     * Mark this endpoint as requiring authorization.
+     *
+     * Overloads:
+     * - `authorize(principalSchema, ...roles)` — typed principal, optional role requirements
+     * - `authorize(...roles)` — untyped principal (`unknown`), optional role requirements
+     *
+     * If no roles are specified, any authenticated user is allowed.
+     */
+    authorize<TSchema extends SchemaBuilder<any, any, any, any, any>>(principalSchema: TSchema, ...roles: TRoles[]): EndpointBuilder<TParams, TBody, TQuery, THeaders, TServices, InferType<TSchema>, TRoles, TResponse>;
+    authorize(...roles: TRoles[]): EndpointBuilder<TParams, TBody, TQuery, THeaders, TServices, unknown, TRoles, TResponse>;
+    /**
+     * Declare the response type for OpenAPI spec generation.
+     *
+     * Overloads:
+     * - `returns<T>()` — generic type only, no runtime schema
+     * - `returns(schema)` — provides a schema for spec generation and type inference
+     */
+    returns<T>(): EndpointBuilder<TParams, TBody, TQuery, THeaders, TServices, TPrincipal, TRoles, T>;
+    returns<TSchema extends SchemaBuilder<any, any, any, any, any>>(schema: TSchema): EndpointBuilder<TParams, TBody, TQuery, THeaders, TServices, TPrincipal, TRoles, InferType<TSchema>>;
+    /** Short, human-readable summary for OpenAPI operation objects. */
+    summary(text: string): EndpointBuilder<TParams, TBody, TQuery, THeaders, TServices, TPrincipal, TRoles, TResponse>;
+    /** Longer description for OpenAPI operation objects. Supports Markdown. */
+    description(text: string): EndpointBuilder<TParams, TBody, TQuery, THeaders, TServices, TPrincipal, TRoles, TResponse>;
+    /** OpenAPI tags grouping this operation in generated documentation. */
+    tags(...tags: string[]): EndpointBuilder<TParams, TBody, TQuery, THeaders, TServices, TPrincipal, TRoles, TResponse>;
+    /** A unique, stable identifier for this operation in OpenAPI spec. */
+    operationId(id: string): EndpointBuilder<TParams, TBody, TQuery, THeaders, TServices, TPrincipal, TRoles, TResponse>;
+    /** Mark this endpoint as deprecated in OpenAPI spec output. */
+    deprecated(): EndpointBuilder<TParams, TBody, TQuery, THeaders, TServices, TPrincipal, TRoles, TResponse>;
+    /** Return an immutable snapshot of this builder's configuration as {@link EndpointMetadata}. */
+    introspect(): EndpointMetadata;
+}
+/**
+ * Optional OpenAPI metadata fields accepted by `createEndpoint` / `createEndpoints`.
+ */
+export type EndpointMetadataDescriptors = {
+    readonly summary?: string;
+    readonly description?: string;
+    readonly tags?: string[];
+    readonly operationId?: string;
+    readonly deprecated?: boolean;
+};
+type ScopedEndpointFactoryMethods<TPrincipal, TRoles extends string = string> = {
+    get<TParams = {}>(pathTemplate?: ParseStringSchemaBuilder<TParams, any, any, any, any>): EndpointBuilder<TParams, undefined, {}, {}, {}, TPrincipal, TRoles>;
+    post<TParams = {}>(pathTemplate?: ParseStringSchemaBuilder<TParams, any, any, any, any>): EndpointBuilder<TParams, undefined, {}, {}, {}, TPrincipal, TRoles>;
+    put<TParams = {}>(pathTemplate?: ParseStringSchemaBuilder<TParams, any, any, any, any>): EndpointBuilder<TParams, undefined, {}, {}, {}, TPrincipal, TRoles>;
+    patch<TParams = {}>(pathTemplate?: ParseStringSchemaBuilder<TParams, any, any, any, any>): EndpointBuilder<TParams, undefined, {}, {}, {}, TPrincipal, TRoles>;
+    delete<TParams = {}>(pathTemplate?: ParseStringSchemaBuilder<TParams, any, any, any, any>): EndpointBuilder<TParams, undefined, {}, {}, {}, TPrincipal, TRoles>;
+    head<TParams = {}>(pathTemplate?: ParseStringSchemaBuilder<TParams, any, any, any, any>): EndpointBuilder<TParams, undefined, {}, {}, {}, TPrincipal, TRoles>;
+    options<TParams = {}>(pathTemplate?: ParseStringSchemaBuilder<TParams, any, any, any, any>): EndpointBuilder<TParams, undefined, {}, {}, {}, TPrincipal, TRoles>;
+};
+export type ScopedEndpointFactory<TRoles extends string = string> = ScopedEndpointFactoryMethods<undefined, TRoles> & {
+    /**
+     * Returns a new resource factory where all endpoints inherit
+     * the given authorization requirements.
+     *
+     * - `authorize(principalSchema, ...roles)` — typed principal
+     * - `authorize(...roles)` — untyped principal
+     */
+    authorize<TSchema extends SchemaBuilder<any, any, any, any, any>>(principalSchema: TSchema, ...roles: TRoles[]): ScopedEndpointFactoryMethods<InferType<TSchema>, TRoles>;
+    authorize(...roles: TRoles[]): ScopedEndpointFactoryMethods<unknown, TRoles>;
+};
+type EndpointFactory<TRoles extends string = string> = {
+    get<TParams = {}>(basePath: string, pathTemplate?: ParseStringSchemaBuilder<TParams, any, any, any, any>): EndpointBuilder<TParams, undefined, {}, {}, {}, undefined, TRoles>;
+    post<TParams = {}>(basePath: string, pathTemplate?: ParseStringSchemaBuilder<TParams, any, any, any, any>): EndpointBuilder<TParams, undefined, {}, {}, {}, undefined, TRoles>;
+    put<TParams = {}>(basePath: string, pathTemplate?: ParseStringSchemaBuilder<TParams, any, any, any, any>): EndpointBuilder<TParams, undefined, {}, {}, {}, undefined, TRoles>;
+    patch<TParams = {}>(basePath: string, pathTemplate?: ParseStringSchemaBuilder<TParams, any, any, any, any>): EndpointBuilder<TParams, undefined, {}, {}, {}, undefined, TRoles>;
+    delete<TParams = {}>(basePath: string, pathTemplate?: ParseStringSchemaBuilder<TParams, any, any, any, any>): EndpointBuilder<TParams, undefined, {}, {}, {}, undefined, TRoles>;
+    head<TParams = {}>(basePath: string, pathTemplate?: ParseStringSchemaBuilder<TParams, any, any, any, any>): EndpointBuilder<TParams, undefined, {}, {}, {}, undefined, TRoles>;
+    options<TParams = {}>(basePath: string, pathTemplate?: ParseStringSchemaBuilder<TParams, any, any, any, any>): EndpointBuilder<TParams, undefined, {}, {}, {}, undefined, TRoles>;
+    resource(basePath: string): ScopedEndpointFactory<TRoles>;
+};
+/**
+ * Create a role-constrained endpoint factory. Roles are defined as a plain
+ * `as const` object whose *values* become the string-literal union accepted
+ * by `authorize()`.
+ *
+ * @example
+ * ```ts
+ * const Roles = { admin: 'admin', editor: 'editor' } as const;
+ * const ep = createEndpoints(Roles);
+ * ep.get('/api/admin').authorize(IPrincipal, 'admin'); // ✓
+ * ep.get('/api/admin').authorize(IPrincipal, 'typo');  // ✗ type error
+ * ```
+ */
+export declare function createEndpoints<const T extends Record<string, string>>(_roles: T): EndpointFactory<T[keyof T]>;
+/**
+ * The global endpoint factory singleton.
+ *
+ * Creates `EndpointBuilder` instances for each HTTP method. Use
+ * {@link createEndpoints} to get a role-constrained version.
+ *
+ * @example
+ * ```ts
+ * import { endpoint } from '@cleverbrush/server';
+ *
+ * const GetUsers = endpoint.get('/api/users');
+ * const CreateUser = endpoint.post('/api/users').body(CreateUserSchema);
+ * ```
+ */
+export declare const endpoint: EndpointFactory;
+export {};

package/dist/HttpError.d.ts

@@ -0,0 +1,41 @@
+import { type ProblemDetails } from './ProblemDetails.js';
+/**
+ * Base class for HTTP errors thrown from endpoint handlers.
+ *
+ * Instances are automatically caught by the server and serialized as
+ * RFC 9457 Problem Details (`application/problem+json`) responses.
+ *
+ * @example
+ * ```ts
+ * throw new HttpError(429, 'Too Many Requests', 'Rate limit exceeded.');
+ * ```
+ */
+export declare class HttpError extends Error {
+    readonly status: number;
+    readonly title: string;
+    readonly detail?: string;
+    readonly extensions?: Record<string, unknown>;
+    constructor(status: number, title?: string, detail?: string, extensions?: Record<string, unknown>);
+    /** Converts this error into an RFC 9457 {@link ProblemDetails} object. */
+    toProblemDetails(): ProblemDetails;
+}
+/** Thrown when a requested resource cannot be found. Produces a 404 response. */
+export declare class NotFoundError extends HttpError {
+    constructor(detail?: string);
+}
+/** Thrown when the request is malformed or fails validation. Produces a 400 response. */
+export declare class BadRequestError extends HttpError {
+    constructor(detail?: string);
+}
+/** Thrown when the request lacks valid authentication credentials. Produces a 401 response. */
+export declare class UnauthorizedError extends HttpError {
+    constructor(detail?: string);
+}
+/** Thrown when the authenticated principal lacks permission. Produces a 403 response. */
+export declare class ForbiddenError extends HttpError {
+    constructor(detail?: string);
+}
+/** Thrown when the request conflicts with the current state of the resource. Produces a 409 response. */
+export declare class ConflictError extends HttpError {
+    constructor(detail?: string);
+}

package/dist/MiddlewarePipeline.d.ts

@@ -0,0 +1,18 @@
+import type { RequestContext } from './RequestContext.js';
+import type { Middleware } from './types.js';
+/**
+ * Executes a chain of {@link Middleware} functions in order, then invokes
+ * a final handler when `next()` is called by every middleware in the chain.
+ *
+ * Middleware can short-circuit the chain by not calling `next()`.
+ */
+export declare class MiddlewarePipeline {
+    #private;
+    /** Append a middleware to the end of the pipeline. */
+    add(middleware: Middleware): void;
+    /**
+     * Execute the pipeline with the given `context`, calling each middleware
+     * in order and finally invoking `finalHandler`.
+     */
+    execute(context: RequestContext, finalHandler: () => Promise<void>): Promise<void>;
+}

package/dist/ParameterResolver.d.ts

@@ -0,0 +1,25 @@
+import type { EndpointMetadata } from './Endpoint.js';
+import type { ProblemDetails } from './ProblemDetails.js';
+import type { RequestContext } from './RequestContext.js';
+/**
+ * Result returned by `resolveArgs()`. When `valid` is `false` the
+ * `problemDetails` payload should be sent as a 400 response.
+ */
+export type ResolveResult = {
+    valid: true;
+    args: unknown[];
+} | {
+    valid: false;
+    problemDetails: ProblemDetails;
+};
+/**
+ * Returns true if the endpoint declares a body schema.
+ */
+export declare function needsBody(meta: EndpointMetadata): boolean;
+/**
+ * Resolve the action context object for an endpoint-based handler.
+ *
+ * Builds `{ context, params?, body?, query?, headers? }` based on
+ * what the endpoint declares.
+ */
+export declare function resolveArgs(meta: EndpointMetadata, parsedPath: Record<string, any> | null, context: RequestContext, parsedBody: unknown): Promise<ResolveResult>;