@i.un/api-client 1.0.9 → 1.1.0

package/dist/index.d.mts

@@ -136,131 +136,85 @@ interface ChainRequestRule {
 declare function executeRequestChain<T>(requests: ChainRequestRule[], handlers?: NetworkHandler[], getChainRequests?: (context: Record<string, any>) => ChainRequestRule[] | null | undefined, initContext?: Record<string, any>): Promise<T>;
 
 /**
- * Protobuf 通用编解码模块
+ * Protobuf 安全通信模块
  *
- * 特性：
- * - 支持加盐混淆（每次编码结果不同）
- * - 直接输出二进制格式
- * - 内置通用容器 schema（任意 JSON 数据）
- * - 支持自定义编解码函数
+ * 提供基于 Protobuf 的二进制序列化、XOR 混淆加密以及与 API Client 的无缝集成。
  */
 
+/**
+ * 基础编解码配置
+ * 控制如何将数据转换为二进制，以及是否混淆
+ */
 interface ProtobufCodecOptions {
-    /** 是否启用混淆 (默认 true) */
+    /** 是否启用二进制 XOR 混淆 (默认 true) */
     obfuscate?: boolean;
     /**
      * 混淆密钥
      * 可以是静态字符串/字节数组，也可以是动态获取密钥的同步或异步函数
      */
     obfuscationKey?: string | Uint8Array | (() => string | Uint8Array | Promise<string | Uint8Array>);
-    /** 自定义 Schema (proto3 syntax) */
-    schema?: string;
-    /** 自定义消息类型名称 (默认 "SecurePayload") */
-    messageName?: string;
-    /** 自定义数据转换逻辑 (用于非默认 Schema) */
+    /** 预编译的 Protobuf 类型对象 (推荐，性能最高) */
+    protoType?: any;
+    /** 数据转换钩子：处理业务模型与 Proto 结构不一致的情况 */
     transform?: {
-        /** 编码前转换：将原始数据转为符合 Schema 的对象 */
         beforeEncode?: (data: any) => any;
-        /** 解码后转换：将 Schema 对象转回原始数据 */
         afterDecode?: (payload: any) => any;
     };
 }
-interface ProtobufConfig {
-    /** 自定义编码函数 */
-    encode?: (data: unknown) => Uint8Array | Promise<Uint8Array>;
-    /** 自定义解码函数 */
+/**
+ * 完全自定义编解码接口
+ * 用于外部项目完全接管序列化过程，同时复用基础库的混淆外壳
+ */
+interface ProtobufCustomCodec {
+    /** 外部定义的编码逻辑 (返回原始二进制) */
+    encode?: (data: any) => Uint8Array | Promise<Uint8Array>;
+    /** 外部定义的解码逻辑 (返回原始对象) */
     decode?: <T>(buffer: Uint8Array) => T | Promise<T>;
-    /** 编码选项（仅内置编解码器使用） */
+}
+/**
+ * 集成配置项
+ * 用于 createProtobufHooks 或 API Client 全局配置
+ */
+interface ProtobufHooksOptions extends ProtobufCodecOptions, ProtobufCustomCodec {
+}
+/**
+ * API Client 内部使用的标准化配置
+ */
+interface ProtobufConfig {
+    encode: (data: any) => Uint8Array | Promise<Uint8Array>;
+    decode: <T>(buffer: Uint8Array) => T | Promise<T>;
     options?: ProtobufCodecOptions;
 }
+/** 简单的二进制异或混淆转换 */
+declare function xorTransform(data: Uint8Array, key: string | Uint8Array): Uint8Array;
+/** 获取混淆密钥（支持异步/函数） */
+declare function getObfuscationKey(keyOption?: ProtobufCodecOptions["obfuscationKey"]): Promise<string | Uint8Array>;
 /**
  * 编码安全载荷
  *
- * @param data - 任意 JSON 可序列化数据
- * @param options - 编解码选项
- * @returns Uint8Array 混淆后的二进制数据
+ * 流程：业务数据 -> (自定义编码 / Proto 序列化) -> 二进制混淆
  */
-declare function encodeSecure<T>(data: T, options?: ProtobufCodecOptions): Promise<Uint8Array>;
+declare function encodeSecure<T>(data: T, options?: ProtobufHooksOptions): Promise<Uint8Array>;
 /**
  * 解码安全载荷
  *
- * @param buffer - 二进制数据
- * @param options - 编解码选项
- * @returns 解码后的原始数据
- */
-declare function decodeSecure<T>(buffer: Uint8Array | ArrayBuffer, options?: ProtobufCodecOptions): Promise<T>;
-/**
- * 创建 Protobuf 二进制响应
- *
- * @param data - 要编码的数据
- * @param options - 编码选项和 CORS headers
- * @returns Response 对象
+ * 流程：二进制流 -> 二进制反混淆 -> (自定义解码 / Proto 反序列化) -> 业务数据
  */
+declare function decodeSecure<T>(buffer: Uint8Array | ArrayBuffer, options?: ProtobufHooksOptions): Promise<T>;
+/** 创建安全响应 (Worker/Server 端使用) */
 declare function secureResponse<T>(data: T, options?: ProtobufCodecOptions & {
     corsHeaders?: Record<string, string>;
 }): Promise<Response>;
-/**
- * 检查 Content-Type 是否是 Protobuf 格式
- */
+/** 解析安全请求体 (Worker/Server 端使用) */
+declare function parseSecureRequest<T>(request: Request, customDecode?: ProtobufCustomCodec["decode"]): Promise<T>;
+/** 检查是否为 Protobuf 响应头 */
 declare function isProtobufContentType(contentType: string | null): boolean;
-/**
- * 规范化 protobuf 配置
- * 将 boolean | ProtobufConfig 统一为 ProtobufConfig 或 null
- */
-declare function normalizeProtobufConfig(config: boolean | ProtobufConfig | undefined): ProtobufConfig | null;
-/**
- * 解析 Protobuf 请求体 (Worker/Server 端使用)
- *
- * @param request - Request 对象
- * @param customDecode - 可选的自定义解码函数
- * @returns 解码后的数据
- */
-declare function parseSecureRequest<T>(request: Request, customDecode?: (buffer: Uint8Array) => T | Promise<T>): Promise<T>;
-/**
- * Protobuf 钩子选项
- */
-interface CreateProtobufHooksOptions extends ProtobufCodecOptions {
-    /** 自定义编码函数 */
-    encode?: (data: unknown) => Uint8Array | Promise<Uint8Array>;
-    /** 自定义解码函数 */
-    decode?: <T>(buffer: Uint8Array) => T | Promise<T>;
-}
-/**
- * 创建 Protobuf 编解码钩子
- * 用于与 createApiClient 配合使用
- *
- * 钩子会自动：
- * - 设置 responseType 为 arrayBuffer
- * - 编码请求体为 Protobuf 格式
- * - 根据响应 Content-Type 自动解码（protobuf 或 JSON）
- *
- * @example
- * ```ts
- * import { createApiClient } from '@i.un/api-client';
- * import { createProtobufHooks } from '@i.un/api-client/protobuf';
- *
- * const { onRequest, onResponse } = createProtobufHooks();
- *
- * const client = createApiClient({
- *   baseURL: 'https://api.example.com',
- *   tokenStorage,
- *   onRequest,
- *   onResponse,
- * });
- *
- * // 自动处理，无需手动指定 responseType
- * const data = await client.post('/api/data', body);
- * ```
- */
-declare function createProtobufHooks(options?: CreateProtobufHooksOptions): {
-    /**
-     * 请求钩子：独立处理请求编码和响应类型设置
-     */
+/** 标准化配置对象 */
+declare function normalizeProtobufConfig(config: boolean | ProtobufConfig | undefined, options?: ProtobufHooksOptions): ProtobufConfig | null;
+/** 创建 Protobuf 编解码钩子 (用于与 createApiClient 配合使用) */
+declare function createProtobufHooks(options?: ProtobufHooksOptions): {
     onRequest(context: FetchContext): Promise<void>;
-    /**
-     * 响应钩子：解码 Protobuf 响应
-     */
     onResponse(context: FetchContext): Promise<void>;
 };
 
-export { type ApiError, type ApiResult, type ChainRequestRule, type CreateApiClientOptions, type CreateProtobufHooksOptions, type HttpRequestSpec, type NetworkAdapter, type NetworkHandler, type ProtobufCodecOptions, type ProtobufConfig, type TokenStorage, createApiClient, createProtobufHooks, decodeSecure, encodeSecure, executeRequestChain, isApiError, isProtobufContentType, normalizeProtobufConfig, parseSecureRequest, secureResponse };
+export { type ApiError, type ApiResult, type ChainRequestRule, type CreateApiClientOptions, type HttpRequestSpec, type NetworkAdapter, type NetworkHandler, type ProtobufCodecOptions, type ProtobufConfig, type ProtobufCustomCodec, type ProtobufHooksOptions, type TokenStorage, createApiClient, createProtobufHooks, decodeSecure, encodeSecure, executeRequestChain, getObfuscationKey, isApiError, isProtobufContentType, normalizeProtobufConfig, parseSecureRequest, secureResponse, xorTransform };

package/dist/index.d.ts

@@ -136,131 +136,85 @@ interface ChainRequestRule {
 declare function executeRequestChain<T>(requests: ChainRequestRule[], handlers?: NetworkHandler[], getChainRequests?: (context: Record<string, any>) => ChainRequestRule[] | null | undefined, initContext?: Record<string, any>): Promise<T>;
 
 /**
- * Protobuf 通用编解码模块
+ * Protobuf 安全通信模块
  *
- * 特性：
- * - 支持加盐混淆（每次编码结果不同）
- * - 直接输出二进制格式
- * - 内置通用容器 schema（任意 JSON 数据）
- * - 支持自定义编解码函数
+ * 提供基于 Protobuf 的二进制序列化、XOR 混淆加密以及与 API Client 的无缝集成。
  */
 
+/**
+ * 基础编解码配置
+ * 控制如何将数据转换为二进制，以及是否混淆
+ */
 interface ProtobufCodecOptions {
-    /** 是否启用混淆 (默认 true) */
+    /** 是否启用二进制 XOR 混淆 (默认 true) */
     obfuscate?: boolean;
     /**
      * 混淆密钥
      * 可以是静态字符串/字节数组，也可以是动态获取密钥的同步或异步函数
      */
     obfuscationKey?: string | Uint8Array | (() => string | Uint8Array | Promise<string | Uint8Array>);
-    /** 自定义 Schema (proto3 syntax) */
-    schema?: string;
-    /** 自定义消息类型名称 (默认 "SecurePayload") */
-    messageName?: string;
-    /** 自定义数据转换逻辑 (用于非默认 Schema) */
+    /** 预编译的 Protobuf 类型对象 (推荐，性能最高) */
+    protoType?: any;
+    /** 数据转换钩子：处理业务模型与 Proto 结构不一致的情况 */
     transform?: {
-        /** 编码前转换：将原始数据转为符合 Schema 的对象 */
         beforeEncode?: (data: any) => any;
-        /** 解码后转换：将 Schema 对象转回原始数据 */
         afterDecode?: (payload: any) => any;
     };
 }
-interface ProtobufConfig {
-    /** 自定义编码函数 */
-    encode?: (data: unknown) => Uint8Array | Promise<Uint8Array>;
-    /** 自定义解码函数 */
+/**
+ * 完全自定义编解码接口
+ * 用于外部项目完全接管序列化过程，同时复用基础库的混淆外壳
+ */
+interface ProtobufCustomCodec {
+    /** 外部定义的编码逻辑 (返回原始二进制) */
+    encode?: (data: any) => Uint8Array | Promise<Uint8Array>;
+    /** 外部定义的解码逻辑 (返回原始对象) */
     decode?: <T>(buffer: Uint8Array) => T | Promise<T>;
-    /** 编码选项（仅内置编解码器使用） */
+}
+/**
+ * 集成配置项
+ * 用于 createProtobufHooks 或 API Client 全局配置
+ */
+interface ProtobufHooksOptions extends ProtobufCodecOptions, ProtobufCustomCodec {
+}
+/**
+ * API Client 内部使用的标准化配置
+ */
+interface ProtobufConfig {
+    encode: (data: any) => Uint8Array | Promise<Uint8Array>;
+    decode: <T>(buffer: Uint8Array) => T | Promise<T>;
     options?: ProtobufCodecOptions;
 }
+/** 简单的二进制异或混淆转换 */
+declare function xorTransform(data: Uint8Array, key: string | Uint8Array): Uint8Array;
+/** 获取混淆密钥（支持异步/函数） */
+declare function getObfuscationKey(keyOption?: ProtobufCodecOptions["obfuscationKey"]): Promise<string | Uint8Array>;
 /**
  * 编码安全载荷
  *
- * @param data - 任意 JSON 可序列化数据
- * @param options - 编解码选项
- * @returns Uint8Array 混淆后的二进制数据
+ * 流程：业务数据 -> (自定义编码 / Proto 序列化) -> 二进制混淆
  */
-declare function encodeSecure<T>(data: T, options?: ProtobufCodecOptions): Promise<Uint8Array>;
+declare function encodeSecure<T>(data: T, options?: ProtobufHooksOptions): Promise<Uint8Array>;
 /**
  * 解码安全载荷
  *
- * @param buffer - 二进制数据
- * @param options - 编解码选项
- * @returns 解码后的原始数据
- */
-declare function decodeSecure<T>(buffer: Uint8Array | ArrayBuffer, options?: ProtobufCodecOptions): Promise<T>;
-/**
- * 创建 Protobuf 二进制响应
- *
- * @param data - 要编码的数据
- * @param options - 编码选项和 CORS headers
- * @returns Response 对象
+ * 流程：二进制流 -> 二进制反混淆 -> (自定义解码 / Proto 反序列化) -> 业务数据
  */
+declare function decodeSecure<T>(buffer: Uint8Array | ArrayBuffer, options?: ProtobufHooksOptions): Promise<T>;
+/** 创建安全响应 (Worker/Server 端使用) */
 declare function secureResponse<T>(data: T, options?: ProtobufCodecOptions & {
     corsHeaders?: Record<string, string>;
 }): Promise<Response>;
-/**
- * 检查 Content-Type 是否是 Protobuf 格式
- */
+/** 解析安全请求体 (Worker/Server 端使用) */
+declare function parseSecureRequest<T>(request: Request, customDecode?: ProtobufCustomCodec["decode"]): Promise<T>;
+/** 检查是否为 Protobuf 响应头 */
 declare function isProtobufContentType(contentType: string | null): boolean;
-/**
- * 规范化 protobuf 配置
- * 将 boolean | ProtobufConfig 统一为 ProtobufConfig 或 null
- */
-declare function normalizeProtobufConfig(config: boolean | ProtobufConfig | undefined): ProtobufConfig | null;
-/**
- * 解析 Protobuf 请求体 (Worker/Server 端使用)
- *
- * @param request - Request 对象
- * @param customDecode - 可选的自定义解码函数
- * @returns 解码后的数据
- */
-declare function parseSecureRequest<T>(request: Request, customDecode?: (buffer: Uint8Array) => T | Promise<T>): Promise<T>;
-/**
- * Protobuf 钩子选项
- */
-interface CreateProtobufHooksOptions extends ProtobufCodecOptions {
-    /** 自定义编码函数 */
-    encode?: (data: unknown) => Uint8Array | Promise<Uint8Array>;
-    /** 自定义解码函数 */
-    decode?: <T>(buffer: Uint8Array) => T | Promise<T>;
-}
-/**
- * 创建 Protobuf 编解码钩子
- * 用于与 createApiClient 配合使用
- *
- * 钩子会自动：
- * - 设置 responseType 为 arrayBuffer
- * - 编码请求体为 Protobuf 格式
- * - 根据响应 Content-Type 自动解码（protobuf 或 JSON）
- *
- * @example
- * ```ts
- * import { createApiClient } from '@i.un/api-client';
- * import { createProtobufHooks } from '@i.un/api-client/protobuf';
- *
- * const { onRequest, onResponse } = createProtobufHooks();
- *
- * const client = createApiClient({
- *   baseURL: 'https://api.example.com',
- *   tokenStorage,
- *   onRequest,
- *   onResponse,
- * });
- *
- * // 自动处理，无需手动指定 responseType
- * const data = await client.post('/api/data', body);
- * ```
- */
-declare function createProtobufHooks(options?: CreateProtobufHooksOptions): {
-    /**
-     * 请求钩子：独立处理请求编码和响应类型设置
-     */
+/** 标准化配置对象 */
+declare function normalizeProtobufConfig(config: boolean | ProtobufConfig | undefined, options?: ProtobufHooksOptions): ProtobufConfig | null;
+/** 创建 Protobuf 编解码钩子 (用于与 createApiClient 配合使用) */
+declare function createProtobufHooks(options?: ProtobufHooksOptions): {
     onRequest(context: FetchContext): Promise<void>;
-    /**
-     * 响应钩子：解码 Protobuf 响应
-     */
     onResponse(context: FetchContext): Promise<void>;
 };
 
-export { type ApiError, type ApiResult, type ChainRequestRule, type CreateApiClientOptions, type CreateProtobufHooksOptions, type HttpRequestSpec, type NetworkAdapter, type NetworkHandler, type ProtobufCodecOptions, type ProtobufConfig, type TokenStorage, createApiClient, createProtobufHooks, decodeSecure, encodeSecure, executeRequestChain, isApiError, isProtobufContentType, normalizeProtobufConfig, parseSecureRequest, secureResponse };
+export { type ApiError, type ApiResult, type ChainRequestRule, type CreateApiClientOptions, type HttpRequestSpec, type NetworkAdapter, type NetworkHandler, type ProtobufCodecOptions, type ProtobufConfig, type ProtobufCustomCodec, type ProtobufHooksOptions, type TokenStorage, createApiClient, createProtobufHooks, decodeSecure, encodeSecure, executeRequestChain, getObfuscationKey, isApiError, isProtobufContentType, normalizeProtobufConfig, parseSecureRequest, secureResponse, xorTransform };