zentao-api 0.3.0 → 0.3.1

package/dist/modules/registry.js

@@ -7,7 +7,7 @@ export const MODULES = BUILTIN_MODULES;
 // - 深克隆：避免用户后续修改自己的输入对象时污染注册表；
 // - 深冻结：让 getModule / getModuleAction 可以零拷贝返回引用，
 //   外部尝试改写会在严格模式下抛 TypeError，开销也降到 O(1) 查询。
-let modules = freezeModules(deepClone(BUILTIN_MODULES));
+let modules = freezeModules(cloneBuiltinModules());
 let moduleMap = buildModuleMap(modules);
 function deepClone(value) {
     if (Array.isArray(value)) {
@@ -22,6 +22,9 @@ function deepClone(value) {
     }
     return value;
 }
+function cloneBuiltinModules() {
+    return deepClone(BUILTIN_MODULES);
+}
 function deepFreeze(value) {
     if (value === null || typeof value !== 'object')
         return value;
@@ -216,6 +219,6 @@ export function isModuleName(moduleName) {
 }
 /** @internal */
 export function resetModuleDefinitions() {
-    modules = freezeModules(deepClone(BUILTIN_MODULES));
+    modules = freezeModules(cloneBuiltinModules());
     rebuildMap();
 }

package/dist/request/index.d.ts

@@ -1,16 +1,116 @@
-import type { RequestOptions, ResponseData } from '../types/index.js';
+import type { DataRecord, RequestOptions, ResponseData } from '../types/index.js';
+import type { BUILTIN_MODULES } from '../modules/generated.js';
+type BuiltinModuleDefinition = (typeof BUILTIN_MODULES)[number];
+type BuiltinModuleName = BuiltinModuleDefinition['name'];
+type BuiltinAction<M extends BuiltinModuleName> = Extract<BuiltinModuleDefinition, {
+    name: M;
+}>['actions'][number];
+type BuiltinActionName<M extends BuiltinModuleName> = BuiltinAction<M>['name'] & string;
+type BuiltinListRequestName = BuiltinModuleName;
+type BuiltinNamedRequestName = {
+    [M in BuiltinModuleName]: `${M}/${BuiltinActionName<M>}`;
+}[BuiltinModuleName];
+type BuiltinIdRequestName = `${BuiltinModuleName}/${number}`;
+/** 内置模块支持的请求名：`module`、`module/action` 或 `module/123`。 */
+export type BuiltinRequestName = BuiltinListRequestName | BuiltinNamedRequestName | BuiltinIdRequestName;
+type ModuleNameOf<Name extends BuiltinRequestName> = Name extends `${infer M}/${string}` ? Extract<M, BuiltinModuleName> : Extract<Name, BuiltinModuleName>;
+type ActionNameOf<Name extends BuiltinRequestName> = Name extends `${string}/${infer A}` ? A extends `${number}` ? 'get' : A : 'list';
+type ActionOfRequest<Name extends BuiltinRequestName> = Extract<BuiltinAction<ModuleNameOf<Name>>, {
+    name: ActionNameOf<Name>;
+}>;
+type UnionToIntersection<T> = (T extends unknown ? (value: T) => void : never) extends (value: infer R) => void ? R : never;
+type NumericInput = number | `${number}`;
+type BooleanInput = boolean | 0 | 1 | 'true' | 'false' | '1' | '0' | 'yes' | 'no' | 'on' | 'off';
+type OptionValue<T> = T extends readonly (infer Option)[] ? Option extends {
+    value: infer Value;
+} ? Value : never : never;
+type ParamInput<T> = (T extends {
+    options: infer Options;
+} ? OptionValue<Options> : never) | (T extends {
+    type: 'number' | 'integer';
+} ? NumericInput : T extends {
+    type: 'boolean';
+} ? BooleanInput : string);
+type QueryParams<A> = A extends {
+    params: readonly (infer Param)[];
+} ? UnionToIntersection<Param extends {
+    name: infer Name extends string;
+} ? {
+    [K in Name]?: ParamInput<Param>;
+} : unknown> : {};
+type SchemaProperties<S> = S extends {
+    properties: infer Properties;
+} ? Properties : {};
+type SchemaRequiredKeys<S> = S extends {
+    required: readonly (infer Key)[];
+} ? Extract<Key, keyof SchemaProperties<S> & string> : never;
+type SchemaValue<S> = S extends {
+    type: 'integer' | 'number';
+} ? NumericInput : S extends {
+    type: 'boolean';
+} ? BooleanInput : S extends {
+    type: 'array';
+    items?: infer Items;
+} ? Array<SchemaValue<Items>> | readonly SchemaValue<Items>[] | string | Record<string, unknown> : S extends {
+    type: 'object';
+} ? Record<string, unknown> : string;
+type BodyParams<A> = A extends {
+    requestBody: {
+        schema: infer Schema;
+    };
+} ? {
+    [K in SchemaRequiredKeys<Schema>]: SchemaValue<SchemaProperties<Schema>[K]>;
+} & {
+    [K in Exclude<keyof SchemaProperties<Schema> & string, SchemaRequiredKeys<Schema>>]?: SchemaValue<SchemaProperties<Schema>[K]>;
+} & {
+    data?: string | Partial<{
+        [K in keyof SchemaProperties<Schema> & string]: SchemaValue<SchemaProperties<Schema>[K]>;
+    }>;
+} : {
+    data?: string | Record<string, unknown>;
+};
+type ScopedParams<PathParams> = 'scope' extends keyof PathParams ? {
+    product?: string | number;
+    productID?: string | number;
+    project?: string | number;
+    projectID?: string | number;
+    execution?: string | number;
+    executionID?: string | number;
+} : {};
+type PathParams<A> = A extends {
+    pathParams: infer Params;
+} ? {
+    [K in Exclude<keyof Params & string, 'scope' | 'scopeID'>]?: string | number;
+} & ScopedParams<Params> & {
+    id?: string | number;
+} : {
+    id?: string | number;
+};
+/** 根据内置请求名推导出的参数类型。 */
+export type RequestParamsFor<Name extends BuiltinRequestName> = PathParams<ActionOfRequest<Name>> & QueryParams<ActionOfRequest<Name>> & BodyParams<ActionOfRequest<Name>> & {
+    page?: string | number;
+    recPerPage?: string | number;
+} & Record<string, unknown>;
+/** 根据内置请求名推导出的 `ResponseData.data` 类型。 */
+export type RequestResultFor<Name extends BuiltinRequestName> = ActionOfRequest<Name> extends {
+    resultType: 'list';
+} ? DataRecord[] : ActionOfRequest<Name> extends {
+    resultType: 'object';
+} ? DataRecord : unknown;
 /**
- * 按模块动作名请求禅道 API。
+ * 按模块名或模块动作名请求禅道 API。
  *
  * 选项优先级为：本次调用 options > 全局 options > 客户端默认值。
  * 当响应 `status` 为 `"fail"` 时，默认按原样返回；若 `options.throwOnFail`
  * 或全局 `throwOnFail` 为真，则改为抛出 `E_API_FAILED`。
  *
  * @typeParam T 期望的 `data` 字段类型；不传时为 `unknown`，调用方需要自行收窄。
- * @param name - 模块动作名，例如 `product/list`。
+ * @param name - 请求名，例如 `product`、`product/list` 或 `product/1`。
  * @param params - 请求参数。
  * @param options - 请求选项。
  * @returns 归一化后的禅道 API 响应。
  * @throws {ZentaoError} 传输层错误、参数缺失或 `throwOnFail` 启用时的业务失败。
  */
-export declare function request<T = unknown>(name: `${string}/${string}`, params?: Record<string, unknown>, options?: RequestOptions): Promise<ResponseData<T>>;
+export declare function request<Name extends BuiltinRequestName>(name: Name, params?: RequestParamsFor<Name>, options?: RequestOptions): Promise<ResponseData<RequestResultFor<Name>>>;
+export declare function request<T = unknown>(name: string, params?: Record<string, unknown>, options?: RequestOptions): Promise<ResponseData<T>>;
+export {};

package/dist/request/index.js

@@ -3,17 +3,21 @@ import { getGlobalOptions } from '../misc/global-options.js';
 import { getModule } from '../modules/registry.js';
 import { extractPager, extractResult, resolveModuleCommand } from '../modules/resolve.js';
 import { isRecord, processData } from '../utils/index.js';
-/** 将 `moduleName/methodName` 形式的请求名拆成模块名和动作名。 */
+/** 将 `moduleName`、`moduleName/methodName` 或 `moduleName/<objectID>` 请求名拆成模块名、动作名和对象 ID。 */
 function splitRequestName(name) {
-    const [moduleName, actionName] = name.split('/');
-    // 如果没有指定 actionName
+    const parts = name.split('/');
+    if (parts.length > 2 || !parts[0]) {
+        throw new ZentaoError('E_INVALID_REQUEST_NAME');
+    }
+    const [moduleName, actionName] = parts;
+    // 如果没有指定 actionName，按列表动作处理。
     if (!actionName?.length) {
         return {
             moduleName,
             actionName: 'list',
         };
     }
-    // 如果 actionName 为数值
+    // 如果 actionName 为数值，按详情快捷写法处理。
     if (Number.isInteger(Number(actionName))) {
         return {
             moduleName,
@@ -26,6 +30,26 @@ function splitRequestName(name) {
         actionName,
     };
 }
+function stringifyMessage(value) {
+    if (typeof value === 'string')
+        return value;
+    if (value === undefined)
+        return undefined;
+    try {
+        return JSON.stringify(value);
+    }
+    catch {
+        return String(value);
+    }
+}
+function extractApiCode(record) {
+    for (const key of ['code', 'errorCode', 'errno']) {
+        const value = record[key];
+        if (typeof value === 'string' || typeof value === 'number')
+            return value;
+    }
+    return undefined;
+}
 /** 判断本次调用是否携带了需要本地处理列表的选项。 */
 function hasListProcessing(options) {
     return Boolean((options.filter && options.filter.length > 0) ||
@@ -73,10 +97,11 @@ function normalizeResponse(command, raw, options) {
     const record = raw;
     const status = record.status === 'fail' ? 'fail' : 'success';
     const data = applyProcessing(extractResult(command.action, record), options);
+    const rawMessage = record.message;
     const pager = extractPager(command.action, record);
-    return {
+    const response = {
         status,
-        message: typeof record.message === 'string' ? record.message : undefined,
+        message: stringifyMessage(rawMessage),
         data: data,
         pager: pager ? {
             total: Number(pager.recTotal),
@@ -84,21 +109,16 @@ function normalizeResponse(command, raw, options) {
             recPerPage: Number(pager.recPerPage),
         } : undefined,
     };
+    if (rawMessage !== undefined && typeof rawMessage !== 'string') {
+        response.rawMessage = rawMessage;
+    }
+    const apiCode = extractApiCode(record);
+    if (apiCode !== undefined)
+        response.apiCode = apiCode;
+    if (status === 'fail')
+        response.raw = record;
+    return response;
 }
-/**
- * 按模块动作名请求禅道 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();
     const client = options.client ?? globals.client;
@@ -110,8 +130,8 @@ export async function request(name, params = {}, options = {}) {
     // recPerPage 是最常用的列表参数，允许在全局或本次调用中统一覆盖。
     const recPerPage = params.recPerPage ?? options.recPerPage ?? globals.recPerPage;
     const mergedParams = {
-        ...(id !== undefined ? { id } : {}),
         ...params,
+        ...(id !== undefined ? { id } : {}),
         ...(recPerPage !== undefined ? { recPerPage } : {}),
     };
     const command = resolveModuleCommand(module, actionName, mergedParams);

package/dist/types/index.d.ts

@@ -29,20 +29,32 @@ export interface GlobalOptions {
 }
 /** SDK 支持的 HTTP 方法。 */
 export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'DELETE';
+/** 请求体序列化方式。 */
+export type ClientRequestBodyType = 'json' | 'form' | 'raw';
+/** 响应体解析方式。 */
+export type ClientResponseType = 'auto' | 'json' | 'text' | 'arrayBuffer' | 'blob' | 'response';
 /** `ZentaoClient.request()` 的单次请求选项。 */
 export interface ClientRequestOptions {
     /** HTTP 方法，默认 `GET`。 */
     method?: HttpMethod;
-    /** JSON 请求体；`GET` 请求会忽略该字段。 */
+    /** 请求体；`GET` 请求会忽略该字段。普通对象默认按 JSON 发送，`FormData` / `Blob` / `ArrayBuffer` 等会原样发送。 */
     body?: unknown;
+    /** 请求体序列化方式。默认 `json`；传入 `FormData` 等原生 body 时会自动按 `raw` 处理。 */
+    bodyType?: ClientRequestBodyType;
+    /** 响应体解析方式。默认 `auto`，会优先尝试 JSON，失败后回落为文本。 */
+    responseType?: ClientResponseType;
+    /** 额外请求头；会与 SDK 自动注入的 `Token` / `Content-Type` 合并。 */
+    headers?: HeadersInit;
     /** URL 查询参数；`undefined` 值会被跳过。 */
     query?: Record<string, string | number | boolean | undefined>;
+    /** 外部取消信号；会与 SDK 自身的超时控制合并。 */
+    signal?: AbortSignal;
     /** 单次请求超时时间，优先级高于全局和客户端默认值。 */
     timeout?: number;
     /** 单次请求 TLS 跳过证书验证选项；仅 Node.js 运行时支持。 */
     insecure?: boolean;
 }
-/** 高阶 `request("moduleName/methodName")` 的单次调用选项。 */
+/** 高阶 `request("moduleName")` / `request("moduleName/methodName")` / `request("moduleName/<objectID>")` 的单次调用选项。 */
 export interface RequestOptions extends ProcessListOptions {
     /** 本次调用使用的客户端；优先级高于全局客户端。 */
     client?: ZentaoClient;
@@ -64,6 +76,12 @@ export interface ResponseData<T = unknown> {
     status: 'success' | 'fail';
     /** 禅道服务端返回的消息。 */
     message?: string;
+    /** 原始消息字段；当服务端返回对象/数组等非字符串消息时保留在这里。 */
+    rawMessage?: unknown;
+    /** 服务端返回的业务错误码或状态码字段。 */
+    apiCode?: string | number;
+    /** 失败响应的原始对象，便于上层展示服务端返回的完整上下文。 */
+    raw?: Record<string, unknown>;
     /** 根据模块动作 `resultGetter` 提取后的业务数据。 */
     data?: T;
     /** 统一分页信息。 */
@@ -183,8 +201,8 @@ export type ModuleActionMethod = HttpMethod | Lowercase<HttpMethod>;
 export type ModuleActionName = ModuleActionType | (string & {});
 /** 模块动作参数可选项。 */
 export type ModuleActionParamOption = {
-    value: unknown;
-    label: string;
+    readonly value: unknown;
+    readonly label: string;
 };
 /** 模块动作的查询参数定义。 */
 export interface ModuleActionParam {
@@ -199,7 +217,7 @@ export interface ModuleActionParam {
     /** 参数值类型，用于基础类型转换。 */
     type?: 'string' | 'number' | 'boolean';
     /** 参数可选值。 */
-    options?: ModuleActionParamOption[];
+    options?: readonly ModuleActionParamOption[];
 }
 /** 模块动作结果形态。 */
 export type ModuleActionResultType = 'text' | 'object' | 'list';
@@ -212,7 +230,7 @@ export interface ModuleActionRequestBody {
     /** 请求体是否必填。 */
     required?: boolean;
     /** OpenAPI 风格 schema，用于从 params 组装 body。 */
-    schema: Record<string, unknown>;
+    schema: Readonly<Record<string, unknown>>;
     /** 请求体示例。 */
     example?: unknown;
 }
@@ -221,7 +239,7 @@ export interface ModuleActionResponse {
     /** 响应说明。 */
     description?: string;
     /** 响应 schema。 */
-    schema: Record<string, unknown>;
+    schema: Readonly<Record<string, unknown>>;
     /** 响应示例。 */
     example?: unknown;
 }
@@ -253,9 +271,9 @@ export interface ModuleAction {
     /** API 路径模板，可包含 `{productID}` 等路径参数。 */
     path: string;
     /** 路径参数定义；字符串为说明，对象可携带默认值和可选项。 */
-    pathParams?: Record<string, string | Omit<ModuleActionParam, 'name'>>;
+    pathParams?: Readonly<Record<string, string | Omit<ModuleActionParam, 'name'>>>;
     /** 查询参数定义。 */
-    params?: ModuleActionParam[];
+    params?: readonly ModuleActionParam[];
     /** 请求体定义。 */
     requestBody?: ModuleActionRequestBody;
     /** 结果形态。 */
@@ -278,7 +296,7 @@ export interface ModuleDefinition {
     /** 模块说明。 */
     description?: string;
     /** 模块支持的动作集合。 */
-    actions: ModuleAction[];
+    actions: readonly ModuleAction[];
 }
 /** 本地数据处理的基础记录类型，对应一条对象数据。 */
 export type DataRecord = Record<string, unknown>;

package/dist/version.js

@@ -1,5 +1,5 @@
-const fallbackBuild = "2026-06-27T10:57:52.736Z";
-const fallbackVersion = "0.3.0";
+const fallbackBuild = "2026-06-27T12:02:58.054Z";
+const fallbackVersion = "0.3.1";
 /**
  * 构建标识，由构建脚本通过 `__ZENTAO_API_BUILD__` 注入。
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zentao-api",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "type": "module",
   "description": "Browser and Node.js SDK for ZenTao API",
   "license": "MIT",
@@ -49,6 +49,7 @@
     "registry:check": "bun run scripts/update-registry.ts --check",
     "build": "rm -rf dist && tsc -p tsconfig.json && bun run scripts/build-browser.ts",
     "smoke:node": "node scripts/smoke-node.mjs",
+    "smoke:browser": "bun run scripts/smoke-browser-bundler.ts",
     "smoke:package": "bun run scripts/smoke-package.ts",
     "docs:reference": "typedoc",
     "docs:zentao-api": "bun run scripts/generate-zentao-api-docs.ts",
@@ -56,7 +57,7 @@
     "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",
+    "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:browser && bun run smoke:package",
     "prepublishOnly": "bun run check"
   },
   "devDependencies": {