/** Standard HTTP/application error codes used in structured API responses. */
export declare const API_ERROR_CODES: {
    readonly SUCCESS: 0;
    readonly NOT_FOUND: 404;
    readonly VALIDATION_ERROR: 422;
    readonly BAD_REQUEST: 400;
    readonly UNAUTHORIZED: 401;
    readonly FORBIDDEN: 403;
    readonly CONFLICT: 409;
    readonly INTERNAL_ERROR: 500;
};
/** Union of all values in {@link API_ERROR_CODES}. */
export type ApiErrorCode = (typeof API_ERROR_CODES)[keyof typeof API_ERROR_CODES];
/** Sentiment tag carried in every API envelope. */
export type ApiEnvelopeResult = 'success' | 'info' | 'warn' | 'error';
/** Envelope wrapping successful API responses. */
export interface ApiSuccessEnvelope<T> {
    code: 0;
    message: string;
    result: 'success' | 'info';
    data: T;
    meta?: {
        total?: number;
        limit?: number;
        offset?: number;
    };
}
/** Envelope wrapping failed or problematic API responses. */
export interface ApiErrorEnvelope {
    result: 'warn' | 'error';
    code: number;
    message: string;
    data: null;
    details?: unknown;
}
/** Generic API response: either a success envelope or an error envelope. */
export type ApiEnvelope<T> = ApiSuccessEnvelope<T> | ApiErrorEnvelope;
/** Build a generic 200-success API envelope. */
export declare function successResponse<T>(data: T, message?: string): ApiSuccessEnvelope<T>;
/** Build a 200-success API envelope tagged as informational (`result: "info"`). */
export declare function infoResponse<T>(data: T, message?: string): ApiSuccessEnvelope<T>;
/** Build a 200-success envelope for paginated list endpoints, tagging as `info` and attaching pagination `meta`. */
export declare function paginatedResponse<T>(data: T[], meta: {
    total?: number;
    limit?: number;
    offset?: number;
}, message?: string): ApiSuccessEnvelope<T[]>;
/**
 * Build a structured API error envelope.
 *
 * Code ≥ 500 tags `result: "error"`; anything else tags `result: "warn"`.
 */
export declare function errorResponse(code: number, message: string, details?: unknown): ApiErrorEnvelope;
/** Convenience wrapper for a 404 "not found" API error. */
export declare function notFoundResponse(message?: string, details?: unknown): ApiErrorEnvelope;
/** Convenience wrapper for a 422 "validation error" API error. */
export declare function validationErrorResponse(details: unknown, message?: string): ApiErrorEnvelope;
/** Convenience wrapper for a 400 "bad request" API error. */
export declare function badRequestResponse(message: string, details?: unknown): ApiErrorEnvelope;
/** Convenience wrapper for a 401 "unauthorized" API error. */
export declare function unauthorizedResponse(message?: string, details?: unknown): ApiErrorEnvelope;
/** Convenience wrapper for a 403 "forbidden" API error. */
export declare function forbiddenResponse(message?: string, details?: unknown): ApiErrorEnvelope;
/** Convenience wrapper for a 409 "conflict" API error. */
export declare function conflictResponse(message?: string, details?: unknown): ApiErrorEnvelope;
/** Convenience wrapper for a 500 "internal server error" API error. */
export declare function internalErrorResponse(message?: string, details?: unknown): ApiErrorEnvelope;
/**
 * Bridge a thrown error to an API error envelope — the single mapping from the domain error layer
 * ({@link AppError}) to the wire layer ({@link ApiErrorEnvelope}). Use this in request handlers
 * instead of hand-mapping `catch` blocks, so HTTP codes stay consistent across endpoints.
 *
 * A known {@link AppError} maps to its HTTP code; client-safe codes surface their message, while
 * `Internal` and any non-`AppError` collapse to an opaque 500 that leaks neither message nor stack.
 * Pass `details` only when you intend it to reach the client (e.g. validation field errors).
 */
export declare function toApiResponse(error: unknown, details?: unknown): ApiErrorEnvelope;
//# sourceMappingURL=api-response.d.ts.map