/**
 * KivoError — 用户友好的结构化错误类
 *
 * FR-Z07: 错误描述 + 可能原因 + 修复建议 + 可重试标记 + 诊断信息
 */
import { type ErrorEntry, type ErrorCategory } from './error-catalog.js';
export declare class KivoError extends Error {
    readonly code: string;
    readonly cause_description: string;
    readonly suggestion: string;
    readonly retryable: boolean;
    readonly category: ErrorCategory;
    readonly diagnostics: Record<string, unknown>;
    constructor(code: string, overrides?: Partial<Pick<ErrorEntry, 'message' | 'cause' | 'suggestion'>>, diagnostics?: Record<string, unknown>);
    /** 生成用户可读的完整错误信息 */
    toUserMessage(): string;
    /** 生成可复制的诊断信息（供提交给支持人员） */
    toDiagnosticString(): string;
    /** 序列化为 API 响应格式 */
    toJSON(): Record<string, unknown>;
}
/**
 * 将任意错误包装为 KivoError。
 * 已经是 KivoError 的直接返回；原生 Error 映射到最接近的错误码。
 */
export declare function wrapError(err: unknown, fallbackCode?: string, diagnostics?: Record<string, unknown>): KivoError;
//# sourceMappingURL=kivo-error.d.ts.map