zentao-api 0.6.0 → 0.6.2

package/dist/modules/registry.d.ts

@@ -3403,6 +3403,9 @@ export declare const MODULES: ({
                     name?: undefined;
                     parent?: undefined;
                     comment?: undefined;
+                    deadline?: undefined;
+                    status?: undefined;
+                    mailto?: undefined;
                     resolution?: undefined;
                     resolvedDate?: undefined;
                     resolvedBuild?: undefined;
@@ -3504,6 +3507,9 @@ export declare const MODULES: ({
                     name?: undefined;
                     parent?: undefined;
                     comment?: undefined;
+                    deadline?: undefined;
+                    status?: undefined;
+                    mailto?: undefined;
                     resolution?: undefined;
                     resolvedDate?: undefined;
                     resolvedBuild?: undefined;
@@ -3555,6 +3561,9 @@ export declare const MODULES: ({
                     story?: undefined;
                     assignedTo?: undefined;
                     comment?: undefined;
+                    deadline?: undefined;
+                    status?: undefined;
+                    mailto?: undefined;
                     resolution?: undefined;
                     resolvedDate?: undefined;
                     resolvedBuild?: undefined;
@@ -3647,6 +3656,9 @@ export declare const MODULES: ({
                     story?: undefined;
                     name?: undefined;
                     parent?: undefined;
+                    deadline?: undefined;
+                    status?: undefined;
+                    mailto?: undefined;
                     resolution?: undefined;
                     resolvedDate?: undefined;
                     resolvedBuild?: undefined;
@@ -3694,6 +3706,81 @@ export declare const MODULES: ({
                     assignedTo?: undefined;
                     name?: undefined;
                     parent?: undefined;
+                    deadline?: undefined;
+                    status?: undefined;
+                    mailto?: undefined;
+                    resolution?: undefined;
+                    resolvedDate?: undefined;
+                    resolvedBuild?: undefined;
+                };
+                required?: undefined;
+            };
+        };
+        pagerGetter?: undefined;
+        resultGetter?: undefined;
+        params?: undefined;
+    } | {
+        name: "confirm";
+        display: string;
+        type: "action";
+        method: "put";
+        path: string;
+        resultType: "text";
+        pathParams: {
+            bugID: string;
+            scope?: undefined;
+            scopeID?: undefined;
+            productID?: undefined;
+            moduleID?: undefined;
+        };
+        requestBody: {
+            required: true;
+            type: "object";
+            schema: {
+                type: string;
+                properties: {
+                    assignedTo: {
+                        type: string;
+                        description: string;
+                    };
+                    type: {
+                        type: string;
+                        description: string;
+                    };
+                    pri: {
+                        type: string;
+                        description: string;
+                        format: string;
+                    };
+                    deadline: {
+                        type: string;
+                        description: string;
+                    };
+                    status: {
+                        type: string;
+                        description: string;
+                    };
+                    mailto: {
+                        type: string;
+                        items: {
+                            type: string;
+                        };
+                        description: string;
+                    };
+                    comment: {
+                        type: string;
+                        description: string;
+                    };
+                    productID?: undefined;
+                    title?: undefined;
+                    openedBuild?: undefined;
+                    project?: undefined;
+                    execution?: undefined;
+                    severity?: undefined;
+                    steps?: undefined;
+                    story?: undefined;
+                    name?: undefined;
+                    parent?: undefined;
                     resolution?: undefined;
                     resolvedDate?: undefined;
                     resolvedBuild?: undefined;
@@ -3756,6 +3843,9 @@ export declare const MODULES: ({
                     story?: undefined;
                     name?: undefined;
                     parent?: undefined;
+                    deadline?: undefined;
+                    status?: undefined;
+                    mailto?: undefined;
                 };
                 required: string[];
             };
@@ -7397,6 +7487,7 @@ export declare const MODULES: ({
         path: string;
         resultType: "list";
         pagerGetter: string;
+        resultGetter: string;
         pathParams: {
             spaceID: string;
             libID: string;
@@ -7405,7 +7496,6 @@ export declare const MODULES: ({
             docID?: undefined;
             moduleID?: undefined;
         };
-        resultGetter: string;
         requestBody?: undefined;
     } | {
         name: "productDocs";
@@ -8452,6 +8542,11 @@ export declare const MODULES: ({
                         type: string;
                         description: string;
                     };
+                    objectID: {
+                        type: string;
+                        description: string;
+                        format: string;
+                    };
                     begin: {
                         type: string;
                         description: string;
@@ -8501,6 +8596,11 @@ export declare const MODULES: ({
                         type: string;
                         description: string;
                     };
+                    objectID: {
+                        type: string;
+                        description: string;
+                        format: string;
+                    };
                     begin: {
                         type: string;
                         description: string;
@@ -9005,6 +9105,7 @@ export declare const MODULES: ({
         path: string;
         resultType: "list";
         pagerGetter: string;
+        resultGetter: string;
         params: ({
             name: string;
             required: false;
@@ -9033,7 +9134,6 @@ export declare const MODULES: ({
             defaultValue?: undefined;
             options?: undefined;
         })[];
-        resultGetter: string;
     } | {
         name: "issues";
         display: string;

package/dist/request/index.d.ts

@@ -1,4 +1,4 @@
-import type { DataRecord, RequestOptions, ResponseData } from '../types/index.js';
+import type { DataRecord, FileCreateParams, FileCreateResult, RequestOptions, ResponseData } from '../types/index.js';
 import type { BuiltinActionMeta, BuiltinModuleName } from '../modules/generated.js';
 type BuiltinActionName<M extends BuiltinModuleName> = Extract<keyof BuiltinActionMeta[M], string>;
 type BuiltinListRequestName = BuiltinModuleName;
@@ -14,11 +14,11 @@ type ActionMetaOf<Name extends BuiltinRequestName> = ModuleNameOf<Name> extends
     resultType: 'object';
 } : never : never;
 /** 根据内置请求名推导出的参数类型。字段细节以运行时 registry 为准，这里保持可扩展。 */
-export type RequestParamsFor<Name extends BuiltinRequestName> = Record<string, unknown>;
+export type RequestParamsFor<Name extends BuiltinRequestName> = Name extends 'file/create' ? FileCreateParams : Record<string, unknown>;
 /** 根据内置请求名推导出的 `ResponseData.data` 类型。 */
 export type RequestResultFor<Name extends BuiltinRequestName> = ActionMetaOf<Name> extends {
     resultType: 'list';
-} ? DataRecord[] : ActionMetaOf<Name> extends {
+} ? DataRecord[] : Name extends 'file/create' ? FileCreateResult : ActionMetaOf<Name> extends {
     resultType: 'object';
 } ? DataRecord : unknown;
 /**

package/dist/request/index.js

@@ -3,6 +3,7 @@ import { getGlobalOptions } from '../misc/global-options.js';
 import { getModule, getModuleAction } from '../modules/registry.js';
 import { extractPager, extractResult, resolveActionRequest } from '../modules/resolve.js';
 import { isRecord, processData } from '../utils/index.js';
+import { prepareActionBody } from './prepare-body.js';
 /** 将 `moduleName`、`moduleName/methodName` 或 `moduleName/<objectID>` 请求名拆成模块名、动作名和对象 ID。 */
 function splitRequestName(name) {
     const parts = name.split('/');
@@ -198,10 +199,14 @@ export async function request(name, params = {}, options = {}) {
         ? await autoFillUpdateParams(module, action, mergedParams, options)
         : mergedParams;
     const command = resolveActionRequest(module, actionName, finalParams);
+    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: command.data,
+        body: preparedBody.body,
+        bodyType: preparedBody.bodyType,
         timeout: options.timeout ?? globals.timeout,
         insecure: options.insecure ?? globals.insecure,
     });

package/dist/request/prepare-body.d.ts

@@ -0,0 +1,12 @@
+import type { ClientRequestBodyType, ModuleActionRequest } from '../types/index.js';
+/** 本地路径上传的默认大小上限（50 MiB）。 */
+export declare const DEFAULT_MAX_UPLOAD_BYTES: number;
+export interface PrepareActionBodyOptions {
+    maxUploadBytes?: number;
+}
+export interface PreparedActionBody {
+    body: unknown;
+    bodyType?: ClientRequestBodyType;
+}
+/** 根据模块动作的媒体类型，把解析后的普通请求体转换为底层客户端可发送的请求体。 */
+export declare function prepareActionBody(command: ModuleActionRequest, options?: PrepareActionBodyOptions): Promise<PreparedActionBody>;

package/dist/request/prepare-body.js

@@ -0,0 +1,221 @@
+import { ZentaoError } from '../misc/errors.js';
+import { isNodeRuntime } from '../misc/environment.js';
+import { isRecord } from '../utils/index.js';
+/** 本地路径上传的默认大小上限（50 MiB）。 */
+export const DEFAULT_MAX_UPLOAD_BYTES = 50 * 1024 * 1024;
+const MIME_TYPES = {
+    '.avif': 'image/avif',
+    '.csv': 'text/csv',
+    '.gif': 'image/gif',
+    '.htm': 'text/html',
+    '.html': 'text/html',
+    '.jpeg': 'image/jpeg',
+    '.jpg': 'image/jpeg',
+    '.json': 'application/json',
+    '.md': 'text/markdown',
+    '.pdf': 'application/pdf',
+    '.png': 'image/png',
+    '.svg': 'image/svg+xml',
+    '.txt': 'text/plain',
+    '.webp': 'image/webp',
+    '.zip': 'application/zip',
+};
+// 与 environment.ts 相同：通过变量形式的动态 import 避免浏览器 bundle 静态拉入 node:*。
+function importNodeModule(specifier) {
+    return import(specifier);
+}
+function isBlob(value) {
+    return typeof Blob !== 'undefined' && value instanceof Blob;
+}
+function isFileUploadPathInput(value) {
+    return isRecord(value) && typeof value.path === 'string';
+}
+function isFileUploadDataInput(value) {
+    return isRecord(value) && Object.prototype.hasOwnProperty.call(value, 'data') && typeof value.filename === 'string';
+}
+function inferContentType(filename) {
+    const normalized = filename.toLowerCase();
+    const dotIndex = normalized.lastIndexOf('.');
+    return dotIndex >= 0 ? MIME_TYPES[normalized.slice(dotIndex)] ?? 'application/octet-stream' : 'application/octet-stream';
+}
+function inferExtension(contentType) {
+    const normalized = contentType.split(';', 1)[0]?.trim().toLowerCase();
+    const entry = Object.entries(MIME_TYPES).find(([, type]) => type === normalized);
+    return entry?.[0] ?? '.bin';
+}
+function resolveMaxUploadBytes(value) {
+    if (value === undefined)
+        return DEFAULT_MAX_UPLOAD_BYTES;
+    if (!Number.isFinite(value) || value < 1) {
+        throw new ZentaoError('E_INVALID_PARAM', { param: 'maxUploadBytes', value: String(value) });
+    }
+    return Math.floor(value);
+}
+function assertUploadSize(size, limit) {
+    if (size > limit) {
+        throw new ZentaoError('E_UPLOAD_FILE_TOO_LARGE', { size, limit });
+    }
+}
+function normalizeFilename(value, fallback, field) {
+    const requested = value?.trim() || fallback.trim();
+    const filename = requested.split(/[\\/]/).at(-1)?.trim() ?? '';
+    if (!filename) {
+        throw new ZentaoError('E_INVALID_UPLOAD_SOURCE', { field });
+    }
+    return filename;
+}
+function errorCode(error) {
+    return isRecord(error) && typeof error.code === 'string' ? error.code : undefined;
+}
+function copyView(view) {
+    const source = new Uint8Array(view.buffer, view.byteOffset, view.byteLength);
+    const copy = new Uint8Array(source.byteLength);
+    copy.set(source);
+    return copy;
+}
+function blobFromData(data, contentType, field) {
+    if (isBlob(data)) {
+        return data.type === contentType ? data : new Blob([data], { type: contentType });
+    }
+    if (data instanceof ArrayBuffer) {
+        return new Blob([data], { type: contentType });
+    }
+    if (ArrayBuffer.isView(data)) {
+        return new Blob([copyView(data)], { type: contentType });
+    }
+    throw new ZentaoError('E_INVALID_UPLOAD_SOURCE', { field });
+}
+async function preparePathFile(source, field, maxUploadBytes) {
+    if (!isNodeRuntime()) {
+        throw new ZentaoError('E_UPLOAD_PATH_UNSUPPORTED');
+    }
+    const path = typeof source === 'string' ? source : source.path;
+    const explicitFilename = typeof source === 'string' ? undefined : source.filename;
+    const explicitContentType = typeof source === 'string' ? undefined : source.contentType;
+    const [fs, pathModule] = await Promise.all([
+        importNodeModule('node:fs/promises'),
+        importNodeModule('node:path'),
+    ]);
+    let stats;
+    try {
+        stats = await fs.stat(path);
+    }
+    catch (error) {
+        if (errorCode(error) === 'ENOENT') {
+            throw new ZentaoError('E_UPLOAD_FILE_NOT_FOUND', { path }, error);
+        }
+        throw new ZentaoError('E_UPLOAD_FILE_READ_FAILED', { path }, error);
+    }
+    if (!stats.isFile()) {
+        throw new ZentaoError('E_INVALID_UPLOAD_SOURCE', { field }, { path });
+    }
+    assertUploadSize(stats.size, maxUploadBytes);
+    const filename = normalizeFilename(explicitFilename, pathModule.basename(path), field);
+    const contentType = explicitContentType?.trim() || inferContentType(filename);
+    const bun = globalThis.Bun;
+    if (bun?.file) {
+        const file = bun.file(path);
+        assertUploadSize(file.size, maxUploadBytes);
+        const shouldApplyContentType = Boolean(explicitContentType?.trim()) || !file.type;
+        return {
+            blob: shouldApplyContentType && file.type !== contentType
+                ? new Blob([file], { type: contentType })
+                : file,
+            filename,
+        };
+    }
+    try {
+        const bytes = await fs.readFile(path);
+        assertUploadSize(bytes.byteLength, maxUploadBytes);
+        return {
+            blob: new Blob([copyView(bytes)], { type: contentType }),
+            filename,
+        };
+    }
+    catch (error) {
+        throw new ZentaoError('E_UPLOAD_FILE_READ_FAILED', { path }, error);
+    }
+}
+async function prepareFile(value, field, maxUploadBytes) {
+    if (typeof value === 'string' || isFileUploadPathInput(value)) {
+        return preparePathFile(value, field, maxUploadBytes);
+    }
+    if (isBlob(value)) {
+        assertUploadSize(value.size, maxUploadBytes);
+        const contentType = value.type || 'application/octet-stream';
+        const name = typeof value.name === 'string'
+            ? value.name
+            : `${field}${inferExtension(contentType)}`;
+        const filename = normalizeFilename(name, `${field}.bin`, field);
+        return {
+            blob: value.type === contentType ? value : new Blob([value], { type: contentType }),
+            filename,
+        };
+    }
+    if (isFileUploadDataInput(value)) {
+        const filename = normalizeFilename(value.filename, field, field);
+        const contentType = value.contentType?.trim()
+            || (isBlob(value.data) ? value.data.type : '')
+            || inferContentType(filename);
+        const blob = blobFromData(value.data, contentType, field);
+        assertUploadSize(blob.size, maxUploadBytes);
+        return { blob, filename };
+    }
+    throw new ZentaoError('E_INVALID_UPLOAD_SOURCE', { field });
+}
+function isBinarySchema(schema) {
+    if (!isRecord(schema))
+        return false;
+    if (schema.format === 'binary')
+        return true;
+    return schema.type === 'array' && isRecord(schema.items) && schema.items.format === 'binary';
+}
+function appendTextValue(form, field, value) {
+    if (value === undefined)
+        return;
+    if (Array.isArray(value)) {
+        for (const item of value)
+            appendTextValue(form, field, item);
+        return;
+    }
+    if (value === null) {
+        form.append(field, '');
+        return;
+    }
+    form.append(field, typeof value === 'object' ? JSON.stringify(value) : String(value));
+}
+async function createMultipartBody(command, maxUploadBytes) {
+    const form = new FormData();
+    const properties = isRecord(command.action.requestBody?.schema.properties)
+        ? command.action.requestBody.schema.properties
+        : {};
+    for (const [field, value] of Object.entries(command.data ?? {})) {
+        if (!isBinarySchema(properties[field])) {
+            appendTextValue(form, field, value);
+            continue;
+        }
+        const values = Array.isArray(value) ? value : [value];
+        if (values.length === 0) {
+            throw new ZentaoError('E_INVALID_UPLOAD_SOURCE', { field });
+        }
+        for (const item of values) {
+            const prepared = await prepareFile(item, field, maxUploadBytes);
+            form.append(field, prepared.blob, prepared.filename);
+        }
+    }
+    return form;
+}
+/** 根据模块动作的媒体类型，把解析后的普通请求体转换为底层客户端可发送的请求体。 */
+export async function prepareActionBody(command, options = {}) {
+    const mediaType = command.action.requestBody?.mediaType ?? 'application/json';
+    if (mediaType === 'multipart/form-data') {
+        return {
+            body: await createMultipartBody(command, resolveMaxUploadBytes(options.maxUploadBytes)),
+            bodyType: 'raw',
+        };
+    }
+    if (mediaType === 'application/x-www-form-urlencoded') {
+        return { body: command.data, bodyType: 'form' };
+    }
+    return { body: command.data };
+}

package/dist/types/index.d.ts

@@ -15,3 +15,4 @@ export * from './options.js';
 export * from './profile.js';
 export * from './data.js';
 export * from './module.js';
+export * from './upload.js';

package/dist/types/index.js

@@ -15,3 +15,4 @@ export * from './options.js';
 export * from './profile.js';
 export * from './data.js';
 export * from './module.js';
+export * from './upload.js';

package/dist/types/module.d.ts

@@ -27,6 +27,8 @@ export interface ModuleActionParam {
     defaultValue?: unknown;
     /** 参数值类型，用于基础类型转换。 */
     type?: 'string' | 'number' | 'boolean';
+    /** OpenAPI schema format，例如 `binary` 或 `int32`。 */
+    format?: string;
     /** 参数可选值。 */
     options?: readonly ModuleActionParamOption[];
 }
@@ -34,12 +36,16 @@ export interface ModuleActionParam {
 export type ModuleActionResultType = 'text' | 'object' | 'list';
 /** 列表分页信息别名。 */
 export type ListPagerInfo = Pager;
+/** 高阶请求支持的请求体媒体类型。 */
+export type ModuleActionRequestMediaType = 'application/json' | 'multipart/form-data' | 'application/x-www-form-urlencoded';
 /** 模块动作请求体定义。 */
 export interface ModuleActionRequestBody {
     /** 请求体类型。 */
     type?: 'object' | 'string';
     /** 请求体是否必填。 */
     required?: boolean;
+    /** 请求体媒体类型；省略时按 `application/json` 处理。 */
+    mediaType?: ModuleActionRequestMediaType;
     /** OpenAPI 风格 schema，用于从 params 组装 body。 */
     schema: Readonly<Record<string, unknown>>;
     /** 请求体示例。 */

package/dist/types/options.d.ts

@@ -33,6 +33,8 @@ export interface RequestOptions extends ProcessListOptions {
     timeout?: number;
     /** 本次调用 TLS 跳过证书验证选项；仅 Node.js 运行时支持。 */
     insecure?: boolean;
+    /** 单个本地文件或 Blob 上传的最大字节数，默认 50 MiB。 */
+    maxUploadBytes?: number;
     /** 单条对象转换函数，在字段摘取前执行；列表转换请使用 `convert`。 */
     convertSingle?: ProcessSingleOptions['convert'];
     /**

package/dist/types/upload.d.ts

@@ -0,0 +1,38 @@
+/** Node.js/Bun 本地文件路径形式的上传输入。 */
+export interface FileUploadPathInput {
+    /** 本地文件路径。 */
+    path: string;
+    /** 上传时使用的文件名；省略时取路径 basename。 */
+    filename?: string;
+    /** 显式 MIME 类型；省略时按文件名推断。 */
+    contentType?: string;
+}
+/** 内存数据形式的上传输入。 */
+export interface FileUploadDataInput {
+    /** 文件内容。 */
+    data: Blob | ArrayBuffer | ArrayBufferView;
+    /** 上传时使用的文件名。 */
+    filename: string;
+    /** 显式 MIME 类型；省略时优先使用 Blob.type，再按文件名推断。 */
+    contentType?: string;
+}
+/**
+ * 高阶 `request()` 可接受的文件输入。
+ *
+ * - Node.js/Bun：可直接传本地路径或 {@link FileUploadPathInput}。
+ * - 浏览器：传 `File`（属于 `Blob`）、`Blob` 或 {@link FileUploadDataInput}；
+ *   无文件名的 `Blob` 会按 MIME 类型生成文件名，需要精确文件名时使用数据对象形式。
+ */
+export type FileUploadSource = string | Blob | FileUploadPathInput | FileUploadDataInput;
+/** `request("file/create")` 的参数。 */
+export type FileCreateParams = Record<string, unknown> & {
+    file: FileUploadSource;
+    objectType: 'bug' | 'story' | 'task' | 'testcase' | (string & {});
+    objectID: number;
+};
+/** `request("file/create")` 归一化后的结果。 */
+export interface FileCreateResult {
+    id: number;
+    url?: string;
+    [key: string]: unknown;
+}

package/dist/types/upload.js

@@ -0,0 +1 @@
+export {};

package/dist/version.js

@@ -1,5 +1,5 @@
-const fallbackBuild = "2026-08-18T03:57:32.732Z";
-const fallbackVersion = "0.6.0";
+const fallbackBuild = "2026-08-18T08:24:17.240Z";
+const fallbackVersion = "0.6.2";
 /**
  * 构建标识，由构建脚本通过 `__ZENTAO_API_BUILD__` 注入。
  *

package/package.json

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