fzkit 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 fengzai6
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,370 @@
+# fzkit / HTTP Client
+
+基于 `axios` 的 HTTP 客户端工厂。帮你统一处理：
+
+- access token 注入
+- 401 / 业务失效时的自动刷新
+- 并发刷新合并与冷却
+- 通用重试（网络错误 / 5xx）
+- in-flight GET 请求合并
+- 业务响应与错误钩子
+
+> 当前版本 `0.1.0`，API 仍可能调整，适合早期接入与验证。
+
+## 安装
+
+```bash
+# npm
+npm install fzkit axios
+
+# yarn
+yarn add fzkit axios
+
+# pnpm
+pnpm add fzkit axios
+```
+
+`axios` 是 peer dependency，需要由业务项目自行安装（`^1.7.0`）。
+
+## 快速开始
+
+```ts
+import axios from "axios";
+import { createHttpClient } from "fzkit";
+
+const http = createHttpClient({
+  axiosConfig: {
+    baseURL: "/api",
+    timeout: 15_000,
+  },
+  getAccessToken: () => localStorage.getItem("access_token"),
+  refreshAccessToken: async () => {
+    const refreshToken = localStorage.getItem("refresh_token");
+    if (!refreshToken) {
+      throw new Error("refreshToken missing");
+    }
+
+    const { data } = await axios.post("/auth/refresh", { refreshToken });
+    if (!data?.accessToken) {
+      throw new Error("refresh response missing accessToken");
+    }
+
+    localStorage.setItem("access_token", data.accessToken);
+    if (data.refreshToken) {
+      localStorage.setItem("refresh_token", data.refreshToken);
+    }
+
+    return data.accessToken;
+  },
+  onAuthFailure: async () => {
+    localStorage.removeItem("access_token");
+    localStorage.removeItem("refresh_token");
+    // 跳转登录页
+  },
+});
+
+const profile = await http.get("/account/profile");
+console.log(profile.data);
+```
+
+返回值是标准 `AxiosInstance`，可继续使用 `http.get/post/request` 等 axios API。
+
+## 设计原则
+
+1. **token 存储完全交给业务侧**  
+   库不内置 storage，只通过 `getAccessToken` / `refreshAccessToken` 读写。  
+   `refreshAccessToken` 返回新 token / `expiresAt` 时，业务必须写回 `getAccessToken` 使用的数据源。
+
+2. **尽量保留 axios 语义**  
+   成功返回 `AxiosResponse`；失败默认透传 `AxiosError`。
+
+3. **鉴权失败与瞬时失败分离**  
+   只有 refresh 鉴权失败、空 token、或登录过期才会走 `onAuthFailure`。  
+   网络错误 / 5xx 默认不登出。
+
+## Public API
+
+```ts
+import {
+  createHttpClient,
+  TokenRefreshManager,
+  type HttpClientOptions,
+  type AccessTokenResult,
+  type AccessTokenDetail,
+  type RetryPolicy,
+  type DedupePolicy,
+  type RequestDedupePolicy,
+  type BusinessResponseResult,
+  type ErrorContext,
+  type ErrorMessages,
+} from "fzkit/http-client";
+```
+
+| 导出 | 说明 |
+| --- | --- |
+| `createHttpClient(options)` | 创建带鉴权/刷新/重试/合并能力的 axios 实例 |
+| `TokenRefreshManager` | 可选，多客户端共享同一套刷新与冷却状态 |
+| 相关类型 | 配置与回调类型定义 |
+
+## 配置项
+
+### 最小可用
+
+| 字段 | 必填 | 说明 |
+| --- | --- | --- |
+| `axiosConfig` | 是 | 透传给 `axios.create` |
+| `getAccessToken` | 是 | 读取当前 access token |
+| `refreshAccessToken` | 否 | 自定义刷新逻辑；不传则 401 直接走 `onAuthFailure` |
+| `onAuthFailure` | 否 | 登录失效收尾（清 token、跳登录） |
+| `skipRefreshUrls` | 否 | 不触发 refresh 的路径（exact / prefix） |
+
+### Token 与 Headers
+
+| 字段 | 默认 | 说明 |
+| --- | --- | --- |
+| `accessTokenHeaderName` | `"Authorization"` | token 注入 header 名 |
+| `accessTokenPrefix` | `"Bearer"` | token 前缀 |
+| `headersProvider` | - | 每次请求动态注入 headers（可 async） |
+| `refreshBufferMs` | `0` | 提前刷新窗口；`getAccessToken` 返回 `AccessTokenDetail` 时生效 |
+
+说明：
+
+- `getAccessToken` 返回空值 / 空字符串 / `{ token: null|undefined }` 时，不注入鉴权 header
+- 调用方显式传入鉴权 header（含空字符串）时，工厂不覆盖
+- `headersProvider` 返回的 headers 会覆盖同名默认注入项
+- 鉴权刷新后的重试请求中，新 token 优先，不会被 `headersProvider` 的旧 Authorization 覆盖
+
+```ts
+const http = createHttpClient({
+  axiosConfig: { baseURL: "/api" },
+  getAccessToken: () => ({
+    token: localStorage.getItem("access_token") ?? "",
+    expiresAt: localStorage.getItem("expires_at"),
+  }),
+  refreshBufferMs: 60_000,
+  headersProvider: () => ({
+    "x-request-id": crypto.randomUUID(),
+  }),
+});
+```
+
+### 刷新控制
+
+| 字段 | 默认 | 说明 |
+| --- | --- | --- |
+| `refreshAccessToken` | - | 刷新逻辑，返回类型与 `getAccessToken` 一致 |
+| `shouldRefreshByResponse` | `() => false` | 通过业务响应判断是否需要刷新 |
+| `refreshCooldownMs` | `15000` | 刷新成功后的冷却期，冷却内 401 跳过刷新、直接用新 token 重试 |
+| `refreshManager` | 内部实例 | 多客户端共享刷新状态 |
+| `unauthorizedStatusCode` | `401` | 触发刷新流程的 HTTP 状态码 |
+| `refreshFailureCodes` | `[]` | 仅用于 refresh 失败判定的业务 code |
+| `isRefreshFailure` | 内置默认 | 判断 refresh 是否已到需要登出的程度 |
+
+默认 `isRefreshFailure`：
+
+- 非 `AxiosError` → 不视为鉴权失败
+- 无 `response`（网络错误）或 `status >= 500` → 不视为鉴权失败
+- `status === unauthorizedStatusCode` 或命中 `refreshFailureCodes` → 鉴权失败
+- `refreshAccessToken` 返回空 token → 按鉴权失败处理（不进冷却、不重试原请求）
+
+```ts
+import { createHttpClient, TokenRefreshManager } from "fzkit/http-client";
+
+const sharedManager = new TokenRefreshManager(15_000);
+
+const http1 = createHttpClient({
+  axiosConfig: { baseURL: "/api1" },
+  getAccessToken: () => tokenStore.accessToken,
+  refreshAccessToken: () => tokenStore.refresh(),
+  refreshManager: sharedManager,
+  onAuthFailure: () => tokenStore.logout(),
+});
+
+const http2 = createHttpClient({
+  axiosConfig: { baseURL: "/api2" },
+  getAccessToken: () => tokenStore.accessToken,
+  refreshAccessToken: () => tokenStore.refresh(),
+  refreshManager: sharedManager,
+  onAuthFailure: () => tokenStore.logout(),
+});
+```
+
+### 重试与请求合并
+
+```ts
+const http = createHttpClient({
+  axiosConfig: { baseURL: "/api" },
+  getAccessToken: async () => "",
+  retryPolicy: {
+    maxRetries: 2,
+    // shouldRetry / retryDelay 可自定义
+  },
+  dedupePolicy: {
+    enabled: true,
+    // generateKey 可自定义
+  },
+});
+```
+
+| 字段 | 默认 | 说明 |
+| --- | --- | --- |
+| `retryPolicy.maxRetries` | `0` | 最大重试次数（不含首次） |
+| `retryPolicy.shouldRetry` | 网络错误或 5xx（取消不重试） | 是否重试 |
+| `retryPolicy.retryDelay` | 指数退避，上限 30s | 重试延迟；非有限/负数按 0ms；回调抛错停止重试并走 `onError` |
+| `dedupePolicy.enabled` | `false` | 是否启用 in-flight GET 合并 |
+| `dedupePolicy.generateKey` | `method:baseURL:url:stableParams:headersProvider` | 合并 key |
+
+补充：
+
+- 鉴权失败（`unauthorizedStatusCode`）优先于通用 `retryPolicy`
+- dedupe 仅对 GET 生效
+- 请求级可用 `{ dedupePolicy: { enabled: false } }` 覆盖客户端级开关
+- 请求级只能覆盖 `enabled`，不能改 `generateKey`
+- dedupe 在 adapter 层生效，覆盖 `http(url)` / `http.get` / `http.request` 等入口
+- 内部 refresh / retry 在失败后 pending 已清理，可正常重放，不会自死锁
+
+#### dedupe 语义边界
+
+- **合并粒度**：仅 in-flight；请求结束后相同 key 会重新发起
+- **默认 key**：`method + baseURL + url + stableParams + headersProvider 快照`
+  - 只纳入 `headersProvider()` 返回值，不纳入调用方 `config.headers` / 工厂注入的 token
+  - 未配置 `headersProvider` 时该段为空
+- **取消**：
+  - 每个消费者的 `signal` / `cancelToken` 只取消自己
+  - 使用引用计数；全部消费者都离开后，才 abort 底层 shared 请求
+  - 已取消的请求不会创建 shared，避免孤儿请求
+- **超时**：
+  - 每个消费者按自己的 `timeout` 做本地超时
+  - shared 物理超时取当前参与者中的 `max(timeout)`
+  - 任一参与者 `timeout === 0`（显式关闭）时，shared 不强制超时
+  - 客户端默认 `timeout: 15_000`，未单独配置时会按该值参与 max 计算
+- **响应隔离**：
+  - 成功响应深拷贝 `data`
+  - 失败时 `error.response.data` 也会深拷贝隔离
+  - `onBusinessResponse` 返回完整响应替换时，也会深拷贝 `data`
+  - 共享 refresh 失败时，每个 waiter 拿到独立错误实例
+  - `headers/status/request` **不保证**引用共享（axios 管线可能重建）；仅保证 `data` 隔离
+- **params 序列化**：默认 key 稳定支持 plain object / array / `URLSearchParams` / `Date` / `Map` / `Set`；循环引用会抛出可控错误
+- **网络侧 config**：底层请求以首个创建 shared 的 leader config 为准（除 cancel/timeout 外）
+
+### 业务钩子
+
+| 字段 | 说明 |
+| --- | --- |
+| `onBusinessResponse` | 成功响应拦截：`void` 继续，`Error` / throw 失败，完整 `AxiosResponse` 替换响应 |
+| `onError` | 请求失败 / 刷新失败钩子，可替换错误；`return Error` 与 `throw` 都会进入该钩子 |
+| `errorMessages` | 覆盖内部英文默认文案（`refreshTokenExpired` / `loginExpired`） |
+
+```ts
+const http = createHttpClient({
+  axiosConfig: { baseURL: "/api" },
+  getAccessToken: () => localStorage.getItem("access_token"),
+  onBusinessResponse: (response) => {
+    const data = response.data as { code?: number; message?: string };
+    if (data.code !== 0) {
+      return new Error(data.message ?? "business error");
+    }
+  },
+  onError: (error, context) => {
+    console.error(`[${context.type}]`, error.message);
+  },
+  errorMessages: {
+    refreshTokenExpired: "登录已过期，请重新登录",
+    loginExpired: "登录已失效，请重新登录",
+  },
+});
+```
+
+## 默认请求流程
+
+1. `axios.create(axiosConfig)`
+2. 请求拦截：注入 token、合并 `headersProvider`
+3. 成功响应：
+   - `shouldRefreshByResponse` 判断是否刷新
+   - `onBusinessResponse` 处理业务响应
+   - 返回原始 `AxiosResponse`
+4. 失败响应：
+   - 命中 `unauthorizedStatusCode` 且启用刷新 → refresh 后重放
+   - 命中 `unauthorizedStatusCode` 且未启用刷新 → `onAuthFailure`
+   - 其他错误再走 `retryPolicy`
+5. refresh 失败：
+   - `isRefreshFailure === true` → `onAuthFailure`
+   - 否则透传原始错误，并触发 `onError({ type: "refresh" })`
+
+## FAQ
+
+### 1. 和直接用 axios 有什么区别？
+
+`createHttpClient` 仍然返回 axios 实例，只是预装了鉴权、刷新、重试、合并等拦截逻辑。你继续用 `get/post/request`，不必换请求写法。
+
+### 2. refresh 返回 400 会自动登出吗？
+
+默认不会。只有：
+
+- refresh 返回 `unauthorizedStatusCode`（默认 401）
+- 或命中 `refreshFailureCodes`
+- 或 `refreshAccessToken` 返回空 token
+- 或你自定义的 `isRefreshFailure` 返回 `true`
+
+才会走 `onAuthFailure`。
+
+如果你们后端用业务 code 表示 refresh token 失效，推荐：
+
+```ts
+refreshFailureCodes: [1001002],
+```
+
+### 3. 为什么网络错误 / 5xx 不登出？
+
+因为这通常不代表 refresh token 失效。默认策略是“瞬时失败可重试，鉴权失败才登出”。
+
+### 4. `skipRefreshUrls` 怎么匹配？
+
+只做 exact / prefix 路径匹配，不是子串 includes：
+
+- `/auth` 匹配 `/auth`、`/auth/login`
+- 不匹配 `/user/auth-history`、`/authorization`、`/api/auth/login`
+
+### 5. 多个 http 客户端如何共享一次刷新？
+
+创建共享的 `TokenRefreshManager`，通过 `refreshManager` 注入给多个 `createHttpClient` 实例。
+
+共享 manager 表示同一鉴权域：
+
+- 一次合并 refresh 事务的鉴权失败只会触发一次 `onAuthFailure`
+- 使用发起该次 refresh 的 client 回调
+- 建议所有共享 client 使用同一 token 数据源与等价 logout 行为
+- 外部 manager 的冷却由构造参数决定；client 的 `refreshCooldownMs` 不会回写已有 manager
+
+### 6. 请求级如何临时关闭 dedupe？
+
+```ts
+await http.get("/profile", {
+  dedupePolicy: { enabled: false },
+});
+```
+
+### 7. 不需要自动刷新怎么办？
+
+不传 `refreshAccessToken` 即可。此时遇到 `unauthorizedStatusCode` 会直接触发 `onAuthFailure`。
+
+### 8. 某些接口完全不想走鉴权/刷新？
+
+建议单独使用普通 `axios` 实例，而不是复用 `createHttpClient` 产物。
+
+### 9. 类型上为什么会看到 `dedupePolicy`？
+
+当前通过 `declare module "axios"` 扩展了请求配置，方便请求级覆盖。  
+该字段只对 `createHttpClient` 创建的实例有运行时效果。
+
+## 测试
+
+```bash
+yarn workspace fzkit test
+```
+
+测试分层与覆盖说明见 [`tests/README.md`](./tests/README.md)。
+
+## License
+
+MIT

package/dist/create-http-client-BoM9-_Ty.d.cts

@@ -0,0 +1,265 @@
+import { AxiosError, AxiosInstance, AxiosRequestConfig, AxiosResponse } from "axios";
+//#region src/http-client/types/token.d.ts
+/**
+ * token 详细信息，用于主动刷新判断。
+ */
+interface AccessTokenDetail {
+  token: string;
+  expiresAt: Date | string | number;
+}
+/**
+ * getAccessToken 的返回值类型，兼容旧版纯字符串返回。
+ */
+type AccessTokenResult = string | AccessTokenDetail | null;
+//#endregion
+//#region src/http-client/token-refresh-manager.d.ts
+/** @internal 冷却期内跳过刷新时的哨兵值，不对业务侧开放。 */
+declare const REFRESH_SKIPPED: unique symbol;
+declare class TokenRefreshManager {
+  private refreshingPromise;
+  private lastRefreshTime;
+  private readonly cooldownMs;
+  constructor(cooldownMs?: number);
+  /** @internal 供 createHttpClient 内部调用。 */
+  runRefresh(task: () => Promise<AccessTokenResult>): Promise<AccessTokenResult | typeof REFRESH_SKIPPED>;
+}
+//#endregion
+//#region src/http-client/types/common.d.ts
+/**
+ * onBusinessResponse 的返回值类型。
+ * - void：继续正常流程（表示成功）
+ * - Error：抛出错误（表示业务失败）
+ * - AxiosResponse：用完整响应形态（status/data/headers/config/statusText）替换原响应，不会二次触发 onBusinessResponse
+ */
+type BusinessResponseResult = void | Error | AxiosResponse;
+/**
+ * 错误上下文，传递给 onError 钩子。
+ */
+interface ErrorContext {
+  /**
+   * 错误来源类型。
+   */
+  type: 'request' | 'refresh';
+}
+/**
+ * 自定义错误消息。
+ */
+interface ErrorMessages {
+  refreshTokenExpired?: string;
+  loginExpired?: string;
+}
+//#endregion
+//#region src/http-client/types/http-client-options.d.ts
+/**
+ * 请求合并配置。
+ */
+interface DedupePolicy {
+  /** 是否启用请求合并。默认 false。仅合并 GET 请求。 */
+  enabled?: boolean;
+  /**
+   * 自定义合并 key 生成器。
+   * 默认：`method:baseURL:url:stableParams:headersProviderSnapshot`
+   *
+   * 默认实现仅纳入 `headersProvider()` 返回值快照（`config.__dedupeProviderHeaders`），
+   * 不纳入调用方 `config.headers` 或工厂注入的 token。
+   * params 稳定序列化支持 plain object / array / URLSearchParams / Date / Map / Set；
+   * 循环引用会抛错，避免误合并。
+   */
+  generateKey?: (config: AxiosRequestConfig) => string;
+}
+/**
+ * 请求级合并配置。
+ * 仅允许覆盖 enabled；generateKey 只能在客户端级配置。
+ */
+interface RequestDedupePolicy {
+  /** 是否启用请求合并。覆盖客户端级 enabled。 */
+  enabled?: boolean;
+}
+declare module 'axios' {
+  interface AxiosRequestConfig {
+    /**
+     * 请求级合并策略。
+     * 仅可覆盖 enabled，不能修改 generateKey。
+     * 仅 createHttpClient 创建的实例生效。
+     */
+    dedupePolicy?: RequestDedupePolicy;
+  }
+}
+/**
+ * 重试策略配置。
+ */
+interface RetryPolicy {
+  /** 最大重试次数（不含首次请求）。默认 0（不重试）。 */
+  maxRetries?: number;
+  /**
+   * 判断是否需要重试。
+   * 默认：网络错误（无 response）或 5xx 状态码时重试；用户取消不重试。
+   */
+  shouldRetry?: (error: unknown, retryCount: number) => boolean;
+  /**
+   * 计算重试延迟（毫秒）。
+   * 默认：指数退避，公式 `1000 * 2^retryCount`，上限 30 秒。
+   * 返回非有限数（NaN/Infinity）或负数时，按 0ms 处理。
+   * shouldRetry / retryDelay 抛错会停止重试，并进入 onError({ type: "request" })。
+   */
+  retryDelay?: (retryCount: number) => number;
+}
+/**
+ * 创建 HTTP 客户端时可传入的配置。
+ *
+ * @typeParam T - getAccessToken / refreshAccessToken 的统一返回类型，
+ *   默认为 `AccessTokenResult`。当 T 为 `AccessTokenDetail` 时启用主动刷新。
+ */
+interface HttpClientOptions<T extends AccessTokenResult = AccessTokenResult> {
+  /**
+   * 透传给 axios.create 的初始化配置。
+   */
+  axiosConfig: AxiosRequestConfig;
+  /**
+   * 获取当前 access token。
+   *
+   * 返回 `string` 时仅注入 token，不做主动刷新判断。
+   * 返回 `AccessTokenDetail` 时，会在 token 即将过期前主动触发刷新。
+   */
+  getAccessToken: () => T | Promise<T>;
+  /**
+   * access token 注入到请求头时使用的字段名。
+   * 默认 `Authorization`。
+   */
+  accessTokenHeaderName?: string;
+  /**
+   * access token 的前缀。
+   * 默认 `Bearer`。
+   */
+  accessTokenPrefix?: string;
+  /**
+   * 刷新失败判定的业务 code 列表。
+   *
+   * 仅用于 `defaultIsRefreshFailure`：当 refresh 请求响应体存在 `data.code`
+   * 且命中该列表时，视为刷新鉴权失败。
+   *
+   * 不会影响普通业务请求的鉴权识别；更通用的入口是 `isRefreshFailure`。
+   * 默认假设响应体形状为 `{ code?: number }`。
+   */
+  refreshFailureCodes?: number[];
+  /**
+   * 通用重试策略。
+   * 默认不重试（maxRetries: 0）。
+   */
+  retryPolicy?: RetryPolicy;
+  /**
+   * 请求合并策略。
+   * 默认关闭（enabled: false）。
+   */
+  dedupePolicy?: DedupePolicy;
+  /**
+   * 运行时动态 headers 提供者。
+   *
+   * 每次请求时调用，返回的 headers 会合并到请求中。
+   * 支持同步或异步返回。
+   *
+   * 典型场景：
+   * - 请求追踪：`{ 'x-trace-id': crypto.randomUUID() }`
+   * - 业务标识：从 store 读取 `{ 'x-tenant-id': tenantId }`
+   *
+   * 注意：
+   * - 首次请求时，返回的 headers 会覆盖默认注入的 headers（如 Authorization）
+   * - 鉴权刷新后的重试请求中，新 token 优先，不会被 headersProvider 的旧 Authorization 覆盖
+   */
+  headersProvider?: () => Record<string, string> | Promise<Record<string, string>>;
+  /**
+   * 触发刷新流程的 HTTP 状态码。
+   * 默认 `401`。
+   */
+  unauthorizedStatusCode?: number;
+  /**
+   * 自定义错误消息，覆盖内部默认值。
+   */
+  errorMessages?: ErrorMessages;
+  /**
+   * 判断刷新 token 请求本身是否已经失败到需要退出登录。
+   *
+   * 默认行为：
+   * - 非 AxiosError（编程错误 / 业务自定义 Error）不视为刷新鉴权失败
+   * - AxiosError 无 response（网络错误）或状态码 >= 500 时不视为刷新失败
+   * - 状态码 === unauthorizedStatusCode 时视为刷新失败
+   * - 响应 data.code 在 refreshFailureCodes 列表中时视为刷新鉴权失败
+   *
+   * 若业务需要“refresh 抛 Error 即登出”，请自定义该函数。
+   */
+  isRefreshFailure?: (error: unknown) => boolean;
+  /**
+   * 自定义刷新逻辑，返回类型必须与 getAccessToken 一致。
+   *
+   * 库不缓存 token。若返回 AccessTokenDetail，业务必须把新 token / expiresAt
+   * 写回 getAccessToken 使用的数据源，后续请求才会读到新过期时间。
+   */
+  refreshAccessToken?: () => T | Promise<T>;
+  /**
+   * 不触发 refresh token 流程的请求路径列表。
+   *
+   * 仅 exact / prefix 匹配，不是任意子串 includes，也不做中间段滑动匹配。
+   * 例如配置 `/auth` 会匹配 `/auth`、`/auth/login`，
+   * 但不会匹配 `/user/auth-history`、`/authorization`、`/api/auth/login`。
+   */
+  skipRefreshUrls?: string[];
+  /**
+   * 提前刷新的毫秒数，默认 0（不提前刷新）。
+   * 设置为大于 0 的值时，会在 token 即将过期前主动触发刷新。
+   */
+  refreshBufferMs?: number;
+  /**
+   * 刷新 token 后的冷却期（毫秒）。
+   * 在冷却期内收到的 401 请求会跳过刷新，直接使用新 token 重试。
+   * 用于处理刷新完成后，旧请求陆续返回 401 的并发场景。
+   * 默认 15000（15 秒）。
+   */
+  refreshCooldownMs?: number;
+  /**
+   * 外部传入的 TokenRefreshManager 实例。
+   * 用于多个客户端共享同一鉴权域的 refresh / 冷却状态。
+   * 不传则自动创建独立实例。
+   *
+   * 共享 manager 时：
+   * - 一次合并 refresh 事务的鉴权失败只会触发一次 onAuthFailure
+   * - 使用发起该次 refresh 的 client 回调
+   * - 建议共享 client 使用同一 token 数据源与等价 logout 行为
+   * - 外部 manager 的 cooldown 由构造参数决定；client 的 refreshCooldownMs 不会回写已有 manager
+   */
+  refreshManager?: TokenRefreshManager;
+  /**
+   * 通过业务响应判断是否需要刷新 token。
+   */
+  shouldRefreshByResponse?: (response: AxiosResponse<unknown>) => boolean;
+  /**
+   * 登录失效后的统一收尾回调。
+   */
+  onAuthFailure?: (error?: unknown) => void | Promise<void>;
+  /**
+   * 业务响应拦截器。
+   * - 返回 void：继续正常流程（表示成功）
+   * - 返回 Error：抛出错误（表示业务失败）
+   * - throw Error / 非 Error：与返回 Error 一样，统一进入 onError({ type: "request" })
+   * - 返回完整 AxiosResponse 形态：用新响应替换原响应，不会二次触发 onBusinessResponse
+   * - 可以是 async
+   */
+  onBusinessResponse?: (response: AxiosResponse<unknown>) => BusinessResponseResult | Promise<BusinessResponseResult>;
+  /**
+   * 全局错误钩子。
+   * - 返回 Error：用新错误替换原错误
+   * - 返回 void：继续抛出原错误
+   * - 可以是 async
+   *
+   * error 类型为 AxiosError | Error：
+   * - 请求失败时为 AxiosError，可通过 axios.isAxiosError(error) 收敛访问 response/config
+   * - 刷新失败时可能为 AxiosError 或业务侧抛出的任意 Error
+   * - 登录过期等内部构造的错误为普通 Error
+   */
+  onError?: (error: AxiosError | Error, context: ErrorContext) => AxiosError | Error | void | Promise<AxiosError | Error | void>;
+}
+//#endregion
+//#region src/http-client/create-http-client.d.ts
+declare const createHttpClient: <T extends AccessTokenResult = AccessTokenResult>(options: HttpClientOptions<T>) => AxiosInstance;
+//#endregion
+export { RetryPolicy as a, ErrorMessages as c, AccessTokenResult as d, RequestDedupePolicy as i, TokenRefreshManager as l, DedupePolicy as n, BusinessResponseResult as o, HttpClientOptions as r, ErrorContext as s, createHttpClient as t, AccessTokenDetail as u };
+//# sourceMappingURL=create-http-client-BoM9-_Ty.d.cts.map

package/dist/create-http-client-BoM9-_Ty.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-http-client-BoM9-_Ty.d.cts","names":[],"sources":["../src/http-client/types/token.ts","../src/http-client/token-refresh-manager.ts","../src/http-client/types/common.ts","../src/http-client/types/http-client-options.ts","../src/http-client/create-http-client.ts"],"mappings":";;;;;UAGiB;EACf;EACA,WAAW;;;;;KAMD,6BAA6B;;;;cCR5B;cAEA;UACH;UACA;mBACS;cAEL;;EAKN,WACJ,YAAY,QAAQ,qBACnB,QAAQ,2BAA2B;;;;;;;;;;KCe5B,gCAAgC,QAAQ;;;;UAKnC;;;;EAIf;;;;;UAMe;EACf;EACA;;;;;;;UCzCe;;EAEf;;;;;;;;;;EAWA,eAAe,QAAQ;;;;;;UAOR;;EAEf;;;YAMU;;;;;;IAMR,eAAe;;;;;;UAOF;;EAEf;;;;;EAMA,eAAe,gBAAgB;;;;;;;EAQ/B,cAAc;;;;;;;;UASC,kBAAkB,UAAU,oBAAoB;;;;EAI/D,aAAa;;;;;;;EAUb,sBAAsB,IAAI,QAAQ;;;;;EAMlC;;;;;EAMA;;;;;;;;;;EAaA;;;;;EAMA,cAAc;;;;;EAMd,eAAe;;;;;;;;;;;;;;;EAgBf,wBAAwB,yBAAyB,QAAQ;;;;;EAMzD;;;;EAKA,gBAAgB;;;;;;;;;;;;EAahB,oBAAoB;;;;;;;EAUpB,2BAA2B,IAAI,QAAQ;;;;;;;;EASvC;;;;;EAMA;;;;;;;EAQA;;;;;;;;;;;;EAaA,iBAAiB;;;;EAKjB,2BAA2B,UAAU;;;;EAOrC,iBAAiB,2BAA2B;;;;;;;;;EAU5C,sBACE,UAAU,2BACP,yBAAyB,QAAQ;;;;;;;;;;;;EAatC,WACE,OAAO,aAAa,OACpB,SAAS,iBACN,aAAa,eAAe,QAAQ,aAAa;;;;cC7O3C,mBAAoB,UAAU,oBAAoB,mBAC7D,SAAS,kBAAkB,OAC1B"}