@cleverbrush/server 3.1.0 → 4.1.0

package/README.md

@@ -19,6 +19,7 @@ A schema-first HTTP server framework for Node.js. Combines [`@cleverbrush/schema
 - **AsyncAPI-ready** — `getSubscriptionRegistrations()` exposes subscription metadata for `generateAsyncApiSpec()` in `@cleverbrush/server-openapi`.
 - **Health check** — optional `/health` endpoint via `server.withHealthcheck()`.
 - **WebSocket subscriptions** — `endpoint.subscription('/ws/path')` with typed incoming/outgoing schemas, `tracked()` events, and async generator handlers.
+- **Contract composition** — `mergeContracts`, `pickGroups`, and `omitGroups` enable audience-scoped bundles: ship only the endpoints each consumer needs.
 
 ## Installation
 
@@ -123,6 +124,36 @@ const CreateUser = endpoint
     .operationId('createUser');
 ```
 
+### Cache Tags
+
+Tag-based cache invalidation. Tags declared on endpoints flow to the
+[`cacheTags` middleware](/client/cache-tags) for automatic HTTP caching and
+invalidation on mutating requests.
+
+```ts
+const ListTodos = endpoint
+    .get('/api/todos')
+    .query(TodoListQuerySchema)
+    .cacheTag('todo-list', p => ({ page: p.query.page, limit: p.query.limit }))
+    .returns(array(TodoSchema));
+
+const UpdateTodo = endpoint
+    .patch('/api/todos/:id')
+    .body(UpdateTodoBody)
+    .clearsCacheTag('todo-list')               // clears the collection cache
+    .clearsCacheTag('todo', p => ({ id: p.params.id }))  // clears specific entity
+    .returns(TodoSchema);
+```
+
+- **`.cacheTag(name)`** — declares the endpoint's data belongs to a cache
+  group. Use on GET endpoints.
+- **`.clearsCacheTag(name)`** — declares that this mutation clears matching
+  cache entries on success. Use on POST / PUT / PATCH / DELETE.
+- **`.cacheTag(name, p => ({ ... }))`** — property-based tag; each selected
+  property becomes part of the cache key (different pages → different entries).
+- **Immutability** — both methods return a new builder; the original is
+  unchanged.
+
 ## Registering and Handling Endpoints
 
 ```ts
@@ -154,6 +185,48 @@ await server.listen(3000);
 | `ActionResult.stream(readable, contentType)` | 200 | Pipes a `Readable` |
 | `ActionResult.status(status)` | any | Bare status, no body |
 
+## File Upload
+
+Accept file uploads via `multipart/form-data` by chaining `.upload()` on an endpoint:
+
+```ts
+import { endpoint } from '@cleverbrush/server';
+import { object, string } from '@cleverbrush/schema';
+
+const UploadAvatar = endpoint
+    .post('/api/avatar')
+    .upload({ maxFileSize: 2 * 1024 * 1024, allowedMimeTypes: ['image/*'] })
+    .body(object({ description: string().optional() }))
+    .authorize(UserPrincipal);
+
+const handler: Handler<typeof UploadAvatar> = async ({ body, files }) => {
+    const avatar = files['avatar'];
+    // avatar: FilePart { filename, mimeType, buffer, size }
+    return ActionResult.created({ name: avatar.filename });
+};
+```
+
+The `files` object on the handler context contains one `FilePart` entry per uploaded file field. Non-file form fields are validated against the body schema and available via `body`.
+
+### Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `maxFileSize` | `number` | 10 MB | Maximum file size per file in bytes |
+| `allowedMimeTypes` | `string[]` | all | MIME type allowlist (supports `image/*` glob) |
+| `maxFileCount` | `number` | 10 | Maximum number of files per request |
+
+### FilePart type
+
+```ts
+interface FilePart {
+    readonly filename: string;
+    readonly mimeType: string;
+    readonly buffer: Buffer;
+    readonly size: number;
+}
+```
+
 ## Middleware
 
 ```ts
@@ -368,6 +441,83 @@ createServer()
     .listen(3000);
 ```
 
+## Contract Composition
+
+When building applications with distinct audiences — a **public client** and an **admin panel**, for example — you want each consumer to import only the endpoints it needs.  This eliminates leaking admin schemas into the client bundle and improves tree-shaking.
+
+The `@cleverbrush/server/contract` entry point ships three utilities for this.
+
+### `mergeContracts`
+
+Combine two `ApiContract` objects into one.  Groups that only exist in one contract are kept as-is; groups that share a key have their endpoint maps shallowly merged.
+
+```ts
+import { defineApi, mergeContracts } from '@cleverbrush/server/contract';
+
+// public-api.ts — safe to import in every consumer
+export const publicApi = defineApi({
+    todos: { list: ..., get: ..., create: ... },
+    auth:  { login: ..., register: ... },
+});
+
+// admin-api.ts — only imported by the admin application
+const adminApi = defineApi({
+    admin: { activityLog: ..., banUser: ... },
+});
+
+// admin-app/contract.ts
+export const fullAdminApi = mergeContracts(publicApi, adminApi);
+// TypeScript sees: { todos, auth, admin } — all fully typed
+
+// client-app/contract.ts
+import { publicApi } from '../shared/public-api';
+// TypeScript sees: { todos, auth } — admin is absent from the bundle
+```
+
+### `pickGroups`
+
+Returns a new contract containing only the listed groups.  The TypeScript return type is `Pick<T, K>` — the compiler sees exactly the selected groups.
+
+```ts
+import { pickGroups } from '@cleverbrush/server/contract';
+
+const fullApi = defineApi({ todos: {...}, auth: {...}, admin: {...}, debug: {...} });
+
+// Only expose what the frontend needs
+const clientApi = pickGroups(fullApi, 'todos', 'auth');
+// TypeScript: { todos: ..., auth: ... }
+// 'admin' and 'debug' do not exist on the type or at runtime
+```
+
+### `omitGroups`
+
+Inverse of `pickGroups` — strips the listed groups and keeps everything else.  Return type is `Omit<T, K>`.
+
+```ts
+import { omitGroups } from '@cleverbrush/server/contract';
+
+const publicApi = omitGroups(fullApi, 'admin', 'debug');
+// TypeScript: { todos: ..., auth: ... }
+```
+
+### Bundle isolation pattern
+
+The key to keeping admin endpoints out of the client bundle is **file-level separation**.  Export different slices from different entry points:
+
+```
+packages/
+  shared-contracts/
+    src/
+      public.ts        // export const publicApi = defineApi({ ... })
+      admin.ts         // export const adminApi  = defineApi({ ... })
+      full.ts          // export const fullApi   = mergeContracts(publicApi, adminApi)
+
+apps/
+  client/              // imports publicApi  — admin endpoints never bundled
+  admin-panel/         // imports fullApi    — full set of endpoints
+  backend/             // imports fullApi    — handles all routes
+```
+
 ## License
 
 BSD-3-Clause — see [LICENSE](../../LICENSE).

package/dist/CacheTag.d.ts

@@ -0,0 +1,76 @@
+import { type ObjectSchemaBuilder, type SchemaBuilder } from '@cleverbrush/schema';
+/**
+ * An accessor that can extract a property value from a structured
+ * request root.  Wraps a {@link PropertyDescriptor}'s `getValue`
+ * closure so the middleware layer does not need to know about schemas.
+ */
+export interface CacheTagPropertyAccessor {
+    getValue(root: {
+        params: Record<string, unknown>;
+        body: unknown;
+        query: Record<string, unknown>;
+        headers: Record<string, string>;
+    }): {
+        value?: unknown;
+        success: boolean;
+    };
+}
+/**
+ * A serialisable cache-tag definition stored on endpoint metadata.
+ *
+ * `properties` maps human-readable key names (used as label segments
+ * in the final cache key) to accessors that resolve the actual value
+ * from call-time request data.
+ */
+export interface CacheTagDefinition {
+    readonly name: string;
+    readonly properties: Readonly<Record<string, CacheTagPropertyAccessor>>;
+}
+/**
+ * Builds a synthetic `object({ params, body, query, headers })` schema
+ * from the endpoint's schema definitions and returns its
+ * `PropertyDescriptorTree` so callers can write type-safe selectors like:
+ *
+ * ```ts
+ * endpoint.cacheTag('todo', p => ({
+ *     id: p.query.id,
+ *     fromBodyId: p.body.id
+ * }))
+ * ```
+ *
+ * Only non-null schemas are included in the synthetic schema.
+ */
+export declare function createCacheTagTree(schemas: {
+    paramsSchema?: SchemaBuilder<any, any, any, any, any> | null;
+    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;
+}): any;
+/**
+ * Serialises the result of a cache-tag selector callback into a
+ * {@link CacheTagDefinition} that can be stored on endpoint metadata
+ * and forwarded to the client middleware.
+ *
+ * Each value in `descriptors` must be a {@link PropertyDescriptor} —
+ * its `getValue` closure is wrapped in a {@link CacheTagPropertyAccessor}.
+ *
+ * @throws If any value is not a valid property descriptor.
+ */
+export declare function serializeTag(name: string, descriptors: Record<string, unknown>): CacheTagDefinition;
+/**
+ * Computes a deterministic cache key from a tag definition and live
+ * request data.
+ *
+ * - Simple tags (no properties) produce just the tag name.
+ * - Tags with properties produce `name:key1=val1,key2=val2` where
+ *   keys are sorted alphabetically for determinism.
+ *
+ * Properties whose `getValue` returns `success: false` are skipped
+ * (their value is not included in the key).
+ */
+export declare function computeCacheKey(tag: CacheTagDefinition, root: {
+    params: Record<string, unknown>;
+    body: unknown;
+    query: Record<string, unknown>;
+    headers: Record<string, string>;
+}): string;

package/dist/Endpoint.d.ts

@@ -1,13 +1,15 @@
 import type { InferType, ObjectSchemaBuilder, ParseStringSchemaBuilder, PropertyDescriptorTree, SchemaBuilder } from '@cleverbrush/schema';
+import { SYMBOL_SCHEMA_PROPERTY_DESCRIPTOR } from '@cleverbrush/schema';
 import type { ActionResult, ContentResult, FileResult, JsonResult, NoContentResult, RedirectResult, StatusCodeResult, StreamResult } from './ActionResult.js';
+import type { CacheTagDefinition } from './CacheTag.js';
 import type { RequestContext } from './RequestContext.js';
 import { type SubscriptionBuilder, type SubscriptionHandlerEntry } from './Subscription.js';
-import type { Middleware } from './types.js';
+import type { FilePart, Middleware, RejectedFile, UploadOptions } from './types.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> = {
+type ActionContextParts<TParams, TBody, TQuery, THeaders, TPrincipal, TUpload extends boolean> = {
     context: RequestContext;
 } & (HasKeys<TParams> extends true ? {
     params: TParams;
@@ -19,14 +21,17 @@ type ActionContextParts<TParams, TBody, TQuery, THeaders, TPrincipal> = {
     headers: THeaders;
 } : {}) & (TPrincipal extends undefined ? {} : {
     principal: TPrincipal;
-});
+}) & (TUpload extends true ? {
+    files: Record<string, FilePart>;
+    rejectedFiles?: RejectedFile[];
+} : {});
 /**
  * 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, any> ? Simplify<ActionContextParts<TParams, TBody, TQuery, THeaders, TPrincipal>> : never;
+export type ActionContext<E> = E extends EndpointBuilder<infer TParams, infer TBody, infer TQuery, infer THeaders, any, infer TPrincipal, any, any, any, infer TUpload> ? Simplify<ActionContextParts<TParams, TBody, TQuery, THeaders, TPrincipal, TUpload>> : never;
 type InferServices<T> = {
     [K in keyof T]: T[K] extends SchemaBuilder<any, any, any, any, any> ? InferType<T[K]> : never;
 };
@@ -34,13 +39,13 @@ type InferServices<T> = {
  * 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, any> ? TServices : {};
-type ResponseType<E> = E extends EndpointBuilder<any, any, any, any, any, any, any, infer TResponse, any> ? TResponse extends SchemaBuilder<any, any, any, any, any> ? InferType<TResponse> : TResponse : any;
+export type ServiceSchemas<E> = E extends EndpointBuilder<any, any, any, any, infer TServices, any, any, any, any, any> ? TServices : {};
+type ResponseType<E> = E extends EndpointBuilder<any, any, any, any, any, any, any, infer TResponse, any, any> ? TResponse extends SchemaBuilder<any, any, any, any, any> ? InferType<TResponse> : TResponse : any;
 /**
  * Extracts the `TResponses` map from an `EndpointBuilder` type.
  * `TResponses` is a `Record<number, BodyType>` inferred from `.responses()`.
  */
-export type ResponsesOf<E> = E extends EndpointBuilder<any, any, any, any, any, any, any, any, infer TResponses> ? TResponses : never;
+export type ResponsesOf<E> = E extends EndpointBuilder<any, any, any, any, any, any, any, any, infer TResponses, any> ? TResponses : never;
 type HasResponses<E> = keyof ResponsesOf<E> extends never ? false : true;
 /**
  * The union of permitted return values for a handler whose endpoint
@@ -64,7 +69,7 @@ export type AllowedResponseReturn<TResponses extends Record<number, any>> = {
  */
 type HandlerReturn<E> = HasResponses<E> extends true ? AllowedResponseReturn<ResponsesOf<E>> : ResponseType<E> | ActionResult;
 export type Handler<E> = HasKeys<ServiceSchemas<E>> extends true ? (arg: ActionContext<E>, services: Simplify<InferServices<ServiceSchemas<E>>>) => HandlerReturn<E> | Promise<HandlerReturn<E>> : (arg: ActionContext<E>) => HandlerReturn<E> | Promise<HandlerReturn<E>>;
-type AnyEndpoint = EndpointBuilder<any, any, any, any, any, any, any, any, any>;
+type AnyEndpoint = EndpointBuilder<any, any, any, any, any, any, any, any, any, any>;
 type AnySubscriptionBuilder = SubscriptionBuilder<any, any, any, any, any, any, any, any>;
 /**
  * A single handler entry in a {@link HandlerMap}.
@@ -298,6 +303,17 @@ export interface EndpointMetadata {
      * OpenAPI Operation Object.
      */
     readonly callbacks: Record<string, CallbackDefinition> | null;
+    /**
+     * When set, the endpoint accepts `multipart/form-data` uploads.
+     * The configuration controls max file size, allowed MIME types, etc.
+     * @see `EndpointBuilder.upload()`
+     */
+    readonly fileUpload: UploadOptions | null;
+    /**
+     * Cache tags declared via `.clearsCacheTag()`, providing tag-based cache
+     * key computation for the client middleware.
+     */
+    readonly cacheTags: readonly CacheTagDefinition[];
 }
 /**
  * Immutable, fluent builder for HTTP endpoint definitions.
@@ -324,7 +340,37 @@ export interface EndpointMetadata {
 type InferResponsesMap<T extends Record<number, SchemaBuilder<any, any, any, any, any> | null>> = {
     [K in keyof T]: T[K] extends SchemaBuilder<any, any, any, any, any> ? InferType<T[K]> : null;
 };
-export declare class EndpointBuilder<TParams = {}, TBody = undefined, TQuery = {}, THeaders = {}, TServices = {}, TPrincipal = undefined, TRoles extends string = string, TResponse = any, TResponses extends Record<number, any> = {}> {
+/**
+ * A leaf node in a cache-tag property tree — mirrors the shape of the
+ * actual runtime {@link PropertyDescriptor} so the compiler accepts
+ * values selected by the consumer.
+ */
+interface CacheTagPropertyLeaf {
+    readonly [SYMBOL_SCHEMA_PROPERTY_DESCRIPTOR]: {
+        readonly getValue: (obj: Record<string, unknown>) => {
+            readonly value?: unknown;
+            readonly success: boolean;
+        };
+    };
+}
+/** Recursively builds a typed property tree from an inferred object shape. */
+type CacheTagPropertyTree<T> = CacheTagPropertyLeaf & (T extends Record<string, unknown> ? {
+    readonly [K in keyof T]-?: CacheTagPropertyTree<T[K]>;
+} : unknown);
+/**
+ * The typed tree passed to the `.clearsCacheTag(name, selector)` callback.
+ *
+ * `p.params`, `p.query`, and `p.headers` provide IDE completion for
+ * each schema's property names, while `p.body` resolves through the
+ * body schema's `InferType`.
+ */
+type CacheTagSelector<TParams, TBody, TQuery, THeaders> = {
+    readonly params: [keyof TParams] extends [never] ? Record<string, never> : TParams extends Record<string, unknown> ? CacheTagPropertyTree<TParams> : Record<string, never>;
+    readonly body: TBody extends undefined ? undefined : TBody extends SchemaBuilder<any, any, any, any, any> ? CacheTagPropertyTree<InferType<TBody>> : Record<string, never>;
+    readonly query: [keyof TQuery] extends [never] ? Record<string, never> : TQuery extends Record<string, unknown> ? CacheTagPropertyTree<TQuery> : Record<string, never>;
+    readonly headers: [keyof THeaders] extends [never] ? Record<string, never> : THeaders extends Record<string, unknown> ? CacheTagPropertyTree<THeaders> : Record<string, never>;
+};
+export declare class EndpointBuilder<TParams = {}, TBody = undefined, TQuery = {}, THeaders = {}, TServices = {}, TPrincipal = undefined, TRoles extends string = string, TResponse = any, TResponses extends Record<number, any> = {}, TUpload extends boolean = false> {
     #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, responsesSchemas?: Record<number, SchemaBuilder<any, any, any, any, any> | null> | null, example?: unknown | null, examples?: Record<string, {
         summary?: string;
@@ -338,15 +384,15 @@ export declare class EndpointBuilder<TParams = {}, TBody = undefined, TQuery = {
     }> | null, responseHeaderSchema?: ObjectSchemaBuilder<any, any, any, any, any, any, any> | null, externalDocs?: {
         url: string;
         description?: string;
-    } | null, links?: Record<string, LinkDefinition> | null, callbacks?: Record<string, CallbackDefinition> | null);
+    } | null, links?: Record<string, LinkDefinition> | null, callbacks?: Record<string, CallbackDefinition> | null, fileUpload?: UploadOptions | null, cacheTags?: readonly CacheTagDefinition[]);
     /** Define the request body schema. Validation failures return 422 Problem Details. */
-    body<TSchema extends SchemaBuilder<any, any, any, any, any>>(schema: TSchema): EndpointBuilder<TParams, TSchema, TQuery, THeaders, TServices, TPrincipal, TRoles, TResponse, TResponses>;
+    body<TSchema extends SchemaBuilder<any, any, any, any, any>>(schema: TSchema): EndpointBuilder<TParams, TSchema, TQuery, THeaders, TServices, TPrincipal, TRoles, TResponse, TResponses, TUpload>;
     /** 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, TResponses>;
+    query<TSchema extends ObjectSchemaBuilder<any, any, any, any, any, any, any>>(schema: TSchema): EndpointBuilder<TParams, TBody, InferType<TSchema>, THeaders, TServices, TPrincipal, TRoles, TResponse, TResponses, TUpload>;
     /** 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, TResponses>;
+    headers<TSchema extends ObjectSchemaBuilder<any, any, any, any, any, any, any>>(schema: TSchema): EndpointBuilder<TParams, TBody, TQuery, InferType<TSchema>, TServices, TPrincipal, TRoles, TResponse, TResponses, TUpload>;
     /** 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, TResponses>;
+    inject<TSchemas extends Record<string, SchemaBuilder<any, any, any, any, any>>>(schemas: TSchemas): EndpointBuilder<TParams, TBody, TQuery, THeaders, TSchemas, TPrincipal, TRoles, TResponse, TResponses, TUpload>;
     /**
      * Mark this endpoint as requiring authorization.
      *
@@ -356,8 +402,8 @@ export declare class EndpointBuilder<TParams = {}, TBody = undefined, TQuery = {
      *
      * 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, TResponses>;
-    authorize(...roles: TRoles[]): EndpointBuilder<TParams, TBody, TQuery, THeaders, TServices, unknown, TRoles, TResponse, TResponses>;
+    authorize<TSchema extends SchemaBuilder<any, any, any, any, any>>(principalSchema: TSchema, ...roles: TRoles[]): EndpointBuilder<TParams, TBody, TQuery, THeaders, TServices, InferType<TSchema>, TRoles, TResponse, TResponses, TUpload>;
+    authorize(...roles: TRoles[]): EndpointBuilder<TParams, TBody, TQuery, THeaders, TServices, unknown, TRoles, TResponse, TResponses, TUpload>;
     /**
      * Declare the response type for OpenAPI spec generation.
      *
@@ -365,8 +411,8 @@ export declare class EndpointBuilder<TParams = {}, TBody = undefined, TQuery = {
      * - `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, TResponses>;
-    returns<TSchema extends SchemaBuilder<any, any, any, any, any>>(schema: TSchema): EndpointBuilder<TParams, TBody, TQuery, THeaders, TServices, TPrincipal, TRoles, TSchema, TResponses>;
+    returns<T>(): EndpointBuilder<TParams, TBody, TQuery, THeaders, TServices, TPrincipal, TRoles, T, TResponses, TUpload>;
+    returns<TSchema extends SchemaBuilder<any, any, any, any, any>>(schema: TSchema): EndpointBuilder<TParams, TBody, TQuery, THeaders, TServices, TPrincipal, TRoles, TSchema, TResponses, TUpload>;
     /**
      * Declare per-status-code response schemas for OpenAPI generation and
      * handler return-type enforcement.
@@ -389,17 +435,17 @@ export declare class EndpointBuilder<TParams = {}, TBody = undefined, TQuery = {
      * };
      * ```
      */
-    responses<const T extends Record<number, SchemaBuilder<any, any, any, any, any> | null>>(map: T): EndpointBuilder<TParams, TBody, TQuery, THeaders, TServices, TPrincipal, TRoles, TResponse, InferResponsesMap<T>>;
+    responses<const T extends Record<number, SchemaBuilder<any, any, any, any, any> | null>>(map: T): EndpointBuilder<TParams, TBody, TQuery, THeaders, TServices, TPrincipal, TRoles, TResponse, InferResponsesMap<T>, TUpload>;
     /** Short, human-readable summary for OpenAPI operation objects. */
-    summary(text: string): EndpointBuilder<TParams, TBody, TQuery, THeaders, TServices, TPrincipal, TRoles, TResponse, TResponses>;
+    summary(text: string): EndpointBuilder<TParams, TBody, TQuery, THeaders, TServices, TPrincipal, TRoles, TResponse, TResponses, TUpload>;
     /** Longer description for OpenAPI operation objects. Supports Markdown. */
-    description(text: string): EndpointBuilder<TParams, TBody, TQuery, THeaders, TServices, TPrincipal, TRoles, TResponse, TResponses>;
+    description(text: string): EndpointBuilder<TParams, TBody, TQuery, THeaders, TServices, TPrincipal, TRoles, TResponse, TResponses, TUpload>;
     /** OpenAPI tags grouping this operation in generated documentation. */
-    tags(...tags: string[]): EndpointBuilder<TParams, TBody, TQuery, THeaders, TServices, TPrincipal, TRoles, TResponse, TResponses>;
+    tags(...tags: string[]): EndpointBuilder<TParams, TBody, TQuery, THeaders, TServices, TPrincipal, TRoles, TResponse, TResponses, TUpload>;
     /** A unique, stable identifier for this operation in OpenAPI spec. */
-    operationId(id: string): EndpointBuilder<TParams, TBody, TQuery, THeaders, TServices, TPrincipal, TRoles, TResponse, TResponses>;
+    operationId(id: string): EndpointBuilder<TParams, TBody, TQuery, THeaders, TServices, TPrincipal, TRoles, TResponse, TResponses, TUpload>;
     /** Mark this endpoint as deprecated in OpenAPI spec output. */
-    deprecated(): EndpointBuilder<TParams, TBody, TQuery, THeaders, TServices, TPrincipal, TRoles, TResponse, TResponses>;
+    deprecated(): EndpointBuilder<TParams, TBody, TQuery, THeaders, TServices, TPrincipal, TRoles, TResponse, TResponses, TUpload>;
     /**
      * Provide a single example value for the request body.
      *
@@ -408,7 +454,7 @@ export declare class EndpointBuilder<TParams = {}, TBody = undefined, TQuery = {
      *
      * @param value - An example request body value.
      */
-    example(value: TBody): EndpointBuilder<TParams, TBody, TQuery, THeaders, TServices, TPrincipal, TRoles, TResponse, TResponses>;
+    example(value: TBody): EndpointBuilder<TParams, TBody, TQuery, THeaders, TServices, TPrincipal, TRoles, TResponse, TResponses, TUpload>;
     /**
      * Provide named examples for the request body.
      *
@@ -421,7 +467,7 @@ export declare class EndpointBuilder<TParams = {}, TBody = undefined, TQuery = {
         summary?: string;
         description?: string;
         value: TBody;
-    }>): EndpointBuilder<TParams, TBody, TQuery, THeaders, TServices, TPrincipal, TRoles, TResponse, TResponses>;
+    }>): EndpointBuilder<TParams, TBody, TQuery, THeaders, TServices, TPrincipal, TRoles, TResponse, TResponses, TUpload>;
     /**
      * Declare that this endpoint produces a binary file response.
      *
@@ -431,7 +477,41 @@ export declare class EndpointBuilder<TParams = {}, TBody = undefined, TQuery = {
      * @param contentType - MIME type (default: `'application/octet-stream'`).
      * @param description - Optional response description for the spec.
      */
-    producesFile(contentType?: string, description?: string): EndpointBuilder<TParams, TBody, TQuery, THeaders, TServices, TPrincipal, TRoles, TResponse, TResponses>;
+    producesFile(contentType?: string, description?: string): EndpointBuilder<TParams, TBody, TQuery, THeaders, TServices, TPrincipal, TRoles, TResponse, TResponses, TUpload>;
+    /**
+     * Mark this endpoint as accepting `multipart/form-data` file uploads.
+     *
+     * When set, the server parses the request body with a streaming multipart
+     * parser instead of the default JSON deserializer. File fields are made
+     * available to the handler via `arg.files` (a `Record<string, FilePart>`),
+     * while non-file form fields are validated against the body schema and
+     * available via `arg.body`.
+     *
+     * @param options - Upload configuration (max file size, allowed MIME types, etc.).
+     *
+     * @example
+     * ```ts
+     * const UploadAvatar = endpoint
+     *     .post('/api/avatar')
+     *     .upload({ maxFileSize: 2 * 1024 * 1024, allowedMimeTypes: ['image/*'] })
+     *     .authorize(PrincipalSchema)
+     *     .responses({ 200: AvatarSchema });
+     *
+     * const handler: Handler<typeof UploadAvatar> = async ({ files }) => {
+     *     const avatar = files['avatar'];
+     *     // avatar: { filename, mimeType, buffer, size }
+     * };
+     * ```
+     */
+    upload(options?: UploadOptions): EndpointBuilder<TParams, TBody, TQuery, THeaders, TServices, TPrincipal, TRoles, TResponse, TResponses, true>;
+    /**
+     * The full path for this endpoint, combining `basePath` and `pathTemplate`.
+     *
+     * For static routes this is the exact URL path (e.g. `"/todos"`).
+     * For dynamic routes the template placeholders are included
+     * (e.g. `"/todos/:id"`).
+     */
+    get path(): string;
     /** Return an immutable snapshot of this builder's configuration as {@link EndpointMetadata}. */
     introspect(): EndpointMetadata;
     /**
@@ -457,7 +537,7 @@ export declare class EndpointBuilder<TParams = {}, TBody = undefined, TQuery = {
      */
     produces(contentTypes: Record<string, {
         schema?: SchemaBuilder<any, any, any, any, any>;
-    }>): EndpointBuilder<TParams, TBody, TQuery, THeaders, TServices, TPrincipal, TRoles, TResponse, TResponses>;
+    }>): EndpointBuilder<TParams, TBody, TQuery, THeaders, TServices, TPrincipal, TRoles, TResponse, TResponses, TUpload>;
     /**
      * Declare response headers emitted by this endpoint.
      *
@@ -476,7 +556,7 @@ export declare class EndpointBuilder<TParams = {}, TBody = undefined, TQuery = {
      *   }))
      * ```
      */
-    responseHeaders<TSchema extends ObjectSchemaBuilder<any, any, any, any, any, any, any>>(schema: TSchema): EndpointBuilder<TParams, TBody, TQuery, THeaders, TServices, TPrincipal, TRoles, TResponse, TResponses>;
+    responseHeaders<TSchema extends ObjectSchemaBuilder<any, any, any, any, any, any, any>>(schema: TSchema): EndpointBuilder<TParams, TBody, TQuery, THeaders, TServices, TPrincipal, TRoles, TResponse, TResponses, TUpload>;
     /**
      * Link external documentation to this operation.
      *
@@ -485,7 +565,7 @@ export declare class EndpointBuilder<TParams = {}, TBody = undefined, TQuery = {
      * @param url - The URL to the external documentation.
      * @param description - Optional short description of the external docs.
      */
-    externalDocs(url: string, description?: string): EndpointBuilder<TParams, TBody, TQuery, THeaders, TServices, TPrincipal, TRoles, TResponse, TResponses>;
+    externalDocs(url: string, description?: string): EndpointBuilder<TParams, TBody, TQuery, THeaders, TServices, TPrincipal, TRoles, TResponse, TResponses, TUpload>;
     /**
      * Declare response links for OpenAPI spec generation.
      *
@@ -506,7 +586,7 @@ export declare class EndpointBuilder<TParams = {}, TBody = undefined, TQuery = {
      *   })
      * ```
      */
-    links(defs: Record<string, LinkDefinition<TResponse>>): EndpointBuilder<TParams, TBody, TQuery, THeaders, TServices, TPrincipal, TRoles, TResponse, TResponses>;
+    links(defs: Record<string, LinkDefinition<TResponse>>): EndpointBuilder<TParams, TBody, TQuery, THeaders, TServices, TPrincipal, TRoles, TResponse, TResponses, TUpload>;
     /**
      * Declare callbacks for OpenAPI spec generation.
      *
@@ -529,7 +609,51 @@ export declare class EndpointBuilder<TParams = {}, TBody = undefined, TQuery = {
      *   })
      * ```
      */
-    callbacks(defs: Record<string, CallbackDefinition<TBody>>): EndpointBuilder<TParams, TBody, TQuery, THeaders, TServices, TPrincipal, TRoles, TResponse, TResponses>;
+    callbacks(defs: Record<string, CallbackDefinition<TBody>>): EndpointBuilder<TParams, TBody, TQuery, THeaders, TServices, TPrincipal, TRoles, TResponse, TResponses, TUpload>;
+    /**
+     * Declare a cache group for this endpoint.
+     *
+     * Use on GET / query endpoints to group responses into a named cache.
+     * The client-side {@code cacheTags} middleware caches responses keyed
+     * by this tag and flushes matching entries when a mutation calls
+     * {@link clearsCacheTag}.
+     *
+     * @overload Simple tag (no properties — single cache entry).
+     * @overload Tag with property descriptors for fine-grained keys.
+     *
+     * @example
+     * ```ts
+     * // GET — responses cached under "todo" group, keyed by id
+     * endpoint.get('/api/todos/:id')
+     *     .cacheTag('todo', p => ({
+     *         id: p.params.id
+     *     }))
+     * ```
+     */
+    cacheTag(name: string): EndpointBuilder<TParams, TBody, TQuery, THeaders, TServices, TPrincipal, TRoles, TResponse, TResponses>;
+    cacheTag(name: string, selector: (tree: CacheTagSelector<TParams, TBody, TQuery, THeaders>) => Record<string, unknown>): EndpointBuilder<TParams, TBody, TQuery, THeaders, TServices, TPrincipal, TRoles, TResponse, TResponses>;
+    /**
+     * Declare which cache groups are cleared when this mutation succeeds.
+     *
+     * Use on POST / PUT / PATCH / DELETE endpoints. When the mutation
+     * completes, the {@code cacheTags} client middleware invalidates all
+     * cache entries matching the declared tag names (prefix match).
+     *
+     * @overload Simple tag (clears all entries prefixed with the name).
+     * @overload Tag with property descriptors for targeted invalidation.
+     *
+     * @example
+     * ```ts
+     * // PATCH — clears "todo-list" and "todo:id=42" on success
+     * endpoint.patch('/api/todos/:id')
+     *     .clearsCacheTag('todo-list')
+     *     .clearsCacheTag('todo', p => ({
+     *         id: p.params.id
+     *     }))
+     * ```
+     */
+    clearsCacheTag(name: string): EndpointBuilder<TParams, TBody, TQuery, THeaders, TServices, TPrincipal, TRoles, TResponse, TResponses>;
+    clearsCacheTag(name: string, selector: (tree: CacheTagSelector<TParams, TBody, TQuery, THeaders>) => Record<string, unknown>): EndpointBuilder<TParams, TBody, TQuery, THeaders, TServices, TPrincipal, TRoles, TResponse, TResponses>;
 }
 /**
  * Optional OpenAPI metadata fields accepted by `createEndpoint` / `createEndpoints`.
@@ -549,6 +673,12 @@ type ScopedEndpointFactoryMethods<TPrincipal, TRoles extends string = string> =
     delete<TParams = {}>(pathTemplate?: ParseStringSchemaBuilder<TParams, any, any, any, any>): EndpointBuilder<TParams, undefined, {}, {}, {}, TPrincipal, TRoles, any, {}>;
     head<TParams = {}>(pathTemplate?: ParseStringSchemaBuilder<TParams, any, any, any, any>): EndpointBuilder<TParams, undefined, {}, {}, {}, TPrincipal, TRoles, any, {}>;
     options<TParams = {}>(pathTemplate?: ParseStringSchemaBuilder<TParams, any, any, any, any>): EndpointBuilder<TParams, undefined, {}, {}, {}, TPrincipal, TRoles, any, {}>;
+    post<TParams = {}>(pathTemplate?: ParseStringSchemaBuilder<TParams, any, any, any, any>): EndpointBuilder<TParams extends undefined ? {} : TParams, undefined, {}, {}, {}, TPrincipal, TRoles, any, {}>;
+    put<TParams = {}>(pathTemplate?: ParseStringSchemaBuilder<TParams, any, any, any, any>): EndpointBuilder<TParams extends undefined ? {} : TParams, undefined, {}, {}, {}, TPrincipal, TRoles, any, {}>;
+    patch<TParams = {}>(pathTemplate?: ParseStringSchemaBuilder<TParams, any, any, any, any>): EndpointBuilder<TParams extends undefined ? {} : TParams, undefined, {}, {}, {}, TPrincipal, TRoles, any, {}>;
+    delete<TParams = {}>(pathTemplate?: ParseStringSchemaBuilder<TParams, any, any, any, any>): EndpointBuilder<TParams extends undefined ? {} : TParams, undefined, {}, {}, {}, TPrincipal, TRoles, any, {}>;
+    head<TParams = {}>(pathTemplate?: ParseStringSchemaBuilder<TParams, any, any, any, any>): EndpointBuilder<TParams extends undefined ? {} : TParams, undefined, {}, {}, {}, TPrincipal, TRoles, any, {}>;
+    options<TParams = {}>(pathTemplate?: ParseStringSchemaBuilder<TParams, any, any, any, any>): EndpointBuilder<TParams extends undefined ? {} : TParams, undefined, {}, {}, {}, TPrincipal, TRoles, any, {}>;
 };
 export type ScopedEndpointFactory<TRoles extends string = string> = ScopedEndpointFactoryMethods<undefined, TRoles> & {
     /**
@@ -562,13 +692,13 @@ export type ScopedEndpointFactory<TRoles extends string = string> = ScopedEndpoi
     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, any, {}>;
-    post<TParams = {}>(basePath: string, pathTemplate?: ParseStringSchemaBuilder<TParams, any, any, any, any>): EndpointBuilder<TParams, undefined, {}, {}, {}, undefined, TRoles, any, {}>;
-    put<TParams = {}>(basePath: string, pathTemplate?: ParseStringSchemaBuilder<TParams, any, any, any, any>): EndpointBuilder<TParams, undefined, {}, {}, {}, undefined, TRoles, any, {}>;
-    patch<TParams = {}>(basePath: string, pathTemplate?: ParseStringSchemaBuilder<TParams, any, any, any, any>): EndpointBuilder<TParams, undefined, {}, {}, {}, undefined, TRoles, any, {}>;
-    delete<TParams = {}>(basePath: string, pathTemplate?: ParseStringSchemaBuilder<TParams, any, any, any, any>): EndpointBuilder<TParams, undefined, {}, {}, {}, undefined, TRoles, any, {}>;
-    head<TParams = {}>(basePath: string, pathTemplate?: ParseStringSchemaBuilder<TParams, any, any, any, any>): EndpointBuilder<TParams, undefined, {}, {}, {}, undefined, TRoles, any, {}>;
-    options<TParams = {}>(basePath: string, pathTemplate?: ParseStringSchemaBuilder<TParams, any, any, any, any>): EndpointBuilder<TParams, undefined, {}, {}, {}, undefined, TRoles, any, {}>;
+    get<TParams = {}>(basePath: string, pathTemplate?: ParseStringSchemaBuilder<TParams, any, any, any, any>): EndpointBuilder<TParams, undefined, {}, {}, {}, any, TRoles, any, {}>;
+    post<TParams = {}>(basePath: string, pathTemplate?: ParseStringSchemaBuilder<TParams, any, any, any, any>): EndpointBuilder<TParams, undefined, {}, {}, {}, any, TRoles, any, {}>;
+    put<TParams = {}>(basePath: string, pathTemplate?: ParseStringSchemaBuilder<TParams, any, any, any, any>): EndpointBuilder<TParams, undefined, {}, {}, {}, any, TRoles, any, {}>;
+    patch<TParams = {}>(basePath: string, pathTemplate?: ParseStringSchemaBuilder<TParams, any, any, any, any>): EndpointBuilder<TParams, undefined, {}, {}, {}, any, TRoles, any, {}>;
+    delete<TParams = {}>(basePath: string, pathTemplate?: ParseStringSchemaBuilder<TParams, any, any, any, any>): EndpointBuilder<TParams, undefined, {}, {}, {}, any, TRoles, any, {}>;
+    head<TParams = {}>(basePath: string, pathTemplate?: ParseStringSchemaBuilder<TParams, any, any, any, any>): EndpointBuilder<TParams, undefined, {}, {}, {}, any, TRoles, any, {}>;
+    options<TParams = {}>(basePath: string, pathTemplate?: ParseStringSchemaBuilder<TParams, any, any, any, any>): EndpointBuilder<TParams, undefined, {}, {}, {}, any, TRoles, any, {}>;
     resource(basePath: string): ScopedEndpointFactory<TRoles>;
     subscription<TParams = {}>(basePath: string, pathTemplate?: ParseStringSchemaBuilder<TParams, any, any, any, any>): SubscriptionBuilder<TParams, {}, {}, {}, undefined, TRoles>;
 };

package/dist/Server.d.ts

@@ -46,6 +46,7 @@ export interface AuthorizationConfig {
  */
 export declare class ServerBuilder {
     #private;
+    constructor(options?: ServerOptions);
     /**
      * Configure the DI service collection.
      *
@@ -78,6 +79,8 @@ export declare class ServerBuilder {
     /**
      * Enable the `GET /health` endpoint that returns `{ ok: true }` (200).
      * Useful for load balancer and container readiness probes.
+     *
+     * The path is available as {@link HEALTHCHECK_PATH}.
      */
     withHealthcheck(): this;
     /**