zentao-api 0.2.0-beta.2 → 0.2.1

package/dist/client/index.d.ts

@@ -1,39 +1,140 @@
 import type { ClientRequestOptions, ZentaoClientOptions } from '../types/index.js';
-/** 禅道 API 客户端，负责 Token 注入、请求超时、TLS 选项和响应解析。 */
+/**
+ * 禅道 API 客户端，封装一次次原始 HTTP 调用。
+ *
+ * 主要职责：
+ * - 站点根地址规范化与 `/api.php/v2` 拼接
+ * - 自动注入 `Token` 头
+ * - 请求超时控制（基于 {@link AbortController}）
+ * - 可选的 TLS 跳过校验（仅 Node.js 运行时）
+ * - 响应体的 JSON 解析与错误归一化
+ *
+ * 适合直接调用裸 API；若希望按模块/动作名调用并自动组装路径、参数、分页，
+ * 请改用 {@link request}。
+ */
 export declare class ZentaoClient {
     /** 禅道站点根地址，不包含 `/api.php/v2`。 */
     readonly siteUrl: string;
-    /** 禅道 API v2 根地址。 */
+    /** 禅道 API v2 根地址，等于 `siteUrl + '/api.php/v2'`。 */
     readonly baseUrl: string;
     private token?;
     private readonly timeout?;
     private readonly insecure?;
-    /** 使用完整配置创建客户端。 */
+    /**
+     * 使用完整配置创建客户端。
+     *
+     * @param options - 客户端配置，参见 {@link ZentaoClientOptions}。
+     * @throws {ZentaoError} `E_INVALID_BASE_URL` —— `baseUrl` 无法解析为合法的 http(s) URL。
+     */
     constructor(options: ZentaoClientOptions);
-    /** 使用站点根地址创建客户端。 */
+    /**
+     * 使用站点根地址创建客户端。
+     *
+     * @param baseUrl - 禅道站点根地址，例如 `https://zentao.example.com`；
+     *   若误传 `/api.php/v2` 后缀会自动剥离。
+     * @throws {ZentaoError} `E_INVALID_BASE_URL` —— 地址不合法或协议非 http(s)。
+     */
     constructor(baseUrl: string);
     /**
      * 发起一次原始 API 请求。
      *
-     * 默认使用 GET；当服务端返回 `{ status: "fail" }` 时仍按原始内容返回，
-     * 只有 HTTP/网络/超时等传输层错误会抛出 {@link ZentaoError}。
+     * 选项优先级：本次调用 `options` > 全局选项（{@link getGlobalOptions}） > 客户端构造时默认值。
+     *
+     * 特殊处理：
+     * - 默认 HTTP 方法为 `GET`，`GET` 请求即使提供了 `options.body` 也不会发送，避免被部分代理/浏览器拒绝。
+     * - 非空响应优先按 JSON 解析；解析失败时回落为字符串原文。
+     * - 业务层失败（即响应体 `{ status: "fail" }`）不会抛出，仍按原样返回；只有 HTTP/网络/超时等传输层错误才会抛错。
+     * - `insecure` 仅在 Node.js 下可用，浏览器中传入会抛 `E_INSECURE_BROWSER`。
+     *
+     * @param path - 相对 {@link baseUrl} 的路径，可省略前导 `/`。
+     * @param options - 单次请求选项，参见 {@link ClientRequestOptions}。
+     * @returns 解析后的响应体；当响应为空字符串时返回 `undefined`。
+     * @throws {ZentaoError} 可能抛出 `E_HTTP_ERROR`（非 2xx 状态）、`E_NETWORK_ERROR`（底层 fetch 失败）、
+     *   `E_TIMEOUT`（超过 `timeout`）或 `E_INSECURE_BROWSER`（浏览器中开启了 `insecure`）。
      */
     request(path: string, options?: ClientRequestOptions): Promise<unknown>;
-    /** 发起 GET 请求并按调用方指定类型返回。 */
+    /**
+     * 发起 `GET` 请求。
+     *
+     * @typeParam T - 期望的响应体类型；调用方负责类型收窄，SDK 不做运行时校验。
+     * @param path - 相对 {@link baseUrl} 的路径。
+     * @returns 解析后的响应体（强转为 `T`）。
+     * @throws {ZentaoError} 传输层失败时抛出，详见 {@link ZentaoClient.request}。
+     */
     get<T>(path: string): Promise<T>;
-    /** 发起 POST 请求并发送 JSON body。 */
-    post<T>(path: string, body: any): Promise<T>;
-    /** 发起 PUT 请求并发送 JSON body。 */
-    put<T>(path: string, body: any): Promise<T>;
-    /** 发起 DELETE 请求。 */
+    /**
+     * 发起 `POST` 请求，`body` 会被序列化为 JSON。
+     *
+     * @typeParam T - 期望的响应体类型。
+     * @param path - 相对 {@link baseUrl} 的路径。
+     * @param body - JSON 请求体，传入对象/数组将被 `JSON.stringify`。
+     * @returns 解析后的响应体（强转为 `T`）。
+     * @throws {ZentaoError} 传输层失败时抛出，详见 {@link ZentaoClient.request}。
+     */
+    post<T>(path: string, body: unknown): Promise<T>;
+    /**
+     * 发起 `PUT` 请求，`body` 会被序列化为 JSON。
+     *
+     * @typeParam T - 期望的响应体类型。
+     * @param path - 相对 {@link baseUrl} 的路径。
+     * @param body - JSON 请求体。
+     * @returns 解析后的响应体（强转为 `T`）。
+     * @throws {ZentaoError} 传输层失败时抛出，详见 {@link ZentaoClient.request}。
+     */
+    put<T>(path: string, body: unknown): Promise<T>;
+    /**
+     * 发起 `DELETE` 请求。
+     *
+     * @typeParam T - 期望的响应体类型。
+     * @param path - 相对 {@link baseUrl} 的路径。
+     * @returns 解析后的响应体（强转为 `T`）。
+     * @throws {ZentaoError} 传输层失败时抛出，详见 {@link ZentaoClient.request}。
+     */
     delete<T>(path: string): Promise<T>;
-    /** 使用账号密码登录，成功后把返回 Token 写入当前客户端实例。 */
+    /**
+     * 使用账号密码登录禅道。
+     *
+     * 成功后会把返回的 Token 写入当前客户端实例（后续请求自动带上 `Token` 头）；
+     * 当全局 `persistProfiles` 为真时，会同时把账号、Token、用户信息、服务端配置和
+     * 客户端偏好（仅在显式设置过 `timeout` / `insecure` 时）持久化为本地 profile，
+     * 并切换为当前 profile，方便下次通过 {@link ZentaoClient.fromProfile} 直接登录态恢复。
+     *
+     * @param account - 禅道用户账号。
+     * @param password - 禅道用户密码（明文，仅在传输层 TLS 内使用）。
+     * @returns 登录成功后返回的 API Token。
+     * @throws {ZentaoError} `E_LOGIN_FAILED` —— 服务端返回 `status !== "success"` 或缺失 token；
+     *   也可能因底层 {@link ZentaoClient.request} 而抛出 HTTP/网络/超时错误。
+     */
     login(account: string, password: string): Promise<string>;
-    /** 创建客户端实例，语义等同于 `new ZentaoClient(options)`。 */
+    /**
+     * 创建客户端实例，语义等同于 `new ZentaoClient(options)`，便于链式调用。
+     *
+     * @param options - 客户端配置，参见 {@link ZentaoClientOptions}。
+     * @returns 新建的客户端实例。
+     * @throws {ZentaoError} 同 {@link ZentaoClient | 构造函数}：`E_INVALID_BASE_URL` 等。
+     */
     static create(options: ZentaoClientOptions): ZentaoClient;
-    /** 创建客户端并写入全局选项，供高阶 `request()` 默认使用。 */
+    /**
+     * 创建客户端并写入全局选项，作为 {@link request} 默认使用的实例。
+     *
+     * 适合应用入口处一次性完成初始化，后续 `request("module/action", params)` 可省略 `options.client`。
+     * 多次调用会覆盖上一次的全局客户端。
+     *
+     * @param options - 客户端配置，参见 {@link ZentaoClientOptions}。
+     * @returns 新建并已注册为全局默认的客户端实例。
+     * @throws {ZentaoError} 同 {@link ZentaoClient | 构造函数}：`E_INVALID_BASE_URL` 等。
+     */
     static init(options: ZentaoClientOptions): ZentaoClient;
-    /** 根据本地持久化 profile 创建客户端；不传 key 时使用当前 profile。 */
+    /**
+     * 根据本地持久化 profile 创建客户端。
+     *
+     * 实际会调用 {@link switchProfile}：若 `profileKey` 存在则刷新其 `lastUsedTime` 并设为当前 profile；
+     * 不传 `profileKey` 时使用当前 profile。Profile 中保存的 `timeout` / `insecure` 偏好也会被带回到客户端实例。
+     *
+     * @param profileKey - 可选的 profile key，格式为 `account@server`；不传时使用当前 profile。
+     * @returns 用 profile 还原后的客户端实例。
+     * @throws {ZentaoError} `E_NO_PROFILE`（无任何 profile 且未传 key）、`E_PROFILE_NOT_FOUND`（指定 key 不存在）、
+     *   `E_PROFILE_STORAGE_UNAVAILABLE`（运行时无法访问持久化存储）。
+     */
     static fromProfile(profileKey?: string): Promise<ZentaoClient>;
 }
-export declare function createClient(options: ZentaoClientOptions): ZentaoClient;

package/dist/client/index.js

@@ -27,11 +27,23 @@ async function parseResponse(response) {
         return text;
     }
 }
-/** 禅道 API 客户端，负责 Token 注入、请求超时、TLS 选项和响应解析。 */
+/**
+ * 禅道 API 客户端，封装一次次原始 HTTP 调用。
+ *
+ * 主要职责：
+ * - 站点根地址规范化与 `/api.php/v2` 拼接
+ * - 自动注入 `Token` 头
+ * - 请求超时控制（基于 {@link AbortController}）
+ * - 可选的 TLS 跳过校验（仅 Node.js 运行时）
+ * - 响应体的 JSON 解析与错误归一化
+ *
+ * 适合直接调用裸 API；若希望按模块/动作名调用并自动组装路径、参数、分页，
+ * 请改用 {@link request}。
+ */
 export class ZentaoClient {
     /** 禅道站点根地址，不包含 `/api.php/v2`。 */
     siteUrl;
-    /** 禅道 API v2 根地址。 */
+    /** 禅道 API v2 根地址，等于 `siteUrl + '/api.php/v2'`。 */
     baseUrl;
     token;
     timeout;
@@ -47,8 +59,19 @@ export class ZentaoClient {
     /**
      * 发起一次原始 API 请求。
      *
-     * 默认使用 GET；当服务端返回 `{ status: "fail" }` 时仍按原始内容返回，
-     * 只有 HTTP/网络/超时等传输层错误会抛出 {@link ZentaoError}。
+     * 选项优先级：本次调用 `options` > 全局选项（{@link getGlobalOptions}） > 客户端构造时默认值。
+     *
+     * 特殊处理：
+     * - 默认 HTTP 方法为 `GET`，`GET` 请求即使提供了 `options.body` 也不会发送，避免被部分代理/浏览器拒绝。
+     * - 非空响应优先按 JSON 解析；解析失败时回落为字符串原文。
+     * - 业务层失败（即响应体 `{ status: "fail" }`）不会抛出，仍按原样返回；只有 HTTP/网络/超时等传输层错误才会抛错。
+     * - `insecure` 仅在 Node.js 下可用，浏览器中传入会抛 `E_INSECURE_BROWSER`。
+     *
+     * @param path - 相对 {@link baseUrl} 的路径，可省略前导 `/`。
+     * @param options - 单次请求选项，参见 {@link ClientRequestOptions}。
+     * @returns 解析后的响应体；当响应为空字符串时返回 `undefined`。
+     * @throws {ZentaoError} 可能抛出 `E_HTTP_ERROR`（非 2xx 状态）、`E_NETWORK_ERROR`（底层 fetch 失败）、
+     *   `E_TIMEOUT`（超过 `timeout`）或 `E_INSECURE_BROWSER`（浏览器中开启了 `insecure`）。
      */
     async request(path, options = {}) {
         const globals = getGlobalOptions();
@@ -59,9 +82,7 @@ export class ZentaoClient {
         const url = buildUrl(this.baseUrl, path, options.query);
         const controller = new AbortController();
         const timer = setTimeout(() => controller.abort(), timeout);
-        const headers = {
-            'Content-Type': 'application/json',
-        };
+        const headers = {};
         if (this.token) {
             headers.Token = this.token;
         }
@@ -71,7 +92,8 @@ export class ZentaoClient {
             signal: controller.signal,
         };
         // GET 请求不携带 body，避免浏览器和部分代理拒绝请求。
-        if (options.body && method !== 'GET') {
+        if (options.body !== undefined && method !== 'GET') {
+            headers['Content-Type'] = 'application/json';
             init.body = JSON.stringify(options.body);
         }
         try {
@@ -101,23 +123,66 @@ export class ZentaoClient {
             clearTimeout(timer);
         }
     }
-    /** 发起 GET 请求并按调用方指定类型返回。 */
+    /**
+     * 发起 `GET` 请求。
+     *
+     * @typeParam T - 期望的响应体类型；调用方负责类型收窄，SDK 不做运行时校验。
+     * @param path - 相对 {@link baseUrl} 的路径。
+     * @returns 解析后的响应体（强转为 `T`）。
+     * @throws {ZentaoError} 传输层失败时抛出，详见 {@link ZentaoClient.request}。
+     */
     async get(path) {
         return this.request(path, { method: 'GET' });
     }
-    /** 发起 POST 请求并发送 JSON body。 */
+    /**
+     * 发起 `POST` 请求，`body` 会被序列化为 JSON。
+     *
+     * @typeParam T - 期望的响应体类型。
+     * @param path - 相对 {@link baseUrl} 的路径。
+     * @param body - JSON 请求体，传入对象/数组将被 `JSON.stringify`。
+     * @returns 解析后的响应体（强转为 `T`）。
+     * @throws {ZentaoError} 传输层失败时抛出，详见 {@link ZentaoClient.request}。
+     */
     async post(path, body) {
         return this.request(path, { method: 'POST', body });
     }
-    /** 发起 PUT 请求并发送 JSON body。 */
+    /**
+     * 发起 `PUT` 请求，`body` 会被序列化为 JSON。
+     *
+     * @typeParam T - 期望的响应体类型。
+     * @param path - 相对 {@link baseUrl} 的路径。
+     * @param body - JSON 请求体。
+     * @returns 解析后的响应体（强转为 `T`）。
+     * @throws {ZentaoError} 传输层失败时抛出，详见 {@link ZentaoClient.request}。
+     */
     async put(path, body) {
         return this.request(path, { method: 'PUT', body });
     }
-    /** 发起 DELETE 请求。 */
+    /**
+     * 发起 `DELETE` 请求。
+     *
+     * @typeParam T - 期望的响应体类型。
+     * @param path - 相对 {@link baseUrl} 的路径。
+     * @returns 解析后的响应体（强转为 `T`）。
+     * @throws {ZentaoError} 传输层失败时抛出，详见 {@link ZentaoClient.request}。
+     */
     async delete(path) {
         return this.request(path, { method: 'DELETE' });
     }
-    /** 使用账号密码登录，成功后把返回 Token 写入当前客户端实例。 */
+    /**
+     * 使用账号密码登录禅道。
+     *
+     * 成功后会把返回的 Token 写入当前客户端实例（后续请求自动带上 `Token` 头）；
+     * 当全局 `persistProfiles` 为真时，会同时把账号、Token、用户信息、服务端配置和
+     * 客户端偏好（仅在显式设置过 `timeout` / `insecure` 时）持久化为本地 profile，
+     * 并切换为当前 profile，方便下次通过 {@link ZentaoClient.fromProfile} 直接登录态恢复。
+     *
+     * @param account - 禅道用户账号。
+     * @param password - 禅道用户密码（明文，仅在传输层 TLS 内使用）。
+     * @returns 登录成功后返回的 API Token。
+     * @throws {ZentaoError} `E_LOGIN_FAILED` —— 服务端返回 `status !== "success"` 或缺失 token；
+     *   也可能因底层 {@link ZentaoClient.request} 而抛出 HTTP/网络/超时错误。
+     */
     async login(account, password) {
         const response = await this.post('/users/login', { account, password });
         if (response.status !== 'success' || !response.token) {
@@ -144,17 +209,42 @@ export class ZentaoClient {
         }
         return response.token;
     }
-    /** 创建客户端实例，语义等同于 `new ZentaoClient(options)`。 */
+    /**
+     * 创建客户端实例，语义等同于 `new ZentaoClient(options)`，便于链式调用。
+     *
+     * @param options - 客户端配置，参见 {@link ZentaoClientOptions}。
+     * @returns 新建的客户端实例。
+     * @throws {ZentaoError} 同 {@link ZentaoClient | 构造函数}：`E_INVALID_BASE_URL` 等。
+     */
     static create(options) {
         return new ZentaoClient(options);
     }
-    /** 创建客户端并写入全局选项，供高阶 `request()` 默认使用。 */
+    /**
+     * 创建客户端并写入全局选项，作为 {@link request} 默认使用的实例。
+     *
+     * 适合应用入口处一次性完成初始化，后续 `request("module/action", params)` 可省略 `options.client`。
+     * 多次调用会覆盖上一次的全局客户端。
+     *
+     * @param options - 客户端配置，参见 {@link ZentaoClientOptions}。
+     * @returns 新建并已注册为全局默认的客户端实例。
+     * @throws {ZentaoError} 同 {@link ZentaoClient | 构造函数}：`E_INVALID_BASE_URL` 等。
+     */
     static init(options) {
         const client = new ZentaoClient(options);
         setGlobalOptions({ client });
         return client;
     }
-    /** 根据本地持久化 profile 创建客户端；不传 key 时使用当前 profile。 */
+    /**
+     * 根据本地持久化 profile 创建客户端。
+     *
+     * 实际会调用 {@link switchProfile}：若 `profileKey` 存在则刷新其 `lastUsedTime` 并设为当前 profile；
+     * 不传 `profileKey` 时使用当前 profile。Profile 中保存的 `timeout` / `insecure` 偏好也会被带回到客户端实例。
+     *
+     * @param profileKey - 可选的 profile key，格式为 `account@server`；不传时使用当前 profile。
+     * @returns 用 profile 还原后的客户端实例。
+     * @throws {ZentaoError} `E_NO_PROFILE`（无任何 profile 且未传 key）、`E_PROFILE_NOT_FOUND`（指定 key 不存在）、
+     *   `E_PROFILE_STORAGE_UNAVAILABLE`（运行时无法访问持久化存储）。
+     */
     static async fromProfile(profileKey) {
         // switchProfile 会在内部读取存储、校验 key 并刷新 lastUsedTime 后写回，
         // 若 key 不存在会抛出 E_PROFILE_NOT_FOUND；不传 key 时由 switchCurrentProfile 处理。
@@ -167,6 +257,3 @@ export class ZentaoClient {
         });
     }
 }
-export function createClient(options) {
-    return ZentaoClient.create(options);
-}

package/dist/index.d.ts

@@ -2,7 +2,7 @@ export { ZentaoClient } from './client/index.js';
 export { ERRORS, ZentaoError, type ErrorCode } from './misc/errors.js';
 export { getGlobalOptions, setGlobalOptions } from './misc/global-options.js';
 export { ZENTAO_PROFILES_STORAGE_KEY, addProfile, deleteProfile, getAllProfiles, getProfile, getProfileKey, switchProfile, } from './profiles/index.js';
-export { defineModuleActions, defineModules, type DefineModulesOptions, getModule, getModuleAction, } from './modules/registry.js';
+export { defineModuleActions, defineModules, type DefineModulesOptions, getModuleNames, getModule, getModuleAction, } from './modules/registry.js';
 export { request } from './request/index.js';
 export { BUILD, VERSION } from './version.js';
 export type { ApiListResponse, ApiResponse, ClientRequestOptions, GlobalOptions, HttpMethod, ListPagerInfo, LoginResponse, ModuleAction, ModuleActionMethod, ModuleActionName, ModuleActionPagerGetterMap, ModuleActionParam, ModuleActionParamOption, ModuleActionRequestBody, ModuleActionResponse, ModuleActionResultRender, ModuleActionResultRenderType, ModuleActionResultType, ModuleActionType, ModuleDefinition, ModuleName, Pager, RequestOptions, ResolvedModuleCommand, ResponseData, ServerConfig, ZentaoProfile, ZentaoProfileConfig, ZentaoProfileRecord, ZentaoProfilesStore, ZentaoClientOptions, } from './types/index.js';

package/dist/index.js

@@ -2,6 +2,6 @@ export { ZentaoClient } from './client/index.js';
 export { ERRORS, ZentaoError } from './misc/errors.js';
 export { getGlobalOptions, setGlobalOptions } from './misc/global-options.js';
 export { ZENTAO_PROFILES_STORAGE_KEY, addProfile, deleteProfile, getAllProfiles, getProfile, getProfileKey, switchProfile, } from './profiles/index.js';
-export { defineModuleActions, defineModules, getModule, getModuleAction, } from './modules/registry.js';
+export { defineModuleActions, defineModules, getModuleNames, getModule, getModuleAction, } from './modules/registry.js';
 export { request } from './request/index.js';
 export { BUILD, VERSION } from './version.js';

package/dist/misc/environment.js

@@ -3,9 +3,11 @@ import { ZentaoError } from './errors.js';
 export function isNodeRuntime() {
     return typeof process !== 'undefined' && Boolean(process.versions?.node);
 }
-async function importNodeModule(specifier) {
-    const dynamicImport = new Function('specifier', 'return import(specifier)');
-    return dynamicImport(specifier);
+// 通过函数参数间接化 `import(specifier)`，让打包器无法在静态分析阶段把
+// `node:*` 拉进浏览器 bundle；同时不依赖 `new Function`/`eval`，
+// 在严格 CSP 下也能正常加载。
+function importNodeModule(specifier) {
+    return import(specifier);
 }
 function toNodeRequestHeaders(headers) {
     const result = {};

package/dist/misc/errors.d.ts

@@ -1,3 +1,9 @@
+/**
+ * SDK 已知错误码到默认消息的映射表。
+ *
+ * 每条消息允许带 `{key}` 占位符，由 {@link ZentaoError} 构造时使用 `replacements`
+ * 进行字面量替换。此对象使用 `as const`，可直接作为类型来源约束错误码。
+ */
 export declare const ERRORS: {
     readonly E_INVALID_BASE_URL: "Invalid ZenTao baseUrl.";
     readonly E_NO_GLOBAL_CLIENT: "No global client configured. Call ZentaoClient.init() or pass options.client.";
@@ -16,15 +22,30 @@ export declare const ERRORS: {
     readonly E_INVALID_MODULE_DEFINITION: "Invalid module definition.";
     readonly E_INVALID_ACTION_DEFINITION: "Invalid module action definition.";
     readonly E_MISSING_PARAM: "Missing required parameter: {param}";
+    readonly E_INVALID_PARAM: "Invalid value for parameter {param}: {value}";
     readonly E_INVALID_REQUEST_NAME: "Request name must use the form \"moduleName/methodName\".";
+    readonly E_API_FAILED: "ZenTao API returned failure: {message}";
 };
+/** SDK 已知错误码，对应 {@link ERRORS} 的 key。 */
 export type ErrorCode = keyof typeof ERRORS;
-/** SDK 统一错误类型，所有可预期错误都会携带稳定错误码。 */
+/**
+ * SDK 统一错误类型。
+ *
+ * 所有可预期错误（参数缺失、HTTP/网络/超时、登录失败、profile 异常等）都通过
+ * `ZentaoError` 抛出并携带稳定 {@link ErrorCode}，方便调用方按 `code` 区分处理。
+ * 错误消息默认来自 {@link ERRORS} 中的模板，并支持占位符替换。
+ */
 export declare class ZentaoError extends Error {
-    /** 错误码，对应 {@link ERRORS} 的 key。 */
+    /** 错误码，对应 {@link ERRORS} 的 key；用于稳定地区分错误类型。 */
     readonly code: ErrorCode;
-    /** 附加上下文，例如 HTTP 响应详情或原始异常。 */
+    /** 附加上下文，例如 HTTP 响应详情、原始异常或失败的禅道响应原文。 */
     readonly details?: unknown;
-    /** 根据错误码和占位符替换值创建错误。 */
+    /**
+     * 构造 SDK 错误实例。
+     *
+     * @param code - 错误码，必须是 {@link ERRORS} 中已声明的 key。
+     * @param replacements - 可选的占位符替换值；遍历后会把 `{key}` 替换为字符串化的值。
+     * @param details - 可选的附加上下文（HTTP 响应详情、原始异常等），保存到 {@link details}。
+     */
     constructor(code: ErrorCode, replacements?: Record<string, string | number>, details?: unknown);
 }

package/dist/misc/errors.js

@@ -1,3 +1,9 @@
+/**
+ * SDK 已知错误码到默认消息的映射表。
+ *
+ * 每条消息允许带 `{key}` 占位符，由 {@link ZentaoError} 构造时使用 `replacements`
+ * 进行字面量替换。此对象使用 `as const`，可直接作为类型来源约束错误码。
+ */
 export const ERRORS = {
     E_INVALID_BASE_URL: 'Invalid ZenTao baseUrl.',
     E_NO_GLOBAL_CLIENT: 'No global client configured. Call ZentaoClient.init() or pass options.client.',
@@ -16,15 +22,29 @@ export const ERRORS = {
     E_INVALID_MODULE_DEFINITION: 'Invalid module definition.',
     E_INVALID_ACTION_DEFINITION: 'Invalid module action definition.',
     E_MISSING_PARAM: 'Missing required parameter: {param}',
+    E_INVALID_PARAM: 'Invalid value for parameter {param}: {value}',
     E_INVALID_REQUEST_NAME: 'Request name must use the form "moduleName/methodName".',
+    E_API_FAILED: 'ZenTao API returned failure: {message}',
 };
-/** SDK 统一错误类型，所有可预期错误都会携带稳定错误码。 */
+/**
+ * SDK 统一错误类型。
+ *
+ * 所有可预期错误（参数缺失、HTTP/网络/超时、登录失败、profile 异常等）都通过
+ * `ZentaoError` 抛出并携带稳定 {@link ErrorCode}，方便调用方按 `code` 区分处理。
+ * 错误消息默认来自 {@link ERRORS} 中的模板，并支持占位符替换。
+ */
 export class ZentaoError extends Error {
-    /** 错误码，对应 {@link ERRORS} 的 key。 */
+    /** 错误码，对应 {@link ERRORS} 的 key；用于稳定地区分错误类型。 */
     code;
-    /** 附加上下文，例如 HTTP 响应详情或原始异常。 */
+    /** 附加上下文，例如 HTTP 响应详情、原始异常或失败的禅道响应原文。 */
     details;
-    /** 根据错误码和占位符替换值创建错误。 */
+    /**
+     * 构造 SDK 错误实例。
+     *
+     * @param code - 错误码，必须是 {@link ERRORS} 中已声明的 key。
+     * @param replacements - 可选的占位符替换值；遍历后会把 `{key}` 替换为字符串化的值。
+     * @param details - 可选的附加上下文（HTTP 响应详情、原始异常等），保存到 {@link details}。
+     */
     constructor(code, replacements, details) {
         let message = ERRORS[code];
         if (replacements) {

package/dist/misc/global-options.d.ts

@@ -1,5 +1,18 @@
 import type { GlobalOptions } from '../types/index.js';
-/** 获取当前全局选项快照；返回副本，避免调用方直接改写内部状态。 */
+/**
+ * 获取当前全局选项的快照。
+ *
+ * 返回的是浅拷贝副本，对返回值的修改不会影响内部状态；如需更新请使用 {@link setGlobalOptions}。
+ *
+ * @returns 当前生效的全局选项快照，参见 {@link GlobalOptions}。
+ */
 export declare function getGlobalOptions(): GlobalOptions;
-/** 合并设置全局选项；传入 `undefined` 可清空对应字段。 */
+/**
+ * 以浅合并的方式更新全局选项。
+ *
+ * 仅覆盖传入 `options` 中显式声明的字段；其余字段保留原值。若希望清空某个字段，
+ * 显式传入 `undefined` 即可（会写入 `undefined` 并在后续读取时返回 `undefined`）。
+ *
+ * @param options - 要合并到全局选项中的字段子集。
+ */
 export declare function setGlobalOptions(options: Partial<GlobalOptions>): void;

package/dist/misc/global-options.js

@@ -1,9 +1,22 @@
 let globalOptions = {};
-/** 获取当前全局选项快照；返回副本，避免调用方直接改写内部状态。 */
+/**
+ * 获取当前全局选项的快照。
+ *
+ * 返回的是浅拷贝副本，对返回值的修改不会影响内部状态；如需更新请使用 {@link setGlobalOptions}。
+ *
+ * @returns 当前生效的全局选项快照，参见 {@link GlobalOptions}。
+ */
 export function getGlobalOptions() {
     return { ...globalOptions };
 }
-/** 合并设置全局选项；传入 `undefined` 可清空对应字段。 */
+/**
+ * 以浅合并的方式更新全局选项。
+ *
+ * 仅覆盖传入 `options` 中显式声明的字段；其余字段保留原值。若希望清空某个字段，
+ * 显式传入 `undefined` 即可（会写入 `undefined` 并在后续读取时返回 `undefined`）。
+ *
+ * @param options - 要合并到全局选项中的字段子集。
+ */
 export function setGlobalOptions(options) {
     globalOptions = { ...globalOptions, ...options };
 }

package/dist/modules/registry.d.ts

@@ -2,21 +2,84 @@ import type { ModuleAction, ModuleDefinition } from '../types/index.js';
 import { BUILTIN_MODULES } from './generated.js';
 export { BUILTIN_MODULES };
 export declare const MODULES: ModuleDefinition[];
+/** {@link defineModules} 的选项。 */
 export interface DefineModulesOptions {
-    /** 同名模块是否整体替换；默认合并模块定义和动作。 */
+    /**
+     * 同名模块的写入策略。
+     *
+     * - `false`（默认）：合并模块的元数据，并按动作名对动作做"同名替换、未知追加"。
+     * - `true`：整体替换已存在的模块定义，原有动作会被丢弃。
+     */
     replace?: boolean;
 }
-/** 定义或扩展模块；同名模块默认合并动作，`replace` 为真时整体替换，未知模块追加。 */
+/**
+ * 注册或扩展模块定义。
+ *
+ * 行为细节：
+ * - 模块名匹配大小写不敏感。
+ * - 未知模块直接追加到注册表末尾。
+ * - 已存在的模块默认按 `mergeModule` 合并：模块元数据浅合并、动作按名同名替换/未知追加；
+ *   `options.replace` 为 `true` 时整体替换。
+ * - 所有写入都会做深克隆 + 深冻结：调用方后续修改自己的对象不会污染注册表，注册表也不可被外部改写。
+ *
+ * @param input - 单个或一组模块定义。
+ * @param options - 写入策略，参见 {@link DefineModulesOptions}。
+ * @throws {ZentaoError} `E_INVALID_MODULE_DEFINITION` —— 缺少 `name` 或 `actions` 字段。
+ */
 export declare function defineModules(input: ModuleDefinition | ModuleDefinition[], options?: DefineModulesOptions): void;
-/** 为已存在模块定义或覆盖动作；同名动作替换，未知动作追加。 */
+/**
+ * 为已存在的模块追加或覆盖动作。
+ *
+ * 不做深度合并：同名动作整体替换，未知动作追加。这避免在 schema、参数数组等字段上出现隐式合并规则。
+ *
+ * @param moduleName - 目标模块名（大小写不敏感）。
+ * @param input - 单个或一组动作定义。
+ * @throws {ZentaoError} `E_INVALID_MODULE`（模块未注册）或 `E_INVALID_ACTION_DEFINITION`
+ *   （动作缺少 `name` / `path` / `method` 等必填字段）。
+ */
 export declare function defineModuleActions(moduleName: string, input: ModuleAction | ModuleAction[]): void;
-/** 获取模块定义；模块不存在时抛出 {@link ZentaoError}。 */
+/**
+ * 获取模块定义。
+ *
+ * 模块名匹配大小写不敏感。返回值是注册表内部的已深冻结引用（O(1) 查询、零拷贝），
+ * 任何写入尝试在严格模式下会抛 `TypeError`；如需修改请使用 {@link defineModules}。
+ *
+ * @param moduleName - 模块名。
+ * @returns 已注册的模块定义。
+ * @throws {ZentaoError} `E_INVALID_MODULE` —— 模块未注册。
+ */
 export declare function getModule(moduleName: string): ModuleDefinition;
-/** 获取指定模块动作；`ls` 会作为 `list` 的别名处理。 */
+/**
+ * 获取指定模块下的某个动作。
+ *
+ * 解析顺序：
+ * 1. `actionName === 'ls'` 时映射为 `list`（仅作为别名，不会修改注册表）。
+ * 2. 在该模块的动作中按名称大小写不敏感匹配。
+ * 3. 当请求的动作不是基础 CRUD（`list`/`get`/`create`/`update`/`delete`）时，
+ *    额外允许命中 `type === 'action'` 的自定义动作（即使名字不在基础 CRUD 中）。
+ *
+ * 返回值同样是已深冻结的引用，请勿尝试修改。
+ *
+ * @param moduleName - 模块名（大小写不敏感）。
+ * @param actionName - 动作名（大小写不敏感）；支持 `ls` 作为 `list` 的别名。
+ * @returns 匹配到的动作定义。
+ * @throws {ZentaoError} `E_INVALID_MODULE`（模块未注册）或 `E_INVALID_ACTION`（动作不存在）。
+ */
 export declare function getModuleAction(moduleName: string, actionName: string): ModuleAction;
-/** 返回当前运行时注册表中的所有模块名。 */
+/**
+ * 返回当前运行时注册表中的所有模块名。
+ *
+ * 顺序与模块写入注册表的顺序一致；包括内置模块和通过 {@link defineModules} 追加的用户模块。
+ *
+ * @returns 模块名数组（保留原始大小写）。
+ */
 export declare function getModuleNames(): string[];
-/** 判断模块名是否已注册，大小写不敏感。 */
+/**
+ * 判断模块名是否已注册。
+ *
+ * @param moduleName - 模块名；匹配大小写不敏感。
+ * @returns 已注册返回 `true`，否则 `false`。
+ */
 export declare function isModuleName(moduleName: string): boolean;
 /** @internal */
 export declare function resetModuleDefinitions(): void;