zentao-api 0.5.5 → 0.6.1

package/dist/request/index.d.ts

@@ -1,11 +1,6 @@
-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;
+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;
 type BuiltinNamedRequestName = {
     [M in BuiltinModuleName]: `${M}/${BuiltinActionName<M>}`;
@@ -15,88 +10,15 @@ type BuiltinIdRequestName = `${BuiltinModuleName}/${number}`;
 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 ? {
-    scope?: 'products' | 'projects' | 'executions' | (string & {});
-    scopeID?: string | number;
-    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>;
+type ActionMetaOf<Name extends BuiltinRequestName> = ModuleNameOf<Name> extends infer M extends BuiltinModuleName ? ActionNameOf<Name> extends infer A ? A extends keyof BuiltinActionMeta[M] ? BuiltinActionMeta[M][A] : {
+    resultType: 'object';
+} : never : never;
+/** 根据内置请求名推导出的参数类型。字段细节以运行时 registry 为准，这里保持可扩展。 */
+export type RequestParamsFor<Name extends BuiltinRequestName> = Name extends 'file/create' ? FileCreateParams : Record<string, unknown>;
 /** 根据内置请求名推导出的 `ResponseData.data` 类型。 */
-export type RequestResultFor<Name extends BuiltinRequestName> = ActionOfRequest<Name> extends {
+export type RequestResultFor<Name extends BuiltinRequestName> = ActionMetaOf<Name> extends {
     resultType: 'list';
-} ? DataRecord[] : ActionOfRequest<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-13T07:55:43.014Z";
-const fallbackVersion = "0.5.5";
+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.5.5",
+  "version": "0.6.1",
   "type": "module",
   "description": "Browser and Node.js SDK for ZenTao API",
   "license": "MIT",