@rabstack/rab-api 1.0.1

package/index.esm.d.ts

@@ -0,0 +1,966 @@
+/// <reference types="node" />
+
+import { Container } from 'typedi';
+import { ErrorRequestHandler } from 'express';
+import { Express as Express_2 } from 'express';
+import { IncomingMessage } from 'http';
+import type Joi from 'joi';
+import { NextFunction } from 'express';
+import { Request as Request_2 } from 'express';
+import { Response as Response_2 } from 'express';
+import { Server } from 'http';
+import { ServerResponse } from 'http';
+import { Service } from 'typedi';
+
+export declare interface AbstractBloc<Params, ResultType> {
+    execute(params: Params): Promise<ResultType> | ResultType;
+}
+
+export declare type AliveKeep = boolean;
+
+export declare type AppRoute<CreateControllerOptions extends InjectorsMetadata = any> = ControllerClassType | CreateRouterProps<CreateControllerOptions>;
+
+/**
+ * AtomApi DELETE controller interface.
+ * Alias for RabApiDelete for backward compatibility.
+ *
+ * @template T - Controller type (usually DeleteController<...>)
+ */
+export declare type AtomApiDelete<T extends IControllerClass = any> = RabApiDelete<T>;
+
+/**
+ * AtomApi GET controller interface.
+ * Alias for RabApiGet for backward compatibility.
+ *
+ * @template T - Controller type (usually GetController<...>)
+ */
+export declare type AtomApiGet<T extends IControllerClass = any> = RabApiGet<T>;
+
+/**
+ * AtomApi PATCH controller interface.
+ * Alias for RabApiPatch for backward compatibility.
+ *
+ * @template T - Controller type (usually PatchController<...>)
+ */
+export declare type AtomApiPatch<T extends IControllerClass = any> = RabApiPatch<T>;
+
+/**
+ * AtomApi POST controller interface.
+ * Alias for RabApiPost for backward compatibility.
+ *
+ * @template T - Controller type (usually PostController<...>)
+ */
+export declare type AtomApiPost<T extends IControllerClass = any> = RabApiPost<T>;
+
+/**
+ * AtomApi PUT controller interface.
+ * Alias for RabApiPut for backward compatibility.
+ *
+ * @template T - Controller type (usually PutController<...>)
+ */
+export declare type AtomApiPut<T extends IControllerClass = any> = RabApiPut<T>;
+
+export declare class AtomExpressApp {
+    app: Express_2;
+    private collectedRoutes;
+    private readonly options;
+    constructor(options: AtomExpressOptions);
+    use(...middleware: any): void;
+    private resolvePipes;
+    private setupRouteController;
+    private buildRouter;
+    route(routerParams: CreateRouterProps): void;
+    listen(port: number | string, callback?: () => void): Server<IncomingMessage, ServerResponse>;
+    getCollectedRoutes(): CollectedRoute[];
+}
+
+export declare type AtomExpressOptions = {
+    errorHandler?: (err: any, req: Request_2, res: Response_2, next: NextFunction) => any;
+    enforceBodyValidation?: boolean;
+    enforceRouteProtection?: boolean;
+    auth?: AuthHandlerOptions;
+    openapi?: {
+        enabled?: boolean;
+        path?: string;
+        info?: {
+            title?: string;
+            version?: string;
+            description?: string;
+        };
+        servers?: Array<{
+            url: string;
+            description?: string;
+            variables?: Record<string, {
+                default: string;
+                description?: string;
+                enum?: string[];
+            }>;
+        }>;
+    };
+};
+
+export declare namespace AtomHelpers {
+    export {
+        joiValidator,
+        validateJoiSchema,
+        retrieveRouteMetaData
+    }
+}
+
+/**
+ * Core route decorator factory.
+ * Creates route decorators for different HTTP methods.
+ *
+ * @param method - HTTP method for this route
+ * @param path - URL path pattern (supports Express-style params like ':id')
+ * @param options - Route configuration options
+ * @returns Class decorator function
+ */
+export declare function AtomRoute(method: HttpMethod, path: string, options?: ControllerRouteDefinitionOptions): (target: any) => void;
+
+export declare const authHandler: (isProtected: boolean, config: AuthHandlerOptions) => (req: any, res: Response_2, next: NextFunction) => void;
+
+export declare type AuthHandlerOptions = {
+    jwt: {
+        secret_key: string;
+        algorithms: any;
+    };
+};
+
+/**
+ * Represents a 400 Bad Request error.
+ * Use this for client-side validation failures or malformed requests.
+ *
+ * @example
+ * ```typescript
+ * throw new BadRequestException(
+ *   'Invalid email format',
+ *   ['Email must be a valid email address'],
+ *   'INVALID_EMAIL'
+ * );
+ * ```
+ */
+export declare class BadRequestException extends RabApiError {
+    /**
+     * @param message - Human-readable error message
+     * @param errors - Optional array of detailed validation errors
+     * @param errorCode - Optional machine-readable error code for client handling
+     */
+    constructor(message: string, errors?: string[], errorCode?: string);
+}
+
+export declare const bodyValidatorWithContext: (config: RouteHandleOptions) => (req: any, res: Response_2, next: NextFunction) => Promise<void>;
+
+export declare type BuildRouterProps = CreateRouterProps & {
+    fullPath?: string;
+};
+
+export declare interface CollectedRoute {
+    method: string;
+    path: string;
+    fullPath: string;
+    controller: ControllerClassType;
+    metadata: any;
+    options?: InjectorsMetadata;
+}
+
+/**
+ * Represents a 409 Conflict error.
+ * Use this when a request conflicts with the current state (e.g., duplicate resources).
+ *
+ * @example
+ * ```typescript
+ * throw new ConflictException('Email already exists', 'EMAIL_CONFLICT');
+ * ```
+ */
+export declare class ConflictException extends RabApiError {
+    /**
+     * @param message - Human-readable error message
+     * @param errorCode - Optional machine-readable error code
+     */
+    constructor(message: string, errorCode?: string);
+}
+
+/**
+ * Controller decorator - marks a class as an injectable controller.
+ * Alias for TypeDI's @Service decorator.
+ */
+export declare const Controller: typeof Service;
+
+/**
+ * Metadata key used to store route information via reflect-metadata.
+ */
+export declare const CONTROLLER_ROUTE_KEY = "controller:route";
+
+export declare type ControllerClassType = new (...dependencies: any) => RabApiController<any, any, any>;
+
+export declare const controllerHandler: (controller: RabApiController, config: RouteHandleOptions) => (req: any, res: any, next: any) => Promise<any>;
+
+/**
+ * Metadata definition for a controller route.
+ * Contains HTTP method, path, handler name, and additional options.
+ */
+export declare interface ControllerRouteDefinition {
+    method: HttpMethod;
+    path: string;
+    handlerName: string;
+    options?: ControllerRouteDefinitionOptions;
+}
+
+/**
+ * Options for configuring controller routes.
+ * Includes validation, permissions, middleware, and more.
+ */
+export declare type ControllerRouteDefinitionOptions = InjectorsMetadata;
+
+export declare type CreateRouterProps<CreateControllerOptions extends InjectorsMetadata = any> = {
+    controllers: AppRoute<CreateControllerOptions>[];
+    basePath?: string;
+    tags?: string[];
+} & InjectorsMetadata;
+
+/**
+ * Enhanced Express Request with strongly-typed properties.
+ * Extends Express Request with type-safe query, body, params, and auth.
+ *
+ * @template TQuery - Query parameter type
+ * @template TBody - Request body type
+ * @template TParams - Route parameter type
+ * @template TUser - Authenticated user/token payload type
+ *
+ * @example
+ * ```typescript
+ * type MyRequest = CTRLRequest<
+ *   { page: number },           // Query
+ *   { name: string },           // Body
+ *   { id: string },             // Params
+ *   { userId: string }          // Auth
+ * >;
+ * ```
+ */
+export declare interface CTRLRequest<TQuery = any, TBody = any, TParams = any, TUser = any> extends Omit<Request_2, 'body' | 'params' | 'query'> {
+    /** Parsed query parameters */
+    query: TQuery;
+    /** Parsed request body */
+    body: TBody;
+    /** Route parameters */
+    params: TParams;
+    /** Authenticated user data (from JWT token) */
+    auth: TUser;
+    /** Uploaded file (from multer or similar) */
+    file?: any;
+    /** Access grant from permission system */
+    accessGrant?: any;
+}
+
+/**
+ * Controller response type.
+ * Can be either direct data or a structured response object.
+ *
+ * @template Data - The response data type
+ *
+ * @example
+ * ```typescript
+ * // Direct response
+ * return { id: '123', name: 'John' };
+ *
+ * // Structured response
+ * return {
+ *   statusCode: 201,
+ *   message: 'User created',
+ *   data: { id: '123', name: 'John' }
+ * };
+ * ```
+ */
+export declare type CTRLResponse<Data> = Data | {
+    /** HTTP status code (optional, defaults to 200) */
+    statusCode?: number;
+    /** Response message */
+    message?: string;
+    /** Response data */
+    data: Data;
+    /** If true, only data will be returned (no metadata wrapper) */
+    excludeMetaData?: boolean;
+};
+
+/**
+ * DELETE route decorator.
+ * Registers a controller class as a DELETE endpoint handler.
+ *
+ * @param path - URL path pattern (e.g., '/users/:id')
+ * @param options - Route configuration options (validation, permissions, etc.)
+ * @returns Class decorator
+ *
+ * @example
+ * ```typescript
+ * @Delete('/users/:id', {
+ *   permission: 'canDeleteUser',
+ * })
+ * export class DeleteUserController implements AtomApiDelete<T> {
+ *   execute = async (request) => {
+ *     await this.userService.delete(request.params.id);
+ *     return { success: true };
+ *   };
+ * }
+ * ```
+ */
+export declare function Delete(path: string, options?: ControllerRouteDefinitionOptions): ClassDecorator;
+
+/**
+ * DELETE controller type.
+ * Used for endpoints that delete resources.
+ *
+ * @template TParams - Route parameter type (default: any)
+ * @template TUser - Authenticated user type (default: any)
+ *
+ * @example
+ * ```typescript
+ * type ControllerT = DeleteController<{ id: string }, TokenPayload>;
+ *
+ * @Delete('/users/:id')
+ * export class DeleteUser implements AtomApiDelete<ControllerT> {
+ *   handler: ControllerT['request'] = async (request) => {
+ *     await this.userBloc.delete(request.params.id);
+ *     return { message: 'User deleted' };
+ *   };
+ * }
+ * ```
+ */
+export declare type DeleteController<TParams = any, TUser = any> = IControllerClass<any, any, any, TParams, TUser>;
+
+/**
+ * Dependency injection container.
+ * Provides access to TypeDI's Container for manual service retrieval.
+ */
+export declare const DiContainer: typeof Container;
+
+/**
+ * Global error handler middleware for Express.
+ * Handles RabApiError instances with proper status codes and error formatting.
+ * Falls back to 500 Internal Server Error for unexpected errors.
+ *
+ * @param err - The error object
+ * @param req - Express request object
+ * @param res - Express response object
+ * @param next - Express next function
+ */
+export declare const errorHandler: ErrorRequestHandler;
+
+/**
+ * Extracts the Bearer token from the Authorization header
+ *
+ * @param request - Express request object
+ * @returns The extracted token or undefined if not found or not a Bearer token
+ *
+ * @example
+ * ```typescript
+ * const token = extractTokenFromHeader(req);
+ * if (!token) {
+ *   throw new UnauthorizedException();
+ * }
+ * ```
+ */
+export declare const extractTokenFromHeader: (request: Request_2) => string | undefined;
+
+/**
+ * Represents a 403 Forbidden error.
+ * Use this when the user is authenticated but lacks permission.
+ *
+ * @example
+ * ```typescript
+ * throw new ForbiddenException('You do not have permission to access this resource', 'INSUFFICIENT_PERMISSIONS');
+ * ```
+ */
+export declare class ForbiddenException extends RabApiError {
+    /**
+     * @param message - Human-readable error message (default: 'Forbidden')
+     * @param errorCode - Optional machine-readable error code
+     */
+    constructor(message?: string, errorCode?: string);
+}
+
+/**
+ * GET route decorator.
+ * Registers a controller class as a GET endpoint handler.
+ *
+ * @param path - URL path pattern (e.g., '/users' or '/users/:id')
+ * @param options - Route configuration options (validation, permissions, etc.)
+ * @returns Class decorator
+ *
+ * @example
+ * ```typescript
+ * @Get('/users/:id', {
+ *   permission: 'canReadUser',
+ * })
+ * export class GetUserController implements AtomApiGet<T> {
+ *   execute = async (request) => {
+ *     return this.userService.findById(request.params.id);
+ *   };
+ * }
+ * ```
+ */
+export declare function Get(path: string, options?: ControllerRouteDefinitionOptions): ClassDecorator;
+
+/**
+ * GET controller type.
+ * Used for endpoints that retrieve data.
+ *
+ * @template TResponse - Response data type
+ * @template TQuery - Query parameter type (default: any)
+ * @template TParams - Route parameter type (default: any)
+ * @template TUser - Authenticated user type (default: any)
+ *
+ * @example
+ * ```typescript
+ * type ControllerT = GetController<User, never, { id: string }, TokenPayload>;
+ *
+ * @Get('/users/:id')
+ * export class GetUser implements RabApiGet<ControllerT> {
+ *   handler: ControllerT['request'] = async (request) => {
+ *     return await this.userBloc.getById(request.params.id);
+ *   };
+ * }
+ * ```
+ */
+export declare type GetController<TResponse, TQuery = any, TParams = any, TUser = any> = IControllerClass<TQuery, any, TResponse, TParams, TUser>;
+
+/**
+ * Supported HTTP methods for route decorators.
+ */
+export declare type HttpMethod = 'get' | 'post' | 'put' | 'patch' | 'delete';
+
+/**
+ * Controller class type definition.
+ * Used to define the type shape for controller implementations.
+ *
+ * @template TQuery - Query parameter type
+ * @template TBody - Request body type
+ * @template TResponse - Response data type
+ * @template TParams - Route parameter type
+ * @template TUser - Authenticated user type
+ *
+ * @example
+ * ```typescript
+ * type MyControllerT = IControllerClass<
+ *   never,                    // No query params
+ *   { name: string },         // Body type
+ *   { id: string },           // Response type
+ *   { id: string },           // Params type
+ *   TokenPayload              // User type
+ * >;
+ *
+ * class MyController implements RabApiPost<MyControllerT> {
+ *   handler: MyControllerT['request'] = async (req) => {
+ *     // Implementation
+ *   };
+ * }
+ * ```
+ */
+export declare type IControllerClass<TQuery = any, TBody = any, TResponse = any, TParams = any, TUser = any> = {
+    /** The request handler function signature */
+    request: (req: CTRLRequest<TQuery, TBody, TParams, TUser>) => Promise<CTRLResponse<TResponse>>;
+    /** Type marker for response type (not used at runtime) */
+    response: TResponse;
+    /** Type marker for body type (not used at runtime) */
+    body: TBody;
+    /** Type marker for params type (not used at runtime) */
+    params: TParams;
+    /** Type marker for user type (not used at runtime) */
+    user: TUser;
+    /** Type marker for query type (not used at runtime) */
+    query: TQuery;
+};
+
+export declare type IDParams = {
+    id: string;
+};
+
+/**
+ * Injectable decorator - marks a class as injectable via dependency injection.
+ * Alias for TypeDI's @Service decorator.
+ */
+export declare const Injectable: typeof Service;
+
+export declare type InjectorsMetadata<TQuery = any, TBody = any, TResponse = any, TParams = any, TParsedParams = any> = {
+    isProtected?: boolean;
+    permission?: string;
+    pipes?: PipeInjector;
+    validateResponse?: (res: TResponse) => asserts res is TResponse;
+    validateQuery?: (queryParameters: TQuery) => Promise<TQuery>;
+    validateBody?: (body: TBody) => Promise<TBody>;
+    disableBodyValidation?: boolean;
+    parseQueryParams?: (query: any) => TParsedParams;
+    bodySchema?: Joi.ObjectSchema<TBody>;
+    querySchema?: Joi.ObjectSchema<TParams>;
+    excludeFromDocs?: boolean;
+    docs?: OpenApiDocsMetadata;
+};
+
+/**
+ * Represents a 500 Internal Server Error.
+ * Use this for unexpected server-side errors.
+ *
+ * @example
+ * ```typescript
+ * throw new InternalServerErrorException('Database connection failed', 'DB_ERROR');
+ * ```
+ */
+export declare class InternalServerErrorException extends RabApiError {
+    /**
+     * @param message - Human-readable error message (default: 'Internal Server Error')
+     * @param errorCode - Optional machine-readable error code
+     */
+    constructor(message?: string, errorCode?: string);
+}
+
+export declare const isCallBackPipe: (pipe: PipeFn | PipeFnCallBack) => pipe is PipeFnCallBack;
+
+export declare function isRouteAController(value: AppRoute): value is ControllerClassType;
+
+/**
+ * Validates data against a Joi schema.
+ * Throws a BadRequestException with detailed error messages if validation fails.
+ *
+ * @param schema - The Joi schema to validate against
+ * @param payload - The data to validate
+ * @param options - Optional Joi validation options
+ * @returns The validated and potentially transformed data
+ * @throws {BadRequestException} When validation fails
+ *
+ * @example
+ * ```typescript
+ * const schema = Joi.object({ email: Joi.string().email().required() });
+ * const validated = await joiValidator(schema, { email: 'test@example.com' });
+ * ```
+ */
+declare function joiValidator<T = any>(schema: Joi.ObjectSchema<any>, payload: T, options?: Joi.ValidationOptions): Promise<T>;
+
+/**
+ * Represents a 405 Method Not Allowed error.
+ * Use this when an HTTP method is not supported for a resource.
+ *
+ * @example
+ * ```typescript
+ * throw new MethodNotAllowedException('DELETE method not allowed on this resource');
+ * ```
+ */
+export declare class MethodNotAllowedException extends RabApiError {
+    /**
+     * @param message - Human-readable error message (default: 'Method Not Allowed')
+     * @param errorCode - Optional machine-readable error code
+     */
+    constructor(message?: string, errorCode?: string);
+}
+
+/**
+ * Represents a 404 Not Found error.
+ * Use this when a requested resource does not exist.
+ *
+ * @example
+ * ```typescript
+ * throw new NotFoundException('User not found', 'USER_NOT_FOUND');
+ * ```
+ */
+export declare class NotFoundException extends RabApiError {
+    /**
+     * @param message - Human-readable error message (default: 'Not Found')
+     * @param errorCode - Optional machine-readable error code
+     */
+    constructor(message?: string, errorCode?: string);
+}
+
+export declare type OpenApiDocsMetadata = {
+    summary?: string;
+    description?: string;
+    tags?: string[];
+    operationId?: string;
+    responses?: Record<string, {
+        description: string;
+        content?: Record<string, any>;
+    }>;
+    deprecated?: boolean;
+};
+
+export declare class OpenApiGenerator {
+    private routes;
+    private options;
+    constructor(routes: CollectedRoute[], options: AtomExpressOptions);
+    generate(): OpenApiSpec;
+    private joiToOpenApiSchema;
+    private convertJoiDescriptionToOpenApi;
+    private generateDefaultTag;
+}
+
+export declare interface OpenApiSpec {
+    openapi: string;
+    info: {
+        title: string;
+        version: string;
+        description: string;
+    };
+    servers?: Array<{
+        url: string;
+        description?: string;
+        variables?: Record<string, any>;
+    }>;
+    paths: Record<string, any>;
+    components: {
+        schemas: Record<string, any>;
+        securitySchemes: Record<string, any>;
+    };
+    security?: Array<Record<string, any>>;
+}
+
+export declare type PagingResult<Data> = {
+    page: number;
+    pageSize: number;
+    total: number;
+    totalPages: number;
+    results: Data[];
+};
+
+/**
+ * PATCH route decorator.
+ * Registers a controller class as a PATCH endpoint handler.
+ * Use for partial resource updates.
+ *
+ * @param path - URL path pattern (e.g., '/users/:id')
+ * @param options - Route configuration options (validation, permissions, etc.)
+ * @returns Class decorator
+ *
+ * @example
+ * ```typescript
+ * @Patch('/users/:id', {
+ *   bodySchema: patchUserSchema,
+ *   permission: 'canUpdateUser',
+ * })
+ * export class PatchUserController implements AtomApiPatch<T> {
+ *   execute = async (request) => {
+ *     return this.userService.patch(request.params.id, request.body);
+ *   };
+ * }
+ * ```
+ */
+export declare function Patch(path: string, options?: ControllerRouteDefinitionOptions): ClassDecorator;
+
+/**
+ * PATCH controller type.
+ * Alias for PostController since PATCH has the same signature.
+ */
+export declare type PatchController<TBody = any, TResponse = any, TParams = any, TUser = any, TQuery = any> = PostController<TBody, TResponse, TParams, TUser, TQuery>;
+
+/**
+ * Represents a 413 Payload Too Large error.
+ * Use this when the request payload exceeds size limits.
+ *
+ * @example
+ * ```typescript
+ * throw new PayloadTooLargeException('File size exceeds 10MB limit', 'FILE_TOO_LARGE');
+ * ```
+ */
+export declare class PayloadTooLargeException extends RabApiError {
+    /**
+     * @param message - Human-readable error message (default: 'Payload Too Large')
+     * @param errorCode - Optional machine-readable error code
+     */
+    constructor(message?: string, errorCode?: string);
+}
+
+/**
+ * Request type for permission validators.
+ * Used in RAB-Access permission validation functions.
+ *
+ * @template TUser - Authenticated user type
+ * @template TParams - Route parameter type
+ * @template TBody - Request body type
+ * @template TQuery - Query parameter type
+ *
+ * @example
+ * ```typescript
+ * async function canAccessResource(
+ *   request: PermissionRequest<TokenPayload, { resourceId: string }>
+ * ): Promise<boolean> {
+ *   return request.auth.userId === request.params.resourceId;
+ * }
+ * ```
+ */
+export declare type PermissionRequest<TUser = any, TParams = any, TBody = any, TQuery = any> = CTRLRequest<TQuery, TBody, TParams, TUser>;
+
+export declare type PipeFn = (req: any, res: any, next: any, error?: any) => void;
+
+export declare type PipeFnCallBack = (route: Omit<InjectorsMetadata, 'pipes'>) => PipeFn[];
+
+export declare type PipeInjector = Array<PipeFn | PipeFnCallBack>;
+
+/**
+ * POST route decorator.
+ * Registers a controller class as a POST endpoint handler.
+ *
+ * @param path - URL path pattern (e.g., '/users' or '/users/:id')
+ * @param options - Route configuration options (validation, permissions, etc.)
+ * @returns Class decorator
+ *
+ * @example
+ * ```typescript
+ * @Post('/users', {
+ *   bodySchema: createUserSchema,
+ *   permission: 'canCreateUser',
+ * })
+ * export class CreateUserController implements AtomApiPost<T> {
+ *   execute = async (request) => {
+ *     return this.userService.create(request.body);
+ *   };
+ * }
+ * ```
+ */
+export declare function Post(path: string, options?: ControllerRouteDefinitionOptions): ClassDecorator;
+
+/**
+ * POST/PUT/PATCH controller type.
+ * Used for endpoints that accept a request body.
+ *
+ * @template TBody - Request body type
+ * @template TResponse - Response data type
+ * @template TParams - Route parameter type (default: any)
+ * @template TUser - Authenticated user type (default: any)
+ * @template TQuery - Query parameter type (default: any)
+ *
+ * @example
+ * ```typescript
+ * type ControllerT = PostController<CreateUserBody, User, never, TokenPayload>;
+ *
+ * @Post('/users', { bodySchema: createUserSchema })
+ * export class CreateUser implements RabApiPost<ControllerT> {
+ *   handler: ControllerT['request'] = async (request) => {
+ *     return await this.userBloc.create(request.body);
+ *   };
+ * }
+ * ```
+ */
+export declare type PostController<TBody = any, TResponse = any, TParams = any, TUser = any, TQuery = any> = IControllerClass<TQuery, TBody, TResponse, TParams, TUser>;
+
+/**
+ * PUT route decorator.
+ * Registers a controller class as a PUT endpoint handler.
+ * Use for full resource replacement.
+ *
+ * @param path - URL path pattern (e.g., '/users/:id')
+ * @param options - Route configuration options (validation, permissions, etc.)
+ * @returns Class decorator
+ *
+ * @example
+ * ```typescript
+ * @Put('/users/:id', {
+ *   bodySchema: updateUserSchema,
+ *   permission: 'canUpdateUser',
+ * })
+ * export class UpdateUserController implements AtomApiPut<T> {
+ *   execute = async (request) => {
+ *     return this.userService.update(request.params.id, request.body);
+ *   };
+ * }
+ * ```
+ */
+export declare function Put(path: string, options?: ControllerRouteDefinitionOptions): ClassDecorator;
+
+/**
+ * PUT controller type.
+ * Alias for PostController since PUT has the same signature.
+ */
+export declare type PutController<TBody = any, TResponse = any, TParams = any, TUser = any, TQuery = any> = PostController<TBody, TResponse, TParams, TUser, TQuery>;
+
+export declare class RabApi {
+    static createRouter<CreateControllerOptions extends InjectorsMetadata = any>(props: CreateRouterProps<CreateControllerOptions>): CreateRouterProps<CreateControllerOptions>;
+    static createApp(props: AtomExpressOptions): AtomExpressApp;
+}
+
+/**
+ * Base controller interface that all HTTP method controllers implement.
+ * Defines the contract for request handlers.
+ *
+ * @template TQuery - Query parameter type
+ * @template TBody - Request body type
+ * @template TResponse - Response data type
+ * @template TParams - Route parameter type
+ * @template TUser - Authenticated user type
+ */
+export declare interface RabApiController<TQuery = any, TBody = any, TResponse = any, TParams = any, TUser = any> {
+    /**
+     * Request handler function that processes the request and returns a response.
+     */
+    handler: (request: CTRLRequest<TQuery, TBody, TParams, TUser>) => Promise<CTRLResponse<TResponse>>;
+}
+
+/**
+ * RabApi DELETE controller interface.
+ * Implement this interface in controller classes decorated with @Delete.
+ *
+ * @template T - Controller type (usually DeleteController<...>)
+ */
+export declare type RabApiDelete<T extends IControllerClass = any> = RabApiController<T['query'], T['body'], T['response'], T['params'], T['user']>;
+
+/**
+ * Base class for all RabAPI errors.
+ * Extends the native Error class with additional HTTP context.
+ */
+export declare class RabApiError extends Error {
+    message: string;
+    readonly statusCode: number;
+    readonly errorCode?: string;
+    readonly errors?: string[];
+    /**
+     * @param message - Human-readable error message
+     * @param statusCode - HTTP status code
+     * @param errorCode - Optional machine-readable error code
+     * @param errors - Optional array of detailed error messages
+     */
+    constructor(message: string, statusCode: number, errorCode?: string, errors?: string[]);
+}
+
+/**
+ * RabApi GET controller interface.
+ * Implement this interface in controller classes decorated with @Get.
+ *
+ * @template T - Controller type (usually GetController<...>)
+ */
+export declare type RabApiGet<T extends IControllerClass = any> = RabApiController<T['query'], T['body'], T['response'], T['params'], T['user']>;
+
+/**
+ * RabApi PATCH controller interface.
+ * Implement this interface in controller classes decorated with @Patch.
+ *
+ * @template T - Controller type (usually PatchController<...>)
+ */
+export declare type RabApiPatch<T extends IControllerClass = any> = RabApiController<T['query'], T['body'], T['response'], T['params'], T['user']>;
+
+/**
+ * RabApi POST controller interface.
+ * Implement this interface in controller classes decorated with @Post.
+ *
+ * @template T - Controller type (usually PostController<...>)
+ *
+ * @example
+ * ```typescript
+ * type ControllerT = PostController<CreateUserBody, User>;
+ *
+ * @Post('/users')
+ * export class CreateUser implements RabApiPost<ControllerT> {
+ *   handler: ControllerT['request'] = async (req) => {...};
+ * }
+ * ```
+ */
+export declare type RabApiPost<T extends IControllerClass = any> = RabApiController<T['query'], T['body'], T['response'], T['params'], T['user']>;
+
+/**
+ * RabApi PUT controller interface.
+ * Implement this interface in controller classes decorated with @Put.
+ *
+ * @template T - Controller type (usually PutController<...>)
+ */
+export declare type RabApiPut<T extends IControllerClass = any> = RabApiController<T['query'], T['body'], T['response'], T['params'], T['user']>;
+
+/**
+ * Represents a 408 Request Timeout error.
+ * Use this when the server times out waiting for a request.
+ *
+ * @example
+ * ```typescript
+ * throw new RequestTimeoutException('Request took too long to complete', 'REQUEST_TIMEOUT');
+ * ```
+ */
+export declare class RequestTimeoutException extends RabApiError {
+    /**
+     * @param message - Human-readable error message (default: 'Request Timeout')
+     * @param errorCode - Optional machine-readable error code
+     */
+    constructor(message?: string, errorCode?: string);
+}
+
+declare function retrieveRouteMetaData(route: ControllerClassType): ControllerRouteDefinition;
+
+export declare type RouteHandleOptions = InjectorsMetadata & Pick<AtomExpressOptions, 'enforceBodyValidation'>;
+
+/**
+ * Represents a 503 Service Unavailable error.
+ * Use this when the server is temporarily unable to handle requests.
+ *
+ * @example
+ * ```typescript
+ * throw new ServiceUnavailableException('System maintenance in progress', 'MAINTENANCE');
+ * ```
+ */
+export declare class ServiceUnavailableException extends RabApiError {
+    /**
+     * @param message - Human-readable error message (default: 'Service Unavailable')
+     * @param errorCode - Optional machine-readable error code
+     */
+    constructor(message?: string, errorCode?: string);
+}
+
+/**
+ * Represents a 429 Too Many Requests error.
+ * Use this when rate limiting is exceeded.
+ *
+ * @example
+ * ```typescript
+ * throw new TooManyRequestsException('Rate limit exceeded. Try again in 60 seconds', 'RATE_LIMIT_EXCEEDED');
+ * ```
+ */
+export declare class TooManyRequestsException extends RabApiError {
+    /**
+     * @param message - Human-readable error message (default: 'Too Many Requests')
+     * @param errorCode - Optional machine-readable error code
+     */
+    constructor(message?: string, errorCode?: string);
+}
+
+/**
+ * Represents a 401 Unauthorized error.
+ * Use this when authentication is required but missing or invalid.
+ *
+ * @example
+ * ```typescript
+ * throw new UnauthorizedException('Invalid token', 'TOKEN_EXPIRED');
+ * ```
+ */
+export declare class UnauthorizedException extends RabApiError {
+    /**
+     * @param message - Human-readable error message (default: 'Unauthorized')
+     * @param errorCode - Optional machine-readable error code
+     */
+    constructor(message?: string, errorCode?: string);
+}
+
+/**
+ * Represents a 422 Unprocessable Entity error.
+ * Use this for semantic validation errors (valid syntax but invalid semantics).
+ *
+ * @example
+ * ```typescript
+ * throw new UnprocessableEntityException(
+ *   'Validation failed',
+ *   ['Age must be at least 18', 'Email domain not allowed'],
+ *   'VALIDATION_FAILED'
+ * );
+ * ```
+ */
+export declare class UnprocessableEntityException extends RabApiError {
+    /**
+     * @param message - Human-readable error message (default: 'Unprocessable Entity')
+     * @param errors - Optional array of detailed validation errors
+     * @param errorCode - Optional machine-readable error code
+     */
+    constructor(message?: string, errors?: string[], errorCode?: string);
+}
+
+export declare interface UseCase<Params, ResultType> {
+    execute(params: Params): Promise<ResultType> | ResultType;
+}
+
+/**
+ * Validates data against a Joi schema (wrapper for joiValidator).
+ * @deprecated Use joiValidator directly
+ */
+declare function validateJoiSchema<T>(scheme: Joi.ObjectSchema<any>, data: any): Promise<T>;
+
+export { }