zentao-api 0.3.3 → 0.4.0

package/dist/modules/registry.d.ts

@@ -1034,19 +1034,12 @@ export declare const MODULES: readonly [{
         readonly display: "获取产品计划列表，支持获取产品下的产品计划";
         readonly type: "list";
         readonly method: "get";
-        readonly path: "/{scope}/{scopeID}/productplans";
+        readonly path: "/products/{productID}/productplans";
         readonly resultType: "list";
         readonly pagerGetter: "pager";
         readonly resultGetter: "productplans";
         readonly pathParams: {
-            readonly scope: {
-                readonly description: "产品计划范围";
-                readonly options: readonly [{
-                    readonly value: "products";
-                    readonly label: "产品";
-                }];
-            };
-            readonly scopeID: "范围ID";
+            readonly productID: "所属产品ID";
         };
         readonly params: readonly [{
             readonly name: "browseType";
@@ -1242,7 +1235,7 @@ export declare const MODULES: readonly [{
         readonly resultGetter: "stories";
         readonly pathParams: {
             readonly scope: {
-                readonly description: "需求范围";
+                readonly description: "需求所属范围";
                 readonly options: readonly [{
                     readonly value: "products";
                     readonly label: "产品";
@@ -1254,7 +1247,7 @@ export declare const MODULES: readonly [{
                     readonly label: "执行";
                 }];
             };
-            readonly scopeID: "范围ID";
+            readonly scopeID: "所属范围ID";
         };
         readonly params: readonly [{
             readonly name: "browseType";
@@ -1577,19 +1570,12 @@ export declare const MODULES: readonly [{
         readonly display: "获取业务需求列表，支持获取产品下的业务需求";
         readonly type: "list";
         readonly method: "get";
-        readonly path: "/{scope}/{scopeID}/epics";
+        readonly path: "/products/{productID}/epics";
         readonly resultType: "list";
         readonly pagerGetter: "pager";
         readonly resultGetter: "epics";
         readonly pathParams: {
-            readonly scope: {
-                readonly description: "业务需求范围";
-                readonly options: readonly [{
-                    readonly value: "products";
-                    readonly label: "产品";
-                }];
-            };
-            readonly scopeID: "范围ID";
+            readonly productID: "所属产品ID";
         };
         readonly params: readonly [{
             readonly name: "browseType";
@@ -1903,19 +1889,12 @@ export declare const MODULES: readonly [{
         readonly display: "获取用户需求列表，支持获取产品下的用户需求";
         readonly type: "list";
         readonly method: "get";
-        readonly path: "/{scope}/{scopeID}/requirements";
+        readonly path: "/products/{productID}/requirements";
         readonly resultType: "list";
         readonly pagerGetter: "pager";
         readonly resultGetter: "requirements";
         readonly pathParams: {
-            readonly scope: {
-                readonly description: "用户需求范围";
-                readonly options: readonly [{
-                    readonly value: "products";
-                    readonly label: "产品";
-                }];
-            };
-            readonly scopeID: "范围ID";
+            readonly productID: "所属产品ID";
         };
         readonly params: readonly [{
             readonly name: "browseType";
@@ -2226,7 +2205,7 @@ export declare const MODULES: readonly [{
         readonly resultGetter: "bugs";
         readonly pathParams: {
             readonly scope: {
-                readonly description: "Bug范围";
+                readonly description: "Bug所属范围";
                 readonly options: readonly [{
                     readonly value: "products";
                     readonly label: "产品";
@@ -2238,7 +2217,7 @@ export declare const MODULES: readonly [{
                     readonly label: "执行";
                 }];
             };
-            readonly scopeID: "范围ID";
+            readonly scopeID: "所属范围ID";
         };
         readonly params: readonly [{
             readonly name: "browseType";
@@ -2560,7 +2539,7 @@ export declare const MODULES: readonly [{
         readonly resultGetter: "testcases";
         readonly pathParams: {
             readonly scope: {
-                readonly description: "测试用例范围";
+                readonly description: "测试用例所属范围";
                 readonly options: readonly [{
                     readonly value: "products";
                     readonly label: "产品";
@@ -2572,7 +2551,7 @@ export declare const MODULES: readonly [{
                     readonly label: "执行";
                 }];
             };
-            readonly scopeID: "范围ID";
+            readonly scopeID: "所属范围ID";
         };
         readonly params: readonly [{
             readonly name: "browseType";
@@ -2804,19 +2783,12 @@ export declare const MODULES: readonly [{
         readonly display: "获取任务列表，支持获取执行下的任务";
         readonly type: "list";
         readonly method: "get";
-        readonly path: "/{scope}/{scopeID}/tasks";
+        readonly path: "/executions/{executionID}/tasks";
         readonly resultType: "list";
         readonly pagerGetter: "pager";
         readonly resultGetter: "tasks";
         readonly pathParams: {
-            readonly scope: {
-                readonly description: "任务范围";
-                readonly options: readonly [{
-                    readonly value: "executions";
-                    readonly label: "执行";
-                }];
-            };
-            readonly scopeID: "范围ID";
+            readonly executionID: "所属执行ID";
         };
         readonly params: readonly [{
             readonly name: "status";
@@ -3180,19 +3152,12 @@ export declare const MODULES: readonly [{
         readonly display: "获取反馈列表，支持获取产品下的反馈";
         readonly type: "list";
         readonly method: "get";
-        readonly path: "/{scope}/{scopeID}/feedbacks";
+        readonly path: "/products/{productID}/feedbacks";
         readonly resultType: "list";
         readonly pagerGetter: "pager";
         readonly resultGetter: "feedbacks";
         readonly pathParams: {
-            readonly scope: {
-                readonly description: "反馈范围";
-                readonly options: readonly [{
-                    readonly value: "products";
-                    readonly label: "产品";
-                }];
-            };
-            readonly scopeID: "范围ID";
+            readonly productID: "所属产品ID";
         };
         readonly params: readonly [{
             readonly name: "browseType";
@@ -3440,19 +3405,12 @@ export declare const MODULES: readonly [{
         readonly display: "获取工单列表，支持获取产品下的工单";
         readonly type: "list";
         readonly method: "get";
-        readonly path: "/{scope}/{scopeID}/tickets";
+        readonly path: "/products/{productID}/tickets";
         readonly resultType: "list";
         readonly pagerGetter: "pager";
         readonly resultGetter: "tickets";
         readonly pathParams: {
-            readonly scope: {
-                readonly description: "工单范围";
-                readonly options: readonly [{
-                    readonly value: "products";
-                    readonly label: "产品";
-                }];
-            };
-            readonly scopeID: "范围ID";
+            readonly productID: "所属产品ID";
         };
         readonly params: readonly [{
             readonly name: "browseType";
@@ -3716,18 +3674,11 @@ export declare const MODULES: readonly [{
         readonly display: "获取应用列表，支持获取产品下的应用";
         readonly type: "list";
         readonly method: "get";
-        readonly path: "/{scope}/{scopeID}/systems";
+        readonly path: "/products/{productID}/systems";
         readonly resultType: "list";
         readonly pagerGetter: "pager";
         readonly pathParams: {
-            readonly scope: {
-                readonly description: "应用范围";
-                readonly options: readonly [{
-                    readonly value: "products";
-                    readonly label: "产品";
-                }];
-            };
-            readonly scopeID: "范围ID";
+            readonly productID: "所属产品ID";
         };
     }, {
         readonly name: "create";
@@ -3822,7 +3773,7 @@ export declare const MODULES: readonly [{
         readonly resultGetter: "builds";
         readonly pathParams: {
             readonly scope: {
-                readonly description: "版本范围";
+                readonly description: "版本所属范围";
                 readonly options: readonly [{
                     readonly value: "projects";
                     readonly label: "项目";
@@ -3831,7 +3782,7 @@ export declare const MODULES: readonly [{
                     readonly label: "执行";
                 }];
             };
-            readonly scopeID: "范围ID";
+            readonly scopeID: "所属范围ID";
         };
     }, {
         readonly name: "create";
@@ -3974,7 +3925,7 @@ export declare const MODULES: readonly [{
         readonly resultGetter: "testtasks";
         readonly pathParams: {
             readonly scope: {
-                readonly description: "测试单范围";
+                readonly description: "测试单所属范围";
                 readonly options: readonly [{
                     readonly value: "products";
                     readonly label: "产品";
@@ -3986,7 +3937,7 @@ export declare const MODULES: readonly [{
                     readonly label: "执行";
                 }];
             };
-            readonly scopeID: "范围ID";
+            readonly scopeID: "所属范围ID";
         };
     }, {
         readonly name: "create";
@@ -4132,19 +4083,12 @@ export declare const MODULES: readonly [{
         readonly display: "获取发布列表，支持获取产品下的发布";
         readonly type: "list";
         readonly method: "get";
-        readonly path: "/{scope}/{scopeID}/releases";
+        readonly path: "/products/{productID}/releases";
         readonly resultType: "list";
         readonly pagerGetter: "pager";
         readonly resultGetter: "releases";
         readonly pathParams: {
-            readonly scope: {
-                readonly description: "发布范围";
-                readonly options: readonly [{
-                    readonly value: "products";
-                    readonly label: "产品";
-                }];
-            };
-            readonly scopeID: "范围ID";
+            readonly productID: "所属产品ID";
         };
     }, {
         readonly name: "create";
@@ -4294,4 +4238,4 @@ export declare const MODULES: readonly [{
 }];
 export { type DefineModulesOptions, defineModules, defineModuleActions, extendModuleAction, resetModuleDefinitions, } from './define.js';
 export { applyBuiltinOverrides };
-export { getModule, getModuleAction, getModuleNames, isModuleName, } from './query.js';
+export { getModule, getModuleAction, getModuleActionParams, getModuleNames, isModuleName, } from './query.js';

package/dist/modules/registry.js

@@ -16,4 +16,4 @@ export { applyBuiltinOverrides };
 // - 注册为 store 的「重置后钩子」，使 resetModuleDefinitions 还原内置基线后自动重新应用。
 setPostResetHook(applyBuiltinOverrides);
 applyBuiltinOverrides();
-export { getModule, getModuleAction, getModuleNames, isModuleName, } from './query.js';
+export { getModule, getModuleAction, getModuleActionParams, getModuleNames, isModuleName, } from './query.js';

package/dist/modules/resolve.d.ts

@@ -1,6 +1,6 @@
-import type { ListPagerInfo, ModuleAction, ModuleDefinition, ResolvedModuleCommand } from '../types/index.js';
+import type { ListPagerInfo, ModuleAction, ModuleActionRequest, ModuleDefinition } from '../types/index.js';
 /** 将模块名、动作名和调用参数解析为实际 API 请求路径、查询参数和请求体。 */
-export declare function resolveModuleCommand(module: ModuleDefinition, actionName: string, params?: Record<string, unknown>): ResolvedModuleCommand;
+export declare function resolveActionRequest(module: ModuleDefinition, actionName: string, params?: Record<string, unknown>): ModuleActionRequest;
 /** 根据动作定义中的 resultGetter，从原始响应里提取业务数据。 */
 export declare function extractResult(action: ModuleAction, response: Record<string, unknown>, params?: Record<string, unknown>): unknown;
 /** 根据动作定义中的 pagerGetter，从原始响应里提取分页信息。 */

package/dist/modules/resolve.js

@@ -1,5 +1,5 @@
 import { ZentaoError } from '../misc/errors.js';
-import { getNestedValue, isRecord } from '../utils/index.js';
+import { getNestedValue, isBlank, isRecord } from '../utils/index.js';
 import { getModuleAction } from './registry.js';
 const SCOPE_MAP = {
     product: 'products',
@@ -11,7 +11,7 @@ const SCOPE_KEY_ORDER = ['execution', 'project', 'product'];
 function pickScope(params) {
     for (const key of SCOPE_KEY_ORDER) {
         const value = params[key] ?? params[`${key}ID`];
-        if (value === undefined || value === null || value === '')
+        if (isBlank(value))
             continue;
         const numberValue = Number(value);
         if (!Number.isNaN(numberValue)) {
@@ -24,7 +24,7 @@ function pickScope(params) {
 function resolvePath(action, values) {
     return action.path.replace(/\{(\w+)\}/g, (_, key) => {
         const value = values[key];
-        if (value === undefined || value === '') {
+        if (isBlank(value)) {
             throw new ZentaoError('E_MISSING_PARAM', { param: key });
         }
         return String(value);
@@ -37,18 +37,21 @@ function parseData(value) {
     if (typeof value === 'string') {
         try {
             const parsed = JSON.parse(value);
-            return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : undefined;
+            return isRecord(parsed) ? parsed : undefined;
         }
         catch {
             return undefined;
         }
     }
-    return value && typeof value === 'object' && !Array.isArray(value) ? value : undefined;
+    return isRecord(value) ? value : undefined;
 }
 const TRUTHY_STRINGS = new Set(['true', '1', 'yes', 'on']);
 const FALSY_STRINGS = new Set(['false', '0', 'no', 'off']);
-/** 按 OpenAPI schema 的基础类型对参数做轻量转换。 */
-function coerceValue(value, type, paramName) {
+/**
+ * 按 OpenAPI schema 的基础类型对参数做轻量转换。
+ * @param fromData 值是否来自 `params.data`（影响数组字段是否包装对象）。
+ */
+function coerceValue(value, type, paramName, fromData = false) {
     if (value === undefined || value === null)
         return value;
     if (type === 'number' || type === 'integer') {
@@ -75,50 +78,64 @@ function coerceValue(value, type, paramName) {
         }
         throw new ZentaoError('E_INVALID_PARAM', { param: paramName, value: String(value) });
     }
+    if (type === 'array') {
+        if (Array.isArray(value))
+            return value;
+        if (typeof value === 'string')
+            return value.split(',');
+        // 来自 params.data 的对象按原样保留，不强行包成单元素数组。
+        if (fromData && isRecord(value))
+            return value;
+        return [value];
+    }
     return value;
 }
-/** 将模块名、动作名和调用参数解析为实际 API 请求路径、查询参数和请求体。 */
-export function resolveModuleCommand(module, actionName, params = {}) {
-    const action = getModuleAction(module.name, actionName);
-    const pathValues = {};
+/** 解析路径占位符的取值：scope 列表前缀、对象 ID，以及默认值补齐。 */
+function resolvePathValues(module, action, params) {
+    const values = {};
     const pathParamNames = Object.keys(action.pathParams ?? {});
     // 生成定义中的 scope 列表接口会统一成 /{scope}/{scopeID}/xxx。
     if (pathParamNames.includes('scope')) {
         const scope = pickScope(params);
         if (!scope)
             throw new ZentaoError('E_MISSING_PARAM', { param: 'product/project/execution' });
-        pathValues.scope = scope.scope;
-        pathValues.scopeID = scope.scopeID;
+        values.scope = scope.scope;
+        values.scopeID = scope.scopeID;
     }
+    // 对象 ID 可来自 `id`、`{module}ID` 或路径中的 `xxxID` 占位符。
     const idParamName = pathParamNames.find((key) => key.endsWith('ID') && key !== 'scopeID');
     const idValue = params.id ?? params[`${module.name}ID`] ?? (idParamName ? params[idParamName] : undefined);
-    const id = idValue === undefined ? undefined : Number(idValue);
-    if (idParamName && id !== undefined && !Number.isNaN(id)) {
-        pathValues[idParamName] = id;
+    const idNumber = idValue === undefined ? Number.NaN : Number(idValue);
+    const id = Number.isNaN(idNumber) ? undefined : idNumber;
+    if (idParamName && id !== undefined) {
+        values[idParamName] = id;
     }
     // pathParams 中未显式传值的参数，可从定义里的默认值或第一个可选项补齐。
     for (const key of pathParamNames) {
-        if (key === 'scope' || key === 'scopeID' || pathValues[key] !== undefined)
+        if (key === 'scope' || key === 'scopeID' || values[key] !== undefined)
             continue;
         const definition = action.pathParams?.[key];
         const value = params[key];
         if (value !== undefined) {
-            pathValues[key] = value;
+            values[key] = value;
             continue;
         }
         if (typeof definition === 'object') {
             if (definition.defaultValue !== undefined) {
-                pathValues[key] = definition.defaultValue;
+                values[key] = definition.defaultValue;
             }
             else if (definition.options?.[0]?.value !== undefined) {
-                pathValues[key] = definition.options[0].value;
+                values[key] = definition.options[0].value;
             }
         }
-        if (pathValues[key] === undefined) {
+        if (values[key] === undefined) {
             throw new ZentaoError('E_MISSING_PARAM', { param: key });
         }
     }
-    // 查询参数只从 action.params 中声明过的字段生成，避免把 body 字段误放到 URL 上。
+    return { values, id };
+}
+/** 仅从 action.params 中声明过的字段生成查询参数，避免把 body 字段误放到 URL 上。 */
+function buildQuery(action, params) {
     const query = {};
     for (const param of action.params ?? []) {
         let value = params[param.name];
@@ -135,41 +152,43 @@ export function resolveModuleCommand(module, actionName, params = {}) {
             query[param.name] = value;
         }
     }
-    let data = parseData(params.data);
-    if (action.requestBody?.schema?.type === 'object') {
-        data = data ? { ...data } : {};
-        const schema = action.requestBody.schema;
-        const required = new Set(schema.required ?? []);
-        for (const [key, property] of Object.entries(schema.properties ?? {})) {
-            // body 字段优先级：params.data 中的字段 > 平铺 params 字段 > schema 默认值。
-            const hasDataValue = Object.prototype.hasOwnProperty.call(data, key);
-            const hasParamValue = Object.prototype.hasOwnProperty.call(params, key);
-            let value = hasDataValue ? data[key] : hasParamValue ? params[key] : property.defaultValue;
-            if (value === undefined && (property.required || required.has(key))) {
-                throw new ZentaoError('E_MISSING_PARAM', { param: key });
-            }
-            value = coerceValue(value, property.type, key);
-            if (property.type === 'array' && value !== undefined && value !== null && !Array.isArray(value)) {
-                if (typeof value === 'string') {
-                    value = value.split(',');
-                }
-                else if (!hasDataValue || !isRecord(value)) {
-                    value = [value];
-                }
-            }
-            if (value !== undefined) {
-                data[key] = value;
-            }
+    return query;
+}
+/** 按 requestBody schema 组装请求体，并对各字段做取值优先级解析与类型转换。 */
+function buildRequestBody(action, params) {
+    const base = parseData(params.data);
+    if (action.requestBody?.schema?.type !== 'object')
+        return base;
+    const data = base ? { ...base } : {};
+    const schema = action.requestBody.schema;
+    const required = new Set(schema.required ?? []);
+    for (const [key, property] of Object.entries(schema.properties ?? {})) {
+        // body 字段优先级：params.data 中的字段 > 平铺 params 字段 > schema 默认值。
+        const hasDataValue = Object.prototype.hasOwnProperty.call(data, key);
+        const hasParamValue = Object.prototype.hasOwnProperty.call(params, key);
+        const raw = hasDataValue ? data[key] : hasParamValue ? params[key] : property.defaultValue;
+        if (raw === undefined && (property.required || required.has(key))) {
+            throw new ZentaoError('E_MISSING_PARAM', { param: key });
+        }
+        const value = coerceValue(raw, property.type, key, hasDataValue);
+        if (value !== undefined) {
+            data[key] = value;
         }
     }
+    return data;
+}
+/** 将模块名、动作名和调用参数解析为实际 API 请求路径、查询参数和请求体。 */
+export function resolveActionRequest(module, actionName, params = {}) {
+    const action = getModuleAction(module.name, actionName);
+    const { values, id } = resolvePathValues(module, action, params);
     return {
         module: module.name,
         action,
         params,
-        path: resolvePath(action, pathValues),
-        query,
-        data,
-        id: id === undefined || Number.isNaN(id) ? undefined : id,
+        path: resolvePath(action, values),
+        query: buildQuery(action, params),
+        data: buildRequestBody(action, params),
+        id,
     };
 }
 /** 根据动作定义中的 resultGetter，从原始响应里提取业务数据。 */

package/dist/request/index.js

@@ -1,7 +1,7 @@
 import { ZentaoError } from '../misc/errors.js';
 import { getGlobalOptions } from '../misc/global-options.js';
 import { getModule, getModuleAction } from '../modules/registry.js';
-import { extractPager, extractResult, resolveModuleCommand } from '../modules/resolve.js';
+import { extractPager, extractResult, resolveActionRequest } from '../modules/resolve.js';
 import { isRecord, processData } from '../utils/index.js';
 /** 将 `moduleName`、`moduleName/methodName` 或 `moduleName/<objectID>` 请求名拆成模块名、动作名和对象 ID。 */
 function splitRequestName(name) {
@@ -50,7 +50,8 @@ function getExplicitDataKeys(data) {
  * 在执行 `update` 动作前，用当前对象的现值填充用户未显式传入的 body 字段。
  *
  * 仅当模块存在 `type: 'get'` 动作且 update 动作声明了对象类型 body schema 时生效；
- * 否则原样返回参数。GET 失败或返回非对象时同样跳过填充，交由后续 PUT 正常处理。
+ * 否则原样返回参数。GET 返回失败状态时会抛出 `E_API_FAILED`，避免继续发送未补齐的 PUT；
+ * GET 成功但返回非对象时跳过填充，交由后续 PUT 正常处理。
  *
  * 字段归属判断同时覆盖平铺 `params` 字段与 `params.data` 中的字段；只有 schema 中声明、
  * 用户未传且当前对象存在的字段才会被补齐，避免覆盖用户本次想修改的字段。
@@ -64,7 +65,7 @@ async function autoFillUpdateParams(module, action, params, options) {
         client: options.client,
         timeout: options.timeout,
         insecure: options.insecure,
-        throwOnFail: options.throwOnFail,
+        throwOnFail: true,
     })).data;
     if (!isRecord(current))
         return params;
@@ -188,7 +189,7 @@ export async function request(name, params = {}, options = {}) {
     const finalParams = action.type === 'update' && (options.autoFill ?? globals.autoFill)
         ? await autoFillUpdateParams(module, action, mergedParams, options)
         : mergedParams;
-    const command = resolveModuleCommand(module, actionName, finalParams);
+    const command = resolveActionRequest(module, actionName, finalParams);
     const raw = await client.request(command.path, {
         method: String(command.action.method).toUpperCase(),
         query: command.query,
@@ -196,6 +197,9 @@ export async function request(name, params = {}, options = {}) {
         timeout: options.timeout ?? globals.timeout,
         insecure: options.insecure ?? globals.insecure,
     });
+    if (options.raw) {
+        return raw;
+    }
     // limit 现归入本地处理选项；本次调用优先，缺省回落到全局默认。
     const processOptions = { ...options, limit: options.limit ?? globals.limit };
     const response = normalizeResponse(command, raw, processOptions);

package/dist/types/module.d.ts

@@ -11,10 +11,14 @@ export type ModuleActionParamOption = {
     readonly value: unknown;
     readonly label: string;
 };
+/** 模块动作参数角色。 */
+export type ModuleActionParamRole = 'query' | 'path' | 'body';
 /** 模块动作的查询参数定义。 */
 export interface ModuleActionParam {
     /** 参数名称。 */
     name: string;
+    /** 参数角色。 */
+    role?: ModuleActionParamRole;
     /** 参数说明。 */
     description?: string;
     /** 是否必填。 */
@@ -125,7 +129,7 @@ export interface ModuleDefinition {
     actions: readonly ModuleAction[];
 }
 /** 将模块动作和参数解析后的可执行请求描述。 */
-export interface ResolvedModuleCommand {
+export interface ModuleActionRequest {
     /** 模块名称。 */
     module: string;
     /** 匹配到的动作定义。 */

package/dist/types/options.d.ts

@@ -48,4 +48,6 @@ export interface RequestOptions extends ProcessListOptions {
      * 不传时回落到全局 `autoFill`，默认 false。
      */
     autoFill?: boolean;
+    /** 是否返回原始响应体，默认 false。 */
+    raw?: boolean;
 }

package/dist/utils/index.d.ts

@@ -1,4 +1,4 @@
-export { isRecord, getNestedValue } from './object.js';
+export { isRecord, isBlank, getNestedValue } from './object.js';
 export { asArray } from './array.js';
 export { normalizeSiteUrl } from './url.js';
 export { pickFields, pickFieldsSingle, filterData, searchData, sortData, processData, } from './data.js';

package/dist/utils/index.js

@@ -1,4 +1,4 @@
-export { isRecord, getNestedValue } from './object.js';
+export { isRecord, isBlank, getNestedValue } from './object.js';
 export { asArray } from './array.js';
 export { normalizeSiteUrl } from './url.js';
 export { pickFields, pickFieldsSingle, filterData, searchData, sortData, processData, } from './data.js';

package/dist/utils/object.d.ts

@@ -1,3 +1,5 @@
 /** 判断值是否为普通对象（非数组、非 null）。 */
 export declare function isRecord(value: unknown): value is Record<string, unknown>;
+/** 判断值是否为“空”（undefined、null 或空字符串）。 */
+export declare function isBlank(value: unknown): boolean;
 export declare function getNestedValue(obj: unknown, path: string): unknown;

package/dist/utils/object.js

@@ -2,6 +2,10 @@
 export function isRecord(value) {
     return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
 }
+/** 判断值是否为“空”（undefined、null 或空字符串）。 */
+export function isBlank(value) {
+    return value === undefined || value === null || value === '';
+}
 export function getNestedValue(obj, path) {
     const keys = path.split('.');
     let current = obj;

package/dist/version.js

@@ -1,5 +1,5 @@
-const fallbackBuild = "2026-06-30T10:00:59.615Z";
-const fallbackVersion = "0.3.3";
+const fallbackBuild = "2026-07-21T02:40:34.356Z";
+const fallbackVersion = "0.4.0";
 /**
  * 构建标识，由构建脚本通过 `__ZENTAO_API_BUILD__` 注入。
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zentao-api",
-  "version": "0.3.3",
+  "version": "0.4.0",
   "type": "module",
   "description": "Browser and Node.js SDK for ZenTao API",
   "license": "MIT",