apaas-oapi-client 0.1.30 → 0.1.32

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 初始化配置
  */
@@ -177,11 +290,13 @@ class Client {
     public object = {
         /**
          * 列出所有对象（数据表）
-         * @param params 请求参数 { offset, filter?, limit }
-         * @returns 接口返回结果
+         * @param params 请求参数 { offset?, filter?, limit? }
+         * @returns 接口返回结果，包含 has_more 字段表示是否还有更多数据
          */
-        list: async (params: { offset: number; filter?: { type?: string; quickQuery?: string }; limit: number }): Promise<any> => {
-            const { offset, filter, limit } = params;
+        list: async (params?: { offset?: number; filter?: { type?: string; quickQuery?: string }; limit?: number }): Promise<any> => {
+            const offset = params?.offset ?? 0;
+            const limit = params?.limit ?? 50;
+            const filter = params?.filter;
             await this.ensureTokenValid();
             const url = `/api/data/v1/namespaces/${this.namespace}/meta/objects/list`;
 
@@ -198,9 +313,81 @@ 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?: { filter?: { type?: string; quickQuery?: string }; limit?: number }): Promise<{ total: number; items: any[] }> => {
+            const filter = params?.filter;
+            const limit = params?.limit ?? 50;
+            
+            let results: any[] = [];
+            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=${res.data?.items?.length}, hasMore=${hasMore}`);
+                this.log(LoggerLevel.trace, `[object.listWithIterator] Page ${page} data: ${JSON.stringify(res.data?.items)}`);
+            }
+
+            this.log(LoggerLevel.info, `[object.listWithIterator] Completed: total=${total}, fetched=${results.length}`);
+            return { total, items: results };
+        },
+
         metadata: {
             /**
              * 获取指定对象下指定字段的元数据
@@ -366,6 +553,52 @@ class Client {
                 }
 
                 return { total, items: results };
+            },
+
+            /**
+             * 统计记录数量
+             * @description 统计指定对象中的记录总数，支持按条件统计
+             * @param params 请求参数 { object_name, data? }
+             * @returns 接口返回结果 { code, total, msg }
+             */
+            count: async (params: { object_name: string; data?: any }): Promise<any> => {
+                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 = res.data?.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
+                };
             }
         },
 
@@ -894,10 +1127,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 +1145,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 +1161,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}`);
 
-                    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 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}`);
+
+            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;
+        },
+
+        /**
+         * 批量用户 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}`);
+                                }
 
-                results.push(...res);
+                                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 +2057,5 @@ class Client {
 export const apaas = {
     Client
 };
+
+export type { BatchResult, RetryOptions };