apaas-oapi-client 0.1.35 → 0.1.37

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "apaas-oapi-client",
-    "version": "0.1.35",
+    "version": "0.1.37",
     "main": "dist/index.js",
     "exports": {
         ".": "./dist/index.js",
@@ -10,9 +10,8 @@
     "type": "commonjs",
     "scripts": {
         "build": "rollup -c",
-        "test": "jest",
-        "test:manual": "tsx test/test.ts",
-        "dev": "ts-node src/index.ts",
+        "test": "jest --passWithNoTests",
+        "dev": "tsx src/index.ts",
         "release": "npm run build && npm version patch && git push origin main --follow-tags"
     },
     "keywords": [],
@@ -33,7 +32,7 @@
         "rollup": "^4.44.1",
         "rollup-plugin-typescript2": "^0.36.0",
         "ts-jest": "^29.4.0",
-        "ts-node": "^10.9.2",
+        "tsx": "^4.21.0",
         "typescript": "^5.8.3"
     },
     "description": ""

package/src/FIELD_SCHEMA_RULES.md

@@ -0,0 +1,81 @@
+# Field Schema Rules (20 Entries)
+
+This file summarizes the verified schema rules for field types in aPaaS.
+
+- Verification date: `2026-02-10`
+- Namespace: `package_5dc5b7__c`
+- Source object for metadata: `full_field_format`
+- Lookup target used in tests: `_user`
+- Reference field target used in tests: `_lark_user_id`
+
+## Why this file exists
+
+`object.metadata.fields` returns type names that are not always accepted by `schema.create/schema.update`.
+Use this mapping when creating fields.
+
+- Includes `18` official metadata field types
+- Plus `2` practical rule extensions:
+  - `text_multiline`
+  - `lookup_multi`
+
+## Type Mapping (metadata -> create)
+
+| Metadata Type | Create Type | Notes |
+| --- | --- | --- |
+| `text` | `text` | single-line text, `max_length=255` |
+| `text_multiline` | `text` | multiline text, `multiline=true`, `max_length=100000` |
+| `bigint` | `bigint` | same |
+| `number` | `float` | `number` create type fails |
+| `date` | `date` | same |
+| `datetime` | `datetime` | same |
+| `option` | `enum` | `option` create type fails |
+| `boolean` | `boolean` | same |
+| `lookup` | `lookup` | single value (`multiple=false`) |
+| `lookup_multi` | `lookup` | multi value (`multiple=true`) |
+| `referenceField` | `reference_field` | depends on lookup field |
+| `file` | `attachment` | `file` create type fails |
+| `autoId` | `auto_number` | `autoId` create type fails |
+| `richText` | `richText` | same |
+| `mobileNumber` | `phone` | `mobileNumber` create type fails |
+| `avatarOrLogo` | `avatar` | `avatarOrLogo` create type fails |
+| `email` | `email` | same |
+| `region` | `region` | same |
+| `decimal` | `decimal` | same |
+| `multilingual` | `multilingual` | same |
+
+## Dependency rules
+
+- `lookup` needs target object to exist first. In tests, target object is `_user`.
+- `lookup_multi` can reference multiple rows (`multiple=true`), but **cannot** be used as guide field for `reference_field`.
+- `reference_field` needs:
+  - a **single-value** lookup field in the same object (`current_lookup_field_api_name`)
+  - a target field in target object (`target_reference_field_api_name`, tested with `_lark_user_id`)
+
+## Option color list
+
+Allowed option colors:
+
+- `blue`
+- `cyan`
+- `green`
+- `yellow`
+- `orange`
+- `red`
+- `magenta`
+- `purple`
+- `blueMagenta`
+- `grey`
+
+## Batch update (`batch_update`) rules
+
+- `add`: use `operator: "add"` and send full field definition.
+- `replace`: use `operator: "replace"` and send full `type` (`name + settings`).
+  - Label-only replace (without `type`) fails with: `k_ec_000015 field type is required`.
+- `remove`: use `operator: "remove"` and only `api_name`.
+- Order constraints:
+  - add phase: create `lookup`/`lookup_multi` before `reference_field`
+  - remove phase: remove `reference_field` before `lookup`/`lookup_multi`
+
+## Canonical machine-readable source
+
+Use `/Users/Ethan/apaas/apaas-sdk/node-client/src/field-schema-rules.ts` as the source of truth for code.

package/src/field-schema-rules.ts

@@ -0,0 +1,336 @@
+/**
+ * Canonical field rules for schema.create/schema.update.
+ * Verified in namespace `package_5dc5b7__c` on 2026-02-10.
+ *
+ * Notes:
+ * - `metadataType` is usually the type name returned by object.metadata.fields.
+ * - Some entries are rule extensions for practical schema usage (`text_multiline`, `lookup_multi`).
+ * - `schemaType` is the type name that should be sent to schema.create/update.
+ */
+
+export type MetadataFieldType =
+    | 'text'
+    | 'text_multiline'
+    | 'bigint'
+    | 'number'
+    | 'date'
+    | 'datetime'
+    | 'option'
+    | 'boolean'
+    | 'lookup'
+    | 'lookup_multi'
+    | 'referenceField'
+    | 'file'
+    | 'autoId'
+    | 'richText'
+    | 'mobileNumber'
+    | 'avatarOrLogo'
+    | 'email'
+    | 'region'
+    | 'decimal'
+    | 'multilingual';
+
+export type SchemaFieldType =
+    | 'text'
+    | 'bigint'
+    | 'float'
+    | 'date'
+    | 'datetime'
+    | 'enum'
+    | 'boolean'
+    | 'lookup'
+    | 'reference_field'
+    | 'attachment'
+    | 'auto_number'
+    | 'richText'
+    | 'phone'
+    | 'avatar'
+    | 'email'
+    | 'region'
+    | 'decimal'
+    | 'multilingual';
+
+export interface FieldCreateRule {
+    metadataType: MetadataFieldType;
+    schemaType: SchemaFieldType;
+    settingsExample: Record<string, unknown>;
+    dependsOn?: string[];
+    notes?: string;
+}
+
+export const SCHEMA_TYPE_BY_METADATA_TYPE: Record<MetadataFieldType, SchemaFieldType> = {
+    text: 'text',
+    text_multiline: 'text',
+    bigint: 'bigint',
+    number: 'float',
+    date: 'date',
+    datetime: 'datetime',
+    option: 'enum',
+    boolean: 'boolean',
+    lookup: 'lookup',
+    lookup_multi: 'lookup',
+    referenceField: 'reference_field',
+    file: 'attachment',
+    autoId: 'auto_number',
+    richText: 'richText',
+    mobileNumber: 'phone',
+    avatarOrLogo: 'avatar',
+    email: 'email',
+    region: 'region',
+    decimal: 'decimal',
+    multilingual: 'multilingual'
+};
+
+export const OPTION_COLOR_LIST = [
+    'blue',
+    'cyan',
+    'green',
+    'yellow',
+    'orange',
+    'red',
+    'magenta',
+    'purple',
+    'blueMagenta',
+    'grey'
+] as const;
+
+export const FIELD_SCHEMA_RULES: FieldCreateRule[] = [
+    {
+        metadataType: 'text',
+        schemaType: 'text',
+        settingsExample: {
+            required: false,
+            unique: false,
+            case_sensitive: false,
+            multiline: false,
+            max_length: 255
+        }
+    },
+    {
+        metadataType: 'text_multiline',
+        schemaType: 'text',
+        settingsExample: {
+            required: false,
+            unique: false,
+            case_sensitive: false,
+            multiline: true,
+            max_length: 100000
+        }
+    },
+    {
+        metadataType: 'bigint',
+        schemaType: 'bigint',
+        settingsExample: {
+            required: false,
+            unique: false
+        }
+    },
+    {
+        metadataType: 'number',
+        schemaType: 'float',
+        settingsExample: {
+            required: false,
+            unique: false,
+            display_as_percentage: false,
+            decimal_places_number: 2
+        },
+        notes: 'Do not send create type as `number`.'
+    },
+    {
+        metadataType: 'date',
+        schemaType: 'date',
+        settingsExample: {
+            required: false
+        }
+    },
+    {
+        metadataType: 'datetime',
+        schemaType: 'datetime',
+        settingsExample: {
+            required: false
+        }
+    },
+    {
+        metadataType: 'option',
+        schemaType: 'enum',
+        settingsExample: {
+            required: false,
+            multiple: false,
+            option_source: 'custom',
+            global_option_api_name: '',
+            options: [
+                {
+                    label: { zh_cn: 'Option One', en_us: 'Option One' },
+                    api_name: 'option_one',
+                    description: null,
+                    color: 'blue',
+                    active: true
+                },
+                {
+                    label: { zh_cn: 'Option Two', en_us: 'Option Two' },
+                    api_name: 'option_two',
+                    description: null,
+                    color: 'green',
+                    active: true
+                }
+            ]
+        },
+        notes: `Do not send create type as \`option\`. Available option colors: ${OPTION_COLOR_LIST.join(', ')}.`
+    },
+    {
+        metadataType: 'boolean',
+        schemaType: 'boolean',
+        settingsExample: {
+            default_value: true,
+            description_if_true: { zh_cn: '1', en_us: '1' },
+            description_if_false: { zh_cn: '0', en_us: '0' }
+        }
+    },
+    {
+        metadataType: 'lookup',
+        schemaType: 'lookup',
+        settingsExample: {
+            required: false,
+            multiple: false,
+            referenced_object_api_name: '_user',
+            display_as_tree: false,
+            display_style: 'select'
+        },
+        dependsOn: ['Target object must exist first: `_user`'],
+        notes: 'Single-value lookup (`multiple: false`), can be used by `reference_field`.'
+    },
+    {
+        metadataType: 'lookup_multi',
+        schemaType: 'lookup',
+        settingsExample: {
+            required: false,
+            multiple: true,
+            referenced_object_api_name: '_user',
+            display_as_tree: false,
+            display_style: 'select'
+        },
+        dependsOn: ['Target object must exist first: `_user`'],
+        notes: 'Multi-value lookup (`multiple: true`) cannot be used by `reference_field`.'
+    },
+    {
+        metadataType: 'referenceField',
+        schemaType: 'reference_field',
+        settingsExample: {
+            current_lookup_field_api_name: 'lookup_835c2a2457b',
+            target_reference_field_api_name: '_lark_user_id'
+        },
+        dependsOn: [
+            'A single-value lookup field must exist first in the same object',
+            'The target field must exist in the lookup target object'
+        ],
+        notes: 'Guide field must be single lookup (`multiple: false`).'
+    },
+    {
+        metadataType: 'file',
+        schemaType: 'attachment',
+        settingsExample: {
+            required: false,
+            any_type: true,
+            max_uploaded_num: 10,
+            mime_types: []
+        },
+        notes: 'Do not send create type as `file`.'
+    },
+    {
+        metadataType: 'autoId',
+        schemaType: 'auto_number',
+        settingsExample: {
+            generation_method: 'random',
+            digits: 1,
+            prefix: '',
+            suffix: '',
+            start_at: '1'
+        },
+        notes: 'Do not send create type as `autoId`.'
+    },
+    {
+        metadataType: 'richText',
+        schemaType: 'richText',
+        settingsExample: {
+            required: false,
+            max_length: 1000
+        }
+    },
+    {
+        metadataType: 'mobileNumber',
+        schemaType: 'phone',
+        settingsExample: {
+            required: false,
+            unique: false
+        },
+        notes: 'Do not send create type as `mobileNumber`.'
+    },
+    {
+        metadataType: 'avatarOrLogo',
+        schemaType: 'avatar',
+        settingsExample: {
+            display_style: 'square'
+        },
+        notes: 'Do not send create type as `avatarOrLogo`.'
+    },
+    {
+        metadataType: 'email',
+        schemaType: 'email',
+        settingsExample: {
+            required: false,
+            unique: false
+        }
+    },
+    {
+        metadataType: 'region',
+        schemaType: 'region',
+        settingsExample: {
+            required: false,
+            multiple: false,
+            has_level_strict: true,
+            strict_level: 4
+        }
+    },
+    {
+        metadataType: 'decimal',
+        schemaType: 'decimal',
+        settingsExample: {
+            required: false,
+            unique: false,
+            display_as_percentage: false,
+            decimal_places: 2
+        }
+    },
+    {
+        metadataType: 'multilingual',
+        schemaType: 'multilingual',
+        settingsExample: {
+            required: false,
+            unique: false,
+            case_sensitive: false,
+            multiline: false,
+            max_length: 1000
+        }
+    }
+];
+
+export const SCHEMA_TYPE_MISMATCHES: Array<{
+    metadataType: MetadataFieldType;
+    schemaType: SchemaFieldType;
+}> = FIELD_SCHEMA_RULES
+    .filter((rule) => rule.metadataType !== rule.schemaType)
+    .map((rule) => ({
+        metadataType: rule.metadataType,
+        schemaType: rule.schemaType
+    }));
+
+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.',
+    remove: 'Use operator=remove with api_name only.',
+    dependencyOrder: {
+        add: ['lookup/lookup_multi before reference_field'],
+        remove: ['reference_field before lookup/lookup_multi']
+    },
+    referenceFieldConstraint: 'reference_field only works with single lookup (`multiple: false`).'
+} as const;