@i.un/api-client 1.0.8 → 1.1.0

package/dist/index.d.mts

@@ -136,116 +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) */
-    useSalt?: boolean;
-    /** 自定义盐值生成器 */
-    saltGenerator?: () => string;
-}
-interface ProtobufConfig {
-    /** 自定义编码函数 */
-    encode?: (data: unknown) => Uint8Array | Promise<Uint8Array>;
-    /** 自定义解码函数 */
-    decode?: <T>(buffer: Uint8Array) => T | Promise<T>;
-    /** 编码选项（仅内置编解码器使用） */
-    options?: ProtobufCodecOptions;
-}
 /**
- * 使用内置 SaltedPayload schema 编码数据
- *
- * @param data - 任意 JSON 可序列化数据
- * @param options - 编码选项
- * @returns Uint8Array 二进制数据
- */
-declare function encodeProtobuf<T>(data: T, options?: ProtobufCodecOptions): Uint8Array;
-/**
- * 使用内置 SaltedPayload schema 解码数据
- *
- * @param buffer - 二进制数据
- * @returns 解码后的原始数据
+ * 基础编解码配置
+ * 控制如何将数据转换为二进制，以及是否混淆
  */
-declare function decodeProtobuf<T>(buffer: Uint8Array | ArrayBuffer): T;
+interface ProtobufCodecOptions {
+    /** 是否启用二进制 XOR 混淆 (默认 true) */
+    obfuscate?: boolean;
+    /**
+     * 混淆密钥
+     * 可以是静态字符串/字节数组，也可以是动态获取密钥的同步或异步函数
+     */
+    obfuscationKey?: string | Uint8Array | (() => string | Uint8Array | Promise<string | Uint8Array>);
+    /** 预编译的 Protobuf 类型对象 (推荐，性能最高) */
+    protoType?: any;
+    /** 数据转换钩子：处理业务模型与 Proto 结构不一致的情况 */
+    transform?: {
+        beforeEncode?: (data: any) => any;
+        afterDecode?: (payload: any) => any;
+    };
+}
 /**
- * 创建 Protobuf 二进制响应
- *
- * @param data - 要编码的数据
- * @param options - 编码选项和 CORS headers
- * @returns Response 对象
+ * 完全自定义编解码接口
+ * 用于外部项目完全接管序列化过程，同时复用基础库的混淆外壳
  */
-declare function protobufResponse<T>(data: T, options?: ProtobufCodecOptions & {
-    corsHeaders?: Record<string, string>;
-}): Response;
+interface ProtobufCustomCodec {
+    /** 外部定义的编码逻辑 (返回原始二进制) */
+    encode?: (data: any) => Uint8Array | Promise<Uint8Array>;
+    /** 外部定义的解码逻辑 (返回原始对象) */
+    decode?: <T>(buffer: Uint8Array) => T | Promise<T>;
+}
 /**
- * 检查 Content-Type 是否是 Protobuf 格式
+ * 集成配置项
+ * 用于 createProtobufHooks 或 API Client 全局配置
  */
-declare function isProtobufContentType(contentType: string | null): boolean;
+interface ProtobufHooksOptions extends ProtobufCodecOptions, ProtobufCustomCodec {
+}
 /**
- * 规范化 protobuf 配置
- * 将 boolean | ProtobufConfig 统一为 ProtobufConfig 或 null
+ * API Client 内部使用的标准化配置
  */
-declare function normalizeProtobufConfig(config: boolean | ProtobufConfig | undefined): ProtobufConfig | null;
+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>;
 /**
- * 解析 Protobuf 请求体 (Worker/Server 端使用)
+ * 编码安全载荷
  *
- * @param request - Request 对象
- * @param customDecode - 可选的自定义解码函数
- * @returns 解码后的数据
+ * 流程：业务数据 -> (自定义编码 / Proto 序列化) -> 二进制混淆
  */
-declare function parseProtobufRequest<T>(request: Request, customDecode?: (buffer: Uint8Array) => T | Promise<T>): Promise<T>;
+declare function encodeSecure<T>(data: T, options?: ProtobufHooksOptions): Promise<Uint8Array>;
 /**
- * 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);
- * ```
+ * 流程：二进制流 -> 二进制反混淆 -> (自定义解码 / Proto 反序列化) -> 业务数据
  */
-declare function createProtobufHooks(options?: CreateProtobufHooksOptions): {
-    /**
-     * 请求钩子：独立处理请求编码和响应类型设置
-     */
+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>;
+/** 解析安全请求体 (Worker/Server 端使用) */
+declare function parseSecureRequest<T>(request: Request, customDecode?: ProtobufCustomCodec["decode"]): Promise<T>;
+/** 检查是否为 Protobuf 响应头 */
+declare function isProtobufContentType(contentType: string | null): boolean;
+/** 标准化配置对象 */
+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, decodeProtobuf, encodeProtobuf, executeRequestChain, isApiError, isProtobufContentType, normalizeProtobufConfig, parseProtobufRequest, protobufResponse };
+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,116 +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) */
-    useSalt?: boolean;
-    /** 自定义盐值生成器 */
-    saltGenerator?: () => string;
-}
-interface ProtobufConfig {
-    /** 自定义编码函数 */
-    encode?: (data: unknown) => Uint8Array | Promise<Uint8Array>;
-    /** 自定义解码函数 */
-    decode?: <T>(buffer: Uint8Array) => T | Promise<T>;
-    /** 编码选项（仅内置编解码器使用） */
-    options?: ProtobufCodecOptions;
-}
 /**
- * 使用内置 SaltedPayload schema 编码数据
- *
- * @param data - 任意 JSON 可序列化数据
- * @param options - 编码选项
- * @returns Uint8Array 二进制数据
- */
-declare function encodeProtobuf<T>(data: T, options?: ProtobufCodecOptions): Uint8Array;
-/**
- * 使用内置 SaltedPayload schema 解码数据
- *
- * @param buffer - 二进制数据
- * @returns 解码后的原始数据
+ * 基础编解码配置
+ * 控制如何将数据转换为二进制，以及是否混淆
  */
-declare function decodeProtobuf<T>(buffer: Uint8Array | ArrayBuffer): T;
+interface ProtobufCodecOptions {
+    /** 是否启用二进制 XOR 混淆 (默认 true) */
+    obfuscate?: boolean;
+    /**
+     * 混淆密钥
+     * 可以是静态字符串/字节数组，也可以是动态获取密钥的同步或异步函数
+     */
+    obfuscationKey?: string | Uint8Array | (() => string | Uint8Array | Promise<string | Uint8Array>);
+    /** 预编译的 Protobuf 类型对象 (推荐，性能最高) */
+    protoType?: any;
+    /** 数据转换钩子：处理业务模型与 Proto 结构不一致的情况 */
+    transform?: {
+        beforeEncode?: (data: any) => any;
+        afterDecode?: (payload: any) => any;
+    };
+}
 /**
- * 创建 Protobuf 二进制响应
- *
- * @param data - 要编码的数据
- * @param options - 编码选项和 CORS headers
- * @returns Response 对象
+ * 完全自定义编解码接口
+ * 用于外部项目完全接管序列化过程，同时复用基础库的混淆外壳
  */
-declare function protobufResponse<T>(data: T, options?: ProtobufCodecOptions & {
-    corsHeaders?: Record<string, string>;
-}): Response;
+interface ProtobufCustomCodec {
+    /** 外部定义的编码逻辑 (返回原始二进制) */
+    encode?: (data: any) => Uint8Array | Promise<Uint8Array>;
+    /** 外部定义的解码逻辑 (返回原始对象) */
+    decode?: <T>(buffer: Uint8Array) => T | Promise<T>;
+}
 /**
- * 检查 Content-Type 是否是 Protobuf 格式
+ * 集成配置项
+ * 用于 createProtobufHooks 或 API Client 全局配置
  */
-declare function isProtobufContentType(contentType: string | null): boolean;
+interface ProtobufHooksOptions extends ProtobufCodecOptions, ProtobufCustomCodec {
+}
 /**
- * 规范化 protobuf 配置
- * 将 boolean | ProtobufConfig 统一为 ProtobufConfig 或 null
+ * API Client 内部使用的标准化配置
  */
-declare function normalizeProtobufConfig(config: boolean | ProtobufConfig | undefined): ProtobufConfig | null;
+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>;
 /**
- * 解析 Protobuf 请求体 (Worker/Server 端使用)
+ * 编码安全载荷
  *
- * @param request - Request 对象
- * @param customDecode - 可选的自定义解码函数
- * @returns 解码后的数据
+ * 流程：业务数据 -> (自定义编码 / Proto 序列化) -> 二进制混淆
  */
-declare function parseProtobufRequest<T>(request: Request, customDecode?: (buffer: Uint8Array) => T | Promise<T>): Promise<T>;
+declare function encodeSecure<T>(data: T, options?: ProtobufHooksOptions): Promise<Uint8Array>;
 /**
- * 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);
- * ```
+ * 流程：二进制流 -> 二进制反混淆 -> (自定义解码 / Proto 反序列化) -> 业务数据
  */
-declare function createProtobufHooks(options?: CreateProtobufHooksOptions): {
-    /**
-     * 请求钩子：独立处理请求编码和响应类型设置
-     */
+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>;
+/** 解析安全请求体 (Worker/Server 端使用) */
+declare function parseSecureRequest<T>(request: Request, customDecode?: ProtobufCustomCodec["decode"]): Promise<T>;
+/** 检查是否为 Protobuf 响应头 */
+declare function isProtobufContentType(contentType: string | null): boolean;
+/** 标准化配置对象 */
+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, decodeProtobuf, encodeProtobuf, executeRequestChain, isApiError, isProtobufContentType, normalizeProtobufConfig, parseProtobufRequest, protobufResponse };
+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 };