@djvlc/openapi-client-core 1.2.0 → 1.2.1

package/dist/index.d.mts

@@ -1,274 +1,2718 @@
-import { ErrorCode, ApiErrorResponse, RequestContext, ApiSuccessResponse } from '@djvlc/contracts-types';
 import { AxiosInstance } from 'axios';
-export { AxiosError, AxiosInstance, InternalAxiosRequestConfig } from 'axios';
+export { AxiosError, AxiosInstance, AxiosResponse, InternalAxiosRequestConfig } from 'axios';
 
 /**
- * 错误类型定义
+ * 认证配置类型定义
+ *
+ * @packageDocumentation
  */
-
 /**
- * API 错误
+ * 认证类型
  */
-declare class ApiError extends Error {
-    /** 错误码 */
-    readonly code: ErrorCode | string;
-    /** HTTP 状态码 */
-    readonly statusCode: number;
-    /** 错误详情 */
-    readonly details?: {
-        field?: string;
-        message: string;
-        code?: string;
-    }[];
-    /** 请求 ID */
-    readonly requestId: string;
-    /** 链路追踪 ID */
-    readonly traceId?: string;
-    /** 是否可重试 */
-    readonly retryable: boolean;
-    constructor(response: ApiErrorResponse, statusCode: number);
-    private isRetryable;
+type AuthType = 'bearer' | 'api-key' | 'basic' | 'custom' | 'none';
+/**
+ * Bearer Token 认证配置
+ */
+interface BearerAuthConfig {
+    readonly type: 'bearer';
+    /**
+     * 获取 Token 的函数
+     * 可以是同步或异步函数
+     */
+    readonly getToken: () => string | null | Promise<string | null>;
+    /**
+     * Token 头部名称
+     * @default 'Authorization'
+     */
+    readonly headerName?: string;
+    /**
+     * Token 前缀
+     * @default 'Bearer'
+     */
+    readonly prefix?: string;
 }
 /**
- * 网络错误
+ * API Key 认证配置
  */
-declare class NetworkError extends Error {
-    readonly cause?: Error | undefined;
-    readonly retryable = true;
-    constructor(message: string, cause?: Error | undefined);
+interface ApiKeyAuthConfig {
+    readonly type: 'api-key';
+    /**
+     * API Key 值
+     */
+    readonly apiKey: string;
+    /**
+     * API Key 头部名称
+     * @default 'X-API-Key'
+     */
+    readonly headerName?: string;
 }
 /**
- * 超时错误
+ * Basic Auth 认证配置
  */
-declare class TimeoutError extends Error {
-    readonly retryable = true;
-    constructor(timeout: number);
+interface BasicAuthConfig {
+    readonly type: 'basic';
+    /**
+     * 用户名
+     */
+    readonly username: string;
+    /**
+     * 密码
+     */
+    readonly password: string;
 }
-
 /**
- * 客户端配置和类型定义
+ * 自定义认证配置
  */
-
+interface CustomAuthConfig {
+    readonly type: 'custom';
+    /**
+     * 自定义认证函数
+     * 接收请求头对象，修改后返回
+     */
+    readonly authenticate: (headers: Record<string, string>) => void | Promise<void>;
+}
 /**
- * 客户端配置
+ * 无认证配置
  */
-interface ClientConfig {
-    /** 基础 URL */
-    baseUrl: string;
-    /** 默认超时时间（毫秒） */
-    timeout?: number;
-    /** 默认请求头 */
-    headers?: Record<string, string>;
-    /** 认证配置 */
-    auth?: AuthConfig;
-    /** 重试配置 */
-    retry?: RetryConfig;
-    /** 请求拦截器 */
-    onRequest?: RequestInterceptor[];
-    /** 响应拦截器 */
-    onResponse?: ResponseInterceptor[];
-    /** 错误拦截器 */
-    onError?: ErrorInterceptor[];
-}
-/**
- * 认证配置
- */
-interface AuthConfig {
-    /** 认证类型 */
-    type: 'bearer' | 'api-key' | 'basic' | 'custom';
-    /** Token 获取函数 */
-    getToken?: () => Promise<string | null> | string | null;
-    /** API Key */
-    apiKey?: string;
-    /** API Key 头部名称 */
-    apiKeyHeader?: string;
-    /** Basic Auth 用户名 */
-    username?: string;
-    /** Basic Auth 密码 */
-    password?: string;
-    /** 自定义认证函数 */
-    customAuth?: (headers: Record<string, string>) => Promise<void> | void;
+interface NoAuthConfig {
+    readonly type: 'none';
 }
 /**
- * 重试配置
+ * 认证配置联合类型
  */
-interface RetryConfig {
-    /** 最大重试次数 */
-    maxRetries: number;
-    /** 初始延迟（毫秒） */
-    initialDelay: number;
-    /** 最大延迟（毫秒） */
-    maxDelay: number;
-    /** 退避策略 */
-    backoff: 'fixed' | 'exponential' | 'linear';
-    /** 可重试的 HTTP 状态码 */
-    retryableStatusCodes?: number[];
-    /** 是否重试网络错误 */
-    retryOnNetworkError?: boolean;
+type AuthConfig = BearerAuthConfig | ApiKeyAuthConfig | BasicAuthConfig | CustomAuthConfig | NoAuthConfig;
+/**
+ * Token 刷新配置
+ */
+interface TokenRefreshConfig {
+    /**
+     * 刷新 Token 的函数
+     * 返回新的 Token，如果刷新失败则抛出异常
+     */
+    readonly refreshToken: () => Promise<string>;
+    /**
+     * 触发刷新的 HTTP 状态码
+     * @default [401]
+     */
+    readonly triggerStatusCodes?: readonly number[];
+    /**
+     * 最大刷新重试次数
+     * @default 1
+     */
+    readonly maxRetries?: number;
+    /**
+     * 刷新失败时的回调
+     */
+    readonly onRefreshFailed?: (error: Error) => void;
 }
+
 /**
- * 请求选项
+ * 重试配置类型定义
+ *
+ * @packageDocumentation
  */
-interface RequestOptions {
-    /** HTTP 方法 */
-    method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
-    /** 请求路径 */
-    path: string;
-    /** 查询参数 */
-    query?: Record<string, string | number | boolean | undefined>;
-    /** 请求体 */
-    body?: unknown;
-    /** 请求头 */
-    headers?: Record<string, string>;
-    /** 超时时间 */
-    timeout?: number;
-    /** 是否跳过认证 */
-    skipAuth?: boolean;
-    /** 请求上下文 */
-    context?: Partial<RequestContext>;
+/**
+ * 退避策略类型
+ */
+type BackoffStrategy = 'fixed' | 'linear' | 'exponential';
+/**
+ * 重试配置
+ */
+interface RetryConfig {
+    /**
+     * 最大重试次数
+     * @default 3
+     */
+    readonly maxRetries: number;
+    /**
+     * 初始延迟（毫秒）
+     * @default 1000
+     */
+    readonly initialDelayMs: number;
+    /**
+     * 最大延迟（毫秒）
+     * @default 30000
+     */
+    readonly maxDelayMs: number;
+    /**
+     * 退避策略
+     * - fixed: 固定延迟
+     * - linear: 线性增长 (initialDelay * (attempt + 1))
+     * - exponential: 指数增长 (initialDelay * 2^attempt)
+     * @default 'exponential'
+     */
+    readonly backoffStrategy: BackoffStrategy;
+    /**
+     * 可重试的 HTTP 状态码
+     * @default [429, 500, 502, 503, 504]
+     */
+    readonly retryableStatusCodes?: readonly number[];
+    /**
+     * 是否重试网络错误
+     * @default true
+     */
+    readonly retryOnNetworkError?: boolean;
+    /**
+     * 是否重试超时错误
+     * @default true
+     */
+    readonly retryOnTimeout?: boolean;
+    /**
+     * 是否尊重 Retry-After 响应头
+     * @default true
+     */
+    readonly respectRetryAfter?: boolean;
+    /**
+     * 重试时的回调函数
+     */
+    readonly onRetry?: RetryCallback;
+    /**
+     * 自定义判断是否应该重试的函数
+     * 如果提供，将覆盖默认的重试逻辑
+     */
+    readonly shouldRetry?: ShouldRetryFn;
+    /**
+     * 抖动系数（0-1 之间）
+     * 用于添加随机延迟，防止惊群效应
+     * @default 0.1
+     */
+    readonly jitterFactor?: number;
 }
 /**
- * 请求拦截器
+ * 重试回调函数
  */
-type RequestInterceptor = (options: RequestOptions) => Promise<RequestOptions>;
+type RetryCallback = (info: RetryInfo) => void;
 /**
- * 响应拦截器
+ * 重试信息
  */
-type ResponseInterceptor = <T>(response: ApiSuccessResponse<T>, options: RequestOptions) => Promise<ApiSuccessResponse<T>>;
+interface RetryInfo {
+    /**
+     * 当前重试次数（从 1 开始）
+     */
+    readonly attempt: number;
+    /**
+     * 最大重试次数
+     */
+    readonly maxRetries: number;
+    /**
+     * 下次重试延迟（毫秒）
+     */
+    readonly delayMs: number;
+    /**
+     * 导致重试的错误
+     */
+    readonly error: Error;
+    /**
+     * 请求 URL
+     */
+    readonly url: string;
+    /**
+     * 请求方法
+     */
+    readonly method: string;
+}
 /**
- * 错误拦截器
+ * 自定义重试判断函数
  */
-type ErrorInterceptor = (error: ApiError, options: RequestOptions) => Promise<void>;
-
+type ShouldRetryFn = (error: Error, attempt: number, context: RetryContext) => boolean;
 /**
- * Axios 实例创建
- *
- * 用于注入到 openapi-generator 生成的客户端
+ * 重试上下文
  */
-
-declare module 'axios' {
-    interface InternalAxiosRequestConfig {
-        __retryCount?: number;
-    }
+interface RetryContext {
+    /**
+     * 请求 URL
+     */
+    readonly url: string;
+    /**
+     * 请求方法
+     */
+    readonly method: string;
+    /**
+     * HTTP 状态码（如果有响应）
+     */
+    readonly statusCode?: number;
+    /**
+     * Retry-After 头的值（秒）
+     */
+    readonly retryAfter?: number;
 }
-
 /**
- * 创建配置好的 Axios 实例
- *
- * 用于注入到 openapi-generator 生成的 API 类中
- *
- * @example
- * ```typescript
- * import { createAxiosInstance } from '@djvlc/openapi-client-core';
- * import { PagesApi, Configuration } from './generated';
- *
- * const axiosInstance = createAxiosInstance({
- *   baseUrl: '/api/admin',
- *   auth: { type: 'bearer', getToken: () => localStorage.getItem('token') },
- *   retry: { maxRetries: 2, initialDelay: 1000, maxDelay: 10000, backoff: 'exponential' },
- * });
- *
- * const config = new Configuration();
- * const pagesApi = new PagesApi(config, undefined, axiosInstance);
- * ```
+ * 默认重试配置
  */
-declare function createAxiosInstance(config: ClientConfig): AxiosInstance;
+declare const DEFAULT_RETRY_CONFIG: Readonly<RetryConfig>;
 
 /**
- * 原生 fetch HTTP 客户端
+ * 拦截器类型定义
  *
- * 保留兼容性，供不使用 axios 的场景使用
+ * @packageDocumentation
  */
 
 /**
- * 基础 HTTP 客户端
+ * 请求拦截器
+ *
+ * 在请求发送前执行，可以修改请求选项
  */
-declare class HttpClient {
-    private readonly config;
-    constructor(config: ClientConfig);
+interface RequestInterceptor {
     /**
-     * 发起请求
+     * 拦截器名称（用于调试和日志）
      */
-    request<T>(options: RequestOptions): Promise<T>;
+    readonly name: string;
     /**
-     * GET 请求
+     * 执行顺序（数字越小越先执行）
+     * @default 0
      */
-    get<T>(path: string, query?: Record<string, string | number | boolean | undefined>): Promise<T>;
+    readonly order?: number;
     /**
-     * POST 请求
+     * 拦截函数
+     * @param context - 请求上下文
+     * @returns 修改后的请求选项，或 Promise
      */
-    post<T>(path: string, body?: unknown, query?: Record<string, string | number | boolean | undefined>): Promise<T>;
+    intercept(context: RequestContext$1): MutableRequestOptions | Promise<MutableRequestOptions>;
+}
+/**
+ * 响应拦截器
+ *
+ * 在收到响应后执行，可以修改响应数据
+ */
+interface ResponseInterceptor {
     /**
-     * PUT 请求
+     * 拦截器名称（用于调试和日志）
      */
-    put<T>(path: string, body?: unknown): Promise<T>;
+    readonly name: string;
     /**
-     * PATCH 请求
+     * 执行顺序（数字越小越先执行）
+     * @default 0
      */
-    patch<T>(path: string, body?: unknown): Promise<T>;
+    readonly order?: number;
     /**
-     * DELETE 请求
+     * 拦截函数
+     * @param response - 响应数据
+     * @param context - 请求上下文
+     * @returns 修改后的响应数据，或 Promise
      */
-    delete<T>(path: string): Promise<T>;
+    intercept<T>(response: ResponseData<T>, context: RequestContext$1): ResponseData<T> | Promise<ResponseData<T>>;
+}
+/**
+ * 错误拦截器
+ *
+ * 在发生错误时执行，可以处理、转换或重新抛出错误
+ */
+interface ErrorInterceptor {
     /**
-     * 构建完整 URL
+     * 拦截器名称（用于调试和日志）
      */
-    private buildUrl;
+    readonly name: string;
     /**
-     * 构建请求头
+     * 执行顺序（数字越小越先执行）
+     * @default 0
      */
-    private buildHeaders;
+    readonly order?: number;
     /**
-     * 带重试的请求执行
+     * 拦截函数
+     *
+     * @param error - 错误对象
+     * @param context - 请求上下文
+     * @returns 如果返回 void，错误将继续传播；如果返回 ResponseData，将作为成功响应返回
+     * @throws 可以抛出新的错误来替换原错误
      */
-    private executeWithRetry;
+    intercept<T>(error: Error, context: RequestContext$1): void | ResponseData<T> | Promise<void | ResponseData<T>>;
+}
+/**
+ * 拦截器集合
+ */
+interface Interceptors {
     /**
-     * 执行单次请求
+     * 请求拦截器列表
      */
-    private execute;
+    readonly request: readonly RequestInterceptor[];
     /**
-     * 判断是否应该重试
+     * 响应拦截器列表
      */
-    private shouldRetry;
+    readonly response: readonly ResponseInterceptor[];
+    /**
+     * 错误拦截器列表
+     */
+    readonly error: readonly ErrorInterceptor[];
 }
 /**
- * 创建 HTTP 客户端
+ * 拦截器工厂函数类型
  */
-declare function createClient(config: ClientConfig): HttpClient;
-
+type RequestInterceptorFactory<TConfig = void> = (config: TConfig) => RequestInterceptor;
+type ResponseInterceptorFactory<TConfig = void> = (config: TConfig) => ResponseInterceptor;
+type ErrorInterceptorFactory<TConfig = void> = (config: TConfig) => ErrorInterceptor;
 /**
- * 工具函数
+ * 拦截器链执行结果
  */
+interface InterceptorChainResult<T> {
+    /**
+     * 是否成功
+     */
+    readonly success: boolean;
+    /**
+     * 响应数据（成功时）
+     */
+    readonly data?: ResponseData<T>;
+    /**
+     * 错误（失败时）
+     */
+    readonly error?: Error;
+    /**
+     * 是否被拦截器处理
+     */
+    readonly handled: boolean;
+}
 
 /**
- * 生成请求 ID
+ * 日志类型定义
+ *
+ * @packageDocumentation
  */
-declare function generateRequestId(): string;
 /**
- * 延迟执行
+ * 日志级别
  */
-declare function sleep(ms: number): Promise<void>;
+type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+/**
+ * 日志器接口
+ */
+interface Logger {
+    /**
+     * 调试日志
+     */
+    debug(message: string, ...args: unknown[]): void;
+    /**
+     * 信息日志
+     */
+    info(message: string, ...args: unknown[]): void;
+    /**
+     * 警告日志
+     */
+    warn(message: string, ...args: unknown[]): void;
+    /**
+     * 错误日志
+     */
+    error(message: string, ...args: unknown[]): void;
+}
+/**
+ * 控制台日志器配置
+ */
+interface ConsoleLoggerConfig {
+    /**
+     * 日志前缀
+     * @default '[DJV-API]'
+     */
+    readonly prefix?: string;
+    /**
+     * 最低日志级别
+     * @default 'info'
+     */
+    readonly level?: LogLevel;
+    /**
+     * 是否显示时间戳
+     * @default true
+     */
+    readonly timestamp?: boolean;
+    /**
+     * 是否使用颜色（仅在 Node.js 环境有效）
+     * @default true
+     */
+    readonly colors?: boolean;
+}
 /**
- * 计算重试延迟
+ * 日志级别优先级映射
  */
-declare function calculateRetryDelay(retry: RetryConfig, attempt: number): number;
+declare const LOG_LEVEL_PRIORITY: Readonly<Record<LogLevel, number>>;
 
 /**
- * @djvlc/openapi-client-core
- *
- * OpenAPI 客户端公共运行时
- *
- * 提供：
- * - Axios 实例创建（用于注入 openapi-generator 生成的客户端）
- * - 原生 fetch HTTP 客户端
- * - 认证处理（bearer/api-key/basic/custom）
- * - 错误处理
- * - 重试机制
- * - 请求/响应拦截器
+ * 客户端配置类型定义
  *
  * @packageDocumentation
  */
 
-declare const VERSION = "2.0.0";
+/**
+ * 客户端基础配置
+ */
+interface ClientConfig {
+    /**
+     * 基础 URL
+     * @example 'https://api.example.com'
+     */
+    readonly baseUrl: string;
+    /**
+     * 默认超时时间（毫秒）
+     * @default 30000
+     */
+    readonly timeout?: number;
+    /**
+     * 默认请求头
+     */
+    readonly headers?: Readonly<Record<string, string>>;
+    /**
+     * 认证配置
+     */
+    readonly auth?: AuthConfig;
+    /**
+     * 重试配置
+     */
+    readonly retry?: RetryConfig;
+    /**
+     * 请求拦截器列表
+     */
+    readonly requestInterceptors?: readonly RequestInterceptor[];
+    /**
+     * 响应拦截器列表
+     */
+    readonly responseInterceptors?: readonly ResponseInterceptor[];
+    /**
+     * 错误拦截器列表
+     */
+    readonly errorInterceptors?: readonly ErrorInterceptor[];
+    /**
+     * 日志器
+     */
+    readonly logger?: Logger;
+    /**
+     * 是否开启调试模式
+     * @default false
+     */
+    readonly debug?: boolean;
+}
+/**
+ * HTTP 方法类型
+ */
+type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' | 'OPTIONS';
+/**
+ * 请求选项
+ */
+interface RequestOptions {
+    /**
+     * HTTP 方法
+     */
+    readonly method: HttpMethod;
+    /**
+     * 请求路径
+     */
+    readonly path: string;
+    /**
+     * 查询参数
+     */
+    readonly query?: Readonly<Record<string, string | number | boolean | undefined | null>>;
+    /**
+     * 请求体
+     */
+    readonly body?: unknown;
+    /**
+     * 请求头
+     */
+    readonly headers?: Readonly<Record<string, string>>;
+    /**
+     * 超时时间（毫秒）
+     */
+    readonly timeout?: number;
+    /**
+     * 是否跳过认证
+     * @default false
+     */
+    readonly skipAuth?: boolean;
+    /**
+     * AbortSignal 用于取消请求
+     */
+    readonly signal?: AbortSignal;
+    /**
+     * 请求元数据（用于拦截器间传递数据）
+     */
+    readonly metadata?: Readonly<Record<string, unknown>>;
+}
+/**
+ * 可变的请求选项（用于拦截器修改）
+ */
+interface MutableRequestOptions {
+    method: HttpMethod;
+    path: string;
+    query?: Record<string, string | number | boolean | undefined | null>;
+    body?: unknown;
+    headers: Record<string, string>;
+    timeout?: number;
+    skipAuth?: boolean;
+    signal?: AbortSignal;
+    metadata: Record<string, unknown>;
+}
+/**
+ * 响应数据结构
+ */
+interface ResponseData<T = unknown> {
+    /**
+     * 响应数据
+     */
+    readonly data: T;
+    /**
+     * HTTP 状态码
+     */
+    readonly status: number;
+    /**
+     * HTTP 状态文本
+     */
+    readonly statusText: string;
+    /**
+     * 响应头
+     */
+    readonly headers: Readonly<Record<string, string>>;
+    /**
+     * 请求 ID
+     */
+    readonly requestId: string;
+    /**
+     * 追踪 ID
+     */
+    readonly traceId?: string;
+}
+/**
+ * 请求上下文（拦截器使用）
+ */
+interface RequestContext$1 {
+    /**
+     * 请求 ID
+     */
+    readonly requestId: string;
+    /**
+     * 追踪 ID
+     */
+    readonly traceId?: string;
+    /**
+     * 请求开始时间戳
+     */
+    readonly startTime: number;
+    /**
+     * 重试次数
+     */
+    retryCount: number;
+    /**
+     * 原始请求选项
+     */
+    readonly originalOptions: Readonly<RequestOptions>;
+    /**
+     * 当前请求选项（可能被拦截器修改）
+     */
+    options: MutableRequestOptions;
+    /**
+     * 完整 URL
+     */
+    readonly url: string;
+    /**
+     * 元数据存储
+     */
+    metadata: Record<string, unknown>;
+}
+
+/**
+ * 指标类型定义
+ *
+ * @packageDocumentation
+ */
+/**
+ * 请求指标
+ */
+interface RequestMetrics {
+    /**
+     * 请求 ID
+     */
+    readonly requestId: string;
+    /**
+     * 完整 URL
+     */
+    readonly url: string;
+    /**
+     * 请求路径（不含查询参数）
+     */
+    readonly path: string;
+    /**
+     * HTTP 方法
+     */
+    readonly method: string;
+    /**
+     * 开始时间戳（毫秒）
+     */
+    readonly startTime: number;
+    /**
+     * 结束时间戳（毫秒）
+     */
+    readonly endTime: number;
+    /**
+     * 耗时（毫秒）
+     */
+    readonly durationMs: number;
+    /**
+     * HTTP 状态码
+     */
+    readonly status?: number;
+    /**
+     * 是否成功（2xx）
+     */
+    readonly success: boolean;
+    /**
+     * 重试次数
+     */
+    readonly retryCount: number;
+    /**
+     * 追踪 ID
+     */
+    readonly traceId?: string;
+    /**
+     * 错误信息（如果失败）
+     */
+    readonly error?: string;
+    /**
+     * 请求体大小（字节）
+     */
+    readonly requestSize?: number;
+    /**
+     * 响应体大小（字节）
+     */
+    readonly responseSize?: number;
+}
+/**
+ * 指标摘要
+ */
+interface MetricsSummary {
+    /**
+     * 总请求数
+     */
+    readonly totalRequests: number;
+    /**
+     * 成功请求数
+     */
+    readonly successfulRequests: number;
+    /**
+     * 失败请求数
+     */
+    readonly failedRequests: number;
+    /**
+     * 成功率（0-1）
+     */
+    readonly successRate: number;
+    /**
+     * 平均耗时（毫秒）
+     */
+    readonly avgDurationMs: number;
+    /**
+     * P50 耗时（毫秒）
+     */
+    readonly p50Ms: number;
+    /**
+     * P90 耗时（毫秒）
+     */
+    readonly p90Ms: number;
+    /**
+     * P95 耗时（毫秒）
+     */
+    readonly p95Ms: number;
+    /**
+     * P99 耗时（毫秒）
+     */
+    readonly p99Ms: number;
+    /**
+     * 最小耗时（毫秒）
+     */
+    readonly minDurationMs: number;
+    /**
+     * 最大耗时（毫秒）
+     */
+    readonly maxDurationMs: number;
+    /**
+     * 总重试次数
+     */
+    readonly totalRetries: number;
+    /**
+     * 按状态码分布
+     */
+    readonly statusCodeDistribution: Readonly<Record<number, number>>;
+    /**
+     * 按路径分布
+     */
+    readonly pathDistribution: Readonly<Record<string, PathMetrics>>;
+}
+/**
+ * 路径指标
+ */
+interface PathMetrics {
+    /**
+     * 请求数
+     */
+    readonly count: number;
+    /**
+     * 成功数
+     */
+    readonly successCount: number;
+    /**
+     * 平均耗时（毫秒）
+     */
+    readonly avgDurationMs: number;
+}
+/**
+ * 指标收集器配置
+ */
+interface MetricsCollectorConfig {
+    /**
+     * 最大保留的指标数量
+     * @default 1000
+     */
+    readonly maxMetrics?: number;
+    /**
+     * 指标过期时间（毫秒）
+     * @default 3600000 (1 hour)
+     */
+    readonly ttlMs?: number;
+    /**
+     * 每次请求完成时的回调
+     */
+    readonly onMetrics?: (metrics: RequestMetrics) => void;
+    /**
+     * 是否启用详细指标（包括请求/响应大小）
+     * @default false
+     */
+    readonly detailed?: boolean;
+}
+/**
+ * 指标收集器接口
+ */
+interface MetricsCollector {
+    /**
+     * 记录请求指标
+     */
+    record(metrics: RequestMetrics): void;
+    /**
+     * 获取指标摘要
+     */
+    summary(): MetricsSummary;
+    /**
+     * 获取所有指标
+     */
+    getAll(): readonly RequestMetrics[];
+    /**
+     * 按路径获取指标
+     */
+    getByPath(path: string): readonly RequestMetrics[];
+    /**
+     * 清空所有指标并返回
+     */
+    flush(): readonly RequestMetrics[];
+    /**
+     * 清空所有指标
+     */
+    clear(): void;
+}
+
+/**
+ * 基础错误类
+ *
+ * @packageDocumentation
+ */
+/**
+ * 客户端基础错误类
+ *
+ * 所有自定义错误的基类，提供统一的错误处理能力
+ */
+declare abstract class BaseClientError extends Error {
+    /**
+     * 错误类型标识符
+     */
+    abstract readonly type: string;
+    /**
+     * 是否可重试
+     */
+    abstract readonly retryable: boolean;
+    /**
+     * 错误发生时间
+     */
+    readonly timestamp: Date;
+    constructor(message: string);
+    /**
+     * 转换为 JSON 对象（用于日志和序列化）
+     */
+    toJSON(): Record<string, unknown>;
+    /**
+     * 转换为字符串
+     */
+    toString(): string;
+}
+
+/**
+ * API 错误类
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * 错误详情
+ */
+interface ApiErrorDetail {
+    /**
+     * 字段名
+     */
+    readonly field?: string;
+    /**
+     * 错误消息
+     */
+    readonly message: string;
+    /**
+     * 错误码
+     */
+    readonly code?: string;
+}
+/**
+ * API 错误配置
+ */
+interface ApiErrorConfig {
+    /**
+     * 错误消息
+     */
+    readonly message: string;
+    /**
+     * 业务错误码
+     */
+    readonly code: string;
+    /**
+     * HTTP 状态码
+     */
+    readonly statusCode: number;
+    /**
+     * 错误详情
+     */
+    readonly details?: readonly ApiErrorDetail[];
+    /**
+     * 请求 ID
+     */
+    readonly requestId: string;
+    /**
+     * 追踪 ID
+     */
+    readonly traceId?: string;
+    /**
+     * Retry-After 头的值（秒）
+     */
+    readonly retryAfter?: number;
+    /**
+     * 原始响应数据
+     */
+    readonly rawResponse?: unknown;
+}
+/**
+ * API 业务错误
+ *
+ * 表示服务器返回的业务错误响应（HTTP 非 2xx）
+ */
+declare class ApiError extends BaseClientError {
+    readonly type: "API_ERROR";
+    /**
+     * 业务错误码
+     */
+    readonly code: string;
+    /**
+     * HTTP 状态码
+     */
+    readonly statusCode: number;
+    /**
+     * 错误详情
+     */
+    readonly details?: readonly ApiErrorDetail[];
+    /**
+     * 请求 ID
+     */
+    readonly requestId: string;
+    /**
+     * 追踪 ID
+     */
+    readonly traceId?: string;
+    /**
+     * Retry-After 头的值（秒）
+     */
+    readonly retryAfterSeconds?: number;
+    /**
+     * 原始响应数据
+     */
+    readonly rawResponse?: unknown;
+    constructor(config: ApiErrorConfig);
+    /**
+     * 是否可重试
+     *
+     * 5xx 和 429 错误通常可重试
+     */
+    get retryable(): boolean;
+    /**
+     * 是否为未授权错误 (401)
+     */
+    isUnauthorized(): boolean;
+    /**
+     * 是否为禁止访问错误 (403)
+     */
+    isForbidden(): boolean;
+    /**
+     * 是否为认证相关错误 (401/403)
+     */
+    isAuthError(): boolean;
+    /**
+     * 是否为未找到错误 (404)
+     */
+    isNotFound(): boolean;
+    /**
+     * 是否为冲突错误 (409)
+     */
+    isConflict(): boolean;
+    /**
+     * 是否为验证错误 (400/422)
+     */
+    isValidationError(): boolean;
+    /**
+     * 是否为限流错误 (429)
+     */
+    isRateLimited(): boolean;
+    /**
+     * 是否为客户端错误 (4xx)
+     */
+    isClientError(): boolean;
+    /**
+     * 是否为服务端错误 (5xx)
+     */
+    isServerError(): boolean;
+    /**
+     * 获取 Retry-After 值（秒）
+     */
+    getRetryAfter(): number | undefined;
+    /**
+     * 获取推荐的重试延迟（毫秒）
+     *
+     * @param defaultMs - 默认延迟（毫秒）
+     */
+    getRetryDelayMs(defaultMs?: number): number;
+    toJSON(): Record<string, unknown>;
+    /**
+     * 类型守卫：判断是否为 ApiError
+     */
+    static is(error: unknown): error is ApiError;
+    /**
+     * 从响应数据创建 ApiError
+     */
+    static fromResponse(data: {
+        code?: string;
+        message?: string;
+        details?: ApiErrorDetail[];
+        requestId?: string;
+        traceId?: string;
+    }, statusCode: number, retryAfter?: number): ApiError;
+}
+
+/**
+ * 网络错误类
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * 网络错误
+ *
+ * 表示网络层面的错误，如 DNS 解析失败、连接被拒绝等
+ */
+declare class NetworkError extends BaseClientError {
+    readonly type: "NETWORK_ERROR";
+    readonly retryable = true;
+    /**
+     * 原始错误
+     */
+    readonly cause?: Error;
+    constructor(message: string, cause?: Error);
+    toJSON(): Record<string, unknown>;
+    /**
+     * 类型守卫：判断是否为 NetworkError
+     */
+    static is(error: unknown): error is NetworkError;
+    /**
+     * 从原生 fetch 错误创建 NetworkError
+     */
+    static fromFetchError(error: Error): NetworkError;
+}
+
+/**
+ * 超时错误类
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * 超时错误
+ *
+ * 表示请求超时
+ */
+declare class TimeoutError extends BaseClientError {
+    readonly type: "TIMEOUT_ERROR";
+    readonly retryable = true;
+    /**
+     * 超时时间（毫秒）
+     */
+    readonly timeoutMs: number;
+    constructor(timeoutMs: number);
+    toJSON(): Record<string, unknown>;
+    /**
+     * 类型守卫：判断是否为 TimeoutError
+     */
+    static is(error: unknown): error is TimeoutError;
+}
+
+/**
+ * 取消错误类
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * 取消错误
+ *
+ * 表示请求被主动取消
+ */
+declare class AbortError extends BaseClientError {
+    readonly type: "ABORT_ERROR";
+    readonly retryable = false;
+    /**
+     * 取消原因
+     */
+    readonly reason?: string;
+    constructor(reason?: string);
+    toJSON(): Record<string, unknown>;
+    /**
+     * 类型守卫：判断是否为 AbortError
+     */
+    static is(error: unknown): error is AbortError;
+    /**
+     * 从原生 AbortError 创建
+     */
+    static fromNative(error: Error): AbortError;
+}
+
+/**
+ * 错误模块
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * 判断错误是否可重试
+ */
+declare function isRetryableError(error: unknown): boolean;
+/**
+ * 获取错误的推荐重试延迟（毫秒）
+ *
+ * @param error - 错误对象
+ * @param defaultMs - 默认延迟
+ */
+declare function getRetryDelay(error: unknown, defaultMs?: number): number;
+/**
+ * 判断是否为客户端错误类型
+ */
+declare function isClientError(error: unknown): error is ApiError | NetworkError | TimeoutError | AbortError;
+/**
+ * 获取错误类型标识符
+ */
+declare function getErrorType(error: unknown): string;
+
+/**
+ * 认证器接口
+ *
+ * @packageDocumentation
+ */
+/**
+ * 认证器接口
+ *
+ * 定义了认证器的基本行为
+ */
+interface Authenticator {
+    /**
+     * 认证类型
+     */
+    readonly type: string;
+    /**
+     * 向请求头添加认证信息
+     *
+     * @param headers - 请求头对象（可变）
+     * @returns Promise<void> 或 void
+     */
+    authenticate(headers: Record<string, string>): Promise<void> | void;
+}
+/**
+ * 认证器工厂函数类型
+ */
+type AuthenticatorFactory<TConfig> = (config: TConfig) => Authenticator;
+
+/**
+ * Bearer Token 认证器
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Bearer Token 认证器
+ *
+ * 将 Bearer Token 添加到 Authorization 头
+ */
+declare class BearerAuthenticator implements Authenticator {
+    readonly type: "bearer";
+    private readonly getToken;
+    private readonly headerName;
+    private readonly prefix;
+    constructor(config: Omit<BearerAuthConfig, 'type'>);
+    authenticate(headers: Record<string, string>): Promise<void>;
+}
+/**
+ * 创建 Bearer Token 认证器
+ */
+declare function createBearerAuthenticator(config: Omit<BearerAuthConfig, 'type'>): BearerAuthenticator;
+
+/**
+ * API Key 认证器
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * API Key 认证器
+ *
+ * 将 API Key 添加到指定的请求头
+ */
+declare class ApiKeyAuthenticator implements Authenticator {
+    readonly type: "api-key";
+    private readonly apiKey;
+    private readonly headerName;
+    constructor(config: Omit<ApiKeyAuthConfig, 'type'>);
+    authenticate(headers: Record<string, string>): void;
+}
+/**
+ * 创建 API Key 认证器
+ */
+declare function createApiKeyAuthenticator(config: Omit<ApiKeyAuthConfig, 'type'>): ApiKeyAuthenticator;
+
+/**
+ * Basic Auth 认证器
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Basic Auth 认证器
+ *
+ * 将用户名和密码以 Base64 编码添加到 Authorization 头
+ */
+declare class BasicAuthenticator implements Authenticator {
+    readonly type: "basic";
+    private readonly encodedCredentials;
+    constructor(config: Omit<BasicAuthConfig, 'type'>);
+    authenticate(headers: Record<string, string>): void;
+}
+/**
+ * 创建 Basic Auth 认证器
+ */
+declare function createBasicAuthenticator(config: Omit<BasicAuthConfig, 'type'>): BasicAuthenticator;
+
+/**
+ * 自定义认证器
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * 自定义认证器
+ *
+ * 允许用户自定义认证逻辑
+ */
+declare class CustomAuthenticator implements Authenticator {
+    readonly type: "custom";
+    private readonly authenticateFn;
+    constructor(config: Omit<CustomAuthConfig, 'type'>);
+    authenticate(headers: Record<string, string>): Promise<void>;
+}
+/**
+ * 创建自定义认证器
+ */
+declare function createCustomAuthenticator(config: Omit<CustomAuthConfig, 'type'>): CustomAuthenticator;
+
+/**
+ * 无认证器
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * 无认证器
+ *
+ * 不进行任何认证操作
+ */
+declare class NoAuthenticator implements Authenticator {
+    readonly type: "none";
+    authenticate(_headers: Record<string, string>): void;
+}
+/**
+ * 创建无认证器
+ */
+declare function createNoAuthenticator(): NoAuthenticator;
+/**
+ * 无认证器单例
+ */
+declare const noAuthenticator: NoAuthenticator;
+
+/**
+ * 认证模块
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * 从配置创建认证器
+ *
+ * @param config - 认证配置
+ * @returns 认证器实例
+ */
+declare function createAuthenticatorFromConfig(config: AuthConfig): Authenticator;
+
+/**
+ * 拦截器管理器
+ *
+ * 管理拦截器的注册、排序和执行
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * 拦截器管理器
+ *
+ * 负责：
+ * 1. 管理拦截器的注册和移除
+ * 2. 按优先级排序拦截器
+ * 3. 顺序执行拦截器链
+ */
+declare class InterceptorManager {
+    private readonly requestInterceptors;
+    private readonly responseInterceptors;
+    private readonly errorInterceptors;
+    /**
+     * 获取所有拦截器
+     */
+    get interceptors(): Interceptors;
+    /**
+     * 添加请求拦截器
+     *
+     * @param interceptor - 请求拦截器
+     * @returns 返回自身，支持链式调用
+     */
+    addRequestInterceptor(interceptor: RequestInterceptor): this;
+    /**
+     * 添加响应拦截器
+     *
+     * @param interceptor - 响应拦截器
+     * @returns 返回自身，支持链式调用
+     */
+    addResponseInterceptor(interceptor: ResponseInterceptor): this;
+    /**
+     * 添加错误拦截器
+     *
+     * @param interceptor - 错误拦截器
+     * @returns 返回自身，支持链式调用
+     */
+    addErrorInterceptor(interceptor: ErrorInterceptor): this;
+    /**
+     * 批量添加拦截器
+     *
+     * @param interceptors - 拦截器配置
+     * @returns 返回自身，支持链式调用
+     */
+    addInterceptors(interceptors: Partial<Interceptors>): this;
+    /**
+     * 移除请求拦截器
+     *
+     * @param name - 拦截器名称
+     * @returns 是否移除成功
+     */
+    removeRequestInterceptor(name: string): boolean;
+    /**
+     * 移除响应拦截器
+     *
+     * @param name - 拦截器名称
+     * @returns 是否移除成功
+     */
+    removeResponseInterceptor(name: string): boolean;
+    /**
+     * 移除错误拦截器
+     *
+     * @param name - 拦截器名称
+     * @returns 是否移除成功
+     */
+    removeErrorInterceptor(name: string): boolean;
+    /**
+     * 清除所有拦截器
+     */
+    clear(): void;
+    /**
+     * 执行请求拦截器链
+     *
+     * @param context - 请求上下文
+     * @returns 修改后的请求选项
+     */
+    executeRequestInterceptors(context: RequestContext$1): Promise<MutableRequestOptions>;
+    /**
+     * 执行响应拦截器链
+     *
+     * @param response - 响应数据
+     * @param context - 请求上下文
+     * @returns 修改后的响应数据
+     */
+    executeResponseInterceptors<T>(response: ResponseData<T>, context: RequestContext$1): Promise<ResponseData<T>>;
+    /**
+     * 执行错误拦截器链
+     *
+     * @param error - 错误对象
+     * @param context - 请求上下文
+     * @returns 如果返回 ResponseData，则表示错误被恢复；否则错误继续传播
+     * @throws 如果拦截器抛出新错误，则使用新错误
+     */
+    executeErrorInterceptors<T>(error: Error, context: RequestContext$1): Promise<ResponseData<T> | void>;
+    /**
+     * 按 order 排序拦截器
+     */
+    private sortInterceptors;
+    /**
+     * 按名称移除拦截器
+     */
+    private removeByName;
+}
+/**
+ * 创建拦截器管理器
+ */
+declare function createInterceptorManager(): InterceptorManager;
+
+/**
+ * 认证拦截器
+ *
+ * 自动向请求添加认证信息
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * 认证拦截器配置
+ */
+interface AuthInterceptorConfig {
+    /**
+     * 认证器实例
+     */
+    readonly authenticator: Authenticator;
+    /**
+     * 执行顺序
+     * @default -100 (优先执行)
+     */
+    readonly order?: number;
+}
+/**
+ * 认证拦截器
+ *
+ * 在请求发送前添加认证信息
+ */
+declare class AuthInterceptor implements RequestInterceptor {
+    readonly name = "auth";
+    readonly order: number;
+    private readonly authenticator;
+    constructor(config: AuthInterceptorConfig);
+    intercept(context: RequestContext$1): Promise<MutableRequestOptions>;
+}
+/**
+ * 创建认证拦截器
+ */
+declare function createAuthInterceptor(config: AuthInterceptorConfig): AuthInterceptor;
+
+/**
+ * 请求 ID 拦截器
+ *
+ * 自动生成并添加请求 ID
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * 请求 ID 拦截器配置
+ */
+interface RequestIdInterceptorConfig {
+    /**
+     * 请求 ID 头名称
+     * @default 'X-Request-ID'
+     */
+    readonly headerName?: string;
+    /**
+     * 自定义 ID 生成函数
+     */
+    readonly generateId?: () => string;
+    /**
+     * 执行顺序
+     * @default -90
+     */
+    readonly order?: number;
+}
+/**
+ * 请求 ID 拦截器
+ *
+ * 为每个请求自动生成唯一的请求 ID
+ */
+declare class RequestIdInterceptor implements RequestInterceptor {
+    readonly name = "request-id";
+    readonly order: number;
+    private readonly headerName;
+    private readonly generateId;
+    constructor(config?: RequestIdInterceptorConfig);
+    intercept(context: RequestContext$1): MutableRequestOptions;
+}
+/**
+ * 创建请求 ID 拦截器
+ */
+declare function createRequestIdInterceptor(config?: RequestIdInterceptorConfig): RequestIdInterceptor;
+
+/**
+ * 追踪上下文拦截器
+ *
+ * 自动添加追踪 ID 和 OpenTelemetry 上下文
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * 追踪拦截器配置
+ */
+interface TraceInterceptorConfig {
+    /**
+     * 追踪 ID 头名称
+     * @default 'X-Trace-ID'
+     */
+    readonly traceIdHeader?: string;
+    /**
+     * 是否添加 traceparent 头（W3C Trace Context）
+     * @default false
+     */
+    readonly addTraceparent?: boolean;
+    /**
+     * 获取追踪 ID 的函数
+     * 如果未提供，将自动生成
+     */
+    readonly getTraceId?: () => string | undefined;
+    /**
+     * 获取 traceparent 的函数
+     */
+    readonly getTraceparent?: () => string | undefined;
+    /**
+     * 执行顺序
+     * @default -80
+     */
+    readonly order?: number;
+}
+/**
+ * 追踪上下文拦截器
+ *
+ * 为请求添加追踪信息，支持分布式追踪
+ */
+declare class TraceInterceptor implements RequestInterceptor {
+    readonly name = "trace";
+    readonly order: number;
+    private readonly traceIdHeader;
+    private readonly addTraceparent;
+    private readonly getTraceId?;
+    private readonly getTraceparent?;
+    constructor(config?: TraceInterceptorConfig);
+    intercept(context: RequestContext$1): MutableRequestOptions;
+}
+/**
+ * 创建追踪拦截器
+ */
+declare function createTraceInterceptor(config?: TraceInterceptorConfig): TraceInterceptor;
+
+/**
+ * 超时拦截器
+ *
+ * 根据请求类型自动设置超时时间
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * 超时拦截器配置
+ */
+interface TimeoutInterceptorConfig {
+    /**
+     * 默认超时时间（毫秒）
+     * @default 30000
+     */
+    readonly defaultTimeout?: number;
+    /**
+     * 按方法设置超时时间
+     * 例如: { GET: 10000, POST: 60000 }
+     */
+    readonly methodTimeouts?: Partial<Record<HttpMethod, number>>;
+    /**
+     * 按路径模式设置超时时间
+     * 使用正则表达式匹配路径
+     */
+    readonly pathTimeouts?: ReadonlyArray<{
+        pattern: RegExp;
+        timeout: number;
+    }>;
+    /**
+     * 执行顺序
+     * @default -70
+     */
+    readonly order?: number;
+}
+/**
+ * 超时拦截器
+ *
+ * 智能设置请求超时时间
+ */
+declare class TimeoutInterceptor implements RequestInterceptor {
+    readonly name = "timeout";
+    readonly order: number;
+    private readonly defaultTimeout;
+    private readonly methodTimeouts;
+    private readonly pathTimeouts;
+    constructor(config?: TimeoutInterceptorConfig);
+    intercept(context: RequestContext$1): MutableRequestOptions;
+}
+/**
+ * 创建超时拦截器
+ */
+declare function createTimeoutInterceptor(config?: TimeoutInterceptorConfig): TimeoutInterceptor;
+
+/**
+ * 重试拦截器
+ *
+ * 处理请求失败时的自动重试
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * 重试拦截器配置
+ */
+interface RetryInterceptorConfig extends Partial<RetryConfig> {
+    /**
+     * 执行重试请求的函数
+     * 由客户端注入
+     */
+    readonly executeRequest: <T>(context: RequestContext$1) => Promise<ResponseData<T>>;
+    /**
+     * 执行顺序
+     * @default 100 (最后执行)
+     */
+    readonly order?: number;
+}
+/**
+ * 重试拦截器
+ *
+ * 在发生可重试错误时自动重试请求
+ *
+ * 注意：这个拦截器应该注册为错误拦截器，而不是响应拦截器
+ */
+declare class RetryInterceptor implements ErrorInterceptor {
+    readonly name = "retry";
+    readonly order: number;
+    private readonly config;
+    private readonly executeRequest;
+    constructor(config: RetryInterceptorConfig);
+    intercept<T>(error: Error, context: RequestContext$1): Promise<ResponseData<T> | void>;
+    /**
+     * 判断是否应该重试
+     */
+    private shouldRetry;
+}
+/**
+ * 创建重试拦截器
+ */
+declare function createRetryInterceptor(config: RetryInterceptorConfig): RetryInterceptor;
+
+/**
+ * Token 刷新拦截器
+ *
+ * 在收到 401 响应时自动刷新 Token 并重试
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Token 刷新拦截器配置
+ */
+interface TokenRefreshInterceptorConfig extends TokenRefreshConfig {
+    /**
+     * 执行重试请求的函数
+     * 由客户端注入
+     */
+    readonly executeRequest: <T>(context: RequestContext$1) => Promise<ResponseData<T>>;
+    /**
+     * Token 刷新后的回调
+     * 用于更新存储的 Token
+     */
+    readonly onTokenRefreshed?: (newToken: string) => void;
+    /**
+     * 执行顺序
+     * @default 50 (在重试拦截器之前)
+     */
+    readonly order?: number;
+}
+/**
+ * Token 刷新拦截器
+ *
+ * 功能：
+ * 1. 在收到 401 响应时自动刷新 Token
+ * 2. 合并并发的 Token 刷新请求，避免重复刷新
+ * 3. 刷新成功后自动重试原请求
+ * 4. 刷新失败时触发回调
+ */
+declare class TokenRefreshInterceptor implements ErrorInterceptor {
+    readonly name = "token-refresh";
+    readonly order: number;
+    private readonly refreshToken;
+    private readonly executeRequest;
+    private readonly triggerStatusCodes;
+    private readonly maxRetries;
+    private readonly onTokenRefreshed?;
+    private readonly onRefreshFailed?;
+    private readonly state;
+    constructor(config: TokenRefreshInterceptorConfig);
+    intercept<T>(error: Error, context: RequestContext$1): Promise<ResponseData<T> | void>;
+    /**
+     * 判断是否应该刷新 Token
+     */
+    private shouldRefresh;
+    /**
+     * 执行 Token 刷新
+     *
+     * 合并并发请求，确保同一时间只有一个刷新请求
+     */
+    private doRefresh;
+    /**
+     * 重置状态（用于测试或手动重置）
+     */
+    reset(): void;
+}
+/**
+ * 创建 Token 刷新拦截器
+ */
+declare function createTokenRefreshInterceptor(config: TokenRefreshInterceptorConfig): TokenRefreshInterceptor;
+
+/**
+ * 错误转换拦截器
+ *
+ * 将原始响应错误转换为结构化的错误对象
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * 错误转换拦截器配置
+ */
+interface ErrorTransformInterceptorConfig {
+    /**
+     * 是否在响应中包含原始数据
+     * @default false
+     */
+    readonly includeRawResponse?: boolean;
+    /**
+     * 自定义错误消息提取函数
+     */
+    readonly extractErrorMessage?: (data: unknown) => string | undefined;
+    /**
+     * 自定义错误码提取函数
+     */
+    readonly extractErrorCode?: (data: unknown) => string | undefined;
+    /**
+     * 执行顺序
+     * @default 0
+     */
+    readonly order?: number;
+}
+/**
+ * 错误转换拦截器
+ *
+ * 处理响应数据，提取错误信息
+ * 注意：这个拦截器主要用于标准化响应格式
+ */
+declare class ErrorTransformInterceptor implements ResponseInterceptor {
+    readonly name = "error-transform";
+    readonly order: number;
+    private readonly includeRawResponse;
+    private readonly extractErrorMessage?;
+    private readonly extractErrorCode?;
+    constructor(config?: ErrorTransformInterceptorConfig);
+    intercept<T>(response: ResponseData<T>, _context: RequestContext$1): ResponseData<T>;
+}
+/**
+ * 创建错误转换拦截器
+ */
+declare function createErrorTransformInterceptor(config?: ErrorTransformInterceptorConfig): ErrorTransformInterceptor;
+
+/**
+ * 错误日志拦截器
+ *
+ * 记录所有请求错误
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * 错误日志拦截器配置
+ */
+interface LoggingInterceptorConfig {
+    /**
+     * 日志器
+     */
+    readonly logger: Logger;
+    /**
+     * 是否记录详细信息（包括请求体、响应体等）
+     * @default false
+     */
+    readonly verbose?: boolean;
+    /**
+     * 是否记录取消的请求
+     * @default false
+     */
+    readonly logAborted?: boolean;
+    /**
+     * 错误过滤器
+     * 返回 true 表示记录该错误
+     */
+    readonly filter?: (error: Error, context: RequestContext$1) => boolean;
+    /**
+     * 执行顺序
+     * @default -100 (优先执行，确保先记录日志)
+     */
+    readonly order?: number;
+}
+/**
+ * 错误日志拦截器
+ *
+ * 记录错误信息用于调试和监控
+ */
+declare class LoggingInterceptor implements ErrorInterceptor {
+    readonly name = "logging";
+    readonly order: number;
+    private readonly logger;
+    private readonly verbose;
+    private readonly logAborted;
+    private readonly filter?;
+    constructor(config: LoggingInterceptorConfig);
+    intercept<T>(error: Error, context: RequestContext$1): void | ResponseData<T>;
+    /**
+     * 构建日志信息
+     */
+    private buildLogInfo;
+}
+/**
+ * 创建错误日志拦截器
+ */
+declare function createLoggingInterceptor(config: LoggingInterceptorConfig): LoggingInterceptor;
+
+/**
+ * 错误上报拦截器
+ *
+ * 将错误上报到监控系统（如 Sentry）
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * 错误上报器接口
+ */
+interface ErrorReporter {
+    /**
+     * 上报错误
+     *
+     * @param error - 错误对象
+     * @param context - 错误上下文
+     */
+    report(error: Error, context: Record<string, unknown>): void;
+}
+/**
+ * 错误严重程度
+ */
+type ErrorSeverity = 'fatal' | 'error' | 'warning' | 'info' | 'debug';
+/**
+ * 错误上报拦截器配置
+ */
+interface ReportingInterceptorConfig {
+    /**
+     * 错误上报器
+     */
+    readonly reporter: ErrorReporter;
+    /**
+     * 获取错误严重程度
+     * @default 根据错误类型自动判断
+     */
+    readonly getSeverity?: (error: Error) => ErrorSeverity;
+    /**
+     * 是否上报客户端错误（4xx）
+     * @default false
+     */
+    readonly reportClientErrors?: boolean;
+    /**
+     * 是否上报取消的请求
+     * @default false
+     */
+    readonly reportAborted?: boolean;
+    /**
+     * 是否上报网络错误
+     * @default true
+     */
+    readonly reportNetworkErrors?: boolean;
+    /**
+     * 采样率（0-1）
+     * 用于减少上报量
+     * @default 1 (100% 上报)
+     */
+    readonly sampleRate?: number;
+    /**
+     * 自定义上下文提取器
+     */
+    readonly extractContext?: (error: Error, context: RequestContext$1) => Record<string, unknown>;
+    /**
+     * 执行顺序
+     * @default -50 (在日志之后)
+     */
+    readonly order?: number;
+}
+/**
+ * 错误上报拦截器
+ *
+ * 将错误上报到外部监控系统
+ */
+declare class ReportingInterceptor implements ErrorInterceptor {
+    readonly name = "reporting";
+    readonly order: number;
+    private readonly reporter;
+    private readonly getSeverity;
+    private readonly reportClientErrors;
+    private readonly reportAborted;
+    private readonly reportNetworkErrors;
+    private readonly sampleRate;
+    private readonly extractContext?;
+    constructor(config: ReportingInterceptorConfig);
+    intercept<T>(error: Error, context: RequestContext$1): void | ResponseData<T>;
+    /**
+     * 判断是否应该上报
+     */
+    private shouldReport;
+    /**
+     * 构建上报上下文
+     */
+    private buildReportContext;
+    /**
+     * 默认的严重程度判断
+     */
+    private defaultGetSeverity;
+}
+/**
+ * 创建错误上报拦截器
+ */
+declare function createReportingInterceptor(config: ReportingInterceptorConfig): ReportingInterceptor;
+
+/**
+ * 请求去重插件
+ *
+ * 避免相同请求并发执行多次
+ *
+ * @packageDocumentation
+ */
+/**
+ * 请求去重器配置
+ */
+interface DeduplicationConfig {
+    /**
+     * 是否只对 GET 请求去重
+     * @default true
+     */
+    readonly getOnly?: boolean;
+    /**
+     * 自定义请求键生成函数
+     * 默认使用 method + url
+     */
+    readonly generateKey?: (method: string, url: string) => string;
+    /**
+     * 最大缓存数量
+     * @default 100
+     */
+    readonly maxSize?: number;
+}
+/**
+ * 请求去重器
+ *
+ * 功能：
+ * 1. 相同的并发请求只执行一次
+ * 2. 结果共享给所有等待者
+ * 3. 请求完成后自动清理
+ */
+declare class RequestDeduper {
+    private readonly getOnly;
+    private readonly generateKey;
+    private readonly maxSize;
+    private readonly inflightRequests;
+    constructor(config?: DeduplicationConfig);
+    /**
+     * 执行请求（带去重）
+     *
+     * @param method - HTTP 方法
+     * @param url - 请求 URL
+     * @param execute - 实际执行请求的函数
+     * @returns 请求结果
+     */
+    execute<T>(method: string, url: string, execute: () => Promise<T>): Promise<T>;
+    /**
+     * 包装 fetch 函数
+     *
+     * @param fetch - 原始 fetch 函数
+     * @returns 去重的 fetch 函数
+     */
+    wrap(fetch: (url: string, init?: RequestInit) => Promise<Response>): (url: string, init?: RequestInit) => Promise<Response>;
+    /**
+     * 获取当前飞行中的请求数量
+     */
+    get inflightCount(): number;
+    /**
+     * 清空所有飞行中的请求
+     */
+    clear(): void;
+    /**
+     * 判断是否应该去重
+     */
+    private shouldDeduplicate;
+    /**
+     * 默认的键生成函数
+     */
+    private defaultGenerateKey;
+    /**
+     * 清理过期的请求
+     */
+    private cleanup;
+}
+/**
+ * 创建请求去重器
+ */
+declare function createRequestDeduper(config?: DeduplicationConfig): RequestDeduper;
+
+/**
+ * 指标收集插件
+ *
+ * 收集请求级别的性能指标
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * 默认指标收集器实现
+ */
+declare class DefaultMetricsCollector implements MetricsCollector {
+    private metrics;
+    private readonly maxMetrics;
+    private readonly ttlMs;
+    private readonly onMetrics?;
+    constructor(config?: MetricsCollectorConfig);
+    record(metrics: RequestMetrics): void;
+    summary(): MetricsSummary;
+    getAll(): readonly RequestMetrics[];
+    getByPath(path: string): readonly RequestMetrics[];
+    flush(): readonly RequestMetrics[];
+    clear(): void;
+    private cleanup;
+    private emptySummary;
+}
+/**
+ * 创建指标收集器
+ */
+declare function createMetricsCollector(config?: MetricsCollectorConfig): MetricsCollector;
+/**
+ * 指标请求拦截器
+ *
+ * 在请求开始时记录时间戳
+ */
+declare class MetricsRequestInterceptor implements RequestInterceptor {
+    readonly name = "metrics-request";
+    readonly order = -1000;
+    intercept(context: RequestContext$1): MutableRequestOptions;
+}
+/**
+ * 指标响应拦截器
+ *
+ * 在请求成功时记录指标
+ */
+declare class MetricsResponseInterceptor implements ResponseInterceptor {
+    private readonly collector;
+    readonly name = "metrics-response";
+    readonly order = 1000;
+    constructor(collector: MetricsCollector);
+    intercept<T>(response: ResponseData<T>, context: RequestContext$1): ResponseData<T>;
+}
+/**
+ * 指标错误拦截器
+ *
+ * 在请求失败时记录指标
+ */
+declare class MetricsErrorInterceptor implements ErrorInterceptor {
+    private readonly collector;
+    readonly name = "metrics-error";
+    readonly order = 1000;
+    constructor(collector: MetricsCollector);
+    intercept<T>(error: Error, context: RequestContext$1): void | ResponseData<T>;
+}
+/**
+ * 创建指标拦截器集合
+ */
+declare function createMetricsInterceptors(collector: MetricsCollector): {
+    request: MetricsRequestInterceptor;
+    response: MetricsResponseInterceptor;
+    error: MetricsErrorInterceptor;
+};
+
+/**
+ * 日志插件
+ *
+ * 提供可配置的日志器实现
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * 控制台日志器
+ *
+ * 将日志输出到控制台
+ */
+declare class ConsoleLogger implements Logger {
+    private readonly prefix;
+    private readonly level;
+    private readonly timestamp;
+    private readonly levelPriority;
+    constructor(config?: ConsoleLoggerConfig);
+    debug(message: string, ...args: unknown[]): void;
+    info(message: string, ...args: unknown[]): void;
+    warn(message: string, ...args: unknown[]): void;
+    error(message: string, ...args: unknown[]): void;
+    private log;
+    private formatMessage;
+}
+/**
+ * 创建控制台日志器
+ */
+declare function createConsoleLogger(config?: ConsoleLoggerConfig): ConsoleLogger;
+/**
+ * 静默日志器
+ *
+ * 不输出任何日志
+ */
+declare class SilentLogger implements Logger {
+    debug(_message: string, ..._args: unknown[]): void;
+    info(_message: string, ..._args: unknown[]): void;
+    warn(_message: string, ..._args: unknown[]): void;
+    error(_message: string, ..._args: unknown[]): void;
+}
+/**
+ * 创建静默日志器
+ */
+declare function createSilentLogger(): SilentLogger;
+/**
+ * 静默日志器单例
+ */
+declare const silentLogger: SilentLogger;
+/**
+ * 缓冲日志器
+ *
+ * 将日志存储在内存中，用于测试
+ */
+declare class BufferLogger implements Logger {
+    private readonly buffer;
+    private readonly maxSize;
+    constructor(maxSize?: number);
+    debug(message: string, ...args: unknown[]): void;
+    info(message: string, ...args: unknown[]): void;
+    warn(message: string, ...args: unknown[]): void;
+    error(message: string, ...args: unknown[]): void;
+    /**
+     * 获取所有日志
+     */
+    getLogs(): ReadonlyArray<{
+        level: LogLevel;
+        message: string;
+        args: unknown[];
+        timestamp: Date;
+    }>;
+    /**
+     * 获取指定级别的日志
+     */
+    getLogsByLevel(level: LogLevel): ReadonlyArray<{
+        level: LogLevel;
+        message: string;
+        args: unknown[];
+        timestamp: Date;
+    }>;
+    /**
+     * 清空日志
+     */
+    clear(): void;
+    /**
+     * 获取日志数量
+     */
+    get size(): number;
+    private add;
+}
+/**
+ * 创建缓冲日志器
+ */
+declare function createBufferLogger(maxSize?: number): BufferLogger;
+
+/**
+ * 基础客户端抽象类
+ *
+ * 定义 HTTP 客户端的基本接口和生命周期
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * 基础客户端抽象类
+ *
+ * 提供：
+ * 1. 配置管理
+ * 2. 拦截器管理
+ * 3. 认证管理
+ * 4. 请求上下文创建
+ */
+declare abstract class BaseClient {
+    protected readonly config: ClientConfig;
+    protected readonly interceptorManager: InterceptorManager;
+    protected readonly authenticator: Authenticator;
+    constructor(config: ClientConfig);
+    /**
+     * 发起请求（子类实现）
+     */
+    abstract request<T>(options: RequestOptions): Promise<T>;
+    /**
+     * GET 请求
+     */
+    get<T>(path: string, query?: Record<string, string | number | boolean | undefined | null>): Promise<T>;
+    /**
+     * POST 请求
+     */
+    post<T>(path: string, body?: unknown, query?: Record<string, string | number | boolean | undefined | null>): Promise<T>;
+    /**
+     * PUT 请求
+     */
+    put<T>(path: string, body?: unknown): Promise<T>;
+    /**
+     * PATCH 请求
+     */
+    patch<T>(path: string, body?: unknown): Promise<T>;
+    /**
+     * DELETE 请求
+     */
+    delete<T>(path: string): Promise<T>;
+    /**
+     * 获取拦截器管理器
+     */
+    get interceptors(): InterceptorManager;
+    /**
+     * 创建请求上下文
+     */
+    protected createRequestContext(options: RequestOptions): RequestContext$1;
+    /**
+     * 执行请求拦截器
+     */
+    protected runRequestInterceptors(context: RequestContext$1): Promise<MutableRequestOptions>;
+    /**
+     * 执行响应拦截器
+     */
+    protected runResponseInterceptors<T>(response: ResponseData<T>, context: RequestContext$1): Promise<ResponseData<T>>;
+    /**
+     * 执行错误拦截器
+     */
+    protected runErrorInterceptors<T>(error: Error, context: RequestContext$1): Promise<ResponseData<T> | void>;
+    /**
+     * 注册配置中的拦截器
+     */
+    private registerConfigInterceptors;
+}
+
+/**
+ * Fetch 客户端实现
+ *
+ * 基于原生 fetch API 的 HTTP 客户端
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Fetch 客户端配置
+ */
+interface FetchClientConfig extends ClientConfig {
+    /**
+     * 是否启用自动重试
+     * @default true
+     */
+    readonly enableRetry?: boolean;
+}
+/**
+ * Fetch 客户端
+ *
+ * 特点：
+ * 1. 基于原生 fetch API
+ * 2. 支持完整的拦截器链
+ * 3. 自动错误转换
+ * 4. 超时和取消支持
+ * 5. 自动重试
+ * 6. 调试日志
+ */
+declare class FetchClient extends BaseClient {
+    private readonly enableRetry;
+    constructor(config: FetchClientConfig);
+    /**
+     * 发起请求
+     */
+    request<T>(options: RequestOptions): Promise<T>;
+    /**
+     * 带重试的请求执行
+     */
+    private executeWithRetry;
+    /**
+     * 判断是否应该重试
+     */
+    private shouldRetry;
+    /**
+     * 执行单次请求
+     */
+    private executeRequest;
+    /**
+     * 构建完整 URL
+     */
+    private buildFullUrl;
+    /**
+     * 构建 fetch init 对象
+     */
+    private buildFetchInit;
+    /**
+     * 创建超时信号
+     */
+    private createTimeoutSignal;
+    /**
+     * 解析响应
+     */
+    private parseResponse;
+    /**
+     * 转换错误
+     */
+    private transformError;
+    /**
+     * 调试日志
+     */
+    private logDebug;
+    /**
+     * 错误日志
+     */
+    private logError;
+}
+/**
+ * 创建 Fetch 客户端
+ */
+declare function createFetchClient(config: FetchClientConfig): FetchClient;
+
+/**
+ * Axios 客户端实现
+ *
+ * 基于 Axios 的 HTTP 客户端，用于与 openapi-generator 生成的代码集成
+ *
+ * @packageDocumentation
+ */
+
+declare module 'axios' {
+    interface InternalAxiosRequestConfig {
+        __retryCount?: number;
+        __startTime?: number;
+        __requestId?: string;
+        __traceId?: string;
+    }
+}
+/**
+ * Axios 客户端配置
+ *
+ * 继承 ClientConfig 并添加 Axios 特有的选项
+ */
+interface AxiosClientConfig extends ClientConfig {
+    /**
+     * 是否启用自动重试
+     * @default true
+     */
+    readonly enableRetry?: boolean;
+}
+/**
+ * 创建配置好的 Axios 实例
+ *
+ * 用于注入到 openapi-generator 生成的 API 类中
+ *
+ * @example
+ * ```typescript
+ * import { createAxiosInstance, createConsoleLogger } from '@djvlc/openapi-client-core';
+ * import { PagesApi, Configuration } from './generated';
+ *
+ * const axiosInstance = createAxiosInstance({
+ *   baseUrl: '/api/admin',
+ *   auth: { type: 'bearer', getToken: () => localStorage.getItem('token') },
+ *   retry: { maxRetries: 2, initialDelayMs: 1000, maxDelayMs: 10000, backoff: 'exponential' },
+ *   logger: createConsoleLogger({ prefix: '[Admin API]' }),
+ *   debug: true,
+ * });
+ *
+ * const config = new Configuration();
+ * const pagesApi = new PagesApi(config, undefined, axiosInstance);
+ * ```
+ */
+declare function createAxiosInstance(config: AxiosClientConfig): AxiosInstance;
+
+/**
+ * Middleware 工厂
+ *
+ * 将 openapi-client-core 的功能转换为 typescript-fetch 生成代码的 Middleware 格式
+ *
+ * 生成代码的 Middleware 接口：
+ * - pre(context): 发请求前，可修改 url/init
+ * - post(context): 收到响应后，可读/替换 Response
+ * - onError(context): 网络错误时，可吞掉错误并返回兜底 Response
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * FetchAPI 类型（与生成代码兼容）
+ */
+type FetchAPI = WindowOrWorkerGlobalScope['fetch'];
+/**
+ * 请求上下文（生成代码格式）
+ */
+interface RequestContext {
+    fetch: FetchAPI;
+    url: string;
+    init: RequestInit;
+}
+/**
+ * 响应上下文（生成代码格式）
+ */
+interface ResponseContext {
+    fetch: FetchAPI;
+    url: string;
+    init: RequestInit;
+    response: Response;
+}
+/**
+ * 错误上下文（生成代码格式）
+ */
+interface ErrorContext {
+    fetch: FetchAPI;
+    url: string;
+    init: RequestInit;
+    error: unknown;
+    response?: Response;
+}
+/**
+ * Fetch 参数
+ */
+interface FetchParams {
+    url: string;
+    init: RequestInit;
+}
+/**
+ * Middleware 接口（与生成代码兼容）
+ */
+interface Middleware {
+    pre?(context: RequestContext): Promise<FetchParams | void>;
+    post?(context: ResponseContext): Promise<Response | void>;
+    onError?(context: ErrorContext): Promise<Response | void>;
+}
+/**
+ * Middleware 工厂配置
+ */
+interface MiddlewareConfig {
+    /** 认证配置 */
+    auth?: AuthConfig;
+    /** 重试配置 */
+    retry?: RetryConfig;
+    /** 是否启用重试 */
+    enableRetry?: boolean;
+    /** 日志器 */
+    logger?: Logger;
+    /** 是否开启调试模式 */
+    debug?: boolean;
+    /** 超时时间（毫秒） */
+    timeout?: number;
+    /** 额外的请求头 */
+    headers?: Record<string, string>;
+    /** 自定义 pre 中间件 */
+    preMiddlewares?: Array<(context: RequestContext) => Promise<FetchParams | void>>;
+    /** 自定义 post 中间件 */
+    postMiddlewares?: Array<(context: ResponseContext) => Promise<Response | void>>;
+    /** 自定义 onError 中间件 */
+    errorMiddlewares?: Array<(context: ErrorContext) => Promise<Response | void>>;
+}
+/**
+ * 创建 Middleware 数组
+ *
+ * 将 openapi-client-core 的功能转换为生成代码兼容的 Middleware 格式
+ *
+ * @param config - 配置选项
+ * @returns Middleware 数组，可直接传给 Configuration
+ *
+ * @example
+ * ```typescript
+ * import { createMiddlewares, createConsoleLogger } from '@djvlc/openapi-client-core';
+ * import { Configuration, PagesApi } from '@djvlc/openapi-admin-client';
+ *
+ * const middlewares = createMiddlewares({
+ *   auth: { type: 'bearer', getToken: () => token },
+ *   retry: { maxRetries: 3, backoffStrategy: 'exponential' },
+ *   logger: createConsoleLogger({ prefix: '[API]' }),
+ *   debug: true,
+ * });
+ *
+ * const config = new Configuration({
+ *   basePath: '/api/admin',
+ *   middleware: middlewares,
+ * });
+ *
+ * const api = new PagesApi(config);
+ * ```
+ */
+declare function createMiddlewares(config?: MiddlewareConfig): Middleware[];
+/**
+ * 创建认证中间件
+ */
+declare function createAuthMiddleware(authConfig: AuthConfig): Middleware;
+/**
+ * 创建请求追踪中间件
+ */
+declare function createTrackingMiddleware(): Middleware;
+
+/**
+ * 请求 ID 生成工具
+ *
+ * @packageDocumentation
+ */
+/**
+ * 生成请求 ID
+ *
+ * 格式: req_{timestamp}_{random}
+ * 例如: req_m5abc123_k7def456
+ *
+ * @returns 唯一的请求 ID
+ */
+declare function generateRequestId(): string;
+/**
+ * 生成追踪 ID
+ *
+ * 格式: trace_{timestamp}_{random}_{random}
+ * 例如: trace_m5abc123_k7def456_x8ghi789
+ *
+ * @returns 唯一的追踪 ID
+ */
+declare function generateTraceId(): string;
+/**
+ * 验证请求 ID 格式
+ *
+ * @param id - 待验证的 ID
+ * @returns 是否为有效的请求 ID
+ */
+declare function isValidRequestId(id: string): boolean;
+/**
+ * 验证追踪 ID 格式
+ *
+ * @param id - 待验证的 ID
+ * @returns 是否为有效的追踪 ID
+ */
+declare function isValidTraceId(id: string): boolean;
+
+/**
+ * 重试延迟计算工具
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * 计算重试延迟（毫秒）
+ *
+ * @param config - 重试配置
+ * @param attempt - 当前重试次数（从 0 开始）
+ * @returns 延迟时间（毫秒）
+ */
+declare function calculateRetryDelay(config: RetryConfig, attempt: number): number;
+/**
+ * 解析 Retry-After 响应头
+ *
+ * 支持两种格式：
+ * 1. 秒数: "120"
+ * 2. HTTP 日期: "Wed, 21 Oct 2015 07:28:00 GMT"
+ *
+ * @param retryAfter - Retry-After 头的值
+ * @returns 延迟时间（秒），如果解析失败则返回 undefined
+ */
+declare function parseRetryAfter(retryAfter: string | null | undefined): number | undefined;
+/**
+ * 获取推荐的重试延迟
+ *
+ * 优先使用 Retry-After 头的值
+ *
+ * @param config - 重试配置
+ * @param attempt - 当前重试次数
+ * @param retryAfterSeconds - Retry-After 头的值（秒）
+ * @returns 延迟时间（毫秒）
+ */
+declare function getRecommendedRetryDelay(config: RetryConfig, attempt: number, retryAfterSeconds?: number): number;
+
+/**
+ * 延迟执行工具
+ *
+ * @packageDocumentation
+ */
+/**
+ * 延迟执行
+ *
+ * @param ms - 延迟时间（毫秒）
+ * @returns Promise，在指定时间后 resolve
+ */
+declare function sleep(ms: number): Promise<void>;
+/**
+ * 可取消的延迟执行
+ *
+ * @param ms - 延迟时间（毫秒）
+ * @param signal - AbortSignal，用于取消延迟
+ * @returns Promise，在指定时间后 resolve，或在取消时 reject
+ */
+declare function sleepWithAbort(ms: number, signal?: AbortSignal): Promise<void>;
+
+/**
+ * URL 处理工具
+ *
+ * @packageDocumentation
+ */
+/**
+ * 查询参数值类型
+ */
+type QueryParamValue = string | number | boolean | undefined | null;
+/**
+ * 查询参数对象类型
+ */
+type QueryParams = Record<string, QueryParamValue>;
+/**
+ * 构建完整 URL
+ *
+ * @param baseUrl - 基础 URL
+ * @param path - 路径
+ * @param query - 查询参数
+ * @returns 完整 URL
+ */
+declare function buildUrl(baseUrl: string, path: string, query?: QueryParams): string;
+/**
+ * 从 URL 提取路径（不含查询参数）
+ *
+ * @param url - 完整 URL
+ * @returns 路径
+ */
+declare function extractPath(url: string): string;
+/**
+ * 解析查询字符串
+ *
+ * @param queryString - 查询字符串（可以包含或不包含 ?）
+ * @returns 解析后的参数对象
+ */
+declare function parseQueryString(queryString: string): Record<string, string>;
+/**
+ * 合并两个 URL 路径
+ *
+ * @param base - 基础路径
+ * @param path - 要追加的路径
+ * @returns 合并后的路径
+ */
+declare function joinPaths(base: string, path: string): string;
+
+/**
+ * 请求头处理工具
+ *
+ * @packageDocumentation
+ */
+/**
+ * 默认请求头
+ */
+declare const DEFAULT_HEADERS: Readonly<Record<string, string>>;
+/**
+ * 合并请求头
+ *
+ * 后面的头会覆盖前面的同名头（大小写不敏感）
+ *
+ * @param headersList - 要合并的请求头列表
+ * @returns 合并后的请求头
+ */
+declare function mergeHeaders(...headersList: (Record<string, string> | undefined)[]): Record<string, string>;
+/**
+ * 获取请求头值（大小写不敏感）
+ *
+ * @param headers - 请求头对象
+ * @param name - 头名称
+ * @returns 头的值，不存在则返回 undefined
+ */
+declare function getHeader(headers: Record<string, string>, name: string): string | undefined;
+/**
+ * 设置请求头（大小写不敏感，会替换同名头）
+ *
+ * @param headers - 请求头对象（会被修改）
+ * @param name - 头名称
+ * @param value - 头的值
+ */
+declare function setHeader(headers: Record<string, string>, name: string, value: string): void;
+/**
+ * 删除请求头（大小写不敏感）
+ *
+ * @param headers - 请求头对象（会被修改）
+ * @param name - 头名称
+ * @returns 是否删除成功
+ */
+declare function removeHeader(headers: Record<string, string>, name: string): boolean;
+/**
+ * 从 Response 对象提取请求头
+ *
+ * @param response - Response 对象
+ * @returns 请求头对象
+ */
+declare function extractResponseHeaders(response: Response): Record<string, string>;
+/**
+ * 检查是否包含指定的 Content-Type
+ *
+ * @param headers - 请求头对象
+ * @param contentType - 要检查的内容类型
+ * @returns 是否匹配
+ */
+declare function hasContentType(headers: Record<string, string>, contentType: string): boolean;
+
+/**
+ * @djvlc/openapi-client-core
+ *
+ * OpenAPI 客户端公共运行时
+ *
+ * 提供模块化的 HTTP 客户端能力：
+ * - 类型定义（types/）
+ * - 错误处理（errors/）
+ * - 认证（auth/）
+ * - 拦截器（interceptors/）
+ * - 插件（plugins/）
+ * - 客户端（clients/）
+ * - 工具函数（utils/）
+ *
+ * @packageDocumentation
+ */
+declare const VERSION = "2.0.0";
+declare const SDK_NAME = "@djvlc/openapi-client-core";
+/**
+ * 获取 SDK 信息
+ */
+declare function getSdkInfo(): {
+    name: string;
+    version: string;
+};
 
-export { ApiError, type AuthConfig, type ClientConfig, type ErrorInterceptor, HttpClient, NetworkError, type RequestInterceptor, type RequestOptions, type ResponseInterceptor, type RetryConfig, TimeoutError, VERSION, calculateRetryDelay, createAxiosInstance, createClient, generateRequestId, sleep };
+export { AbortError, ApiError, type ApiErrorConfig, type ApiErrorDetail, type ApiKeyAuthConfig, ApiKeyAuthenticator, type AuthConfig, AuthInterceptor, type AuthInterceptorConfig, type AuthType, type Authenticator, type AuthenticatorFactory, type AxiosClientConfig, type BackoffStrategy, BaseClient, BaseClientError, type BasicAuthConfig, BasicAuthenticator, type BearerAuthConfig, BearerAuthenticator, BufferLogger, type ClientConfig, ConsoleLogger, type ConsoleLoggerConfig, type CustomAuthConfig, CustomAuthenticator, DEFAULT_HEADERS, DEFAULT_RETRY_CONFIG, type DeduplicationConfig, DefaultMetricsCollector, type ErrorInterceptor, type ErrorInterceptorFactory, type ErrorReporter, type ErrorSeverity, ErrorTransformInterceptor, type ErrorTransformInterceptorConfig, FetchClient, type FetchClientConfig, type HttpMethod, type InterceptorChainResult, InterceptorManager, type Interceptors, LOG_LEVEL_PRIORITY, type LogLevel, type Logger, LoggingInterceptor, type LoggingInterceptorConfig, type MetricsCollector, type MetricsCollectorConfig, MetricsErrorInterceptor, MetricsRequestInterceptor, MetricsResponseInterceptor, type MetricsSummary, type MiddlewareConfig, type MutableRequestOptions, NetworkError, type NoAuthConfig, NoAuthenticator, type PathMetrics, type QueryParamValue, type QueryParams, ReportingInterceptor, type ReportingInterceptorConfig, type RequestContext$1 as RequestContext, RequestDeduper, RequestIdInterceptor, type RequestIdInterceptorConfig, type RequestInterceptor, type RequestInterceptorFactory, type RequestMetrics, type RequestOptions, type ResponseData, type ResponseInterceptor, type ResponseInterceptorFactory, type RetryCallback, type RetryConfig, type RetryContext, type RetryInfo, RetryInterceptor, type RetryInterceptorConfig, SDK_NAME, type ShouldRetryFn, SilentLogger, TimeoutError, TimeoutInterceptor, type TimeoutInterceptorConfig, type TokenRefreshConfig, TokenRefreshInterceptor, type TokenRefreshInterceptorConfig, TraceInterceptor, type TraceInterceptorConfig, VERSION, buildUrl, calculateRetryDelay, createApiKeyAuthenticator, createAuthInterceptor, createAuthMiddleware, createAuthenticatorFromConfig, createAxiosInstance, createBasicAuthenticator, createBearerAuthenticator, createBufferLogger, createConsoleLogger, createCustomAuthenticator, createErrorTransformInterceptor, createFetchClient, createInterceptorManager, createLoggingInterceptor, createMetricsCollector, createMetricsInterceptors, createMiddlewares, createNoAuthenticator, createReportingInterceptor, createRequestDeduper, createRequestIdInterceptor, createRetryInterceptor, createSilentLogger, createTimeoutInterceptor, createTokenRefreshInterceptor, createTraceInterceptor, createTrackingMiddleware, extractPath, extractResponseHeaders, generateRequestId, generateTraceId, getErrorType, getHeader, getRecommendedRetryDelay, getRetryDelay, getSdkInfo, hasContentType, isClientError, isRetryableError, isValidRequestId, isValidTraceId, joinPaths, mergeHeaders, noAuthenticator, parseQueryString, parseRetryAfter, removeHeader, setHeader, silentLogger, sleep, sleepWithAbort };