apaas-oapi-client 0.1.40 → 1.0.0

package/skills/apaas-shared/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: apaas-shared
-description: "Use for aPaaS Node SDK shared setup and safety rules: client initialization, credentials, namespace, token cache, logger level, pagination defaults, retry expectations, write/delete confirmation, and error triage before using module-specific apaas skills."
+description: "Use for aPaaS Node SDK shared setup and safety rules: client initialization, credentials, namespace, token cache, logger level, OpenAPI coverage, pagination defaults, retry expectations, write/delete confirmation, and error-code triage before using module-specific apaas skills."
 ---
 
 # aPaaS Shared
@@ -14,6 +14,8 @@ Use this skill before module-specific aPaaS SDK work.
 - Keep `clientId`, `clientSecret`, access tokens, and app secrets out of logs and final answers.
 - Prefer `client.setLoggerLevel(3)` for normal work, `4` for debugging, and `5` only when inspecting non-sensitive payloads.
 - Treat SDK responses with `code !== "0"` as failed even if the HTTP call succeeded.
+- Read [references/openapi-coverage.md](references/openapi-coverage.md) when checking whether an API doc endpoint is already wrapped.
+- Read [references/openapi-error-codes.md](references/openapi-error-codes.md) when triaging non-zero response codes.
 
 ```ts
 import { apaas } from "apaas-oapi-client";
@@ -39,8 +41,9 @@ client.setLoggerLevel(3);
 ## Module Routing
 
 - Object metadata and record CRUD: use `apaas-object`.
+- OQL, cross-object search, constant objects, and datasets: use `apaas-object`.
 - Object and field schema changes: use `apaas-schema`.
-- Cloud functions and automation flows: use `apaas-function-flow`.
+- Cloud functions, automation flows, workflow status, user tasks, and Lark integration tokens: use `apaas-function-flow`.
 - Builder page metadata and links: use `apaas-builder`.
 - Global options and variables: use `apaas-global`.
 - User/department ID exchange and attachments: use `apaas-exchange-attachment`.

package/skills/apaas-shared/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "aPaaS Shared"
-  short_description: "aPaaS SDK 认证、凭证、安全与通用调用规则指南"
-  default_prompt: "Use $apaas-shared to initialize aPaaS SDK access safely."
+  short_description: "aPaaS SDK 认证、凭证、安全、OpenAPI 覆盖与错误码规则指南"
+  default_prompt: "Use $apaas-shared to initialize aPaaS SDK access and route OpenAPI/error-code work safely."

package/skills/apaas-shared/references/openapi-coverage.md

@@ -0,0 +1,33 @@
+# OpenAPI Coverage
+
+Source snapshot: API doc share for namespace `package_154107__c`, fetched on 2026-06-30. The left navigation contained 167 doc nodes and 72 unique current endpoints after normalizing namespace/object placeholders.
+
+## Current SDK Coverage
+
+| Doc area | Endpoints | SDK entry |
+| --- | --- | --- |
+| Auth | `POST /auth/v1/appToken` | `client.init()` / token cache |
+| Page | list/detail/link | `client.page.list`, `client.page.detail`, `client.page.url` |
+| Object metadata | object list, object metadata, field metadata | `client.object.list*`, `client.object.metadata.*` |
+| Object records | get/list/create/update/delete/batch | `client.object.search/create/update/delete.*` |
+| Object other APIs | OQL, cross-object search | `client.object.oql`, `client.object.search.recordsAcrossObjects*` |
+| Schema | batch create/update/delete objects | `client.schema.create/update/delete`, plus staged helpers |
+| Constant objects | `_currency`, `_country`, `_timeZone` records and metadata | `client.constant.records`, `record`, `metadata.*` |
+| Dataset | dataset list | `client.dataset.list`, `client.dataset.listWithIterator` |
+| Attachments | files and images | `client.attachment.file.*`, `client.attachment.avatar.*` |
+| Global config | global options and variables | `client.global.options.*`, `client.global.variables.*` |
+| Workflow execution | async execution status, flow detail | `client.workflow.execution.status`, `client.workflow.definition.detail` |
+| Workflow user tasks | task/instance list, detail, agree/reject/transfer/add assignee/cc/expedite/cancel/rollback/chat | `client.workflow.userTask.*` |
+| Flow invocation | v1/v2 flow execute | `client.automation.v1.execute`, `client.automation.v2.execute` |
+| Lark integration | default/custom app and tenant tokens | `client.integration.lark.*` |
+| Feishu ID exchange | v2 user/department exchange | `client.user.*`, `client.department.*` |
+
+## Deprecated Docs
+
+The doc tree also exposes `历史版本（不推荐）`. Do not add those endpoints as default SDK methods unless a user explicitly asks for legacy compatibility. Prefer current `/v1/data/...`, `/api/data/v1/...`, `/api/flow/v1/...`, and `/api/integration/v1/...` endpoints.
+
+## Validation Checklist
+
+- Run `npm test -- --runInBand` after endpoint changes.
+- Run `npm run build` so `dist/index.d.ts` exposes new methods.
+- Run `npm pack --dry-run --json` and verify `skills/` plus `dist/` are included.

package/skills/apaas-shared/references/openapi-error-codes.md

@@ -0,0 +1,55 @@
+# OpenAPI Error Codes
+
+All OpenAPI responses use `code`, `msg`, and often `data`. Treat `code !== "0"` as failed even when HTTP status is 200.
+
+```json
+{
+  "code": "k_op_ec_10100",
+  "msg": "Request parameters are not valid: userId is empty"
+}
+```
+
+## Families
+
+The 2026-06-30 API doc bundle listed 531 error codes:
+
+| Family | Prefix | Count | Typical area |
+| --- | --- | ---: | --- |
+| 通用 | `k_ec_` | 26 | generic parameter, permission, naming, unsupported |
+| OpenAPI | `k_op_ec_` | 19 | auth, request parsing, rate limit, backend errors |
+| 身份集成 | `k_ident_` | 38 | identity provider, user/account integration |
+| 元数据 | `k_mt_ec_` | 329 | object/field/schema metadata, record constraints |
+| 规则引擎 | `k_ru_ec_` | 24 | rule/formula/field picker validation |
+| 流程 | `k_wf_ec_` | 70 | workflow definition, execution, user tasks |
+| 权限 | `k_perm_ec_` | 10 | permission and security group errors |
+| 图片/附件 | `k_img_ec_` | 15 | image/file upload, preview, storage |
+
+## High-Signal Codes
+
+| Code | Meaning | First action |
+| --- | --- | --- |
+| `k_ec_000009` | 权限不足 | Verify app permission, namespace, and API credential scope. |
+| `k_ec_000011` | 缺少必填参数 | Compare payload with SDK method params and doc body/query/path fields. |
+| `k_ec_000012` | 必填参数为空 | Check empty strings, empty arrays, and missing nested fields. |
+| `k_ec_000015` | 请求参数不合法 | Read `msg`; for schema writes also run `client.schema.validateResponse`. |
+| `k_op_ec_10100` | 请求参数不合法 | Validate body shape and enum values. |
+| `k_op_ec_10101` | 无法解析 body | Check JSON serialization and `Content-Type: application/json`. |
+| `k_op_ec_10102` | URL 路径参数错误 | Check path params such as object, field, task, flow, or integration API names. |
+| `k_op_ec_10201` | 鉴权失败 | Re-init client and verify `clientId/clientSecret`. |
+| `k_op_ec_10203` | 无访问权限 | Check package role and API credential permission. |
+| `k_op_ec_20003` | 请求被限流 | Reduce concurrency; prefer iterator helpers and ID cursor pagination. |
+| `k_mt_ec_900064` | 字段被报表/页面/规则引用，无法删除 | Remove dependent page/rule/report references before schema delete. |
+| `k_mt_ec_900075` | 一次最多创建或更新 1000 条记录 | Split record writes into chunks. |
+| `k_wf_ec_2001002` | 缺少流程入参 | Re-read flow definition and required input params. |
+| `k_wf_ec_2001005` | 流程实例 ID 不存在 | Verify `execution_id` or approval instance ID from list/status APIs. |
+| `k_wf_ec_2001008` | 幂等键已使用 | Generate a new idempotency key before resubmit. |
+| `k_perm_ec_000001` | 权限不足 | Do not retry blindly; fix permission first. |
+| `k_img_ec_000004` | 附件超过 100M | Compress or split file before upload. |
+| `k_img_ec_000011` | 文件 ID 错误 | Re-read upload response and avoid mixing image/file IDs. |
+
+## Triage Rules
+
+- Do not rely on HTTP status alone.
+- Log `code`, `msg`, and safe request identifiers; do not log secrets or access tokens.
+- For batch APIs, inspect item-level status in `data.items` because the request can be partially successful.
+- For schema writes, `code: "0"` with `data: null` is a silent failure and must be treated as failed.

package/src/FIELD_SCHEMA_RULES.md

@@ -83,9 +83,24 @@ Create/update schema payloads use snake_case keys:
 - Option source: `type.settings.option_source`
 - Global option API name: `type.settings.global_option_api_name`
 
+OpenAPI write payloads require color short codes, while metadata returns color names. The SDK normalizes these metadata names before writing:
+
+| Metadata color | OpenAPI write code |
+|---|---|
+| `blue` | `B` |
+| `cyan` | `W` |
+| `green` | `G` |
+| `yellow` | `Y` |
+| `orange` | `O` |
+| `red` | `R` |
+| `magenta` | `V` |
+| `purple` | `P` |
+| `blueMagenta` | `I` |
+| `grey` | `N` |
+
 Do not copy metadata `optionList` back into `schema.update`; convert it to `options`.
 
-Use `getOptionColor(index)` from the SDK to assign colors in this stable 10-color cycle.
+Use `getOptionColor(index)` from the SDK to assign metadata color names in this stable 10-color cycle. Use `getOptionColorCode(color)` only when constructing raw OpenAPI payloads outside the SDK normalizer.
 
 ## Batch update (`batch_update`) rules
 
@@ -100,3 +115,5 @@ Use `getOptionColor(index)` from the SDK to assign colors in this stable 10-colo
 ## Canonical machine-readable source
 
 Use `/Users/Ethan/apaas/apaas-sdk/node-client/src/field-schema-rules.ts` as the source of truth for code.
+
+The SDK exports `SQL_TYPE_TO_SCHEMA_TYPE`, `COLUMN_NAME_SEMANTIC_RULES`, and `SQL_CONSTRAINT_TO_SETTINGS` for SQL/ER conversion workflows.

package/src/field-schema-rules.ts

@@ -96,6 +96,25 @@ export const OPTION_COLOR_LIST = [
 
 export type OptionColor = typeof OPTION_COLOR_LIST[number];
 
+export const OPTION_COLOR_CODE_BY_NAME: Record<OptionColor, string> = {
+    blue: 'B',
+    cyan: 'W',
+    green: 'G',
+    yellow: 'Y',
+    orange: 'O',
+    red: 'R',
+    magenta: 'V',
+    purple: 'P',
+    blueMagenta: 'I',
+    grey: 'N'
+} as const;
+
+export const OPTION_COLOR_NAME_BY_CODE = Object.fromEntries(
+    Object.entries(OPTION_COLOR_CODE_BY_NAME).map(([name, code]) => [code, name])
+) as Record<string, OptionColor>;
+
+export type OptionColorCode = typeof OPTION_COLOR_CODE_BY_NAME[OptionColor];
+
 export function getOptionColor(index: number): OptionColor {
     if (!Number.isInteger(index) || index < 0) {
         throw new Error('Option color index must be a non-negative integer.');
@@ -104,6 +123,18 @@ export function getOptionColor(index: number): OptionColor {
     return OPTION_COLOR_LIST[index % OPTION_COLOR_LIST.length];
 }
 
+export function getOptionColorCode(color: OptionColor): OptionColorCode {
+    return OPTION_COLOR_CODE_BY_NAME[color] as OptionColorCode;
+}
+
+export function normalizeOptionColorForSchema(color: unknown): unknown {
+    if (typeof color !== 'string') {
+        return color;
+    }
+
+    return OPTION_COLOR_CODE_BY_NAME[color as OptionColor] || color;
+}
+
 export const OPTION_COLOR_RULES = {
     allowedColors: OPTION_COLOR_LIST,
     assignment: 'Use OPTION_COLOR_LIST in order and cycle from the beginning when options exceed 10.',
@@ -124,6 +155,8 @@ export const OPTION_COLOR_RULES = {
         typeName: 'enum',
         optionsPath: 'type.settings.options',
         colorPath: 'type.settings.options[].color',
+        colorInput: 'SDK accepts metadata color names and normalizes them to OpenAPI color codes before writing.',
+        colorCodeByName: OPTION_COLOR_CODE_BY_NAME,
         sourcePath: 'type.settings.option_source',
         globalOptionPath: 'type.settings.global_option_api_name'
     }
@@ -210,7 +243,7 @@ export const FIELD_SCHEMA_RULES: FieldCreateRule[] = [
                 }
             ]
         },
-        notes: `Do not send create type as \`option\`. Metadata returns optionList/optionSource/globalOptionAPIName; create/update expects options/option_source/global_option_api_name. Available option colors: ${OPTION_COLOR_LIST.join(', ')}.`
+        notes: `Do not send create type as \`option\`. Metadata returns optionList/optionSource/globalOptionAPIName; create/update expects options/option_source/global_option_api_name. The SDK accepts metadata color names and sends OpenAPI color codes (${Object.entries(OPTION_COLOR_CODE_BY_NAME).map(([name, code]) => `${name}=${code}`).join(', ')}).`
     },
     {
         metadataType: 'boolean',
@@ -359,6 +392,67 @@ export const SCHEMA_TYPE_MISMATCHES: Array<{
         schemaType: rule.schemaType
     }));
 
+export interface SqlTypeMapping {
+    /** SQL type regex pattern, case-insensitive. */
+    sqlPattern: string;
+    /** Mapped aPaaS schema type. */
+    schemaType: SchemaFieldType;
+    /** Settings derivation rule. */
+    settingsMapping: string;
+}
+
+export const SQL_TYPE_TO_SCHEMA_TYPE: SqlTypeMapping[] = [
+    { sqlPattern: 'VARCHAR\\(\\d+\\)|CHAR\\(\\d+\\)', schemaType: 'text', settingsMapping: 'max_length from (n), multiline: false' },
+    { sqlPattern: 'TEXT|LONGTEXT|MEDIUMTEXT|TINYTEXT|CLOB', schemaType: 'text', settingsMapping: 'multiline: true, max_length: 100000' },
+    { sqlPattern: 'INT|INTEGER|BIGINT|SMALLINT|TINYINT(?!\\(1\\))|MEDIUMINT|SERIAL', schemaType: 'bigint', settingsMapping: 'required/unique from constraints' },
+    { sqlPattern: 'FLOAT|DOUBLE|REAL', schemaType: 'float', settingsMapping: 'decimal_places_number: 2' },
+    { sqlPattern: 'DECIMAL\\(\\d+,\\d+\\)|NUMERIC\\(\\d+,\\d+\\)', schemaType: 'decimal', settingsMapping: 'decimal_places from scale (s)' },
+    { sqlPattern: 'DATE', schemaType: 'date', settingsMapping: 'required from constraints' },
+    { sqlPattern: 'DATETIME|TIMESTAMP', schemaType: 'datetime', settingsMapping: 'required from constraints' },
+    { sqlPattern: 'BOOLEAN|BOOL|TINYINT\\(1\\)|BIT', schemaType: 'boolean', settingsMapping: 'default_value from DEFAULT' },
+    { sqlPattern: 'ENUM\\(.*\\)', schemaType: 'enum', settingsMapping: 'options from enum values, colors auto-assigned with getOptionColor(index)' },
+    { sqlPattern: 'BLOB|BINARY|VARBINARY|LONGBLOB|MEDIUMBLOB', schemaType: 'attachment', settingsMapping: 'any_type: true' },
+    { sqlPattern: 'JSON', schemaType: 'richText', settingsMapping: 'only when JSON stores rich text content' }
+];
+
+export interface ColumnNameSemanticRule {
+    /** Column name regex pattern, case-insensitive. */
+    columnPattern: string;
+    /** Inferred aPaaS schema type. */
+    schemaType: SchemaFieldType;
+    /** Inference notes. */
+    notes: string;
+}
+
+export const COLUMN_NAME_SEMANTIC_RULES: ColumnNameSemanticRule[] = [
+    { columnPattern: '(^|_)(e?mail)(s?$|_)', schemaType: 'email', notes: 'Column name contains email/mail' },
+    { columnPattern: '(^|_)(phone|mobile|tel)(s?$|_)', schemaType: 'phone', notes: 'Column name contains phone/mobile/tel' },
+    { columnPattern: '(^|_)(avatar|logo|profile_image)(s?$|_)', schemaType: 'avatar', notes: 'Column name contains avatar/logo' },
+    { columnPattern: '(^|_)(region|province|city|district|address)(s?$|_)', schemaType: 'region', notes: 'Column name implies geographic data' }
+];
+
+export interface SqlConstraintMapping {
+    /** SQL constraint. */
+    sqlConstraint: string;
+    /** Mapped aPaaS settings field. */
+    settingsField: string;
+    /** Mapped value. */
+    settingsValue: string;
+    /** Mapping notes. */
+    notes: string;
+}
+
+export const SQL_CONSTRAINT_TO_SETTINGS: SqlConstraintMapping[] = [
+    { sqlConstraint: 'NOT NULL', settingsField: 'required', settingsValue: 'true', notes: 'Maps to required: true' },
+    { sqlConstraint: 'UNIQUE', settingsField: 'unique', settingsValue: 'true', notes: 'Maps to unique: true' },
+    { sqlConstraint: 'PRIMARY KEY', settingsField: '-', settingsValue: '-', notes: 'Ignored: aPaaS uses system _id' },
+    { sqlConstraint: 'AUTO_INCREMENT', settingsField: '-', settingsValue: '-', notes: 'Ignored: aPaaS _id auto-increments. For business serial numbers, use auto_number' },
+    { sqlConstraint: 'FOREIGN KEY', settingsField: 'referenced_object_api_name', settingsValue: '(target table)', notes: 'Convert to lookup field' },
+    { sqlConstraint: 'DEFAULT', settingsField: 'default_value', settingsValue: '(value)', notes: 'Only boolean type supports default_value in aPaaS' },
+    { sqlConstraint: 'CHECK', settingsField: '-', settingsValue: '-', notes: 'Not supported in aPaaS, handle in application logic' },
+    { sqlConstraint: 'INDEX', settingsField: '-', settingsValue: '-', notes: 'Not applicable, aPaaS manages indexing automatically' }
+];
+
 export const BATCH_UPDATE_REQUIREMENTS = {
     add: 'Use operator=add with full field definition.',
     replace: 'Use operator=replace and include full `type` (name + settings). Label-only replace fails.',

package/src/field-types.ts

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