import { ErrorContext } from '../../types';
/**
 * Custom error class for the CertusAdiValt system with enhanced error handling capabilities.
 *
 * Extends the native Error class to include structured error information, HTTP status codes,
 * contextual metadata, and chainable builder methods for error customization.
 *
 * @example
 * ```typescript
 * // Basic error creation
 * throw new CertusAdiValtError('User not found', 'USER_NOT_FOUND', 404);
 *
 * // Error with context and original error
 * try {
 *   await someOperation();
 * } catch (error) {
 *   throw new CertusAdiValtError(
 *     'Operation failed',
 *     'OP_FAILED',
 *     500,
 *     { userId: 123, operation: 'update' },
 *     error
 *   );
 * }
 *
 * // Using builder pattern
 * throw new CertusAdiValtError('Initial error')
 *   .withCode('VALIDATION_ERROR')
 *   .withStatusCode(400)
 *   .withContext({ field: 'email', value: 'invalid' });
 * ```
 */
export declare class CertusAdiValtError extends Error {
    /**
     * Machine-readable error code for programmatic error handling.
     * @type {string}
     */
    readonly code: string;
    /**
     * HTTP status code associated with the error.
     * @type {number}
     */
    readonly statusCode: number;
    /**
     * Timestamp when the error was created.
     * @type {Date}
     */
    readonly timestamp: Date;
    /**
     * Additional contextual information about the error.
     * @type {Record<string, unknown>}
     */
    readonly context: Record<string, unknown>;
    /**
     * Original error that caused this error, if any.
     * @type {Error | undefined}
     */
    readonly originalError?: Error;
    /**
     * Creates a new CertusAdiValtError instance.
     *
     * @param {string} message - Human-readable error description
     * @param {string} [code=ErrorCodes.SRV_INTERNAL_ERROR] - Machine-readable error code
     * @param {number} [statusCode=HttpStatus.INTERNAL_SERVER_ERROR] - HTTP status code
     * @param {Record<string, unknown>} [context={}] - Additional error context
     * @param {Error} [originalError] - Original error that caused this error
     *
     * @example
     * ```typescript
     * // Minimal error
     * new CertusAdiValtError('Something went wrong');
     *
     * // Full error with all parameters
     * new CertusAdiValtError(
     *   'Database connection failed',
     *   'DB_CONNECTION_ERROR',
     *   503,
     *   { host: 'localhost', port: 5432 },
     *   originalError
     * );
     * ```
     */
    constructor(message: string, code?: string, statusCode?: number, context?: Record<string, unknown>, originalError?: Error);
    /**
     * Converts the error to a structured JSON representation suitable for API responses.
     *
     * @returns {ErrorContext} Structured error context object with all error details
     *
     * @remarks
     * The returned object includes:
     * - Error name, message, code, and status code
     * - Timestamp of error creation
     * - Additional context metadata
     * - Stack trace (if available)
     * - Original error details (name, message, stack) if present
     *
     * @example
     * ```typescript
     * const error = new CertusAdiValtError('Not found', 'NOT_FOUND', 404);
     * const json = error.toJSON();
     * // Returns:
     * // {
     * //   name: 'CertusAdiValtError',
     * //   message: 'Not found',
     * //   code: 'NOT_FOUND',
     * //   statusCode: 404,
     * //   timestamp: Date,
     * //   context: {},
     * //   stack: '...',
     * //   originalError: undefined
     * // }
     * ```
     */
    toJSON(): ErrorContext;
    /**
     * Converts the error to a log-friendly format with reduced verbosity.
     *
     * @returns {Record<string, unknown>} Simplified error representation for logging
     *
     * @remarks
     * Compared to toJSON(), this method:
     * - Uses ISO string for timestamp instead of Date object
     * - Provides simplified original error (name and message only)
     * - Structures output for better log aggregation and parsing
     * - Excludes full stack traces from original errors
     *
     * @example
     * ```typescript
     * const error = new CertusAdiValtError('DB error', 'DB_ERROR', 500);
     * const logData = error.toLog();
     * console.error('Operation failed:', logData);
     * ```
     */
    toLog(): Record<string, unknown>;
    /**
     * Creates a new error instance with additional context merged into existing context.
     *
     * @param {Record<string, unknown>} context - Additional context to merge
     * @returns {this} New error instance with merged context
     *
     * @example
     * ```typescript
     * const error = new CertusAdiValtError('Error')
     *   .withContext({ userId: 123 })
     *   .withContext({ operation: 'create' });
     * // error.context = { userId: 123, operation: 'create' }
     * ```
     */
    withContext(context: Record<string, unknown>): this;
    /**
     * Creates a new error instance with the specified error code.
     *
     * @param {string} code - New error code to use
     * @returns {this} New error instance with updated code
     *
     * @example
     * ```typescript
     * const error = new CertusAdiValtError('Error')
     *   .withCode('VALIDATION_ERROR');
     * ```
     */
    withCode(code: string): this;
    /**
     * Creates a new error instance with the specified HTTP status code.
     *
     * @param {number} statusCode - New HTTP status code to use
     * @returns {this} New error instance with updated status code
     *
     * @example
     * ```typescript
     * const error = new CertusAdiValtError('Error')
     *   .withStatusCode(400);
     * ```
     */
    withStatusCode(statusCode: number): this;
    /**
     * Creates a new error instance with the specified error message.
     *
     * @param {string} message - New error message to use
     * @returns {this} New error instance with updated message
     *
     * @example
     * ```typescript
     * const error = new CertusAdiValtError('Initial')
     *   .withMessage('More specific error message');
     * ```
     */
    withMessage(message: string): this;
    /**
     * Protected method to clone the error instance with overridden properties.
     * Used internally by builder pattern methods to create modified error instances.
     *
     * @protected
     * @param {Partial<{ message: string; code: string; statusCode: number; context: Record<string, unknown>; originalError?: Error; }>} overrides - Properties to override in the new instance
     * @returns {this} New error instance with applied overrides
     *
     * @remarks
     * - Preserves the original stack trace for better debugging
     * - Creates a new instance rather than modifying the existing one
     * - Maintains the same constructor chain for subclass compatibility
     *
     * @example
     * ```typescript
     * // In a subclass
     * protected clone(overrides: Partial<...>): this {
     *   const cloned = super.clone(overrides);
     *   // Add subclass-specific logic
     *   return cloned;
     * }
     * ```
     */
    protected clone(overrides: Partial<{
        message: string;
        code: string;
        statusCode: number;
        context: Record<string, unknown>;
        originalError?: Error;
    }>): this;
}