/**
 * Standardized API Response Envelope for INTENT Module
 *
 * Provides consistent API response formatting for better client integration.
 * Includes success/error envelopes, pagination, and trace context support.
 *
 * @packageDocumentation
 */
import { VorionError } from '../common/errors.js';
/**
 * Standard HTTP status codes used in API responses
 */
export declare const HttpStatus: {
    readonly OK: 200;
    readonly CREATED: 201;
    readonly ACCEPTED: 202;
    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 TOO_MANY_REQUESTS: 429;
    readonly INTERNAL_SERVER_ERROR: 500;
    readonly BAD_GATEWAY: 502;
    readonly SERVICE_UNAVAILABLE: 503;
    readonly GATEWAY_TIMEOUT: 504;
};
export type HttpStatusCode = (typeof HttpStatus)[keyof typeof HttpStatus];
/**
 * Error information in the response envelope
 */
export interface ApiError {
    /** Machine-readable error code */
    code: string;
    /** Human-readable error message */
    message: string;
    /** Additional error details for debugging */
    details?: Record<string, unknown>;
    /** Trace ID for distributed tracing correlation */
    traceId?: string;
}
/**
 * Pagination information for list responses
 */
export interface PaginationInfo {
    /** Current page number (1-indexed) */
    page: number;
    /** Number of items per page */
    pageSize: number;
    /** Total number of items across all pages */
    totalItems: number;
    /** Total number of pages */
    totalPages: number;
}
/**
 * Cursor-based pagination information
 */
export interface CursorPaginationInfo {
    /** Cursor for the next page */
    nextCursor?: string | undefined;
    /** Cursor for the previous page */
    prevCursor?: string | undefined;
    /** Whether there are more items */
    hasMore: boolean;
    /** Number of items returned */
    count: number;
}
/**
 * Response metadata
 */
export interface ResponseMeta {
    /** Unique request identifier for tracking */
    requestId: string;
    /** ISO 8601 timestamp when response was generated */
    timestamp: string;
    /** Page-based pagination information */
    pagination?: PaginationInfo;
    /** Cursor-based pagination information */
    cursor?: CursorPaginationInfo;
}
/**
 * Standard API response envelope
 *
 * @typeParam T - The type of the response data
 */
export interface ApiResponse<T> {
    /** Whether the request was successful */
    success: boolean;
    /** Response data (present on success) */
    data?: T;
    /** Error information (present on failure) */
    error?: ApiError;
    /** Response metadata */
    meta?: ResponseMeta;
}
/**
 * Options for creating response metadata
 */
export interface MetaOptions {
    /** Custom request ID (generated if not provided) */
    requestId?: string | undefined;
    /** Page-based pagination info */
    pagination?: PaginationInfo | undefined;
    /** Cursor-based pagination info */
    cursor?: CursorPaginationInfo | undefined;
}
/**
 * Options for paginated responses
 */
export interface PaginatedOptions {
    /** Current page number */
    page: number;
    /** Items per page */
    pageSize: number;
    /** Total items count */
    totalItems: number;
    /** Custom request ID */
    requestId?: string | undefined;
}
/**
 * Options for cursor-based paginated responses
 */
export interface CursorPaginatedOptions {
    /** Next page cursor */
    nextCursor?: string | undefined;
    /** Previous page cursor */
    prevCursor?: string | undefined;
    /** Whether more items exist */
    hasMore: boolean;
    /** Custom request ID */
    requestId?: string | undefined;
}
/**
 * Create a successful API response
 *
 * @typeParam T - The type of the response data
 * @param data - The response data
 * @param options - Optional metadata configuration
 * @returns Standardized success response
 *
 * @example
 * ```typescript
 * const response = successResponse({ id: '123', name: 'Test' });
 * // { success: true, data: { id: '123', name: 'Test' }, meta: { requestId: '...', timestamp: '...' } }
 * ```
 */
export declare function successResponse<T>(data: T, options?: MetaOptions): ApiResponse<T>;
/**
 * Create an error API response
 *
 * @param code - Machine-readable error code
 * @param message - Human-readable error message
 * @param details - Additional error details
 * @param requestId - Optional request ID for tracking
 * @returns Standardized error response
 *
 * @example
 * ```typescript
 * const response = errorResponse('VALIDATION_ERROR', 'Invalid input', { field: 'email' });
 * // { success: false, error: { code: 'VALIDATION_ERROR', message: 'Invalid input', details: {...}, traceId: '...' }, meta: {...} }
 * ```
 */
export declare function errorResponse(code: string, message: string, details?: Record<string, unknown>, requestId?: string): ApiResponse<never>;
/**
 * Create a paginated API response (page-based)
 *
 * @typeParam T - The type of items in the response
 * @param items - Array of items for the current page
 * @param options - Pagination options including page, pageSize, and totalItems
 * @returns Standardized paginated response
 *
 * @example
 * ```typescript
 * const response = paginatedResponse(items, { page: 1, pageSize: 20, totalItems: 100 });
 * // { success: true, data: [...], meta: { pagination: { page: 1, pageSize: 20, totalItems: 100, totalPages: 5 }, ... } }
 * ```
 */
export declare function paginatedResponse<T>(items: T[], options: PaginatedOptions): ApiResponse<T[]>;
/**
 * Create a cursor-based paginated API response
 *
 * @typeParam T - The type of items in the response
 * @param items - Array of items for the current page
 * @param options - Cursor pagination options
 * @returns Standardized cursor-paginated response
 *
 * @example
 * ```typescript
 * const response = cursorPaginatedResponse(items, { nextCursor: 'abc123', hasMore: true });
 * // { success: true, data: [...], meta: { cursor: { nextCursor: 'abc123', hasMore: true, count: 10 }, ... } }
 * ```
 */
export declare function cursorPaginatedResponse<T>(items: T[], options: CursorPaginatedOptions): ApiResponse<T[]>;
/**
 * Create a "created" response (HTTP 201)
 *
 * @typeParam T - The type of the created resource
 * @param data - The created resource data
 * @param options - Optional metadata configuration
 * @returns Standardized success response for created resources
 */
export declare function createdResponse<T>(data: T, options?: MetaOptions): ApiResponse<T>;
/**
 * Create an "accepted" response (HTTP 202) for async operations
 *
 * @typeParam T - The type of the response data
 * @param data - Optional response data (e.g., tracking information)
 * @param options - Optional metadata configuration
 * @returns Standardized success response for accepted requests
 */
export declare function acceptedResponse<T>(data?: T, options?: MetaOptions): ApiResponse<T | undefined>;
/**
 * Map VorionError to appropriate HTTP status code
 *
 * @param error - The VorionError instance
 * @returns HTTP status code
 */
export declare function getHttpStatusFromError(error: VorionError): HttpStatusCode;
/**
 * Map error code to HTTP status code
 *
 * @param code - The error code string
 * @returns HTTP status code
 */
export declare function getHttpStatusFromCode(code: string): HttpStatusCode;
/**
 * Create an error response from a VorionError
 *
 * @param error - The VorionError instance
 * @param requestId - Optional request ID for tracking
 * @returns Standardized error response
 */
export declare function errorResponseFromVorionError(error: VorionError, requestId?: string): ApiResponse<never>;
/**
 * Create an error response from any error (including non-VorionError)
 *
 * @param error - The error (VorionError or standard Error)
 * @param requestId - Optional request ID for tracking
 * @returns Standardized error response with appropriate HTTP status
 */
export declare function errorResponseFromError(error: unknown, requestId?: string): {
    response: ApiResponse<never>;
    status: HttpStatusCode;
};
/**
 * Type guard to check if a response is successful
 *
 * @param response - The API response to check
 * @returns True if the response indicates success
 */
export declare function isSuccessResponse<T>(response: ApiResponse<T>): response is ApiResponse<T> & {
    success: true;
    data: T;
};
/**
 * Type guard to check if a response is an error
 *
 * @param response - The API response to check
 * @returns True if the response indicates an error
 */
export declare function isErrorResponse<T>(response: ApiResponse<T>): response is ApiResponse<T> & {
    success: false;
    error: ApiError;
};
//# sourceMappingURL=response.d.ts.map