@cleverbrush/server 4.4.3 → 5.0.0

package/dist/Endpoint.d.ts

@@ -2,14 +2,16 @@ import type { InferType, ObjectSchemaBuilder, ParseStringSchemaBuilder, Property
 import { SYMBOL_SCHEMA_PROPERTY_DESCRIPTOR } from '@cleverbrush/schema';
 import type { ActionResult, ContentResult, FileResult, JsonResult, NoContentResult, RawResult, RedirectResult, StatusCodeResult, StreamResult } from './ActionResult.js';
 import type { CacheTagDefinition } from './CacheTag.js';
+import type { EndpointOptions, RuntimeEndpointOptions } from './EndpointOptions.js';
 import type { RequestContext } from './RequestContext.js';
 import { type SubscriptionBuilder, type SubscriptionHandlerEntry } from './Subscription.js';
 import type { FilePart, Middleware, RejectedFile, UploadOptions } from './types.js';
+import { type UploadConfiguration, type UploadContract, type UploadFiles, type UploadSchema } from './upload.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, TUpload extends boolean> = {
+type ActionContextParts<TParams, TBody, TQuery, THeaders, TPrincipal, TUpload extends UploadContract> = {
     context: RequestContext;
 } & (HasKeys<TParams> extends true ? {
     params: TParams;
@@ -21,10 +23,12 @@ type ActionContextParts<TParams, TBody, TQuery, THeaders, TPrincipal, TUpload ex
     headers: THeaders;
 } : {}) & (TPrincipal extends undefined ? {} : {
     principal: TPrincipal;
-}) & (TUpload extends true ? {
+}) & (TUpload extends false ? {} : TUpload extends true ? {
     files: Record<string, FilePart>;
     rejectedFiles?: RejectedFile[];
-} : {});
+} : {
+    files: UploadFiles<TUpload>;
+});
 /**
  * The fully-typed argument object passed to endpoint handlers.
  *
@@ -77,10 +81,9 @@ type AnySubscriptionBuilder = SubscriptionBuilder<any, any, any, any, any, any,
  * Either a bare handler function or an object with a `handler` function and
  * optional per-endpoint `middlewares`.
  */
-export type HandlerEntry<E> = Handler<E> | {
+export type HandlerEntry<E> = Handler<E> | ({
     handler: Handler<E>;
-    middlewares?: Middleware[];
-};
+} & EndpointOptions<E>);
 /**
  * A compile-time complete mapping from an endpoint group structure to
  * handler entries. Every endpoint key in every group must have a
@@ -108,6 +111,10 @@ export interface HandlerMapping {
         endpoint: AnyEndpoint;
         handler: (...args: any[]) => any;
         middlewares?: Middleware[];
+        handlerErrorsMapped?: boolean;
+        prepare?: RuntimeEndpointOptions['prepare'];
+        idempotency?: RuntimeEndpointOptions['idempotency'];
+        errors?: RuntimeEndpointOptions['errors'];
     }>;
     /** @internal */
     readonly _subscriptions: ReadonlyArray<{
@@ -308,12 +315,14 @@ export interface EndpointMetadata {
      * The configuration controls max file size, allowed MIME types, etc.
      * @see `EndpointBuilder.upload()`
      */
-    readonly fileUpload: UploadOptions | null;
+    readonly fileUpload: UploadConfiguration | null;
     /**
      * Cache tags declared via `.clearsCacheTag()`, providing tag-based cache
      * key computation for the client middleware.
      */
     readonly cacheTags: readonly CacheTagDefinition[];
+    /** Opt-in to bounded mutation response replay. */
+    readonly idempotent?: boolean;
 }
 /**
  * Immutable, fluent builder for HTTP endpoint definitions.
@@ -370,7 +379,7 @@ type CacheTagSelector<TParams, TBody, TQuery, THeaders> = {
     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> {
+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 UploadContract = 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;
@@ -384,7 +393,13 @@ 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, fileUpload?: UploadOptions | null, cacheTags?: readonly CacheTagDefinition[]);
+    } | null, links?: Record<string, LinkDefinition> | null, callbacks?: Record<string, CallbackDefinition> | null, fileUpload?: UploadConfiguration | null, cacheTags?: readonly CacheTagDefinition[], idempotent?: boolean);
+    /**
+     * Enable optional X-Idempotency-Key replay for this mutation. The server
+     * registration must provide an explicit authorization scope. Retention is
+     * process-local; reusing a key asserts that the input is unchanged.
+     */
+    idempotent(): EndpointBuilder<TParams, TBody, TQuery, THeaders, TServices, TPrincipal, TRoles, TResponse, TResponses, TUpload>;
     /** 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, TUpload>;
     /** Define the query string schema (must be an object schema). Validation failures return 422. */
@@ -491,9 +506,11 @@ export declare class EndpointBuilder<TParams = {}, TBody = undefined, TQuery = {
      *
      * 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`.
+     * available via `arg.files`. A schema of file() / array(file()) fields
+     * infers their names, cardinality and optionality. Without a schema,
+     * files remain a Record<string, FilePart>. Non-file fields use arg.body.
+     * File-only endpoints do not require a body schema. Typed uploads fail
+     * before the handler if their contract is invalid; limits produce 413.
      *
      * @param options - Upload configuration (max file size, allowed MIME types, etc.).
      *
@@ -511,6 +528,7 @@ export declare class EndpointBuilder<TParams = {}, TBody = undefined, TQuery = {
      * };
      * ```
      */
+    upload<S extends UploadSchema>(schema: S, options?: UploadOptions): EndpointBuilder<TParams, TBody, TQuery, THeaders, TServices, TPrincipal, TRoles, TResponse, TResponses, S>;
     upload(options?: UploadOptions): EndpointBuilder<TParams, TBody, TQuery, THeaders, TServices, TPrincipal, TRoles, TResponse, TResponses, true>;
     /**
      * The full path for this endpoint, combining `basePath` and `pathTemplate`.
@@ -622,7 +640,7 @@ export declare class EndpointBuilder<TParams = {}, TBody = undefined, TQuery = {
      * 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
+     * The client-side `cacheTags` middleware caches responses keyed
      * by this tag and flushes matching entries when a mutation calls
      * {@link clearsCacheTag}.
      *
@@ -644,7 +662,7 @@ export declare class EndpointBuilder<TParams = {}, TBody = undefined, TQuery = {
      * 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
+     * completes, the `cacheTags` client middleware invalidates all
      * cache entries matching the declared tag names (prefix match).
      *
      * @overload Simple tag (clears all entries prefixed with the name).
@@ -652,7 +670,7 @@ export declare class EndpointBuilder<TParams = {}, TBody = undefined, TQuery = {
      *
      * @example
      * ```ts
-     * // PATCH — clears "todo-list" and "todo:id=42" on success
+     * // PATCH — clears "todo-list" / "todo" names and their computed ct2 keys
      * endpoint.patch('/api/todos/:id')
      *     .clearsCacheTag('todo-list')
      *     .clearsCacheTag('todo', p => ({

package/dist/EndpointOptions.d.ts

@@ -0,0 +1,31 @@
+import type { ActionContext, Handler, ResponsesOf } from './Endpoint.js';
+import type { ErrorMap, ErrorResponsesOf } from './ErrorMap.js';
+import type { Middleware } from './types.js';
+/** Identity components are serialized without ambiguous string concatenation. */
+export type IdempotencyScope = string | readonly (string | number)[];
+/** Per-endpoint, process-local replay limits. */
+export interface EndpointIdempotencyLimits {
+    ttl?: number;
+    maxEntries?: number;
+    maxResponseBytes?: number;
+}
+/** Server-only callbacks, inferred from the endpoint's validated request and DI. */
+export type EndpointOptions<E> = {
+    middlewares?: Middleware[];
+    /** Runs on every request, including replays; return the request used by scope and handler. */
+    prepare?: (...args: Parameters<Handler<E>>) => ActionContext<E> | Promise<ActionContext<E>>;
+    idempotency?: EndpointIdempotencyLimits & {
+        scope: (...args: Parameters<Handler<E>>) => IdempotencyScope | Promise<IdempotencyScope>;
+    };
+    errors?: keyof ResponsesOf<E> extends never ? never : ErrorMap<ErrorResponsesOf<E>>;
+};
+/** @internal Erased callback types retained through registration/composition. */
+export interface RuntimeEndpointOptions {
+    /** @internal Handler invocation already owns its error policy. */
+    handlerErrorsMapped?: boolean;
+    prepare?: (...args: any[]) => any;
+    idempotency?: EndpointIdempotencyLimits & {
+        scope: (...args: any[]) => IdempotencyScope | Promise<IdempotencyScope>;
+    };
+    errors?: ErrorMap<any, any>;
+}

package/dist/ErrorMap.d.ts

@@ -0,0 +1,90 @@
+import { type ContentResult, type FileResult, JsonResult, NoContentResult, type RawResult, type RedirectResult, StatusCodeResult, type StreamResult } from './ActionResult.js';
+import type { EndpointBuilder, Handler, ResponsesOf } from './Endpoint.js';
+/** Explicit, contract-checkable responses supported by error policies. */
+export type ErrorResponse = JsonResult<number, unknown> | NoContentResult | StatusCodeResult<number>;
+/** The declared JSON and bodyless responses of an HTTP endpoint. */
+export type ErrorResponsesOf<E> = {
+    [K in keyof ResponsesOf<E> & number]: ResponsesOf<E>[K] extends null ? K extends 204 ? NoContentResult : StatusCodeResult<K> : JsonResult<K, ResponsesOf<E>[K]>;
+}[keyof ResponsesOf<E> & number];
+type ErrorConstructor<E extends Error> = abstract new (...args: any[]) => E;
+declare const responseTypes: unique symbol;
+type ResponseSignature<R> = R extends FileResult | StreamResult | ContentResult | RedirectResult | RawResult ? {
+    kind: 'unsupported';
+} : R extends JsonResult<infer S, infer B> ? {
+    kind: 'json';
+    status: S;
+    body: B;
+} : R extends StatusCodeResult<infer S> ? {
+    kind: 'empty';
+    status: S;
+} : R extends NoContentResult ? {
+    kind: 'empty';
+    status: 204;
+} : never;
+type Rule = {
+    matches: (error: unknown) => boolean;
+    translate: (error: any) => ErrorResponse | Promise<ErrorResponse>;
+};
+/**
+ * Immutable, ordered exception translators. Create one with {@link errorMap}.
+ *
+ * Policies retain their exact response union until attached to an endpoint.
+ * They do not change that endpoint's responses, catch infrastructure errors,
+ * or automatically expose exception messages.
+ *
+ * @typeParam R - Union of all responses produced by this policy.
+ */
+export declare class ErrorMap<R extends ErrorResponse = never, Signature = ResponseSignature<R>> {
+    #private;
+    /** @internal Retains status/body discrimination across exported policies. */
+    readonly [responseTypes]: Signature;
+    /** @internal Use {@link errorMap}. */
+    constructor(rules?: readonly Rule[]);
+    /**
+     * Return a new policy with a translator appended. First matching rule wins.
+     * Put subclass rules before base-class rules. Translators may be async;
+     * translator failures propagate without re-entering this policy.
+     *
+     * @param errorType - Error constructor matched using `instanceof`.
+     * @param translate - Application-owned conversion to an explicit response.
+     */
+    on<E extends Error, T extends ErrorResponse>(errorType: ErrorConstructor<E>, translate: (error: E) => T | Promise<T>): ErrorMap<R | T, Signature | ResponseSignature<T>>;
+    /**
+     * Translate a recognized exception or rethrow the original value unchanged.
+     * Usually invoked by {@link withErrors}, not directly by an application.
+     */
+    translate(error: unknown): Promise<R>;
+}
+/**
+ * Create an empty, immutable error policy. Unknown exceptions are rethrown.
+ *
+ * @example
+ * ```ts
+ * const errors = errorMap().on(MissingItemError, () =>
+ *     ActionResult.notFound({ message: 'Item not found' })
+ * );
+ * ```
+ */
+export declare function errorMap(): ErrorMap<never>;
+/**
+ * Wrap only a handler's invocation in an endpoint-checked error policy.
+ *
+ * Requires explicit `.responses()` declarations. Every possible translated
+ * status/body must fit the endpoint; file/raw/stream escape hatches are not
+ * accepted. Request and injected-service types are unchanged. Authentication,
+ * validation, middleware, DI and response serialization remain outside this
+ * wrapper and use the server's normal error handling.
+ *
+ * @param endpoint - Configured HTTP endpoint, the sole source of handler types.
+ * @param policy - Reusable policy compatible with the endpoint's responses.
+ * @param handler - Named or inline handler to wrap.
+ * @returns A handler suitable for `handle`, `mapHandlers`, or implementation scopes.
+ */
+export declare function withErrors<E extends EndpointBuilder<any, any, any, any, any, any, any, any, any, any>>(endpoint: E, policy: keyof ResponsesOf<NoInfer<E>> extends never ? never : ErrorMap<ErrorResponsesOf<NoInfer<E>>>, handler: Handler<NoInfer<E>>): Handler<E>;
+/** @internal Shared registration validation. */
+export declare function validateErrorMap(endpoint: {
+    introspect(): {
+        responsesSchemas: unknown;
+    };
+}): void;
+export {};

package/dist/Implementation.d.ts

@@ -0,0 +1,193 @@
+import type { InferType, SchemaBuilder } from '@cleverbrush/schema';
+import type { ApiContract, ApiGroup } from './contract.js';
+import { type EndpointBuilder, type Handler, type HandlerMapping } from './Endpoint.js';
+import type { EndpointOptions, RuntimeEndpointOptions } from './EndpointOptions.js';
+import { type SubscriptionBuilder, type SubscriptionHandlerEntry } from './Subscription.js';
+import type { Middleware } from './types.js';
+type AnySchema = SchemaBuilder<any, any, any, any, any>;
+type Services = Record<string, AnySchema>;
+type AnyEndpoint = EndpointBuilder<any, any, any, any, any, any, any, any, any, any>;
+type AnySubscription = SubscriptionBuilder<any, any, any, any, any, any, any, any>;
+type Definition = AnyEndpoint | AnySubscription;
+type Merge<A, B> = {
+    -readonly [K in keyof Required<A> as K extends keyof B ? never : K]: A[K];
+} & {
+    -readonly [K in keyof Required<B>]: B[K];
+};
+/** Server-only enrichment shared by every operation in a scope. */
+export interface ImplementationDefaults {
+    /** Merged with contract services; later same-name bindings win. */
+    readonly inject?: Services;
+    /** Explicitly require authentication, retaining any existing role requirements. */
+    readonly authorize?: AnySchema;
+    /** Replace inherited documentation tags when supplied. */
+    readonly tags?: readonly string[];
+}
+/** Per-operation overrides. Wire schemas and cache metadata are not configurable here. */
+export interface ImplementationOperationOptions extends ImplementationDefaults {
+    /** Short documentation summary. */
+    readonly summary?: string;
+    /** Longer documentation description. */
+    readonly description?: string;
+    /** Stable OpenAPI/AsyncAPI operation identifier. */
+    readonly operationId?: string;
+    /** Mark deprecated; this cannot clear an inherited deprecation. */
+    readonly deprecated?: true;
+}
+/** Typed defaults and operation-specific server settings for a contract group. */
+export interface ImplementationGroupOptions<G extends ApiGroup> extends ImplementationDefaults {
+    /** Keys must belong to the selected group. */
+    readonly operations?: {
+        readonly [K in keyof G]?: ImplementationOperationOptions;
+    };
+}
+type Injected<O> = O extends {
+    readonly inject: infer I extends Services;
+} ? I : {};
+type Principal<P, O> = O extends {
+    readonly authorize: infer S extends AnySchema;
+} ? InferType<S> : P;
+type OperationOptions<O, K extends PropertyKey> = O extends {
+    readonly operations: infer Operations;
+} ? K extends keyof Operations ? Operations[K] : {} : {};
+type Configured<E, Defaults, Options> = E extends EndpointBuilder<infer P, infer B, infer Q, infer H, infer S, infer A, infer Roles, infer R, infer Rs, infer U> ? EndpointBuilder<P, B, Q, H, Merge<Merge<S, Injected<Defaults>>, Injected<Options>>, Principal<Principal<A, Defaults>, Options>, Roles, R, Rs, U> : E extends SubscriptionBuilder<infer P, infer Q, infer H, infer S, infer A, infer Roles, infer I, infer O> ? SubscriptionBuilder<P, Q, H, Merge<Merge<S, Injected<Defaults>>, Injected<Options>>, Principal<Principal<A, Defaults>, Options>, Roles, I, O> : never;
+type ConfiguredGroup<G extends ApiGroup, O> = {
+    readonly [K in keyof G]: Configured<G[K], O, OperationOptions<O, K>>;
+};
+/** Handler binding accepted by an implementation scope. Policies apply only to HTTP handlers. */
+export type ImplementationHandlerEntry<E> = E extends AnySubscription ? SubscriptionHandlerEntry<E> & {
+    errors?: never;
+} : E extends AnyEndpoint ? Handler<E> | ({
+    handler: Handler<E>;
+} & EndpointOptions<E>) : never;
+/** Complete, endpoint-specific handler bindings for one configured scope. */
+export type ImplementationHandlers<G extends ApiGroup> = {
+    [K in keyof G]: ImplementationHandlerEntry<G[K]>;
+};
+type ExactKeys<Given, Expected> = Record<Exclude<keyof Given, keyof Expected>, never>;
+type ExactOperations<O, G> = O extends {
+    readonly operations: infer Ops;
+} ? {
+    readonly operations: ExactKeys<Ops, G>;
+} : unknown;
+type Entry = RuntimeEndpointOptions & {
+    readonly group: string;
+    readonly name: string;
+    readonly source: Definition;
+    readonly endpoint: Definition;
+    readonly handler: (...args: any[]) => any;
+    readonly middlewares?: Middleware[];
+};
+declare const moduleContract: unique symbol;
+declare const moduleEntries: unique symbol;
+/**
+ * Exportable, immutable set of bound operations. Its type retains the original
+ * contract slice, not just an erased array of registrations.
+ * Obtain modules with `scope.withHandlers()` or `implement(api).use(...)`.
+ */
+export declare class ImplementationModule<C extends ApiContract> {
+    #private;
+    /** @internal Compile-time contract coverage. */
+    readonly [moduleContract]: C;
+    /** @internal Construct modules through an implementation scope. */
+    constructor(entries: readonly Entry[]);
+    /** @internal */
+    [moduleEntries](): readonly Entry[];
+}
+/**
+ * Configured, unbound operations from a single contract group.
+ * Export the scope from a configuration-only module, then use
+ * `Handler<typeof scope.endpoints.operation>` in separate handler files.
+ * No handler imports or registration side effects are needed here.
+ */
+export declare class ImplementationScope<G extends string, Source extends ApiGroup, Endpoints extends ApiGroup> {
+    #private;
+    /** @internal Use `implement(api).group(...)`. */
+    constructor(group: G, source: Source, endpoints: Endpoints);
+    /** Configured endpoint builders: the source of handler request, DI and response types. */
+    get endpoints(): Endpoints;
+    /**
+     * Select operations for a smaller module without losing source identity.
+     * The composition root still checks coverage of the full contract.
+     */
+    pick<const K extends keyof Source & keyof Endpoints & string>(...names: K[]): ImplementationScope<G, Pick<Source, K>, Pick<Endpoints, K>>;
+    /**
+     * Bind exactly one handler for every operation in this scope.
+     * Named handlers and inline functions receive the same endpoint typing.
+     * Optional descriptors attach middleware and HTTP error policies.
+     */
+    withHandlers<const H extends ImplementationHandlers<Endpoints>>(handlers: H & ExactKeys<H, Endpoints>): ImplementationModule<{
+        [K in G]: Source;
+    }>;
+}
+type ContractOf<M> = M extends ImplementationModule<infer C> ? C : never;
+type MergeContracts<A extends ApiContract, B extends ApiContract> = {
+    -readonly [G in keyof Required<A & B>]: G extends keyof A ? G extends keyof B ? A[G] & B[G] : A[G] : G extends keyof B ? B[G] : never;
+};
+type Joined<Bound extends ApiContract, Modules extends readonly ImplementationModule<any>[]> = Modules extends readonly [
+    infer Head,
+    ...infer Tail extends readonly ImplementationModule<any>[]
+] ? Joined<MergeContracts<Bound, ContractOf<Head>>, Tail> : Bound;
+type Missing<C, B> = {
+    [G in keyof C & string]: `${G}.${Exclude<keyof C[G], G extends keyof B ? keyof B[G] : never> & string}`;
+}[keyof C & string];
+type Overlap<A, B> = {
+    [G in keyof A & keyof B & string]: `${G}.${keyof A[G] & keyof B[G] & string}`;
+}[keyof A & keyof B & string];
+type Incompatible<C, S> = {
+    [G in keyof S & string]: G extends keyof C ? {
+        [K in keyof S[G] & string]: K extends keyof C[G] ? S[G][K] extends C[G][K] ? never : `${G}.${K}` : `${G}.${K}`;
+    }[keyof S[G] & string] : `${G}.${keyof S[G] & string}`;
+}[keyof S & string];
+type CheckModules<C, B extends ApiContract, M extends readonly ImplementationModule<any>[]> = number extends M['length'] ? {
+    readonly implementationError: 'Use a tuple of modules with known operation keys';
+} : M extends readonly [
+    infer Head,
+    ...infer Tail extends readonly ImplementationModule<any>[]
+] ? [
+    Overlap<B, ContractOf<Head>> | Incompatible<C, ContractOf<Head>>
+] extends [never] ? CheckModules<C, MergeContracts<B, ContractOf<Head>>, Tail> : {
+    readonly duplicateOrIncompatibleOperations: Overlap<B, ContractOf<Head>> | Incompatible<C, ContractOf<Head>>;
+} : unknown;
+/**
+ * Immutable composition root bound to a shared contract. Compose exported
+ * feature modules with `use`, then pass `complete()` to `server.handleAll`.
+ * Partial roots are themselves modules and can be composed in larger roots.
+ */
+export declare class ApiImplementation<C extends ApiContract, Bound extends ApiContract = {}> extends ImplementationModule<Bound> {
+    #private;
+    /** @internal Use {@link implement}. */
+    constructor(contract: C, entries?: readonly Entry[]);
+    /**
+     * Create an unbound scope; does not register handlers or change this root.
+     * Services merge contract → group → operation. Only explicitly supplied
+     * documentation fields override inherited values. Authorization retains roles.
+     */
+    group<K extends keyof C & string, const O extends ImplementationGroupOptions<C[K]> = {}>(name: K, options?: O & ExactOperations<O, C[K]>): ImplementationScope<K, C[K], ConfiguredGroup<C[K], O>>;
+    /**
+     * Compose modules without erasing their operation coverage. Rejects duplicate
+     * and incompatible bindings, including runtime source-identity mismatches.
+     */
+    use<const M extends readonly ImplementationModule<any>[]>(...modules: M & CheckModules<C, Bound, M>): ApiImplementation<C, Joined<Bound, M>>;
+    /**
+     * Finalize only when every operation in the original contract is covered.
+     * Rechecks coverage at runtime for JavaScript callers and erased types.
+     * Returns the existing registration format; the server pipeline is unchanged.
+     */
+    complete(this: [Missing<C, Bound>] extends [never] ? ApiImplementation<C, Bound> : {
+        readonly missingOperations: Missing<C, Bound>;
+    }): HandlerMapping;
+}
+/**
+ * Start an immutable implementation bound to a shared API contract.
+ *
+ * @param contract - Complete shared contract, or an intentional audience slice.
+ * @example
+ * ```ts
+ * const todos = implement(api).group('todos', { inject: { db: DbToken } });
+ * const module = todos.withHandlers({ list: listHandler, create: createHandler });
+ * server.handleAll(implement(api).use(module).complete());
+ * ```
+ */
+export declare function implement<C extends ApiContract>(contract: C): ApiImplementation<C>;
+export {};

package/dist/RequestContext.d.ts

@@ -7,7 +7,7 @@ import type { IServiceProvider } from '@cleverbrush/di';
  */
 export declare const IRequestContext: import("@cleverbrush/schema").ExtendedObject<{
     method: import("@cleverbrush/schema").ExtendedString<string>;
-    url: import("@cleverbrush/schema").ExtendedString<string>;
+    url: import("@cleverbrush/schema").AnySchemaBuilder<true, false, URL, false, {}, URL>;
     pathParams: import("@cleverbrush/schema").ExtendedRecord<import("@cleverbrush/schema").ExtendedString<string>, import("@cleverbrush/schema").ExtendedString<string>>;
     queryParams: import("@cleverbrush/schema").ExtendedRecord<import("@cleverbrush/schema").ExtendedString<string>, import("@cleverbrush/schema").ExtendedString<string>>;
     headers: import("@cleverbrush/schema").ExtendedRecord<import("@cleverbrush/schema").ExtendedString<string>, import("@cleverbrush/schema").ExtendedString<string>>;
@@ -60,7 +60,7 @@ export declare class RequestContext {
     /** The DI service provider scoped to this request. Set by the server before invoking the handler. */
     get services(): IServiceProvider | undefined;
     set services(value: IServiceProvider);
-    /** Read and buffer the raw request body. Result is cached after the first call. */
+    /** Read once; concurrent readers share the same result or failure. */
     body(): Promise<Buffer>;
     /** Read, buffer, and JSON-parse the request body. Result is cached after the first call. */
     json(): Promise<unknown>;

package/dist/Server.d.ts

@@ -2,7 +2,9 @@ import type { AuthenticationScheme } from '@cleverbrush/auth';
 import { PolicyBuilder } from '@cleverbrush/auth';
 import { ServiceCollection, type ServiceProvider } from '@cleverbrush/di';
 import { ContentNegotiator } from './ContentNegotiator.js';
+import { type ServerCorsOptions } from './Cors.js';
 import type { EndpointBuilder, Handler, HandlerMapping } from './Endpoint.js';
+import type { EndpointOptions } from './EndpointOptions.js';
 import { Router } from './Router.js';
 import type { ContentTypeHandler, EndpointRegistration, Middleware, ServerBatchingOptions, ServerOptions, SubscriptionRegistration } from './types.js';
 import type { WebhookDefinition } from './Webhook.js';
@@ -62,10 +64,18 @@ export declare class ServerBuilder {
      */
     services(configureFn: (svc: ServiceCollection) => void): this;
     /**
-     * Add a global middleware that runs for every request.
-     * Middleware is executed in the order it is added.
+     * Add middleware to the matched-request pipeline after authentication.
+     * Middleware is executed in the order it is added. CORS short-circuits
+     * and unmatched routes do not enter this pipeline.
      */
     use(middleware: Middleware): this;
+    /**
+     * Enable server-wide CORS before routing and authentication.
+     * Accepted preflights return 204 without running ordinary middleware.
+     * Requests with disallowed origins return 403 before handlers run.
+     * Configuration is validated and copied when the server starts listening.
+     */
+    useCors(options: ServerCorsOptions): this;
     /**
      * Register an additional content type handler for content negotiation.
      * JSON is registered by default.
@@ -73,8 +83,8 @@ export declare class ServerBuilder {
     contentType(handler: ContentTypeHandler): this;
     /**
      * Enable authentication with one or more schemes.
-     * Registers a global middleware that authenticates every request and
-     * sets `ctx.principal`.
+     * Registers middleware that authenticates protected requests and sets
+     * `ctx.principal`. CORS preflights are handled before this middleware.
      */
     useAuthentication(config: AuthenticationConfig): this;
     /**
@@ -88,7 +98,7 @@ 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}.
+     * The path is available as `HEALTHCHECK_PATH`.
      */
     withHealthcheck(): this;
     /**
@@ -120,9 +130,7 @@ export declare class ServerBuilder {
      * @param handler - The typed handler function.
      * @param options - Optional per-endpoint middleware.
      */
-    handle<E extends EndpointBuilder<any, any, any, any, any, any, any, any, any>>(endpointDef: E, handler: Handler<E>, options?: {
-        middlewares?: Middleware[];
-    }): this;
+    handle<E extends EndpointBuilder<any, any, any, any, any, any, any, any, any>>(endpointDef: E, handler: Handler<E>, options?: EndpointOptions<E>): this;
     /**
      * Register all endpoints from a {@link HandlerMapping} created by
      * {@link mapHandlers}. This is the bulk equivalent of calling
@@ -171,7 +179,7 @@ export declare class ServerBuilder {
 }
 export declare class Server {
     #private;
-    constructor(router: Router, serviceProvider: ServiceProvider, contentNegotiator: ContentNegotiator, globalMiddlewares: Middleware[], healthcheck?: boolean, hasSubscriptions?: boolean, batchConfig?: ServerBatchingOptions | null, maxBodySize?: number);
+    constructor(router: Router, serviceProvider: ServiceProvider, contentNegotiator: ContentNegotiator, globalMiddlewares: Middleware[], healthcheck?: boolean, hasSubscriptions?: boolean, batchConfig?: ServerBatchingOptions | null, maxBodySize?: number, corsOptions?: ServerCorsOptions);
     /**
      * Start listening. Called internally by `ServerBuilder.listen()` after
      * the server is fully configured.

package/dist/VirtualHttp.d.ts

@@ -81,6 +81,8 @@ export declare class VirtualServerResponse extends Writable {
      * Mirrors `ServerResponse.getHeader()`.
      */
     getHeader(name: string): string | undefined;
+    /** Return a snapshot of response headers, matching ServerResponse. */
+    getHeaders(): Record<string, string>;
     /**
      * Captures the body and signals the end of the response.
      *

package/dist/cacheKey.d.ts

@@ -0,0 +1,17 @@
+import type { CacheTagDefinition } from './CacheTag.js';
+type CacheRoot = Parameters<CacheTagDefinition['properties'][string]['getValue']>[0];
+/**
+ * Compute a versioned, deterministic key from a tag and selected request values.
+ *
+ * Format: `ct2:` followed by JSON `[tagName, [[property, encodedValue], ...]]`.
+ * Properties and object keys are sorted by code units. Values are type-tagged;
+ * Dates retain millisecond precision. Missing/undefined selected properties are
+ * omitted. Even property-free tags use this format; base invalidation labels
+ * remain the original names. All cache writers/invalidators must use the same
+ * version and retire old entries when upgrading.
+ *
+ * @throws TypeError for cyclic values, invalid dates, functions, symbols,
+ * accessor properties, or objects other than arrays, dates and plain objects.
+ */
+export declare function computeCacheKey(tag: CacheTagDefinition, root: CacheRoot): string;
+export {};

package/dist/chunk-UZECVBRI.js

@@ -0,0 +1,2 @@
+function f(n,e){if(n===null)return["null"];switch(typeof n){case"undefined":return["undefined"];case"string":case"boolean":return[typeof n,n];case"number":return["number",Object.is(n,-0)?"-0":String(n)];case"bigint":return["bigint",String(n)];case"object":{if(e.has(n))throw new TypeError("Cache tag values must not contain cycles.");if(n instanceof Date){if(!Number.isFinite(n.getTime()))throw new TypeError("Cache tag dates must be valid.");return["date",n.toISOString()]}let t=Object.getPrototypeOf(n);if(!Array.isArray(n)&&t!==Object.prototype&&t!==null)throw new TypeError("Unsupported cache tag object.");if(Object.getOwnPropertySymbols(n).length>0)throw new TypeError("Cache tag values cannot have symbol keys.");e.add(n);try{if(Array.isArray(n)){if(Object.keys(n).some(a=>!/^(0|[1-9]\d*)$/.test(a)||Number(a)>=n.length))throw new TypeError("Cache tag arrays cannot have named properties.");return["array",Array.from({length:n.length},(a,s)=>{let i=Object.getOwnPropertyDescriptor(n,s);if(i&&!("value"in i))throw new TypeError("Cache tag values cannot contain getters.");return f(i?.value,e)})]}return["object",Object.keys(n).sort().map(a=>{let s=Object.getOwnPropertyDescriptor(n,a);if(!("value"in s))throw new TypeError("Cache tag values cannot contain getters.");return[a,f(s.value,e)]})]}finally{e.delete(n)}}default:throw new TypeError(`Unsupported cache tag value: ${typeof n}.`)}}function b(n,e){let t=[];for(let a of Object.keys(n.properties).sort()){let s=n.properties[a].getValue(e);s.success&&s.value!==void 0&&t.push([a,f(s.value,new Set)])}return`ct2:${JSON.stringify([n.name,t])}`}import{object as E,SYMBOL_HAS_PROPERTIES as x,SYMBOL_SCHEMA_PROPERTY_DESCRIPTOR as R}from"@cleverbrush/schema";function w(n){let e={};if(n.paramsSchema){let a=n.paramsSchema;typeof a.introspect=="function"&&a.introspect().objectSchema?e.params=a.introspect().objectSchema:a[x]===!0&&(e.params=a)}if(n.bodySchema){let a=n.bodySchema;(a[x]===!0||typeof a.introspect=="function")&&(e.body=a)}n.querySchema&&(e.query=n.querySchema),n.headerSchema&&(e.headers=n.headerSchema);let t=E(e);return E.getPropertiesFor(t)}function L(n){return n==null||typeof n!="object"?!1:typeof n[R]=="object"&&n[R]!==null}function O(n,e){let t={};for(let[a,s]of Object.entries(e)){if(!L(s))throw new Error(`Cache tag "${n}": property "${a}" is not a valid PropertyDescriptor. Make sure you select a leaf property from the tree (e.g. p.query.id, not p.query).`);let i=s[R];t[a]={getValue:r=>i.getValue(r)}}return{name:n,properties:t}}var P=Symbol.for("cleverbrush.tracked");function N(n,e){return{[P]:!0,id:n,data:e}}function se(n){return n!==null&&typeof n=="object"&&P in n&&n[P]===!0}var p=class n{#a;#s;#n;#i;#r;#o;#l;#t;#d;#h;#c;#p;#u;#y;constructor(e,t="/",a=null,s=null,i=null,r=null,y=null,d=null,o=null,h=null,c=[],m=null,g=!1,S=null){this.#a=e,this.#s=t,this.#n=a,this.#i=s,this.#r=i,this.#o=r,this.#l=y,this.#t=d,this.#d=o,this.#h=h,this.#c=c,this.#p=m,this.#u=g,this.#y=S}#e(e){return new n(e.basePath??this.#a,e.pathTemplate??this.#s,e.incomingSchema!==void 0?e.incomingSchema:this.#n,e.outgoingSchema!==void 0?e.outgoingSchema:this.#i,e.querySchema!==void 0?e.querySchema:this.#r,e.headerSchema!==void 0?e.headerSchema:this.#o,e.serviceSchemas!==void 0?e.serviceSchemas:this.#l,e.authRoles!==void 0?e.authRoles:this.#t,e.summary!==void 0?e.summary:this.#d,e.description!==void 0?e.description:this.#h,e.tags??this.#c,e.operationId!==void 0?e.operationId:this.#p,e.deprecated??this.#u,e.externalDocs!==void 0?e.externalDocs:this.#y)}incoming(e){return this.#e({incomingSchema:e})}outgoing(e){return this.#e({outgoingSchema:e})}query(e){return this.#e({querySchema:e})}headers(e){return this.#e({headerSchema:e})}inject(e){return this.#e({serviceSchemas:e})}authorize(...e){let t;e.length>0&&typeof e[0]=="object"&&e[0]!==null&&"introspect"in e[0]?t=e.slice(1):t=e;let a=this.#t?[...this.#t,...t]:t;return this.#e({authRoles:a})}public(){return this.#e({authRoles:null})}summary(e){return this.#e({summary:e})}description(e){return this.#e({description:e})}tags(...e){return this.#e({tags:e})}operationId(e){return this.#e({operationId:e})}deprecated(){return this.#e({deprecated:!0})}externalDocs(e,t){return this.#e({externalDocs:{url:e,description:t}})}introspect(){return{protocol:"subscription",basePath:this.#a,pathTemplate:this.#s,incomingSchema:this.#n,outgoingSchema:this.#i,querySchema:this.#r,headerSchema:this.#o,serviceSchemas:this.#l,authRoles:this.#t,summary:this.#d,description:this.#h,tags:this.#c,operationId:this.#p,deprecated:this.#u,externalDocs:this.#y}}};function k(n,e){return new p(n,e??"/")}function C(n){return n instanceof p}import{any as $}from"@cleverbrush/schema";function Y(){return $().hasType().addValidator(n=>{let e=n!==null&&typeof n=="object"&&typeof n.filename=="string"&&typeof n.mimeType=="string"&&n.buffer instanceof Uint8Array&&n.size===n.buffer.byteLength;return{valid:e,errors:e?[]:[{message:"Expected an uploaded file"}]}}).withExtension("uploadFile",!0)}function H(n,e){if(!n)return;for(let s of["maxFileSize","maxFileCount","maxFieldSize","maxFieldCount","maxFieldNameSize","maxPartCount"]){let i=n[s];if(i!==void 0&&(!Number.isSafeInteger(i)||i<1))throw new TypeError(`${s} must be a positive safe integer`)}if(!n.schema)return;let t=n.schema.introspect();if(t.type!=="object"||t.isNullable||!t.isRequired||t.acceptUnknownProps)throw new TypeError("Upload schemas must be required, closed objects");let a=e?.introspect();if(a&&a.type!=="object")throw new TypeError("Multipart body schemas must be objects");for(let[s,i]of Object.entries(t.properties)){let r=i.introspect(),y=r.type==="array"?r.elementSchema?.introspect():r;if(!y?.extensions?.uploadFile||r.isNullable||y.isNullable||r.hasDefault||y.hasDefault||r.type==="array"&&!y.isRequired)throw new TypeError(`Upload field "${s}" must be file() or array(file())`);if(Object.hasOwn(a?.properties??{},s))throw new TypeError(`Multipart text and file fields overlap: ${s}`)}}function he(n,e){let t=[],a=[];for(let s of Object.keys(n)){let i=n[s],r=e[s];for(let y of Object.keys(i)){let d=i[y],o=r[y],h=typeof o=="function"?o:o.handler,c=typeof o=="function"?void 0:o.middlewares;C(d)?a.push({endpoint:d,handler:h,middlewares:c}):t.push({endpoint:d,handler:h,middlewares:c,handlerErrorsMapped:typeof o=="function"?!1:o.handlerErrorsMapped,prepare:typeof o=="function"?void 0:o.prepare,idempotency:typeof o=="function"?void 0:o.idempotency,errors:typeof o=="function"?void 0:o.errors})}}return{_entries:t,_subscriptions:a}}var T=class n{#a;#s;#n;#i;#r;#o;#l;#t;#d;#h;#c;#p;#u;#y;#e;#m;#g;#S;#f;#R;#P;#B;#b;#E;#T;#x;constructor(e,t,a,s,i,r,y=null,d=null,o=null,h=null,c=[],m=null,g=!1,S=null,v=null,U=null,I=null,D=null,Q=null,K=null,M=null,F=null,q=null,B=null,z=[],G=!1){H(B,s),this.#a=e,this.#s=t,this.#n=a,this.#i=s,this.#r=i,this.#o=r,this.#l=y,this.#t=d,this.#d=o,this.#h=h,this.#c=c,this.#p=m,this.#u=g,this.#y=S,this.#e=v,this.#m=U,this.#g=I,this.#S=D,this.#f=Q,this.#R=K,this.#P=M,this.#B=F,this.#b=q,this.#E=B,this.#T=z,this.#x=G}idempotent(){if(!["POST","PUT","PATCH","DELETE"].includes(this.#a.toUpperCase()))throw new TypeError("Idempotency requires a mutation endpoint");return new n(this.#a,this.#s,this.#n,this.#i,this.#r,this.#o,this.#l,this.#t,this.#d,this.#h,this.#c,this.#p,this.#u,this.#y,this.#e,this.#m,this.#g,this.#S,this.#f,this.#R,this.#P,this.#B,this.#b,this.#E,this.#T,!0)}body(e){return new n(this.#a,this.#s,this.#n,e,this.#r,this.#o,this.#l,this.#t,this.#d,this.#h,this.#c,this.#p,this.#u,this.#y,this.#e,this.#m,this.#g,this.#S,this.#f,this.#R,this.#P,this.#B,this.#b,this.#E,this.#T,this.#x)}query(e){return new n(this.#a,this.#s,this.#n,this.#i,e,this.#o,this.#l,this.#t,this.#d,this.#h,this.#c,this.#p,this.#u,this.#y,this.#e,this.#m,this.#g,this.#S,this.#f,this.#R,this.#P,this.#B,this.#b,this.#E,this.#T,this.#x)}headers(e){return new n(this.#a,this.#s,this.#n,this.#i,this.#r,e,this.#l,this.#t,this.#d,this.#h,this.#c,this.#p,this.#u,this.#y,this.#e,this.#m,this.#g,this.#S,this.#f,this.#R,this.#P,this.#B,this.#b,this.#E,this.#T,this.#x)}inject(e){return new n(this.#a,this.#s,this.#n,this.#i,this.#r,this.#o,e,this.#t,this.#d,this.#h,this.#c,this.#p,this.#u,this.#y,this.#e,this.#m,this.#g,this.#S,this.#f,this.#R,this.#P,this.#B,this.#b,this.#E,this.#T,this.#x)}authorize(...e){let t;e.length>0&&typeof e[0]=="object"&&e[0]!==null&&"introspect"in e[0]?t=e.slice(1):t=e;let a=this.#t?[...this.#t,...t]:t;return new n(this.#a,this.#s,this.#n,this.#i,this.#r,this.#o,this.#l,a,this.#d,this.#h,this.#c,this.#p,this.#u,this.#y,this.#e,this.#m,this.#g,this.#S,this.#f,this.#R,this.#P,this.#B,this.#b,this.#E,this.#T,this.#x)}public(){return new n(this.#a,this.#s,this.#n,this.#i,this.#r,this.#o,this.#l,null,this.#d,this.#h,this.#c,this.#p,this.#u,this.#y,this.#e,this.#m,this.#g,this.#S,this.#f,this.#R,this.#P,this.#B,this.#b,this.#E,this.#T,this.#x)}returns(e){let t=e!=null&&typeof e=="object"&&"introspect"in e?e:null;return new n(this.#a,this.#s,this.#n,this.#i,this.#r,this.#o,this.#l,this.#t,this.#d,this.#h,this.#c,this.#p,this.#u,t??this.#y,this.#e,this.#m,this.#g,this.#S,this.#f,this.#R,this.#P,this.#B,this.#b,this.#E,this.#T,this.#x)}responses(e){return new n(this.#a,this.#s,this.#n,this.#i,this.#r,this.#o,this.#l,this.#t,this.#d,this.#h,this.#c,this.#p,this.#u,this.#y,e,this.#m,this.#g,this.#S,this.#f,this.#R,this.#P,this.#B,this.#b,this.#E,this.#T,this.#x)}summary(e){return new n(this.#a,this.#s,this.#n,this.#i,this.#r,this.#o,this.#l,this.#t,e,this.#h,this.#c,this.#p,this.#u,this.#y,this.#e,this.#m,this.#g,this.#S,this.#f,this.#R,this.#P,this.#B,this.#b,this.#E,this.#T,this.#x)}description(e){return new n(this.#a,this.#s,this.#n,this.#i,this.#r,this.#o,this.#l,this.#t,this.#d,e,this.#c,this.#p,this.#u,this.#y,this.#e,this.#m,this.#g,this.#S,this.#f,this.#R,this.#P,this.#B,this.#b,this.#E,this.#T,this.#x)}tags(...e){return new n(this.#a,this.#s,this.#n,this.#i,this.#r,this.#o,this.#l,this.#t,this.#d,this.#h,e,this.#p,this.#u,this.#y,this.#e,this.#m,this.#g,this.#S,this.#f,this.#R,this.#P,this.#B,this.#b,this.#E,this.#T,this.#x)}operationId(e){return new n(this.#a,this.#s,this.#n,this.#i,this.#r,this.#o,this.#l,this.#t,this.#d,this.#h,this.#c,e,this.#u,this.#y,this.#e,this.#m,this.#g,this.#S,this.#f,this.#R,this.#P,this.#B,this.#b,this.#E,this.#T,this.#x)}deprecated(){return new n(this.#a,this.#s,this.#n,this.#i,this.#r,this.#o,this.#l,this.#t,this.#d,this.#h,this.#c,this.#p,!0,this.#y,this.#e,this.#m,this.#g,this.#S,this.#f,this.#R,this.#P,this.#B,this.#b,this.#E,this.#T,this.#x)}example(e){return new n(this.#a,this.#s,this.#n,this.#i,this.#r,this.#o,this.#l,this.#t,this.#d,this.#h,this.#c,this.#p,this.#u,this.#y,this.#e,e,this.#g,this.#S,this.#f,this.#R,this.#P,this.#B,this.#b,this.#E,this.#T,this.#x)}examples(e){return new n(this.#a,this.#s,this.#n,this.#i,this.#r,this.#o,this.#l,this.#t,this.#d,this.#h,this.#c,this.#p,this.#u,this.#y,this.#e,this.#m,e,this.#S,this.#f,this.#R,this.#P,this.#B,this.#b,this.#E,this.#T,this.#x)}producesFile(e,t){return new n(this.#a,this.#s,this.#n,this.#i,this.#r,this.#o,this.#l,this.#t,this.#d,this.#h,this.#c,this.#p,this.#u,this.#y,this.#e,this.#m,this.#g,{contentType:e,description:t},this.#f,this.#R,this.#P,this.#B,this.#b,this.#E,this.#T,this.#x)}upload(e,t){let a=e&&"introspect"in e?e:void 0,s=a?t:e;return new n(this.#a,this.#s,this.#n,this.#i,this.#r,this.#o,this.#l,this.#t,this.#d,this.#h,this.#c,this.#p,this.#u,this.#y,this.#e,this.#m,this.#g,this.#S,this.#f,this.#R,this.#P,this.#B,this.#b,{...s,allowedMimeTypes:s?.allowedMimeTypes?[...s.allowedMimeTypes]:void 0,maxFileSize:s?.maxFileSize??10*1024*1024,maxFileCount:s?.maxFileCount??10,schema:a},this.#T,this.#x)}get path(){let e=this.#s,t=this.#n,a;if(typeof t=="string")a=t;else{let{literals:s,segments:i}=t.introspect().templateDefinition,r="";for(let y=0;y<i.length;y++)r+=s[y]+`:${i[y].path}`;r+=s[i.length]??"",a=r}return a==="/"?e||"/":e+a}introspect(){return{method:this.#a,basePath:this.#s,pathTemplate:this.#n,bodySchema:this.#i,querySchema:this.#r,headerSchema:this.#o,serviceSchemas:this.#l,authRoles:this.#t,summary:this.#d,description:this.#h,tags:this.#c,operationId:this.#p,deprecated:this.#u,responseSchema:this.#y,responsesSchemas:this.#e,example:this.#m,examples:this.#g,producesFile:this.#S,produces:this.#f,responseHeaderSchema:this.#R,externalDocs:this.#P,links:this.#B,callbacks:this.#b,fileUpload:this.#E,cacheTags:this.#T,idempotent:this.#x}}produces(e){return new n(this.#a,this.#s,this.#n,this.#i,this.#r,this.#o,this.#l,this.#t,this.#d,this.#h,this.#c,this.#p,this.#u,this.#y,this.#e,this.#m,this.#g,this.#S,e,this.#R,this.#P,this.#B,this.#b,this.#E,this.#T,this.#x)}responseHeaders(e){return new n(this.#a,this.#s,this.#n,this.#i,this.#r,this.#o,this.#l,this.#t,this.#d,this.#h,this.#c,this.#p,this.#u,this.#y,this.#e,this.#m,this.#g,this.#S,this.#f,e,this.#P,this.#B,this.#b,this.#E,this.#T,this.#x)}externalDocs(e,t){return new n(this.#a,this.#s,this.#n,this.#i,this.#r,this.#o,this.#l,this.#t,this.#d,this.#h,this.#c,this.#p,this.#u,this.#y,this.#e,this.#m,this.#g,this.#S,this.#f,this.#R,{url:e,description:t},this.#B,this.#b,this.#E,this.#T,this.#x)}links(e){return new n(this.#a,this.#s,this.#n,this.#i,this.#r,this.#o,this.#l,this.#t,this.#d,this.#h,this.#c,this.#p,this.#u,this.#y,this.#e,this.#m,this.#g,this.#S,this.#f,this.#R,this.#P,e,this.#b,this.#E,this.#T,this.#x)}callbacks(e){return new n(this.#a,this.#s,this.#n,this.#i,this.#r,this.#o,this.#l,this.#t,this.#d,this.#h,this.#c,this.#p,this.#u,this.#y,this.#e,this.#m,this.#g,this.#S,this.#f,this.#R,this.#P,this.#B,e,this.#E,this.#T,this.#x)}cacheTag(e,t){return this.clearsCacheTag(e,t)}clearsCacheTag(e,t){if(!t)return new n(this.#a,this.#s,this.#n,this.#i,this.#r,this.#o,this.#l,this.#t,this.#d,this.#h,this.#c,this.#p,this.#u,this.#y,this.#e,this.#m,this.#g,this.#S,this.#f,this.#R,this.#P,this.#B,this.#b,this.#E,[...this.#T,{name:e,properties:{}}],this.#x);let a=J(this.#n),s=w({paramsSchema:a,bodySchema:this.#i,querySchema:this.#r,headerSchema:this.#o}),i=t(s);if(typeof i!="object"||i===null)throw new Error(`Cache tag "${e}": selector must return an object with property descriptors (e.g. { id: p.query.id }).`);let r=O(e,i);return new n(this.#a,this.#s,this.#n,this.#i,this.#r,this.#o,this.#l,this.#t,this.#d,this.#h,this.#c,this.#p,this.#u,this.#y,this.#e,this.#m,this.#g,this.#S,this.#f,this.#R,this.#P,this.#B,this.#b,this.#E,[...this.#T,r],this.#x)}};function l(n,e,t,a,s){return new T(n,e,t??"/",null,null,null,null,a??null,s?.summary??null,s?.description??null,s?.tags??[],s?.operationId??null,s?.deprecated??!1,null,null,null,null,null,null,null)}function u(n,e){return{get:t=>l("GET",n,t,e),post:t=>l("POST",n,t,e),put:t=>l("PUT",n,t,e),patch:t=>l("PATCH",n,t,e),delete:t=>l("DELETE",n,t,e),head:t=>l("HEAD",n,t,e),options:t=>l("OPTIONS",n,t,e),public:()=>u(n,null)}}function V(n){return{...u(n,null),authorize(...e){let t;return e.length>0&&typeof e[0]=="object"&&e[0]!==null&&"introspect"in e[0]?t=e.slice(1):t=e,u(n,t)},public(){return u(n,null)}}}function J(n){if(n&&typeof n!="string"&&typeof n.introspect=="function"){let e=n.introspect();if(e.objectSchema)return e.objectSchema}return null}function W(n){return j}var j={get:(n,e)=>l("GET",n,e),post:(n,e)=>l("POST",n,e),put:(n,e)=>l("PUT",n,e),patch:(n,e)=>l("PATCH",n,e),delete:(n,e)=>l("DELETE",n,e),head:(n,e)=>l("HEAD",n,e),options:(n,e)=>l("OPTIONS",n,e),resource:V,subscription:(n,e)=>k(n,e)};import{object as X,parseString as Z}from"@cleverbrush/schema";function A(n){let e=X(n);return((t,...a)=>Z(e,s=>s(t,...a)))}function _(n,...e){return n!=null&&Array.isArray(n.raw)?A({})(n):A(n??{})}function Te(n){for(let e of Object.values(n))Object.freeze(e);return Object.freeze(n)}function me(n,e){let t={};for(let a of Object.keys(n))t[a]={...n[a]};for(let a of Object.keys(e))Object.hasOwn(t,a)?t[a]={...t[a],...e[a]}:t[a]={...e[a]};for(let a of Object.values(t))Object.freeze(a);return Object.freeze(t)}function ge(n,...e){let t={};for(let a of e)t[a]=n[a],Object.freeze(t[a]);return Object.freeze(t)}function Se(n,...e){let t=new Set(e),a={};for(let s of Object.keys(n))t.has(s)||(a[s]=n[s],Object.freeze(a[s]));return Object.freeze(a)}export{b as a,w as b,O as c,N as d,se as e,p as f,C as g,Y as h,he as i,T as j,W as k,j as l,_ as m,Te as n,me as o,ge as p,Se as q};
+//# sourceMappingURL=chunk-UZECVBRI.js.map