zentao-api 0.6.7 → 0.6.8

package/dist/client/index.d.ts

@@ -1,4 +1,4 @@
-import type { ClientRequestOptions, GetZentaoConfigOptions, ServerConfig, ZentaoClientOptions } from '../types/index.js';
+import type { ClientRequestOptions, FromProfileOptions, GetZentaoConfigOptions, ServerConfig, ZentaoClientOptions } from '../types/index.js';
 /**
  * 禅道 API 客户端，封装一次次原始 HTTP 调用。
  *
@@ -69,10 +69,21 @@ export declare class ZentaoClient {
         responseType: 'blob';
     }): Promise<Blob>;
     request<T = unknown>(path: string, options?: ClientRequestOptions): Promise<T>;
-    /** API 与站点配置共用的传输层；配置请求不传入 Token。 */
-    private fetchUrl;
     /**
-     * 获取禅道站点 `/?mode=getconfig` 配置，不发送 API Token。
+     * 使用完整 URL 发起请求，复用 API 与站点配置的传输层。
+     *
+     * @param url - 完整请求 URL，包含所需的查询参数。
+     * @param options - 单次请求选项；其中 `query` 需由调用方预先拼入 `url`。
+     * @param token - 显式注入的 Token；省略时不自动使用实例保存的 Token。
+     * @param fetchOptions - 原生 fetch 的缓存与凭据选项。
+     * @returns 按 `options.responseType` 解析的响应体，默认优先 JSON，失败后返回文本。
+     * @throws {ZentaoError} 传输层失败时抛出，详见 {@link ZentaoClient.request}。
+     */
+    fetch(url: string, options: ClientRequestOptions, token?: string, fetchOptions?: Pick<RequestInit, 'cache' | 'credentials'>): Promise<unknown>;
+    /**
+     * 匿名获取禅道站点 `/?mode=getconfig` 配置，只需站点地址，无需登录或 profile。
+     *
+     * 不发送 API Token，浏览器请求显式省略 Cookie 等凭据，不受 API Token 过期影响。
      *
      * 默认复用不超过 24 小时的缓存；缺失、过期或时间异常时重新获取。
      * `forceRefresh: true` 忽略缓存。同一客户端的并发刷新共用首次调用的传输选项；
@@ -134,6 +145,8 @@ export declare class ZentaoClient {
      * 当全局 `persistProfiles` 为真时，会同时把账号、Token、用户信息、服务端配置和
      * 客户端偏好（仅在显式设置过 `timeout` / `insecure` 时）持久化为本地 profile，
      * 并切换为当前 profile，方便下次通过 {@link ZentaoClient.fromProfile} 直接登录态恢复。
+     * 重新登录同一账号时保留已有自定义字段，以及未被显式覆盖的客户端偏好。
+     * 保存的 `timeout` / `insecure` 与请求一致：全局显式值优先于实例默认值。
      *
      * @param account - 禅道用户账号。
      * @param password - 禅道用户密码（明文，仅在传输层 TLS 内使用）。
@@ -164,13 +177,16 @@ export declare class ZentaoClient {
     /**
      * 根据本地持久化 profile 创建客户端。
      *
-     * 实际会调用 {@link switchProfile}：若 `profileKey` 存在则刷新其 `lastUsedTime` 并设为当前 profile；
+     * 默认调用 {@link switchProfile}：若 `profileKey` 存在则刷新其 `lastUsedTime` 并设为当前 profile；
      * 不传 `profileKey` 时使用当前 profile。Profile 中保存的 `timeout` / `insecure` 偏好也会被带回到客户端实例。
+     * `activate: false` 时只读存储，不切换账号、不更新时间，支持可读但不可写的存储。
+     * 两种模式均不替换全局客户端；后续配置刷新是否写回仍由全局 `persistProfiles` 控制。
      *
      * @param profileKey - 可选的 profile key，格式为 `account@server`；不传时使用当前 profile。
+     * @param options - 恢复选项；默认保持切换当前 profile 的行为。
      * @returns 用 profile 还原后的客户端实例。
      * @throws {ZentaoError} `E_NO_PROFILE`（无任何 profile 且未传 key）、`E_PROFILE_NOT_FOUND`（指定 key 不存在）、
-     *   `E_PROFILE_STORAGE_UNAVAILABLE`（运行时无法访问持久化存储）。
+     *   `E_PROFILE_STORAGE_INVALID`（存储内容不合法）、`E_PROFILE_STORAGE_UNAVAILABLE`（运行时无法访问持久化存储）。
      */
-    static fromProfile(profileKey?: string): Promise<ZentaoClient>;
+    static fromProfile(profileKey?: string, options?: FromProfileOptions): Promise<ZentaoClient>;
 }

package/dist/client/index.js

@@ -2,7 +2,7 @@ import { isZentaoConfigFetchError, ZentaoError } from '../misc/errors.js';
 import { parseZentaoVersion } from '../misc/zentao-version.js';
 import { assertInsecureSupported, fetchWithInsecureTls } from '../misc/environment.js';
 import { getGlobalOptions, setGlobalOptions } from '../misc/global-options.js';
-import { addProfile, switchProfile, updateProfileServerConfig } from '../profiles/index.js';
+import { getProfileOrThrow, saveLoginProfile, switchProfile, updateProfileServerConfig } from '../profiles/index.js';
 import { isRecord, normalizeSiteUrl } from '../utils/index.js';
 const DEFAULT_TIMEOUT = 10000;
 const CONFIG_MAX_AGE = 24 * 60 * 60 * 1000;
@@ -316,10 +316,19 @@ export class ZentaoClient {
         this.insecure = options.insecure;
     }
     async request(path, options = {}) {
-        return this.fetchUrl(buildUrl(this.baseUrl, path, options.query), options, this.token);
+        return this.fetch(buildUrl(this.baseUrl, path, options.query), options, this.token);
     }
-    /** API 与站点配置共用的传输层；配置请求不传入 Token。 */
-    async fetchUrl(url, options, token, cache) {
+    /**
+     * 使用完整 URL 发起请求，复用 API 与站点配置的传输层。
+     *
+     * @param url - 完整请求 URL，包含所需的查询参数。
+     * @param options - 单次请求选项；其中 `query` 需由调用方预先拼入 `url`。
+     * @param token - 显式注入的 Token；省略时不自动使用实例保存的 Token。
+     * @param fetchOptions - 原生 fetch 的缓存与凭据选项。
+     * @returns 按 `options.responseType` 解析的响应体，默认优先 JSON，失败后返回文本。
+     * @throws {ZentaoError} 传输层失败时抛出，详见 {@link ZentaoClient.request}。
+     */
+    async fetch(url, options, token, fetchOptions = {}) {
         const globals = getGlobalOptions();
         const method = options.method ?? 'GET';
         const timeout = options.timeout ?? globals.timeout ?? this.timeout ?? DEFAULT_TIMEOUT;
@@ -333,7 +342,7 @@ export class ZentaoClient {
             method,
             headers,
             redirect: 'manual',
-            cache,
+            ...fetchOptions,
         };
         // GET 请求不携带 body，避免浏览器和部分代理拒绝请求。
         if (options.body !== undefined && method !== 'GET') {
@@ -379,7 +388,9 @@ export class ZentaoClient {
         }
     }
     /**
-     * 获取禅道站点 `/?mode=getconfig` 配置，不发送 API Token。
+     * 匿名获取禅道站点 `/?mode=getconfig` 配置，只需站点地址，无需登录或 profile。
+     *
+     * 不发送 API Token，浏览器请求显式省略 Cookie 等凭据，不受 API Token 过期影响。
      *
      * 默认复用不超过 24 小时的缓存；缺失、过期或时间异常时重新获取。
      * `forceRefresh: true` 忽略缓存。同一客户端的并发刷新共用首次调用的传输选项；
@@ -407,9 +418,9 @@ export class ZentaoClient {
             parseZentaoVersion(this.serverConfig.version);
             return this.serverConfig;
         }
-        const pending = this.fetchUrl(buildUrl(this.siteUrl, '/', { mode: 'getconfig' }), {
+        const pending = this.fetch(buildUrl(this.siteUrl, '/', { mode: 'getconfig' }), {
             method: 'GET', timeout: options.timeout, insecure: options.insecure, signal: options.signal,
-        }, undefined, 'no-store').then(async (config) => {
+        }, undefined, { cache: 'no-store', credentials: 'omit' }).then(async (config) => {
             if (!isServerConfig(config))
                 throw new ZentaoError('E_INVALID_ZENTAO_CONFIG');
             parseZentaoVersion(config.version);
@@ -500,6 +511,8 @@ export class ZentaoClient {
      * 当全局 `persistProfiles` 为真时，会同时把账号、Token、用户信息、服务端配置和
      * 客户端偏好（仅在显式设置过 `timeout` / `insecure` 时）持久化为本地 profile，
      * 并切换为当前 profile，方便下次通过 {@link ZentaoClient.fromProfile} 直接登录态恢复。
+     * 重新登录同一账号时保留已有自定义字段，以及未被显式覆盖的客户端偏好。
+     * 保存的 `timeout` / `insecure` 与请求一致：全局显式值优先于实例默认值。
      *
      * @param account - 禅道用户账号。
      * @param password - 禅道用户密码（明文，仅在传输层 TLS 内使用）。
@@ -525,13 +538,13 @@ export class ZentaoClient {
         let profileKey;
         if (globals.persistProfiles) {
             const config = {};
-            const timeout = this.timeout ?? globals.timeout;
-            const insecure = this.insecure ?? globals.insecure;
+            const timeout = globals.timeout ?? this.timeout;
+            const insecure = globals.insecure ?? this.insecure;
             if (timeout !== undefined)
                 config.timeout = timeout;
             if (insecure !== undefined)
                 config.insecure = insecure;
-            const profile = await addProfile({
+            const profile = await saveLoginProfile({
                 server: this.siteUrl,
                 account,
                 token: response.token,
@@ -574,18 +587,19 @@ export class ZentaoClient {
     /**
      * 根据本地持久化 profile 创建客户端。
      *
-     * 实际会调用 {@link switchProfile}：若 `profileKey` 存在则刷新其 `lastUsedTime` 并设为当前 profile；
+     * 默认调用 {@link switchProfile}：若 `profileKey` 存在则刷新其 `lastUsedTime` 并设为当前 profile；
      * 不传 `profileKey` 时使用当前 profile。Profile 中保存的 `timeout` / `insecure` 偏好也会被带回到客户端实例。
+     * `activate: false` 时只读存储，不切换账号、不更新时间，支持可读但不可写的存储。
+     * 两种模式均不替换全局客户端；后续配置刷新是否写回仍由全局 `persistProfiles` 控制。
      *
      * @param profileKey - 可选的 profile key，格式为 `account@server`；不传时使用当前 profile。
+     * @param options - 恢复选项；默认保持切换当前 profile 的行为。
      * @returns 用 profile 还原后的客户端实例。
      * @throws {ZentaoError} `E_NO_PROFILE`（无任何 profile 且未传 key）、`E_PROFILE_NOT_FOUND`（指定 key 不存在）、
-     *   `E_PROFILE_STORAGE_UNAVAILABLE`（运行时无法访问持久化存储）。
+     *   `E_PROFILE_STORAGE_INVALID`（存储内容不合法）、`E_PROFILE_STORAGE_UNAVAILABLE`（运行时无法访问持久化存储）。
      */
-    static async fromProfile(profileKey) {
-        // switchProfile 会在内部读取存储、校验 key 并刷新 lastUsedTime 后写回，
-        // 若 key 不存在会抛出 E_PROFILE_NOT_FOUND；不传 key 时由 switchCurrentProfile 处理。
-        const activeProfile = await switchProfile(profileKey);
+    static async fromProfile(profileKey, options = {}) {
+        const activeProfile = options.activate === false ? await getProfileOrThrow(profileKey) : await switchProfile(profileKey);
         const client = new ZentaoClient({
             baseUrl: activeProfile.server,
             token: activeProfile.token,

package/dist/misc/errors.d.ts

@@ -19,7 +19,7 @@ export declare const ERRORS: {
     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_INVALID: "ZenTao profile storage must be a JSON object with a profiles array and an optional currentProfile string.";
     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}";

package/dist/misc/errors.js

@@ -19,7 +19,7 @@ export const ERRORS = {
     E_INVALID_PROFILE: 'Invalid ZenTao profile.',
     E_NO_PROFILE: 'No ZenTao profile is configured.',
     E_PROFILE_NOT_FOUND: 'ZenTao profile not found: {profileKey}',
-    E_PROFILE_STORAGE_INVALID: 'ZenTao profile storage is not valid JSON.',
+    E_PROFILE_STORAGE_INVALID: 'ZenTao profile storage must be a JSON object with a profiles array and an optional currentProfile string.',
     E_PROFILE_STORAGE_UNAVAILABLE: 'ZenTao profile storage is unavailable in this runtime.',
     E_INVALID_MODULE: 'Unknown module: {module}',
     E_INVALID_ACTION: 'Unknown action: {module}-{action}',

package/dist/modules/registry-store.js

@@ -156,6 +156,9 @@ export function validateAction(action) {
     if (action.resultType !== undefined && typeof action.resultType !== 'string') {
         throw new ZentaoError('E_INVALID_ACTION_DEFINITION');
     }
+    if (action.request !== undefined && typeof action.request !== 'function') {
+        throw new ZentaoError('E_INVALID_ACTION_DEFINITION');
+    }
 }
 /** 当前运行时注册表中的模块数组（define 侧原地修改，query 侧只读）。 */
 export function getModulesState() {

package/dist/profiles/file-lock.d.ts

@@ -0,0 +1,6 @@
+/**
+ * 在同一主机的本地文件系统上保护 profile 的 read-modify-write。
+ * 仅回收已确认退出的本机进程；不以锁的年龄判断进程是否仍在写入。
+ * @internal
+ */
+export declare function withProfileFileLock<T>(file: string, operation: () => Promise<T>, timeoutMs?: number): Promise<T>;

package/dist/profiles/file-lock.js

@@ -0,0 +1,127 @@
+import { ZentaoError } from '../misc/errors.js';
+// 间接导入，避免浏览器打包器解析 Node 内置模块。
+function importNodeModule(specifier) {
+    return import(specifier);
+}
+/**
+ * 在同一主机的本地文件系统上保护 profile 的 read-modify-write。
+ * 仅回收已确认退出的本机进程；不以锁的年龄判断进程是否仍在写入。
+ * @internal
+ */
+export async function withProfileFileLock(file, operation, timeoutMs = 5000) {
+    const [fs, path, os, crypto] = await Promise.all([
+        importNodeModule('node:fs/promises'),
+        importNodeModule('node:path'),
+        importNodeModule('node:os'),
+        importNodeModule('node:crypto'),
+    ]);
+    await fs.mkdir(path.dirname(file), { recursive: true, mode: 0o700 });
+    const directory = await fs.realpath(path.dirname(file));
+    const lock = path.join(directory, `${path.basename(file)}.lock`);
+    const ownerName = `${process.pid}-${crypto.randomUUID()}.json`;
+    const candidate = `${lock}.${ownerName}`;
+    const hostname = os.hostname();
+    async function removeOwner(name) {
+        try {
+            await fs.unlink(path.join(lock, name));
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return;
+            throw error;
+        }
+        try {
+            // 迟到的释放者/回收者不能删除后继持有者的非空目录。
+            await fs.rmdir(lock);
+        }
+        catch (error) {
+            if (!['ENOENT', 'ENOTEMPTY', 'EEXIST'].includes(error.code ?? ''))
+                throw error;
+        }
+    }
+    async function reclaimDeadOwner() {
+        try {
+            const entries = await fs.readdir(lock, { withFileTypes: true });
+            if (entries.length !== 1 || !entries[0].isFile())
+                return;
+            const name = entries[0].name;
+            if (!/^[1-9]\d*-[\da-f]{8}-(?:[\da-f]{4}-){3}[\da-f]{12}\.json$/.test(name))
+                return;
+            let owner;
+            try {
+                owner = JSON.parse(await fs.readFile(path.join(lock, name), 'utf8'));
+            }
+            catch (error) {
+                if (error instanceof SyntaxError)
+                    return;
+                throw error;
+            }
+            if (!owner || typeof owner.pid !== 'number' || !Number.isSafeInteger(owner.pid)
+                || owner.pid <= 0 || !name.startsWith(`${owner.pid}-`) || owner.hostname !== hostname)
+                return;
+            try {
+                process.kill(owner.pid, 0);
+            }
+            catch (error) {
+                if (error.code === 'ESRCH')
+                    await removeOwner(name);
+                // EPERM 或未知错误都不能证明进程已退出。
+            }
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+    }
+    await fs.mkdir(candidate, { mode: 0o700 });
+    let acquired = false;
+    try {
+        await fs.writeFile(path.join(candidate, ownerName), JSON.stringify({ pid: process.pid, hostname }), {
+            flag: 'wx', mode: 0o600,
+        });
+        const started = performance.now();
+        while (performance.now() - started < timeoutMs) {
+            try {
+                // 先准备非空目录再原子 rename，不留下“已有锁但尚无 owner”的窗口。
+                await fs.rename(candidate, lock);
+                acquired = true;
+                break;
+            }
+            catch (error) {
+                const code = error.code;
+                if (code === 'EPERM') {
+                    // Windows 对已有目录可能返回 EPERM；没有目标目录时保留真实权限错误。
+                    const existing = await fs.stat(lock).catch(statError => {
+                        if (statError.code === 'ENOENT')
+                            return undefined;
+                        throw statError;
+                    });
+                    if (!existing?.isDirectory())
+                        throw error;
+                }
+                else if (code !== 'EEXIST' && code !== 'ENOTEMPTY') {
+                    throw error;
+                }
+                await reclaimDeadOwner();
+                const remaining = timeoutMs - (performance.now() - started);
+                if (remaining > 0) {
+                    await new Promise(resolve => setTimeout(resolve, Math.min(remaining, 25 + Math.random() * 25)));
+                }
+            }
+        }
+        if (!acquired) {
+            throw new ZentaoError('E_PROFILE_STORAGE_UNAVAILABLE', undefined, new Error('Timed out waiting for the profile file lock.'));
+        }
+        try {
+            return await operation();
+        }
+        finally {
+            await removeOwner(ownerName);
+        }
+    }
+    finally {
+        // 此候选目录只属于本次调用；固定锁目录绝不能递归删除。
+        if (!acquired)
+            await fs.rm(candidate, { recursive: true, force: true });
+    }
+}

package/dist/profiles/index.d.ts

@@ -23,7 +23,7 @@ export declare function getProfileKey(profile: Pick<ZentaoProfile, 'account' | '
  * 读取过程不会写回存储；存储中无法解析的条目会被静默忽略，不会影响其余 profile。
  *
  * @returns 当前存储中的所有 profile（带 `key` 字段），文件不存在时返回空数组。
- * @throws {ZentaoError} `E_PROFILE_STORAGE_INVALID`（存储内容不是合法 JSON）或
+ * @throws {ZentaoError} `E_PROFILE_STORAGE_INVALID`（存储内容不是合法 JSON 或根结构不合法）或
  *   `E_PROFILE_STORAGE_UNAVAILABLE`（运行时无法访问存储）。
  */
 export declare function getAllProfiles(): Promise<ZentaoProfileRecord[]>;
@@ -35,13 +35,16 @@ export declare function getAllProfiles(): Promise<ZentaoProfileRecord[]>;
  * @throws {ZentaoError} `E_PROFILE_STORAGE_INVALID` / `E_PROFILE_STORAGE_UNAVAILABLE`。
  */
 export declare function getProfile(profileKey?: string): Promise<ZentaoProfileRecord | undefined>;
+/** 只读恢复与账号切换共用相同的 key 解析和错误语义。 @internal */
+export declare function getProfileOrThrow(profileKey?: string): Promise<ZentaoProfileRecord>;
 /**
  * 添加或覆盖一个本地 profile，并把它设置为当前使用的 profile。
  *
  * 行为细节：
  * - 同 key（`account@server`）已存在时会**整体覆盖**而非合并字段。
  * - 写入时会自动补齐 `loginTime` 与 `lastUsedTime`（若调用方未提供则使用当前 ISO 时间）。
- * - 操作通过进程内串行锁保护 read-modify-write，避免并发调用导致的 lost update；跨进程并发不在保证范围。
+ * - Node.js 通过文件锁保护同主机本地文件系统的 read-modify-write；浏览器在支持 Web Locks 时保护同源上下文，其他环境仅保证实例内串行。
+ * - 跨进程或上下文等待锁超过约 5 秒时抛出存储不可用错误，不修改 profile 数据。
  * - 实际写入使用临时文件 + `rename` 的原子方式，并将文件与目录权限收紧到 `0600`/`0700`（Node.js 下）。
  *
  * @param profile - 要写入的 profile，必须至少包含 `server`、`account`、`token`。
@@ -50,12 +53,14 @@ export declare function getProfile(profileKey?: string): Promise<ZentaoProfileRe
  *   `E_INVALID_BASE_URL`、`E_PROFILE_STORAGE_INVALID`、`E_PROFILE_STORAGE_UNAVAILABLE`。
  */
 export declare function addProfile(profile: ZentaoProfile): Promise<ZentaoProfileRecord>;
+/** 登录只更新会话字段和显式偏好，保留同账号的应用数据。 @internal */
+export declare function saveLoginProfile(profile: ZentaoProfile): Promise<ZentaoProfileRecord>;
 /** 只刷新已有 profile 的服务器配置，不切换当前账号或重建已删除的记录。 @internal */
 export declare function updateProfileServerConfig(profileKey: string, serverConfig: ServerConfig, fetchedAt: string): Promise<void>;
 /**
  * 删除指定 profile。
  *
- * 若被删除的是当前 profile，会回退为列表中最近一次写入的 profile；若已无任何 profile，
+ * 若被删除的是当前 profile，会回退为最近添加且仍保留的 profile；覆盖或切换已有记录不改变添加顺序。若已无任何 profile，
  * 当前 profile 会被清空。操作同样通过进程内串行锁保护。
  *
  * @param profileKey - 要删除的 profile key。