@djvlc/openapi-client-core 1.0.0

package/dist/index.d.mts

@@ -0,0 +1,996 @@
+/**
+ * @djvlc/openapi-client-core - 版本信息
+ *
+ * 版本号在构建时由 tsup 注入，避免手动维护。
+ */
+/**
+ * SDK 版本号（构建时注入）
+ */
+declare const SDK_VERSION: string;
+/**
+ * SDK 名称（构建时注入）
+ */
+declare const SDK_NAME: string;
+/**
+ * 获取 SDK 版本信息
+ */
+declare function getSdkInfo(): {
+    name: string;
+    version: string;
+};
+
+/**
+ * @djvlc/openapi-client-core - 错误类定义
+ *
+ * 提供结构化的错误类型，便于调用方区分和处理不同类型的错误。
+ *
+ * 错误层次：
+ *   - DjvApiError: 业务层错误（服务器返回的错误响应）
+ *   - NetworkError: 网络层错误（连接失败、DNS 解析失败等）
+ *   - TimeoutError: 超时错误（继承自 NetworkError）
+ *   - AbortError: 请求被取消（继承自 NetworkError）
+ */
+/**
+ * API 业务错误
+ *
+ * 当服务器返回非 2xx 响应时抛出，包含完整的错误信息。
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await client.PageApi.resolvePage({ pageUid: 'xxx' });
+ * } catch (e) {
+ *   if (DjvApiError.is(e)) {
+ *     console.log('业务错误:', e.code, e.message);
+ *     console.log('追踪ID:', e.traceId);
+ *
+ *     // 使用增强方法
+ *     if (e.isAuthError()) {
+ *       redirectToLogin();
+ *     } else if (e.isRateLimited()) {
+ *       const retryAfter = e.getRetryAfter();
+ *       await delay(retryAfter * 1000);
+ *     }
+ *   }
+ * }
+ * ```
+ */
+declare class DjvApiError extends Error {
+    /** 业务错误码（可能是字符串如 'INVALID_REQUEST' 或数字如 1001） */
+    readonly code: string | number;
+    /** HTTP 状态码 */
+    readonly status: number;
+    /** 追踪 ID（用于日志排查） */
+    readonly traceId?: string | undefined;
+    /** 详细错误信息（字段级错误等） */
+    readonly details?: unknown | undefined;
+    /** 原始响应对象 */
+    readonly response?: Response | undefined;
+    /** 标识这是一个 API 错误（用于 instanceof 替代方案） */
+    readonly isApiError: true;
+    /** 错误名称 */
+    readonly name: "DjvApiError";
+    constructor(message: string, 
+    /** 业务错误码（可能是字符串如 'INVALID_REQUEST' 或数字如 1001） */
+    code: string | number, 
+    /** HTTP 状态码 */
+    status: number, 
+    /** 追踪 ID（用于日志排查） */
+    traceId?: string | undefined, 
+    /** 详细错误信息（字段级错误等） */
+    details?: unknown | undefined, 
+    /** 原始响应对象 */
+    response?: Response | undefined);
+    /**
+     * 是否为认证错误 (401 Unauthorized)
+     */
+    isUnauthorized(): boolean;
+    /**
+     * 是否为权限错误 (403 Forbidden)
+     */
+    isForbidden(): boolean;
+    /**
+     * 是否为认证相关错误 (401 或 403)
+     */
+    isAuthError(): boolean;
+    /**
+     * 是否为客户端错误 (4xx)
+     */
+    isClientError(): boolean;
+    /**
+     * 是否为服务端错误 (5xx)
+     */
+    isServerError(): boolean;
+    /**
+     * 是否为限流错误 (429 Too Many Requests)
+     */
+    isRateLimited(): boolean;
+    /**
+     * 是否为资源未找到 (404 Not Found)
+     */
+    isNotFound(): boolean;
+    /**
+     * 是否为请求冲突 (409 Conflict)
+     */
+    isConflict(): boolean;
+    /**
+     * 是否为请求验证失败 (400 Bad Request 或 422 Unprocessable Entity)
+     */
+    isValidationError(): boolean;
+    /**
+     * 获取 Retry-After 头的值（秒）
+     *
+     * 适用于 429 限流响应和 503 服务不可用响应
+     *
+     * @returns 重试等待秒数，如果没有 Retry-After 头则返回 null
+     */
+    getRetryAfter(): number | null;
+    /**
+     * 获取重试延迟（毫秒）
+     *
+     * 优先使用 Retry-After 头，否则返回默认值
+     *
+     * @param defaultMs 默认延迟毫秒数
+     */
+    getRetryDelayMs(defaultMs?: number): number;
+    /**
+     * 类型保护：判断是否为 DjvApiError
+     */
+    static is(error: unknown): error is DjvApiError;
+    /**
+     * 从响应创建错误
+     */
+    static fromResponse(response: Response): Promise<DjvApiError>;
+    /**
+     * 转为 JSON（便于日志记录）
+     */
+    toJSON(): {
+        name: "DjvApiError";
+        message: string;
+        code: string | number;
+        status: number;
+        traceId: string | undefined;
+        details: unknown;
+    };
+}
+/**
+ * 网络层错误
+ *
+ * 当请求无法到达服务器时抛出（连接失败、DNS 解析失败、CORS 等）。
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await client.PageApi.resolvePage({ pageUid: 'xxx' });
+ * } catch (e) {
+ *   if (NetworkError.is(e)) {
+ *     console.log('网络错误，请检查网络连接');
+ *   }
+ * }
+ * ```
+ */
+declare class NetworkError extends Error {
+    /** 标识这是一个网络错误 */
+    readonly isNetworkError: true;
+    /** 错误名称 */
+    readonly name: string;
+    /** 原始错误 */
+    readonly originalCause?: Error;
+    constructor(message: string, 
+    /** 原始错误 */
+    cause?: Error);
+    /**
+     * 获取原始错误
+     */
+    get cause(): Error | undefined;
+    /**
+     * 类型保护：判断是否为 NetworkError（包括子类）
+     */
+    static is(error: unknown): error is NetworkError;
+    /**
+     * 从原始错误创建
+     */
+    static fromError(error: unknown): NetworkError | AbortError;
+    toJSON(): Record<string, unknown>;
+}
+/**
+ * 超时错误
+ *
+ * 当请求超过指定时间未响应时抛出。
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await client.PageApi.resolvePage({ pageUid: 'xxx' });
+ * } catch (e) {
+ *   if (TimeoutError.is(e)) {
+ *     console.log(`请求超时 (${e.timeoutMs}ms)，请稍后重试`);
+ *   }
+ * }
+ * ```
+ */
+declare class TimeoutError extends NetworkError {
+    /** 超时时间（毫秒） */
+    readonly timeoutMs: number;
+    /** 请求 URL */
+    readonly url?: string | undefined;
+    /** 标识这是一个超时错误 */
+    readonly isTimeout: true;
+    readonly name: string;
+    constructor(
+    /** 超时时间（毫秒） */
+    timeoutMs: number, 
+    /** 请求 URL */
+    url?: string | undefined);
+    /**
+     * 类型保护：判断是否为 TimeoutError
+     */
+    static is(error: unknown): error is TimeoutError;
+    toJSON(): Record<string, unknown>;
+}
+/**
+ * 请求取消错误
+ *
+ * 当请求被用户手动取消时抛出。
+ *
+ * @example
+ * ```typescript
+ * const controller = new AbortController();
+ * setTimeout(() => controller.abort(), 100);
+ *
+ * try {
+ *   await client.PageApi.resolvePage({ pageUid: 'xxx' }, { signal: controller.signal });
+ * } catch (e) {
+ *   if (AbortError.is(e)) {
+ *     console.log('请求已取消');
+ *   }
+ * }
+ * ```
+ */
+declare class AbortError extends NetworkError {
+    /** 标识这是一个取消错误 */
+    readonly isAbort: true;
+    readonly name: string;
+    constructor(message?: string);
+    /**
+     * 类型保护：判断是否为 AbortError
+     */
+    static is(error: unknown): error is AbortError;
+}
+/**
+ * 判断错误是否可重试
+ *
+ * 可重试的情况：
+ * - 超时错误
+ * - 网络错误（非取消）
+ * - 特定 HTTP 状态码：408, 429, 500, 502, 503, 504
+ */
+declare function isRetryableError(error: unknown): boolean;
+/**
+ * 获取错误的推荐重试延迟（毫秒）
+ *
+ * 优先使用 Retry-After 头，否则返回默认值
+ */
+declare function getRetryDelay(error: unknown, defaultMs?: number): number;
+
+/**
+ * @djvlc/openapi-client-core - 公共类型定义
+ */
+/**
+ * 请求上下文（Middleware 使用）
+ */
+interface RequestContext {
+    /** 请求 URL */
+    url: string;
+    /** 请求初始化配置 */
+    init: RequestInit;
+    /** 额外元数据 */
+    meta?: Record<string, unknown>;
+}
+/**
+ * 响应上下文（Middleware 使用）
+ */
+interface ResponseContext extends RequestContext {
+    /** 响应对象 */
+    response: Response;
+    /** 请求耗时（毫秒） */
+    durationMs: number;
+}
+/**
+ * Middleware 定义
+ */
+interface Middleware {
+    /** 请求前钩子 */
+    pre?: (context: RequestContext) => Promise<RequestContext> | RequestContext;
+    /** 响应后钩子 */
+    post?: (context: ResponseContext) => Promise<void> | void;
+}
+/**
+ * 重试配置
+ */
+interface RetryOptions {
+    /** 最大重试次数（默认 0 不重试） */
+    maxRetries?: number;
+    /** 重试延迟基数（毫秒，默认 1000） */
+    retryDelayMs?: number;
+    /** 是否使用指数退避（默认 true） */
+    exponentialBackoff?: boolean;
+    /** 最大延迟时间（毫秒，默认 30000） */
+    maxDelayMs?: number;
+    /** 可重试的 HTTP 状态码（默认 [408, 429, 500, 502, 503, 504]） */
+    retryableStatuses?: number[];
+    /** 自定义重试判断函数 */
+    shouldRetry?: (error: unknown, attempt: number) => boolean;
+    /** 重试前回调（用于日志等） */
+    onRetry?: (error: unknown, attempt: number, delayMs: number) => void;
+    /**
+     * 是否尊重 Retry-After 响应头
+     *
+     * 当服务器返回 429 或 503 时，优先使用 Retry-After 头中的延迟时间
+     *
+     * @default true
+     */
+    respectRetryAfter?: boolean;
+}
+/**
+ * 日志接口
+ */
+interface Logger {
+    /** 请求日志 */
+    request?: (url: string, init: RequestInit) => void;
+    /** 响应日志 */
+    response?: (url: string, response: Response, durationMs: number) => void;
+    /** 错误日志 */
+    error?: (url: string, error: unknown) => void;
+    /** 重试日志 */
+    retry?: (url: string, attempt: number, error: unknown) => void;
+}
+/**
+ * 拦截器配置
+ */
+interface Interceptors {
+    /** 请求拦截器 */
+    request?: RequestInterceptor[];
+    /** 响应拦截器 */
+    response?: ResponseInterceptor[];
+    /** 错误拦截器 */
+    error?: ErrorInterceptor[];
+}
+/**
+ * 请求拦截器
+ */
+type RequestInterceptor = (context: RequestContext) => Promise<RequestContext> | RequestContext;
+/**
+ * 响应拦截器
+ */
+type ResponseInterceptor = (response: Response, context: RequestContext) => Promise<Response> | Response;
+/**
+ * 错误拦截器
+ */
+type ErrorInterceptor = (error: unknown, context: RequestContext) => Promise<unknown> | unknown;
+/**
+ * 基础客户端配置
+ */
+interface BaseClientOptions {
+    /** 基础 URL */
+    baseUrl: string;
+    /** 获取认证 Token（Bearer） */
+    getAuthToken?: () => string | Promise<string>;
+    /** 获取 API Key */
+    getApiKey?: () => string | Promise<string>;
+    /** 获取追踪头（OpenTelemetry） */
+    getTraceHeaders?: () => Record<string, string>;
+    /** 默认请求头 */
+    defaultHeaders?: Record<string, string>;
+    /** 超时时间（毫秒，默认 30000） */
+    timeoutMs?: number;
+    /** 自定义 fetch 实现 */
+    fetchApi?: typeof fetch;
+    /** Cookie 策略（默认 'omit'） */
+    credentials?: RequestCredentials;
+    /** 重试配置 */
+    retry?: RetryOptions;
+    /** 日志配置 */
+    logger?: Logger;
+    /** 是否开启调试模式 */
+    debug?: boolean;
+    /** Middleware 列表 */
+    middleware?: Middleware[];
+    /** 拦截器 */
+    interceptors?: Interceptors;
+}
+/**
+ * 请求额外配置（每个请求可覆盖）
+ */
+interface RequestOptions {
+    /** 取消信号 */
+    signal?: AbortSignal;
+    /** 超时时间（覆盖全局配置） */
+    timeoutMs?: number;
+    /** 是否跳过重试 */
+    skipRetry?: boolean;
+    /** 额外请求头 */
+    headers?: Record<string, string>;
+}
+/**
+ * SDK 版本信息（自动注入）
+ */
+interface SdkInfo {
+    /** 包名 */
+    name: string;
+    /** 版本号 */
+    version: string;
+    /** 平台信息 */
+    platform?: string;
+}
+/**
+ * Configuration 参数（兼容生成代码）
+ */
+interface ConfigurationParameters {
+    basePath?: string;
+    fetchApi?: typeof fetch;
+    middleware?: Middleware[];
+    credentials?: RequestCredentials;
+    headers?: (() => Promise<Record<string, string>> | Record<string, string>) | Record<string, string>;
+}
+
+/**
+ * @djvlc/openapi-client-core - 工具函数
+ */
+/**
+ * 移除 URL 末尾的斜杠
+ */
+declare function stripTrailingSlash(url: string): string;
+/**
+ * 标准化 Headers
+ */
+declare function normalizeHeaders(initHeaders: HeadersInit | undefined): Headers;
+/**
+ * 合并多个 Headers
+ */
+declare function mergeHeaders(...headersList: (HeadersInit | undefined)[]): Headers;
+/**
+ * 延迟指定时间
+ */
+declare function delay(ms: number): Promise<void>;
+/**
+ * 计算指数退避延迟
+ */
+declare function calculateBackoffDelay(attempt: number, baseDelayMs: number, maxDelayMs: number, exponential?: boolean): number;
+/**
+ * 获取当前运行平台
+ */
+declare function getPlatform(): string;
+/**
+ * 生成 SDK User-Agent 字符串
+ */
+declare function buildUserAgent(sdkName: string, sdkVersion: string): string;
+/**
+ * 判断是否为浏览器环境
+ */
+declare function isBrowser(): boolean;
+/**
+ * 安全解析 JSON
+ */
+declare function safeParseJson<T = unknown>(response: Response): Promise<T | null>;
+/**
+ * 克隆响应（用于读取 body 后仍保留原响应）
+ */
+declare function cloneResponse(response: Response): Response;
+
+/**
+ * @djvlc/openapi-client-core - Fetch 增强
+ *
+ * 提供超时、重试、取消等能力的 fetch 封装。
+ */
+
+/**
+ * 创建带超时的 fetch
+ */
+declare function createFetchWithTimeout(fetchImpl: typeof fetch, timeoutMs: number): typeof fetch;
+/**
+ * 创建带重试的 fetch
+ */
+declare function createFetchWithRetry(fetchImpl: typeof fetch, options?: RetryOptions, logger?: Logger): typeof fetch;
+/**
+ * 创建增强版 fetch（组合超时 + 重试 + 日志）
+ */
+declare function createEnhancedFetch(options: {
+    fetchApi?: typeof fetch;
+    timeoutMs?: number;
+    retry?: RetryOptions;
+    logger?: Logger;
+}): typeof fetch;
+/**
+ * 执行请求并处理错误
+ *
+ * 统一处理响应，非 2xx 响应转换为 DjvApiError
+ */
+declare function executeRequest(fetchFn: typeof fetch, url: string, init: RequestInit, options?: RequestOptions): Promise<Response>;
+
+/**
+ * @djvlc/openapi-client-core - Middleware 系统
+ *
+ * 提供请求/响应拦截、认证注入、追踪头注入等能力。
+ */
+
+/**
+ * 创建 Headers 注入 Middleware
+ *
+ * 统一处理：
+ * - 默认 Headers
+ * - Bearer Token
+ * - API Key
+ * - Trace Headers
+ * - SDK 版本
+ */
+declare function createHeadersMiddleware(opts: {
+    getAuthToken?: () => string | Promise<string>;
+    getApiKey?: () => string | Promise<string>;
+    getTraceHeaders?: () => Record<string, string>;
+    defaultHeaders?: Record<string, string>;
+    sdkInfo?: SdkInfo;
+}): Middleware;
+/**
+ * 创建日志 Middleware
+ */
+declare function createLoggingMiddleware(opts: {
+    onRequest?: (url: string, init: RequestInit) => void;
+    onResponse?: (url: string, response: Response, durationMs: number) => void;
+    onError?: (url: string, error: unknown) => void;
+}): Middleware;
+/**
+ * 应用 Middleware 链
+ */
+declare function applyMiddlewareChain(middlewares: Middleware[], context: RequestContext): Promise<RequestContext>;
+/**
+ * 应用 post Middleware 链
+ */
+declare function applyPostMiddlewareChain(middlewares: Middleware[], context: ResponseContext): Promise<void>;
+/**
+ * 从 ClientOptions 创建默认 Middleware 列表
+ */
+declare function createDefaultMiddlewares(opts: Pick<BaseClientOptions, 'getAuthToken' | 'getApiKey' | 'getTraceHeaders' | 'defaultHeaders' | 'logger' | 'debug'>, sdkInfo?: SdkInfo): Middleware[];
+
+/**
+ * @djvlc/openapi-client-core - 拦截器系统
+ *
+ * 提供更灵活的请求/响应/错误拦截能力。
+ */
+
+/**
+ * 拦截器管理器
+ */
+declare class InterceptorManager {
+    private requestInterceptors;
+    private responseInterceptors;
+    private errorInterceptors;
+    constructor(interceptors?: Interceptors);
+    /**
+     * 添加请求拦截器
+     * @returns 移除拦截器的函数
+     */
+    addRequestInterceptor(interceptor: RequestInterceptor): () => void;
+    /**
+     * 添加响应拦截器
+     * @returns 移除拦截器的函数
+     */
+    addResponseInterceptor(interceptor: ResponseInterceptor): () => void;
+    /**
+     * 添加错误拦截器
+     * @returns 移除拦截器的函数
+     */
+    addErrorInterceptor(interceptor: ErrorInterceptor): () => void;
+    /**
+     * 执行请求拦截器链
+     */
+    runRequestInterceptors(context: RequestContext): Promise<RequestContext>;
+    /**
+     * 执行响应拦截器链
+     */
+    runResponseInterceptors(response: Response, context: RequestContext): Promise<Response>;
+    /**
+     * 执行错误拦截器链
+     */
+    runErrorInterceptors(error: unknown, context: RequestContext): Promise<unknown>;
+    /**
+     * 清除所有拦截器
+     */
+    clear(): void;
+}
+/**
+ * 创建 Token 刷新拦截器
+ *
+ * 当收到 401 错误时自动刷新 token 并重试请求
+ */
+declare function createTokenRefreshInterceptor(options: {
+    /** 刷新 token 的函数 */
+    refreshToken: () => Promise<string>;
+    /** 判断是否需要刷新 */
+    shouldRefresh?: (response: Response) => boolean;
+    /** 最大刷新重试次数 */
+    maxRetries?: number;
+}): ResponseInterceptor;
+/**
+ * 创建请求去重拦截器
+ *
+ * 相同请求（URL + Method）在进行中时，复用同一个 Promise
+ */
+declare function createDedupeInterceptor(): {
+    interceptor: RequestInterceptor;
+    clear: () => void;
+};
+/**
+ * 创建请求缓存拦截器
+ *
+ * 缓存 GET 请求的响应
+ */
+declare function createCacheInterceptor(options: {
+    /** 缓存 TTL（毫秒） */
+    ttlMs?: number;
+    /** 判断是否应该缓存 */
+    shouldCache?: (context: RequestContext) => boolean;
+    /** 最大缓存条目数 */
+    maxSize?: number;
+}): {
+    requestInterceptor: RequestInterceptor;
+    responseInterceptor: ResponseInterceptor;
+    clear: () => void;
+};
+
+/**
+ * @djvlc/openapi-client-core - 请求去重
+ *
+ * 避免相同的 GET 请求并发执行多次，复用进行中的请求。
+ */
+/**
+ * 请求去重器选项
+ */
+interface DedupeOptions {
+    /**
+     * 生成请求唯一标识的函数
+     *
+     * 默认使用 `${method}:${url}`
+     */
+    keyGenerator?: (url: string, init?: RequestInit) => string;
+    /**
+     * 是否只对 GET 请求去重
+     *
+     * @default true
+     */
+    getOnly?: boolean;
+    /**
+     * 调试日志
+     */
+    onDedupe?: (key: string, pending: number) => void;
+}
+/**
+ * 请求去重器
+ *
+ * @example
+ * ```typescript
+ * const deduper = createRequestDeduper();
+ *
+ * // 包装 fetch
+ * const dedupedFetch = deduper.wrap(fetch);
+ *
+ * // 相同的请求只会执行一次
+ * const [r1, r2] = await Promise.all([
+ *   dedupedFetch('/api/user'),
+ *   dedupedFetch('/api/user'),
+ * ]);
+ * ```
+ */
+declare function createRequestDeduper(options?: DedupeOptions): {
+    /**
+     * 包装 fetch 函数，添加请求去重能力
+     */
+    wrap: (fetchFn: typeof fetch) => typeof fetch;
+    /**
+     * 获取当前进行中的请求数量
+     */
+    getPendingCount(): number;
+    /**
+     * 获取所有进行中的请求 key
+     */
+    getPendingKeys(): string[];
+    /**
+     * 清除所有进行中的请求记录
+     *
+     * 注意：这不会取消请求，只是清除去重映射
+     */
+    clear(): void;
+};
+/**
+ * 请求去重器类型
+ */
+type RequestDeduper = ReturnType<typeof createRequestDeduper>;
+
+/**
+ * @djvlc/openapi-client-core - 指标收集
+ *
+ * 提供请求级别的指标收集能力，用于可观测性和性能监控。
+ */
+
+/**
+ * 请求指标
+ */
+interface RequestMetrics {
+    /** 请求 ID（唯一标识） */
+    requestId: string;
+    /** 请求 URL */
+    url: string;
+    /** 请求路径（不含 base URL 和 query） */
+    path: string;
+    /** HTTP 方法 */
+    method: string;
+    /** 请求开始时间戳（毫秒） */
+    startTime: number;
+    /** 请求结束时间戳（毫秒） */
+    endTime: number;
+    /** 请求耗时（毫秒） */
+    durationMs: number;
+    /** HTTP 状态码 */
+    status: number;
+    /** 是否成功（2xx） */
+    success: boolean;
+    /** 是否来自缓存 */
+    fromCache?: boolean;
+    /** 重试次数 */
+    retryCount?: number;
+    /** 请求体大小（字节） */
+    requestSize?: number;
+    /** 响应体大小（字节，如果可获取） */
+    responseSize?: number;
+    /** 错误信息（如果失败） */
+    error?: string;
+    /** 追踪 ID */
+    traceId?: string;
+}
+/**
+ * 指标摘要
+ */
+interface MetricsSummary {
+    /** 总请求数 */
+    totalRequests: number;
+    /** 成功请求数 */
+    successCount: number;
+    /** 失败请求数 */
+    failureCount: number;
+    /** 成功率 */
+    successRate: number;
+    /** 平均耗时（毫秒） */
+    avgDurationMs: number;
+    /** P50 耗时（毫秒） */
+    p50Ms: number;
+    /** P90 耗时（毫秒） */
+    p90Ms: number;
+    /** P95 耗时（毫秒） */
+    p95Ms: number;
+    /** P99 耗时（毫秒） */
+    p99Ms: number;
+    /** 最小耗时（毫秒） */
+    minMs: number;
+    /** 最大耗时（毫秒） */
+    maxMs: number;
+    /** 按状态码分组的计数 */
+    statusCodeCounts: Record<number, number>;
+    /** 按路径分组的计数 */
+    pathCounts: Record<string, number>;
+    /** 统计时间范围 */
+    timeRange: {
+        start: number;
+        end: number;
+    };
+}
+/**
+ * 指标收集器选项
+ */
+interface MetricsCollectorOptions {
+    /** 最大保留的指标数量（避免内存泄漏） */
+    maxMetrics?: number;
+    /** 指标 TTL（毫秒，超过此时间的指标会被清理） */
+    ttlMs?: number;
+    /** 是否自动清理过期指标 */
+    autoCleanup?: boolean;
+    /** 清理间隔（毫秒） */
+    cleanupIntervalMs?: number;
+    /** 指标收集回调（每次请求完成时调用） */
+    onMetrics?: (metrics: RequestMetrics) => void;
+}
+/**
+ * 指标收集器
+ */
+interface MetricsCollector {
+    /** 收集指标 */
+    collect(metrics: RequestMetrics): void;
+    /** 获取所有指标 */
+    getMetrics(): RequestMetrics[];
+    /** 获取并清空所有指标 */
+    flush(): RequestMetrics[];
+    /** 获取指标摘要 */
+    summary(): MetricsSummary;
+    /** 按路径获取指标 */
+    getByPath(path: string): RequestMetrics[];
+    /** 按时间范围获取指标 */
+    getByTimeRange(startTime: number, endTime: number): RequestMetrics[];
+    /** 清除所有指标 */
+    clear(): void;
+    /** 销毁收集器（清理定时器等） */
+    destroy(): void;
+}
+/**
+ * 创建指标收集器
+ *
+ * @example
+ * ```typescript
+ * const metrics = createMetricsCollector({
+ *   maxMetrics: 1000,
+ *   onMetrics: (m) => console.log(`${m.method} ${m.path} - ${m.durationMs}ms`),
+ * });
+ *
+ * // 使用 middleware 收集指标
+ * const client = createClient({
+ *   middleware: [createMetricsMiddleware(metrics)],
+ * });
+ *
+ * // 获取摘要
+ * const summary = metrics.summary();
+ * console.log(`成功率: ${(summary.successRate * 100).toFixed(1)}%`);
+ * console.log(`P95: ${summary.p95Ms}ms`);
+ * ```
+ */
+declare function createMetricsCollector(options?: MetricsCollectorOptions): MetricsCollector;
+/**
+ * 创建指标收集 Middleware
+ *
+ * @example
+ * ```typescript
+ * const metrics = createMetricsCollector();
+ * const middleware = createMetricsMiddleware(metrics);
+ *
+ * const client = createClient({
+ *   middleware: [middleware],
+ * });
+ * ```
+ */
+declare function createMetricsMiddleware(collector: MetricsCollector): Middleware;
+
+/**
+ * @djvlc/openapi-client-core - 日志系统
+ */
+
+/**
+ * 创建控制台日志器
+ */
+declare function createConsoleLogger(options?: {
+    /** 日志前缀 */
+    prefix?: string;
+    /** 是否启用 */
+    enabled?: boolean;
+    /** 日志级别：'debug' | 'info' | 'warn' | 'error' */
+    level?: 'debug' | 'info' | 'warn' | 'error';
+    /** 是否包含时间戳 */
+    timestamp?: boolean;
+    /** 是否包含请求体 */
+    includeBody?: boolean;
+}): Logger;
+/**
+ * 创建静默日志器（不输出任何日志）
+ */
+declare function createSilentLogger(): Logger;
+/**
+ * 创建自定义日志器
+ *
+ * 将日志发送到自定义目标（如监控系统）
+ */
+declare function createCustomLogger(handlers: {
+    onRequest?: (data: {
+        url: string;
+        method: string;
+        headers?: Record<string, string>;
+        timestamp: number;
+    }) => void;
+    onResponse?: (data: {
+        url: string;
+        status: number;
+        durationMs: number;
+        timestamp: number;
+    }) => void;
+    onError?: (data: {
+        url: string;
+        error: unknown;
+        timestamp: number;
+    }) => void;
+    onRetry?: (data: {
+        url: string;
+        attempt: number;
+        error: unknown;
+        timestamp: number;
+    }) => void;
+}): Logger;
+/**
+ * 组合多个日志器
+ */
+declare function combineLoggers(...loggers: Logger[]): Logger;
+
+/**
+ * @djvlc/openapi-client-core - Configuration 类
+ *
+ * 兼容 openapi-generator 生成的代码，同时提供增强能力。
+ */
+
+/**
+ * API 配置类
+ *
+ * 兼容 openapi-generator 的 Configuration，同时提供增强能力。
+ */
+declare class Configuration {
+    /** 基础路径 */
+    basePath: string;
+    /** fetch 实现 */
+    fetchApi: typeof fetch;
+    /** Middleware 列表 */
+    middleware: Middleware[];
+    /** Cookie 策略 */
+    credentials?: RequestCredentials;
+    /** 拦截器管理器 */
+    interceptors: InterceptorManager;
+    /** SDK 信息 */
+    sdkInfo?: SdkInfo;
+    constructor(params?: ConfigurationParameters);
+    /**
+     * 从 ClientOptions 创建 Configuration
+     */
+    static fromClientOptions(opts: BaseClientOptions, sdkInfo?: SdkInfo): Configuration;
+}
+/**
+ * 创建兼容 openapi-generator 的 Configuration
+ *
+ * 这个函数用于快速创建一个简单的配置，兼容生成的 API 类。
+ */
+declare function createConfiguration(opts: BaseClientOptions, sdkInfo?: SdkInfo): Configuration;
+
+/**
+ * @djvlc/openapi-client-core - 客户端工厂
+ *
+ * 提供通用的客户端创建逻辑。
+ */
+
+/**
+ * API 类构造函数类型
+ */
+type ApiConstructor<T> = new (configuration: Configuration) => T;
+/**
+ * API 类映射
+ */
+type ApiMap = Record<string, ApiConstructor<unknown>>;
+/**
+ * 从 API 类映射提取实例类型
+ */
+type ApiInstances<T extends ApiMap> = {
+    [K in keyof T]: InstanceType<T[K]>;
+};
+/**
+ * 创建客户端的通用工厂函数
+ *
+ * @example
+ * ```typescript
+ * import * as apis from './gen/apis';
+ *
+ * const client = createClient(apis, {
+ *   baseUrl: 'https://api.example.com',
+ *   getAuthToken: () => token,
+ * }, { name: '@djvlc/openapi-user-client', version: '1.0.0' });
+ * ```
+ */
+declare function createClient<T extends ApiMap>(apiClasses: T, opts: BaseClientOptions, sdkInfo?: SdkInfo): {
+    config: Configuration;
+    apis: ApiInstances<T>;
+} & ApiInstances<T>;
+/**
+ * 过滤出 API 类（以 'Api' 结尾的构造函数）
+ */
+declare function filterApiClasses<T extends Record<string, unknown>>(exports: T): Record<string, ApiConstructor<unknown>>;
+
+export { AbortError, type ApiConstructor, type ApiInstances, type ApiMap, type BaseClientOptions, Configuration, type ConfigurationParameters, type DedupeOptions, DjvApiError, type ErrorInterceptor, InterceptorManager, type Interceptors, type Logger, type MetricsCollector, type MetricsCollectorOptions, type MetricsSummary, type Middleware, NetworkError, type RequestContext, type RequestDeduper, type RequestInterceptor, type RequestMetrics, type RequestOptions, type ResponseContext, type ResponseInterceptor, type RetryOptions, SDK_NAME, SDK_VERSION, type SdkInfo, TimeoutError, applyMiddlewareChain, applyPostMiddlewareChain, buildUserAgent, calculateBackoffDelay, cloneResponse, combineLoggers, createCacheInterceptor, createClient, createConfiguration, createConsoleLogger, createCustomLogger, createDedupeInterceptor, createDefaultMiddlewares, createEnhancedFetch, createFetchWithRetry, createFetchWithTimeout, createHeadersMiddleware, createLoggingMiddleware, createMetricsCollector, createMetricsMiddleware, createRequestDeduper, createSilentLogger, createTokenRefreshInterceptor, delay, executeRequest, filterApiClasses, getPlatform, getRetryDelay, getSdkInfo, isBrowser, isRetryableError, mergeHeaders, normalizeHeaders, safeParseJson, stripTrailingSlash };