/**
 * ===============================================================================
 * BASE ERROR CLASSES - Foundation for PromptSpeak Error Handling
 * ===============================================================================
 *
 * Provides the abstract base class for all PromptSpeak errors.
 * Ensures consistent error structure across the entire codebase with:
 *   - Structured error information for logging and debugging
 *   - JSON serialization for API responses
 *   - Error chaining for root cause analysis
 *   - Automatic timestamps
 *   - HTTP status code mapping
 *   - Retry guidance
 *
 * ===============================================================================
 */
import { ErrorCode, ErrorSeverity } from './codes.js';
/**
 * Options for constructing a PromptSpeakError.
 */
export interface PromptSpeakErrorOptions {
    /** Additional details about the error */
    details?: Record<string, unknown>;
    /** The original error that caused this error */
    originalError?: Error;
    /** Override the default retryable status */
    retryable?: boolean;
    /** Override the default HTTP status code */
    statusCode?: number;
    /** Override the default severity */
    severity?: ErrorSeverity;
}
/**
 * JSON representation of a PromptSpeakError.
 * Used for API responses and logging.
 */
export interface SerializedError {
    /** Error name/type */
    name: string;
    /** Error message */
    message: string;
    /** Error code for programmatic handling */
    code: ErrorCode;
    /** Error severity */
    severity: ErrorSeverity;
    /** Whether the operation can be retried */
    retryable: boolean;
    /** HTTP status code */
    statusCode: number;
    /** ISO timestamp when the error occurred */
    timestamp: string;
    /** Additional error details */
    details?: Record<string, unknown>;
    /** Stack trace (only in development) */
    stack?: string;
    /** Original error information */
    cause?: {
        name: string;
        message: string;
        stack?: string;
    };
}
/**
 * Base error class for all PromptSpeak errors.
 * Provides structured error information for logging and debugging.
 *
 * @abstract
 * @example
 * ```typescript
 * class MyCustomError extends PromptSpeakError {
 *   readonly code = ErrorCode.CUSTOM_ERROR;
 *   readonly severity = ErrorSeverity.MEDIUM;
 *
 *   constructor(message: string, options?: PromptSpeakErrorOptions) {
 *     super(message, options);
 *     this.name = 'MyCustomError';
 *   }
 * }
 * ```
 */
export declare abstract class PromptSpeakError extends Error {
    /**
     * The error code for programmatic handling.
     */
    abstract readonly code: ErrorCode;
    /**
     * The severity level of the error.
     */
    abstract readonly severity: ErrorSeverity;
    /**
     * Whether the operation that caused this error can be retried.
     */
    readonly retryable: boolean;
    /**
     * The HTTP status code associated with this error.
     */
    readonly statusCode: number;
    /**
     * Additional details about the error.
     */
    readonly details?: Record<string, unknown>;
    /**
     * The original error that caused this error, if any.
     */
    readonly originalError?: Error;
    /**
     * ISO timestamp when the error was created.
     */
    readonly timestamp: string;
    /**
     * Creates a new PromptSpeakError.
     *
     * @param message - Human-readable error message
     * @param options - Additional error options
     */
    constructor(message: string, options?: PromptSpeakErrorOptions);
    /**
     * Initialize properties that depend on abstract members.
     * Call this in subclass constructors after setting code and severity.
     */
    protected initializeDefaults(options?: PromptSpeakErrorOptions): void;
    /**
     * Serializes the error to a JSON-compatible object.
     * Useful for API responses and structured logging.
     *
     * @param includeStack - Whether to include the stack trace (default: false)
     * @returns Serialized error object
     */
    toJSON(includeStack?: boolean): SerializedError;
    /**
     * Returns a string representation of the error.
     */
    toString(): string;
    /**
     * Creates a new error of the same type with additional details.
     * Useful for adding context as errors propagate up the call stack.
     *
     * @param additionalDetails - Additional details to merge
     * @returns A new error instance with merged details
     */
    withDetails(additionalDetails: Record<string, unknown>): this;
    /**
     * Wraps an existing error in a PromptSpeakError.
     * Preserves the original error for debugging.
     *
     * @param error - The error to wrap
     * @param message - Optional override message
     * @returns A new error instance wrapping the original
     */
    static wrap<T extends PromptSpeakError>(this: new (message: string, options?: PromptSpeakErrorOptions) => T, error: Error, message?: string): T;
}
/**
 * Type guard to check if an error is a PromptSpeakError.
 */
export declare function isPromptSpeakError(error: unknown): error is PromptSpeakError;
/**
 * Type guard to check if an error has a specific error code.
 */
export declare function hasErrorCode<T extends ErrorCode>(error: unknown, code: T): error is PromptSpeakError & {
    code: T;
};
/**
 * Converts any error to a PromptSpeakError.
 * If already a PromptSpeakError, returns it unchanged.
 * Otherwise, wraps it in an InternalError.
 */
export declare function toPromptSpeakError(error: unknown): PromptSpeakError;
//# sourceMappingURL=base.d.ts.map