zentao-api 0.2.0-beta.1 → 0.2.0-beta.2

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,122 @@ 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);
+}
+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

@@ -6,6 +6,11 @@ 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.";

package/dist/misc/errors.js

@@ -6,6 +6,11 @@ export const ERRORS = {
     E_TIMEOUT: 'Request timed out.',
     E_INSECURE_BROWSER: 'The insecure option is only supported in Node.js runtimes.',
     E_LOGIN_FAILED: 'ZenTao login failed.',
+    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_UNAVAILABLE: 'ZenTao profile storage is unavailable in this runtime.',
     E_INVALID_MODULE: 'Unknown module: {module}',
     E_INVALID_ACTION: 'Unknown action: {module}-{action}',
     E_INVALID_MODULE_DEFINITION: 'Invalid module definition.',

package/dist/modules/registry.d.ts

@@ -4,9 +4,9 @@ export { BUILTIN_MODULES };
 export declare const MODULES: ModuleDefinition[];
 export interface DefineModulesOptions {
     /** 同名模块是否整体替换；默认合并模块定义和动作。 */
-    relace?: boolean;
+    replace?: boolean;
 }
-/** 定义或扩展模块；同名模块默认合并动作，`relace` 为真时整体替换，未知模块追加。 */
+/** 定义或扩展模块；同名模块默认合并动作，`replace` 为真时整体替换，未知模块追加。 */
 export declare function defineModules(input: ModuleDefinition | ModuleDefinition[], options?: DefineModulesOptions): void;
 /** 为已存在模块定义或覆盖动作；同名动作替换，未知动作追加。 */
 export declare function defineModuleActions(moduleName: string, input: ModuleAction | ModuleAction[]): void;

package/dist/modules/registry.js

@@ -6,12 +6,25 @@ export const MODULES = BUILTIN_MODULES;
 // 运行时注册表使用内置定义的浅克隆，避免用户扩展污染生成文件导出的常量。
 let modules = cloneModules(BUILTIN_MODULES);
 let moduleMap = buildModuleMap(modules);
+function cloneValue(value) {
+    if (Array.isArray(value)) {
+        return value.map(cloneValue);
+    }
+    if (value && typeof value === 'object') {
+        const result = {};
+        for (const [key, nestedValue] of Object.entries(value)) {
+            result[key] = cloneValue(nestedValue);
+        }
+        return result;
+    }
+    return value;
+}
 function cloneActions(source) {
-    return source.map((action) => ({ ...action }));
+    return source.map((action) => cloneValue(action));
 }
 function cloneModules(source) {
     return source.map((module) => ({
-        ...module,
+        ...cloneValue(module),
         actions: cloneActions(module.actions),
     }));
 }
@@ -23,7 +36,7 @@ function mergeActions(base, extension) {
     const next = cloneActions(base);
     for (const action of extension) {
         const index = findActionIndex(next, String(action.name));
-        const clone = { ...action };
+        const clone = cloneValue(action);
         if (index >= 0) {
             next[index] = clone;
         }
@@ -56,15 +69,15 @@ function validateAction(action) {
         throw new ZentaoError('E_INVALID_ACTION_DEFINITION');
     }
 }
-/** 定义或扩展模块；同名模块默认合并动作，`relace` 为真时整体替换，未知模块追加。 */
+/** 定义或扩展模块；同名模块默认合并动作，`replace` 为真时整体替换，未知模块追加。 */
 export function defineModules(input, options = {}) {
     for (const module of asArray(input)) {
         validateModule(module);
         const key = module.name.toLowerCase();
         const index = modules.findIndex((item) => item.name.toLowerCase() === key);
-        const next = { ...module, actions: cloneActions(module.actions) };
+        const next = { ...cloneValue(module), actions: cloneActions(module.actions) };
         if (index >= 0) {
-            modules[index] = options.relace ? next : mergeModule(modules[index], module);
+            modules[index] = options.replace ? next : mergeModule(modules[index], module);
         }
         else {
             modules.push(next);
@@ -81,7 +94,7 @@ export function defineModuleActions(moduleName, input) {
     for (const action of asArray(input)) {
         validateAction(action);
         const index = findActionIndex(module.actions, String(action.name));
-        const next = { ...action };
+        const next = cloneValue(action);
         // 同名动作替换，未知动作追加；不做深度合并，避免 schema/数组字段出现隐式规则。
         if (index >= 0) {
             module.actions[index] = next;
@@ -97,7 +110,7 @@ export function getModule(moduleName) {
     if (!module) {
         throw new ZentaoError('E_INVALID_MODULE', { module: moduleName });
     }
-    return module;
+    return cloneModules([module])[0];
 }
 /** 获取指定模块动作；`ls` 会作为 `list` 的别名处理。 */
 export function getModuleAction(moduleName, actionName) {
@@ -105,12 +118,12 @@ export function getModuleAction(moduleName, actionName) {
     const normalized = actionName === 'ls' ? 'list' : actionName;
     const direct = module.actions.find((action) => String(action.name).toLowerCase() === normalized.toLowerCase());
     if (direct)
-        return direct;
+        return cloneValue(direct);
     const crud = new Set(['list', 'get', 'create', 'update', 'delete']);
     if (!crud.has(normalized)) {
         const custom = module.actions.find((action) => action.type === 'action' && String(action.name).toLowerCase() === normalized.toLowerCase());
         if (custom)
-            return custom;
+            return cloneValue(custom);
     }
     throw new ZentaoError('E_INVALID_ACTION', { module: moduleName, action: actionName });
 }

package/dist/modules/resolve.js

@@ -1,5 +1,5 @@
 import { ZentaoError } from '../misc/errors.js';
-import { getNestedValue } from '../utils/index.js';
+import { getNestedValue, isRecord } from '../utils/index.js';
 import { getModuleAction } from './registry.js';
 const SCOPE_MAP = {
     product: 'products',
@@ -45,9 +45,6 @@ function parseData(value) {
     }
     return value && typeof value === 'object' && !Array.isArray(value) ? value : undefined;
 }
-function isPlainObject(value) {
-    return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
-}
 /** 按 OpenAPI schema 的基础类型对参数做轻量转换。 */
 function coerceValue(value, type) {
     if (value === undefined)
@@ -57,11 +54,24 @@ function coerceValue(value, type) {
         return Number.isNaN(numberValue) ? value : numberValue;
     }
     if (type === 'boolean') {
-        if (value === 'true')
-            return true;
-        if (value === 'false')
-            return false;
-        return Boolean(value);
+        if (typeof value === 'boolean')
+            return value;
+        if (typeof value === 'number') {
+            if (value === 1)
+                return true;
+            if (value === 0)
+                return false;
+            return value;
+        }
+        if (typeof value === 'string') {
+            const normalized = value.trim().toLowerCase();
+            if (['true', '1', 'yes', 'on'].includes(normalized))
+                return true;
+            if (['false', '0', 'no', 'off'].includes(normalized))
+                return false;
+            return value;
+        }
+        return value;
     }
     return value;
 }
@@ -140,7 +150,7 @@ export function resolveModuleCommand(module, actionName, params = {}) {
                 if (typeof value === 'string') {
                     value = value.split(',');
                 }
-                else if (!hasDataValue || !isPlainObject(value)) {
+                else if (!hasDataValue || !isRecord(value)) {
                     value = [value];
                 }
             }

package/dist/profiles/index.d.ts

@@ -0,0 +1,14 @@
+import type { ZentaoProfile, ZentaoProfileRecord } from '../types/index.js';
+export declare const ZENTAO_PROFILES_STORAGE_KEY = "ZENTAO_PROFILES";
+/** 根据 profile 的账号和禅道地址生成稳定 key。 */
+export declare function getProfileKey(profile: Pick<ZentaoProfile, 'account' | 'server'>): string;
+/** 列出所有保存的本地 profile。 */
+export declare function getAllProfiles(): Promise<ZentaoProfileRecord[]>;
+/** 获取指定 profile；不传 key 时返回上次使用的 profile。 */
+export declare function getProfile(profileKey?: string): Promise<ZentaoProfileRecord | undefined>;
+/** 添加或覆盖一个本地 profile，并把它设置为当前使用的 profile。 */
+export declare function addProfile(profile: ZentaoProfile): Promise<ZentaoProfileRecord>;
+/** 删除指定 profile；返回是否实际删除了记录。 */
+export declare function deleteProfile(profileKey: string): Promise<boolean>;
+/** 切换当前使用的 profile，并刷新最后使用时间；不传 key 时使用当前 profile。 */
+export declare function switchProfile(profileKey?: string): Promise<ZentaoProfileRecord>;

package/dist/profiles/index.js

@@ -0,0 +1,205 @@
+import { ZentaoError } from '../misc/errors.js';
+import { isNodeRuntime } from '../misc/environment.js';
+import { normalizeSiteUrl } from '../utils/index.js';
+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();
+}
+async function importNodeModule(specifier) {
+    const dynamicImport = new Function('specifier', 'return import(specifier)');
+    return dynamicImport(specifier);
+}
+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();
+        await fs.mkdir(path.dirname(file), { recursive: true });
+        await fs.writeFile(file, text, 'utf8');
+        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。 */
+export function getProfileKey(profile) {
+    return profileKeyFromParts(profile.account, profile.server);
+}
+/** 列出所有保存的本地 profile。 */
+export async function getAllProfiles() {
+    const store = await readStore();
+    return store.profiles.map(toRecord);
+}
+/** 获取指定 profile；不传 key 时返回上次使用的 profile。 */
+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。 */
+export async function addProfile(profile) {
+    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；返回是否实际删除了记录。 */
+export async function deleteProfile(profileKey) {
+    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，并刷新最后使用时间；不传 key 时使用当前 profile。 */
+export async function switchProfile(profileKey) {
+    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/types/index.d.ts

@@ -22,6 +22,8 @@ export interface GlobalOptions {
     timeout?: number;
     /** 默认 TLS 跳过证书验证选项；仅 Node.js 运行时支持。 */
     insecure?: boolean;
+    /** 是否在登录成功后把账号、Token 和配置持久化为本地 profile。 */
+    persistProfiles?: boolean;
 }
 /** SDK 支持的 HTTP 方法。 */
 export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'DELETE';
@@ -98,6 +100,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 +117,61 @@ 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;
+    /** 是否将对象属性中的 HTML 转换为 Markdown。 */
+    htmlToMarkdown?: 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[];