@theokit/http 0.4.0

package/dist/index.d.ts

@@ -0,0 +1,1047 @@
+import { ZodTypeAny, z } from 'zod';
+import { D as DiContainer, M as MiddlewareConsumerImpl } from './middleware-consumer-ljxK1fU_.js';
+export { a as MiddlewareConfigProxy, b as MiddlewareFn, N as NestMiddleware, R as ResolvedMiddleware, m as middlewareMatchesPath, r as resolveOrNew, c as runMiddleware } from './middleware-consumer-ljxK1fU_.js';
+import { S as ServerHandle } from './types-CGthbcon.js';
+export { ReadinessCheck, TheoApp, TheoAppOptions } from './app.js';
+
+interface ControllerOptions {
+    host?: string;
+}
+interface ControllerMeta {
+    prefix: string;
+    host?: string;
+}
+/**
+ * Class decorator that declares a route-prefix scope.
+ * Equivalent to NestJS's @Controller('prefix').
+ */
+declare function Controller(prefix?: string, opts?: ControllerOptions): ClassDecorator;
+
+type HttpVerb = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'OPTIONS' | 'HEAD' | 'ALL';
+interface RouteMethodEntry {
+    verb: HttpVerb;
+    path: string;
+    propertyKey: string | symbol;
+}
+declare const Get: (path?: string) => MethodDecorator;
+declare const Post: (path?: string) => MethodDecorator;
+declare const Put: (path?: string) => MethodDecorator;
+declare const Patch: (path?: string) => MethodDecorator;
+declare const Delete: (path?: string) => MethodDecorator;
+declare const Options: (path?: string) => MethodDecorator;
+declare const Head: (path?: string) => MethodDecorator;
+declare const All: (path?: string) => MethodDecorator;
+
+type ParamSource = 'req' | 'res' | 'body' | 'param' | 'query' | 'headers' | 'session' | 'ip' | 'host';
+interface ParamEntry {
+    source: ParamSource;
+    key?: string;
+    index: number;
+    passthrough?: boolean;
+    /** Explicit Zod schema — when set, bypasses design:paramtypes + DTO resolution.
+     *  Preferred path: `@Body(zMySchema)` works without emitDecoratorMetadata. */
+    schema?: ZodTypeAny;
+}
+declare const Req: (keyOrSchema?: string | ZodTypeAny) => ParameterDecorator;
+declare const Body: (keyOrSchema?: string | ZodTypeAny) => ParameterDecorator;
+declare const Param: (keyOrSchema?: string | ZodTypeAny) => ParameterDecorator;
+declare const Query: (keyOrSchema?: string | ZodTypeAny) => ParameterDecorator;
+declare const Headers: (keyOrSchema?: string | ZodTypeAny) => ParameterDecorator;
+declare const Session: (keyOrSchema?: string | ZodTypeAny) => ParameterDecorator;
+declare const Ip: (keyOrSchema?: string | ZodTypeAny) => ParameterDecorator;
+declare const HostParam: (keyOrSchema?: string | ZodTypeAny) => ParameterDecorator;
+declare function Res(opts?: {
+    passthrough?: boolean;
+}): ParameterDecorator;
+
+declare function HttpCode(status: number): MethodDecorator;
+declare function Header(name: string, value: string): MethodDecorator;
+interface RedirectMeta {
+    url: string;
+    status: number;
+}
+declare function Redirect(url: string, status?: number): MethodDecorator;
+
+declare function UseGuards(...guards: Function[]): ClassDecorator & MethodDecorator;
+declare function UseInterceptors(...interceptors: Function[]): ClassDecorator & MethodDecorator;
+declare function UseFilters(...filters: Function[]): ClassDecorator & MethodDecorator;
+/** @Catch(ExceptionType, ...) — marks which exception types an ExceptionFilter handles.
+ *  Empty args = catch-all filter. */
+declare function Catch(...exceptions: Function[]): ClassDecorator;
+
+/**
+ * @SetMetadata + Reflector — NestJS-style custom metadata for guards.
+ *
+ * Enables role-based auth pattern:
+ *   const Roles = createDecorator<string[]>()
+ *   @Roles(['admin'])  →  guard reads via reflector.get(Roles, handler)
+ */
+
+/** Unique key type for type-safe metadata decorators. */
+type MetadataKey<T> = symbol & {
+    __type?: T;
+};
+declare function createDecorator<T>(): (value: T) => MethodDecorator & ClassDecorator;
+/**
+ * Low-level @SetMetadata decorator — attaches arbitrary metadata.
+ * NestJS equivalent: `@SetMetadata(key, value)`.
+ *
+ * Prefer `createDecorator<T>()` for type-safe metadata.
+ */
+declare function SetMetadata<T>(metaKey: string | symbol, value: T): MethodDecorator & ClassDecorator;
+/**
+ * Reflector — reads metadata set by createDecorator or @SetMetadata.
+ * NestJS-compatible Reflector with getAllAndOverride/getAllAndMerge.
+ * HTTP-only per ADR D1.
+ */
+declare class Reflector {
+    /**
+     * Read metadata set by a typed decorator created via createDecorator<T>().
+     *
+     * @example
+     * ```ts
+     * const Roles = createDecorator<string[]>()
+     * const reflector = new Reflector()
+     * const roles = reflector.get(Roles, handlerFn) // string[] | undefined
+     * ```
+     */
+    get<T>(decorator: (value: T) => MethodDecorator & ClassDecorator, target: Function, propertyKey?: string | symbol): T | undefined;
+    /**
+     * Read metadata set by @SetMetadata(key, value).
+     */
+    getByKey<T>(key: string | symbol, target: Function, propertyKey?: string | symbol): T | undefined;
+    /**
+     * Read metadata checking method-level first, then class-level.
+     * Returns the first non-undefined value found.
+     *
+     * NestJS equivalent: `reflector.getAllAndOverride(ROLES_KEY, [context.getHandler(), context.getClass()])`
+     *
+     * @example
+     * ```ts
+     * const Roles = createDecorator<string[]>()
+     * // In a guard:
+     * const roles = reflector.getAllAndOverride(Roles, context.getClass(), context.getMethodName())
+     * // Checks method-level @Roles first, falls back to class-level @Roles
+     * ```
+     */
+    getAllAndOverride<T>(decorator: (value: T) => MethodDecorator & ClassDecorator, target: Function, propertyKey?: string | symbol): T | undefined;
+    /**
+     * Read metadata checking method-level first, then class-level, by raw key.
+     * Returns the first non-undefined value found.
+     */
+    getAllAndOverrideByKey<T>(key: string | symbol, target: Function, propertyKey?: string | symbol): T | undefined;
+    /**
+     * Read metadata from both method-level and class-level, merging arrays.
+     * Returns all found values as a flat array.
+     *
+     * NestJS equivalent: `reflector.getAllAndMerge(ROLES_KEY, [context.getHandler(), context.getClass()])`
+     *
+     * @example
+     * ```ts
+     * const Tags = createDecorator<string[]>()
+     *
+     * @Tags(['api'])
+     * @Controller('cats')
+     * class CatsCtrl {
+     *   @Tags(['read'])
+     *   @Get()
+     *   findAll() {}
+     * }
+     *
+     * reflector.getAllAndMerge(Tags, CatsCtrl, 'findAll')
+     * // → ['read', 'api'] (method + class merged)
+     * ```
+     */
+    getAllAndMerge<T>(decorator: (value: T) => MethodDecorator & ClassDecorator, target: Function, propertyKey?: string | symbol): T extends (infer U)[] ? U[] : T[];
+}
+
+interface ThrottleOptions {
+    /** Maximum requests within the TTL window. */
+    limit: number;
+    /** Time-to-live in milliseconds. */
+    ttl: number;
+    /** Optional throttle set name (for multiple throttler definitions). */
+    name?: string;
+}
+/**
+ * Override the global rate limit for a controller or specific route.
+ * NestJS equivalent: `@Throttle({ default: { limit, ttl } })`.
+ */
+declare function Throttle(options: ThrottleOptions): ClassDecorator & MethodDecorator;
+/**
+ * Skip rate limiting for a controller or specific route.
+ * NestJS equivalent: `@SkipThrottle()`.
+ *
+ * @param skip — defaults to `true`. Pass `false` to re-enable on a
+ * specific route inside a skipped controller.
+ */
+declare function SkipThrottle(skip?: boolean): ClassDecorator & MethodDecorator;
+/**
+ * Read throttle metadata for a given class or method.
+ * Used by the rate-limit plugin to resolve per-route overrides.
+ */
+declare function getThrottleOptions(target: Function, propertyKey?: string | symbol): ThrottleOptions | undefined;
+/**
+ * Check if throttling is skipped for a given class or method.
+ */
+declare function isThrottleSkipped(target: Function, propertyKey?: string | symbol): boolean;
+
+/**
+ * Global Symbol-keyed metadata namespace constants for @theokit/http.
+ *
+ * Uses Symbol.for() (global Symbol registry) instead of Symbol() (local) because
+ * the SWC loader imports controller files as separate module instances. With local
+ * Symbols, the decorator-set metadata keys would be different Symbol instances from
+ * the keys used by walkControllerMetadata — making metadata lookup silently fail.
+ *
+ * Symbol.for() ensures the SAME Symbol instance across module boundaries, which is
+ * exactly how reflect-metadata keys should work in a multi-module decorator system.
+ */
+declare const CONTROLLER_PREFIX: unique symbol;
+declare const ROUTE_METHODS: unique symbol;
+declare const ROUTE_PARAMS: unique symbol;
+declare const ROUTE_STATUS: unique symbol;
+declare const ROUTE_HEADERS: unique symbol;
+declare const ROUTE_REDIRECT: unique symbol;
+declare const USE_GUARDS: unique symbol;
+declare const USE_INTERCEPTORS: unique symbol;
+declare const USE_FILTERS: unique symbol;
+declare const CATCH_EXCEPTIONS: unique symbol;
+
+/**
+ * Typed facade over Reflect.defineMetadata / Reflect.getMetadata.
+ * Centralizes all reflect-metadata calls so decorators + bridge
+ * never call Reflect.* directly (single import point for the polyfill).
+ */
+declare function setMeta<T>(key: symbol, target: object, value: T, propertyKey?: string | symbol): void;
+declare function getMeta<T>(key: symbol, target: object, propertyKey?: string | symbol): T | undefined;
+
+/**
+ * ExecutionContext — Web Standard Request-based context passed to guards.
+ *
+ * Per ADR D460: the pipeline operates on Web Standard Request/Response.
+ * node:http types live ONLY in the runtime adapter (runtime/node.ts).
+ *
+ * Guards access request headers via request.headers.get('x-role'),
+ * NOT via req.headers['x-role'].
+ */
+/**
+ * Execution context available in guards during request processing.
+ * Uses Web Standard Request (works on Node, Bun, Deno, CF Workers).
+ */
+interface ExecutionContext {
+    /** The Web Standard Request object. */
+    getRequest(): Request;
+    /** Parsed URL (convenience — avoids re-parsing). */
+    getUrl(): URL;
+    /** The controller class constructor. */
+    getClass(): Function;
+    /** The handler method name (property key on the controller). */
+    getMethodName(): string | symbol;
+}
+/**
+ * Interface for guard classes (bound via @UseGuards).
+ *
+ * @example
+ * ```ts
+ * class RolesGuard implements CanActivate {
+ *   canActivate(context: ExecutionContext): boolean {
+ *     const request = context.getRequest()
+ *     const role = request.headers.get('x-role')
+ *     return role === 'admin'
+ *   }
+ * }
+ * ```
+ */
+interface CanActivate {
+    canActivate(context: ExecutionContext): boolean | Promise<boolean>;
+}
+/** Create an ExecutionContext from a Web Standard Request. */
+declare function createExecutionContext(request: Request, controllerClass: Function, methodName: string | symbol): ExecutionContext;
+
+/** Interface for exception filter classes (bound via @UseFilters). */
+interface ExceptionFilter {
+    catch(exception: unknown, host: ArgumentsHost): Response | Promise<Response>;
+}
+/** ArgumentsHost — Web Standard. */
+interface ArgumentsHost {
+    getRequest(): Request;
+}
+/**
+ * Run exception filters and return an error Response.
+ * Returns the filter's Response or a built-in fallback.
+ */
+declare function runExceptionFilters(exception: unknown, filters: Function[], request: Request, container?: DiContainer): Promise<Response>;
+
+/**
+ * Resolves a Zod schema from a DTO class via the `static schema` convention (Pattern D2).
+ * Returns undefined when the class doesn't carry a compatible schema.
+ */
+declare function resolveDtoSchema(dtoClass: unknown): ZodTypeAny | undefined;
+
+/**
+ * Configuration error thrown by the bridge when decorator setup is incomplete.
+ * Carries actionable messages pointing consumers to the migration guide.
+ */
+declare class HttpDecoratorsConfigError extends Error {
+    readonly name = "HttpDecoratorsConfigError";
+    constructor(message: string);
+}
+
+/**
+ * Interceptor execution engine — onion-model chain runner.
+ *
+ * Per Pattern D3: "@UseInterceptors both translate to defineMiddleware wraps".
+ * Interceptors wrap the handler call (NOT body parsing — EC-1) and can
+ * transform the response or short-circuit by not calling next().
+ *
+ * Execution order follows NestJS convention:
+ *   middleware → guards → interceptors → handler
+ * Interceptor composition: class-level FIRST, then method-level (EC-9).
+ */
+
+/**
+ * Interceptor interface — Web Standard Request.
+ * `next()` wraps ONLY the handler call — body parsing happens before.
+ */
+interface Interceptor {
+    intercept(request: Request, next: () => Promise<unknown>): Promise<unknown>;
+}
+/**
+ * Run the interceptor chain using the onion model.
+ * Outermost interceptor (first in array) wraps all inner ones.
+ */
+declare function runInterceptors(interceptors: Function[], handler: () => Promise<unknown>, request: Request, container?: DiContainer): Promise<unknown>;
+
+interface WalkResult {
+    verb: HttpVerb;
+    fullPath: string;
+    propertyKey: string | symbol;
+    bodySchema?: ZodTypeAny;
+    querySchema?: ZodTypeAny;
+    paramsSchema?: ZodTypeAny;
+    paramEntries: ParamEntry[];
+    status?: number;
+    headers: [string, string][];
+    redirect?: RedirectMeta;
+    guards: Function[];
+    interceptors: Function[];
+    filters: Function[];
+}
+/**
+ * Normalize a joined path: strip doubles, trim trailing, ensure leading.
+ * (EC-3)
+ */
+declare function joinPath(prefix: string, path: string): string;
+/**
+ * Walk all decorator metadata on a controller class and produce
+ * a structured list of route descriptors. Memoized per class via WeakMap.
+ */
+declare function walkControllerMetadata(ControllerClass: Function): WalkResult[];
+
+interface RouteRegistration {
+    verb: HttpVerb;
+    fullPath: string;
+    walkResult: WalkResult;
+}
+/**
+ * Low-level API: walks decorator metadata per controller class and returns
+ * structured route descriptors. Used internally by the Vite plugin (ADR D7)
+ * and available to advanced consumers who don't use Vite.
+ *
+ * EC-5: deduplicates by class reference; warns on duplicates.
+ */
+declare function registerControllers(controllers: Function[]): RouteRegistration[];
+
+/**
+ * Creates a real HTTP server from decorated controller classes.
+ * Uses Web Standard Request/Response internally; Node adapter at the boundary.
+ */
+interface CreateDecoratorServerOptions {
+    controllers: Function[];
+    container?: DiContainer;
+    configure?: (consumer: MiddlewareConsumerImpl) => void;
+}
+declare function createDecoratorServer(controllersOrOpts: Function[] | CreateDecoratorServerOptions): ServerHandle;
+
+/**
+ * HttpException hierarchy for @theokit/http.
+ *
+ * Per ADR D2: response shape {error: {code, message, statusCode}} matches
+ * existing guard (401) and validation (422) format.
+ */
+interface HttpExceptionOptions {
+    cause?: Error;
+    description?: string;
+}
+declare class HttpException extends Error {
+    readonly statusCode: number;
+    readonly code: string;
+    readonly description?: string;
+    constructor(message: string, statusCode: number, options?: HttpExceptionOptions);
+    toJSON(): {
+        error: {
+            description?: string | undefined;
+            code: string;
+            message: string;
+            statusCode: number;
+        };
+    };
+}
+declare const BadRequestException_base: {
+    new (message?: string, options?: HttpExceptionOptions): {
+        readonly statusCode: number;
+        readonly code: string;
+        readonly description?: string;
+        toJSON(): {
+            error: {
+                description?: string | undefined;
+                code: string;
+                message: string;
+                statusCode: number;
+            };
+        };
+        name: string;
+        message: string;
+        stack?: string;
+        cause?: unknown;
+    };
+    isError(error: unknown): error is Error;
+    captureStackTrace(targetObject: object, constructorOpt?: Function): void;
+    prepareStackTrace(err: Error, stackTraces: NodeJS.CallSite[]): any;
+    stackTraceLimit: number;
+};
+declare class BadRequestException extends BadRequestException_base {
+}
+declare const UnauthorizedException_base: {
+    new (message?: string, options?: HttpExceptionOptions): {
+        readonly statusCode: number;
+        readonly code: string;
+        readonly description?: string;
+        toJSON(): {
+            error: {
+                description?: string | undefined;
+                code: string;
+                message: string;
+                statusCode: number;
+            };
+        };
+        name: string;
+        message: string;
+        stack?: string;
+        cause?: unknown;
+    };
+    isError(error: unknown): error is Error;
+    captureStackTrace(targetObject: object, constructorOpt?: Function): void;
+    prepareStackTrace(err: Error, stackTraces: NodeJS.CallSite[]): any;
+    stackTraceLimit: number;
+};
+declare class UnauthorizedException extends UnauthorizedException_base {
+}
+declare const ForbiddenException_base: {
+    new (message?: string, options?: HttpExceptionOptions): {
+        readonly statusCode: number;
+        readonly code: string;
+        readonly description?: string;
+        toJSON(): {
+            error: {
+                description?: string | undefined;
+                code: string;
+                message: string;
+                statusCode: number;
+            };
+        };
+        name: string;
+        message: string;
+        stack?: string;
+        cause?: unknown;
+    };
+    isError(error: unknown): error is Error;
+    captureStackTrace(targetObject: object, constructorOpt?: Function): void;
+    prepareStackTrace(err: Error, stackTraces: NodeJS.CallSite[]): any;
+    stackTraceLimit: number;
+};
+declare class ForbiddenException extends ForbiddenException_base {
+}
+declare const NotFoundException_base: {
+    new (message?: string, options?: HttpExceptionOptions): {
+        readonly statusCode: number;
+        readonly code: string;
+        readonly description?: string;
+        toJSON(): {
+            error: {
+                description?: string | undefined;
+                code: string;
+                message: string;
+                statusCode: number;
+            };
+        };
+        name: string;
+        message: string;
+        stack?: string;
+        cause?: unknown;
+    };
+    isError(error: unknown): error is Error;
+    captureStackTrace(targetObject: object, constructorOpt?: Function): void;
+    prepareStackTrace(err: Error, stackTraces: NodeJS.CallSite[]): any;
+    stackTraceLimit: number;
+};
+declare class NotFoundException extends NotFoundException_base {
+}
+declare const MethodNotAllowedException_base: {
+    new (message?: string, options?: HttpExceptionOptions): {
+        readonly statusCode: number;
+        readonly code: string;
+        readonly description?: string;
+        toJSON(): {
+            error: {
+                description?: string | undefined;
+                code: string;
+                message: string;
+                statusCode: number;
+            };
+        };
+        name: string;
+        message: string;
+        stack?: string;
+        cause?: unknown;
+    };
+    isError(error: unknown): error is Error;
+    captureStackTrace(targetObject: object, constructorOpt?: Function): void;
+    prepareStackTrace(err: Error, stackTraces: NodeJS.CallSite[]): any;
+    stackTraceLimit: number;
+};
+declare class MethodNotAllowedException extends MethodNotAllowedException_base {
+}
+declare const NotAcceptableException_base: {
+    new (message?: string, options?: HttpExceptionOptions): {
+        readonly statusCode: number;
+        readonly code: string;
+        readonly description?: string;
+        toJSON(): {
+            error: {
+                description?: string | undefined;
+                code: string;
+                message: string;
+                statusCode: number;
+            };
+        };
+        name: string;
+        message: string;
+        stack?: string;
+        cause?: unknown;
+    };
+    isError(error: unknown): error is Error;
+    captureStackTrace(targetObject: object, constructorOpt?: Function): void;
+    prepareStackTrace(err: Error, stackTraces: NodeJS.CallSite[]): any;
+    stackTraceLimit: number;
+};
+declare class NotAcceptableException extends NotAcceptableException_base {
+}
+declare const RequestTimeoutException_base: {
+    new (message?: string, options?: HttpExceptionOptions): {
+        readonly statusCode: number;
+        readonly code: string;
+        readonly description?: string;
+        toJSON(): {
+            error: {
+                description?: string | undefined;
+                code: string;
+                message: string;
+                statusCode: number;
+            };
+        };
+        name: string;
+        message: string;
+        stack?: string;
+        cause?: unknown;
+    };
+    isError(error: unknown): error is Error;
+    captureStackTrace(targetObject: object, constructorOpt?: Function): void;
+    prepareStackTrace(err: Error, stackTraces: NodeJS.CallSite[]): any;
+    stackTraceLimit: number;
+};
+declare class RequestTimeoutException extends RequestTimeoutException_base {
+}
+declare const ConflictException_base: {
+    new (message?: string, options?: HttpExceptionOptions): {
+        readonly statusCode: number;
+        readonly code: string;
+        readonly description?: string;
+        toJSON(): {
+            error: {
+                description?: string | undefined;
+                code: string;
+                message: string;
+                statusCode: number;
+            };
+        };
+        name: string;
+        message: string;
+        stack?: string;
+        cause?: unknown;
+    };
+    isError(error: unknown): error is Error;
+    captureStackTrace(targetObject: object, constructorOpt?: Function): void;
+    prepareStackTrace(err: Error, stackTraces: NodeJS.CallSite[]): any;
+    stackTraceLimit: number;
+};
+declare class ConflictException extends ConflictException_base {
+}
+declare const GoneException_base: {
+    new (message?: string, options?: HttpExceptionOptions): {
+        readonly statusCode: number;
+        readonly code: string;
+        readonly description?: string;
+        toJSON(): {
+            error: {
+                description?: string | undefined;
+                code: string;
+                message: string;
+                statusCode: number;
+            };
+        };
+        name: string;
+        message: string;
+        stack?: string;
+        cause?: unknown;
+    };
+    isError(error: unknown): error is Error;
+    captureStackTrace(targetObject: object, constructorOpt?: Function): void;
+    prepareStackTrace(err: Error, stackTraces: NodeJS.CallSite[]): any;
+    stackTraceLimit: number;
+};
+declare class GoneException extends GoneException_base {
+}
+declare const PreconditionFailedException_base: {
+    new (message?: string, options?: HttpExceptionOptions): {
+        readonly statusCode: number;
+        readonly code: string;
+        readonly description?: string;
+        toJSON(): {
+            error: {
+                description?: string | undefined;
+                code: string;
+                message: string;
+                statusCode: number;
+            };
+        };
+        name: string;
+        message: string;
+        stack?: string;
+        cause?: unknown;
+    };
+    isError(error: unknown): error is Error;
+    captureStackTrace(targetObject: object, constructorOpt?: Function): void;
+    prepareStackTrace(err: Error, stackTraces: NodeJS.CallSite[]): any;
+    stackTraceLimit: number;
+};
+declare class PreconditionFailedException extends PreconditionFailedException_base {
+}
+declare const PayloadTooLargeException_base: {
+    new (message?: string, options?: HttpExceptionOptions): {
+        readonly statusCode: number;
+        readonly code: string;
+        readonly description?: string;
+        toJSON(): {
+            error: {
+                description?: string | undefined;
+                code: string;
+                message: string;
+                statusCode: number;
+            };
+        };
+        name: string;
+        message: string;
+        stack?: string;
+        cause?: unknown;
+    };
+    isError(error: unknown): error is Error;
+    captureStackTrace(targetObject: object, constructorOpt?: Function): void;
+    prepareStackTrace(err: Error, stackTraces: NodeJS.CallSite[]): any;
+    stackTraceLimit: number;
+};
+declare class PayloadTooLargeException extends PayloadTooLargeException_base {
+}
+declare const UnsupportedMediaTypeException_base: {
+    new (message?: string, options?: HttpExceptionOptions): {
+        readonly statusCode: number;
+        readonly code: string;
+        readonly description?: string;
+        toJSON(): {
+            error: {
+                description?: string | undefined;
+                code: string;
+                message: string;
+                statusCode: number;
+            };
+        };
+        name: string;
+        message: string;
+        stack?: string;
+        cause?: unknown;
+    };
+    isError(error: unknown): error is Error;
+    captureStackTrace(targetObject: object, constructorOpt?: Function): void;
+    prepareStackTrace(err: Error, stackTraces: NodeJS.CallSite[]): any;
+    stackTraceLimit: number;
+};
+declare class UnsupportedMediaTypeException extends UnsupportedMediaTypeException_base {
+}
+declare const ImATeapotException_base: {
+    new (message?: string, options?: HttpExceptionOptions): {
+        readonly statusCode: number;
+        readonly code: string;
+        readonly description?: string;
+        toJSON(): {
+            error: {
+                description?: string | undefined;
+                code: string;
+                message: string;
+                statusCode: number;
+            };
+        };
+        name: string;
+        message: string;
+        stack?: string;
+        cause?: unknown;
+    };
+    isError(error: unknown): error is Error;
+    captureStackTrace(targetObject: object, constructorOpt?: Function): void;
+    prepareStackTrace(err: Error, stackTraces: NodeJS.CallSite[]): any;
+    stackTraceLimit: number;
+};
+declare class ImATeapotException extends ImATeapotException_base {
+}
+declare const UnprocessableEntityException_base: {
+    new (message?: string, options?: HttpExceptionOptions): {
+        readonly statusCode: number;
+        readonly code: string;
+        readonly description?: string;
+        toJSON(): {
+            error: {
+                description?: string | undefined;
+                code: string;
+                message: string;
+                statusCode: number;
+            };
+        };
+        name: string;
+        message: string;
+        stack?: string;
+        cause?: unknown;
+    };
+    isError(error: unknown): error is Error;
+    captureStackTrace(targetObject: object, constructorOpt?: Function): void;
+    prepareStackTrace(err: Error, stackTraces: NodeJS.CallSite[]): any;
+    stackTraceLimit: number;
+};
+declare class UnprocessableEntityException extends UnprocessableEntityException_base {
+}
+declare const InternalServerErrorException_base: {
+    new (message?: string, options?: HttpExceptionOptions): {
+        readonly statusCode: number;
+        readonly code: string;
+        readonly description?: string;
+        toJSON(): {
+            error: {
+                description?: string | undefined;
+                code: string;
+                message: string;
+                statusCode: number;
+            };
+        };
+        name: string;
+        message: string;
+        stack?: string;
+        cause?: unknown;
+    };
+    isError(error: unknown): error is Error;
+    captureStackTrace(targetObject: object, constructorOpt?: Function): void;
+    prepareStackTrace(err: Error, stackTraces: NodeJS.CallSite[]): any;
+    stackTraceLimit: number;
+};
+declare class InternalServerErrorException extends InternalServerErrorException_base {
+}
+declare const NotImplementedException_base: {
+    new (message?: string, options?: HttpExceptionOptions): {
+        readonly statusCode: number;
+        readonly code: string;
+        readonly description?: string;
+        toJSON(): {
+            error: {
+                description?: string | undefined;
+                code: string;
+                message: string;
+                statusCode: number;
+            };
+        };
+        name: string;
+        message: string;
+        stack?: string;
+        cause?: unknown;
+    };
+    isError(error: unknown): error is Error;
+    captureStackTrace(targetObject: object, constructorOpt?: Function): void;
+    prepareStackTrace(err: Error, stackTraces: NodeJS.CallSite[]): any;
+    stackTraceLimit: number;
+};
+declare class NotImplementedException extends NotImplementedException_base {
+}
+declare const BadGatewayException_base: {
+    new (message?: string, options?: HttpExceptionOptions): {
+        readonly statusCode: number;
+        readonly code: string;
+        readonly description?: string;
+        toJSON(): {
+            error: {
+                description?: string | undefined;
+                code: string;
+                message: string;
+                statusCode: number;
+            };
+        };
+        name: string;
+        message: string;
+        stack?: string;
+        cause?: unknown;
+    };
+    isError(error: unknown): error is Error;
+    captureStackTrace(targetObject: object, constructorOpt?: Function): void;
+    prepareStackTrace(err: Error, stackTraces: NodeJS.CallSite[]): any;
+    stackTraceLimit: number;
+};
+declare class BadGatewayException extends BadGatewayException_base {
+}
+declare const ServiceUnavailableException_base: {
+    new (message?: string, options?: HttpExceptionOptions): {
+        readonly statusCode: number;
+        readonly code: string;
+        readonly description?: string;
+        toJSON(): {
+            error: {
+                description?: string | undefined;
+                code: string;
+                message: string;
+                statusCode: number;
+            };
+        };
+        name: string;
+        message: string;
+        stack?: string;
+        cause?: unknown;
+    };
+    isError(error: unknown): error is Error;
+    captureStackTrace(targetObject: object, constructorOpt?: Function): void;
+    prepareStackTrace(err: Error, stackTraces: NodeJS.CallSite[]): any;
+    stackTraceLimit: number;
+};
+declare class ServiceUnavailableException extends ServiceUnavailableException_base {
+}
+declare const GatewayTimeoutException_base: {
+    new (message?: string, options?: HttpExceptionOptions): {
+        readonly statusCode: number;
+        readonly code: string;
+        readonly description?: string;
+        toJSON(): {
+            error: {
+                description?: string | undefined;
+                code: string;
+                message: string;
+                statusCode: number;
+            };
+        };
+        name: string;
+        message: string;
+        stack?: string;
+        cause?: unknown;
+    };
+    isError(error: unknown): error is Error;
+    captureStackTrace(targetObject: object, constructorOpt?: Function): void;
+    prepareStackTrace(err: Error, stackTraces: NodeJS.CallSite[]): any;
+    stackTraceLimit: number;
+};
+declare class GatewayTimeoutException extends GatewayTimeoutException_base {
+}
+declare const HttpVersionNotSupportedException_base: {
+    new (message?: string, options?: HttpExceptionOptions): {
+        readonly statusCode: number;
+        readonly code: string;
+        readonly description?: string;
+        toJSON(): {
+            error: {
+                description?: string | undefined;
+                code: string;
+                message: string;
+                statusCode: number;
+            };
+        };
+        name: string;
+        message: string;
+        stack?: string;
+        cause?: unknown;
+    };
+    isError(error: unknown): error is Error;
+    captureStackTrace(targetObject: object, constructorOpt?: Function): void;
+    prepareStackTrace(err: Error, stackTraces: NodeJS.CallSite[]): any;
+    stackTraceLimit: number;
+};
+declare class HttpVersionNotSupportedException extends HttpVersionNotSupportedException_base {
+}
+declare const TooManyRequestsException_base: {
+    new (message?: string, options?: HttpExceptionOptions): {
+        readonly statusCode: number;
+        readonly code: string;
+        readonly description?: string;
+        toJSON(): {
+            error: {
+                description?: string | undefined;
+                code: string;
+                message: string;
+                statusCode: number;
+            };
+        };
+        name: string;
+        message: string;
+        stack?: string;
+        cause?: unknown;
+    };
+    isError(error: unknown): error is Error;
+    captureStackTrace(targetObject: object, constructorOpt?: Function): void;
+    prepareStackTrace(err: Error, stackTraces: NodeJS.CallSite[]): any;
+    stackTraceLimit: number;
+};
+declare class TooManyRequestsException extends TooManyRequestsException_base {
+}
+/**
+ * HttpStatus enum — all standard HTTP status codes as named constants.
+ *
+ * @example
+ * ```ts
+ * import { HttpStatus } from '@theokit/http'
+ *
+ * @HttpCode(HttpStatus.CREATED)
+ * @Post()
+ * create() { ... }
+ *
+ * if (res.status === HttpStatus.NOT_FOUND) { ... }
+ * ```
+ */
+declare const HttpStatus: {
+    readonly OK: 200;
+    readonly CREATED: 201;
+    readonly ACCEPTED: 202;
+    readonly NO_CONTENT: 204;
+    readonly MOVED_PERMANENTLY: 301;
+    readonly FOUND: 302;
+    readonly NOT_MODIFIED: 304;
+    readonly TEMPORARY_REDIRECT: 307;
+    readonly PERMANENT_REDIRECT: 308;
+    readonly BAD_REQUEST: 400;
+    readonly UNAUTHORIZED: 401;
+    readonly PAYMENT_REQUIRED: 402;
+    readonly FORBIDDEN: 403;
+    readonly NOT_FOUND: 404;
+    readonly METHOD_NOT_ALLOWED: 405;
+    readonly NOT_ACCEPTABLE: 406;
+    readonly REQUEST_TIMEOUT: 408;
+    readonly CONFLICT: 409;
+    readonly GONE: 410;
+    readonly PRECONDITION_FAILED: 412;
+    readonly PAYLOAD_TOO_LARGE: 413;
+    readonly UNSUPPORTED_MEDIA_TYPE: 415;
+    readonly IM_A_TEAPOT: 418;
+    readonly UNPROCESSABLE_ENTITY: 422;
+    readonly TOO_MANY_REQUESTS: 429;
+    readonly INTERNAL_SERVER_ERROR: 500;
+    readonly NOT_IMPLEMENTED: 501;
+    readonly BAD_GATEWAY: 502;
+    readonly SERVICE_UNAVAILABLE: 503;
+    readonly GATEWAY_TIMEOUT: 504;
+};
+type HttpStatusCode = (typeof HttpStatus)[keyof typeof HttpStatus];
+
+/**
+ * Typed Client — end-to-end type inference from route contracts.
+ *
+ * Zero codegen, zero runtime overhead on types. The developer defines
+ * a route map using `contract()`, and `createTypedClient<T>()` infers
+ * request body + response types automatically.
+ */
+
+interface RouteDefinition {
+    body?: z.ZodType;
+    params?: Record<string, 'string' | 'number'>;
+    query?: Record<string, 'string' | 'number' | 'boolean'>;
+    response: unknown;
+}
+type RouteMap = Record<string, RouteDefinition>;
+type InferBody<D> = D extends {
+    body: z.ZodType;
+} ? z.infer<D['body']> : never;
+type InferResponse<D> = D extends {
+    response: infer R;
+} ? R : unknown;
+interface TypedClient<M extends RouteMap> {
+    get<P extends string & keyof M>(path: P, opts?: {
+        query?: Record<string, string>;
+        headers?: Record<string, string>;
+    }): Promise<InferResponse<M[`GET ${P}`] extends never ? M[P] : M[`GET ${P}`]>>;
+    post<P extends string>(path: P, body?: InferBody<M[`POST ${P}`]>, opts?: {
+        headers?: Record<string, string>;
+    }): Promise<InferResponse<M[`POST ${P}`]>>;
+    put<P extends string>(path: P, body?: InferBody<M[`PUT ${P}`]>, opts?: {
+        headers?: Record<string, string>;
+    }): Promise<InferResponse<M[`PUT ${P}`]>>;
+    delete<P extends string>(path: P, opts?: {
+        headers?: Record<string, string>;
+    }): Promise<InferResponse<M[`DELETE ${P}`]>>;
+}
+declare function createTypedClient<M extends RouteMap>(baseUrl: string, defaultHeaders?: Record<string, string>): TypedClient<M>;
+declare class TypedClientError extends Error {
+    readonly status: number;
+    readonly body: Record<string, unknown>;
+    constructor(status: number, body: Record<string, unknown>);
+}
+
+/**
+ * Route Contract — type-level bridge between @Controller and TypedClient.
+ *
+ * The developer defines a contract object mapping routes to their types.
+ * This object is the single source of truth for both server validation
+ * and client type inference.
+ *
+ * @example
+ * ```ts
+ * // server/contracts.ts — shared between server and client
+ * import { z } from 'zod'
+ * import { contract } from '@theokit/http'
+ *
+ * export const zCreateTask = z.object({
+ *   title: z.string().min(3),
+ *   priority: z.enum(['low', 'medium', 'high']).default('medium'),
+ * })
+ *
+ * export interface Task { id: number; title: string; priority: string; done: boolean }
+ *
+ * export const routes = contract({
+ *   'GET /api/tasks':       { response: [] as Task[] },
+ *   'GET /api/tasks/:id':   { response: {} as Task },
+ *   'POST /api/tasks':      { body: zCreateTask, response: {} as Task },
+ *   'PUT /api/tasks/:id':   { body: z.object({ done: z.boolean() }), response: {} as Task },
+ *   'DELETE /api/tasks/:id': { response: undefined as void },
+ * })
+ * export type AppRoutes = typeof routes
+ * ```
+ *
+ * The `contract()` function is identity at runtime (zero overhead) but
+ * enforces the RouteMap type at the type level, enabling full inference.
+ */
+
+/**
+ * Identity function that enforces RouteMap type constraint.
+ * Zero runtime overhead — exists only for type inference.
+ */
+declare function contract<T extends RouteMap>(routes: T): T;
+
+export { All, type ArgumentsHost, BadGatewayException, BadRequestException, Body, CATCH_EXCEPTIONS, CONTROLLER_PREFIX, type CanActivate, Catch, ConflictException, Controller, type ControllerMeta, type ControllerOptions, Delete, DiContainer, type ExceptionFilter, type ExecutionContext, ForbiddenException, GatewayTimeoutException, Get, GoneException, Head, Header, Headers, HostParam, HttpCode, HttpDecoratorsConfigError, HttpException, type HttpExceptionOptions, HttpStatus, type HttpStatusCode, type HttpVerb, HttpVersionNotSupportedException, ImATeapotException, type Interceptor, InternalServerErrorException, Ip, type MetadataKey, MethodNotAllowedException, MiddlewareConsumerImpl, NotAcceptableException, NotFoundException, NotImplementedException, Options, Param, type ParamEntry, type ParamSource, Patch, PayloadTooLargeException, Post, PreconditionFailedException, Put, Query, ROUTE_HEADERS, ROUTE_METHODS, ROUTE_PARAMS, ROUTE_REDIRECT, ROUTE_STATUS, Redirect, type RedirectMeta, Reflector, Req, RequestTimeoutException, Res, type RouteDefinition, type RouteMap, type RouteMethodEntry, type RouteRegistration, ServiceUnavailableException, Session, SetMetadata, SkipThrottle, Throttle, type ThrottleOptions, TooManyRequestsException, type TypedClient, TypedClientError, USE_FILTERS, USE_GUARDS, USE_INTERCEPTORS, UnauthorizedException, UnprocessableEntityException, UnsupportedMediaTypeException, UseFilters, UseGuards, UseInterceptors, type WalkResult, contract, createDecorator, createDecoratorServer, createExecutionContext, createTypedClient, getMeta, getThrottleOptions, isThrottleSkipped, joinPath, registerControllers, resolveDtoSchema, runExceptionFilters, runInterceptors, setMeta, walkControllerMetadata };