zentao-api 0.4.0 → 0.5.0

package/dist/modules/override.js

@@ -110,4 +110,18 @@ export function applyBuiltinOverrides() {
             return action;
         });
     });
+    // 为 task/create|update 补充 parent 字段（创建子任务）
+    ['create', 'update'].forEach((actionName) => {
+        extendModuleAction('task', actionName, (action) => {
+            const properties = action.requestBody?.schema?.properties;
+            if (properties && !properties.parent) {
+                properties.parent = {
+                    type: 'integer',
+                    description: '父任务',
+                    format: 'int32',
+                };
+            }
+            return action;
+        });
+    });
 }

package/dist/modules/query.d.ts

@@ -6,10 +6,9 @@ import type { ModuleAction, ModuleActionParam, ModuleActionParamRole, ModuleDefi
  * 任何写入尝试在严格模式下会抛 `TypeError`；如需修改请使用 {@link defineModules}。
  *
  * @param moduleName - 模块名。
- * @returns 已注册的模块定义。
- * @throws {ZentaoError} `E_INVALID_MODULE` —— 模块未注册。
+ * @returns 已注册的模块定义；模块未注册时返回 `undefined`。
  */
-export declare function getModule(moduleName: string): ModuleDefinition;
+export declare function getModule(moduleName: string): ModuleDefinition | undefined;
 /**
  * 获取指定模块下的某个动作。
  *
@@ -23,10 +22,9 @@ export declare function getModule(moduleName: string): ModuleDefinition;
  *
  * @param moduleName - 模块名（大小写不敏感）。
  * @param actionName - 动作名（大小写不敏感）；支持 `ls` 作为 `list` 的别名。
- * @returns 匹配到的动作定义。
- * @throws {ZentaoError} `E_INVALID_MODULE`（模块未注册）或 `E_INVALID_ACTION`（动作不存在）。
+ * @returns 匹配到的动作定义；模块未注册或动作不存在时返回 `undefined`。
  */
-export declare function getModuleAction(moduleName: string, actionName: string): ModuleAction;
+export declare function getModuleAction(moduleName: string, actionName: string): ModuleAction | undefined;
 /**
  * 获取指定模块下的某个动作的参数。
  *
@@ -54,3 +52,10 @@ export declare function getModuleNames(): string[];
  * @returns 已注册返回 `true`，否则 `false`。
  */
 export declare function isModuleName(moduleName: string): boolean;
+/**
+ * 获取对象属性。
+ *
+ * @param objectType - 对象类型。
+ * @returns 对象属性。
+ */
+export declare function getObjectProps(objectType: string): Record<string, string>;

package/dist/modules/query.js

@@ -1,4 +1,4 @@
-import { ZentaoError } from '../misc/errors.js';
+import { objectProps } from './object-props.js';
 import { getModuleMapState, getModulesState } from './registry-store.js';
 /**
  * 获取模块定义。
@@ -7,15 +7,10 @@ import { getModuleMapState, getModulesState } from './registry-store.js';
  * 任何写入尝试在严格模式下会抛 `TypeError`；如需修改请使用 {@link defineModules}。
  *
  * @param moduleName - 模块名。
- * @returns 已注册的模块定义。
- * @throws {ZentaoError} `E_INVALID_MODULE` —— 模块未注册。
+ * @returns 已注册的模块定义；模块未注册时返回 `undefined`。
  */
 export function getModule(moduleName) {
-    const module = getModuleMapState().get(moduleName.toLowerCase());
-    if (!module) {
-        throw new ZentaoError('E_INVALID_MODULE', { module: moduleName });
-    }
-    return module;
+    return getModuleMapState().get(moduleName.toLowerCase());
 }
 /**
  * 获取指定模块下的某个动作。
@@ -30,11 +25,12 @@ export function getModule(moduleName) {
  *
  * @param moduleName - 模块名（大小写不敏感）。
  * @param actionName - 动作名（大小写不敏感）；支持 `ls` 作为 `list` 的别名。
- * @returns 匹配到的动作定义。
- * @throws {ZentaoError} `E_INVALID_MODULE`（模块未注册）或 `E_INVALID_ACTION`（动作不存在）。
+ * @returns 匹配到的动作定义；模块未注册或动作不存在时返回 `undefined`。
  */
 export function getModuleAction(moduleName, actionName) {
     const module = getModule(moduleName);
+    if (!module)
+        return undefined;
     const normalized = actionName === 'ls' ? 'list' : actionName;
     const direct = module.actions.find((action) => String(action.name).toLowerCase() === normalized.toLowerCase());
     if (direct)
@@ -45,7 +41,7 @@ export function getModuleAction(moduleName, actionName) {
         if (custom)
             return custom;
     }
-    throw new ZentaoError('E_INVALID_ACTION', { module: moduleName, action: actionName });
+    return undefined;
 }
 /**
  * 获取指定模块下的某个动作的参数。
@@ -125,3 +121,12 @@ export function getModuleNames() {
 export function isModuleName(moduleName) {
     return getModuleMapState().has(moduleName.toLowerCase());
 }
+/**
+ * 获取对象属性。
+ *
+ * @param objectType - 对象类型。
+ * @returns 对象属性。
+ */
+export function getObjectProps(objectType) {
+    return objectProps[objectType];
+}

package/dist/modules/registry.d.ts

@@ -4238,4 +4238,4 @@ export declare const MODULES: readonly [{
 }];
 export { type DefineModulesOptions, defineModules, defineModuleActions, extendModuleAction, resetModuleDefinitions, } from './define.js';
 export { applyBuiltinOverrides };
-export { getModule, getModuleAction, getModuleActionParams, getModuleNames, isModuleName, } from './query.js';
+export { getModule, getModuleAction, getModuleActionParams, getModuleNames, isModuleName, getObjectProps, } from './query.js';

package/dist/modules/registry.js

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

package/dist/modules/resolve.js

@@ -6,9 +6,28 @@ const SCOPE_MAP = {
     project: 'projects',
     execution: 'executions',
 };
+const VALID_SCOPES = new Set(Object.values(SCOPE_MAP));
 const SCOPE_KEY_ORDER = ['execution', 'project', 'product'];
-/** 从调用参数中推断作用域列表路径，优先级为执行 > 项目 > 产品。 */
+/**
+ * 从调用参数中推断作用域列表路径。
+ *
+ * 优先使用显式 `scope` + `scopeID`；二者缺一则回落到别名推断，
+ * 别名优先级为执行 > 项目 > 产品。
+ */
 function pickScope(params) {
+    const explicitScope = params.scope;
+    const explicitScopeID = params.scopeID;
+    if (!isBlank(explicitScope) && !isBlank(explicitScopeID)) {
+        const scope = String(explicitScope);
+        if (!VALID_SCOPES.has(scope)) {
+            throw new ZentaoError('E_INVALID_PARAM', { param: 'scope', value: scope });
+        }
+        const scopeID = Number(explicitScopeID);
+        if (Number.isNaN(scopeID)) {
+            throw new ZentaoError('E_INVALID_PARAM', { param: 'scopeID', value: String(explicitScopeID) });
+        }
+        return { scope, scopeID };
+    }
     for (const key of SCOPE_KEY_ORDER) {
         const value = params[key] ?? params[`${key}ID`];
         if (isBlank(value))
@@ -98,7 +117,7 @@ function resolvePathValues(module, action, params) {
     if (pathParamNames.includes('scope')) {
         const scope = pickScope(params);
         if (!scope)
-            throw new ZentaoError('E_MISSING_PARAM', { param: 'product/project/execution' });
+            throw new ZentaoError('E_MISSING_PARAM', { param: 'scope/scopeID or product/project/execution' });
         values.scope = scope.scope;
         values.scopeID = scope.scopeID;
     }
@@ -180,6 +199,9 @@ function buildRequestBody(action, params) {
 /** 将模块名、动作名和调用参数解析为实际 API 请求路径、查询参数和请求体。 */
 export function resolveActionRequest(module, actionName, params = {}) {
     const action = getModuleAction(module.name, actionName);
+    if (!action) {
+        throw new ZentaoError('E_INVALID_ACTION', { module: module.name, action: actionName });
+    }
     const { values, id } = resolvePathValues(module, action, params);
     return {
         module: module.name,

package/dist/request/index.d.ts

@@ -70,6 +70,8 @@ type BodyParams<A> = A extends {
     data?: string | Record<string, unknown>;
 };
 type ScopedParams<PathParams> = 'scope' extends keyof PathParams ? {
+    scope?: 'products' | 'projects' | 'executions' | (string & {});
+    scopeID?: string | number;
     product?: string | number;
     productID?: string | number;
     project?: string | number;

package/dist/request/index.js

@@ -176,6 +176,9 @@ export async function request(name, params = {}, options = {}) {
     }
     const { moduleName, actionName, id } = splitRequestName(name);
     const module = getModule(moduleName);
+    if (!module) {
+        throw new ZentaoError('E_INVALID_MODULE', { module: moduleName });
+    }
     // recPerPage 是最常用的列表参数，允许在全局或本次调用中统一覆盖。
     const recPerPage = params.recPerPage ?? options.recPerPage ?? globals.recPerPage;
     const mergedParams = {
@@ -186,6 +189,9 @@ export async function request(name, params = {}, options = {}) {
     // autoFill：update 动作先 GET 当前对象，用现值补齐用户未显式传入的字段，
     // 避免禅道 PUT 把未提交字段覆盖为空。
     const action = getModuleAction(moduleName, actionName);
+    if (!action) {
+        throw new ZentaoError('E_INVALID_ACTION', { module: moduleName, action: actionName });
+    }
     const finalParams = action.type === 'update' && (options.autoFill ?? globals.autoFill)
         ? await autoFillUpdateParams(module, action, mergedParams, options)
         : mergedParams;

package/dist/version.js

@@ -1,5 +1,5 @@
-const fallbackBuild = "2026-07-21T02:40:34.356Z";
-const fallbackVersion = "0.4.0";
+const fallbackBuild = "2026-08-11T11:36:59.266Z";
+const fallbackVersion = "0.5.0";
 /**
  * 构建标识，由构建脚本通过 `__ZENTAO_API_BUILD__` 注入。
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zentao-api",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "type": "module",
   "description": "Browser and Node.js SDK for ZenTao API",
   "license": "MIT",
@@ -70,6 +70,8 @@
     "vitepress": "^1.6.4"
   },
   "engines": {
-    "node": ">=18"
-  }
+    "node": ">=18",
+    "bun": ">=1.0.0"
+  },
+  "packageManager": "bun@1.3.13"
 }