apaas-oapi-client 0.1.39 → 1.0.0

package/dist/index.js

@@ -735,6 +735,850 @@ function extractMultilingualText(multilingualText, languageCode = LANGUAGE_CODES
     return found ? found.text : ((_a = multilingualText[0]) === null || _a === void 0 ? void 0 : _a.text) || '';
 }
 
+/**
+ * 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.
+ */
+const SCHEMA_TYPE_BY_METADATA_TYPE = {
+    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'
+};
+const OPTION_COLOR_LIST = [
+    'blue',
+    'cyan',
+    'green',
+    'yellow',
+    'orange',
+    'red',
+    'magenta',
+    'purple',
+    'blueMagenta',
+    'grey'
+];
+const OPTION_COLOR_CODE_BY_NAME = {
+    blue: 'B',
+    cyan: 'W',
+    green: 'G',
+    yellow: 'Y',
+    orange: 'O',
+    red: 'R',
+    magenta: 'V',
+    purple: 'P',
+    blueMagenta: 'I',
+    grey: 'N'
+};
+const OPTION_COLOR_NAME_BY_CODE = Object.fromEntries(Object.entries(OPTION_COLOR_CODE_BY_NAME).map(([name, code]) => [code, name]));
+function getOptionColor(index) {
+    if (!Number.isInteger(index) || index < 0) {
+        throw new Error('Option color index must be a non-negative integer.');
+    }
+    return OPTION_COLOR_LIST[index % OPTION_COLOR_LIST.length];
+}
+function getOptionColorCode(color) {
+    return OPTION_COLOR_CODE_BY_NAME[color];
+}
+function normalizeOptionColorForSchema(color) {
+    if (typeof color !== 'string') {
+        return color;
+    }
+    return OPTION_COLOR_CODE_BY_NAME[color] || color;
+}
+const OPTION_COLOR_RULES = {
+    allowedColors: OPTION_COLOR_LIST,
+    assignment: 'Use OPTION_COLOR_LIST in order and cycle from the beginning when options exceed 10.',
+    verifiedBy: {
+        namespace: 'package_154107__c',
+        object: 'object_test2',
+        field: 'option_colors',
+        date: '2026-06-30'
+    },
+    metadataShape: {
+        typeName: 'option',
+        optionListPath: 'type.settings.optionList',
+        colorPath: 'type.settings.optionList[].color',
+        sourcePath: 'type.settings.optionSource',
+        globalOptionPath: 'type.settings.globalOptionAPIName'
+    },
+    createShape: {
+        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'
+    }
+};
+const FIELD_SCHEMA_RULES = [
+    {
+        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\`. 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',
+        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
+        }
+    }
+];
+const SCHEMA_TYPE_MISMATCHES = FIELD_SCHEMA_RULES
+    .filter((rule) => rule.metadataType !== rule.schemaType)
+    .map((rule) => ({
+    metadataType: rule.metadataType,
+    schemaType: rule.schemaType
+}));
+const SQL_TYPE_TO_SCHEMA_TYPE = [
+    { 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' }
+];
+const COLUMN_NAME_SEMANTIC_RULES = [
+    { 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' }
+];
+const SQL_CONSTRAINT_TO_SETTINGS = [
+    { 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' }
+];
+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`).'
+};
+
+const SCHEMA_BATCH_SIZE = 10;
+function isSystemSchemaName(apiName) {
+    return apiName.startsWith('_');
+}
+function normalizeSchemaObjectsForWrite(objects) {
+    return objects.map((object) => {
+        if (!object.fields) {
+            return { ...object };
+        }
+        return {
+            ...object,
+            fields: object.fields.map((field) => normalizeSchemaFieldForWrite(field))
+        };
+    });
+}
+function normalizeSchemaFieldForWrite(field) {
+    var _a, _b;
+    const settings = (_a = field.type) === null || _a === void 0 ? void 0 : _a.settings;
+    if (((_b = field.type) === null || _b === void 0 ? void 0 : _b.name) !== 'enum' || !Array.isArray(settings === null || settings === void 0 ? void 0 : settings.options)) {
+        return { ...field };
+    }
+    return {
+        ...field,
+        type: {
+            ...field.type,
+            settings: {
+                ...settings,
+                options: settings.options.map((option) => {
+                    if (!option || typeof option !== 'object' || !('color' in option)) {
+                        return option;
+                    }
+                    return {
+                        ...option,
+                        color: normalizeOptionColorForSchema(option.color)
+                    };
+                })
+            }
+        }
+    };
+}
+function validateSchemaResponse(result, context = 'schema', options = {}) {
+    var _a, _b, _c, _d;
+    const failures = [];
+    if (!result) {
+        failures.push({
+            layer: 'request',
+            context,
+            code: 'NO_RESULT',
+            message: `${context} request failed: empty response`
+        });
+        return { ok: false, result, failures };
+    }
+    if (String(result.code) !== '0') {
+        failures.push({
+            layer: 'request',
+            context,
+            code: result.code === undefined ? 'undefined' : String(result.code),
+            message: `${context} request failed: ${result.code} ${result.msg || result.message || ''}`.trim()
+        });
+    }
+    if (result.data === null && !options.allowDataNull) {
+        failures.push({
+            layer: 'silent',
+            context,
+            code: 'DATA_NULL',
+            message: `${context} silently failed: result.code is 0 but result.data is null`
+        });
+    }
+    for (const item of ((_a = result.data) === null || _a === void 0 ? void 0 : _a.items) || []) {
+        const itemCode = (_b = item.status) === null || _b === void 0 ? void 0 : _b.code;
+        if (itemCode === undefined && options.requireItemStatus) {
+            failures.push({
+                layer: 'item',
+                context,
+                code: 'MISSING_STATUS',
+                apiName: getItemApiName(item),
+                item,
+                message: `${context} item status is missing: ${getItemApiName(item) || 'unknown'}`
+            });
+            continue;
+        }
+        if (itemCode !== undefined && String(itemCode) !== '0') {
+            failures.push({
+                layer: 'item',
+                context,
+                code: String(itemCode),
+                apiName: getItemApiName(item),
+                item,
+                message: `${context} item failed: ${getItemApiName(item) || 'unknown'} ${((_c = item.status) === null || _c === void 0 ? void 0 : _c.message) || ((_d = item.status) === null || _d === void 0 ? void 0 : _d.msg) || ''}`.trim()
+            });
+        }
+    }
+    return { ok: failures.length === 0, result, failures };
+}
+function checkSchemaResponse(result, context = 'schema', options) {
+    const validation = validateSchemaResponse(result, context, options);
+    if (!validation.ok) {
+        const error = new Error(validation.failures.map((failure) => failure.message).join('; '));
+        error.failures = validation.failures;
+        throw error;
+    }
+    return result;
+}
+async function batchExecute(items, fn, options = {}) {
+    var _a;
+    const batchSize = (_a = options.batchSize) !== null && _a !== void 0 ? _a : SCHEMA_BATCH_SIZE;
+    if (!Number.isInteger(batchSize) || batchSize <= 0) {
+        throw new Error('batchSize must be a positive integer.');
+    }
+    const batchCount = Math.ceil(items.length / batchSize);
+    const results = [];
+    const failures = [];
+    for (let start = 0; start < items.length; start += batchSize) {
+        const batch = items.slice(start, start + batchSize);
+        const batchIndex = Math.floor(start / batchSize) + 1;
+        const info = {
+            batchIndex,
+            batchCount,
+            start,
+            end: start + batch.length,
+            batchSize: batch.length
+        };
+        const context = `${options.context || 'schema batch'} [${batchIndex}/${batchCount}]`;
+        try {
+            const result = await fn(batch, info);
+            results.push(result);
+            if (options.checkResponse !== false) {
+                const validation = validateSchemaResponse(result, context, options.responseOptions);
+                failures.push(...validation.failures);
+                if (!validation.ok && !options.continueOnError) {
+                    const error = new Error(validation.failures.map((failure) => failure.message).join('; '));
+                    error.failures = validation.failures;
+                    throw error;
+                }
+            }
+        }
+        catch (error) {
+            if (!options.continueOnError) {
+                throw error;
+            }
+            failures.push({
+                layer: 'request',
+                context,
+                code: 'EXCEPTION',
+                message: error instanceof Error ? error.message : String(error)
+            });
+        }
+    }
+    return {
+        ok: failures.length === 0,
+        total: items.length,
+        batchSize,
+        batchCount,
+        results,
+        failures
+    };
+}
+function splitSchemaFieldsByDependency(fields) {
+    const baseFields = [];
+    const lookupFields = [];
+    const referenceFields = [];
+    for (const field of fields) {
+        const typeName = getSchemaFieldTypeName(field);
+        if (typeName === 'reference_field' || typeName === 'referenceField') {
+            referenceFields.push(field);
+        }
+        else if (typeName === 'lookup' || typeName === 'lookup_multi') {
+            lookupFields.push(field);
+        }
+        else {
+            baseFields.push(field);
+        }
+    }
+    return { baseFields, lookupFields, referenceFields };
+}
+async function createSchemaObjectShells(client, objects, options = {}) {
+    assertNoSystemObjects(objects.map((object) => object.api_name), 'createSchemaObjectShells');
+    const existingNames = options.skipExisting === false
+        ? new Set()
+        : await getExistingObjectNames(client);
+    const shells = objects
+        .filter((object) => !existingNames.has(object.api_name))
+        .map(toShellObject);
+    const result = {
+        requested: objects.map((object) => object.api_name),
+        created: shells.map((object) => object.api_name),
+        skippedExisting: objects
+            .filter((object) => existingNames.has(object.api_name))
+            .map((object) => object.api_name)
+    };
+    if (shells.length === 0) {
+        return result;
+    }
+    result.batches = await batchExecute(shells, (batch) => client.schema.create({ objects: batch }), {
+        batchSize: options.batchSize,
+        context: options.context || 'schema.createShells',
+        continueOnError: options.continueOnError,
+        checkResponse: options.checkResponse,
+        responseOptions: options.responseOptions
+    });
+    return result;
+}
+async function addFieldsIdempotent(client, objectName, fieldsToAdd, options = {}) {
+    assertNoSystemObjects([objectName], 'addFieldsIdempotent');
+    assertNoSystemFields(fieldsToAdd.map((field) => field.api_name), `addFieldsIdempotent(${objectName})`);
+    const existingNames = options.skipExisting === false
+        ? new Set()
+        : await getExistingFieldNames(client, objectName);
+    const newFields = fieldsToAdd.filter((field) => !existingNames.has(field.api_name)).map(toAddField);
+    const skippedFields = fieldsToAdd
+        .filter((field) => existingNames.has(field.api_name))
+        .map((field) => field.api_name);
+    if (newFields.length === 0) {
+        return {
+            objectName,
+            addedFields: [],
+            skippedFields
+        };
+    }
+    const result = await client.schema.update({
+        objects: [{ api_name: objectName, fields: newFields }]
+    });
+    if (options.checkResponse !== false) {
+        checkSchemaResponse(result, options.context || `schema.addFieldsIdempotent(${objectName})`, options.responseOptions);
+    }
+    return {
+        objectName,
+        addedFields: newFields.map((field) => field.api_name),
+        skippedFields,
+        result
+    };
+}
+async function createSchemaObjectsInStages(client, objects, options = {}) {
+    const context = options.context || 'schema.createWithStages';
+    const shells = await createSchemaObjectShells(client, objects, {
+        ...options,
+        context: `${context}.shells`
+    });
+    const baseFields = [];
+    const lookupFields = [];
+    const referenceFields = [];
+    for (const object of objects) {
+        assertNoSystemFields((object.fields || []).map((field) => field.api_name), `${context}(${object.api_name})`);
+        const split = splitSchemaFieldsByDependency(object.fields || []);
+        if (split.baseFields.length > 0) {
+            baseFields.push(await addFieldsIdempotent(client, object.api_name, split.baseFields, {
+                context: `${context}.baseFields(${object.api_name})`,
+                skipExisting: options.skipExisting,
+                checkResponse: options.checkResponse,
+                responseOptions: options.responseOptions
+            }));
+        }
+        if (split.lookupFields.length > 0) {
+            lookupFields.push(await addFieldsIdempotent(client, object.api_name, split.lookupFields, {
+                context: `${context}.lookupFields(${object.api_name})`,
+                skipExisting: options.skipExisting,
+                checkResponse: options.checkResponse,
+                responseOptions: options.responseOptions
+            }));
+        }
+        if (split.referenceFields.length > 0) {
+            referenceFields.push(await addFieldsIdempotent(client, object.api_name, split.referenceFields, {
+                context: `${context}.referenceFields(${object.api_name})`,
+                skipExisting: options.skipExisting,
+                checkResponse: options.checkResponse,
+                responseOptions: options.responseOptions
+            }));
+        }
+    }
+    const result = {
+        shells,
+        baseFields,
+        lookupFields,
+        referenceFields
+    };
+    const finalSettings = options.updateFinalSettings === false
+        ? []
+        : objects
+            .filter((object) => object.settings && Object.keys(object.settings).length > 0)
+            .map((object) => ({ api_name: object.api_name, settings: object.settings }));
+    if (finalSettings.length > 0) {
+        result.finalSettings = await batchExecute(finalSettings, (batch) => client.schema.update({ objects: batch }), {
+            batchSize: options.batchSize,
+            context: `${context}.finalSettings`,
+            continueOnError: options.continueOnError,
+            checkResponse: options.checkResponse,
+            responseOptions: {
+                ...options.responseOptions,
+                allowDataNull: true
+            }
+        });
+    }
+    if (options.verify !== false) {
+        result.verification = await verifySchemaObjects(client, objects.map((object) => object.api_name), { includeMarkdown: options.includeMarkdown });
+    }
+    return result;
+}
+async function verifySchemaObjects(client, objectNames, options = {}) {
+    var _a, _b;
+    const allObjects = await client.object.listWithIterator();
+    const objects = [];
+    for (const objectName of objectNames) {
+        const exists = Boolean((_a = allObjects.items) === null || _a === void 0 ? void 0 : _a.find((object) => object.apiName === objectName || object.api_name === objectName));
+        if (!exists) {
+            objects.push({
+                objectName,
+                exists: false,
+                fields: [],
+                customFields: []
+            });
+            continue;
+        }
+        const fieldResult = await client.object.metadata.fields({ object_name: objectName });
+        if (fieldResult.code !== undefined && String(fieldResult.code) !== '0') {
+            throw new Error(`verifySchemaObjects(${objectName}) failed: ${fieldResult.code} ${fieldResult.msg || fieldResult.message || ''}`.trim());
+        }
+        const fields = ((_b = fieldResult.data) === null || _b === void 0 ? void 0 : _b.fields) || [];
+        objects.push({
+            objectName,
+            exists: true,
+            fields,
+            customFields: fields.filter((field) => !isSystemSchemaName(field.apiName || field.api_name || ''))
+        });
+    }
+    const result = { objects };
+    if (options.includeMarkdown && client.object.metadata.export2markdown) {
+        result.markdown = await client.object.metadata.export2markdown({ object_names: objectNames });
+    }
+    return result;
+}
+function buildFieldRemovalPlan(fieldsByObject) {
+    const referenceFieldObjects = new Map();
+    const lookupObjects = new Map();
+    const otherFieldObjects = new Map();
+    for (const [objectName, fields] of Object.entries(fieldsByObject)) {
+        for (const field of fields) {
+            const apiName = field.api_name || field.apiName;
+            if (!apiName || isSystemSchemaName(apiName)) {
+                continue;
+            }
+            const target = getRemovalGroup(field, referenceFieldObjects, lookupObjects, otherFieldObjects);
+            const existing = target.get(objectName) || [];
+            existing.push({ operator: 'remove', api_name: apiName });
+            target.set(objectName, existing);
+        }
+    }
+    return {
+        referenceFieldObjects: mapRemovalObjects(referenceFieldObjects),
+        lookupObjects: mapRemovalObjects(lookupObjects),
+        otherFieldObjects: mapRemovalObjects(otherFieldObjects)
+    };
+}
+async function deleteAllCustomObjects(client, options = {}) {
+    var _a;
+    if (options.confirm !== true) {
+        throw new Error('deleteAllCustomObjects requires { confirm: true }.');
+    }
+    const context = options.context || 'schema.deleteAllCustomObjects';
+    const allObjects = await client.object.listWithIterator();
+    const customObjects = (allObjects.items || []).filter((object) => !isSystemSchemaName(object.apiName || object.api_name || ''));
+    const objectNames = customObjects.map((object) => object.apiName || object.api_name);
+    const fieldsByObject = {};
+    for (const objectName of objectNames) {
+        const fieldResult = await client.object.metadata.fields({ object_name: objectName });
+        if (fieldResult.code !== undefined && String(fieldResult.code) !== '0') {
+            throw new Error(`${context}.readFields(${objectName}) failed: ${fieldResult.code} ${fieldResult.msg || fieldResult.message || ''}`.trim());
+        }
+        fieldsByObject[objectName] = ((_a = fieldResult.data) === null || _a === void 0 ? void 0 : _a.fields) || [];
+    }
+    const removalPlan = buildFieldRemovalPlan(fieldsByObject);
+    const fieldRemovalResults = [];
+    for (const [phase, updateObjects] of [
+        ['referenceFields', removalPlan.referenceFieldObjects],
+        ['lookupFields', removalPlan.lookupObjects],
+        ['otherFields', options.removeOtherFields ? removalPlan.otherFieldObjects : []]
+    ]) {
+        if (updateObjects.length === 0) {
+            continue;
+        }
+        fieldRemovalResults.push(await batchExecute(updateObjects, (batch) => client.schema.update({ objects: batch }), {
+            batchSize: options.batchSize,
+            context: `${context}.${phase}`,
+            continueOnError: options.continueOnError,
+            checkResponse: options.checkResponse,
+            responseOptions: options.responseOptions
+        }));
+    }
+    const result = {
+        deletedObjects: objectNames,
+        removalPlan,
+        fieldRemovalResults
+    };
+    if (objectNames.length > 0) {
+        result.deleteResults = await batchExecute(objectNames, (batch) => client.schema.delete({ api_names: batch }), {
+            batchSize: options.batchSize,
+            context: `${context}.deleteObjects`,
+            continueOnError: options.continueOnError,
+            checkResponse: options.checkResponse,
+            responseOptions: {
+                ...options.responseOptions,
+                allowDataNull: true
+            }
+        });
+    }
+    if (options.verify !== false) {
+        const after = await client.object.listWithIterator();
+        result.remainingObjects = (after.items || [])
+            .filter((object) => objectNames.includes(object.apiName || object.api_name))
+            .map((object) => object.apiName || object.api_name);
+        if (result.remainingObjects.length > 0) {
+            throw new Error(`${context} verification failed: remaining objects ${result.remainingObjects.join(', ')}`);
+        }
+    }
+    return result;
+}
+function getItemApiName(item) {
+    return item.api_name || item.apiName || item.name;
+}
+function getSchemaFieldTypeName(field) {
+    const type = field.type;
+    if (typeof type === 'string') {
+        return type;
+    }
+    return type === null || type === void 0 ? void 0 : type.name;
+}
+function toAddField(field) {
+    return {
+        ...field,
+        operator: 'add'
+    };
+}
+function toShellObject(object) {
+    const { fields: _fields, ...shell } = object;
+    const originalSettings = object.settings || {};
+    return {
+        ...shell,
+        settings: {
+            ...originalSettings,
+            display_name: '_id',
+            allow_search_fields: ['_id'],
+            search_layout: []
+        }
+    };
+}
+async function getExistingObjectNames(client) {
+    const result = await client.object.listWithIterator();
+    return new Set((result.items || []).map((object) => object.apiName || object.api_name).filter(Boolean));
+}
+async function getExistingFieldNames(client, objectName) {
+    var _a;
+    const result = await client.object.metadata.fields({ object_name: objectName });
+    if (result.code !== undefined && String(result.code) !== '0') {
+        throw new Error(`getExistingFieldNames(${objectName}) failed: ${result.code} ${result.msg || result.message || ''}`.trim());
+    }
+    return new Set((((_a = result.data) === null || _a === void 0 ? void 0 : _a.fields) || []).map((field) => field.apiName || field.api_name).filter(Boolean));
+}
+function assertNoSystemObjects(apiNames, context) {
+    const systemNames = apiNames.filter(isSystemSchemaName);
+    if (systemNames.length > 0) {
+        throw new Error(`${context} cannot modify system objects: ${systemNames.join(', ')}`);
+    }
+}
+function assertNoSystemFields(apiNames, context) {
+    const systemNames = apiNames.filter(isSystemSchemaName);
+    if (systemNames.length > 0) {
+        throw new Error(`${context} cannot modify system fields: ${systemNames.join(', ')}`);
+    }
+}
+function getRemovalGroup(field, referenceFieldObjects, lookupObjects, otherFieldObjects) {
+    const typeName = getSchemaFieldTypeName(field);
+    if (typeName === 'reference_field' || typeName === 'referenceField') {
+        return referenceFieldObjects;
+    }
+    if (typeName === 'lookup' || typeName === 'lookup_multi') {
+        return lookupObjects;
+    }
+    return otherFieldObjects;
+}
+function mapRemovalObjects(fieldsByObject) {
+    return Array.from(fieldsByObject.entries()).map(([api_name, fields]) => ({ api_name, fields }));
+}
+
 /**
  * 判断错误是否可重试
  */
@@ -1381,8 +2225,70 @@ class Client {
                         total: total,
                         msg: res.msg
                     };
+                },
+                /**
+                 * 跨对象搜索记录
+                 * @description 在最多 5 个对象中按搜索词查询记录
+                 * @param params 请求体，包含 q、search_objects、page_token、page_size、metadata 等
+                 */
+                recordsAcrossObjects: async (params) => {
+                    await this.ensureTokenValid();
+                    const url = `/v1/namespaces/${this.namespace}/objects/records/search`;
+                    this.log(LoggerLevel.info, `[object.search.recordsAcrossObjects] Searching records: q=${params.q}`);
+                    const res = await this.axiosInstance.post(url, params, {
+                        headers: this.authHeaders(true)
+                    });
+                    this.log(LoggerLevel.debug, `[object.search.recordsAcrossObjects] Records searched: code=${res.data.code}`);
+                    this.log(LoggerLevel.trace, `[object.search.recordsAcrossObjects] Response: ${JSON.stringify(res.data)}`);
+                    return res.data;
+                },
+                /**
+                 * 跨对象搜索记录 - 自动 page_token 分页
+                 */
+                recordsAcrossObjectsWithIterator: async (params) => {
+                    var _a, _b, _c, _d, _e, _f;
+                    const pageSize = params.page_size || 20;
+                    let pageToken = params.page_token || '';
+                    let hasMore = true;
+                    const items = [];
+                    let lastResponse = null;
+                    while (hasMore) {
+                        const res = await this.object.search.recordsAcrossObjects({
+                            ...params,
+                            page_size: pageSize,
+                            page_token: pageToken
+                        });
+                        if (res.code !== '0') {
+                            this.log(LoggerLevel.error, `[object.search.recordsAcrossObjectsWithIterator] Error searching records: code=${res.code}, msg=${res.msg}`);
+                            throw new Error(res.msg || `Search failed with code ${res.code}`);
+                        }
+                        const pageItems = ((_a = res.data) === null || _a === void 0 ? void 0 : _a.items) || ((_b = res.data) === null || _b === void 0 ? void 0 : _b.records) || ((_c = res.data) === null || _c === void 0 ? void 0 : _c.search_results) || [];
+                        if (Array.isArray(pageItems)) {
+                            items.push(...pageItems);
+                        }
+                        lastResponse = res;
+                        const nextPageToken = ((_d = res.data) === null || _d === void 0 ? void 0 : _d.next_page_token) || ((_e = res.data) === null || _e === void 0 ? void 0 : _e.page_token) || '';
+                        hasMore = Boolean(((_f = res.data) === null || _f === void 0 ? void 0 : _f.has_more) && nextPageToken);
+                        pageToken = nextPageToken;
+                    }
+                    return { items, lastResponse };
                 }
             },
+            /**
+             * 执行 OQL
+             * @description 执行对象查询语言，支持匿名参数 args 和具名参数 namedArgs
+             */
+            oql: async (params) => {
+                await this.ensureTokenValid();
+                const url = `/api/data/v1/namespaces/${this.namespace}/records/query`;
+                this.log(LoggerLevel.info, '[object.oql] Executing OQL');
+                const res = await this.axiosInstance.post(url, params, {
+                    headers: this.authHeaders(true)
+                });
+                this.log(LoggerLevel.debug, `[object.oql] OQL executed: code=${res.data.code}`);
+                this.log(LoggerLevel.trace, `[object.oql] Response: ${JSON.stringify(res.data)}`);
+                return res.data;
+            },
             create: {
                 /**
                  * 单条记录创建
@@ -1760,6 +2666,73 @@ class Client {
                 }
             }
         };
+        /**
+         * 常量对象模块
+         */
+        this.constant = {
+            /**
+             * 查询常量对象列表。object_name 可取 _currency、_country、_timeZone。
+             */
+            records: async (params) => {
+                const { object_name, data = {} } = params;
+                await this.ensureTokenValid();
+                const url = `/api/data/v1/namespaces/${this.namespace}/objects/${object_name}/records`;
+                this.log(LoggerLevel.info, `[constant.records] Fetching constant records: ${object_name}`);
+                const res = await this.axiosInstance.post(url, data, {
+                    headers: this.authHeaders(true)
+                });
+                this.log(LoggerLevel.debug, `[constant.records] Constant records fetched: ${object_name}, code=${res.data.code}`);
+                this.log(LoggerLevel.trace, `[constant.records] Response: ${JSON.stringify(res.data)}`);
+                return res.data;
+            },
+            /**
+             * 查询常量对象单条记录详情。
+             */
+            record: async (params) => {
+                const { object_name, record_id } = params;
+                await this.ensureTokenValid();
+                const url = `/api/data/v1/namespaces/${this.namespace}/objects/${object_name}/${record_id}`;
+                this.log(LoggerLevel.info, `[constant.record] Fetching constant record: ${object_name}.${record_id}`);
+                const res = await this.axiosInstance.get(url, {
+                    headers: this.authHeaders()
+                });
+                this.log(LoggerLevel.debug, `[constant.record] Constant record fetched: ${object_name}.${record_id}, code=${res.data.code}`);
+                this.log(LoggerLevel.trace, `[constant.record] Response: ${JSON.stringify(res.data)}`);
+                return res.data;
+            },
+            metadata: {
+                /**
+                 * 获取常量对象元数据。
+                 */
+                fields: async (params) => {
+                    const { object_name } = params;
+                    await this.ensureTokenValid();
+                    const url = `/api/data/v1/namespaces/${this.namespace}/meta/objects/${object_name}`;
+                    this.log(LoggerLevel.info, `[constant.metadata.fields] Fetching constant metadata: ${object_name}`);
+                    const res = await this.axiosInstance.get(url, {
+                        headers: this.authHeaders()
+                    });
+                    this.log(LoggerLevel.debug, `[constant.metadata.fields] Constant metadata fetched: ${object_name}, code=${res.data.code}`);
+                    this.log(LoggerLevel.trace, `[constant.metadata.fields] Response: ${JSON.stringify(res.data)}`);
+                    return res.data;
+                },
+                /**
+                 * 获取常量对象字段详情。
+                 */
+                field: async (params) => {
+                    const { object_name, field_name } = params;
+                    await this.ensureTokenValid();
+                    const url = `/api/data/v1/namespaces/${this.namespace}/meta/objects/${object_name}/fields/${field_name}`;
+                    this.log(LoggerLevel.info, `[constant.metadata.field] Fetching constant field metadata: ${object_name}.${field_name}`);
+                    const res = await this.axiosInstance.get(url, {
+                        headers: this.authHeaders()
+                    });
+                    this.log(LoggerLevel.debug, `[constant.metadata.field] Constant field metadata fetched: ${object_name}.${field_name}, code=${res.data.code}`);
+                    this.log(LoggerLevel.trace, `[constant.metadata.field] Response: ${JSON.stringify(res.data)}`);
+                    return res.data;
+                }
+            }
+        };
         /**
          * 部门 ID 交换模块
          */
@@ -1986,6 +2959,71 @@ class Client {
                 return result;
             }
         };
+        /**
+         * 集成模块
+         */
+        this.integration = {
+            lark: {
+                /**
+                 * 获取默认飞书集成 tenantAccessToken。
+                 */
+                defaultTenantAccessToken: async () => {
+                    await this.ensureTokenValid();
+                    const url = `/api/integration/v1/namespaces/${this.namespace}/defaultLark/tenantAccessToken`;
+                    this.log(LoggerLevel.info, '[integration.lark.defaultTenantAccessToken] Fetching default tenant token');
+                    const res = await this.axiosInstance.get(url, {
+                        headers: this.authHeaders()
+                    });
+                    this.log(LoggerLevel.debug, `[integration.lark.defaultTenantAccessToken] Token fetched: code=${res.data.code}`);
+                    this.log(LoggerLevel.trace, `[integration.lark.defaultTenantAccessToken] Response: ${JSON.stringify(res.data)}`);
+                    return res.data;
+                },
+                /**
+                 * 获取默认飞书集成 appAccessToken。
+                 */
+                defaultAppAccessToken: async () => {
+                    await this.ensureTokenValid();
+                    const url = `/api/integration/v1/namespaces/${this.namespace}/defaultLark/appAccessToken`;
+                    this.log(LoggerLevel.info, '[integration.lark.defaultAppAccessToken] Fetching default app token');
+                    const res = await this.axiosInstance.get(url, {
+                        headers: this.authHeaders()
+                    });
+                    this.log(LoggerLevel.debug, `[integration.lark.defaultAppAccessToken] Token fetched: code=${res.data.code}`);
+                    this.log(LoggerLevel.trace, `[integration.lark.defaultAppAccessToken] Response: ${JSON.stringify(res.data)}`);
+                    return res.data;
+                },
+                /**
+                 * 获取自定义飞书集成 tenantAccessToken。
+                 */
+                tenantAccessToken: async (params) => {
+                    const { lark_integration_api_name } = params;
+                    await this.ensureTokenValid();
+                    const url = `/api/integration/v1/namespaces/${this.namespace}/lark/tenantAccessToken/${lark_integration_api_name}`;
+                    this.log(LoggerLevel.info, `[integration.lark.tenantAccessToken] Fetching tenant token: ${lark_integration_api_name}`);
+                    const res = await this.axiosInstance.get(url, {
+                        headers: this.authHeaders()
+                    });
+                    this.log(LoggerLevel.debug, `[integration.lark.tenantAccessToken] Token fetched: ${lark_integration_api_name}, code=${res.data.code}`);
+                    this.log(LoggerLevel.trace, `[integration.lark.tenantAccessToken] Response: ${JSON.stringify(res.data)}`);
+                    return res.data;
+                },
+                /**
+                 * 获取自定义飞书集成 appAccessToken。
+                 */
+                appAccessToken: async (params) => {
+                    const { lark_integration_api_name } = params;
+                    await this.ensureTokenValid();
+                    const url = `/api/integration/v1/namespaces/${this.namespace}/lark/appAccessToken/${lark_integration_api_name}`;
+                    this.log(LoggerLevel.info, `[integration.lark.appAccessToken] Fetching app token: ${lark_integration_api_name}`);
+                    const res = await this.axiosInstance.get(url, {
+                        headers: this.authHeaders()
+                    });
+                    this.log(LoggerLevel.debug, `[integration.lark.appAccessToken] Token fetched: ${lark_integration_api_name}, code=${res.data.code}`);
+                    this.log(LoggerLevel.trace, `[integration.lark.appAccessToken] Response: ${JSON.stringify(res.data)}`);
+                    return res.data;
+                }
+            }
+        };
         /**
          * 云函数模块
          */
@@ -2439,6 +3477,59 @@ class Client {
                 }
             }
         };
+        /**
+         * 数据集模块
+         */
+        this.dataset = {
+            /**
+             * 查询数据集列表。
+             */
+            list: async (params) => {
+                await this.ensureTokenValid();
+                const url = `/v1/namespaces/${this.namespace}/datasets`;
+                const requestData = params || {};
+                this.log(LoggerLevel.info, '[dataset.list] Fetching datasets');
+                const res = await this.axiosInstance.post(url, requestData, {
+                    headers: this.authHeaders(true)
+                });
+                this.log(LoggerLevel.debug, `[dataset.list] Datasets fetched: code=${res.data.code}`);
+                this.log(LoggerLevel.trace, `[dataset.list] Response: ${JSON.stringify(res.data)}`);
+                return res.data;
+            },
+            /**
+             * 查询全部数据集 - 默认使用 cursor 分页。
+             */
+            listWithIterator: async (params) => {
+                var _a, _b, _c, _d, _e, _f, _g;
+                const pageSize = (params === null || params === void 0 ? void 0 : params.page_size) || 100;
+                let pageToken = '';
+                let hasMore = true;
+                let total = 0;
+                const datasets = [];
+                let lastResponse = null;
+                while (hasMore) {
+                    const res = await this.dataset.list({
+                        ...params,
+                        page_type: 'cursor',
+                        page_size: pageSize,
+                        page_token: pageToken
+                    });
+                    if (res.code !== '0') {
+                        this.log(LoggerLevel.error, `[dataset.listWithIterator] Error fetching datasets: code=${res.code}, msg=${res.msg}`);
+                        throw new Error(res.msg || `Fetch failed with code ${res.code}`);
+                    }
+                    const pageDatasets = ((_a = res.data) === null || _a === void 0 ? void 0 : _a.datasets) || ((_b = res.data) === null || _b === void 0 ? void 0 : _b.items) || [];
+                    if (Array.isArray(pageDatasets)) {
+                        datasets.push(...pageDatasets);
+                    }
+                    total = (_d = (_c = res.data) === null || _c === void 0 ? void 0 : _c.total) !== null && _d !== void 0 ? _d : total;
+                    lastResponse = res;
+                    pageToken = ((_e = res.data) === null || _e === void 0 ? void 0 : _e.next_page_token) || ((_f = res.data) === null || _f === void 0 ? void 0 : _f.page_token) || '';
+                    hasMore = Boolean(((_g = res.data) === null || _g === void 0 ? void 0 : _g.has_more) && pageToken);
+                }
+                return { total, datasets, lastResponse };
+            }
+        };
         /**
          * 自动化流程模块
          */
@@ -2507,6 +3598,218 @@ class Client {
                 }
             }
         };
+        /**
+         * 流程模块
+         */
+        this.workflow = {
+            execution: {
+                /**
+                 * 查询异步流程状态。
+                 */
+                status: async (params) => {
+                    const { execution_id } = params;
+                    await this.ensureTokenValid();
+                    const url = `/api/v2/workflow/namespaces/${this.namespace}/open_api/execution`;
+                    this.log(LoggerLevel.info, `[workflow.execution.status] Fetching execution status: ${execution_id}`);
+                    const res = await this.axiosInstance.get(url, {
+                        headers: this.authHeaders(true),
+                        params: { executionId: execution_id }
+                    });
+                    this.log(LoggerLevel.debug, `[workflow.execution.status] Execution status fetched: code=${res.data.code}`);
+                    this.log(LoggerLevel.trace, `[workflow.execution.status] Response: ${JSON.stringify(res.data)}`);
+                    return res.data;
+                }
+            },
+            definition: {
+                /**
+                 * 获取流程定义详情。
+                 */
+                detail: async (params) => {
+                    const { flow_api_name } = params;
+                    await this.ensureTokenValid();
+                    const url = `/api/flow/v1/namespaces/${this.namespace}/flow/${flow_api_name}`;
+                    this.log(LoggerLevel.info, `[workflow.definition.detail] Fetching flow definition: ${flow_api_name}`);
+                    const res = await this.axiosInstance.get(url, {
+                        headers: this.authHeaders()
+                    });
+                    this.log(LoggerLevel.debug, `[workflow.definition.detail] Flow definition fetched: ${flow_api_name}, code=${res.data.code}`);
+                    this.log(LoggerLevel.trace, `[workflow.definition.detail] Response: ${JSON.stringify(res.data)}`);
+                    return res.data;
+                }
+            },
+            userTask: {
+                /**
+                 * 获取包含人工任务的流程列表。
+                 */
+                flows: async (params) => {
+                    await this.ensureTokenValid();
+                    const url = `/api/flow/v1/namespaces/${this.namespace}/user_task/flow_list`;
+                    this.log(LoggerLevel.info, '[workflow.userTask.flows] Fetching user-task flows');
+                    const res = await this.axiosInstance.post(url, params, {
+                        headers: this.authHeaders(true)
+                    });
+                    this.log(LoggerLevel.debug, `[workflow.userTask.flows] User-task flows fetched: code=${res.data.code}`);
+                    this.log(LoggerLevel.trace, `[workflow.userTask.flows] Response: ${JSON.stringify(res.data)}`);
+                    return res.data;
+                },
+                /**
+                 * 获取包含人工任务的流程实例 ID 列表。
+                 */
+                instanceIds: async (params) => {
+                    const { page_size, page_token, start_time, end_time, api_ids } = params;
+                    await this.ensureTokenValid();
+                    const url = `/api/flow/v1/namespaces/${this.namespace}/instances/listids`;
+                    const data = {};
+                    if (start_time !== undefined)
+                        data.start_time = String(start_time);
+                    if (end_time !== undefined)
+                        data.end_time = String(end_time);
+                    if (api_ids !== undefined)
+                        data.api_ids = api_ids;
+                    this.log(LoggerLevel.info, '[workflow.userTask.instanceIds] Fetching workflow instance IDs');
+                    const res = await this.axiosInstance.get(url, {
+                        headers: this.authHeaders(true),
+                        params: { page_size, page_token },
+                        data
+                    });
+                    this.log(LoggerLevel.debug, `[workflow.userTask.instanceIds] Workflow instance IDs fetched: code=${res.data.code}`);
+                    this.log(LoggerLevel.trace, `[workflow.userTask.instanceIds] Response: ${JSON.stringify(res.data)}`);
+                    return res.data;
+                },
+                /**
+                 * 获取流程实例详情。
+                 */
+                instanceDetail: async (params) => {
+                    const { approval_instance_id, includes } = params;
+                    await this.ensureTokenValid();
+                    const url = `/api/flow/v1/namespaces/${this.namespace}/instances/${approval_instance_id}`;
+                    this.log(LoggerLevel.info, `[workflow.userTask.instanceDetail] Fetching workflow instance: ${approval_instance_id}`);
+                    const res = await this.axiosInstance.get(url, {
+                        headers: this.authHeaders(),
+                        params: includes ? { includes } : undefined
+                    });
+                    this.log(LoggerLevel.debug, `[workflow.userTask.instanceDetail] Workflow instance fetched: ${approval_instance_id}, code=${res.data.code}`);
+                    this.log(LoggerLevel.trace, `[workflow.userTask.instanceDetail] Response: ${JSON.stringify(res.data)}`);
+                    return res.data;
+                },
+                /**
+                 * 批量获取流程实例的任务列表。
+                 */
+                instanceTasks: async (params) => {
+                    const { approval_instance_ids, task_status } = params;
+                    await this.ensureTokenValid();
+                    const url = `/api/flow/v1/namespaces/${this.namespace}/instances/usertasks`;
+                    this.log(LoggerLevel.info, '[workflow.userTask.instanceTasks] Fetching workflow instance tasks');
+                    const res = await this.axiosInstance.get(url, {
+                        headers: this.authHeaders(true),
+                        params: task_status ? { task_status } : undefined,
+                        data: { approval_instance_ids }
+                    });
+                    this.log(LoggerLevel.debug, `[workflow.userTask.instanceTasks] Workflow instance tasks fetched: code=${res.data.code}`);
+                    this.log(LoggerLevel.trace, `[workflow.userTask.instanceTasks] Response: ${JSON.stringify(res.data)}`);
+                    return res.data;
+                },
+                /**
+                 * 获取任务列表。
+                 */
+                tasks: async (params) => {
+                    await this.ensureTokenValid();
+                    const url = `/api/flow/v1/namespaces/${this.namespace}/user_tasks`;
+                    this.log(LoggerLevel.info, '[workflow.userTask.tasks] Fetching user tasks');
+                    const res = await this.axiosInstance.post(url, params, {
+                        headers: this.authHeaders(true)
+                    });
+                    this.log(LoggerLevel.debug, `[workflow.userTask.tasks] User tasks fetched: code=${res.data.code}`);
+                    this.log(LoggerLevel.trace, `[workflow.userTask.tasks] Response: ${JSON.stringify(res.data)}`);
+                    return res.data;
+                },
+                /**
+                 * 获取任务详情。
+                 */
+                detail: async (params) => {
+                    const { task_id } = params;
+                    await this.ensureTokenValid();
+                    const url = `/api/flow/v1/namespaces/${this.namespace}/user_task/${task_id}/detail`;
+                    this.log(LoggerLevel.info, `[workflow.userTask.detail] Fetching user task: ${task_id}`);
+                    const res = await this.axiosInstance.get(url, {
+                        headers: this.authHeaders()
+                    });
+                    this.log(LoggerLevel.debug, `[workflow.userTask.detail] User task fetched: ${task_id}, code=${res.data.code}`);
+                    this.log(LoggerLevel.trace, `[workflow.userTask.detail] Response: ${JSON.stringify(res.data)}`);
+                    return res.data;
+                },
+                agree: async (params) => {
+                    const { approval_task_id, ...data } = params;
+                    await this.ensureTokenValid();
+                    const url = `/api/flow/v1/namespaces/${this.namespace}/user_task/${approval_task_id}/agree`;
+                    const res = await this.axiosInstance.post(url, data, { headers: this.authHeaders(true) });
+                    return res.data;
+                },
+                reject: async (params) => {
+                    const { approval_task_id, ...data } = params;
+                    await this.ensureTokenValid();
+                    const url = `/api/flow/v1/namespaces/${this.namespace}/user_task/${approval_task_id}/reject`;
+                    const res = await this.axiosInstance.post(url, data, { headers: this.authHeaders(true) });
+                    return res.data;
+                },
+                transfer: async (params) => {
+                    const { approval_task_id, ...data } = params;
+                    await this.ensureTokenValid();
+                    const url = `/api/flow/v1/namespaces/${this.namespace}/user_task/${approval_task_id}/trans`;
+                    const res = await this.axiosInstance.post(url, data, { headers: this.authHeaders(true) });
+                    return res.data;
+                },
+                addAssignee: async (params) => {
+                    const { approval_task_id, ...data } = params;
+                    await this.ensureTokenValid();
+                    const url = `/api/flow/v1/namespaces/${this.namespace}/user_task/${approval_task_id}/add_assignee`;
+                    const res = await this.axiosInstance.post(url, data, { headers: this.authHeaders(true) });
+                    return res.data;
+                },
+                cc: async (params) => {
+                    const { task_id, ...data } = params;
+                    await this.ensureTokenValid();
+                    const url = `/api/flow/v1/namespaces/${this.namespace}/user_task/${task_id}/cc`;
+                    const res = await this.axiosInstance.post(url, data, { headers: this.authHeaders(true) });
+                    return res.data;
+                },
+                expedite: async (params) => {
+                    const { task_id, ...data } = params;
+                    await this.ensureTokenValid();
+                    const url = `/api/flow/v1/namespaces/${this.namespace}/user_task/${task_id}/expediting`;
+                    const res = await this.axiosInstance.post(url, data, { headers: this.authHeaders(true) });
+                    return res.data;
+                },
+                cancelInstance: async (params) => {
+                    const { approval_instance_id, ...data } = params;
+                    await this.ensureTokenValid();
+                    const url = `/api/flow/v1/namespaces/${this.namespace}/instance/${approval_instance_id}/cancel`;
+                    const res = await this.axiosInstance.post(url, data, { headers: this.authHeaders(true) });
+                    return res.data;
+                },
+                rollbackPoints: async (params) => {
+                    const { task_id, ...data } = params;
+                    await this.ensureTokenValid();
+                    const url = `/api/flow/v1/namespaces/${this.namespace}/user_task/${task_id}/rollback_points`;
+                    const res = await this.axiosInstance.post(url, data, { headers: this.authHeaders(true) });
+                    return res.data;
+                },
+                rollback: async (params) => {
+                    const { task_id, ...data } = params;
+                    await this.ensureTokenValid();
+                    const url = `/api/flow/v1/namespaces/${this.namespace}/user_task/${task_id}/rollback`;
+                    const res = await this.axiosInstance.post(url, data, { headers: this.authHeaders(true) });
+                    return res.data;
+                },
+                startChat: async (params) => {
+                    const { task_id, ...data } = params;
+                    await this.ensureTokenValid();
+                    const url = `/api/flow/v1/namespaces/${this.namespace}/user_task/${task_id}/chat`;
+                    const res = await this.axiosInstance.post(url, data, { headers: this.authHeaders(true) });
+                    return res.data;
+                }
+            }
+        };
         /**
          * 数据对象结构管理模块（Schema）
          */
@@ -2519,12 +3822,13 @@ class Client {
              */
             create: async (params) => {
                 const { objects } = params;
+                const requestObjects = normalizeSchemaObjectsForWrite(objects);
                 await this.ensureTokenValid();
                 const url = `/v1/namespaces/${this.namespace}/objects/batch_create`;
                 this.log(LoggerLevel.info, `[schema.create] Creating ${objects.length} object(s)`);
                 this.log(LoggerLevel.trace, `[schema.create] Request URL: ${this.axiosInstance.defaults.baseURL}${url}`);
-                this.log(LoggerLevel.trace, `[schema.create] Request Body: ${JSON.stringify({ objects }, null, 2)}`);
-                const res = await this.axiosInstance.post(url, { objects }, {
+                this.log(LoggerLevel.trace, `[schema.create] Request Body: ${JSON.stringify({ objects: requestObjects }, null, 2)}`);
+                const res = await this.axiosInstance.post(url, { objects: requestObjects }, {
                     headers: {
                         Authorization: `${this.accessToken}`,
                         'Content-Type': 'application/json'
@@ -2581,12 +3885,13 @@ class Client {
              */
             update: async (params) => {
                 const { objects } = params;
+                const requestObjects = normalizeSchemaObjectsForWrite(objects);
                 await this.ensureTokenValid();
                 const url = `/v1/namespaces/${this.namespace}/objects/batch_update`;
                 this.log(LoggerLevel.info, `[schema.update] Updating ${objects.length} object(s)`);
                 this.log(LoggerLevel.trace, `[schema.update] Request URL: ${this.axiosInstance.defaults.baseURL}${url}`);
-                this.log(LoggerLevel.trace, `[schema.update] Request Body: ${JSON.stringify({ objects }, null, 2)}`);
-                const res = await this.axiosInstance.post(url, { objects }, {
+                this.log(LoggerLevel.trace, `[schema.update] Request Body: ${JSON.stringify({ objects: requestObjects }, null, 2)}`);
+                const res = await this.axiosInstance.post(url, { objects: requestObjects }, {
                     headers: {
                         Authorization: `${this.accessToken}`,
                         'Content-Type': 'application/json'
@@ -2630,6 +3935,48 @@ class Client {
                 this.log(LoggerLevel.debug, `[schema.delete] Objects deleted: code=${res.data.code}`);
                 this.log(LoggerLevel.trace, `[schema.delete] Response: ${JSON.stringify(res.data)}`);
                 return res.data;
+            },
+            /**
+             * 校验 schema 写接口响应，覆盖请求级错误、data=null 静默失败、item 级失败。
+             */
+            checkResponse: checkSchemaResponse,
+            /**
+             * 返回 schema 写接口响应校验结果，不抛错。
+             */
+            validateResponse: validateSchemaResponse,
+            /**
+             * 按 schema 单批 10 个对象的限制分批执行。
+             */
+            batchExecute,
+            /**
+             * 创建对象空壳。会移除 fields，并将 display/search 临时指向 _id。
+             */
+            createShells: async (params) => {
+                return createSchemaObjectShells(this, params.objects, params);
+            },
+            /**
+             * 幂等添加字段：先读 metadata，跳过已存在字段，再调用 schema.update。
+             */
+            addFieldsIdempotent: async (params) => {
+                return addFieldsIdempotent(this, params.object_name, params.fields, params);
+            },
+            /**
+             * 三阶段创建对象：空壳 -> 基础字段 -> lookup -> reference_field -> final settings。
+             */
+            createWithStages: async (params) => {
+                return createSchemaObjectsInStages(this, params.objects, params);
+            },
+            /**
+             * 写后验证对象和字段，可选导出 Markdown。
+             */
+            verifyObjects: async (params) => {
+                return verifySchemaObjects(this, params.object_names, params);
+            },
+            /**
+             * 删除全部自定义对象。高风险操作，必须显式传 confirm: true。
+             */
+            deleteAllCustomObjects: async (params) => {
+                return deleteAllCustomObjects(this, params);
             }
         };
         this.clientId = options.clientId;
@@ -2739,24 +4086,56 @@ class Client {
         this.log(LoggerLevel.debug, `[namespace] Current namespace: ${this.namespace}`);
         return this.namespace;
     }
+    authHeaders(includeContentType = false) {
+        return includeContentType
+            ? { Authorization: `${this.accessToken}`, 'Content-Type': 'application/json' }
+            : { Authorization: `${this.accessToken}` };
+    }
 }
 const apaas = {
     Client
 };
 
+exports.BATCH_UPDATE_REQUIREMENTS = BATCH_UPDATE_REQUIREMENTS;
+exports.COLUMN_NAME_SEMANTIC_RULES = COLUMN_NAME_SEMANTIC_RULES;
 exports.CREATE_OBJECT_EXAMPLE = CREATE_OBJECT_EXAMPLE;
+exports.FIELD_SCHEMA_RULES = FIELD_SCHEMA_RULES;
 exports.FIELD_TYPES = FIELD_TYPES;
 exports.LANGUAGE_CODES = LANGUAGE_CODES;
+exports.OPTION_COLOR_CODE_BY_NAME = OPTION_COLOR_CODE_BY_NAME;
+exports.OPTION_COLOR_LIST = OPTION_COLOR_LIST;
+exports.OPTION_COLOR_NAME_BY_CODE = OPTION_COLOR_NAME_BY_CODE;
+exports.OPTION_COLOR_RULES = OPTION_COLOR_RULES;
+exports.SCHEMA_BATCH_SIZE = SCHEMA_BATCH_SIZE;
 exports.SCHEMA_GUIDELINES = SCHEMA_GUIDELINES;
+exports.SCHEMA_TYPE_BY_METADATA_TYPE = SCHEMA_TYPE_BY_METADATA_TYPE;
+exports.SCHEMA_TYPE_MISMATCHES = SCHEMA_TYPE_MISMATCHES;
+exports.SQL_CONSTRAINT_TO_SETTINGS = SQL_CONSTRAINT_TO_SETTINGS;
+exports.SQL_TYPE_TO_SCHEMA_TYPE = SQL_TYPE_TO_SCHEMA_TYPE;
 exports.SYSTEM_FIELDS = SYSTEM_FIELDS;
 exports.UPDATE_OBJECT_ADD_FIELD_EXAMPLE = UPDATE_OBJECT_ADD_FIELD_EXAMPLE;
 exports.UPDATE_OBJECT_REMOVE_FIELD_EXAMPLE = UPDATE_OBJECT_REMOVE_FIELD_EXAMPLE;
 exports.UPDATE_OBJECT_REPLACE_FIELD_EXAMPLE = UPDATE_OBJECT_REPLACE_FIELD_EXAMPLE;
 exports.UPDATE_OBJECT_SETTINGS_EXAMPLE = UPDATE_OBJECT_SETTINGS_EXAMPLE;
+exports.addFieldsIdempotent = addFieldsIdempotent;
 exports.apaas = apaas;
+exports.batchExecute = batchExecute;
+exports.buildFieldRemovalPlan = buildFieldRemovalPlan;
+exports.checkSchemaResponse = checkSchemaResponse;
 exports.createMultilingualText = createMultilingualText;
+exports.createSchemaObjectShells = createSchemaObjectShells;
+exports.createSchemaObjectsInStages = createSchemaObjectsInStages;
+exports.deleteAllCustomObjects = deleteAllCustomObjects;
 exports.extractMultilingualText = extractMultilingualText;
 exports.getCustomFieldTypes = getCustomFieldTypes;
 exports.getFieldType = getFieldType;
+exports.getOptionColor = getOptionColor;
+exports.getOptionColorCode = getOptionColorCode;
 exports.getSystemFields = getSystemFields;
 exports.isSystemField = isSystemField;
+exports.isSystemSchemaName = isSystemSchemaName;
+exports.normalizeOptionColorForSchema = normalizeOptionColorForSchema;
+exports.normalizeSchemaObjectsForWrite = normalizeSchemaObjectsForWrite;
+exports.splitSchemaFieldsByDependency = splitSchemaFieldsByDependency;
+exports.validateSchemaResponse = validateSchemaResponse;
+exports.verifySchemaObjects = verifySchemaObjects;