zentao-api 0.6.5 → 0.6.7

package/dist/misc/errors.d.ts

@@ -10,8 +10,12 @@ export declare const ERRORS: {
     readonly E_HTTP_ERROR: "HTTP request failed: {status} {statusText}";
     readonly E_NETWORK_ERROR: "Network request failed: {message}";
     readonly E_TIMEOUT: "Request timed out.";
+    readonly E_ABORTED: "Request was aborted.";
     readonly E_INSECURE_BROWSER: "The insecure option is only supported in Node.js runtimes.";
     readonly E_LOGIN_FAILED: "ZenTao login failed.";
+    readonly E_INVALID_ZENTAO_CONFIG: "ZenTao configuration must be an object with a non-empty version.";
+    readonly E_INVALID_ZENTAO_VERSION: "Invalid ZenTao version: {version}";
+    readonly E_UNSUPPORTED_ZENTAO_VERSION: "Action {action} does not support ZenTao {version}; minimum versions: {minVersion}";
     readonly E_INVALID_PROFILE: "Invalid ZenTao profile.";
     readonly E_NO_PROFILE: "No ZenTao profile is configured.";
     readonly E_PROFILE_NOT_FOUND: "ZenTao profile not found: {profileKey}";
@@ -35,6 +39,8 @@ export declare const ERRORS: {
 };
 /** SDK 已知错误码，对应 {@link ERRORS} 的 key。 */
 export type ErrorCode = keyof typeof ERRORS;
+/** 仅配置获取失败可选择跳过；取消、版本错误和持久化错误仍须抛出。 @internal */
+export declare function isZentaoConfigFetchError(error: unknown): boolean;
 /**
  * SDK 统一错误类型。
  *

package/dist/misc/errors.js

@@ -10,8 +10,12 @@ export const ERRORS = {
     E_HTTP_ERROR: 'HTTP request failed: {status} {statusText}',
     E_NETWORK_ERROR: 'Network request failed: {message}',
     E_TIMEOUT: 'Request timed out.',
+    E_ABORTED: 'Request was aborted.',
     E_INSECURE_BROWSER: 'The insecure option is only supported in Node.js runtimes.',
     E_LOGIN_FAILED: 'ZenTao login failed.',
+    E_INVALID_ZENTAO_CONFIG: 'ZenTao configuration must be an object with a non-empty version.',
+    E_INVALID_ZENTAO_VERSION: 'Invalid ZenTao version: {version}',
+    E_UNSUPPORTED_ZENTAO_VERSION: 'Action {action} does not support ZenTao {version}; minimum versions: {minVersion}',
     E_INVALID_PROFILE: 'Invalid ZenTao profile.',
     E_NO_PROFILE: 'No ZenTao profile is configured.',
     E_PROFILE_NOT_FOUND: 'ZenTao profile not found: {profileKey}',
@@ -33,6 +37,11 @@ export const ERRORS = {
     E_UPLOAD_FILE_TOO_LARGE: 'Upload file is {size} bytes and exceeds the {limit} byte limit.',
     E_INVALID_UPLOAD_SOURCE: 'Invalid upload source for field: {field}',
 };
+/** 仅配置获取失败可选择跳过；取消、版本错误和持久化错误仍须抛出。 @internal */
+export function isZentaoConfigFetchError(error) {
+    return error instanceof ZentaoError && (error.code === 'E_HTTP_ERROR' || error.code === 'E_NETWORK_ERROR'
+        || error.code === 'E_TIMEOUT' || error.code === 'E_INVALID_ZENTAO_CONFIG');
+}
 /**
  * SDK 统一错误类型。
  *

package/dist/misc/zentao-version.d.ts

@@ -0,0 +1,11 @@
+interface ZentaoVersion {
+    edition: string;
+    parts: number[];
+}
+/** 只接受开源版、biz、max、ipd 系列的点分数字正式版本。 */
+export declare function parseZentaoVersion(version: string): ZentaoVersion;
+/** 注册和生成时共用，缺少版本、格式非法或同系列重复均拒绝。 */
+export declare function validateMinVersion(value: unknown): asserts value is readonly string[];
+/** 同系列逐段比较，缺少的数字段视为零；未列出的系列不支持。 */
+export declare function supportsZentaoVersion(version: ZentaoVersion, minimums: readonly string[]): boolean;
+export {};

package/dist/misc/zentao-version.js

@@ -0,0 +1,35 @@
+import { ZentaoError } from './errors.js';
+/** 只接受开源版、biz、max、ipd 系列的点分数字正式版本。 */
+export function parseZentaoVersion(version) {
+    const match = typeof version === 'string' ? version.trim().match(/^(biz|max|ipd)?(\d+(?:\.\d+)*)$/i) : null;
+    const parts = match?.[2].split('.').map(Number);
+    if (!match || !parts?.every(Number.isSafeInteger)) {
+        throw new ZentaoError('E_INVALID_ZENTAO_VERSION', { version: String(version) });
+    }
+    return { edition: (match[1] ?? '').toLowerCase(), parts };
+}
+/** 注册和生成时共用，缺少版本、格式非法或同系列重复均拒绝。 */
+export function validateMinVersion(value) {
+    try {
+        if (!Array.isArray(value) || value.length === 0)
+            throw new Error('minVersion must be a non-empty array.');
+        const editions = Array.from(value, version => parseZentaoVersion(version).edition);
+        if (new Set(editions).size !== editions.length)
+            throw new Error('Duplicate editions in minVersion.');
+    }
+    catch (error) {
+        throw new ZentaoError('E_INVALID_ACTION_DEFINITION', undefined, error);
+    }
+}
+/** 同系列逐段比较，缺少的数字段视为零；未列出的系列不支持。 */
+export function supportsZentaoVersion(version, minimums) {
+    const minimum = minimums.map(parseZentaoVersion).find(item => item.edition === version.edition);
+    if (!minimum)
+        return false;
+    for (let index = 0; index < Math.max(version.parts.length, minimum.parts.length); index++) {
+        const difference = (version.parts[index] ?? 0) - (minimum.parts[index] ?? 0);
+        if (difference !== 0)
+            return difference > 0;
+    }
+    return true;
+}

package/dist/modules/define.d.ts

@@ -21,7 +21,8 @@ export interface DefineModulesOptions {
  *
  * @param input - 单个或一组模块定义。
  * @param options - 写入策略，参见 {@link DefineModulesOptions}。
- * @throws {ZentaoError} `E_INVALID_MODULE_DEFINITION` —— 缺少 `name` 或 `actions` 字段。
+ * @throws {ZentaoError} `E_INVALID_MODULE_DEFINITION` —— 缺少 `name` 或 `actions` 字段；
+ *   `E_INVALID_ACTION_DEFINITION` —— 动作字段非法或 `minVersion` 缺失、为空、格式错误、系列重复。
  */
 export declare function defineModules(input: ModuleDefinition | ModuleDefinition[], options?: DefineModulesOptions): void;
 /**
@@ -34,7 +35,7 @@ export declare function defineModules(input: ModuleDefinition | ModuleDefinition
  * @param moduleName - 目标模块名（大小写不敏感）。
  * @param input - 单个或一组动作定义。
  * @throws {ZentaoError} `E_INVALID_MODULE`（模块未注册）、`E_INVALID_ACTION_DEFINITION`
- *   （动作缺少 `name` / `path`，或 `method` / `resultType` 类型非法），或
+ *   （动作缺少 `name` / `path`、`minVersion` 无效，或 `method` / `resultType` 类型非法），或
  *   `E_INDETERMINATE_ACTION_METHOD` / `E_INDETERMINATE_ACTION_RESULT_TYPE`（省略字段且无法按 `type` 推导）。
  */
 export declare function defineModuleActions(moduleName: string, input: ModuleAction | ModuleAction[]): void;
@@ -52,7 +53,7 @@ export declare function defineModuleActions(moduleName: string, input: ModuleAct
  * @param actionName - 目标动作名（大小写不敏感）。
  * @param action - 深度合并的补丁对象，或接收当前动作深克隆并返回完整动作定义的函数。
  * @throws {ZentaoError} `E_INVALID_MODULE`（模块未注册）、`E_INVALID_ACTION`（动作不存在）、
- *   `E_INVALID_ACTION_DEFINITION`（合并结果缺少 `name` / `path`，或 `method` / `resultType` 类型非法），
+ *   `E_INVALID_ACTION_DEFINITION`（合并结果缺少 `name` / `path`、`minVersion` 无效，或 `method` / `resultType` 类型非法），
  *   或 `E_INDETERMINATE_ACTION_METHOD` / `E_INDETERMINATE_ACTION_RESULT_TYPE`（省略字段且无法按 `type` 推导）。
  */
 export declare function extendModuleAction(moduleName: string, actionName: string, action: Partial<ModuleAction> | ((action: ModuleAction) => ModuleAction)): void;

package/dist/modules/define.js

@@ -13,7 +13,8 @@ import { deepClone, deepMerge, findActionIndex, freezeAction, freezeModule, getM
  *
  * @param input - 单个或一组模块定义。
  * @param options - 写入策略，参见 {@link DefineModulesOptions}。
- * @throws {ZentaoError} `E_INVALID_MODULE_DEFINITION` —— 缺少 `name` 或 `actions` 字段。
+ * @throws {ZentaoError} `E_INVALID_MODULE_DEFINITION` —— 缺少 `name` 或 `actions` 字段；
+ *   `E_INVALID_ACTION_DEFINITION` —— 动作字段非法或 `minVersion` 缺失、为空、格式错误、系列重复。
  */
 export function defineModules(input, options = {}) {
     const modules = getModulesState();
@@ -42,7 +43,7 @@ export function defineModules(input, options = {}) {
  * @param moduleName - 目标模块名（大小写不敏感）。
  * @param input - 单个或一组动作定义。
  * @throws {ZentaoError} `E_INVALID_MODULE`（模块未注册）、`E_INVALID_ACTION_DEFINITION`
- *   （动作缺少 `name` / `path`，或 `method` / `resultType` 类型非法），或
+ *   （动作缺少 `name` / `path`、`minVersion` 无效，或 `method` / `resultType` 类型非法），或
  *   `E_INDETERMINATE_ACTION_METHOD` / `E_INDETERMINATE_ACTION_RESULT_TYPE`（省略字段且无法按 `type` 推导）。
  */
 export function defineModuleActions(moduleName, input) {
@@ -84,7 +85,7 @@ export function defineModuleActions(moduleName, input) {
  * @param actionName - 目标动作名（大小写不敏感）。
  * @param action - 深度合并的补丁对象，或接收当前动作深克隆并返回完整动作定义的函数。
  * @throws {ZentaoError} `E_INVALID_MODULE`（模块未注册）、`E_INVALID_ACTION`（动作不存在）、
- *   `E_INVALID_ACTION_DEFINITION`（合并结果缺少 `name` / `path`，或 `method` / `resultType` 类型非法），
+ *   `E_INVALID_ACTION_DEFINITION`（合并结果缺少 `name` / `path`、`minVersion` 无效，或 `method` / `resultType` 类型非法），
  *   或 `E_INDETERMINATE_ACTION_METHOD` / `E_INDETERMINATE_ACTION_RESULT_TYPE`（省略字段且无法按 `type` 推导）。
  */
 export function extendModuleAction(moduleName, actionName, action) {