zentao-api 0.2.0-beta.1 → 0.2.0

package/dist/profiles/index.js

@@ -0,0 +1,294 @@
+import { ZentaoError } from '../misc/errors.js';
+import { isNodeRuntime } from '../misc/environment.js';
+import { normalizeSiteUrl } from '../utils/index.js';
+/**
+ * 浏览器环境下用于在 `localStorage` 中保存 profile 数据的 key。
+ *
+ * Node.js 环境会改用文件 `~/.config/zentao/zentao.json`，与此常量无关。
+ */
+export const ZENTAO_PROFILES_STORAGE_KEY = 'ZENTAO_PROFILES';
+const PROFILE_FILE_PARTS = ['.config', 'zentao', 'zentao.json'];
+function isRecord(value) {
+    return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+function cloneJson(value) {
+    if (value === undefined)
+        return value;
+    return JSON.parse(JSON.stringify(value));
+}
+function nowString() {
+    return new Date().toISOString();
+}
+// 通过函数参数间接化 `import(specifier)`，避免打包器把 Node 内置模块拉进
+// 浏览器 bundle；同时不依赖 `new Function`/`eval`，对严格 CSP 友好。
+function importNodeModule(specifier) {
+    return import(specifier);
+}
+// 进程内串行锁：所有 read-modify-write 类的 profile 操作都通过这个队列，
+// 避免并发 `addProfile`/`switchProfile` 出现 lost update（写文件本身是原子
+// rename，但 read→modify→write 之间没有跨步保护）。跨进程并发不在保证范围内。
+let storeMutex = Promise.resolve();
+function withStoreMutex(operation) {
+    const next = storeMutex.then(operation, operation);
+    storeMutex = next.catch(() => undefined);
+    return next;
+}
+function getBrowserStorage() {
+    try {
+        return globalThis.localStorage;
+    }
+    catch {
+        return undefined;
+    }
+}
+async function getProfileFilePath() {
+    const path = await importNodeModule('node:path');
+    const home = process.env.HOME
+        ?? process.env.USERPROFILE
+        ?? (await importNodeModule('node:os')).homedir();
+    if (!home) {
+        throw new ZentaoError('E_PROFILE_STORAGE_UNAVAILABLE');
+    }
+    return path.join(home, ...PROFILE_FILE_PARTS);
+}
+function profileKeyFromParts(account, server) {
+    const normalizedAccount = account.trim();
+    const normalizedServer = normalizeSiteUrl(server);
+    if (!normalizedAccount)
+        throw new ZentaoError('E_INVALID_PROFILE');
+    return `${normalizedAccount}@${normalizedServer}`;
+}
+function normalizeProfile(profile) {
+    if (!isRecord(profile) || typeof profile.server !== 'string' || typeof profile.account !== 'string' || typeof profile.token !== 'string') {
+        throw new ZentaoError('E_INVALID_PROFILE');
+    }
+    const token = profile.token.trim();
+    if (!token)
+        throw new ZentaoError('E_INVALID_PROFILE');
+    const copy = cloneJson(profile);
+    delete copy.key;
+    return {
+        ...copy,
+        server: normalizeSiteUrl(profile.server),
+        account: profile.account.trim(),
+        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 [];
+            }
+        })
+        : [];
+    const currentProfile = typeof raw.currentProfile === 'string' ? raw.currentProfile : undefined;
+    return currentProfile ? { currentProfile, profiles } : { profiles };
+}
+function parseStore(text) {
+    try {
+        return normalizeStore(JSON.parse(text));
+    }
+    catch (error) {
+        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: [] };
+            }
+            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: [] };
+}
+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;
+        }
+        return;
+    }
+    const storage = getBrowserStorage();
+    if (!storage) {
+        throw new ZentaoError('E_PROFILE_STORAGE_UNAVAILABLE');
+    }
+    storage.setItem(ZENTAO_PROFILES_STORAGE_KEY, text);
+}
+function toRecord(profile) {
+    const normalized = normalizeProfile(profile);
+    return {
+        ...cloneJson(normalized),
+        key: getProfileKey(normalized),
+    };
+}
+function findProfile(store, profileKey) {
+    return store.profiles.find((profile) => getProfileKey(profile) === profileKey);
+}
+function setFallbackCurrentProfile(store) {
+    if (!store.currentProfile || !findProfile(store, store.currentProfile)) {
+        const fallback = store.profiles.at(-1);
+        store.currentProfile = fallback ? getProfileKey(fallback) : undefined;
+    }
+}
+/**
+ * 根据 profile 的账号和禅道站点地址生成稳定 key。
+ *
+ * Key 格式为 `account@server`，其中 `server` 会经过 {@link normalizeSiteUrl} 规范化，
+ * 因此即使传入末尾带 `/` 或 `/api.php/v2` 的地址，也会得到一致的结果。
+ *
+ * @param profile - 只需要包含 `account` 和 `server` 两个字段。
+ * @returns 形如 `admin@https://zentao.example.com` 的 profile key。
+ * @throws {ZentaoError} `E_INVALID_PROFILE`（账号为空白）或 `E_INVALID_BASE_URL`（`server` 不合法）。
+ */
+export function getProfileKey(profile) {
+    return profileKeyFromParts(profile.account, profile.server);
+}
+/**
+ * 列出本地保存的所有 profile。
+ *
+ * Node.js 下从 `~/.config/zentao/zentao.json` 读取；浏览器下从 `localStorage` 读取。
+ * 读取过程不会写回存储；存储中无法解析的条目会被静默忽略，不会影响其余 profile。
+ *
+ * @returns 当前存储中的所有 profile（带 `key` 字段），文件不存在时返回空数组。
+ * @throws {ZentaoError} `E_PROFILE_STORAGE_INVALID`（存储内容不是合法 JSON）或
+ *   `E_PROFILE_STORAGE_UNAVAILABLE`（运行时无法访问存储）。
+ */
+export async function getAllProfiles() {
+    const store = await readStore();
+    return store.profiles.map(toRecord);
+}
+/**
+ * 获取指定 profile。
+ *
+ * @param profileKey - 可选的 profile key（`account@server`）；不传时返回当前（最近一次切换的）profile。
+ * @returns 命中的 profile（带 `key` 字段）；当 key 不存在或尚未配置当前 profile 时返回 `undefined`。
+ * @throws {ZentaoError} `E_PROFILE_STORAGE_INVALID` / `E_PROFILE_STORAGE_UNAVAILABLE`。
+ */
+export async function getProfile(profileKey) {
+    const store = await readStore();
+    const key = profileKey ?? store.currentProfile;
+    if (!key)
+        return undefined;
+    const profile = findProfile(store, key);
+    return profile ? toRecord(profile) : undefined;
+}
+/**
+ * 添加或覆盖一个本地 profile，并把它设置为当前使用的 profile。
+ *
+ * 行为细节：
+ * - 同 key（`account@server`）已存在时会**整体覆盖**而非合并字段。
+ * - 写入时会自动补齐 `loginTime` 与 `lastUsedTime`（若调用方未提供则使用当前 ISO 时间）。
+ * - 操作通过进程内串行锁保护 read-modify-write，避免并发调用导致的 lost update；跨进程并发不在保证范围。
+ * - 实际写入使用临时文件 + `rename` 的原子方式，并将文件与目录权限收紧到 `0600`/`0700`（Node.js 下）。
+ *
+ * @param profile - 要写入的 profile，必须至少包含 `server`、`account`、`token`。
+ * @returns 实际写入并附带 `key` 字段的 profile 记录。
+ * @throws {ZentaoError} `E_INVALID_PROFILE`（必填字段缺失或 token 为空白）、
+ *   `E_INVALID_BASE_URL`、`E_PROFILE_STORAGE_INVALID`、`E_PROFILE_STORAGE_UNAVAILABLE`。
+ */
+export function addProfile(profile) {
+    return withStoreMutex(async () => {
+        const store = await readStore();
+        const timestamp = nowString();
+        const normalized = normalizeProfile({
+            ...profile,
+            loginTime: profile.loginTime ?? timestamp,
+            lastUsedTime: profile.lastUsedTime ?? timestamp,
+        });
+        const profileKey = getProfileKey(normalized);
+        const index = store.profiles.findIndex((item) => getProfileKey(item) === profileKey);
+        if (index >= 0) {
+            store.profiles[index] = normalized;
+        }
+        else {
+            store.profiles.push(normalized);
+        }
+        store.currentProfile = profileKey;
+        await writeStore(store);
+        return toRecord(normalized);
+    });
+}
+/**
+ * 删除指定 profile。
+ *
+ * 若被删除的是当前 profile，会回退为列表中最近一次写入的 profile；若已无任何 profile，
+ * 当前 profile 会被清空。操作同样通过进程内串行锁保护。
+ *
+ * @param profileKey - 要删除的 profile key。
+ * @returns 当且仅当确实删除了某条记录时返回 `true`；key 不存在时返回 `false` 且不会写盘。
+ * @throws {ZentaoError} `E_PROFILE_STORAGE_INVALID` / `E_PROFILE_STORAGE_UNAVAILABLE`。
+ */
+export function deleteProfile(profileKey) {
+    return withStoreMutex(async () => {
+        const store = await readStore();
+        const nextProfiles = store.profiles.filter((profile) => getProfileKey(profile) !== profileKey);
+        if (nextProfiles.length === store.profiles.length)
+            return false;
+        store.profiles = nextProfiles;
+        setFallbackCurrentProfile(store);
+        await writeStore(store);
+        return true;
+    });
+}
+/**
+ * 切换当前使用的 profile，并刷新其 `lastUsedTime`。
+ *
+ * 不传 `profileKey` 时使用当前 profile（相当于把当前 profile 的 `lastUsedTime` 刷新一遍）。
+ * 切换成功后会立即写回存储，由进程内串行锁保护。
+ *
+ * @param profileKey - 可选的目标 profile key；不传则使用当前 profile。
+ * @returns 切换后生效的 profile 记录（带 `key` 字段）。
+ * @throws {ZentaoError} `E_NO_PROFILE`（未配置任何当前 profile 且未传 key）、
+ *   `E_PROFILE_NOT_FOUND`（目标 key 不存在）、`E_PROFILE_STORAGE_INVALID` /
+ *   `E_PROFILE_STORAGE_UNAVAILABLE`。
+ */
+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 });
+        }
+        profile.lastUsedTime = nowString();
+        store.currentProfile = key;
+        await writeStore(store);
+        return toRecord(profile);
+    });
+}

package/dist/request/index.d.ts

@@ -3,5 +3,14 @@ import type { RequestOptions, ResponseData } from '../types/index.js';
  * 按模块动作名请求禅道 API。
  *
  * 选项优先级为：本次调用 options > 全局 options > 客户端默认值。
+ * 当响应 `status` 为 `"fail"` 时，默认按原样返回；若 `options.throwOnFail`
+ * 或全局 `throwOnFail` 为真，则改为抛出 `E_API_FAILED`。
+ *
+ * @typeParam T 期望的 `data` 字段类型；不传时为 `unknown`，调用方需要自行收窄。
+ * @param name - 模块动作名，例如 `product/list`。
+ * @param params - 请求参数。
+ * @param options - 请求选项。
+ * @returns 归一化后的禅道 API 响应。
+ * @throws {ZentaoError} 传输层错误、参数缺失或 `throwOnFail` 启用时的业务失败。
  */
-export declare function request(name: `${string}/${string}`, params?: Record<string, unknown>, options?: RequestOptions): Promise<ResponseData>;
+export declare function request<T = unknown>(name: `${string}/${string}`, params?: Record<string, unknown>, options?: RequestOptions): Promise<ResponseData<T>>;

package/dist/request/index.js

@@ -29,7 +29,7 @@ function normalizeResponse(command, raw, limit) {
     return {
         status,
         message: typeof record.message === 'string' ? record.message : undefined,
-        data,
+        data: data,
         pager: pager ? {
             total: Number(pager.recTotal),
             page: Number(pager.pageID),
@@ -41,6 +41,15 @@ function normalizeResponse(command, raw, limit) {
  * 按模块动作名请求禅道 API。
  *
  * 选项优先级为：本次调用 options > 全局 options > 客户端默认值。
+ * 当响应 `status` 为 `"fail"` 时，默认按原样返回；若 `options.throwOnFail`
+ * 或全局 `throwOnFail` 为真，则改为抛出 `E_API_FAILED`。
+ *
+ * @typeParam T 期望的 `data` 字段类型；不传时为 `unknown`，调用方需要自行收窄。
+ * @param name - 模块动作名，例如 `product/list`。
+ * @param params - 请求参数。
+ * @param options - 请求选项。
+ * @returns 归一化后的禅道 API 响应。
+ * @throws {ZentaoError} 传输层错误、参数缺失或 `throwOnFail` 启用时的业务失败。
  */
 export async function request(name, params = {}, options = {}) {
     const globals = getGlobalOptions();
@@ -61,5 +70,9 @@ export async function request(name, params = {}, options = {}) {
         timeout: options.timeout ?? globals.timeout,
         insecure: options.insecure ?? globals.insecure,
     });
-    return normalizeResponse(command, raw, options.limit ?? globals.limit);
+    const response = normalizeResponse(command, raw, options.limit ?? globals.limit);
+    if (response.status === 'fail' && (options.throwOnFail ?? globals.throwOnFail)) {
+        throw new ZentaoError('E_API_FAILED', { message: response.message ?? '' }, response);
+    }
+    return response;
 }

package/dist/types/index.d.ts

@@ -22,6 +22,10 @@ export interface GlobalOptions {
     timeout?: number;
     /** 默认 TLS 跳过证书验证选项；仅 Node.js 运行时支持。 */
     insecure?: boolean;
+    /** 是否在登录成功后把账号、Token 和配置持久化为本地 profile。 */
+    persistProfiles?: boolean;
+    /** 当禅道服务端返回 `{ status: "fail" }` 时是否抛出 `E_API_FAILED`，默认 false。 */
+    throwOnFail?: boolean;
 }
 /** SDK 支持的 HTTP 方法。 */
 export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'DELETE';
@@ -30,7 +34,7 @@ export interface ClientRequestOptions {
     /** HTTP 方法，默认 `GET`。 */
     method?: HttpMethod;
     /** JSON 请求体；`GET` 请求会忽略该字段。 */
-    body?: Record<string, unknown>;
+    body?: unknown;
     /** URL 查询参数；`undefined` 值会被跳过。 */
     query?: Record<string, string | number | boolean | undefined>;
     /** 单次请求超时时间，优先级高于全局和客户端默认值。 */
@@ -50,15 +54,20 @@ export interface RequestOptions {
     timeout?: number;
     /** 本次调用 TLS 跳过证书验证选项；仅 Node.js 运行时支持。 */
     insecure?: boolean;
+    /**
+     * 当禅道服务端返回 `{ status: "fail" }` 时是否抛出 `E_API_FAILED`。
+     * 不传时回落到全局 `throwOnFail`，默认 false（保留原始失败响应）。
+     */
+    throwOnFail?: boolean;
 }
 /** 高阶 `request()` 归一化后的返回数据。 */
-export interface ResponseData {
+export interface ResponseData<T = unknown> {
     /** 禅道服务端状态；非标准响应会按成功响应包装到 `data`。 */
     status: 'success' | 'fail';
     /** 禅道服务端返回的消息。 */
     message?: string;
     /** 根据模块动作 `resultGetter` 提取后的业务数据。 */
-    data?: any;
+    data?: T;
     /** 统一分页信息。 */
     pager?: {
         /** 总记录数。 */
@@ -98,6 +107,10 @@ export interface ApiListResponse extends ApiResponse {
 export interface LoginResponse extends ApiResponse {
     /** 登录成功后返回的 API Token。 */
     token?: string;
+    /** 部分禅道环境会随登录响应返回用户信息。 */
+    user?: Record<string, unknown>;
+    /** 部分禅道环境会随登录响应返回服务端配置。 */
+    serverConfig?: ServerConfig;
 }
 /** 禅道 `?mode=getconfig` 返回的服务端配置。 */
 export interface ServerConfig {
@@ -111,6 +124,59 @@ export interface ServerConfig {
     viewVar: string;
     sessionVar: string;
 }
+/** 保存到本地 profile 中的客户端偏好配置。 */
+export interface ZentaoProfileConfig {
+    /** 默认输出格式，供 CLI 等上层应用复用。 */
+    defaultOutputFormat?: 'markdown' | 'json' | 'raw';
+    /** 界面语言。 */
+    lang?: string;
+    /** 默认分页大小。 */
+    defaultRecPerPage?: number;
+    /** 是否跳过 TLS 证书验证；仅 Node.js 运行时支持。 */
+    insecure?: boolean;
+    /** 请求超时时间，单位毫秒。 */
+    timeout?: number;
+    /** 是否在批量操作出错时停止执行后续操作。 */
+    batchFailFast?: boolean;
+    /** JSON 格式化时是否添加缩进。 */
+    jsonPretty?: boolean;
+    /** 模块级分页偏好。 */
+    pagers?: Record<string, number>;
+    /** 允许上层应用保存自定义配置。 */
+    [key: string]: unknown;
+}
+/** 本地持久化的禅道账号 profile。 */
+export interface ZentaoProfile {
+    /** 禅道站点根地址，不包含 `/api.php/v2`。 */
+    server: string;
+    /** 用户账号。 */
+    account: string;
+    /** 禅道 API Token。 */
+    token: string;
+    /** 登录验证通过后得到的用户信息。 */
+    user?: Record<string, unknown>;
+    /** 登录时间。 */
+    loginTime?: string;
+    /** 最后使用时间。 */
+    lastUsedTime?: string;
+    /** 禅道服务端配置。 */
+    serverConfig?: ServerConfig;
+    /** 客户端自定义配置。 */
+    config?: ZentaoProfileConfig;
+    /** 允许上层应用保存额外字段。 */
+    [key: string]: unknown;
+}
+/** 运行时返回的 profile，会额外带上 `account@server` 形式的 key。 */
+export interface ZentaoProfileRecord extends ZentaoProfile {
+    key: string;
+}
+/** 本地 profile 存储文件或浏览器 localStorage 中的 JSON 结构。 */
+export interface ZentaoProfilesStore {
+    /** 当前使用的 profile key。 */
+    currentProfile?: string;
+    /** 保存的 profile 列表。 */
+    profiles: ZentaoProfile[];
+}
 /** 模块动作类型：基础 CRUD 或自定义动作。 */
 export type ModuleActionType = 'list' | 'get' | 'create' | 'update' | 'delete' | 'action';
 /** 模块动作使用的 HTTP 方法；兼容生成定义中的小写方法。 */

package/dist/utils/index.d.ts

@@ -1,2 +1,6 @@
+/** 判断值是否为普通对象（非数组、非 null）。 */
+export declare function isRecord(value: unknown): value is Record<string, unknown>;
+/** 将用户传入的站点根地址规范化，兼容误传入 `/api.php/v2` 的场景。 */
+export declare function normalizeSiteUrl(baseUrl: string): string;
 export declare function getNestedValue(obj: unknown, path: string): unknown;
 export declare function asArray<T>(value: T | T[]): T[];

package/dist/utils/index.js

@@ -1,3 +1,26 @@
+import { ZentaoError } from '../misc/errors.js';
+/** 判断值是否为普通对象（非数组、非 null）。 */
+export function isRecord(value) {
+    return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+/** 将用户传入的站点根地址规范化，兼容误传入 `/api.php/v2` 的场景。 */
+export function normalizeSiteUrl(baseUrl) {
+    const trimmed = baseUrl.trim().replace(/\/+$/, '');
+    if (!trimmed)
+        throw new ZentaoError('E_INVALID_BASE_URL');
+    const siteUrl = trimmed.replace(/\/api\.php\/v2$/i, '');
+    let parsed;
+    try {
+        parsed = new URL(siteUrl);
+    }
+    catch {
+        throw new ZentaoError('E_INVALID_BASE_URL');
+    }
+    if (!['http:', 'https:'].includes(parsed.protocol) || parsed.search || parsed.hash) {
+        throw new ZentaoError('E_INVALID_BASE_URL');
+    }
+    return parsed.toString().replace(/\/+$/, '');
+}
 export function getNestedValue(obj, path) {
     const keys = path.split('.');
     let current = obj;

package/dist/version.d.ts

@@ -1,2 +1,12 @@
+/**
+ * 构建标识，由构建脚本通过 `__ZENTAO_API_BUILD__` 注入。
+ *
+ * 通常是 commit hash 或 CI 构建号；本地 `tsc` 直接编译时回落为 `'development'`。
+ */
 export declare const BUILD: string;
+/**
+ * SDK 版本号，由构建脚本通过 `__ZENTAO_API_VERSION__` 注入。
+ *
+ * 通常等于 `package.json` 的 `version` 字段；本地 `tsc` 直接编译时回落为 `'0.0.0-dev'`。
+ */
 export declare const VERSION: string;

package/dist/version.js

@@ -1,4 +1,14 @@
-const fallbackBuild = "2026-05-10T12:45:54.888Z";
-const fallbackVersion = "0.2.0-beta.1";
+const fallbackBuild = "2026-05-25T12:42:48.013Z";
+const fallbackVersion = "0.2.0";
+/**
+ * 构建标识，由构建脚本通过 `__ZENTAO_API_BUILD__` 注入。
+ *
+ * 通常是 commit hash 或 CI 构建号；本地 `tsc` 直接编译时回落为 `'development'`。
+ */
 export const BUILD = typeof __ZENTAO_API_BUILD__ === 'string' ? __ZENTAO_API_BUILD__ : fallbackBuild;
+/**
+ * SDK 版本号，由构建脚本通过 `__ZENTAO_API_VERSION__` 注入。
+ *
+ * 通常等于 `package.json` 的 `version` 字段；本地 `tsc` 直接编译时回落为 `'0.0.0-dev'`。
+ */
 export const VERSION = typeof __ZENTAO_API_VERSION__ === 'string' ? __ZENTAO_API_VERSION__ : fallbackVersion;

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "zentao-api",
-  "version": "0.2.0-beta.1",
+  "version": "0.2.0",
   "type": "module",
   "description": "Browser and Node.js SDK for ZenTao API",
   "license": "MIT",
   "author": "Sun Hao <sunhao@chandao.com>",
   "repository": {
     "type": "git",
-    "url": "https://github.com/catouse/zentao-api.git"
+    "url": "https://github.com/easysoft/zentao-api"
   },
   "keywords": [
     "zentao",
@@ -18,12 +18,21 @@
   ],
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
+  "sideEffects": [
+    "./dist/browser-global.js",
+    "./dist/browser/zentao-api.global.js"
+  ],
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
+      "browser": "./dist/browser.js",
       "import": "./dist/index.js"
     },
-    "./browser": "./dist/browser/zentao-api.global.js",
+    "./browser": {
+      "types": "./dist/browser.d.ts",
+      "import": "./dist/browser.js"
+    },
+    "./browser/global": "./dist/browser/zentao-api.global.js",
     "./package.json": "./package.json"
   },
   "files": [
@@ -41,19 +50,25 @@
     "build": "rm -rf dist && tsc -p tsconfig.json && bun run scripts/build-browser.ts",
     "smoke:node": "node scripts/smoke-node.mjs",
     "smoke:package": "bun run scripts/smoke-package.ts",
+    "docs:reference": "typedoc",
+    "docs:zentao-api": "bun run scripts/generate-zentao-api-docs.ts",
+    "docs:generate": "bun run docs:reference && bun run docs:zentao-api",
+    "docs:dev": "bun run docs:generate && vitepress dev docs",
+    "docs:build": "bun run docs:generate && vitepress build docs",
+    "docs:preview": "bun run docs:build && vitepress preview docs",
     "check": "bun run test:coverage && bun run typecheck && bun run typecheck:tests && bun run registry:check && bun run build && bun run smoke:node && bun run smoke:package",
     "prepublishOnly": "bun run check"
   },
-  "dependencies": {
-    "turndown": "^7.2.0"
-  },
   "devDependencies": {
     "@types/bun": "^1.3.13",
     "@types/node": "^24.10.0",
-    "@types/turndown": "^5.0.5",
-    "typescript": "^5.7.0"
+    "typedoc": "^0.28.19",
+    "typedoc-plugin-markdown": "^4.11.0",
+    "typedoc-vitepress-theme": "^1.1.2",
+    "typescript": "^5.7.0",
+    "vitepress": "^1.6.4"
   },
   "engines": {
     "node": ">=18"
   }
-}
+}

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

@@ -1 +0,0 @@
-export * from '../index.js';

package/dist/misc/browser-global.js

@@ -1,8 +0,0 @@
-import * as api from '../index.js';
-// Bun 的 IIFE bundle 不总是自动挂载 globalName；这里显式暴露浏览器全局对象。
-const globalTarget = globalThis;
-globalTarget.ZentaoAPI = api;
-if (globalTarget.window) {
-    globalTarget.window.ZentaoAPI = api;
-}
-export * from '../index.js';