apaas-oapi-client 0.1.40 → 1.0.0

package/README.md

@@ -15,15 +15,18 @@
 - ✅ records 查询（支持分页迭代）
 - ✅ record 单条查询、单条更新、单条删除
 - ✅ record 批量创建、批量更新、批量删除
+- ✅ OQL、跨对象搜索、常量对象、数据集列表
 
 ### 对象结构管理（Schema）
 - ✅ **创建数据对象**（批量）
 - ✅ **更新数据对象**（批量，支持添加/修改/删除字段）
 - ✅ **删除数据对象**（批量）
+- ✅ **AI 友好的安全编排接口**（响应校验、幂等加字段、三阶段建对象、依赖顺序删除）
 - ✅ **字段类型完整文档**（20+ 字段类型，含示例）
 
 ### 其他功能
 - ✅ 获取 accessToken（自动刷新）
+- ✅ 工作流人工任务、异步流程状态、飞书集成 token
 - ✅ **导出数据对象文档为 Markdown**
 - ✅ 内置 Bottleneck 限流器
 - ✅ 自定义日志等级
@@ -36,10 +39,10 @@
 
 | Skill | 适用场景 |
 | --- | --- |
-| `apaas-shared` | Client 初始化、凭证安全、namespace、token、日志、分页与错误处理 |
-| `apaas-object` | 对象列表、字段元数据、记录查询/创建/更新/删除、Markdown 导出 |
+| `apaas-shared` | Client 初始化、凭证安全、namespace、token、日志、OpenAPI 覆盖、分页与错误码处理 |
+| `apaas-object` | 对象列表、字段元数据、记录查询/创建/更新/删除、OQL、跨对象搜索、常量对象、数据集 |
 | `apaas-schema` | 对象和字段结构管理、字段类型映射、lookup/reference 依赖规则 |
-| `apaas-function-flow` | 云函数调用、自动化流程 v1/v2 执行 |
+| `apaas-function-flow` | 云函数调用、自动化流程 v1/v2 执行、工作流人工任务、飞书集成 token |
 | `apaas-builder` | 页面列表、页面详情、页面访问链接 |
 | `apaas-global` | 全局选项、环境变量读取与审计 |
 | `apaas-exchange-attachment` | 用户/部门 ID 交换、附件和头像上传下载 |
@@ -85,6 +88,7 @@ cp -R node_modules/apaas-oapi-client/skills/apaas-* "${CODEX_HOME:-$HOME/.codex}
 使用建议：
 
 - 写入前先用 `apaas-object` 读取真实 metadata。
+- 大量读取优先使用 iterator 或 `apaas-object/references/id-cursor-pagination.md`。
 - Schema 字段变更前先读 `apaas-schema/references/field-schema-rules.md`。
 - 删除、批量写入、流程执行都按写操作处理，先确认目标和影响。
 
@@ -113,8 +117,8 @@ const client = new apaas.Client({
 
 await client.init();
 
-// 创建数据对象
-await client.schema.create({
+// 安全创建数据对象：空壳 -> 基础字段 -> lookup -> reference_field -> final settings
+await client.schema.createWithStages({
     objects: [{
         api_name: 'product',
         label: { zh_cn: '产品', en_us: 'Product' },
@@ -124,9 +128,19 @@ await client.schema.create({
         },
         fields: [
             {
+                operator: 'add',
                 api_name: 'code',
                 label: { zh_cn: '编号', en_us: 'Code' },
-                type: { name: 'text', settings: { required: true } },
+                type: {
+                    name: 'text',
+                    settings: {
+                        required: true,
+                        unique: false,
+                        case_sensitive: false,
+                        multiline: false,
+                        max_length: 100
+                    }
+                },
                 encrypt_type: 'none'
             }
         ]
@@ -141,11 +155,23 @@ await client.schema.update({
             operator: 'add',  // 添加新字段
             api_name: 'name',
             label: { zh_cn: '名称', en_us: 'Name' },
-            type: { name: 'text', settings: { required: true } },
+            type: {
+                name: 'text',
+                settings: {
+                    required: true,
+                    unique: false,
+                    case_sensitive: false,
+                    multiline: false,
+                    max_length: 100
+                }
+            },
             encrypt_type: 'none'
         }]
     }]
 });
+
+// 三层响应校验：请求级错误、data=null 静默失败、item 级失败
+client.schema.checkResponse({ code: '0', data: { items: [] } }, 'schema.update');
 ```
 
 ---

package/UserManual.md

@@ -14,6 +14,10 @@ aPaaS 平台有完整的 Open API 能力，但是目前这些能力全都以单
 - ✅ record 单条更新、批量更新
 	
 - ✅ record 单条删除、批量删除
+
+- ✅ OQL、跨对象搜索、常量对象、数据集列表
+
+- ✅ 工作流人工任务、异步流程状态、飞书集成 token
 	
 - ✅ 内置 Bottleneck 限流器，基于 API 接口配置限流规则
 	
@@ -171,6 +175,32 @@ console.log('Items:', items);
 
 ***
 
+### **执行 OQL**
+
+```JavaScript
+const res = await client.object.oql({
+  query: 'SELECT _id, _name FROM _user WHERE _type = $1 LIMIT 10',
+  args: ['_employee']
+});
+console.log(res);
+```
+
+### **跨对象搜索**
+
+```JavaScript
+const res = await client.object.search.recordsAcrossObjects({
+  q: 'Ethan',
+  search_objects: [{
+    api_name: '_user',
+    select: ['_id', '_name'],
+    search_fields: ['_name']
+  }],
+  page_size: 20,
+  metadata: 'Label'
+});
+console.log(res);
+```
+
 
 
 
@@ -378,6 +408,40 @@ console.log('✅ 文档导出成功！');
 
 ***
 
+# **🧩 常量对象与数据集**
+
+## **常量对象**
+
+支持 `_currency`、`_country`、`_timeZone`。
+
+```JavaScript
+const currencies = await client.constant.records({
+  object_name: '_currency',
+  data: {
+    limit: 100,
+    offset: 0,
+    count: false,
+    fields: ['_id', '_name']
+  }
+});
+
+const country = await client.constant.record({
+  object_name: '_country',
+  record_id: 'CN'
+});
+```
+
+## **数据集**
+
+```JavaScript
+const datasets = await client.dataset.listWithIterator({
+  page_size: 100
+});
+console.log(datasets);
+```
+
+***
+
 
 
 # **📎 附件模块**
@@ -636,6 +700,56 @@ console.log(res);
 // 返回: { code: "0", msg: "success", data: { errMsg, executionId, status, data, errCode } }
 ```
 
+## **查询异步流程状态**
+
+```JavaScript
+const status = await client.workflow.execution.status({
+  execution_id: '1848390852196499'
+});
+console.log(status);
+```
+
+## **获取流程定义详情**
+
+```JavaScript
+const flow = await client.workflow.definition.detail({
+  flow_api_name: 'package_xxx__c__action_xxx'
+});
+console.log(flow);
+```
+
+## **人工任务**
+
+```JavaScript
+const tasks = await client.workflow.userTask.tasks({
+  type: 'pending',
+  source: 'assignMe',
+  kunlun_user_id: '1783981209205788',
+  limit: 20,
+  offset: 0
+});
+
+await client.workflow.userTask.agree({
+  approval_task_id: '1785996265147395',
+  user_id: '1783981209205788',
+  opinion: '同意'
+});
+```
+
+***
+
+# **🔗 集成模块**
+
+## **飞书集成 Token**
+
+```JavaScript
+const tenantToken = await client.integration.lark.defaultTenantAccessToken();
+
+const appToken = await client.integration.lark.appAccessToken({
+  lark_integration_api_name: 'larkIntegration_xxx'
+});
+```
+
 ***
 
 <br>
@@ -693,4 +807,4 @@ console.log(client.currentNamespace);
 
 > 由 [aPaaS OAPI Client SDK](https://www.npmjs.com/package/apaas-oapi-client) 提供支持，如有问题请提交 Issue 反馈。
 
----
+---

package/dist/field-schema-rules.d.ts

@@ -19,7 +19,12 @@ export interface FieldCreateRule {
 export declare const SCHEMA_TYPE_BY_METADATA_TYPE: Record<MetadataFieldType, SchemaFieldType>;
 export declare const OPTION_COLOR_LIST: readonly ["blue", "cyan", "green", "yellow", "orange", "red", "magenta", "purple", "blueMagenta", "grey"];
 export type OptionColor = typeof OPTION_COLOR_LIST[number];
+export declare const OPTION_COLOR_CODE_BY_NAME: Record<OptionColor, string>;
+export declare const OPTION_COLOR_NAME_BY_CODE: Record<string, OptionColor>;
+export type OptionColorCode = typeof OPTION_COLOR_CODE_BY_NAME[OptionColor];
 export declare function getOptionColor(index: number): OptionColor;
+export declare function getOptionColorCode(color: OptionColor): OptionColorCode;
+export declare function normalizeOptionColorForSchema(color: unknown): unknown;
 export declare const OPTION_COLOR_RULES: {
     readonly allowedColors: readonly ["blue", "cyan", "green", "yellow", "orange", "red", "magenta", "purple", "blueMagenta", "grey"];
     readonly assignment: "Use OPTION_COLOR_LIST in order and cycle from the beginning when options exceed 10.";
@@ -40,6 +45,8 @@ export declare const OPTION_COLOR_RULES: {
         readonly typeName: "enum";
         readonly optionsPath: "type.settings.options";
         readonly colorPath: "type.settings.options[].color";
+        readonly colorInput: "SDK accepts metadata color names and normalizes them to OpenAPI color codes before writing.";
+        readonly colorCodeByName: Record<"blue" | "cyan" | "green" | "yellow" | "orange" | "red" | "magenta" | "purple" | "blueMagenta" | "grey", string>;
         readonly sourcePath: "type.settings.option_source";
         readonly globalOptionPath: "type.settings.global_option_api_name";
     };
@@ -49,6 +56,35 @@ export declare const SCHEMA_TYPE_MISMATCHES: Array<{
     metadataType: MetadataFieldType;
     schemaType: SchemaFieldType;
 }>;
+export interface SqlTypeMapping {
+    /** SQL type regex pattern, case-insensitive. */
+    sqlPattern: string;
+    /** Mapped aPaaS schema type. */
+    schemaType: SchemaFieldType;
+    /** Settings derivation rule. */
+    settingsMapping: string;
+}
+export declare const SQL_TYPE_TO_SCHEMA_TYPE: SqlTypeMapping[];
+export interface ColumnNameSemanticRule {
+    /** Column name regex pattern, case-insensitive. */
+    columnPattern: string;
+    /** Inferred aPaaS schema type. */
+    schemaType: SchemaFieldType;
+    /** Inference notes. */
+    notes: string;
+}
+export declare const COLUMN_NAME_SEMANTIC_RULES: ColumnNameSemanticRule[];
+export interface SqlConstraintMapping {
+    /** SQL constraint. */
+    sqlConstraint: string;
+    /** Mapped aPaaS settings field. */
+    settingsField: string;
+    /** Mapped value. */
+    settingsValue: string;
+    /** Mapping notes. */
+    notes: string;
+}
+export declare const SQL_CONSTRAINT_TO_SETTINGS: SqlConstraintMapping[];
 export declare const BATCH_UPDATE_REQUIREMENTS: {
     readonly add: "Use operator=add with full field definition.";
     readonly replace: "Use operator=replace and include full `type` (name + settings). Label-only replace fails.";

package/dist/field-types.d.ts

@@ -80,8 +80,8 @@ export interface CreateObjectDefinition {
     label: MultilingualText;
     /** 对象设置（可选） */
     settings?: ObjectSettings;
-    /** 字段列表（必填，至少包含一个自定义字段） */
-    fields: CreateFieldDefinition[];
+    /** 字段列表（可选）。schema.create 会忽略 fields，安全做法是先建空壳，再用 schema.update 添加字段。 */
+    fields?: CreateFieldDefinition[];
 }
 /**
  * 更新对象的定义