import { ErrorType } from './error-types';
export type ErrorSource = 'cloud-api' | 'runtime' | 'manager-node' | 'cli' | 'toolbox';
/**
 * `error.meta.failures` 的单项（**多项失败的统一表达**）。
 *
 * 用于**多项失败**场景：`code` 只能承载**一个**码（兼容既有消费方），其余失败项
 * 的码会在结构层面丢失 —— 埋点因此统计不到真实分布。`meta.failures` 承载**全量**失败项。
 *
 * ⚠️ 它不是「替代 code」：`code` 仍取第一项，`meta.failures` 是**附加**信息。
 * ⚠️ 与 `meta` 的其他 key 一样，新增字段必须 ① 抽具名 interface ② 补文档登记表 ③ 补契约测试。
 */
export interface IMetaFailure {
    /** 精确错误码 */
    code: string;
    /** 简述（同 ICheckResult.summary） */
    summary?: string;
    /** 可执行的修复建议（同 ICheckResult.remediation） */
    remediation?: string;
}
interface Options {
    original?: Error | undefined;
    code?: string | number;
    /** 标准错误类型：自有码的唯一来源；传入后 code / source 由它决定，且**不可被调用方覆盖** */
    type?: ErrorType;
    requestId?: string;
    action?: string;
    meta?: Record<string, any>;
    /** 错误来源层（对齐 CLI CloudBaseError.source） */
    source?: ErrorSource;
    /** 文档链接覆盖（缺省按 `(code, source)` 派生） */
    docs?: string;
}
/**
 * ## `code` 与 `source` 的两条硬规则（2026-09-20 确立）
 *
 * **规则 1：原本无 `code` → 必须补；已有 `code` → 一律不变。**
 * `code` 是机器契约（驱动消费层 `exitCode`、在 `--json` 暴露、是埋点与文档锚点的键），
 * 改它等于破坏下游判断。
 *
 * > **批量改 `code` 前必跑「已发布影响审计」**：被改动的**原始行**是否存在于**上一个发布 tag**
 * > 的同名文件中 ⇒ 判断是否动了**已发布给用户**的行为。
 *
 * **规则 2：`source` 必须与 `code` 的`归属`配套。**
 * - 包装点**自造** `code`（本层语义）→ `source: 'manager-node'`（本层即 domain）
 * - 包装点**沿用上游** `code`（`e.code || '<FALLBACK>'`）→ `source` 继承上游来源层
 *
 * 反例（禁止）：自造的 `code` 配上**上游**的 `source` —— `(reason, domain)` 二元组失真（AIP-193）。
 */
/**
 * CloudBase SDK（manager-node）标准化错误类。
 *
 * 对齐 CLI 的 CloudBaseError 对象模型：code（稳定语义码）+ message（调试信息）+
 * source（来源层）+ original（cause 链）+ requestId/action（诊断信息）+
 * meta（结构化载荷 —— 多项失败明细见 `meta.failures`）。
 * 差异：SDK 层无 exitCode（进程退出码是 CLI 概念），message 自动加 [action] 前缀（CLI 依赖）。
 */
export declare class CloudBaseError extends Error {
    readonly message: string;
    readonly name = "CloudBaseError";
    readonly original: Error | undefined;
    readonly code: string | number;
    readonly requestId: string;
    readonly action: string;
    readonly meta: Record<string, any> | undefined;
    readonly source: ErrorSource | '';
    /** 错误码文档链接（按 `(code, source)` 派生；`opts.docs` 可覆盖） */
    readonly docs: string;
    constructor(message: string, options?: Options);
    /**
     * 标准 `Error.cause` 视图（ES2022）。
     *
     * 与 `original` **同源**（不重复存储，仅暴露标准视图）：
     * - `original` **保留**，因为已有 8 处调用点依赖它访问上游 SDK 错误
     *   （`.Code` / `.Message` / `.RequestId` / `.Response`）；
     * - 额外提供 `cause` 是为了对齐标准 —— Node 等工具链会**自动打印 cause 链**，
     *   且与 `AggregateError` 兼容。
     */
    get cause(): Error | undefined;
    /**
     * 转为 JSON 错误结构（对齐 CLI CloudBaseError.toJSON）
     * 格式：{ error: { code, message, stack?, requestId?, action?, source?, docs?, meta? } }
     */
    toJSON(): Record<string, unknown>;
}
/**
 * 判断一个值是否为 CloudBaseError（**跨仓 / 跨进程安全**）。
 *
 * ⚠️ **不要用 `instanceof CloudBaseError` 做跨仓判断**：CLI / manager-node / toolbox
 * 各有**独立的** CloudBaseError 类（三个不同的构造函数），跨仓时 `instanceof`
 * 必然为 false；本仓为第三方消费方保留了 ES5 原型兜底（`Object.setPrototypeOf`，见构造函数），
 * 降级编译下同仓内 `instanceof` 也可能失效。因此判断**只依赖结构特征**：
 *
 *   1. 是 Error 实例
 *   2. `name === 'CloudBaseError'`
 *   3. 有 `toJSON()` 方法
 *
 * ⚠️ **不要依赖其他字段**（`requestId` / `source` / `params` / `original` …）做判断 ——
 * 它们都是**按需可选字段**，未来增删不应影响「是不是 CloudBaseError」。
 *
 * 三仓各持一份**同名同实现**的副本（约定相同，不共享包）。
 */
export declare function isCloudBaseError(value: unknown): value is CloudBaseError;
/**
 * 判断错误码是否满足**正规化**规则（**我们自定义的码**适用）。
 *
 * 规则（对齐 AIP-193 `ErrorInfo.reason`）：
 *   1. `UPPER_SNAKE_CASE` —— `^[A-Z][A-Z0-9_]*$`
 *   2. 长度 ≤ **63** 字符
 *   3. **不以 `_` 结尾**（`_` 结尾表示「前缀」，不是完整码）
 *
 * ⚠️ **仅适用于我们自定义的码**（`source` 为 `manager-node` / `cli` / `toolbox`）。
 * **平台码不适用**：控制面是驼峰（如 `InvalidParameter`），数据面由平台规范约束。
 *
 * 用法：单测断言码表全员合规；新增码时先过这里，再落库。
 */
export declare function isValidErrorCode(code: unknown): code is string;
/**
 * 判断值是否属于 `ErrorSource` 闭集。
 *
 * 存在的理由：`source` 在**跨仓**传递时是普通字符串（另一仓的声明无法约束本仓类型），
 * 直接 `return e.source` 会丢类型 ⇒ 用守卫**收窄**，而不是 `as` 强转。
 */
export declare function isErrorSource(value: unknown): value is ErrorSource;
/**
 * **重包装时继承上游错误的来源层**（R3：`source` 与 `code` 归属配套）。
 *
 * - 上游错误带**合法** `source` ⇒ 沿用（`code` 也应同时沿用它，不可自造）
 * - 否则 ⇒ 落到**本层** `'manager-node'`
 *
 * ⚠️ 只在**沿用上游 `code`** 时使用；自造 `code` 时必须硬写本层 `source`。
 */
export declare function errorSourceOf(e: unknown): ErrorSource;
/**
 * 参数校验错误：统一 code = INVALID_PARAM + source = manager-node。
 *
 * 用于替换散落的 `throw new Error('参数校验消息')`，让参数校验类错误
 * 带上稳定 code（CLI 据此映射 exitCode=3）与来源标识，而非裸 Error 兜底。
 */
export declare function throwInvalidParam(message: string): never;
/**
 * 资源不存在错误：统一 code = NOT_FOUND + source = manager-node。
 * 用于替换 `throw new Error('xxx 不存在')` 类错误。
 */
export declare function throwNotFound(message: string): never;
/**
 * 网络/请求错误：统一 code = NETWORK_ERROR + source = manager-node。
 * 用于替换 `throw new Error('下载失败' / 'HTTP ERROR')` 类错误。
 */
export declare function throwNetError(message: string): never;
/**
 * 服务端/业务操作错误：统一 code = API_ERROR + source = manager-node。
 * 用于替换「服务端返回异常 / 业务状态不满足」类错误。
 */
export declare function throwApiError(message: string): never;
/**
 * 缺凭证错误：统一 code = MISSING_CREDENTIAL + source = manager-node。
 * 用于替换 `throw new Error('missing secretId ...')` 类错误（SDK 初始化缺密钥）。
 */
export declare function throwCredentialError(message: string): never;
/**
 * 本地文件读写错误：统一 code = FILE_READ_ERROR + source = manager-node。
 * 用于替换本地文件系统操作（读取 / 写入 / 计算摘要 / 路径处理）失败类错误。
 * 与 CLI / toolbox 的同名 helper 一致（三仓同名同语义）。
 */
export declare function throwFileError(message: string): never;
export {};