@i.un/api-client 0.1.0

package/.vscode/settings.json

@@ -0,0 +1,8 @@
+{
+  "json.schemas": [
+    {
+      "url": "https://cdn.jsdelivr.net/npm/tsup/schema.json",
+      "fileMatch": ["package.json", "tsup.config.json"]
+    }
+  ]
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 zhyswan
+
+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,285 @@
+English | [简体中文](./README.zh-CN.md)
+
+# Api Client
+
+A lightweight HTTP client built on top of `ofetch`, with:
+
+- Automatic `Authorization` token injection
+- Optional token refresh with single-flight behavior
+- Unified success / error handling with configurable protocol
+- Full TypeScript support
+
+Works in browsers, Node, browser extensions, and more.
+
+---
+
+## Installation
+
+```bash
+npm install @i.un/api-client
+# or
+pnpm add @i.un/api-client
+# or
+yarn add @i.un/api-client
+```
+
+> Package name: `@i.un/api-client`.
+
+---
+
+## Quick Start
+
+```ts
+import { createApiClient, type TokenStorage } from "@i.un/api-client";
+
+// 1. Provide a TokenStorage (where to read/store the token)
+const tokenStorage: TokenStorage = {
+  async getAccessToken() {
+    return localStorage.getItem("access_token") || "";
+  },
+  async setAccessToken(token: string) {
+    localStorage.setItem("access_token", token);
+  },
+};
+
+// 2. Create client
+const client = createApiClient({
+  baseURL: "https://api.example.com",
+  tokenStorage,
+  // Token refresh endpoint (default ApiResult protocol: { code, data: { access_token }, message })
+  refreshToken: "/auth/refresh",
+});
+
+// 3. Use it
+const { get, post, put, patch, del, request } = client;
+
+// Example: GET
+const user = await get<{ name: string }>("/user/profile");
+
+// Example: POST
+const updated = await post<{ ok: boolean }>("/user/profile", { name: "foo" });
+```
+
+---
+
+## Default Response Protocol
+
+This library ships with a default response shape:
+
+```ts
+export interface ApiResult<T> {
+  code: number;
+  data: T;
+  message: string;
+}
+```
+
+Default behavior:
+
+- Your backend is expected to return `ApiResult<T>`.
+- When calling `request/get/post/...`:
+  - If `code === 0`:
+    - By default, returns `data` (i.e. `T`).
+    - If `returnFullResponse: true` is passed, returns the full `ApiResult<T>`.
+  - If `code !== 0`:
+    - Throws an `ApiError` (custom error type, see below).
+
+You can override this protocol via configuration (see "Advanced: custom unwrapping and error mapping").
+
+---
+
+## Error Type
+
+```ts
+export interface ApiError extends Error {
+  code: number;      // business error code
+  data?: unknown;    // backend data field
+  status?: number;   // HTTP status code (for network-level errors)
+}
+
+export const isApiError = (error: unknown): error is ApiError => {
+  return error instanceof Error && "code" in error;
+};
+```
+
+Usage example:
+
+```ts
+try {
+  const data = await get("/some/api");
+} catch (e) {
+  if (isApiError(e)) {
+    console.log("business error", e.code, e.message, e.data);
+  } else {
+    console.error("unexpected error", e);
+  }
+}
+```
+
+---
+
+## Options: `CreateApiClientOptions`
+
+```ts
+export interface CreateApiClientOptions {
+  baseURL: string;
+  tokenStorage: TokenStorage;
+
+  // Optional automatic token refresh
+  refreshToken?: (() => Promise<string>) | string | false;
+
+  // How to detect an auth error (defaults to code === 401)
+  isAuthError?: (code: number) => boolean;
+
+  // Custom success unwrapping logic
+  unwrapResponse?<T>(result: unknown, returnFullResponse: boolean): T;
+
+  // Custom error mapping from response to Error
+  createErrorFromResult?(res: unknown): Error;
+}
+```
+
+### `TokenStorage`
+
+```ts
+export interface TokenStorage {
+  getAccessToken: () => Promise<string> | string;
+  setAccessToken: (token: string) => Promise<void> | void;
+}
+```
+
+You decide where the token lives, e.g.:
+
+- Browser: `localStorage` / `sessionStorage` / cookies
+- Node: in-memory, Redis, database, etc.
+- Browser extension: `chrome.storage`, cookies, etc.
+
+---
+
+## Automatic Token Refresh
+
+### Option 1: String endpoint (recommended)
+
+```ts
+const client = createApiClient({
+  baseURL,
+  tokenStorage,
+  refreshToken: "/auth/refresh",
+});
+```
+
+Behavior:
+
+- When a business response satisfies `isAuthError(code) === true` (401 by default):
+  - Calls `ofetch<ApiResult<{ access_token: string }>>(refreshToken, { baseURL, method: "POST" })`.
+  - If `code !== 0`, uses `createErrorFromResult` to throw an error.
+  - If `code === 0`, takes `data.access_token` as the new token and calls `tokenStorage.setAccessToken`.
+  - Then automatically retries the original request once with the new token.
+- Single-flight:
+  - Uses an internal `refreshingPromise` to ensure only one refresh request is in-flight at a time.
+  - Concurrent 401s will wait for that promise and reuse the result.
+
+### Option 2: Custom function
+
+```ts
+const client = createApiClient({
+  baseURL,
+  tokenStorage,
+  refreshToken: async () => {
+    const res = await ofetch<{ accessToken: string }>("/auth/refresh", {
+      baseURL,
+      method: "POST",
+    });
+    return res.accessToken;
+  },
+});
+```
+
+> It is recommended **not** to call the same auto-refreshing `request` inside `refreshToken`, to avoid possible recursion if the refresh endpoint itself returns an auth error.
+
+---
+
+## Request Methods
+
+```ts
+const { rawRequest, request, get, post, put, patch, del } = createApiClient(...);
+```
+
+- `rawRequest`: The underlying `$fetch` instance (from `ofetch.create`), returns raw results, no auto refresh or unwrapping.
+- `request<T>(url, options?)`: Core method with token injection, refresh, unwrapping, and error throwing.
+- `get<T>(url, params?, options?)`: `GET` with `params` mapped to `query`.
+- `post/put/patch<T>(url, body?, options?)`: `body` defaults to `{}`.
+- `del<T>(url, params?, options?)`: `DELETE` with `params` mapped to `query`.
+
+Examples:
+
+```ts
+// GET /users?id=1
+const user = await get<User>("/users", { id: 1 });
+
+// POST /users { name }
+const created = await post<User>("/users", { name: "foo" });
+
+// Direct request (more flexible)
+const data = await request<User>("/users/1", {
+  method: "GET",
+  returnFullResponse: false, // true returns ApiResult<User>
+});
+```
+
+---
+
+## Advanced: Custom unwrapping and error mapping
+
+If your backend does not follow the `{ code, data, message }` protocol, you can override it:
+
+```ts
+const client = createApiClient({
+  baseURL,
+  tokenStorage,
+  refreshToken: false,
+
+  unwrapResponse<T>(result, returnFullResponse) {
+    // Example: backend returns { success, result, errorMsg }
+    if (result && typeof result === "object" && "success" in result) {
+      const body = result as any;
+      if (body.success) {
+        return returnFullResponse ? (body as T) : (body.result as T);
+      }
+    }
+    return result as T;
+  },
+
+  createErrorFromResult(res): Error {
+    const body = res as any;
+    const err = new Error(body.errorMsg || "Request failed");
+    // You can attach custom fields here, e.g. (err as any).code = body.code;
+    return err;
+  },
+});
+```
+
+Internally, the library:
+
+- Calls `unwrapResponse` for success cases.
+- Calls `createErrorFromResult` for business failures.
+- Manages token injection, refresh, retry, etc.
+
+The protocol details are entirely up to you.
+
+---
+
+## Environment & Notes
+
+- Built on `ofetch`, works in browsers, Node 18+, Nuxt, etc.
+- Requires `fetch` / `Headers`:
+  - Browsers: built-in.
+  - Node 18+: built-in `fetch`.
+  - Older Node: you need to polyfill e.g. with `undici` or `cross-fetch`.
+- The core client does **not** depend on `window` / `localStorage` / `chrome`, etc. Environment-specific logic should live in your `TokenStorage` (and higher-level wrappers if needed).
+
+---
+
+## License
+
+MIT

package/README.zh-CN.md

@@ -0,0 +1,275 @@
+# Api Client
+
+一个基于 `ofetch` 的轻量级 HTTP 客户端，内置：
+
+- 自动携带 `Authorization` token
+- 自动刷新 token（可选，串行防抖）
+- 统一成功/失败返回结构（可配置协议）
+- 完整 TypeScript 类型支持
+
+适用于浏览器、Node、浏览器扩展等多种环境。
+
+---
+
+## 安装
+
+```bash
+npm install @i.un/api-client
+# or
+pnpm add @i.un/api-client
+# or
+yarn add @i.un/api-client
+```
+
+> 包名：`@i.un/api-client`。
+
+---
+
+## 快速上手
+
+```ts
+import { createApiClient, type TokenStorage } from "@i.un/api-client";
+
+// 1. 提供一个 TokenStorage（决定 token 从哪里来、存到哪里去）
+const tokenStorage: TokenStorage = {
+  async getAccessToken() {
+    return localStorage.getItem("access_token") || "";
+  },
+  async setAccessToken(token: string) {
+    localStorage.setItem("access_token", token);
+  },
+};
+
+// 2. 创建 client
+const client = createApiClient({
+  baseURL: "https://api.example.com",
+  tokenStorage,
+  // 刷新 token 的接口（默认 ApiResult 协议：{ code, data: { access_token }, message }）
+  refreshToken: "/auth/refresh",
+});
+
+// 3. 使用
+const { get, post, put, patch, del, request } = client;
+
+// 示例：GET
+const user = await get<{ name: string }>("/user/profile");
+
+// 示例：POST
+const updated = await post<{ ok: boolean }>("/user/profile", { name: "foo" });
+```
+
+---
+
+## 默认响应协议
+
+库内置了一个默认响应协议类型：
+
+```ts
+export interface ApiResult<T> {
+  code: number;
+  data: T;
+  message: string;
+}
+```
+
+默认行为：
+
+- 约定后端统一返回 `ApiResult<T>`。
+- 调用 `request/get/post/...`：
+  - 当 `code === 0`：
+    - 默认返回 `data`（即 `T`）。
+    - 如果传了 `returnFullResponse: true`，则返回完整的 `ApiResult<T>`。
+  - 当 `code !== 0`：
+    - 抛出 `ApiError`（自定义错误类型，见下文）。
+
+你可以通过配置项覆盖这套协议（见「高级：自定义解包和错误映射」）。
+
+---
+
+## 错误类型
+
+```ts
+export interface ApiError extends Error {
+  code: number;      // 业务错误码
+  data?: unknown;    // 后端 data 字段
+  status?: number;   // HTTP 状态码（仅网络层错误时可能存在）
+}
+
+export const isApiError = (error: unknown): error is ApiError => {
+  return error instanceof Error && "code" in error;
+};
+```
+
+调用方使用示例：
+
+```ts
+try {
+  const data = await get("/some/api");
+} catch (e) {
+  if (isApiError(e)) {
+    console.log("business error", e.code, e.message, e.data);
+  } else {
+    console.error("unexpected error", e);
+  }
+}
+```
+
+---
+
+## 配置项：`CreateApiClientOptions`
+
+```ts
+export interface CreateApiClientOptions {
+  baseURL: string;
+  tokenStorage: TokenStorage;
+
+  // 自动刷新 token（可选）
+  refreshToken?: (() => Promise<string>) | string | false;
+
+  // 识别“需要刷新 / 认证失败”的业务错误（可选，默认 code === 401）
+  isAuthError?: (code: number) => boolean;
+
+  // 自定义成功响应解包逻辑（可选）
+  unwrapResponse?<T>(result: unknown, returnFullResponse: boolean): T;
+
+  // 自定义失败响应映射为 Error 的逻辑（可选）
+  createErrorFromResult?(res: unknown): Error;
+}
+```
+
+### `TokenStorage`
+
+```ts
+export interface TokenStorage {
+  getAccessToken: () => Promise<string> | string;
+  setAccessToken: (token: string) => Promise<void> | void;
+}
+```
+
+你可以自由决定 token 存到哪里，比如：
+
+- 浏览器：`localStorage` / `sessionStorage` / `cookie`
+- Node：内存变量、Redis、数据库等
+- 浏览器扩展：`chrome.storage`、`cookies` 等
+
+---
+
+## 自动刷新 Token
+
+### 方式一：字符串 endpoint（推荐）
+
+```ts
+const client = createApiClient({
+  baseURL,
+  tokenStorage,
+  refreshToken: "/auth/refresh",
+});
+```
+
+内部行为：
+
+- 业务请求返回 `isAuthError(code) === true`（默认 401）时：
+  - 调用 `ofetch<ApiResult<{ access_token: string }>>(refreshToken, { baseURL, method: "POST" })`。
+  - 如果 `code !== 0`，使用 `createErrorFromResult` 抛错。
+  - 如果 `code === 0`，从 `data.access_token` 取出新 token，并调用 `tokenStorage.setAccessToken` 存储。
+  - 然后自动使用新 token 重试原请求一次。
+- 串行防抖：
+  - 使用内部的 `refreshingPromise` 确保同一时刻只有一个刷新请求在进行；
+  - 其它并发 401 请求会等待这次刷新完成，复用刷新结果。
+
+### 方式二：自定义函数
+
+```ts
+const client = createApiClient({
+  baseURL,
+  tokenStorage,
+  refreshToken: async () => {
+    const res = await ofetch<{ accessToken: string }>("/auth/refresh", {
+      baseURL,
+      method: "POST",
+    });
+    return res.accessToken;
+  },
+});
+```
+
+> 建议在 `refreshToken` 内部不要再调用同一个带自动刷新的 `request`，以避免在刷新接口也返回认证错误时形成递归。
+
+---
+
+## 请求方法
+
+```ts
+const { rawRequest, request, get, post, put, patch, del } = createApiClient(...);
+```
+
+- `rawRequest`: 底层的 `$fetch` 实例（来自 `ofetch.create`），按原样返回结果，不做自动刷新和解包。
+- `request<T>(url, options?)`: 核心方法，自动携带 token / 自动刷新 / 解包 / 抛 `Error`。
+- `get<T>(url, params?, options?)`: `GET` 请求，`params` 会被放到 `query`。
+- `post/put/patch<T>(url, body?, options?)`: `body` 默认 `{}`。
+- `del<T>(url, params?, options?)`: `DELETE` 请求，`params` 放到 `query`。
+
+示例：
+
+```ts
+// GET /users?id=1
+const user = await get<User>("/users", { id: 1 });
+
+// POST /users { name }
+const created = await post<User>("/users", { name: "foo" });
+
+// 直接用 request（更通用）
+const data = await request<User>("/users/1", {
+  method: "GET",
+  returnFullResponse: false, // true 时返回 ApiResult<User>
+});
+```
+
+---
+
+## 高级：自定义解包和错误映射
+
+如果你的后端协议不是 `{ code, data, message }`，可以通过配置覆盖：
+
+```ts
+const client = createApiClient({
+  baseURL,
+  tokenStorage,
+  refreshToken: false,
+
+  unwrapResponse<T>(result, returnFullResponse) {
+    // 举例：后端协议是 { success, result, errorMsg }
+    if (result && typeof result === "object" && "success" in result) {
+      const body = result as any;
+      if (body.success) {
+        return returnFullResponse ? (body as T) : (body.result as T);
+      }
+    }
+    return result as T;
+  },
+
+  createErrorFromResult(res): Error {
+    const body = res as any;
+    const err = new Error(body.errorMsg || "Request failed");
+    // 可以按需挂一些自定义字段，比如 err.code / err.raw
+    return err;
+  },
+});
+```
+
+---
+
+## 环境支持与注意事项
+
+- 依赖 `ofetch`，可在浏览器、Node 18+、Nuxt 等环境使用。
+- 需要环境有 `fetch` / `Headers`：
+  - 浏览器：原生支持。
+  - Node 18+：内置 `fetch`。
+  - 更低版本 Node：需要自行 polyfill（例如 `undici` 或 `cross-fetch`）。
+- `client.ts` 本身不依赖 `window`／`localStorage`／`chrome` 等对象，这些应在你实现 `TokenStorage` 时根据环境自行选择。
+
+---
+
+## License
+
+MIT

package/dist/client.d.mts

@@ -0,0 +1,41 @@
+import { $Fetch, FetchOptions } from 'ofetch';
+
+interface ApiResult<T> {
+    code: number;
+    data: T;
+    message: string;
+}
+interface ApiError extends Error {
+    code: number;
+    data?: unknown;
+    status?: number;
+}
+declare const isApiError: (error: unknown) => error is ApiError;
+interface TokenStorage {
+    getAccessToken: () => Promise<string> | string;
+    setAccessToken: (token: string) => Promise<void> | void;
+}
+interface CreateApiClientOptions {
+    baseURL: string;
+    tokenStorage: TokenStorage;
+    refreshToken?: (() => Promise<string>) | string | false;
+    isAuthError?: (code: number) => boolean;
+    unwrapResponse?<T>(result: unknown, returnFullResponse: boolean): T;
+    createErrorFromResult?(res: unknown): Error;
+}
+type RequestOptions = FetchOptions<"json"> & {
+    returnFullResponse?: boolean;
+};
+declare function createApiClient(options: CreateApiClientOptions): {
+    rawRequest: $Fetch;
+    request: <T = unknown>(url: string, options?: RequestOptions & {
+        _retry?: boolean;
+    }) => Promise<T>;
+    get: <T = unknown>(url: string, params?: FetchOptions["query"], options?: RequestOptions) => Promise<T>;
+    post: <T = unknown>(url: string, body?: FetchOptions["body"], options?: RequestOptions) => Promise<T>;
+    put: <T = unknown>(url: string, body?: FetchOptions["body"], options?: RequestOptions) => Promise<T>;
+    patch: <T = unknown>(url: string, body?: FetchOptions["body"], options?: RequestOptions) => Promise<T>;
+    del: <T = unknown>(url: string, params?: FetchOptions["query"], options?: RequestOptions) => Promise<T>;
+};
+
+export { type ApiError, type ApiResult, type CreateApiClientOptions, type TokenStorage, createApiClient, isApiError };

package/dist/client.d.ts

@@ -0,0 +1,41 @@
+import { $Fetch, FetchOptions } from 'ofetch';
+
+interface ApiResult<T> {
+    code: number;
+    data: T;
+    message: string;
+}
+interface ApiError extends Error {
+    code: number;
+    data?: unknown;
+    status?: number;
+}
+declare const isApiError: (error: unknown) => error is ApiError;
+interface TokenStorage {
+    getAccessToken: () => Promise<string> | string;
+    setAccessToken: (token: string) => Promise<void> | void;
+}
+interface CreateApiClientOptions {
+    baseURL: string;
+    tokenStorage: TokenStorage;
+    refreshToken?: (() => Promise<string>) | string | false;
+    isAuthError?: (code: number) => boolean;
+    unwrapResponse?<T>(result: unknown, returnFullResponse: boolean): T;
+    createErrorFromResult?(res: unknown): Error;
+}
+type RequestOptions = FetchOptions<"json"> & {
+    returnFullResponse?: boolean;
+};
+declare function createApiClient(options: CreateApiClientOptions): {
+    rawRequest: $Fetch;
+    request: <T = unknown>(url: string, options?: RequestOptions & {
+        _retry?: boolean;
+    }) => Promise<T>;
+    get: <T = unknown>(url: string, params?: FetchOptions["query"], options?: RequestOptions) => Promise<T>;
+    post: <T = unknown>(url: string, body?: FetchOptions["body"], options?: RequestOptions) => Promise<T>;
+    put: <T = unknown>(url: string, body?: FetchOptions["body"], options?: RequestOptions) => Promise<T>;
+    patch: <T = unknown>(url: string, body?: FetchOptions["body"], options?: RequestOptions) => Promise<T>;
+    del: <T = unknown>(url: string, params?: FetchOptions["query"], options?: RequestOptions) => Promise<T>;
+};
+
+export { type ApiError, type ApiResult, type CreateApiClientOptions, type TokenStorage, createApiClient, isApiError };