zentao-api 0.2.0-beta.1 → 0.2.0

package/dist/client/index.d.ts

@@ -1,37 +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 创建客户端。
+     *
+     * 实际会调用 {@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

@@ -1,14 +1,9 @@
 import { ZentaoError } from '../misc/errors.js';
-import { assertInsecureSupported, withInsecureTls } from '../misc/environment.js';
+import { assertInsecureSupported, fetchWithInsecureTls } from '../misc/environment.js';
 import { getGlobalOptions, setGlobalOptions } from '../misc/global-options.js';
+import { addProfile, switchProfile } from '../profiles/index.js';
+import { isRecord, normalizeSiteUrl } from '../utils/index.js';
 const DEFAULT_TIMEOUT = 10000;
-/** 将用户传入的站点根地址规范化，兼容误传入 `/api.php/v2` 的场景。 */
-function normalizeSiteUrl(baseUrl) {
-    const trimmed = baseUrl.trim().replace(/\/+$/, '');
-    if (!trimmed)
-        throw new ZentaoError('E_INVALID_BASE_URL');
-    return trimmed.replace(/\/api\.php\/v2$/i, '');
-}
 /** 拼接 API 路径与查询参数，跳过值为 `undefined` 的查询项。 */
 function buildUrl(baseUrl, path, query) {
     const normalizedPath = path.startsWith('/') ? path : `/${path}`;
@@ -32,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;
@@ -52,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();
@@ -64,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;
         }
@@ -76,25 +92,24 @@ 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 {
-            return await withInsecureTls(insecure, async () => {
-                const response = await fetch(url, init);
-                if (!response.ok) {
-                    throw new ZentaoError('E_HTTP_ERROR', {
-                        status: response.status,
-                        statusText: response.statusText,
-                    }, {
-                        url: response.url,
-                        status: response.status,
-                        statusText: response.statusText,
-                        body: await response.text().catch(() => undefined),
-                    });
-                }
-                return parseResponse(response);
-            });
+            const response = await fetchWithInsecureTls(insecure, url, init);
+            if (!response.ok) {
+                throw new ZentaoError('E_HTTP_ERROR', {
+                    status: response.status,
+                    statusText: response.statusText,
+                }, {
+                    url: response.url,
+                    status: response.status,
+                    statusText: response.statusText,
+                    body: await response.text().catch(() => undefined),
+                });
+            }
+            return parseResponse(response);
         }
         catch (error) {
             if (error instanceof ZentaoError)
@@ -108,42 +123,137 @@ 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) {
             throw new ZentaoError('E_LOGIN_FAILED');
         }
         this.token = response.token;
+        const globals = getGlobalOptions();
+        if (globals.persistProfiles) {
+            const config = {};
+            const timeout = this.timeout ?? globals.timeout;
+            const insecure = this.insecure ?? globals.insecure;
+            if (timeout !== undefined)
+                config.timeout = timeout;
+            if (insecure !== undefined)
+                config.insecure = insecure;
+            await addProfile({
+                server: this.siteUrl,
+                account,
+                token: response.token,
+                user: isRecord(response.user) ? response.user : undefined,
+                serverConfig: isRecord(response.serverConfig) ? response.serverConfig : undefined,
+                config: Object.keys(config).length > 0 ? config : undefined,
+            });
+        }
         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;
     }
-}
-export function createClient(options) {
-    return ZentaoClient.create(options);
+    /**
+     * 根据本地持久化 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 处理。
+        const activeProfile = await switchProfile(profileKey);
+        return new ZentaoClient({
+            baseUrl: activeProfile.server,
+            token: activeProfile.token,
+            timeout: typeof activeProfile.config?.timeout === 'number' ? activeProfile.config.timeout : undefined,
+            insecure: typeof activeProfile.config?.insecure === 'boolean' ? activeProfile.config.insecure : undefined,
+        });
+    }
 }

package/dist/index.d.ts

@@ -1,7 +1,8 @@
 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 { 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, ZentaoClientOptions, } from './types/index.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

@@ -1,6 +1,7 @@
 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 { request } from './request/index.js';
 export { BUILD, VERSION } from './version.js';

package/dist/misc/environment.d.ts

@@ -2,5 +2,7 @@
 export declare function isNodeRuntime(): boolean;
 /** 浏览器无法跳过 TLS 校验，因此在发起请求前提前失败。 */
 export declare function assertInsecureSupported(enabled: boolean | undefined): void;
-/** 在 Node.js 中临时关闭 TLS 校验，并在本次请求结束后恢复原值。 */
+/** 发起 fetch 请求；Node.js 下的 `insecure` 只作用于当前 HTTPS 请求。 */
+export declare function fetchWithInsecureTls(enabled: boolean | undefined, url: string, init: RequestInit): Promise<Response>;
+/** 保留给内部测试和兼容调用：校验 TLS 选项，但不再改写进程级环境变量。 */
 export declare function withInsecureTls<T>(enabled: boolean | undefined, fn: () => Promise<T>): Promise<T>;

package/dist/misc/environment.js

@@ -3,28 +3,124 @@ import { ZentaoError } from './errors.js';
 export function isNodeRuntime() {
     return typeof process !== 'undefined' && Boolean(process.versions?.node);
 }
+// 通过函数参数间接化 `import(specifier)`，让打包器无法在静态分析阶段把
+// `node:*` 拉进浏览器 bundle；同时不依赖 `new Function`/`eval`，
+// 在严格 CSP 下也能正常加载。
+function importNodeModule(specifier) {
+    return import(specifier);
+}
+function toNodeRequestHeaders(headers) {
+    const result = {};
+    new Headers(headers).forEach((value, key) => {
+        result[key] = value;
+    });
+    return result;
+}
+function toResponseHeaders(headers) {
+    const result = new Headers();
+    for (const [key, value] of Object.entries(headers)) {
+        if (value === undefined)
+            continue;
+        result.set(key, Array.isArray(value) ? value.join(', ') : String(value));
+    }
+    return result;
+}
+async function toNodeBody(body) {
+    if (body === undefined || body === null)
+        return undefined;
+    if (typeof body === 'string')
+        return body;
+    if (body instanceof Uint8Array)
+        return body;
+    if (body instanceof ArrayBuffer)
+        return new Uint8Array(body);
+    if (ArrayBuffer.isView(body)) {
+        return new Uint8Array(body.buffer, body.byteOffset, body.byteLength);
+    }
+    if (body instanceof Blob) {
+        return new Uint8Array(await body.arrayBuffer());
+    }
+    return String(body);
+}
+function abortError() {
+    return new DOMException('The operation was aborted.', 'AbortError');
+}
+function concatenateChunks(chunks) {
+    const totalLength = chunks.reduce((total, chunk) => total + chunk.byteLength, 0);
+    const result = new Uint8Array(totalLength);
+    let offset = 0;
+    for (const chunk of chunks) {
+        result.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return result.buffer;
+}
+async function nodeFetchWithTlsOptions(url, init, rejectUnauthorized) {
+    const parsed = new URL(url);
+    const transport = parsed.protocol === 'https:'
+        ? await importNodeModule('node:https')
+        : await importNodeModule('node:http');
+    const body = await toNodeBody(init.body);
+    return new Promise((resolve, reject) => {
+        if (init.signal?.aborted) {
+            reject(abortError());
+            return;
+        }
+        const request = transport.request(parsed, {
+            method: init.method ?? 'GET',
+            headers: toNodeRequestHeaders(init.headers),
+            rejectUnauthorized,
+        }, (response) => {
+            const chunks = [];
+            response.on('data', (chunk) => {
+                chunks.push(typeof chunk === 'string' ? new TextEncoder().encode(chunk) : chunk);
+            });
+            response.on('end', () => {
+                cleanup();
+                const responseBody = chunks.length > 0 ? concatenateChunks(chunks) : undefined;
+                const fetchResponse = new Response(responseBody, {
+                    status: response.statusCode ?? 200,
+                    statusText: response.statusMessage ?? '',
+                    headers: toResponseHeaders(response.headers),
+                });
+                Object.defineProperty(fetchResponse, 'url', { value: url });
+                resolve(fetchResponse);
+            });
+        });
+        const cleanup = () => {
+            init.signal?.removeEventListener('abort', abortHandler);
+        };
+        const abortHandler = () => {
+            cleanup();
+            request.destroy(abortError());
+        };
+        request.on('error', (error) => {
+            cleanup();
+            reject(error);
+        });
+        init.signal?.addEventListener('abort', abortHandler, { once: true });
+        if (body !== undefined)
+            request.write(body);
+        request.end();
+    });
+}
 /** 浏览器无法跳过 TLS 校验，因此在发起请求前提前失败。 */
 export function assertInsecureSupported(enabled) {
     if (enabled && !isNodeRuntime()) {
         throw new ZentaoError('E_INSECURE_BROWSER');
     }
 }
-/** 在 Node.js 中临时关闭 TLS 校验，并在本次请求结束后恢复原值。 */
+/** 发起 fetch 请求；Node.js 下的 `insecure` 只作用于当前 HTTPS 请求。 */
+export async function fetchWithInsecureTls(enabled, url, init) {
+    if (!enabled)
+        return fetch(url, init);
+    assertInsecureSupported(enabled);
+    return nodeFetchWithTlsOptions(url, init, false);
+}
+/** 保留给内部测试和兼容调用：校验 TLS 选项，但不再改写进程级环境变量。 */
 export async function withInsecureTls(enabled, fn) {
     if (!enabled)
         return fn();
     assertInsecureSupported(enabled);
-    const previous = process.env.NODE_TLS_REJECT_UNAUTHORIZED;
-    process.env.NODE_TLS_REJECT_UNAUTHORIZED = '0';
-    try {
-        return await fn();
-    }
-    finally {
-        if (previous === undefined) {
-            delete process.env.NODE_TLS_REJECT_UNAUTHORIZED;
-        }
-        else {
-            process.env.NODE_TLS_REJECT_UNAUTHORIZED = previous;
-        }
-    }
+    return fn();
 }

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.";
@@ -6,20 +12,40 @@ export declare const ERRORS: {
     readonly E_TIMEOUT: "Request timed out.";
     readonly E_INSECURE_BROWSER: "The insecure option is only supported in Node.js runtimes.";
     readonly E_LOGIN_FAILED: "ZenTao login failed.";
+    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}";
+    readonly E_PROFILE_STORAGE_INVALID: "ZenTao profile storage is not valid JSON.";
+    readonly E_PROFILE_STORAGE_UNAVAILABLE: "ZenTao profile storage is unavailable in this runtime.";
     readonly E_INVALID_MODULE: "Unknown module: {module}";
     readonly E_INVALID_ACTION: "Unknown action: {module}-{action}";
     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);
 }