apaas-oapi-client 0.1.30 → 0.1.32

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 客户端
  */
@@ -61,11 +119,14 @@ class Client {
         this.object = {
             /**
              * 列出所有对象（数据表）
-             * @param params 请求参数 { offset, filter?, limit }
-             * @returns 接口返回结果
+             * @param params 请求参数 { offset?, filter?, limit? }
+             * @returns 接口返回结果，包含 has_more 字段表示是否还有更多数据
              */
             list: async (params) => {
-                const { offset, filter, limit } = params;
+                var _a, _b;
+                const offset = (_a = params === null || params === void 0 ? void 0 : params.offset) !== null && _a !== void 0 ? _a : 0;
+                const limit = (_b = params === null || params === void 0 ? void 0 : params.limit) !== null && _b !== void 0 ? _b : 50;
+                const filter = params === null || params === void 0 ? void 0 : params.filter;
                 await this.ensureTokenValid();
                 const url = `/api/data/v1/namespaces/${this.namespace}/meta/objects/list`;
                 this.log(LoggerLevel.debug, `[object.list] Fetching objects list: offset=${offset}, limit=${limit}`);
@@ -78,8 +139,66 @@ class Client {
                 });
                 this.log(LoggerLevel.debug, `[object.list] Objects list fetched successfully: code=${res.data.code}`);
                 this.log(LoggerLevel.trace, `[object.list] Response: ${JSON.stringify(res.data)}`);
+                // 添加 has_more 字段判断是否还有更多数据
+                if (res.data && res.data.data) {
+                    const total = res.data.data.total || 0;
+                    const currentEnd = offset + limit;
+                    res.data.has_more = currentEnd < total;
+                    this.log(LoggerLevel.debug, `[object.list] has_more=${res.data.has_more}, total=${total}, currentEnd=${currentEnd}`);
+                }
                 return res.data;
             },
+            /**
+             * 列出所有对象（数据表）- 支持自动分页查询
+             * @description 该方法会自动处理分页，直到没有更多数据为止
+             * @param params 请求参数 { filter?, limit? }
+             * @returns { total, items }
+             */
+            listWithIterator: async (params) => {
+                var _a, _b, _c, _d;
+                const filter = params === null || params === void 0 ? void 0 : params.filter;
+                const limit = (_a = params === null || params === void 0 ? void 0 : params.limit) !== null && _a !== void 0 ? _a : 50;
+                let results = [];
+                let offset = 0;
+                let total = 0;
+                let hasMore = true;
+                let page = 0;
+                let totalPages = 0;
+                this.log(LoggerLevel.info, `[object.listWithIterator] Starting paginated query with limit=${limit}`);
+                while (hasMore) {
+                    const res = await this.object.list({
+                        offset,
+                        limit,
+                        filter
+                    });
+                    if (res.code !== '0') {
+                        this.log(LoggerLevel.error, `[object.listWithIterator] Error querying objects: code=${res.code}, msg=${res.msg}`);
+                        throw new Error(res.msg || `Query failed with code ${res.code}`);
+                    }
+                    page += 1;
+                    if (res.data && Array.isArray(res.data.items)) {
+                        results = results.concat(res.data.items);
+                    }
+                    if (res.data && (res.data.total !== undefined && res.data.total !== null)) {
+                        total = res.data.total;
+                    }
+                    if (page === 1) {
+                        totalPages = Math.ceil(total / limit);
+                        this.log(LoggerLevel.info, `[object.listWithIterator] Total objects: ${total}, pages: ${totalPages}`);
+                    }
+                    // 判断是否还有更多数据
+                    hasMore = res.has_more === true;
+                    offset += limit;
+                    const padLength = totalPages.toString().length;
+                    const pageStr = page.toString().padStart(padLength, '0');
+                    const totalPagesStr = totalPages.toString().padStart(padLength, '0');
+                    this.log(LoggerLevel.info, `[object.listWithIterator] Page completed: [${pageStr}/${totalPagesStr}]`);
+                    this.log(LoggerLevel.debug, `[object.listWithIterator] Page ${page} details: items=${(_c = (_b = res.data) === null || _b === void 0 ? void 0 : _b.items) === null || _c === void 0 ? void 0 : _c.length}, hasMore=${hasMore}`);
+                    this.log(LoggerLevel.trace, `[object.listWithIterator] Page ${page} data: ${JSON.stringify((_d = res.data) === null || _d === void 0 ? void 0 : _d.items)}`);
+                }
+                this.log(LoggerLevel.info, `[object.listWithIterator] Completed: total=${total}, fetched=${results.length}`);
+                return { total, items: results };
+            },
             metadata: {
                 /**
                  * 获取指定对象下指定字段的元数据
@@ -214,6 +333,45 @@ class Client {
                         });
                     }
                     return { total, items: results };
+                },
+                /**
+                 * 统计记录数量
+                 * @description 统计指定对象中的记录总数，支持按条件统计
+                 * @param params 请求参数 { object_name, data? }
+                 * @returns 接口返回结果 { code, total, msg }
+                 */
+                count: async (params) => {
+                    var _a;
+                    const { object_name, data } = params;
+                    // 默认查询参数：最小化数据传输，只获取总数
+                    const defaultData = {
+                        offset: 0,
+                        page_size: 1,
+                        need_total_count: true,
+                        use_page_token: true,
+                        select: ['_id'],
+                        query_deleted_record: false
+                    };
+                    // 合并用户传入的参数（用户参数优先）
+                    const queryData = data ? { ...defaultData, ...data } : defaultData;
+                    this.log(LoggerLevel.info, `[object.search.count] Counting records in: ${object_name}`);
+                    this.log(LoggerLevel.debug, `[object.search.count] Query data: ${JSON.stringify(queryData)}`);
+                    const res = await this.object.search.records({
+                        object_name,
+                        data: queryData
+                    });
+                    if (res.code !== '0') {
+                        this.log(LoggerLevel.error, `[object.search.count] Error counting records: code=${res.code}, msg=${res.msg}`);
+                        throw new Error(res.msg || `Count failed with code ${res.code}`);
+                    }
+                    const total = ((_a = res.data) === null || _a === void 0 ? void 0 : _a.total) || 0;
+                    this.log(LoggerLevel.info, `[object.search.count] Total records in ${object_name}: ${total}`);
+                    // 返回格式：{ code, total, msg }
+                    return {
+                        code: res.code,
+                        total: total,
+                        msg: res.msg
+                    };
                 }
             },
             create: {
@@ -631,10 +789,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 +804,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 初始化配置
  */
@@ -71,17 +102,33 @@ declare class Client {
     object: {
         /**
          * 列出所有对象（数据表）
-         * @param params 请求参数 { offset, filter?, limit }
-         * @returns 接口返回结果
+         * @param params 请求参数 { offset?, filter?, limit? }
+         * @returns 接口返回结果，包含 has_more 字段表示是否还有更多数据
          */
-        list: (params: {
-            offset: number;
+        list: (params?: {
+            offset?: number;
             filter?: {
                 type?: string;
                 quickQuery?: string;
             };
-            limit: number;
+            limit?: number;
         }) => Promise<any>;
+        /**
+         * 列出所有对象（数据表）- 支持自动分页查询
+         * @description 该方法会自动处理分页，直到没有更多数据为止
+         * @param params 请求参数 { filter?, limit? }
+         * @returns { total, items }
+         */
+        listWithIterator: (params?: {
+            filter?: {
+                type?: string;
+                quickQuery?: string;
+            };
+            limit?: number;
+        }) => Promise<{
+            total: number;
+            items: any[];
+        }>;
         metadata: {
             /**
              * 获取指定对象下指定字段的元数据
@@ -138,6 +185,16 @@ declare class Client {
                 total: number;
                 items: any[];
             }>;
+            /**
+             * 统计记录数量
+             * @description 统计指定对象中的记录总数，支持按条件统计
+             * @param params 请求参数 { object_name, data? }
+             * @returns 接口返回结果 { code, total, msg }
+             */
+            count: (params: {
+                object_name: string;
+                data?: any;
+            }) => Promise<any>;
         };
         create: {
             /**
@@ -295,12 +352,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 +633,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.30",
+    "version": "0.1.32",
     "main": "dist/index.js",
     "exports": {
         ".": "./dist/index.js",