zentao-api 0.6.7 → 0.6.8

package/dist/profiles/index.js

@@ -1,6 +1,7 @@
 import { ZentaoError } from '../misc/errors.js';
 import { isNodeRuntime } from '../misc/environment.js';
 import { isRecord, normalizeSiteUrl } from '../utils/index.js';
+import { withProfileFileLock } from './file-lock.js';
 /**
  * 浏览器环境下用于在 `localStorage` 中保存 profile 数据的 key。
  *
@@ -21,23 +22,48 @@ function nowString() {
 function importNodeModule(specifier) {
     return import(specifier);
 }
-// 进程内串行锁：所有 read-modify-write 类的 profile 操作都通过这个队列，
-// 避免并发 `addProfile`/`switchProfile` 出现 lost update（写文件本身是原子
-// rename，但 read→modify→write 之间没有跨步保护）。跨进程并发不在保证范围内。
+// 所有 read-modify-write 都先进入实例队列，再取得文件锁或浏览器 Web Lock。
 let storeMutex = Promise.resolve();
 function withStoreMutex(operation) {
-    const next = storeMutex.then(operation, operation);
+    const run = () => withStorageErrors(async () => {
+        if (isNodeRuntime())
+            return withProfileFileLock(await getProfileFilePath(), operation);
+        const locks = globalThis.navigator?.locks;
+        // ponytail: 没有 Web Locks 时仅保证实例内串行；需要跨标签保证的应用应使用支持 Web Locks 的环境。
+        if (!locks)
+            return operation();
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), 5000);
+        try {
+            return await locks.request(`${ZENTAO_PROFILES_STORAGE_KEY}:write`, { signal: controller.signal }, () => {
+                clearTimeout(timeout);
+                return operation();
+            });
+        }
+        finally {
+            clearTimeout(timeout);
+        }
+    });
+    const next = storeMutex.then(run, run);
     storeMutex = next.catch(() => undefined);
     return next;
 }
-function getBrowserStorage() {
+async function withStorageErrors(operation) {
     try {
-        return globalThis.localStorage;
+        return await operation();
     }
-    catch {
-        return undefined;
+    catch (error) {
+        if (error instanceof ZentaoError)
+            throw error;
+        throw new ZentaoError('E_PROFILE_STORAGE_UNAVAILABLE', undefined, error);
     }
 }
+function getBrowserStorage() {
+    const storage = globalThis.localStorage;
+    if (!storage)
+        throw new ZentaoError('E_PROFILE_STORAGE_UNAVAILABLE');
+    return storage;
+}
 async function getProfileFilePath() {
     const path = await importNodeModule('node:path');
     const home = process.env.HOME
@@ -60,30 +86,31 @@ function normalizeProfile(profile) {
         throw new ZentaoError('E_INVALID_PROFILE');
     }
     const token = profile.token.trim();
-    if (!token)
+    const account = profile.account.trim();
+    if (!token || !account)
         throw new ZentaoError('E_INVALID_PROFILE');
     const copy = cloneJson(profile);
     delete copy.key;
     return {
         ...copy,
         server: normalizeSiteUrl(profile.server),
-        account: profile.account.trim(),
+        account,
         token,
     };
 }
 function normalizeStore(raw) {
-    if (!isRecord(raw))
-        return { profiles: [] };
-    const profiles = Array.isArray(raw.profiles)
-        ? raw.profiles.flatMap((profile) => {
-            try {
-                return [normalizeProfile(profile)];
-            }
-            catch {
-                return [];
-            }
-        })
-        : [];
+    if (!isRecord(raw) || !Array.isArray(raw.profiles)
+        || (raw.currentProfile !== undefined && typeof raw.currentProfile !== 'string')) {
+        throw new ZentaoError('E_PROFILE_STORAGE_INVALID');
+    }
+    const profiles = raw.profiles.flatMap((profile) => {
+        try {
+            return [normalizeProfile(profile)];
+        }
+        catch {
+            return [];
+        }
+    });
     const currentProfile = typeof raw.currentProfile === 'string' ? raw.currentProfile : undefined;
     return currentProfile ? { currentProfile, profiles } : { profiles };
 }
@@ -95,54 +122,50 @@ function parseStore(text) {
         throw new ZentaoError('E_PROFILE_STORAGE_INVALID', undefined, error);
     }
 }
-async function readStore() {
-    if (isNodeRuntime()) {
-        const fs = await importNodeModule('node:fs/promises');
-        const file = await getProfileFilePath();
-        try {
-            return parseStore(await fs.readFile(file, 'utf8'));
-        }
-        catch (error) {
-            if (error.code === 'ENOENT') {
-                return { profiles: [] };
+function readStore() {
+    return withStorageErrors(async () => {
+        if (isNodeRuntime()) {
+            const fs = await importNodeModule('node:fs/promises');
+            const file = await getProfileFilePath();
+            try {
+                return parseStore(await fs.readFile(file, 'utf8'));
+            }
+            catch (error) {
+                if (error.code === 'ENOENT') {
+                    return { profiles: [] };
+                }
+                throw error;
             }
-            throw error;
         }
-    }
-    const storage = getBrowserStorage();
-    if (!storage) {
-        throw new ZentaoError('E_PROFILE_STORAGE_UNAVAILABLE');
-    }
-    const text = storage.getItem(ZENTAO_PROFILES_STORAGE_KEY);
-    return text ? parseStore(text) : { profiles: [] };
+        const text = getBrowserStorage().getItem(ZENTAO_PROFILES_STORAGE_KEY);
+        return text === null ? { profiles: [] } : parseStore(text);
+    });
 }
-async function writeStore(store) {
-    const normalizedStore = normalizeStore(store);
-    const text = `${JSON.stringify(normalizedStore, null, 2)}\n`;
-    if (isNodeRuntime()) {
-        const fs = await importNodeModule('node:fs/promises');
-        const path = await importNodeModule('node:path');
-        const file = await getProfileFilePath();
-        const dir = path.dirname(file);
-        const tempFile = path.join(dir, `.zentao.${Date.now()}.${Math.random().toString(36).slice(2)}.tmp`);
-        await fs.mkdir(dir, { recursive: true, mode: 0o700 });
-        await fs.chmod(dir, 0o700).catch(() => undefined);
-        try {
-            await fs.writeFile(tempFile, text, { encoding: 'utf8', mode: 0o600 });
-            await fs.rename(tempFile, file);
-            await fs.chmod(file, 0o600).catch(() => undefined);
-        }
-        catch (error) {
-            await fs.rm(tempFile, { force: true }).catch(() => undefined);
-            throw error;
+function writeStore(store) {
+    return withStorageErrors(async () => {
+        const normalizedStore = normalizeStore(store);
+        const text = `${JSON.stringify(normalizedStore, null, 2)}\n`;
+        if (isNodeRuntime()) {
+            const fs = await importNodeModule('node:fs/promises');
+            const path = await importNodeModule('node:path');
+            const file = await getProfileFilePath();
+            const dir = path.dirname(file);
+            const tempFile = path.join(dir, `.zentao.${Date.now()}.${Math.random().toString(36).slice(2)}.tmp`);
+            await fs.mkdir(dir, { recursive: true, mode: 0o700 });
+            await fs.chmod(dir, 0o700).catch(() => undefined);
+            try {
+                await fs.writeFile(tempFile, text, { encoding: 'utf8', mode: 0o600 });
+                await fs.rename(tempFile, file);
+                await fs.chmod(file, 0o600).catch(() => undefined);
+            }
+            catch (error) {
+                await fs.rm(tempFile, { force: true }).catch(() => undefined);
+                throw error;
+            }
+            return;
         }
-        return;
-    }
-    const storage = getBrowserStorage();
-    if (!storage) {
-        throw new ZentaoError('E_PROFILE_STORAGE_UNAVAILABLE');
-    }
-    storage.setItem(ZENTAO_PROFILES_STORAGE_KEY, text);
+        getBrowserStorage().setItem(ZENTAO_PROFILES_STORAGE_KEY, text);
+    });
 }
 function toRecord(profile) {
     const normalized = normalizeProfile(profile);
@@ -154,6 +177,15 @@ function toRecord(profile) {
 function findProfile(store, profileKey) {
     return store.profiles.find((profile) => getProfileKey(profile) === profileKey);
 }
+function requireProfile(store, profileKey) {
+    const key = profileKey ?? store.currentProfile;
+    if (!key)
+        throw new ZentaoError('E_NO_PROFILE');
+    const profile = findProfile(store, key);
+    if (!profile)
+        throw new ZentaoError('E_PROFILE_NOT_FOUND', { profileKey: key });
+    return profile;
+}
 function setFallbackCurrentProfile(store) {
     if (!store.currentProfile || !findProfile(store, store.currentProfile)) {
         const fallback = store.profiles.at(-1);
@@ -180,7 +212,7 @@ export function getProfileKey(profile) {
  * 读取过程不会写回存储；存储中无法解析的条目会被静默忽略，不会影响其余 profile。
  *
  * @returns 当前存储中的所有 profile（带 `key` 字段），文件不存在时返回空数组。
- * @throws {ZentaoError} `E_PROFILE_STORAGE_INVALID`（存储内容不是合法 JSON）或
+ * @throws {ZentaoError} `E_PROFILE_STORAGE_INVALID`（存储内容不是合法 JSON 或根结构不合法）或
  *   `E_PROFILE_STORAGE_UNAVAILABLE`（运行时无法访问存储）。
  */
 export async function getAllProfiles() {
@@ -202,13 +234,18 @@ export async function getProfile(profileKey) {
     const profile = findProfile(store, key);
     return profile ? toRecord(profile) : undefined;
 }
+/** 只读恢复与账号切换共用相同的 key 解析和错误语义。 @internal */
+export async function getProfileOrThrow(profileKey) {
+    return toRecord(requireProfile(await readStore(), profileKey));
+}
 /**
  * 添加或覆盖一个本地 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`。
@@ -217,10 +254,17 @@ export async function getProfile(profileKey) {
  *   `E_INVALID_BASE_URL`、`E_PROFILE_STORAGE_INVALID`、`E_PROFILE_STORAGE_UNAVAILABLE`。
  */
 export function addProfile(profile) {
+    return saveProfile(profile);
+}
+/** 登录只更新会话字段和显式偏好，保留同账号的应用数据。 @internal */
+export function saveLoginProfile(profile) {
+    return saveProfile(profile, true);
+}
+function saveProfile(profile, preservePreferences = false) {
     return withStoreMutex(async () => {
         const store = await readStore();
         const timestamp = nowString();
-        const normalized = normalizeProfile({
+        let normalized = normalizeProfile({
             ...profile,
             loginTime: profile.loginTime ?? timestamp,
             lastUsedTime: profile.lastUsedTime ?? timestamp,
@@ -228,6 +272,12 @@ export function addProfile(profile) {
         const profileKey = getProfileKey(normalized);
         const index = store.profiles.findIndex((item) => getProfileKey(item) === profileKey);
         if (index >= 0) {
+            if (preservePreferences) {
+                const previous = store.profiles[index];
+                const config = { ...(isRecord(previous.config) ? previous.config : {}), ...normalized.config };
+                normalized = normalizeProfile({ ...previous, ...profile, ...normalized,
+                    config: Object.keys(config).length ? config : undefined });
+            }
             store.profiles[index] = normalized;
         }
         else {
@@ -253,7 +303,7 @@ export function updateProfileServerConfig(profileKey, serverConfig, fetchedAt) {
 /**
  * 删除指定 profile。
  *
- * 若被删除的是当前 profile，会回退为列表中最近一次写入的 profile；若已无任何 profile，
+ * 若被删除的是当前 profile，会回退为最近添加且仍保留的 profile；覆盖或切换已有记录不改变添加顺序。若已无任何 profile，
  * 当前 profile 会被清空。操作同样通过进程内串行锁保护。
  *
  * @param profileKey - 要删除的 profile key。
@@ -287,16 +337,9 @@ export function deleteProfile(profileKey) {
 export function switchProfile(profileKey) {
     return withStoreMutex(async () => {
         const store = await readStore();
-        const key = profileKey ?? store.currentProfile;
-        if (!key) {
-            throw new ZentaoError('E_NO_PROFILE');
-        }
-        const profile = findProfile(store, key);
-        if (!profile) {
-            throw new ZentaoError('E_PROFILE_NOT_FOUND', { profileKey: key });
-        }
+        const profile = requireProfile(store, profileKey);
         profile.lastUsedTime = nowString();
-        store.currentProfile = key;
+        store.currentProfile = getProfileKey(profile);
         await writeStore(store);
         return toRecord(profile);
     });

package/dist/request/index.js

@@ -234,14 +234,18 @@ async function requestInternal(name, params, options, version) {
     const preparedBody = await prepareActionBody(command, {
         maxUploadBytes: options.maxUploadBytes,
     });
-    const raw = await client.request(command.path, {
-        method: String(command.action.method).toUpperCase(),
-        query: command.query,
-        body: preparedBody.body,
-        bodyType: preparedBody.bodyType,
+    const requestOptions = {
+        ...preparedBody,
         timeout: options.timeout ?? globals.timeout,
         insecure: options.insecure ?? globals.insecure,
-    });
+    };
+    const raw = command.action.request
+        ? await command.action.request({ request: command, ...requestOptions, client, options })
+        : await client.request(command.path, {
+            method: String(command.action.method).toUpperCase(),
+            query: command.query,
+            ...requestOptions,
+        });
     if (options.raw) {
         return raw;
     }

package/dist/types/client.d.ts

@@ -1,3 +1,8 @@
+/** 从本地 profile 恢复客户端时的选项。 */
+export interface FromProfileOptions {
+    /** 是否切换为当前 profile 并更新使用时间，默认 true；false 时恢复过程只读存储。 */
+    activate?: boolean;
+}
 /** 创建 {@link ZentaoClient} 时使用的配置。 */
 export interface ZentaoClientOptions {
     /** 禅道站点根地址，例如 `https://zentao.example.com`；SDK 会自动拼接 `/api.php/v2`。 */

package/dist/types/module.d.ts

@@ -1,5 +1,6 @@
-import type { HttpMethod } from './client.js';
-import type { RequestProcessOptions } from './options.js';
+import type { ZentaoClient } from '../client/index.js';
+import type { ClientRequestBodyType, HttpMethod } from './client.js';
+import type { RequestOptions, RequestProcessOptions } from './options.js';
 import type { Pager } from './response.js';
 /** 模块动作类型：基础 CRUD 或自定义动作。 */
 export type ModuleActionType = 'list' | 'get' | 'create' | 'update' | 'delete' | 'action';
@@ -86,6 +87,26 @@ export type ModuleActionResultFieldMap = Readonly<Record<string, string>>;
  * @param options 本次请求的数据处理选项；直接调用 getter 时可以省略。
  */
 export type ModuleActionGetterFn<T, O = RequestProcessOptions> = (data: unknown, params: Record<string, unknown>, options?: O) => T;
+/**
+ * 自定义动作的请求发送逻辑，在版本检查、参数解析和请求体准备完成后调用。
+ * 返回原始响应数据，后续仍按动作定义提取结果、分页并应用请求选项；抛出的错误原样传递。
+ */
+export type ModuleActionRequestCallback = (info: {
+    /** 解析后的路径、查询参数、请求体数据及动作定义。 */
+    request: ModuleActionRequest;
+    /** 准备好的请求体，例如 JSON 对象或上传用的 FormData。 */
+    body: unknown;
+    /** 请求体序列化方式，可直接传给客户端。 */
+    bodyType?: ClientRequestBodyType;
+    /** 本次请求的超时选项，未指定时回落到全局选项。 */
+    timeout?: number;
+    /** 本次请求的 TLS 选项，未指定时回落到全局选项。 */
+    insecure?: boolean;
+    /** 本次调用选定的客户端。 */
+    client: ZentaoClient;
+    /** 调用方传入的原始请求选项。 */
+    options: RequestOptions;
+}) => Promise<unknown>;
 /** 禅道模块中的单个 API 动作定义。 */
 export interface ModuleAction {
     /** 动作名称，例如 `list`、`get`、`close`。 */
@@ -128,6 +149,8 @@ export interface ModuleAction {
      * 字符串为字段路径（支持 `a.b` 嵌套）、对象为字段映射、函数则接收原始响应与调用参数。
      */
     resultGetter?: string | ModuleActionResultFieldMap | ModuleActionGetterFn<unknown>;
+    /** 自定义请求回调；省略时通过 ZentaoClient.request 发送请求，返回值沿用相同的响应处理流程。 */
+    request?: ModuleActionRequestCallback;
 }
 /** 内置模块名称，同时允许用户扩展自定义模块名。 */
 export type ModuleName = 'user' | 'program' | 'product' | 'project' | 'execution' | 'productplan' | 'story' | 'epic' | 'requirement' | 'bug' | 'testcase' | 'task' | 'feedback' | 'ticket' | 'system' | 'build' | 'testtask' | 'release' | 'file' | (string & {});

package/dist/types/profile.d.ts

@@ -1,23 +1,27 @@
 import type { ServerConfig } from './response.js';
-/** 保存到本地 profile 中的客户端偏好配置。 */
+/**
+ * 保存到本地 profile 中的客户端偏好配置。
+ * SDK 自动恢复 `timeout` / `insecure`；其余字段仅供上层应用读取和解释。
+ * 自定义值应使用 JSON 数据，不保留 Date、Map 等类型信息，不支持 BigInt 或循环对象。
+ */
 export interface ZentaoProfileConfig {
     /** 默认输出格式，供 CLI 等上层应用复用。 */
     defaultOutputFormat?: 'markdown' | 'json' | 'raw';
-    /** 界面语言。 */
+    /** 上层应用的界面语言，SDK 不自动应用。 */
     lang?: string;
-    /** 默认分页大小。 */
+    /** 上层应用的默认分页大小；SDK 请求分页使用 `recPerPage` 选项。 */
     defaultRecPerPage?: number;
     /** 是否跳过 TLS 证书验证；仅 Node.js 运行时支持。 */
     insecure?: boolean;
     /** 请求超时时间，单位毫秒。 */
     timeout?: number;
-    /** 是否在批量操作出错时停止执行后续操作。 */
+    /** 上层应用是否在批量操作出错时停止执行后续操作。 */
     batchFailFast?: boolean;
-    /** JSON 格式化时是否添加缩进。 */
+    /** 上层应用格式化 JSON 时是否添加缩进。 */
     jsonPretty?: boolean;
-    /** 模块级分页偏好。 */
+    /** 上层应用的模块级分页偏好，SDK 不自动应用。 */
     pagers?: Record<string, number>;
-    /** 允许上层应用保存自定义配置。 */
+    /** 允许上层应用保存 JSON 格式的自定义配置。 */
     [key: string]: unknown;
 }
 /** 本地持久化的禅道账号 profile。 */
@@ -40,7 +44,7 @@ export interface ZentaoProfile {
     serverConfigFetchedAt?: string;
     /** 客户端自定义配置。 */
     config?: ZentaoProfileConfig;
-    /** 允许上层应用保存额外字段。 */
+    /** 允许上层应用保存 JSON 格式的额外字段，不保留 Date、Map 等类型信息，不支持 BigInt 或循环对象。 */
     [key: string]: unknown;
 }
 /** 运行时返回的 profile，会额外带上 `account@server` 形式的 key。 */

package/dist/version.js

@@ -1,5 +1,5 @@
-const fallbackBuild = "2026-09-05T14:37:58.417Z";
-const fallbackVersion = "0.6.7";
+const fallbackBuild = "2026-09-06T14:52:03.785Z";
+const fallbackVersion = "0.6.8";
 /**
  * 构建标识，由构建脚本通过 `__ZENTAO_API_BUILD__` 注入。
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zentao-api",
-  "version": "0.6.7",
+  "version": "0.6.8",
   "type": "module",
   "description": "Browser and Node.js SDK for ZenTao API",
   "license": "MIT",