apaas-oapi-client 0.1.35 → 0.1.37

package/dist/index.d.ts

@@ -1,4 +1,36 @@
 import { LoggerLevel } from './logger';
+import { FIELD_TYPES, SYSTEM_FIELDS, LANGUAGE_CODES, SCHEMA_GUIDELINES, CREATE_OBJECT_EXAMPLE, UPDATE_OBJECT_ADD_FIELD_EXAMPLE, UPDATE_OBJECT_REPLACE_FIELD_EXAMPLE, UPDATE_OBJECT_REMOVE_FIELD_EXAMPLE, UPDATE_OBJECT_SETTINGS_EXAMPLE, getSystemFields, getCustomFieldTypes, getFieldType, isSystemField, createMultilingualText, extractMultilingualText, type FieldTypeMetadata, type MultilingualText, type ObjectSettings, type FieldTypeDefinition, type EncryptType, type FieldOperator, type CreateFieldDefinition, type UpdateFieldDefinition, type CreateObjectDefinition, type UpdateObjectDefinition } from './field-types';
+/**
+ * 批量操作结果
+ */
+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 +103,41 @@ declare class Client {
     object: {
         /**
          * 列出所有对象（数据表）
-         * @param params 请求参数 { offset, filter?, limit }
-         * @returns 接口返回结果
+         * @param params 请求参数 { offset?, filter?, limit? }
+         * @returns 接口返回结果 { code, items, total, msg, 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 { code, msg, items, total, failed? } - code 表示失败的分页数量
+         */
+        listWithIterator: (params?: {
+            filter?: {
+                type?: string;
+                quickQuery?: string;
+            };
+            limit?: number;
+        }) => Promise<{
+            code: string;
+            msg: string;
+            items: any[];
+            total: number;
+            failed?: Array<{
+                offset: number;
+                limit: number;
+                code: string;
+                msg: string;
+            }>;
+        }>;
         metadata: {
             /**
              * 获取指定对象下指定字段的元数据
@@ -102,6 +158,36 @@ declare class Client {
             fields: (params: {
                 object_name: string;
             }) => Promise<any>;
+            /**
+             * 导出数据对象元数据为 Markdown 文档
+             * @description 将数据对象的字段信息导出为详细的 Markdown 文档，包含字段类型、配置、选项等完整信息
+             * @param options 导出配置
+             * @param options.object_names 可选，要导出的对象名称数组。如果不传，则导出所有对象
+             * @returns Markdown 文档字符串
+             * @example
+             * ```typescript
+             * // 导出所有对象
+             * const markdown = await client.object.metadata.export2markdown();
+             *
+             * // 只导出指定对象
+             * const markdown = await client.object.metadata.export2markdown({
+             *   object_names: ['object_store', 'object_order', '_user']
+             * });
+             *
+             * // 结合 listWithIterator 使用
+             * const allObjects = await client.object.listWithIterator();
+             * const objectNames = allObjects.items.map(obj => obj.apiName);
+             * const markdown = await client.object.metadata.export2markdown({
+             *   object_names: objectNames
+             * });
+             *
+             * // 保存到文件
+             * fs.writeFileSync('objects_doc.md', markdown, 'utf-8');
+             * ```
+             */
+            export2markdown: (options?: {
+                object_names?: string[];
+            }) => Promise<string>;
         };
         search: {
             /**
@@ -138,6 +224,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: {
             /**
@@ -163,15 +259,26 @@ declare class Client {
             /**
              * 分批创建所有记录 - 支持超过 100 条数据，自动拆分
              * @description 创建多条记录到指定对象中，超过 100 条数据会自动拆分为多次请求
-             * @param params 请求参数 { object_name, records }
-             * @returns { total, items }
+             * @param params 请求参数 { object_name, records, limit }
+             * @returns { total, success, failed, successCount, failedCount }
              */
             recordsWithIterator: (params: {
                 object_name: string;
                 records: any[];
+                limit?: number;
             }) => Promise<{
                 total: number;
-                items: any[];
+                success: Array<{
+                    _id: string;
+                    success: true;
+                }>;
+                failed: Array<{
+                    _id: string;
+                    success: false;
+                    error?: string;
+                }>;
+                successCount: number;
+                failedCount: number;
             }>;
         };
         update: {
@@ -199,19 +306,33 @@ declare class Client {
             /**
              * 批量更新 - 支持超过 100 条数据，自动拆分
              * @description 更新指定对象下的多条记录，超过 100 条数据会自动拆分为多次请求
-             * @param params 请求参数
-             * @returns 所有子请求的返回结果数组
+             * @param params 请求参数，包含 object_name, records, limit
+             * @returns { total, success, failed, successCount, failedCount }
              */
             recordsWithIterator: (params: {
                 object_name: string;
                 records: any[];
-            }) => Promise<any[]>;
+                limit?: number;
+            }) => Promise<{
+                total: number;
+                success: Array<{
+                    _id: string;
+                    success: true;
+                }>;
+                failed: Array<{
+                    _id: string;
+                    success: false;
+                    error?: string;
+                }>;
+                successCount: number;
+                failedCount: number;
+            }>;
         };
         delete: {
             /**
              * 单条删除
              * @description 删除指定对象下的单条记录
-             * @param params 请求参数
+             * @param params 请求参数，包含 object_name 和 record_id
              * @returns 接口返回结果
              */
             record: (params: {
@@ -221,7 +342,7 @@ declare class Client {
             /**
              * 多条删除 - 最多传入 100 条
              * @description 删除指定对象下的多条记录
-             * @param params 请求参数
+             * @param params 请求参数，包含 object_name 和 ids 数组
              * @returns 接口返回结果
              */
             records: (params: {
@@ -231,13 +352,27 @@ declare class Client {
             /**
              * 批量删除
              * @description 删除指定对象下的多条记录，超过 100 条数据会自动拆分为多次请求
-             * @param params 请求参数
-             * @returns 所有子请求的返回结果数组
+             * @param params 请求参数，包含 object_name, ids 数组 和 可选的 limit
+             * @returns { total, success, failed, successCount, failedCount }
              */
             recordsWithIterator: (params: {
                 object_name: string;
                 ids: string[];
-            }) => Promise<any[]>;
+                limit?: number;
+            }) => Promise<{
+                total: number;
+                success: Array<{
+                    _id: string;
+                    success: true;
+                }>;
+                failed: Array<{
+                    _id: string;
+                    success: false;
+                    error?: string;
+                }>;
+                successCount: number;
+                failedCount: number;
+            }>;
         };
     };
     /**
@@ -256,12 +391,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>>;
     };
     /**
      * 云函数模块
@@ -506,8 +668,140 @@ declare class Client {
             }) => Promise<any>;
         };
     };
+    /**
+     * 数据对象结构管理模块（Schema）
+     */
+    schema: {
+        /**
+         * 批量创建数据对象（表）
+         * @description 批量创建一个或多个数据对象
+         * @param params 请求参数 { objects: Array }
+         * @returns 接口返回结果
+         */
+        create: (params: {
+            objects: Array<{
+                api_name: string;
+                label: {
+                    zh_cn: string;
+                    en_us: string;
+                };
+                settings?: {
+                    allow_search_fields?: string[];
+                    display_name?: string;
+                    search_layout?: string[];
+                };
+                fields: Array<{
+                    api_name: string;
+                    label: {
+                        zh_cn: string;
+                        en_us: string;
+                    };
+                    type: {
+                        name: string;
+                        settings?: any;
+                    };
+                    encrypt_type?: string | null;
+                }>;
+            }>;
+        }) => Promise<any>;
+        /**
+         * 批量更新数据对象（表）
+         * @description 批量更新一个或多个数据对象的配置
+         * @param params 请求参数 { objects: Array }
+         * @returns 接口返回结果
+         * @example
+         * ```typescript
+         * // 添加新字段
+         * await client.schema.update({
+         *   objects: [{
+         *     api_name: 'my_object',
+         *     fields: [{
+         *       operator: 'add',
+         *       api_name: 'new_field',
+         *       label: { zh_cn: '新字段', en_us: 'New Field' },
+         *       type: { name: 'text', settings: { required: false } },
+         *       encrypt_type: 'none'
+         *     }]
+         *   }]
+         * });
+         *
+         * // 修改现有字段
+         * await client.schema.update({
+         *   objects: [{
+         *     api_name: 'my_object',
+         *     fields: [{
+         *       operator: 'replace',
+         *       api_name: 'existing_field',
+         *       label: { zh_cn: '新标签', en_us: 'New Label' }
+         *     }]
+         *   }]
+         * });
+         *
+         * // 删除字段
+         * await client.schema.update({
+         *   objects: [{
+         *     api_name: 'my_object',
+         *     fields: [{
+         *       operator: 'remove',
+         *       api_name: 'field_to_delete'
+         *     }]
+         *   }]
+         * });
+         * ```
+         */
+        update: (params: {
+            objects: Array<{
+                api_name: string;
+                label?: {
+                    zh_cn: string;
+                    en_us: string;
+                };
+                settings?: {
+                    allow_search_fields?: string[];
+                    display_name?: string;
+                    search_layout?: string[];
+                };
+                fields?: Array<{
+                    /** 操作类型：add=添加字段, replace=修改字段, remove=删除字段 */
+                    operator: "add" | "replace" | "remove";
+                    /** 字段 API 名称 */
+                    api_name: string;
+                    /** 字段标签（可选，operator=add 和 replace 时使用） */
+                    label?: {
+                        zh_cn: string;
+                        en_us: string;
+                    };
+                    /** 字段类型（可选，operator=add 和 replace 时使用） */
+                    type?: {
+                        name: string;
+                        settings?: any;
+                    };
+                    /** 加密类型（可选） */
+                    encrypt_type?: string | null;
+                }>;
+            }>;
+        }) => Promise<any>;
+        /**
+         * 批量删除数据对象（表）
+         * @description 批量删除一个或多个数据对象
+         * @param params 请求参数 { api_names: string[] }
+         * @returns 接口返回结果
+         * @example
+         * ```typescript
+         * // 删除单个对象
+         * await client.schema.delete({ api_names: ['object_abc'] });
+         *
+         * // 删除多个对象
+         * await client.schema.delete({ api_names: ['object_abc', 'object_def'] });
+         * ```
+         */
+        delete: (params: {
+            api_names: string[];
+        }) => Promise<any>;
+    };
 }
 export declare const apaas: {
     Client: typeof Client;
 };
-export {};
+export type { BatchResult, RetryOptions, FieldTypeMetadata, MultilingualText, ObjectSettings, FieldTypeDefinition, EncryptType, FieldOperator, CreateFieldDefinition, UpdateFieldDefinition, CreateObjectDefinition, UpdateObjectDefinition };
+export { FIELD_TYPES, SYSTEM_FIELDS, LANGUAGE_CODES, SCHEMA_GUIDELINES, CREATE_OBJECT_EXAMPLE, UPDATE_OBJECT_ADD_FIELD_EXAMPLE, UPDATE_OBJECT_REPLACE_FIELD_EXAMPLE, UPDATE_OBJECT_REMOVE_FIELD_EXAMPLE, UPDATE_OBJECT_SETTINGS_EXAMPLE, getSystemFields, getCustomFieldTypes, getFieldType, isSystemField, createMultilingualText, extractMultilingualText };