apaas-oapi-client 0.1.29 → 0.1.31

package/.env

@@ -0,0 +1,5 @@
+CLIENT_APP_ID=c_fc919c38b7ab41a5ab36
+CLIENT_APP_SECRET=cad5106b819a43f286fb46a51b6ea2c8
+
+LARK_APP_ID=cli_a77cb9cd64b81013
+LARK_APP_SECRET=AEq56P8ntETGxNucLHTgbdLR2kNkXRNd

package/README.md

@@ -25,3 +25,10 @@
 
 ```bash
 npm install apaas-oapi-client
+```
+
+---
+
+## 📖 **使用文档**
+
+- 完整说明、初始化示例与 API 用法请查看 [UserManual.md](./UserManual.md)。

package/dist/index.d.ts

@@ -0,0 +1,513 @@
+import { LoggerLevel } from './logger';
+/**
+ * Client 初始化配置
+ */
+interface ClientOptions {
+    /** 命名空间, 例如 app_xxx */
+    namespace: string;
+    /** 应用 clientId */
+    clientId: string;
+    /** 应用 clientSecret */
+    clientSecret: string;
+    /** 是否禁用 token 缓存, 每次调用强制刷新 token, 默认 false */
+    disableTokenCache?: boolean;
+}
+/**
+ * aPaaS OpenAPI 客户端
+ */
+declare class Client {
+    private clientId;
+    private clientSecret;
+    private namespace;
+    private disableTokenCache;
+    private accessToken;
+    private expireTime;
+    private axiosInstance;
+    private loggerLevel;
+    /**
+     * 构造函数
+     * @param options ClientOptions
+     */
+    constructor(options: ClientOptions);
+    /**
+     * 设置日志等级
+     * @param level LoggerLevel
+     */
+    setLoggerLevel(level: LoggerLevel): void;
+    /**
+     * 日志打印方法
+     * @param level LoggerLevel
+     * @param args 打印内容
+     */
+    private log;
+    /**
+     * 初始化 client, 自动获取 token
+     */
+    init(): Promise<void>;
+    /**
+     * 获取 accessToken
+     */
+    private getAccessToken;
+    /**
+     * 确保 token 有效, 若过期则刷新
+     */
+    private ensureTokenValid;
+    /**
+     * 获取当前 accessToken
+     */
+    get token(): string | null;
+    /**
+     * 获取当前 token 剩余过期时间（单位：秒）
+     * @returns 剩余秒数，若无 token 则返回 null
+     */
+    get tokenExpireTime(): number | null;
+    /**
+     * 获取当前 namespace
+     */
+    get currentNamespace(): string;
+    /**
+     * 对象模块
+     */
+    object: {
+        /**
+         * 列出所有对象（数据表）
+         * @param params 请求参数 { offset, filter?, limit }
+         * @returns 接口返回结果
+         */
+        list: (params: {
+            offset: number;
+            filter?: {
+                type?: string;
+                quickQuery?: string;
+            };
+            limit: number;
+        }) => Promise<any>;
+        metadata: {
+            /**
+             * 获取指定对象下指定字段的元数据
+             * @description 查询指定对象下的单个字段元数据
+             * @param params 请求参数 { object_name, field_name }
+             * @returns 接口返回结果
+             */
+            field: (params: {
+                object_name: string;
+                field_name: string;
+            }) => Promise<any>;
+            /**
+             * 获取指定对象的所有字段信息
+             * @description 查询指定对象下的所有字段元数据
+             * @param params 请求参数 { object_name }
+             * @returns 接口返回结果
+             */
+            fields: (params: {
+                object_name: string;
+            }) => Promise<any>;
+        };
+        search: {
+            /**
+             * 单条记录查询
+             * @description 查询指定对象下的单条记录
+             * @param params 请求参数
+             * @returns 接口返回结果
+             */
+            record: (params: {
+                object_name: string;
+                record_id: string;
+                select: string[];
+            }) => Promise<any>;
+            /**
+             * 多条记录查询 - 最多传入 100 条
+             * @description 查询指定对象下的多条记录
+             * @param params 请求参数
+             * @returns 接口返回结果
+             */
+            records: (params: {
+                object_name: string;
+                data: any;
+            }) => Promise<any>;
+            /**
+             * 查询所有记录 - 支持超过 100 条数据，自动分页查询
+             * @description 该方法会自动处理分页，直到没有更多数据为止
+             * @param params 请求参数
+             * @returns { total, items }
+             */
+            recordsWithIterator: (params: {
+                object_name: string;
+                data: any;
+            }) => Promise<{
+                total: number;
+                items: any[];
+            }>;
+        };
+        create: {
+            /**
+             * 单条记录创建
+             * @description 创建单条记录到指定对象中
+             * @param params 请求参数 { object_name, record }
+             * @returns 接口返回结果
+             */
+            record: (params: {
+                object_name: string;
+                record: any;
+            }) => Promise<any>;
+            /**
+             * 批量创建记录 - 最多传入 100 条
+             * @description 创建多条记录到指定对象中
+             * @param params 请求参数 { object_name, records }
+             * @returns 接口返回结果
+             */
+            records: (params: {
+                object_name: string;
+                records: any[];
+            }) => Promise<any>;
+            /**
+             * 分批创建所有记录 - 支持超过 100 条数据，自动拆分
+             * @description 创建多条记录到指定对象中，超过 100 条数据会自动拆分为多次请求
+             * @param params 请求参数 { object_name, records }
+             * @returns { total, items }
+             */
+            recordsWithIterator: (params: {
+                object_name: string;
+                records: any[];
+            }) => Promise<{
+                total: number;
+                items: any[];
+            }>;
+        };
+        update: {
+            /**
+             * 单条更新
+             * @description 更新指定对象下的单条记录
+             * @param params 请求参数
+             * @returns 接口返回结果
+             */
+            record: (params: {
+                object_name: string;
+                record_id: string;
+                record: any;
+            }) => Promise<any>;
+            /**
+             * 多条更新 - 最多传入 100 条
+             * @description 更新指定对象下的多条记录
+             * @param params 请求参数
+             * @returns 接口返回结果
+             */
+            records: (params: {
+                object_name: string;
+                records: any[];
+            }) => Promise<any>;
+            /**
+             * 批量更新 - 支持超过 100 条数据，自动拆分
+             * @description 更新指定对象下的多条记录，超过 100 条数据会自动拆分为多次请求
+             * @param params 请求参数
+             * @returns 所有子请求的返回结果数组
+             */
+            recordsWithIterator: (params: {
+                object_name: string;
+                records: any[];
+            }) => Promise<any[]>;
+        };
+        delete: {
+            /**
+             * 单条删除
+             * @description 删除指定对象下的单条记录
+             * @param params 请求参数
+             * @returns 接口返回结果
+             */
+            record: (params: {
+                object_name: string;
+                record_id: string;
+            }) => Promise<any>;
+            /**
+             * 多条删除 - 最多传入 100 条
+             * @description 删除指定对象下的多条记录
+             * @param params 请求参数
+             * @returns 接口返回结果
+             */
+            records: (params: {
+                object_name: string;
+                ids: string[];
+            }) => Promise<any>;
+            /**
+             * 批量删除
+             * @description 删除指定对象下的多条记录，超过 100 条数据会自动拆分为多次请求
+             * @param params 请求参数
+             * @returns 所有子请求的返回结果数组
+             */
+            recordsWithIterator: (params: {
+                object_name: string;
+                ids: string[];
+            }) => Promise<any[]>;
+        };
+    };
+    /**
+     * 部门 ID 交换模块
+     */
+    department: {
+        /**
+         * 单个部门 ID 交换
+         * @param params 请求参数
+         * @returns 单个部门映射结果
+         */
+        exchange: (params: {
+            department_id_type: "department_id" | "external_department_id" | "external_open_department_id";
+            department_id: string;
+        }) => Promise<any>;
+        /**
+         * 批量部门 ID 交换
+         * @param params 请求参数
+         * @returns 所有子请求的返回结果数组
+         */
+        batchExchange: (params: {
+            department_id_type: "department_id" | "external_department_id" | "external_open_department_id";
+            department_ids: string[];
+        }) => Promise<any[]>;
+    };
+    /**
+     * 云函数模块
+     */
+    function: {
+        /**
+         * 调用云函数
+         * @param params 请求参数 { name: string; params: any }
+         * @returns 接口返回结果
+         */
+        invoke: (params: {
+            name: string;
+            params: any;
+        }) => Promise<any>;
+    };
+    /**
+     * 页面模块
+     */
+    page: {
+        /**
+         * 获取所有页面
+         * @param params 请求参数 { limit: number (max 200), offset: number }
+         * @returns 接口返回结果
+         */
+        list: (params: {
+            limit: number;
+            offset: number;
+        }) => Promise<any>;
+        /**
+         * 获取所有页面 - 支持自动分页，获取全部数据
+         * @description 该方法会自动处理分页，直到获取所有页面数据
+         * @param params 请求参数 { limit?: number }
+         * @returns { total, items }
+         */
+        listWithIterator: (params?: {
+            limit?: number;
+        }) => Promise<{
+            total: number;
+            items: any[];
+        }>;
+        /**
+         * 获取页面详情
+         * @param params 请求参数 { page_id: string }
+         * @returns 接口返回结果
+         */
+        detail: (params: {
+            page_id: string;
+        }) => Promise<any>;
+        /**
+         * 获取页面访问地址
+         * @param params 请求参数 { page_id: string, pageParams?: any, parentPageParams?: any, navId?: string, tabId?: string }
+         * @returns 接口返回结果
+         */
+        url: (params: {
+            page_id: string;
+            pageParams?: any;
+            parentPageParams?: any;
+            navId?: string;
+            tabId?: string;
+        }) => Promise<any>;
+    };
+    /**
+     * 附件模块
+     */
+    attachment: {
+        /**
+         * 文件操作
+         */
+        file: {
+            /**
+             * 上传文件
+             * @param params 请求参数 { file: any }
+             * @returns 接口返回结果
+             */
+            upload: (params: {
+                file: any;
+            }) => Promise<any>;
+            /**
+             * 下载文件
+             * @param params 请求参数 { file_id: string }
+             * @returns 文件二进制流
+             */
+            download: (params: {
+                file_id: string;
+            }) => Promise<any>;
+            /**
+             * 删除文件
+             * @param params 请求参数 { file_id: string }
+             * @returns 接口返回结果
+             */
+            delete: (params: {
+                file_id: string;
+            }) => Promise<any>;
+        };
+        /**
+         * 头像图片操作
+         */
+        avatar: {
+            /**
+             * 上传头像图片
+             * @param params 请求参数 { image: any }
+             * @returns 接口返回结果
+             */
+            upload: (params: {
+                image: any;
+            }) => Promise<any>;
+            /**
+             * 下载头像图片
+             * @param params 请求参数 { image_id: string }
+             * @returns 图片二进制流
+             */
+            download: (params: {
+                image_id: string;
+            }) => Promise<any>;
+        };
+    };
+    /**
+     * 全局数据模块
+     */
+    global: {
+        /**
+         * 全局选项
+         */
+        options: {
+            /**
+             * 查询全局选项详情
+             * @param params 请求参数 { api_name: string }
+             * @returns 接口返回结果
+             */
+            detail: (params: {
+                api_name: string;
+            }) => Promise<any>;
+            /**
+             * 查询全局选项列表
+             * @param params 请求参数 { limit: number, offset: number, filter?: { quickQuery?: string } }
+             * @returns 接口返回结果
+             */
+            list: (params: {
+                limit: number;
+                offset: number;
+                filter?: {
+                    quickQuery?: string;
+                };
+            }) => Promise<any>;
+            /**
+             * 查询所有全局选项 - 支持自动分页，获取全部数据
+             * @description 该方法会自动处理分页，直到获取所有全局选项数据
+             * @param params 请求参数 { limit?: number, filter?: { quickQuery?: string } }
+             * @returns { total, items }
+             */
+            listWithIterator: (params?: {
+                limit?: number;
+                filter?: {
+                    quickQuery?: string;
+                };
+            }) => Promise<{
+                total: number;
+                items: any[];
+            }>;
+        };
+        /**
+         * 环境变量
+         */
+        variables: {
+            /**
+             * 查询环境变量详情
+             * @param params 请求参数 { api_name: string }
+             * @returns 接口返回结果
+             */
+            detail: (params: {
+                api_name: string;
+            }) => Promise<any>;
+            /**
+             * 查询环境变量列表
+             * @param params 请求参数 { limit: number, offset: number, filter?: { quickQuery?: string } }
+             * @returns 接口返回结果
+             */
+            list: (params: {
+                limit: number;
+                offset: number;
+                filter?: {
+                    quickQuery?: string;
+                };
+            }) => Promise<any>;
+            /**
+             * 查询所有环境变量 - 支持自动分页，获取全部数据
+             * @description 该方法会自动处理分页，直到获取所有环境变量数据
+             * @param params 请求参数 { limit?: number, filter?: { quickQuery?: string } }
+             * @returns { total, items }
+             */
+            listWithIterator: (params?: {
+                limit?: number;
+                filter?: {
+                    quickQuery?: string;
+                };
+            }) => Promise<{
+                total: number;
+                items: any[];
+            }>;
+        };
+    };
+    /**
+     * 自动化流程模块
+     */
+    automation: {
+        /**
+         * V1 版本
+         */
+        v1: {
+            /**
+             * 执行流程
+             * @param params 请求参数 { flow_api_name: string, operator: { _id: number, email: string }, params: any }
+             * @returns 接口返回结果
+             */
+            execute: (params: {
+                flow_api_name: string;
+                operator: {
+                    _id: number;
+                    email: string;
+                };
+                params: any;
+            }) => Promise<any>;
+        };
+        /**
+         * V2 版本
+         */
+        v2: {
+            /**
+             * 执行流程
+             * @param params 请求参数 { flow_api_name: string, operator: { _id: number, email: string }, params: any, is_resubmit?: boolean, pre_instance_id?: string }
+             * @returns 接口返回结果
+             */
+            execute: (params: {
+                flow_api_name: string;
+                operator: {
+                    _id: number;
+                    email: string;
+                };
+                params: any;
+                is_resubmit?: boolean;
+                pre_instance_id?: string;
+            }) => Promise<any>;
+        };
+    };
+}
+export declare const apaas: {
+    Client: typeof Client;
+};
+export {};

package/dist/index.js

@@ -43,6 +43,64 @@ async function functionLimiter(fn, options = {}) {
     return wrapped();
 }
 
+/**
+ * 判断错误是否可重试
+ */
+function isRetryableError(error) {
+    // 网络错误
+    if (error.code === 'ECONNRESET' || error.code === 'ETIMEDOUT' || error.code === 'ENOTFOUND') {
+        return true;
+    }
+    // Axios 错误
+    if (axios.isAxiosError(error)) {
+        const axiosError = error;
+        // 没有响应(网络错误)
+        if (!axiosError.response) {
+            return true;
+        }
+        // 5xx 服务器错误
+        if (axiosError.response.status >= 500) {
+            return true;
+        }
+        // 429 限流
+        if (axiosError.response.status === 429) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * 带重试的函数执行
+ */
+async function executeWithRetry(fn, options = {}, logContext = '', logger) {
+    const { maxRetries = 3, initialDelay = 1000, maxDelay = 10000, backoffMultiplier = 2 } = options;
+    let lastError;
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+        try {
+            return await fn();
+        }
+        catch (error) {
+            lastError = error;
+            // 最后一次尝试，直接抛出
+            if (attempt === maxRetries) {
+                break;
+            }
+            // 判断是否可重试
+            if (!isRetryableError(error)) {
+                throw error;
+            }
+            // 计算延迟时间(指数退避)
+            const delay = Math.min(initialDelay * Math.pow(backoffMultiplier, attempt), maxDelay);
+            if (logger) {
+                logger(LoggerLevel.warn, `${logContext} Attempt ${attempt + 1}/${maxRetries + 1} failed, retrying in ${delay}ms...`, error instanceof Error ? error.message : String(error));
+            }
+            // 等待后重试
+            await new Promise(resolve => setTimeout(resolve, delay));
+        }
+    }
+    // 所有重试都失败
+    throw lastError;
+}
 /**
  * aPaaS OpenAPI 客户端
  */
@@ -631,10 +689,10 @@ class Client {
             /**
              * 批量部门 ID 交换
              * @param params 请求参数
-             * @returns 所有子请求的返回结果数组
+             * @returns 批量操作结果，包含成功和失败的详细信息
              */
             batchExchange: async (params) => {
-                const { department_id_type, department_ids } = params;
+                const { department_id_type, department_ids, retryOptions } = params;
                 // department_id_type 可选值：
                 // - 'department_id' (如 "1758534140403815")
                 // - 'external_department_id' (外部平台 department_id, 无固定格式)
@@ -646,37 +704,177 @@ class Client {
                 }
                 if (department_ids.length === 0) {
                     this.log(LoggerLevel.warn, '[department.batchExchange] Empty department_ids array provided, returning empty result');
-                    return [];
+                    return { success: [], failed: [], successCount: 0, failedCount: 0, total: 0 };
                 }
                 const url = '/api/integration/v2/feishu/getDepartments';
-                const chunkSize = 100;
+                const chunkSize = 200; // 最大支持200个
                 const chunks = [];
                 for (let i = 0; i < department_ids.length; i += chunkSize) {
                     chunks.push(department_ids.slice(i, i + chunkSize));
                 }
                 this.log(LoggerLevel.info, `[department.batchExchange] Chunking ${department_ids.length} department IDs into ${chunks.length} groups of ${chunkSize}`);
-                const results = [];
+                const successResults = [];
+                const failedResults = [];
                 for (const [index, chunk] of chunks.entries()) {
                     this.log(LoggerLevel.info, `[department.batchExchange] Processing chunk ${index + 1}/${chunks.length}: ${chunk.length} IDs`);
-                    const res = await functionLimiter(async () => {
-                        await this.ensureTokenValid();
-                        const response = await this.axiosInstance.post(url, {
-                            department_id_type,
-                            department_ids: chunk
-                        }, {
-                            headers: { Authorization: `${this.accessToken}` }
+                    try {
+                        const res = await executeWithRetry(async () => {
+                            return await functionLimiter(async () => {
+                                await this.ensureTokenValid();
+                                const response = await this.axiosInstance.post(url, {
+                                    department_id_type,
+                                    department_ids: chunk
+                                }, {
+                                    headers: { Authorization: `${this.accessToken}` },
+                                    timeout: 30000 // 30秒超时
+                                });
+                                this.log(LoggerLevel.debug, `[department.batchExchange] Chunk ${index + 1} completed: code=${response.data.code}`);
+                                this.log(LoggerLevel.trace, `[department.batchExchange] Chunk ${index + 1} response: ${JSON.stringify(response.data)}`);
+                                if (response.data.code !== '0') {
+                                    this.log(LoggerLevel.error, `[department.batchExchange] Error exchanging departments: code=${response.data.code}, msg=${response.data.msg}`);
+                                    throw new Error(response.data.msg || `Exchange failed with code ${response.data.code}`);
+                                }
+                                return response.data.data || [];
+                            });
+                        }, retryOptions, `[department.batchExchange] Chunk ${index + 1}/${chunks.length}`, this.log.bind(this));
+                        successResults.push(...res);
+                        this.log(LoggerLevel.info, `[department.batchExchange] Chunk ${index + 1} succeeded: ${res.length} departments`);
+                    }
+                    catch (error) {
+                        // 部分失败：记录失败的chunk
+                        const errorMsg = error instanceof Error ? error.message : String(error);
+                        this.log(LoggerLevel.error, `[department.batchExchange] Chunk ${index + 1} failed after retries: ${errorMsg}`);
+                        chunk.forEach(id => {
+                            failedResults.push({
+                                id,
+                                error: errorMsg
+                            });
                         });
-                        this.log(LoggerLevel.debug, `[department.batchExchange] Chunk ${index + 1} completed: code=${response.data.code}`);
-                        this.log(LoggerLevel.trace, `[department.batchExchange] Chunk ${index + 1} response: ${JSON.stringify(response.data)}`);
-                        if (response.data.code !== '0') {
-                            this.log(LoggerLevel.error, `[department.batchExchange] Error exchanging departments: code=${response.data.code}, msg=${response.data.msg}`);
-                            throw new Error(response.data.msg || `Exchange failed with code ${response.data.code}`);
-                        }
-                        return response.data.data || [];
+                    }
+                }
+                const result = {
+                    success: successResults,
+                    failed: failedResults,
+                    successCount: successResults.length,
+                    failedCount: failedResults.length,
+                    total: department_ids.length
+                };
+                this.log(LoggerLevel.info, `[department.batchExchange] Completed: total=${result.total}, success=${result.successCount}, failed=${result.failedCount}`);
+                return result;
+            }
+        };
+        /**
+         * 用户 ID 交换模块
+         */
+        this.user = {
+            /**
+             * 单个用户 ID 交换
+             * @param params 请求参数
+             * @returns 单个用户映射结果
+             */
+            exchange: async (params) => {
+                const { user_id_type, user_id, feishu_app_id } = params;
+                // user_id_type 可选值：
+                // - 'user_id' (如 "1758534140403815")
+                // - 'external_user_id' (外部平台 user_id, 无固定格式)
+                // - 'external_open_id' (以 'ou_' 开头的 open_id)
+                const url = '/api/integration/v2/feishu/getUsers';
+                this.log(LoggerLevel.info, `[user.exchange] Exchanging user ID: ${user_id}`);
+                const res = await functionLimiter(async () => {
+                    await this.ensureTokenValid();
+                    const response = await this.axiosInstance.post(url, {
+                        user_id_type,
+                        feishu_app_id,
+                        user_ids: [user_id]
+                    }, {
+                        headers: { Authorization: `${this.accessToken}` }
                     });
-                    results.push(...res);
+                    this.log(LoggerLevel.debug, `[user.exchange] User ID exchanged: ${user_id}, code=${response.data.code}`);
+                    this.log(LoggerLevel.trace, `[user.exchange] Response: ${JSON.stringify(response.data)}`);
+                    if (response.data.code !== '0') {
+                        this.log(LoggerLevel.error, `[user.exchange] Error exchanging user: code=${response.data.code}, msg=${response.data.msg}`);
+                        throw new Error(response.data.msg || `Exchange failed with code ${response.data.code}`);
+                    }
+                    return response.data.data && response.data.data[0]; // 返回第一个元素
+                });
+                return res;
+            },
+            /**
+             * 批量用户 ID 交换
+             * @param params 请求参数
+             * @returns 批量操作结果，包含成功和失败的详细信息
+             */
+            batchExchange: async (params) => {
+                const { user_id_type, user_ids, feishu_app_id, retryOptions } = params;
+                // user_id_type 可选值：
+                // - 'user_id' (如 "1758534140403815")
+                // - 'external_user_id' (外部平台 user_id, 无固定格式)
+                // - 'external_open_id' (以 'ou_' 开头的 open_id)
+                // 参数校验
+                if (!user_ids || !Array.isArray(user_ids)) {
+                    this.log(LoggerLevel.error, '[user.batchExchange] Invalid user_ids parameter: must be a non-empty array');
+                    throw new Error('参数 user_ids 必须是一个数组');
+                }
+                if (user_ids.length === 0) {
+                    this.log(LoggerLevel.warn, '[user.batchExchange] Empty user_ids array provided, returning empty result');
+                    return { success: [], failed: [], successCount: 0, failedCount: 0, total: 0 };
+                }
+                const url = '/api/integration/v2/feishu/getUsers';
+                const chunkSize = 200; // 最大支持200个
+                const chunks = [];
+                for (let i = 0; i < user_ids.length; i += chunkSize) {
+                    chunks.push(user_ids.slice(i, i + chunkSize));
+                }
+                this.log(LoggerLevel.info, `[user.batchExchange] Chunking ${user_ids.length} user IDs into ${chunks.length} groups of ${chunkSize}`);
+                const successResults = [];
+                const failedResults = [];
+                for (const [index, chunk] of chunks.entries()) {
+                    this.log(LoggerLevel.info, `[user.batchExchange] Processing chunk ${index + 1}/${chunks.length}: ${chunk.length} IDs`);
+                    try {
+                        const res = await executeWithRetry(async () => {
+                            return await functionLimiter(async () => {
+                                await this.ensureTokenValid();
+                                const response = await this.axiosInstance.post(url, {
+                                    user_id_type,
+                                    feishu_app_id,
+                                    user_ids: chunk
+                                }, {
+                                    headers: { Authorization: `${this.accessToken}` },
+                                    timeout: 30000 // 30秒超时
+                                });
+                                this.log(LoggerLevel.debug, `[user.batchExchange] Chunk ${index + 1} completed: code=${response.data.code}`);
+                                this.log(LoggerLevel.trace, `[user.batchExchange] Chunk ${index + 1} response: ${JSON.stringify(response.data)}`);
+                                if (response.data.code !== '0') {
+                                    this.log(LoggerLevel.error, `[user.batchExchange] Error exchanging users: code=${response.data.code}, msg=${response.data.msg}`);
+                                    throw new Error(response.data.msg || `Exchange failed with code ${response.data.code}`);
+                                }
+                                return response.data.data || [];
+                            });
+                        }, retryOptions, `[user.batchExchange] Chunk ${index + 1}/${chunks.length}`, this.log.bind(this));
+                        successResults.push(...res);
+                        this.log(LoggerLevel.info, `[user.batchExchange] Chunk ${index + 1} succeeded: ${res.length} users`);
+                    }
+                    catch (error) {
+                        // 部分失败：记录失败的chunk
+                        const errorMsg = error instanceof Error ? error.message : String(error);
+                        this.log(LoggerLevel.error, `[user.batchExchange] Chunk ${index + 1} failed after retries: ${errorMsg}`);
+                        chunk.forEach(id => {
+                            failedResults.push({
+                                id,
+                                error: errorMsg
+                            });
+                        });
+                    }
                 }
-                return results;
+                const result = {
+                    success: successResults,
+                    failed: failedResults,
+                    successCount: successResults.length,
+                    failedCount: failedResults.length,
+                    total: user_ids.length
+                };
+                this.log(LoggerLevel.info, `[user.batchExchange] Completed: total=${result.total}, success=${result.successCount}, failed=${result.failedCount}`);
+                return result;
             }
         };
         /**

package/dist/limiter.d.ts

@@ -0,0 +1,17 @@
+import Bottleneck from 'bottleneck';
+/**
+ * 默认 apaas 限流配置
+ */
+export declare const apaasLimiterOptions: {
+    minTime: number;
+    reservoir: number;
+    reservoirRefreshAmount: number;
+    reservoirRefreshInterval: number;
+};
+/**
+ * 创建限流器
+ * @param fn 被限流函数
+ * @param options 自定义限流配置
+ * @returns 包装后的限流函数
+ */
+export declare function functionLimiter<T>(fn: () => Promise<T>, options?: Partial<Bottleneck.ConstructorOptions>): Promise<T>;

package/dist/logger.d.ts

@@ -0,0 +1,11 @@
+/**
+ * 日志等级枚举
+ */
+export declare enum LoggerLevel {
+    fatal = 0,
+    error = 1,
+    warn = 2,
+    info = 3,
+    debug = 4,
+    trace = 5
+}

package/dist/src/index.d.ts

@@ -1,4 +1,35 @@
 import { LoggerLevel } from './logger';
+/**
+ * 批量操作结果
+ */
+interface BatchResult<T> {
+    /** 成功的项 */
+    success: T[];
+    /** 失败的项 */
+    failed: Array<{
+        id: string;
+        error: string;
+    }>;
+    /** 成功数量 */
+    successCount: number;
+    /** 失败数量 */
+    failedCount: number;
+    /** 总数 */
+    total: number;
+}
+/**
+ * 重试配置
+ */
+interface RetryOptions {
+    /** 最大重试次数 */
+    maxRetries?: number;
+    /** 初始延迟时间(ms) */
+    initialDelay?: number;
+    /** 最大延迟时间(ms) */
+    maxDelay?: number;
+    /** 延迟倍数 */
+    backoffMultiplier?: number;
+}
 /**
  * Client 初始化配置
  */
@@ -295,12 +326,39 @@ declare class Client {
         /**
          * 批量部门 ID 交换
          * @param params 请求参数
-         * @returns 所有子请求的返回结果数组
+         * @returns 批量操作结果，包含成功和失败的详细信息
          */
         batchExchange: (params: {
             department_id_type: "department_id" | "external_department_id" | "external_open_department_id";
             department_ids: string[];
-        }) => Promise<any[]>;
+            retryOptions?: RetryOptions;
+        }) => Promise<BatchResult<any>>;
+    };
+    /**
+     * 用户 ID 交换模块
+     */
+    user: {
+        /**
+         * 单个用户 ID 交换
+         * @param params 请求参数
+         * @returns 单个用户映射结果
+         */
+        exchange: (params: {
+            user_id_type: "user_id" | "external_user_id" | "external_open_id";
+            user_id: string;
+            feishu_app_id: string;
+        }) => Promise<any>;
+        /**
+         * 批量用户 ID 交换
+         * @param params 请求参数
+         * @returns 批量操作结果，包含成功和失败的详细信息
+         */
+        batchExchange: (params: {
+            user_id_type: "user_id" | "external_user_id" | "external_open_id";
+            user_ids: string[];
+            feishu_app_id: string;
+            retryOptions?: RetryOptions;
+        }) => Promise<BatchResult<any>>;
     };
     /**
      * 云函数模块
@@ -549,4 +607,4 @@ declare class Client {
 export declare const apaas: {
     Client: typeof Client;
 };
-export {};
+export type { BatchResult, RetryOptions };

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "apaas-oapi-client",
-    "version": "0.1.29",
+    "version": "0.1.31",
     "main": "dist/index.js",
     "exports": {
         ".": "./dist/index.js",

package/src/index.ts

@@ -1,8 +1,121 @@
 import dayjs from 'dayjs';
-import axios, { AxiosInstance } from 'axios';
+import axios, { AxiosInstance, AxiosError } from 'axios';
 import { LoggerLevel } from './logger';
 import { functionLimiter } from './limiter';
 
+/**
+ * 批量操作结果
+ */
+interface BatchResult<T> {
+    /** 成功的项 */
+    success: T[];
+    /** 失败的项 */
+    failed: Array<{ id: string; error: string }>;
+    /** 成功数量 */
+    successCount: number;
+    /** 失败数量 */
+    failedCount: number;
+    /** 总数 */
+    total: number;
+}
+
+/**
+ * 重试配置
+ */
+interface RetryOptions {
+    /** 最大重试次数 */
+    maxRetries?: number;
+    /** 初始延迟时间(ms) */
+    initialDelay?: number;
+    /** 最大延迟时间(ms) */
+    maxDelay?: number;
+    /** 延迟倍数 */
+    backoffMultiplier?: number;
+}
+
+/**
+ * 判断错误是否可重试
+ */
+function isRetryableError(error: any): boolean {
+    // 网络错误
+    if (error.code === 'ECONNRESET' || error.code === 'ETIMEDOUT' || error.code === 'ENOTFOUND') {
+        return true;
+    }
+
+    // Axios 错误
+    if (axios.isAxiosError(error)) {
+        const axiosError = error as AxiosError;
+        // 没有响应(网络错误)
+        if (!axiosError.response) {
+            return true;
+        }
+        // 5xx 服务器错误
+        if (axiosError.response.status >= 500) {
+            return true;
+        }
+        // 429 限流
+        if (axiosError.response.status === 429) {
+            return true;
+        }
+    }
+
+    return false;
+}
+
+/**
+ * 带重试的函数执行
+ */
+async function executeWithRetry<T>(
+    fn: () => Promise<T>,
+    options: RetryOptions = {},
+    logContext: string = '',
+    logger?: (level: LoggerLevel, ...args: any[]) => void
+): Promise<T> {
+    const {
+        maxRetries = 3,
+        initialDelay = 1000,
+        maxDelay = 10000,
+        backoffMultiplier = 2
+    } = options;
+
+    let lastError: any;
+
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+        try {
+            return await fn();
+        } catch (error) {
+            lastError = error;
+
+            // 最后一次尝试，直接抛出
+            if (attempt === maxRetries) {
+                break;
+            }
+
+            // 判断是否可重试
+            if (!isRetryableError(error)) {
+                throw error;
+            }
+
+            // 计算延迟时间(指数退避)
+            const delay = Math.min(initialDelay * Math.pow(backoffMultiplier, attempt), maxDelay);
+
+            if (logger) {
+                logger(
+                    LoggerLevel.warn,
+                    `${logContext} Attempt ${attempt + 1}/${maxRetries + 1} failed, retrying in ${delay}ms...`,
+                    error instanceof Error ? error.message : String(error)
+                );
+            }
+
+            // 等待后重试
+            await new Promise(resolve => setTimeout(resolve, delay));
+        }
+    }
+
+    // 所有重试都失败
+    throw lastError;
+}
+
 /**
  * Client 初始化配置
  */
@@ -894,10 +1007,14 @@ class Client {
         /**
          * 批量部门 ID 交换
          * @param params 请求参数
-         * @returns 所有子请求的返回结果数组
+         * @returns 批量操作结果，包含成功和失败的详细信息
          */
-        batchExchange: async (params: { department_id_type: 'department_id' | 'external_department_id' | 'external_open_department_id'; department_ids: string[] }): Promise<any[]> => {
-            const { department_id_type, department_ids } = params;
+        batchExchange: async (params: {
+            department_id_type: 'department_id' | 'external_department_id' | 'external_open_department_id';
+            department_ids: string[];
+            retryOptions?: RetryOptions;
+        }): Promise<BatchResult<any>> => {
+            const { department_id_type, department_ids, retryOptions } = params;
             // department_id_type 可选值：
             // - 'department_id' (如 "1758534140403815")
             // - 'external_department_id' (外部平台 department_id, 无固定格式)
@@ -908,15 +1025,15 @@ class Client {
                 this.log(LoggerLevel.error, '[department.batchExchange] Invalid department_ids parameter: must be a non-empty array');
                 throw new Error('参数 department_ids 必须是一个数组');
             }
-            
+
             if (department_ids.length === 0) {
                 this.log(LoggerLevel.warn, '[department.batchExchange] Empty department_ids array provided, returning empty result');
-                return [];
+                return { success: [], failed: [], successCount: 0, failedCount: 0, total: 0 };
             }
 
             const url = '/api/integration/v2/feishu/getDepartments';
 
-            const chunkSize = 100;
+            const chunkSize = 200; // 最大支持200个
             const chunks: string[][] = [];
             for (let i = 0; i < department_ids.length; i += chunkSize) {
                 chunks.push(department_ids.slice(i, i + chunkSize));
@@ -924,39 +1041,231 @@ class Client {
 
             this.log(LoggerLevel.info, `[department.batchExchange] Chunking ${department_ids.length} department IDs into ${chunks.length} groups of ${chunkSize}`);
 
-            const results: any[] = [];
+            const successResults: any[] = [];
+            const failedResults: Array<{ id: string; error: string }> = [];
+
             for (const [index, chunk] of chunks.entries()) {
                 this.log(LoggerLevel.info, `[department.batchExchange] Processing chunk ${index + 1}/${chunks.length}: ${chunk.length} IDs`);
 
-                const res = await functionLimiter(async () => {
-                    await this.ensureTokenValid();
+                try {
+                    const res = await executeWithRetry(
+                        async () => {
+                            return await functionLimiter(async () => {
+                                await this.ensureTokenValid();
+
+                                const response = await this.axiosInstance.post(
+                                    url,
+                                    {
+                                        department_id_type,
+                                        department_ids: chunk
+                                    },
+                                    {
+                                        headers: { Authorization: `${this.accessToken}` },
+                                        timeout: 30000 // 30秒超时
+                                    }
+                                );
+
+                                this.log(LoggerLevel.debug, `[department.batchExchange] Chunk ${index + 1} completed: code=${response.data.code}`);
+                                this.log(LoggerLevel.trace, `[department.batchExchange] Chunk ${index + 1} response: ${JSON.stringify(response.data)}`);
+
+                                if (response.data.code !== '0') {
+                                    this.log(LoggerLevel.error, `[department.batchExchange] Error exchanging departments: code=${response.data.code}, msg=${response.data.msg}`);
+                                    throw new Error(response.data.msg || `Exchange failed with code ${response.data.code}`);
+                                }
 
-                    const response = await this.axiosInstance.post(
-                        url,
-                        {
-                            department_id_type,
-                            department_ids: chunk
+                                return response.data.data || [];
+                            });
                         },
-                        {
-                            headers: { Authorization: `${this.accessToken}` }
-                        }
+                        retryOptions,
+                        `[department.batchExchange] Chunk ${index + 1}/${chunks.length}`,
+                        this.log.bind(this)
                     );
 
-                    this.log(LoggerLevel.debug, `[department.batchExchange] Chunk ${index + 1} completed: code=${response.data.code}`);
-                    this.log(LoggerLevel.trace, `[department.batchExchange] Chunk ${index + 1} response: ${JSON.stringify(response.data)}`);
+                    successResults.push(...res);
+                    this.log(LoggerLevel.info, `[department.batchExchange] Chunk ${index + 1} succeeded: ${res.length} departments`);
+                } catch (error) {
+                    // 部分失败：记录失败的chunk
+                    const errorMsg = error instanceof Error ? error.message : String(error);
+                    this.log(LoggerLevel.error, `[department.batchExchange] Chunk ${index + 1} failed after retries: ${errorMsg}`);
+
+                    chunk.forEach(id => {
+                        failedResults.push({
+                            id,
+                            error: errorMsg
+                        });
+                    });
+                }
+            }
+
+            const result: BatchResult<any> = {
+                success: successResults,
+                failed: failedResults,
+                successCount: successResults.length,
+                failedCount: failedResults.length,
+                total: department_ids.length
+            };
+
+            this.log(LoggerLevel.info, `[department.batchExchange] Completed: total=${result.total}, success=${result.successCount}, failed=${result.failedCount}`);
+
+            return result;
+        }
+    };
+
+    /**
+     * 用户 ID 交换模块
+     */
+    public user = {
+        /**
+         * 单个用户 ID 交换
+         * @param params 请求参数
+         * @returns 单个用户映射结果
+         */
+        exchange: async (params: { user_id_type: 'user_id' | 'external_user_id' | 'external_open_id'; user_id: string; feishu_app_id: string }): Promise<any> => {
+            const { user_id_type, user_id, feishu_app_id } = params;
+            // user_id_type 可选值：
+            // - 'user_id' (如 "1758534140403815")
+            // - 'external_user_id' (外部平台 user_id, 无固定格式)
+            // - 'external_open_id' (以 'ou_' 开头的 open_id)
+
+            const url = '/api/integration/v2/feishu/getUsers';
+
+            this.log(LoggerLevel.info, `[user.exchange] Exchanging user ID: ${user_id}`);
 
-                    if (response.data.code !== '0') {
-                        this.log(LoggerLevel.error, `[department.batchExchange] Error exchanging departments: code=${response.data.code}, msg=${response.data.msg}`);
-                        throw new Error(response.data.msg || `Exchange failed with code ${response.data.code}`);
+            const res = await functionLimiter(async () => {
+                await this.ensureTokenValid();
+
+                const response = await this.axiosInstance.post(
+                    url,
+                    {
+                        user_id_type,
+                        feishu_app_id,
+                        user_ids: [user_id]
+                    },
+                    {
+                        headers: { Authorization: `${this.accessToken}` }
                     }
+                );
 
-                    return response.data.data || [];
-                });
+                this.log(LoggerLevel.debug, `[user.exchange] User ID exchanged: ${user_id}, code=${response.data.code}`);
+                this.log(LoggerLevel.trace, `[user.exchange] Response: ${JSON.stringify(response.data)}`);
+
+                if (response.data.code !== '0') {
+                    this.log(LoggerLevel.error, `[user.exchange] Error exchanging user: code=${response.data.code}, msg=${response.data.msg}`);
+                    throw new Error(response.data.msg || `Exchange failed with code ${response.data.code}`);
+                }
+
+                return response.data.data && response.data.data[0]; // 返回第一个元素
+            });
+
+            return res;
+        },
 
-                results.push(...res);
+        /**
+         * 批量用户 ID 交换
+         * @param params 请求参数
+         * @returns 批量操作结果，包含成功和失败的详细信息
+         */
+        batchExchange: async (params: {
+            user_id_type: 'user_id' | 'external_user_id' | 'external_open_id';
+            user_ids: string[];
+            feishu_app_id: string;
+            retryOptions?: RetryOptions;
+        }): Promise<BatchResult<any>> => {
+            const { user_id_type, user_ids, feishu_app_id, retryOptions } = params;
+            // user_id_type 可选值：
+            // - 'user_id' (如 "1758534140403815")
+            // - 'external_user_id' (外部平台 user_id, 无固定格式)
+            // - 'external_open_id' (以 'ou_' 开头的 open_id)
+
+            // 参数校验
+            if (!user_ids || !Array.isArray(user_ids)) {
+                this.log(LoggerLevel.error, '[user.batchExchange] Invalid user_ids parameter: must be a non-empty array');
+                throw new Error('参数 user_ids 必须是一个数组');
+            }
+
+            if (user_ids.length === 0) {
+                this.log(LoggerLevel.warn, '[user.batchExchange] Empty user_ids array provided, returning empty result');
+                return { success: [], failed: [], successCount: 0, failedCount: 0, total: 0 };
+            }
+
+            const url = '/api/integration/v2/feishu/getUsers';
+
+            const chunkSize = 200; // 最大支持200个
+            const chunks: string[][] = [];
+            for (let i = 0; i < user_ids.length; i += chunkSize) {
+                chunks.push(user_ids.slice(i, i + chunkSize));
+            }
+
+            this.log(LoggerLevel.info, `[user.batchExchange] Chunking ${user_ids.length} user IDs into ${chunks.length} groups of ${chunkSize}`);
+
+            const successResults: any[] = [];
+            const failedResults: Array<{ id: string; error: string }> = [];
+
+            for (const [index, chunk] of chunks.entries()) {
+                this.log(LoggerLevel.info, `[user.batchExchange] Processing chunk ${index + 1}/${chunks.length}: ${chunk.length} IDs`);
+
+                try {
+                    const res = await executeWithRetry(
+                        async () => {
+                            return await functionLimiter(async () => {
+                                await this.ensureTokenValid();
+
+                                const response = await this.axiosInstance.post(
+                                    url,
+                                    {
+                                        user_id_type,
+                                        feishu_app_id,
+                                        user_ids: chunk
+                                    },
+                                    {
+                                        headers: { Authorization: `${this.accessToken}` },
+                                        timeout: 30000 // 30秒超时
+                                    }
+                                );
+
+                                this.log(LoggerLevel.debug, `[user.batchExchange] Chunk ${index + 1} completed: code=${response.data.code}`);
+                                this.log(LoggerLevel.trace, `[user.batchExchange] Chunk ${index + 1} response: ${JSON.stringify(response.data)}`);
+
+                                if (response.data.code !== '0') {
+                                    this.log(LoggerLevel.error, `[user.batchExchange] Error exchanging users: code=${response.data.code}, msg=${response.data.msg}`);
+                                    throw new Error(response.data.msg || `Exchange failed with code ${response.data.code}`);
+                                }
+
+                                return response.data.data || [];
+                            });
+                        },
+                        retryOptions,
+                        `[user.batchExchange] Chunk ${index + 1}/${chunks.length}`,
+                        this.log.bind(this)
+                    );
+
+                    successResults.push(...res);
+                    this.log(LoggerLevel.info, `[user.batchExchange] Chunk ${index + 1} succeeded: ${res.length} users`);
+                } catch (error) {
+                    // 部分失败：记录失败的chunk
+                    const errorMsg = error instanceof Error ? error.message : String(error);
+                    this.log(LoggerLevel.error, `[user.batchExchange] Chunk ${index + 1} failed after retries: ${errorMsg}`);
+
+                    chunk.forEach(id => {
+                        failedResults.push({
+                            id,
+                            error: errorMsg
+                        });
+                    });
+                }
             }
 
-            return results;
+            const result: BatchResult<any> = {
+                success: successResults,
+                failed: failedResults,
+                successCount: successResults.length,
+                failedCount: failedResults.length,
+                total: user_ids.length
+            };
+
+            this.log(LoggerLevel.info, `[user.batchExchange] Completed: total=${result.total}, success=${result.successCount}, failed=${result.failedCount}`);
+
+            return result;
         }
     };
 
@@ -1628,3 +1937,5 @@ class Client {
 export const apaas = {
     Client
 };
+
+export type { BatchResult, RetryOptions };