declare const HTTP_STATUS: {
    readonly OK: 200;
    readonly CREATED: 201;
    readonly NO_CONTENT: 204;
    readonly BAD_REQUEST: 400;
    readonly UNAUTHORIZED: 401;
    readonly FORBIDDEN: 403;
    readonly NOT_FOUND: 404;
    readonly CONFLICT: 409;
    readonly UNPROCESSABLE_ENTITY: 422;
    readonly INTERNAL_SERVER_ERROR: 500;
    readonly SERVER_ERROR: 500;
};
type HttpStatusCode = (typeof HTTP_STATUS)[keyof typeof HTTP_STATUS];
declare const statusCode: {
    readonly OK: 200;
    readonly CREATED: 201;
    readonly NO_CONTENT: 204;
    readonly BAD_REQUEST: 400;
    readonly UNAUTHORIZED: 401;
    readonly FORBIDDEN: 403;
    readonly NOT_FOUND: 404;
    readonly CONFLICT: 409;
    readonly UNPROCESSABLE_ENTITY: 422;
    readonly INTERNAL_SERVER_ERROR: 500;
    readonly SERVER_ERROR: 500;
};

interface AppErrorOptions {
    message: string;
    statusCode?: number;
    code?: string;
    details?: unknown;
}
declare class AppError extends Error {
    readonly statusCode: number;
    readonly code: string;
    readonly details: unknown;
    readonly isOperational: boolean;
    constructor(options: AppErrorOptions);
}

declare class BadRequestError extends AppError {
    constructor(message?: string, details?: unknown);
}
declare class UnauthorizedError extends AppError {
    constructor(message?: string, details?: unknown);
}
declare class ForbiddenError extends AppError {
    constructor(message?: string, details?: unknown);
}
declare class NotFoundError extends AppError {
    constructor(message?: string, details?: unknown);
}
declare class ConflictError extends AppError {
    constructor(message?: string, details?: unknown);
}
declare class ValidationError extends AppError {
    constructor(message?: string, details?: unknown);
}

type SortOrder = "asc" | "desc";
type QueryValue = string | number | boolean | null | undefined;
interface SortQuery {
    sortBy?: QueryValue;
    sortOrder?: SortOrder | string | null;
}
type FilterQuery = Record<string, unknown>;
interface SearchQuery {
    q?: QueryValue;
    search?: QueryValue;
}

/** Picks only developer-approved filter fields from a query object. */
declare function getFilters<TAllowedField extends string>(query: FilterQuery, allowedFields: readonly TAllowedField[]): Partial<Record<TAllowedField, unknown>>;

type AsyncRequestHandler<TRequest = unknown, TResponse = unknown, TNext = unknown> = (req: TRequest, res: TResponse, next: TNext) => Promise<unknown> | unknown;
/** Wraps async route handlers and forwards rejected promises to next(). */
declare function asyncHandler<TRequest = unknown, TResponse = unknown>(handler: AsyncRequestHandler<TRequest, TResponse, (error?: unknown) => void>): (req: TRequest, res: TResponse, next: (error?: unknown) => void) => void;

interface ErrorResponseLike {
    headersSent?: boolean;
    status(code: number): ErrorResponseLike;
    json(body: unknown): unknown;
}
type NextFunctionLike = (error?: unknown) => void;
/** Express-compatible error middleware that emits standard JSON errors. */
declare function errorMiddleware(error: unknown, _req: unknown, res: ErrorResponseLike, next: NextFunctionLike): unknown;

/** Express-compatible middleware that forwards unmatched routes as NotFoundError. */
declare function notFoundMiddleware(req: {
    originalUrl?: string;
    url?: string;
}, _res: unknown, next: (error?: unknown) => void): void;

interface LoggerRequest {
    method?: string;
    originalUrl?: string;
    url?: string;
    ip?: string;
    baseUrl?: string;
    path?: string;
    body?: unknown;
    route?: {
        path?: unknown;
        stack?: Array<{
            name?: string;
            handle?: unknown;
        }>;
    };
    headers?: Record<string, string | string[] | undefined>;
    get?: (name: string) => string | undefined;
    user?: unknown;
}
interface LoggerResponse {
    statusCode?: number;
    on?: (event: "finish", listener: () => void) => unknown;
    json?: (body: unknown) => unknown;
}
type LoggerNext = () => void;
interface LoggerOptions {
    enabled?: boolean;
    projectName?: string;
    includeRequestFrom?: boolean;
    includeIp?: boolean;
    includeUserAgent?: boolean;
    includeRouteContext?: boolean;
    includeRequestData?: boolean;
    includeResponseData?: boolean;
    maxRequestDataLength?: number;
    maxResponseDataLength?: number;
    redactFields?: readonly string[];
    controllerFileSuffix?: string;
    sourceFile?: string;
    sourceMethod?: string;
    getSourceFile?: (req: LoggerRequest) => string | undefined;
    getSourceMethod?: (req: LoggerRequest) => string | undefined;
    getUser?: (req: LoggerRequest) => string | undefined;
    log?: (message: string) => void;
    logger?: (message: string) => void;
}
type LoggerConfig = LoggerOptions;
type RequestLoggerRequest = LoggerRequest;
type RequestLoggerResponse = LoggerResponse;
type RequestLoggerNext = LoggerNext;
type RequestLoggerOptions = LoggerOptions;
type RequestLoggerConfig = LoggerConfig;
declare function configureLogger(config: LoggerConfig): void;
declare function resetLoggerConfig(): void;
declare function formatRequestLog(input: {
    projectName?: string;
    method?: string;
    url?: string;
    statusCode?: number;
    durationMs: number;
    timestamp?: string;
    requestFrom?: string;
    ip?: string;
    userAgent?: string;
    sourceFile?: string;
    sourceMethod?: string;
    user?: string;
    requestData?: string;
    responseData?: string;
}): string;
declare function logger(options?: LoggerOptions): (req: LoggerRequest, res: LoggerResponse, next: LoggerNext) => void;
declare const requestLogger: typeof logger;

interface PaginationQuery {
    max?: QueryValue;
    offset?: QueryValue;
    sortBy?: QueryValue;
    sortOrder?: SortOrder | string | null;
}
interface PaginationOptions {
    defaultMax?: number;
    maxMax?: number;
}
interface NormalizedPagination {
    max: number;
    offset: number;
    sortBy?: string;
    sortOrder?: SortOrder;
}
interface PaginationMeta {
    max: number;
    offset: number;
    total: number;
    hasNextPage: boolean;
    hasPreviousPage: boolean;
}
interface PaginatedData<T> {
    data: T[];
    total: number;
}

/** Normalizes raw pagination query parameters into safe numeric values. */
declare function normalizePaginationQuery(query?: PaginationQuery, options?: PaginationOptions): NormalizedPagination;
/** Returns normalized pagination settings for repository or service queries. */
declare function getPagination(query?: PaginationQuery, options?: PaginationOptions): NormalizedPagination;
/** Slices an array using normalized pagination and includes the full total. */
declare function paginate<T>(items: T[], pagination: Pick<NormalizedPagination, "max" | "offset">): PaginatedData<T>;
/** Builds pagination metadata for API responses. */
declare function getPaginationMeta(input: {
    max?: number;
    offset?: number;
    total: number;
}): PaginationMeta;

interface ApiError {
    success: false;
    message: string;
    error: string;
    details?: unknown;
    timestamp: string;
}

interface ErrorResponseInput {
    message?: string;
    code?: string;
    details?: unknown;
}
/** Creates a standard failed JSON API response. */
declare function errorResponse(input?: ErrorResponseInput): ApiError;

interface ApiResponse<T = unknown> {
    success: true;
    message: string;
    data: T;
    timestamp: string;
}
interface ValidationErrorItem {
    field: string;
    message: string;
}
interface PaginatedResponse<T = unknown> extends ApiResponse<T[]> {
    total: number;
}

interface PaginatedResponseInput<T> {
    message?: string;
    data?: T[];
    max?: number;
    offset?: number;
    total: number;
}
interface PaginatedResponseWithMetaInput<T> {
    message?: string;
    data?: T[];
    meta: {
        max?: number;
        offset?: number;
        total: number;
    };
}
/** Creates a standard successful response with pagination metadata. */
declare function paginatedResponse<T = unknown>(input: PaginatedResponseInput<T> | PaginatedResponseWithMetaInput<T>): PaginatedResponse<T>;

interface SuccessResponseInput<T> {
    message?: string;
    data?: T;
    total?: number;
}
interface ResponseInput<T> extends SuccessResponseInput<T> {
    statusCode?: HttpStatusCode;
    total?: number;
}
type ResponseResult<T> = ApiResponse<T | Record<string, never>> & {
    statusCode: HttpStatusCode;
    total: number;
};
type SuccessResponseResult<T> = ApiResponse<T | Record<string, never>> & {
    total: number;
};
/** Creates a standard successful JSON API response. */
declare function successResponse<T = unknown>(input?: SuccessResponseInput<T>): SuccessResponseResult<T>;
/** Creates a simple successful JSON API response from data or an input object. */
declare function response<T = unknown>(input?: T | ResponseInput<T>, statusMessageOrTotal?: HttpStatusCode | string | number, messageOrTotal?: string | number, total?: number): ResponseResult<T>;

interface ValidationErrorResponse {
    success: false;
    message: string;
    errors: ValidationErrorItem[];
    timestamp: string;
}
interface ValidationErrorResponseInput {
    message?: string;
    errors?: ValidationErrorItem[];
}
/** Creates a standard validation error response. */
declare function validationErrorResponse(input?: ValidationErrorResponseInput): ValidationErrorResponse;

/** Extracts a search keyword from q or search query parameters. */
declare function getSearch(query?: SearchQuery): {
    keyword?: string;
};

/** Normalizes sorting query parameters. */
declare function getSorting(query?: SortQuery): {
    sortBy?: string;
    sortOrder: SortOrder;
};

export { type ApiError, type ApiResponse, AppError, type AppErrorOptions, type AsyncRequestHandler, BadRequestError, ConflictError, type ErrorResponseInput, type FilterQuery, ForbiddenError, HTTP_STATUS, type HttpStatusCode, type LoggerConfig, type LoggerNext, type LoggerOptions, type LoggerRequest, type LoggerResponse, type NormalizedPagination, NotFoundError, type PaginatedData, type PaginatedResponse, type PaginatedResponseInput, type PaginatedResponseWithMetaInput, type PaginationMeta, type PaginationOptions, type PaginationQuery, type QueryValue, type RequestLoggerConfig, type RequestLoggerNext, type RequestLoggerOptions, type RequestLoggerRequest, type RequestLoggerResponse, type ResponseInput, type ResponseResult, type SearchQuery, type SortOrder, type SortQuery, type SuccessResponseInput, type SuccessResponseResult, UnauthorizedError, ValidationError, type ValidationErrorItem, type ValidationErrorResponse, type ValidationErrorResponseInput, asyncHandler, configureLogger, errorMiddleware, errorResponse, formatRequestLog, getFilters, getPagination, getPaginationMeta, getSearch, getSorting, logger, normalizePaginationQuery, notFoundMiddleware, paginate, paginatedResponse, requestLogger, resetLoggerConfig, response, statusCode, successResponse, validationErrorResponse };