@i.un/api-client 1.1.1 → 1.1.3

package/README.md

@@ -90,9 +90,9 @@ You can override this protocol via configuration (see "Advanced: custom unwrappi
 
 ```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)
+  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 => {
@@ -267,8 +267,177 @@ The protocol details are entirely up to you.
 
 ---
 
+## Request Chain Execution
+
+The Request Chain engine (`executeRequestChain`) allows you to coordinate multiple dependent HTTP requests. It manages a shared **Context**, handles **Variable Substitution**, and supports **Smart Routing** via a strategy pattern.
+
+### Core Concepts
+
+- **Rule (`ChainRequestRule`)**: Defines a single step in the chain.
+- **Context**: A shared object that accumulates results. Every step can read from and write to the context.
+- **Handler (`NetworkHandler`)**: Decides which **Adapter** should execute a particular request based on the URL or Method.
+
+### Rule Configuration (`ChainRequestRule`)
+
+| Property         | Type              | Description                                                                                 |
+| :--------------- | :---------------- | :------------------------------------------------------------------------------------------ |
+| `key`            | `string`          | The key to store the result in the Context.                                                 |
+| `request`        | `HttpRequestSpec` | Method, URL, Headers, and initial Body.                                                     |
+| `selector`       | `string`          | Optional. A dot-notation path (e.g., `user.id`) to extract specific data from the response. |
+| `includeContext` | `boolean`         | If true, the entire Context is merged into the request `body`.                              |
+| `pickContext`    | `string[]`        | Specific keys from the Context to merge into the request `body`.                            |
+| `payload`        | `object`          | Static data to merge into the request `body`.                                               |
+| `optional`       | `boolean`         | If true, the chain continues even if this request fails.                                    |
+
+### Variable Substitution
+
+You can use `{{key.path}}` in `url`, `headers`, and `body`. The engine will replace these placeholders with values from the current Context.
+
+### Detailed Example: 3-Step Orchestration
+
+```ts
+import { executeRequestChain } from "@i.un/api-client";
+
+const rules = [
+  // Step 1: Get session
+  {
+    key: "auth",
+    request: { method: "POST", url: "/login", body: { user: "admin" } },
+  },
+  // Step 2: Use session token in URL and Headers
+  {
+    key: "profile",
+    request: {
+      method: "GET",
+      url: "/users/{{auth.userId}}",
+      headers: { "X-Session": "{{auth.token}}" },
+    },
+    selector: "data", // context.profile will only contain the 'data' field
+  },
+  // Step 3: Combine previous data into a new request
+  {
+    key: "update",
+    request: { method: "PUT", url: "/sync" },
+    pickContext: ["profile"], // body will be { profile: context.profile, ...payload }
+    payload: { source: "web-client" },
+  },
+];
+
+const result = await executeRequestChain(rules);
+```
+
+### Custom Routing (Strategy Pattern)
+
+You can provide a list of `NetworkHandler`s to route requests to different environments (e.g., redirecting `/ext/*` to a browser extension API while `/api/*` goes to standard fetch).
+
+```ts
+const handlers = [
+  {
+    name: "extension-router",
+    shouldHandle: (url) => url.startsWith("chrome-extension://"),
+    adapter: {
+      post: (url, body) => chrome.runtime.sendMessage({ url, body }),
+      get: (url) => ...
+    }
+  }
+];
+
+await executeRequestChain(rules, handlers);
+```
+
+---
+
+## Protobuf & Security
+
+The Protobuf module provides a security layer over `ofetch`. It supports binary serialization, XOR obfuscation, and automatic integration via hooks.
+
+### The Pipeline
+
+1. **Object** -> **Transform** (Optional) -> **Protobuf Encode** -> **XOR Obfuscation** -> **Binary Payload**
+
+### Integration Hooks
+
+Use `createProtobufHooks` to add Protobuf support to your `api-client` instance.
+
+```ts
+import { createApiClient, createProtobufHooks } from "@i.un/api-client";
+
+const hooks = createProtobufHooks({
+  // 1. XOR Encryption key (optional but recommended)
+  obfuscationKey: () => fetchSecretKeyFromServer(),
+
+  // 2. Custom transformations
+  transform: {
+    beforeEncode: (data) => ({ ...data, ts: Date.now() }),
+    afterDecode: (res) => res.data,
+  },
+});
+
+const client = createApiClient({
+  baseURL: "/api",
+  ...hooks,
+});
+
+// usage: just set Content-Type or Accept to 'application/x-protobuf'
+const data = await client.post(
+  "/secure-endpoint",
+  { foo: "bar" },
+  {
+    headers: { "Content-Type": "application/x-protobuf" },
+  },
+);
+```
+
+### Manual Header Configuration
+
+If you are not using the automatic hooks or need to manually configure headers for a specific request, you can use the `setProtobufRequestHeaders` helper:
+
+```ts
+import { setProtobufRequestHeaders } from "@i.un/api-client";
+
+// 1. Send and receive Protobuf (default)
+const headers = setProtobufRequestHeaders({ "X-Custom": "val" });
+// { "X-Custom": "val", "Content-Type": "application/x-protobuf", "Accept": "application/x-protobuf" }
+
+// 2. Only receive Protobuf
+const receiveOnly = setProtobufRequestHeaders({}, "receive");
+// { "Accept": "application/x-protobuf" }
+
+// Use with client
+await client.get("/data", { headers: receiveOnly });
+```
+
+### Envelope Mode vs Custom Type Mode
+
+- **Envelope Mode (Default)**: If no `protoType` is provided, the library uses a built-in `SecurePayload` (Timestamp + JSON-stringified data). This is the easiest way to hide data from DevTools without defining schemas for every API.
+- **Custom Type Mode**: Provide a `protoType` (compiled from `.proto`) for full binary performance and type safety.
+
+```ts
+const hooks = createProtobufHooks({
+  protoType: MyCompiledMessage, // From protobufjs
+});
+```
+
+### Server-Side Usage (Node/Workers)
+
+The library provides utilities for the server/worker side to handle these secure requests.
+
+```ts
+import { parseSecureRequest, secureResponse } from "@i.un/api-client";
+
+// 1. Parse incoming request
+const body = await parseSecureRequest(request, { obfuscationKey: "key" });
+
+// 2. Send secure response
+return await secureResponse({ success: true }, { obfuscationKey: "key" });
+```
+
+---
+
 ## Environment & Notes
 
+---
+
 - Built on `ofetch`, works in browsers, Node 18+, Nuxt, etc.
 - Requires `fetch` / `Headers`:
   - Browsers: built-in.

package/README.zh-CN.md

@@ -90,9 +90,9 @@ export interface ApiResult<T> {
 
 ```ts
 export interface ApiError extends Error {
-  code: number;      // 业务错误码
-  data?: unknown;    // 后端 data 字段
-  status?: number;   // HTTP 状态码（仅网络层错误时可能存在）
+  code: number; // 业务错误码
+  data?: unknown; // 后端 data 字段
+  status?: number; // HTTP 状态码（仅网络层错误时可能存在）
 }
 
 export const isApiError = (error: unknown): error is ApiError => {
@@ -259,8 +259,177 @@ const client = createApiClient({
 
 ---
 
+## 请求链执行 (Request Chain)
+
+请求链引擎 (`executeRequestChain`) 允许你编排多个相互依赖的 HTTP 请求。它管理一个共享的 **上下文 (Context)**，处理 **变量替换 (Variable Substitution)**，并支持通过策略模式实现的 **智能路由 (Smart Routing)**。
+
+### 核心概念
+
+- **规则 (`ChainRequestRule`)**: 定义链中的单个步骤。
+- **上下文 (Context)**: 一个共享对象，用于累积结果。每个步骤都可以从上下文中读取数据或向其中写入结果。
+- **处理器 (`NetworkHandler`)**: 根据 URL 或方法决定哪个 **适配器 (Adapter)** 应该执行特定的请求。
+
+### 规则配置 (`ChainRequestRule`)
+
+| 属性             | 类型              | 描述                                                         |
+| :--------------- | :---------------- | :----------------------------------------------------------- |
+| `key`            | `string`          | 结果在上下文中的存储键名。                                   |
+| `request`        | `HttpRequestSpec` | 包含方法、URL、Header 和初始 Body。                          |
+| `selector`       | `string`          | 可选。使用点分隔的路径（如 `user.id`）从响应中提取特定数据。 |
+| `includeContext` | `boolean`         | 如果为 true，则将整个上下文合并到请求的 `body` 中。          |
+| `pickContext`    | `string[]`        | 指定要合并到请求 `body` 中的上下文键列表。                   |
+| `payload`        | `object`          | 要合并到请求 `body` 中的静态数据。                           |
+| `optional`       | `boolean`         | 如果为 true，即使该请求失败，链式执行也会继续。              |
+
+### 变量替换
+
+你可以在 `url`、`headers` 和 `body` 中使用 `{{key.path}}`。引擎会自动将这些占位符替换为当前上下文中的值。
+
+### 详细示例：三步请求编排
+
+```ts
+import { executeRequestChain } from "@i.un/api-client";
+
+const rules = [
+  // 步骤 1: 获取登录会话
+  {
+    key: "auth",
+    request: { method: "POST", url: "/login", body: { user: "admin" } },
+  },
+  // 步骤 2: 在 URL 和 Header 中使用会话 Token
+  {
+    key: "profile",
+    request: {
+      method: "GET",
+      url: "/users/{{auth.userId}}",
+      headers: { "X-Session": "{{auth.token}}" },
+    },
+    selector: "data", // context.profile 将仅包含响应中的 'data' 字段
+  },
+  // 步骤 3: 结合之前的步骤数据发起新请求
+  {
+    key: "update",
+    request: { method: "PUT", url: "/sync" },
+    pickContext: ["profile"], // body 将会是 { profile: context.profile, ...payload }
+    payload: { source: "web-client" },
+  },
+];
+
+const result = await executeRequestChain(rules);
+```
+
+### 自定义路由 (策略模式)
+
+你可以提供 `NetworkHandler` 列表，将请求路由到不同的环境（例如：将 `/ext/*` 重定向到浏览器扩展 API，而 `/api/*` 走标准 fetch）。
+
+```ts
+const handlers = [
+  {
+    name: "extension-router",
+    shouldHandle: (url) => url.startsWith("chrome-extension://"),
+    adapter: {
+      post: (url, body) => chrome.runtime.sendMessage({ url, body }),
+      get: (url) => ...
+    }
+  }
+];
+
+await executeRequestChain(rules, handlers);
+```
+
+---
+
+## Protobuf 与安全通信
+
+Protobuf 模块为 `ofetch` 提供了一层安全保障。它支持二进制序列化、XOR 混淆以及通过 Hook 实现的自动集成。
+
+### 处理流程
+
+1. **对象** -> **转换 (Transform, 可选)** -> **Protobuf 编码** -> **XOR 混淆** -> **二进制负载 (Binary Payload)**
+
+### 集成 Hook
+
+由于使用了 `createProtobufHooks`，你可以轻松地为 `api-client` 实例添加 Protobuf 支持。
+
+```ts
+import { createApiClient, createProtobufHooks } from "@i.un/api-client";
+
+const hooks = createProtobufHooks({
+  // 1. XOR 加密密钥 (可选，但推荐)
+  obfuscationKey: () => fetchSecretKeyFromServer(),
+
+  // 2. 自定义数据转换
+  transform: {
+    beforeEncode: (data) => ({ ...data, ts: Date.now() }),
+    afterDecode: (res) => res.data,
+  },
+});
+
+const client = createApiClient({
+  baseURL: "/api",
+  ...hooks,
+});
+
+// 使用方法：只需将 Content-Type 或 Accept 设置为 'application/x-protobuf'
+const data = await client.post(
+  "/secure-endpoint",
+  { foo: "bar" },
+  {
+    headers: { "Content-Type": "application/x-protobuf" },
+  },
+);
+```
+
+### 手动配置请求头
+
+如果你没有使用自动 Hook，或者需要为特定请求手动配置 Header，可以使用 `setProtobufRequestHeaders` 辅助函数：
+
+```ts
+import { setProtobufRequestHeaders } from "@i.un/api-client";
+
+// 1. 同时发送和接收 Protobuf (默认)
+const headers = setProtobufRequestHeaders({ "X-Custom": "val" });
+// { "X-Custom": "val", "Content-Type": "application/x-protobuf", "Accept": "application/x-protobuf" }
+
+// 2. 仅接收 Protobuf
+const receiveOnly = setProtobufRequestHeaders({}, "receive");
+// { "Accept": "application/x-protobuf" }
+
+// 在 client 中使用
+await client.get("/data", { headers: receiveOnly });
+```
+
+### 信封模式 vs 自定义类型模式
+
+- **信封模式 (默认)**：如果不提供 `protoType`，库将使用内置的 `SecurePayload`（包含时间戳和经过 JSON 序列化的数据）。这是在不为每个接口定义 Schema 的情况下，向开发者工具隐藏数据的最简单方法。
+- **自定义类型模式**：提供一个 `protoType`（从 `.proto` 文件编译出的对象），以获得极致的二进制性能和类型安全。
+
+```ts
+const hooks = createProtobufHooks({
+  protoType: MyCompiledMessage, // 来自 protobufjs
+});
+```
+
+### 服务端/边缘计算使用 (Node/Workers)
+
+本库提供了服务端工具，用于处理这些安全请求。
+
+```ts
+import { parseSecureRequest, secureResponse } from "@i.un/api-client";
+
+// 1. 解析进入的加密请求
+const body = await parseSecureRequest(request, { obfuscationKey: "key" });
+
+// 2. 发送加密响应
+return await secureResponse({ success: true }, { obfuscationKey: "key" });
+```
+
+---
+
 ## 环境支持与注意事项
 
+---
+
 - 依赖 `ofetch`，可在浏览器、Node 18+、Nuxt 等环境使用。
 - 需要环境有 `fetch` / `Headers`：
   - 浏览器：原生支持。

package/dist/chain.d.mts

@@ -0,0 +1,85 @@
+/**
+ * Request Chain Runner
+ * 负责解析和执行通用的 HTTP 请求链 (Chain Execution)
+ * 适用于任何需要链式 HTTP 请求编排的场景
+ */
+/** Supported HTTP Methods */
+type HttpMethod = "GET" | "POST" | "PUT" | "DELETE" | "PATCH";
+/** HTTP 请求参数 */
+interface HttpRequestSpec {
+    method: HttpMethod;
+    url: string;
+    headers?: Record<string, string>;
+    body?: any;
+}
+/**
+ * 网络适配器接口
+ * 定义实际发送请求的能力
+ */
+/**
+ * 网络适配器接口
+ * 定义实际发送请求的能力
+ */
+interface NetworkAdapter {
+    get<T>(url: string, params?: any, headers?: Record<string, string>): Promise<T>;
+    post<T>(url: string, body?: any, headers?: Record<string, string>): Promise<T>;
+    put?<T>(url: string, body?: any, headers?: Record<string, string>): Promise<T>;
+    delete?<T>(url: string, params?: any, headers?: Record<string, string>): Promise<T>;
+    patch?<T>(url: string, body?: any, headers?: Record<string, string>): Promise<T>;
+}
+/**
+ * 网络处理器接口 (Strategy Pattern)
+ * 组合了"匹配规则"和"执行能力"
+ */
+interface NetworkHandler {
+    /** 处理器名称 (用于调试) */
+    name?: string;
+    /** 判断该 URL 是否由此适配器处理 */
+    shouldHandle(url: string, method: HttpMethod): boolean;
+    /** 具体的网络适配器 */
+    adapter: NetworkAdapter;
+}
+/**
+ * 请求链规则 (Chain Step)
+ */
+interface ChainRequestRule {
+    /**
+     * 结果存储的键名 (Context Key)
+     * Fetch 结果存储: context[key] = response
+     */
+    key?: string;
+    /**
+     * HTTP 请求详情
+     */
+    request: HttpRequestSpec;
+    /**
+     * 数据提取选择器
+     * 用于从响应中提取特定数据, e.g., "elements.0"
+     */
+    selector?: string;
+    /** 是否允许请求失败 (默认 false) */
+    optional?: boolean;
+    /**
+     * 是否包含上下文
+     * 如果为 true，请求 Body 将自动合并当前 Context 和 Payload
+     */
+    includeContext?: boolean;
+    /**
+     * 上下文筛选列表 (优先级高于 includeContext)
+     * 指定需要合并到 Body 中的 Context Key 列表
+     * e.g., ["rawProfile", "rawCompany"]
+     */
+    pickContext?: string[];
+    /** 额外 Payload (仅当 includeContext 为 true 或 pickContext 存在时合并) */
+    payload?: Record<string, any>;
+}
+/**
+ * 请求链执行器 (Request Chain Engine)
+ * 支持链式请求、上下文累积、智能路由、变量替换
+ *
+ * @param requests 链式执行规则列表
+ * @param handlers 网络适配器处理器列表 (按顺序匹配)
+ */
+declare function executeRequestChain<T>(requests: ChainRequestRule[], handlers?: NetworkHandler[], getChainRequests?: (context: Record<string, any>) => ChainRequestRule[] | null | undefined, initContext?: Record<string, any>): Promise<T>;
+
+export { type ChainRequestRule, type HttpRequestSpec, type NetworkAdapter, type NetworkHandler, executeRequestChain };

package/dist/chain.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Request Chain Runner
+ * 负责解析和执行通用的 HTTP 请求链 (Chain Execution)
+ * 适用于任何需要链式 HTTP 请求编排的场景
+ */
+/** Supported HTTP Methods */
+type HttpMethod = "GET" | "POST" | "PUT" | "DELETE" | "PATCH";
+/** HTTP 请求参数 */
+interface HttpRequestSpec {
+    method: HttpMethod;
+    url: string;
+    headers?: Record<string, string>;
+    body?: any;
+}
+/**
+ * 网络适配器接口
+ * 定义实际发送请求的能力
+ */
+/**
+ * 网络适配器接口
+ * 定义实际发送请求的能力
+ */
+interface NetworkAdapter {
+    get<T>(url: string, params?: any, headers?: Record<string, string>): Promise<T>;
+    post<T>(url: string, body?: any, headers?: Record<string, string>): Promise<T>;
+    put?<T>(url: string, body?: any, headers?: Record<string, string>): Promise<T>;
+    delete?<T>(url: string, params?: any, headers?: Record<string, string>): Promise<T>;
+    patch?<T>(url: string, body?: any, headers?: Record<string, string>): Promise<T>;
+}
+/**
+ * 网络处理器接口 (Strategy Pattern)
+ * 组合了"匹配规则"和"执行能力"
+ */
+interface NetworkHandler {
+    /** 处理器名称 (用于调试) */
+    name?: string;
+    /** 判断该 URL 是否由此适配器处理 */
+    shouldHandle(url: string, method: HttpMethod): boolean;
+    /** 具体的网络适配器 */
+    adapter: NetworkAdapter;
+}
+/**
+ * 请求链规则 (Chain Step)
+ */
+interface ChainRequestRule {
+    /**
+     * 结果存储的键名 (Context Key)
+     * Fetch 结果存储: context[key] = response
+     */
+    key?: string;
+    /**
+     * HTTP 请求详情
+     */
+    request: HttpRequestSpec;
+    /**
+     * 数据提取选择器
+     * 用于从响应中提取特定数据, e.g., "elements.0"
+     */
+    selector?: string;
+    /** 是否允许请求失败 (默认 false) */
+    optional?: boolean;
+    /**
+     * 是否包含上下文
+     * 如果为 true，请求 Body 将自动合并当前 Context 和 Payload
+     */
+    includeContext?: boolean;
+    /**
+     * 上下文筛选列表 (优先级高于 includeContext)
+     * 指定需要合并到 Body 中的 Context Key 列表
+     * e.g., ["rawProfile", "rawCompany"]
+     */
+    pickContext?: string[];
+    /** 额外 Payload (仅当 includeContext 为 true 或 pickContext 存在时合并) */
+    payload?: Record<string, any>;
+}
+/**
+ * 请求链执行器 (Request Chain Engine)
+ * 支持链式请求、上下文累积、智能路由、变量替换
+ *
+ * @param requests 链式执行规则列表
+ * @param handlers 网络适配器处理器列表 (按顺序匹配)
+ */
+declare function executeRequestChain<T>(requests: ChainRequestRule[], handlers?: NetworkHandler[], getChainRequests?: (context: Record<string, any>) => ChainRequestRule[] | null | undefined, initContext?: Record<string, any>): Promise<T>;
+
+export { type ChainRequestRule, type HttpRequestSpec, type NetworkAdapter, type NetworkHandler, executeRequestChain };