zentao-api 0.6.0 → 0.6.1

package/dist/index.d.ts

@@ -6,4 +6,4 @@ export { defineModuleActions, defineModules, type DefineModulesOptions, type Exp
 export { request, type BuiltinRequestName, type RequestParamsFor, type RequestResultFor, } from './request/index.js';
 export { pickFields, pickFieldsSingle, filterData, searchData, sortData, processData, } from './utils/index.js';
 export { BUILD, VERSION } from './version.js';
-export type { ApiListResponse, ApiResponse, ClientRequestBodyType, ClientRequestOptions, ClientResponseType, DataRecord, DataRecordFilter, DataRecordFilterGroup, GlobalOptions, HttpMethod, ListPagerInfo, LoginResponse, ModuleAction, ModuleActionMethod, ModuleActionName, ModuleActionPagerGetterMap, ModuleActionParam, ModuleActionParamOption, ModuleActionRequest, ModuleActionRequestBody, ModuleActionResponse, ModuleActionResultType, ModuleActionType, ModuleDefinition, ModuleName, Pager, ProcessListOptions, ProcessSingleOptions, RequestOptions, ResponseData, ServerConfig, SortExpr, SortFn, ZentaoProfile, ZentaoProfileConfig, ZentaoProfileRecord, ZentaoProfilesStore, ZentaoClientOptions, } from './types/index.js';
+export type { ApiListResponse, ApiResponse, ClientRequestBodyType, ClientRequestOptions, ClientResponseType, DataRecord, DataRecordFilter, DataRecordFilterGroup, FileCreateParams, FileCreateResult, FileUploadDataInput, FileUploadPathInput, FileUploadSource, GlobalOptions, HttpMethod, ListPagerInfo, LoginResponse, ModuleAction, ModuleActionMethod, ModuleActionName, ModuleActionPagerGetterMap, ModuleActionParam, ModuleActionParamOption, ModuleActionRequest, ModuleActionRequestBody, ModuleActionRequestMediaType, ModuleActionResponse, ModuleActionResultType, ModuleActionType, ModuleDefinition, ModuleName, Pager, ProcessListOptions, ProcessSingleOptions, RequestOptions, ResponseData, ServerConfig, SortExpr, SortFn, ZentaoProfile, ZentaoProfileConfig, ZentaoProfileRecord, ZentaoProfilesStore, ZentaoClientOptions, } from './types/index.js';

package/dist/misc/errors.d.ts

@@ -27,6 +27,11 @@ export declare const ERRORS: {
     readonly E_INVALID_PARAM: "Invalid value for parameter {param}: {value}";
     readonly E_INVALID_REQUEST_NAME: "Request name must use the form \"moduleName\", \"moduleName/methodName\", or \"moduleName/<objectID>\".";
     readonly E_API_FAILED: "ZenTao API returned failure: {message}";
+    readonly E_UPLOAD_PATH_UNSUPPORTED: "Local file paths are not supported in browser runtimes. Pass a File or Blob instead.";
+    readonly E_UPLOAD_FILE_NOT_FOUND: "Upload file not found: {path}";
+    readonly E_UPLOAD_FILE_READ_FAILED: "Failed to read upload file: {path}";
+    readonly E_UPLOAD_FILE_TOO_LARGE: "Upload file is {size} bytes and exceeds the {limit} byte limit.";
+    readonly E_INVALID_UPLOAD_SOURCE: "Invalid upload source for field: {field}";
 };
 /** SDK 已知错误码，对应 {@link ERRORS} 的 key。 */
 export type ErrorCode = keyof typeof ERRORS;

package/dist/misc/errors.js

@@ -27,6 +27,11 @@ export const ERRORS = {
     E_INVALID_PARAM: 'Invalid value for parameter {param}: {value}',
     E_INVALID_REQUEST_NAME: 'Request name must use the form "moduleName", "moduleName/methodName", or "moduleName/<objectID>".',
     E_API_FAILED: 'ZenTao API returned failure: {message}',
+    E_UPLOAD_PATH_UNSUPPORTED: 'Local file paths are not supported in browser runtimes. Pass a File or Blob instead.',
+    E_UPLOAD_FILE_NOT_FOUND: 'Upload file not found: {path}',
+    E_UPLOAD_FILE_READ_FAILED: 'Failed to read upload file: {path}',
+    E_UPLOAD_FILE_TOO_LARGE: 'Upload file is {size} bytes and exceeds the {limit} byte limit.',
+    E_INVALID_UPLOAD_SOURCE: 'Invalid upload source for field: {field}',
 };
 /**
  * SDK 统一错误类型。

package/dist/modules/export.d.ts

@@ -1,7 +1,9 @@
-import type { ModuleAction, ModuleActionParam, ModuleDefinition } from '../types/index.js';
+import type { ModuleAction, ModuleActionParam, ModuleActionRequestMediaType, ModuleDefinition } from '../types/index.js';
 /** 导出的模块动作定义。 */
 export type ExportedModuleAction = Omit<ModuleAction, 'requestBody'> & {
     bodyParams: ModuleActionParam[];
+    /** 请求体媒体类型；省略时为 `application/json`。 */
+    bodyMediaType?: ModuleActionRequestMediaType;
 };
 /** 导出的模块定义。 */
 export type ExportedModuleDefinition = Omit<ModuleDefinition, 'actions'> & {

package/dist/modules/export.js

@@ -30,6 +30,7 @@ export function exportRegistry(options = {}) {
                     const { requestBody, ...exportedAction } = action;
                     return {
                         ...exportedAction,
+                        ...(requestBody?.mediaType ? { bodyMediaType: requestBody.mediaType } : {}),
                         bodyParams: requestBody
                             ? getModuleActionParams(module.name, action.name, { roles: ['body'] })
                             : [],

package/dist/modules/generated.d.ts

@@ -7103,11 +7103,13 @@ export declare const BUILTIN_MODULES: ({
         requestBody: {
             required: true;
             type: "object";
+            mediaType: "multipart/form-data";
             schema: {
                 type: string;
                 properties: {
                     file: {
                         type: string;
+                        format: string;
                         description: string;
                     };
                     objectType: {
@@ -7151,6 +7153,7 @@ export declare const BUILTIN_MODULES: ({
                 };
                 required: string[];
             };
+            mediaType?: undefined;
         };
     } | {
         name: "delete";

package/dist/modules/generated.js

@@ -6306,12 +6306,14 @@ export const BUILTIN_MODULES = [
                 requestBody: {
                     required: true,
                     type: 'object',
+                    mediaType: 'multipart/form-data',
                     schema: {
                         "type": "object",
                         "properties": {
                             "file": {
                                 "type": "string",
-                                "description": "本地文件路径，将按 multipart/form-data 上传"
+                                "format": "binary",
+                                "description": "待上传文件；Node.js/Bun 可传本地文件路径，浏览器传 File 或 Blob"
                             },
                             "objectType": {
                                 "type": "string",

package/dist/modules/registry.d.ts

@@ -7100,11 +7100,13 @@ export declare const MODULES: ({
         requestBody: {
             required: true;
             type: "object";
+            mediaType: "multipart/form-data";
             schema: {
                 type: string;
                 properties: {
                     file: {
                         type: string;
+                        format: string;
                         description: string;
                     };
                     objectType: {
@@ -7148,6 +7150,7 @@ export declare const MODULES: ({
                 };
                 required: string[];
             };
+            mediaType?: undefined;
         };
     } | {
         name: "delete";

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-18T05:15:46.553Z";
+const fallbackVersion = "0.6.1";
 /**
  * 构建标识，由构建脚本通过 `__ZENTAO_API_BUILD__` 注入。
  *

package/package.json

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