@cosmneo/onion-lasagna 0.1.0

package/dist/index-tOH7XBa3.d.ts

@@ -0,0 +1,1187 @@
+import { B as BaseDto } from './base-dto.class-D7W9iqoU.js';
+import { C as CodedError, P as PresentationErrorCode, V as ValidationError } from './validation-error.type-kD4_qNZ9.js';
+import { H as HttpRequest, a as HttpResponse } from './http-response-BAhi8lF4.js';
+import './routing.type-DB4pt-d9.js';
+
+/**
+ * Primary port interface for use case execution (Hexagonal Architecture).
+ *
+ * Defines the contract for inbound adapters that handle application use cases.
+ * Implementations receive a validated input DTO and return an output DTO.
+ *
+ * @typeParam TInDto - Input DTO type, must extend BaseDto
+ * @typeParam TOutDto - Output DTO type, must extend BaseDto
+ *
+ * @example
+ * ```typescript
+ * interface CreateUserPort extends BaseInboundPort<CreateUserInputDto, CreateUserOutputDto> {}
+ * ```
+ */
+interface BaseInboundPort<TInDto extends BaseDto<unknown>, TOutDto extends BaseDto<unknown>> {
+    /**
+     * Executes the use case with the provided input.
+     *
+     * @param input - Validated input DTO
+     * @returns Promise resolving to the output DTO
+     * @throws {UseCaseError} When use case execution fails
+     * @throws {DomainError} When domain invariants are violated
+     * @throws {InfraError} When infrastructure operations fail
+     */
+    execute(input: TInDto): Promise<TOutDto>;
+}
+
+/**
+ * Configuration for creating a BaseController instance.
+ *
+ * All types must be DTOs (extending BaseDto) to ensure validation at every boundary:
+ * - TRequestDto: Validated HTTP request (body, headers, params, query)
+ * - TResponseDto: Validated HTTP response structure
+ * - TInDto: Validated use case input
+ * - TOutDto: Validated use case output
+ *
+ * @typeParam TRequestDto - Validated request DTO from the framework layer
+ * @typeParam TResponseDto - Validated response DTO to return to the framework
+ * @typeParam TInDto - Input DTO type for the use case
+ * @typeParam TOutDto - Output DTO type from the use case
+ */
+interface BaseControllerConfig<TRequestDto extends BaseDto<unknown>, TResponseDto extends BaseDto<unknown>, TInDto extends BaseDto<unknown>, TOutDto extends BaseDto<unknown>> {
+    /** Maps the validated request DTO to a use case input DTO. */
+    requestMapper: (request: TRequestDto) => TInDto;
+    /** The use case to execute. */
+    useCase: BaseInboundPort<TInDto, TOutDto>;
+    /** Maps the use case output DTO to a validated response DTO. */
+    responseMapper: (output: TOutDto) => TResponseDto;
+}
+/**
+ * Base controller implementing the request/response pipeline.
+ *
+ * Orchestrates the flow: `requestDto → mapRequest → executeUseCase → mapResponse → responseDto`
+ *
+ * All boundaries are validated DTOs:
+ * - Input: TRequestDto (validated by framework layer before controller)
+ * - Use case input: TInDto (validated by mapRequest)
+ * - Use case output: TOutDto (validated by use case)
+ * - Output: TResponseDto (validated by mapResponse)
+ *
+ * Features:
+ * - Converts {@link ObjectValidationError} to {@link InvalidRequestError}
+ * - Passes through known {@link CodedError} types
+ * - Wraps unknown errors in {@link ControllerError}
+ *
+ * Architecture:
+ * - {@link execute} - Public entry point with error wrapping (do not override)
+ * - {@link pipeline} - Protected pipeline orchestration (override for custom flow)
+ * - {@link mapRequest} - Request-to-input transformation
+ * - {@link executeUseCase} - Use case execution
+ * - {@link mapResponse} - Output-to-response transformation
+ *
+ * @typeParam TRequestDto - Validated request DTO from the framework layer
+ * @typeParam TResponseDto - Validated response DTO to return to the framework
+ * @typeParam TInDto - Input DTO type for the use case
+ * @typeParam TOutDto - Output DTO type from the use case
+ *
+ * @example Basic usage
+ * ```typescript
+ * const controller = BaseController.create({
+ *   requestMapper: (req) => CreateUserInputDto.create(req.data),
+ *   useCase: createUserUseCase,
+ *   responseMapper: (output) => CreateUserResponseDto.create({ id: output.data.id }),
+ * });
+ *
+ * // Framework layer creates the request DTO
+ * const requestDto = CreateUserRequestDto.create(httpRequest);
+ * const responseDto = await controller.execute(requestDto);
+ * ```
+ *
+ * @example Custom controller overriding pipeline
+ * ```typescript
+ * class LoggingController extends BaseController<...> {
+ *   protected override async pipeline(input: TRequestDto): Promise<TResponseDto> {
+ *     console.log('Request received:', input);
+ *     const result = await super.pipeline(input);
+ *     console.log('Response:', result);
+ *     return result;
+ *   }
+ * }
+ * ```
+ *
+ * @example Custom controller overriding individual methods
+ * ```typescript
+ * class CachingController extends BaseController<...> {
+ *   private cache = new Map();
+ *
+ *   protected override async executeUseCase(input: TInDto): Promise<TOutDto> {
+ *     const key = JSON.stringify(input.data);
+ *     if (this.cache.has(key)) return this.cache.get(key);
+ *     const result = await super.executeUseCase(input);
+ *     this.cache.set(key, result);
+ *     return result;
+ *   }
+ * }
+ * ```
+ */
+declare class BaseController<TRequestDto extends BaseDto<unknown>, TResponseDto extends BaseDto<unknown>, TInDto extends BaseDto<unknown>, TOutDto extends BaseDto<unknown>> {
+    protected readonly requestMapper: (request: TRequestDto) => TInDto;
+    protected readonly useCase: BaseInboundPort<TInDto, TOutDto>;
+    protected readonly responseMapper: (output: TOutDto) => TResponseDto;
+    /**
+     * Creates a new BaseController instance.
+     *
+     * @param requestMapper - Function to map request DTO to use case input DTO
+     * @param useCase - The use case port to execute
+     * @param responseMapper - Function to map use case output DTO to response DTO
+     */
+    constructor(requestMapper: (request: TRequestDto) => TInDto, useCase: BaseInboundPort<TInDto, TOutDto>, responseMapper: (output: TOutDto) => TResponseDto);
+    /**
+     * Factory method to create a controller from a configuration object.
+     *
+     * @param config - Controller configuration
+     * @returns A new BaseController instance
+     */
+    static create<TRequestDto extends BaseDto<unknown>, TResponseDto extends BaseDto<unknown>, TInDto extends BaseDto<unknown>, TOutDto extends BaseDto<unknown>>(config: BaseControllerConfig<TRequestDto, TResponseDto, TInDto, TOutDto>): BaseController<TRequestDto, TResponseDto, TInDto, TOutDto>;
+    /**
+     * Executes the controller pipeline with error wrapping.
+     *
+     * This is the public entry point that ensures consistent error handling.
+     * All errors are wrapped in {@link ControllerError} unless they extend {@link CodedError}.
+     *
+     * **Do not override this method.** Override {@link pipeline} instead for custom pipeline logic.
+     *
+     * @param input - The validated request DTO
+     * @returns Promise resolving to the validated response DTO
+     * @throws {InvalidRequestError} When request mapping/validation fails
+     * @throws {ControllerError} When an unexpected error occurs
+     * @throws {CodedError} When use case throws a known error type
+     */
+    execute(input: TRequestDto): Promise<TResponseDto>;
+    /**
+     * Runs the controller pipeline.
+     *
+     * Orchestrates: `mapRequest → executeUseCase → mapResponse`
+     *
+     * Override this method to customize the entire pipeline flow, or override
+     * individual protected methods ({@link mapRequest}, {@link executeUseCase},
+     * {@link mapResponse}) for more granular control.
+     *
+     * @param input - The validated request DTO
+     * @returns Promise resolving to the validated response DTO
+     */
+    protected pipeline(input: TRequestDto): Promise<TResponseDto>;
+    /**
+     * Maps the request DTO to a use case input DTO.
+     *
+     * Override to add custom pre-processing, logging, or transformation logic.
+     * The default implementation uses the configured `requestMapper` and converts
+     * {@link ObjectValidationError} to {@link InvalidRequestError}.
+     *
+     * @param input - The validated request DTO
+     * @returns The use case input DTO
+     * @throws {InvalidRequestError} When validation fails
+     * @throws {ControllerError} When mapping fails unexpectedly
+     */
+    protected mapRequest(input: TRequestDto): TInDto;
+    /**
+     * Executes the use case with the mapped input.
+     *
+     * Override to add custom logic around use case execution, such as:
+     * - Logging/tracing
+     * - Caching
+     * - Retry logic
+     * - Multi-use-case orchestration
+     *
+     * @param input - The use case input DTO
+     * @returns Promise resolving to the use case output DTO
+     */
+    protected executeUseCase(input: TInDto): Promise<TOutDto>;
+    /**
+     * Maps the use case output DTO to a response DTO.
+     *
+     * Override to add custom post-processing, logging, or transformation logic.
+     * The default implementation uses the configured `responseMapper`.
+     *
+     * @param output - The use case output DTO
+     * @returns The response DTO
+     * @throws {ControllerError} When mapping or validation fails
+     */
+    protected mapResponse(output: TOutDto): TResponseDto;
+}
+
+/**
+ * Result returned by an {@link AccessGuard} function.
+ *
+ * Represents the outcome of an authorization check, indicating whether
+ * access should be granted and optionally providing a reason for denial.
+ *
+ * **Usage with GuardedController:**
+ * - If `isAllowed: true`, the controller method executes normally
+ * - If `isAllowed: false`, throws {@link AccessDeniedError} with the reason
+ *
+ * @example Allowing access
+ * ```typescript
+ * const result: AccessGuardResult = {
+ *   isAllowed: true,
+ * };
+ * ```
+ *
+ * @example Denying access with reason
+ * ```typescript
+ * const result: AccessGuardResult = {
+ *   isAllowed: false,
+ *   reason: 'User does not have admin privileges',
+ * };
+ * ```
+ */
+interface AccessGuardResult {
+    /**
+     * Whether the request should be allowed to proceed.
+     *
+     * - `true`: Access granted, method executes
+     * - `false`: Access denied, throws {@link AccessDeniedError}
+     */
+    isAllowed: boolean;
+    /**
+     * Optional explanation for why access was denied.
+     *
+     * When `isAllowed` is `false`, this message is passed to
+     * {@link AccessDeniedError} and can be returned to the client.
+     * Defaults to "Access denied" if not provided.
+     */
+    reason?: string;
+}
+
+/**
+ * Access guard types for controller authorization.
+ *
+ * Provides type definitions for the authorization pattern used by
+ * {@link GuardedController}. Guards can be synchronous or asynchronous,
+ * enabling both simple checks and complex authorization logic.
+ *
+ * @example Synchronous guard (simple role check)
+ * ```typescript
+ * const adminGuard: AccessGuard<Request> = (req) => ({
+ *   isAllowed: req.user?.role === 'admin',
+ *   reason: 'Admin access required',
+ * });
+ * ```
+ *
+ * @example Asynchronous guard (database lookup)
+ * ```typescript
+ * const resourceOwnerGuard: AccessGuard<Request> = async (req) => {
+ *   const resource = await db.findById(req.resourceId);
+ *   return {
+ *     isAllowed: resource?.ownerId === req.user?.id,
+ *     reason: 'You do not own this resource',
+ *   };
+ * };
+ * ```
+ *
+ * @module
+ */
+
+/**
+ * Function type for authorization checks in controllers.
+ *
+ * An AccessGuard receives the incoming request and returns an
+ * {@link AccessGuardResult} indicating whether access should be granted.
+ * Guards can be synchronous or return a Promise for async operations.
+ *
+ * @typeParam T - The request type being guarded (defaults to `unknown`)
+ * @param request - The incoming request to evaluate
+ * @returns An {@link AccessGuardResult} or Promise resolving to one
+ *
+ * @example With GuardedController.create()
+ * ```typescript
+ * const controller = GuardedController.create({
+ *   accessGuard: (req) => ({
+ *     isAllowed: req.authenticated,
+ *     reason: 'Authentication required',
+ *   }),
+ *   requestMapper: (req) => MyInputDto.create(req),
+ *   useCase: myUseCase,
+ *   responseMapper: (out) => MyOutputDto.create(out),
+ * });
+ * ```
+ */
+type AccessGuard<T = unknown> = (request: T) => AccessGuardResult | Promise<AccessGuardResult>;
+
+/**
+ * Configuration for creating a GuardedController instance.
+ *
+ * All types must be DTOs (extending BaseDto) to ensure validation at every boundary.
+ *
+ * @typeParam TRequestDto - Validated request DTO from the framework layer
+ * @typeParam TResponseDto - Validated response DTO to return to the framework
+ * @typeParam TInDto - Input DTO type for the use case
+ * @typeParam TOutDto - Output DTO type from the use case
+ */
+interface GuardedControllerConfig<TRequestDto extends BaseDto<unknown>, TResponseDto extends BaseDto<unknown>, TInDto extends BaseDto<unknown>, TOutDto extends BaseDto<unknown>> {
+    /** Maps the validated request DTO to a use case input DTO. */
+    requestMapper: (request: TRequestDto) => TInDto;
+    /** The use case to execute. */
+    useCase: BaseInboundPort<TInDto, TOutDto>;
+    /** Maps the use case output DTO to a validated response DTO. */
+    responseMapper: (output: TOutDto) => TResponseDto;
+    /** Optional access guard; defaults to allowing all requests. */
+    accessGuard?: AccessGuard<TRequestDto>;
+}
+/**
+ * Controller with access control.
+ *
+ * Extends {@link BaseController} with an access guard that runs before
+ * the pipeline. If the guard denies access, an {@link AccessDeniedError}
+ * is thrown.
+ *
+ * All types must be DTOs (extending BaseDto) to ensure validation at every boundary.
+ *
+ * @typeParam TRequestDto - Validated request DTO from the framework layer
+ * @typeParam TResponseDto - Validated response DTO to return to the framework
+ * @typeParam TInDto - Input DTO type for the use case
+ * @typeParam TOutDto - Output DTO type from the use case
+ *
+ * @example
+ * ```typescript
+ * const controller = GuardedController.create({
+ *   requestMapper: (req) => UpdateUserInputDto.create(req.data),
+ *   useCase: updateUserUseCase,
+ *   responseMapper: (output) => UpdateUserResponseDto.create(output.data),
+ *   accessGuard: async (req) => ({
+ *     isAllowed: req.data.user?.role === 'admin',
+ *     reason: 'Admin access required',
+ *   }),
+ * });
+ * ```
+ */
+declare class GuardedController<TRequestDto extends BaseDto<unknown>, TResponseDto extends BaseDto<unknown>, TInDto extends BaseDto<unknown>, TOutDto extends BaseDto<unknown>> extends BaseController<TRequestDto, TResponseDto, TInDto, TOutDto> {
+    /** The access guard function for this controller. */
+    protected readonly accessGuard: AccessGuard<TRequestDto>;
+    /**
+     * Creates a new GuardedController instance.
+     *
+     * @param requestMapper - Function to map request DTO to use case input DTO
+     * @param useCase - The use case port to execute
+     * @param responseMapper - Function to map use case output DTO to response DTO
+     * @param accessGuard - Optional access guard; defaults to allowing all
+     */
+    constructor(requestMapper: (request: TRequestDto) => TInDto, useCase: BaseInboundPort<TInDto, TOutDto>, responseMapper: (output: TOutDto) => TResponseDto, accessGuard?: AccessGuard<TRequestDto>);
+    /**
+     * Factory method to create a guarded controller from a configuration object.
+     *
+     * @param config - Controller configuration including optional access guard
+     * @returns A new GuardedController instance
+     */
+    static create<TRequestDto extends BaseDto<unknown>, TResponseDto extends BaseDto<unknown>, TInDto extends BaseDto<unknown>, TOutDto extends BaseDto<unknown>>(config: GuardedControllerConfig<TRequestDto, TResponseDto, TInDto, TOutDto>): GuardedController<TRequestDto, TResponseDto, TInDto, TOutDto>;
+    /**
+     * Runs the controller pipeline with access control.
+     *
+     * Checks the access guard before executing the pipeline.
+     * If denied, throws {@link AccessDeniedError}.
+     *
+     * @param input - The validated request DTO
+     * @returns Promise resolving to the validated response DTO
+     * @throws {AccessDeniedError} When access guard denies the request
+     */
+    protected pipeline(input: TRequestDto): Promise<TResponseDto>;
+    /**
+     * Checks access using the configured guard.
+     *
+     * Override to customize access control logic.
+     *
+     * @param input - The validated request DTO
+     * @throws {AccessDeniedError} When access is denied
+     */
+    protected checkAccess(input: TRequestDto): Promise<void>;
+}
+
+/**
+ * Error thrown when access to a resource is denied.
+ *
+ * Indicates that the requester does not have permission to perform
+ * the requested operation. Thrown by {@link GuardedController} when
+ * an access guard returns `isAllowed: false`.
+ *
+ * **When thrown:**
+ * - Access guard denies the request
+ * - User lacks required permissions
+ * - Resource ownership check fails
+ *
+ * @example GuardedController usage
+ * ```typescript
+ * const controller = GuardedController.create({
+ *   accessGuard: (req) => ({
+ *     isAllowed: req.user?.role === 'admin',
+ *     reason: 'Admin access required',
+ *   }),
+ *   // ... other config
+ * });
+ * ```
+ *
+ * @example Manual usage
+ * ```typescript
+ * if (!user.canAccess(resource)) {
+ *   throw new AccessDeniedError({
+ *     message: 'You do not have access to this resource',
+ *     code: 'RESOURCE_ACCESS_DENIED',
+ *   });
+ * }
+ * ```
+ *
+ * @extends CodedError
+ */
+declare class AccessDeniedError extends CodedError {
+    /**
+     * Creates a new AccessDeniedError instance.
+     *
+     * @param options - Error configuration
+     * @param options.message - Description of why access was denied
+     * @param options.code - Machine-readable error code (default: 'ACCESS_DENIED')
+     * @param options.cause - Optional underlying error
+     */
+    constructor({ message, code, cause, }: {
+        message: string;
+        code?: PresentationErrorCode | string;
+        cause?: unknown;
+    });
+    /**
+     * Creates an AccessDeniedError from a caught error.
+     *
+     * @param cause - The original caught error
+     * @returns A new AccessDeniedError instance with the cause attached
+     */
+    static fromError(cause: unknown): AccessDeniedError;
+}
+
+/**
+ * Base error class for presentation layer (controller) failures.
+ *
+ * Controller errors represent failures in request handling,
+ * such as access control violations or malformed requests.
+ * They are the outermost error layer and typically map to HTTP responses.
+ *
+ * **When to throw:**
+ * - Access control failures (unauthorized/forbidden)
+ * - Request validation failures
+ * - Unexpected controller execution errors
+ *
+ * **Child classes:**
+ * - {@link AccessDeniedError} - Authorization failures (HTTP 403)
+ * - {@link InvalidRequestError} - Request validation failures (HTTP 400)
+ *
+ * @example
+ * ```typescript
+ * // Thrown automatically by BaseController for unexpected errors
+ * throw new ControllerError({
+ *   message: 'Controller execution failed',
+ *   cause: originalError,
+ * });
+ * ```
+ */
+declare class ControllerError extends CodedError {
+    /**
+     * Creates a new ControllerError instance.
+     *
+     * @param options - Error configuration
+     * @param options.message - Human-readable error description
+     * @param options.code - Machine-readable error code (default: 'CONTROLLER_ERROR')
+     * @param options.cause - Optional underlying error
+     */
+    constructor({ message, code, cause, }: {
+        message: string;
+        code?: PresentationErrorCode | string;
+        cause?: unknown;
+    });
+    /**
+     * Creates a ControllerError from a caught error.
+     *
+     * @param cause - The original caught error
+     * @returns A new ControllerError instance with the cause attached
+     */
+    static fromError(cause: unknown): ControllerError;
+}
+
+/**
+ * Error thrown when request validation fails at the controller level.
+ *
+ * Contains structured validation errors with field paths and messages,
+ * converted from {@link ObjectValidationError} by {@link BaseController}.
+ * Provides detailed feedback about which fields failed validation.
+ *
+ * **When thrown:**
+ * - Request DTO validation fails
+ * - Malformed request data
+ * - Missing required fields
+ *
+ * @example
+ * ```typescript
+ * // Automatically thrown by BaseController when DTO validation fails
+ * // The validationErrors array contains field-level details:
+ * // [
+ * //   { field: 'email', message: 'Invalid email format' },
+ * //   { field: 'age', message: 'Must be a positive number' }
+ * // ]
+ * ```
+ *
+ * @example Manual usage
+ * ```typescript
+ * throw new InvalidRequestError({
+ *   message: 'Request validation failed',
+ *   validationErrors: [
+ *     { field: 'username', message: 'Username is required' },
+ *   ],
+ * });
+ * ```
+ *
+ * @extends CodedError
+ */
+declare class InvalidRequestError extends CodedError {
+    /**
+     * Array of field-level validation errors.
+     *
+     * Each entry contains:
+     * - `field`: Dot-notation path to the invalid field
+     * - `message`: Human-readable validation failure message
+     */
+    readonly validationErrors: ValidationError[];
+    /**
+     * Creates a new InvalidRequestError instance.
+     *
+     * @param options - Error configuration
+     * @param options.message - Summary of the validation failure
+     * @param options.code - Machine-readable error code (default: 'INVALID_REQUEST')
+     * @param options.cause - Optional underlying error
+     * @param options.validationErrors - Array of field-level validation errors
+     */
+    constructor({ message, code, cause, validationErrors, }: {
+        message: string;
+        code?: PresentationErrorCode | string;
+        cause?: unknown;
+        validationErrors: ValidationError[];
+    });
+    /**
+     * Creates an InvalidRequestError from a caught error.
+     *
+     * @param cause - The original caught error
+     * @returns A new InvalidRequestError instance with the cause attached
+     */
+    static fromError(cause: unknown): InvalidRequestError;
+}
+
+/**
+ * Enhanced request wrapper with metadata and context.
+ *
+ * Provides a generic structure for wrapping any request type with
+ * additional metadata (e.g., trace ID, timestamp) and execution context
+ * (e.g., authenticated user, permissions).
+ *
+ * This is a presentation-layer concern as it represents how external
+ * systems (HTTP, Kafka, WebSocket, gRPC, CLI, etc.) interact with
+ * our services.
+ *
+ * @typeParam TMetadata - Request metadata type (e.g., trace ID, correlation ID)
+ * @typeParam TContext - Execution context type (e.g., auth user, API key, permissions)
+ * @typeParam TRequest - The actual request payload type
+ *
+ * @example
+ * ```typescript
+ * interface RequestMetadata {
+ *   traceId: string;
+ *   timestamp: Date;
+ * }
+ *
+ * interface UserContext {
+ *   userId: string;
+ *   roles: string[];
+ * }
+ *
+ * type MyEnhancedRequest = EnhancedRequest<RequestMetadata, UserContext, HttpRequest>;
+ *
+ * const request: MyEnhancedRequest = {
+ *   metadata: { traceId: 'abc-123', timestamp: new Date() },
+ *   context: { userId: 'user-1', roles: ['admin'] },
+ *   request: { body: { name: 'John' } },
+ * };
+ * ```
+ */
+interface EnhancedRequest<TMetadata, TContext, TRequest> {
+    /**
+     * Request metadata containing operational information.
+     * Typically includes trace IDs, timestamps, and other observability data.
+     */
+    metadata: TMetadata;
+    /**
+     * Execution context containing authorization and identity information.
+     * Typically includes authenticated user data, permissions, and API key info.
+     */
+    context: TContext;
+    /**
+     * The actual request payload.
+     * Contains the business-relevant data from the incoming request.
+     */
+    request: TRequest;
+}
+
+/**
+ * Enhanced HTTP request with metadata and context.
+ *
+ * A specialized version of {@link EnhancedRequest} where the request payload
+ * is fixed to {@link HttpRequest}. This is the standard type for HTTP-based
+ * frameworks (AWS API Gateway, Cloudflare Workers, Express, etc.).
+ *
+ * @typeParam TMetadata - Request metadata type (e.g., request ID, correlation ID)
+ * @typeParam TContext - Execution context type (e.g., authenticated user, API key)
+ *
+ * @example AWS API Gateway usage
+ * ```typescript
+ * interface AwsMetadata {
+ *   requestId: string;
+ *   stage: string;
+ * }
+ *
+ * interface AuthorizerContext {
+ *   userId: string;
+ *   permissions: string[];
+ * }
+ *
+ * type AwsEnhancedRequest = EnhancedHttpRequest<AwsMetadata, AuthorizerContext>;
+ *
+ * const request: AwsEnhancedRequest = {
+ *   metadata: { requestId: 'req-123', stage: 'prod' },
+ *   context: { userId: 'user-1', permissions: ['read', 'write'] },
+ *   request: {
+ *     body: { name: 'John' },
+ *     headers: { 'content-type': 'application/json' },
+ *     pathParams: { id: '123' },
+ *     queryParams: { limit: '10' },
+ *   },
+ * };
+ * ```
+ */
+type EnhancedHttpRequest<TMetadata, TContext> = EnhancedRequest<TMetadata, TContext, HttpRequest>;
+
+/**
+ * Service metadata.
+ *
+ * Describes a service (bounded context / API surface) in a stable, serializable way.
+ *
+ * Intended use:
+ * - building OpenAPI specs (grouping, base paths)
+ * - generating clients/docs
+ * - consistent identification across repos
+ */
+interface ServiceMetadata {
+    /**
+     * Stable identifier for the service.
+     *
+     * Recommendation: kebab-case and unique across the system.
+     * Example: `user-service`
+     */
+    id: string;
+    /**
+     * Short identifier used in logs, URLs, or UI labels.
+     *
+     * Recommendation: short kebab-case.
+     * Example: `user`
+     */
+    shortId: string;
+    /**
+     * Human-readable service name.
+     *
+     * Example: `User Service`
+     */
+    name: string;
+    /**
+     * Human-readable description of the service.
+     */
+    description: string;
+    /**
+     * Service base path prefix used to namespace HTTP routes.
+     *
+     * Example: `/user-service`
+     */
+    basePath: string;
+    /**
+     * OpenAPI-specific configuration for per-service spec generation.
+     */
+    openApi: {
+        /**
+         * OpenAPI info.title for per-service spec.
+         *
+         * Example: `User Service API`
+         */
+        title: string;
+        /**
+         * OpenAPI info.description for per-service spec.
+         * If not set, uses the service's `description`.
+         */
+        description?: string;
+    };
+}
+
+/**
+ * Resource metadata.
+ *
+ * A "resource" is a group of endpoints inside a service (often aligned with a domain aggregate
+ * or a REST-ish resource folder like `organization-membership-invite`).
+ *
+ * Intended use:
+ * - OpenAPI tags (2nd-level grouping)
+ * - stable tag naming/ordering independent of folder name changes
+ */
+interface ResourceMetadata {
+    /**
+     * Stable identifier for the resource.
+     *
+     * Recommendation: kebab-case and matches its folder name.
+     * Example: `organization-membership-invite`
+     */
+    id: string;
+    /**
+     * Short identifier used in logs or metrics.
+     *
+     * Recommendation: short kebab-case.
+     * Example: `org-invite`
+     */
+    shortId: string;
+    /**
+     * Human-readable resource name.
+     *
+     * Example: `Organization Membership Invite`
+     */
+    name: string;
+    /**
+     * Human-readable description of the resource.
+     */
+    description: string;
+    /**
+     * Resource path segment (relative to service basePath).
+     *
+     * Combined with service basePath and endpoint path to form the full route.
+     *
+     * Example: `/users`
+     */
+    path: string;
+    /**
+     * Explicit ordering for UI grouping within the service.
+     *
+     * Lower numbers come first.
+     */
+    order: number;
+    /**
+     * OpenAPI-specific configuration for tag generation.
+     */
+    openApi: {
+        /**
+         * OpenAPI tag display name.
+         *
+         * Example: `Organization Membership Invite`
+         */
+        tag: string;
+        /**
+         * OpenAPI tag description shown in documentation.
+         */
+        tagDescription: string;
+    };
+}
+
+/**
+ * System metadata.
+ *
+ * Top-level metadata for the whole API surface ("the system"), sitting above
+ * individual services/resources/endpoints.
+ *
+ * This is intentionally stable and serializable so it can be consumed by tools
+ * (OpenAPI generation, docs, code generation).
+ */
+/**
+ * API Key authentication scheme (header, query, or cookie).
+ */
+interface ApiKeyAuthScheme {
+    type: 'apiKey';
+    in: 'header' | 'query' | 'cookie';
+    /** Header/query/cookie parameter name, e.g. 'x-api-key' */
+    name: string;
+    description?: string;
+}
+/**
+ * HTTP Bearer authentication scheme.
+ */
+interface HttpBearerAuthScheme {
+    type: 'http';
+    scheme: 'bearer';
+    bearerFormat?: string;
+    description?: string;
+}
+/**
+ * HTTP Basic authentication scheme.
+ */
+interface HttpBasicAuthScheme {
+    type: 'http';
+    scheme: 'basic';
+    description?: string;
+}
+/**
+ * Union of all supported authentication schemes.
+ */
+type AuthScheme = ApiKeyAuthScheme | HttpBearerAuthScheme | HttpBasicAuthScheme;
+interface SystemMetadata {
+    /**
+     * Stable system identifier.
+     *
+     * Recommendation: kebab-case.
+     * Example: `acmp-connector`
+     */
+    id: string;
+    /**
+     * Short identifier for compact displays/logging.
+     *
+     * Example: `acmp`
+     */
+    shortId: string;
+    /**
+     * Human-readable system name.
+     *
+     * Example: `ACMP Connector`
+     */
+    name: string;
+    /**
+     * Human-readable description.
+     */
+    description?: string;
+    /**
+     * System/API version (SemVer recommended).
+     *
+     * Example: `1.0.0`
+     */
+    version: string;
+    /**
+     * Default servers for the API.
+     * Used by OpenAPI generation and client configuration.
+     */
+    servers?: {
+        url: string;
+        description?: string;
+    }[];
+    /**
+     * Authentication configuration.
+     */
+    auth?: {
+        /**
+         * Whether endpoints should be considered secure by default.
+         * @default true
+         */
+        secureByDefault?: boolean;
+        /**
+         * Available authentication schemes.
+         *
+         * Keyed by scheme name (must be unique within the system).
+         * Example: `{ apiKeyAuth: { type: 'apiKey', in: 'header', name: 'x-api-key' } }`
+         */
+        schemes: Record<string, AuthScheme>;
+        /**
+         * Default security requirements (applies to all secure endpoints).
+         *
+         * OpenAPI semantics:
+         * - Array is OR (any requirement can satisfy)
+         * - Object is AND (all schemes required together)
+         *
+         * Example: `[{ apiKeyAuth: [] }]`
+         */
+        defaultSecurity?: Record<string, string[]>[];
+    };
+    /**
+     * OpenAPI-specific overrides for global spec generation.
+     */
+    openApi?: {
+        /**
+         * OpenAPI info.title.
+         * Overrides `name` if set.
+         */
+        title?: string;
+        /**
+         * OpenAPI info.description.
+         * Overrides `description` if set.
+         */
+        description?: string;
+        /**
+         * OpenAPI info.termsOfService URL.
+         */
+        termsOfService?: string;
+        /**
+         * OpenAPI info.contact.
+         */
+        contact?: {
+            name?: string;
+            url?: string;
+            email?: string;
+        };
+        /**
+         * OpenAPI info.license.
+         */
+        license?: {
+            name: string;
+            url?: string;
+        };
+    };
+}
+/**
+ * Extracts the scheme names (keys) from a SystemMetadata constant.
+ *
+ * @example
+ * const systemMeta = { auth: { schemes: { apiKeyAuth: {...}, bearerAuth: {...} } } } as const;
+ * type Names = SchemeNamesOf<typeof systemMeta>; // 'apiKeyAuth' | 'bearerAuth'
+ */
+type SchemeNamesOf<TSystem> = TSystem extends {
+    auth: {
+        schemes: infer S;
+    };
+} ? keyof S & string : never;
+/**
+ * Creates a typed OpenAPI security requirement array from scheme names.
+ *
+ * @example
+ * type Req = SecurityRequirementOf<'apiKeyAuth' | 'bearerAuth'>;
+ * // Array<Partial<Record<'apiKeyAuth' | 'bearerAuth', string[]>>>
+ */
+type SecurityRequirementOf<TSchemeNames extends string> = Partial<Record<TSchemeNames, string[]>>[];
+/**
+ * Input type for defineSystemMetadata helper (with generic auth).
+ */
+type SystemMetadataInput<TSchemeNames extends string> = Omit<SystemMetadata, 'auth'> & {
+    auth?: {
+        secureByDefault?: boolean;
+        schemes: Record<TSchemeNames, AuthScheme>;
+        defaultSecurity?: Partial<Record<TSchemeNames, string[]>>[];
+    };
+};
+/**
+ * Defines system metadata with fully-typed `defaultSecurity`.
+ *
+ * Infers scheme names from the `schemes` object and validates that
+ * `defaultSecurity` only references existing scheme names.
+ *
+ * @example
+ * export const systemMetadata = defineSystemMetadata({
+ *   id: 'my-api',
+ *   shortId: 'api',
+ *   name: 'My API',
+ *   version: '1.0.0',
+ *   auth: {
+ *     schemes: {
+ *       apiKeyAuth: { type: 'apiKey', in: 'header', name: 'x-api-key' },
+ *     },
+ *     defaultSecurity: [{ apiKeyAuth: [] }],  // ✅ Valid
+ *     // defaultSecurity: [{ typoAuth: [] }], // ❌ TypeScript error!
+ *   },
+ * });
+ */
+declare function defineSystemMetadata<const TSchemeNames extends string>(metadata: SystemMetadataInput<TSchemeNames>): SystemMetadataInput<TSchemeNames> & SystemMetadata;
+
+/**
+ * Allowed HTTP methods for endpoint metadata.
+ */
+type HttpEndpointMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+/**
+ * Allowed HTTP success status codes.
+ */
+type HttpSuccessStatus = 200 | 201 | 202 | 204;
+/**
+ * OpenAPI-specific fields for endpoint metadata (loosely typed).
+ */
+interface HttpEndpointOpenApi {
+    /**
+     * OpenAPI operation summary.
+     * Overrides `description` for the summary field if set.
+     */
+    summary?: string;
+    /**
+     * OpenAPI operation description (detailed).
+     * Overrides `description` for the description field if set.
+     */
+    description?: string;
+    /**
+     * Explicit OpenAPI operationId.
+     * Defaults to endpoint `name` if not set.
+     */
+    operationId?: string;
+    /**
+     * Override resource tag(s) for this endpoint.
+     * Defaults to resource's openApi.tag or name if not set.
+     */
+    tags?: string[];
+    /**
+     * Mark endpoint as deprecated in OpenAPI documentation.
+     * @default false
+     */
+    deprecated?: boolean;
+    /**
+     * HTTP success status code for OpenAPI documentation.
+     *
+     * @default Derived from HTTP method:
+     * - GET: 200
+     * - POST: 201
+     * - PUT: 200
+     * - PATCH: 200
+     * - DELETE: 204
+     */
+    successStatus?: HttpSuccessStatus;
+    /**
+     * Explicit OpenAPI `security` requirements for this endpoint.
+     *
+     * OpenAPI semantics:
+     * - The array is OR (any requirement can satisfy).
+     * - Each object is AND (all schemes in the object are required together).
+     *
+     * Examples:
+     * - Public endpoint (overrides any global security): `[]`
+     * - Require api key: `[ { apiKeyAuth: [] } ]`
+     * - Allow either api key OR bearer: `[ { apiKeyAuth: [] }, { bearerAuth: [] } ]`
+     */
+    security?: Record<string, string[]>[];
+}
+/**
+ * OpenAPI-specific fields for endpoint metadata (strongly typed security).
+ */
+interface HttpEndpointOpenApiFor<TSystem> extends Omit<HttpEndpointOpenApi, 'security'> {
+    /**
+     * Explicit OpenAPI `security` requirements for this endpoint.
+     * Scheme names are validated against the system metadata at compile time.
+     */
+    security?: SecurityRequirementOf<SchemeNamesOf<TSystem>>;
+}
+/**
+ * HTTP endpoint metadata.
+ *
+ * Describes an HTTP endpoint in a stable, serializable way.
+ *
+ * Intended use:
+ * - documentation (OpenAPI generation)
+ * - HTTP client generation
+ * - consistent endpoint identification (id/shortId)
+ */
+interface HttpEndpointMetadata {
+    /**
+     * Stable endpoint identifier.
+     *
+     * Recommendation: kebab-case.
+     * Example: `get-user-by-id`
+     */
+    id: string;
+    /**
+     * Short endpoint identifier.
+     *
+     * Useful for logs/metrics.
+     * Example: `gubi`
+     */
+    shortId: string;
+    /**
+     * Stable endpoint name used in code.
+     *
+     * Recommendation: camelCase.
+     * Example: `getUserById`
+     */
+    name: string;
+    /**
+     * Human-readable description.
+     *
+     * Used as default for OpenAPI summary/description.
+     */
+    description: string;
+    /**
+     * Endpoint-relative path (without service or resource path).
+     *
+     * Combined with service basePath and resource path to form the full route.
+     * Use `computeRoutePath()` to compute the full path when needed.
+     *
+     * Example: `/{id}` or `/` for collection endpoints
+     */
+    path: string;
+    /**
+     * HTTP method.
+     */
+    method: HttpEndpointMethod;
+    /**
+     * OpenAPI-specific overrides for this endpoint.
+     */
+    openApi?: HttpEndpointOpenApi;
+}
+/**
+ * HTTP endpoint metadata with strongly-typed `openApi.security`.
+ *
+ * Use this to get compile-time validation of security scheme names
+ * against a SystemMetadata constant.
+ *
+ * @example
+ * import type { HttpEndpointMetadataFor } from '@cosmneo/org-lib-backend-common-kit';
+ * import { systemMetadata } from '@/contracts/system-metadata';
+ *
+ * export const getUserHttpMetadata: HttpEndpointMetadataFor<typeof systemMetadata> = {
+ *   id: 'get-user',
+ *   // ...
+ *   openApi: {
+ *     security: [{ apiKeyAuth: [] }],  // ✅ Compile-time checked!
+ *   },
+ * };
+ */
+interface HttpEndpointMetadataFor<TSystem> extends Omit<HttpEndpointMetadata, 'openApi'> {
+    /**
+     * OpenAPI-specific overrides for this endpoint (with typed security).
+     */
+    openApi?: HttpEndpointOpenApiFor<TSystem>;
+}
+
+/**
+ * Computes the full route path from service, resource, and endpoint metadata.
+ *
+ * Handles path normalization:
+ * - Ensures leading slash
+ * - Joins segments with single slashes
+ * - Removes trailing slash (except for root)
+ *
+ * @example
+ * ```typescript
+ * computeRoutePath(
+ *   { basePath: '/user-service' },
+ *   { path: '/users' },
+ *   { path: '/{id}' }
+ * ); // => '/user-service/users/{id}'
+ * ```
+ */
+declare function computeRoutePath(service: Pick<ServiceMetadata, 'basePath'>, resource: Pick<ResourceMetadata, 'path'>, endpoint: Pick<HttpEndpointMetadata, 'path'>): string;
+
+/**
+ * Type guard to validate that a value is a valid HttpResponse.
+ *
+ * Checks that the value has the required `statusCode` property as a number.
+ * This is used to validate controller outputs before passing to response mappers.
+ *
+ * @param value - The value to check
+ * @returns True if the value is a valid HttpResponse
+ *
+ * @example
+ * ```typescript
+ * const output = controller.execute(input);
+ * if (!isHttpResponse(output)) {
+ *   throw new Error('Controller must return an HttpResponse');
+ * }
+ * ```
+ */
+declare function isHttpResponse(value: unknown): value is HttpResponse;
+/**
+ * Asserts that a value is a valid HttpResponse.
+ *
+ * Throws a descriptive error if the value is not a valid HttpResponse,
+ * making it easier to debug controller output issues.
+ *
+ * @param value - The value to validate
+ * @param context - Optional context for the error message (e.g., 'mapOutput')
+ * @throws Error if the value is not a valid HttpResponse
+ *
+ * @example
+ * ```typescript
+ * const output = controller.execute(input);
+ * assertHttpResponse(output, 'controller output');
+ * // Now TypeScript knows output is HttpResponse
+ * ```
+ */
+declare function assertHttpResponse(value: unknown, context?: string): asserts value is HttpResponse;
+
+export { AccessDeniedError as A, type BaseInboundPort as B, ControllerError as C, type EnhancedHttpRequest as E, type GuardedControllerConfig as G, type HttpEndpointMethod as H, InvalidRequestError as I, type ResourceMetadata as R, type ServiceMetadata as S, type BaseControllerConfig as a, BaseController as b, GuardedController as c, type AccessGuard as d, type AccessGuardResult as e, type EnhancedRequest as f, type HttpSuccessStatus as g, type HttpEndpointOpenApi as h, type HttpEndpointOpenApiFor as i, type HttpEndpointMetadata as j, type HttpEndpointMetadataFor as k, type ApiKeyAuthScheme as l, type HttpBearerAuthScheme as m, type HttpBasicAuthScheme as n, type AuthScheme as o, type SystemMetadata as p, type SchemeNamesOf as q, type SecurityRequirementOf as r, defineSystemMetadata as s, computeRoutePath as t, isHttpResponse as u, assertHttpResponse as v };