zentao-api 0.3.0 → 0.3.1

package/dist/client/index.js

@@ -15,8 +15,92 @@ function buildUrl(baseUrl, path, query) {
     }
     return url.toString();
 }
-/** 优先解析 JSON；非 JSON 响应保留为原始文本。 */
-async function parseResponse(response) {
+function isPlainObject(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
+function isInstanceOfGlobal(value, name) {
+    const ctor = globalThis[name];
+    return typeof ctor === 'function' && value instanceof ctor;
+}
+function isArrayBufferBody(value) {
+    return value instanceof ArrayBuffer || ArrayBuffer.isView(value);
+}
+function appendFormValue(form, key, value) {
+    if (value === undefined)
+        return;
+    if (Array.isArray(value)) {
+        for (const item of value)
+            appendFormValue(form, key, item);
+        return;
+    }
+    form.append(key, value === null ? '' : String(value));
+}
+function serializeBody(body, bodyType, headers) {
+    if (body === undefined || body === null)
+        return undefined;
+    if (bodyType === 'form') {
+        const form = body instanceof URLSearchParams ? body : new URLSearchParams();
+        if (!(body instanceof URLSearchParams) && isPlainObject(body)) {
+            for (const [key, value] of Object.entries(body))
+                appendFormValue(form, key, value);
+        }
+        else if (!(body instanceof URLSearchParams)) {
+            throw new ZentaoError('E_INVALID_PARAM', { param: 'body', value: String(body) });
+        }
+        if (!headers.has('Content-Type')) {
+            headers.set('Content-Type', 'application/x-www-form-urlencoded;charset=UTF-8');
+        }
+        return form;
+    }
+    if (bodyType === 'raw' ||
+        typeof body === 'string' ||
+        isArrayBufferBody(body) ||
+        isInstanceOfGlobal(body, 'FormData') ||
+        isInstanceOfGlobal(body, 'URLSearchParams') ||
+        isInstanceOfGlobal(body, 'Blob') ||
+        isInstanceOfGlobal(body, 'ReadableStream')) {
+        return body;
+    }
+    if (!headers.has('Content-Type')) {
+        headers.set('Content-Type', 'application/json');
+    }
+    return JSON.stringify(body);
+}
+function createRequestSignal(timeout, externalSignal) {
+    const controller = new AbortController();
+    const abortFromExternal = () => controller.abort(externalSignal?.reason);
+    const timer = setTimeout(() => controller.abort(), timeout);
+    if (externalSignal?.aborted) {
+        abortFromExternal();
+    }
+    else {
+        externalSignal?.addEventListener('abort', abortFromExternal, { once: true });
+    }
+    return {
+        signal: controller.signal,
+        cleanup: () => {
+            clearTimeout(timer);
+            externalSignal?.removeEventListener('abort', abortFromExternal);
+        },
+    };
+}
+/** 按指定策略解析响应；默认优先 JSON，失败后保留原始文本。 */
+async function parseResponse(response, responseType = 'auto') {
+    if (responseType === 'response')
+        return response;
+    if (responseType === 'arrayBuffer')
+        return response.arrayBuffer();
+    if (responseType === 'blob')
+        return response.blob();
+    if (responseType === 'text')
+        return response.text();
+    if (responseType === 'json') {
+        const text = await response.text();
+        return text === '' ? undefined : JSON.parse(text);
+    }
     const text = await response.text();
     if (text === '')
         return undefined;
@@ -56,23 +140,6 @@ export class ZentaoClient {
         this.timeout = options.timeout;
         this.insecure = options.insecure;
     }
-    /**
-     * 发起一次原始 API 请求。
-     *
-     * 选项优先级：本次调用 `options` > 全局选项（{@link getGlobalOptions}） > 客户端构造时默认值。
-     *
-     * 特殊处理：
-     * - 默认 HTTP 方法为 `GET`，`GET` 请求即使提供了 `options.body` 也不会发送，避免被部分代理/浏览器拒绝。
-     * - 非空响应优先按 JSON 解析；解析失败时回落为字符串原文。
-     * - 业务层失败（即响应体 `{ status: "fail" }`）不会抛出，仍按原样返回；只有 HTTP/网络/超时等传输层错误才会抛错。
-     * - `insecure` 仅在 Node.js 下可用，浏览器中传入会抛 `E_INSECURE_BROWSER`。
-     *
-     * @param path - 相对 {@link baseUrl} 的路径，可省略前导 `/`。
-     * @param options - 单次请求选项，参见 {@link ClientRequestOptions}。
-     * @returns 解析后的响应体；当响应为空字符串时返回 `undefined`。
-     * @throws {ZentaoError} 可能抛出 `E_HTTP_ERROR`（非 2xx 状态）、`E_NETWORK_ERROR`（底层 fetch 失败）、
-     *   `E_TIMEOUT`（超过 `timeout`）或 `E_INSECURE_BROWSER`（浏览器中开启了 `insecure`）。
-     */
     async request(path, options = {}) {
         const globals = getGlobalOptions();
         const method = options.method ?? 'GET';
@@ -80,21 +147,19 @@ export class ZentaoClient {
         const insecure = options.insecure ?? globals.insecure ?? this.insecure;
         assertInsecureSupported(insecure);
         const url = buildUrl(this.baseUrl, path, options.query);
-        const controller = new AbortController();
-        const timer = setTimeout(() => controller.abort(), timeout);
-        const headers = {};
+        const headers = new Headers(options.headers);
         if (this.token) {
-            headers.Token = this.token;
+            headers.set('Token', this.token);
         }
+        const { signal, cleanup } = createRequestSignal(timeout, options.signal);
         const init = {
             method,
             headers,
-            signal: controller.signal,
+            signal,
         };
         // GET 请求不携带 body，避免浏览器和部分代理拒绝请求。
         if (options.body !== undefined && method !== 'GET') {
-            headers['Content-Type'] = 'application/json';
-            init.body = JSON.stringify(options.body);
+            init.body = serializeBody(options.body, options.bodyType, headers);
         }
         try {
             const response = await fetchWithInsecureTls(insecure, url, init);
@@ -109,7 +174,7 @@ export class ZentaoClient {
                     body: await response.text().catch(() => undefined),
                 });
             }
-            return parseResponse(response);
+            return parseResponse(response, options.responseType);
         }
         catch (error) {
             if (error instanceof ZentaoError)
@@ -120,7 +185,7 @@ export class ZentaoClient {
             throw new ZentaoError('E_NETWORK_ERROR', { message: error.message ?? String(error) }, error);
         }
         finally {
-            clearTimeout(timer);
+            cleanup();
         }
     }
     /**
@@ -131,8 +196,8 @@ export class ZentaoClient {
      * @returns 解析后的响应体（强转为 `T`）。
      * @throws {ZentaoError} 传输层失败时抛出，详见 {@link ZentaoClient.request}。
      */
-    async get(path) {
-        return this.request(path, { method: 'GET' });
+    async get(path, options = {}) {
+        return this.request(path, { ...options, method: 'GET' });
     }
     /**
      * 发起 `POST` 请求，`body` 会被序列化为 JSON。
@@ -143,8 +208,8 @@ export class ZentaoClient {
      * @returns 解析后的响应体（强转为 `T`）。
      * @throws {ZentaoError} 传输层失败时抛出，详见 {@link ZentaoClient.request}。
      */
-    async post(path, body) {
-        return this.request(path, { method: 'POST', body });
+    async post(path, body, options = {}) {
+        return this.request(path, { ...options, method: 'POST', body });
     }
     /**
      * 发起 `PUT` 请求，`body` 会被序列化为 JSON。
@@ -155,8 +220,8 @@ export class ZentaoClient {
      * @returns 解析后的响应体（强转为 `T`）。
      * @throws {ZentaoError} 传输层失败时抛出，详见 {@link ZentaoClient.request}。
      */
-    async put(path, body) {
-        return this.request(path, { method: 'PUT', body });
+    async put(path, body, options = {}) {
+        return this.request(path, { ...options, method: 'PUT', body });
     }
     /**
      * 发起 `DELETE` 请求。
@@ -166,8 +231,8 @@ export class ZentaoClient {
      * @returns 解析后的响应体（强转为 `T`）。
      * @throws {ZentaoError} 传输层失败时抛出，详见 {@link ZentaoClient.request}。
      */
-    async delete(path) {
-        return this.request(path, { method: 'DELETE' });
+    async delete(path, options = {}) {
+        return this.request(path, { ...options, method: 'DELETE' });
     }
     /**
      * 使用账号密码登录禅道。

package/dist/index.d.ts

@@ -3,7 +3,7 @@ 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, getModuleNames, getModule, getModuleAction, } from './modules/registry.js';
-export { request } from './request/index.js';
+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, ClientRequestOptions, DataRecord, DataRecordFilter, DataRecordFilterGroup, GlobalOptions, HttpMethod, ListPagerInfo, LoginResponse, ModuleAction, ModuleActionMethod, ModuleActionName, ModuleActionPagerGetterMap, ModuleActionParam, ModuleActionParamOption, ModuleActionRequestBody, ModuleActionResponse, ModuleActionResultRender, ModuleActionResultRenderType, ModuleActionResultType, ModuleActionType, ModuleDefinition, ModuleName, Pager, ProcessListOptions, ProcessSingleOptions, RequestOptions, ResolvedModuleCommand, ResponseData, ServerConfig, SortExpr, SortFn, ZentaoProfile, ZentaoProfileConfig, ZentaoProfileRecord, ZentaoProfilesStore, ZentaoClientOptions, } from './types/index.js';
+export type { ApiListResponse, ApiResponse, ClientRequestBodyType, ClientRequestOptions, ClientResponseType, DataRecord, DataRecordFilter, DataRecordFilterGroup, GlobalOptions, HttpMethod, ListPagerInfo, LoginResponse, ModuleAction, ModuleActionMethod, ModuleActionName, ModuleActionPagerGetterMap, ModuleActionParam, ModuleActionParamOption, ModuleActionRequestBody, ModuleActionResponse, ModuleActionResultRender, ModuleActionResultRenderType, ModuleActionResultType, ModuleActionType, ModuleDefinition, ModuleName, Pager, ProcessListOptions, ProcessSingleOptions, RequestOptions, ResolvedModuleCommand, ResponseData, ServerConfig, SortExpr, SortFn, ZentaoProfile, ZentaoProfileConfig, ZentaoProfileRecord, ZentaoProfilesStore, ZentaoClientOptions, } from './types/index.js';

package/dist/index.js

@@ -3,6 +3,6 @@ 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, getModuleNames, getModule, getModuleAction, } from './modules/registry.js';
-export { request } from './request/index.js';
+export { request, } from './request/index.js';
 export { pickFields, pickFieldsSingle, filterData, searchData, sortData, processData, } from './utils/index.js';
 export { BUILD, VERSION } from './version.js';

package/dist/misc/environment.js

@@ -25,7 +25,11 @@ function toResponseHeaders(headers) {
     }
     return result;
 }
-async function toNodeBody(body) {
+function hasHeader(headers, name) {
+    const normalized = name.toLowerCase();
+    return Object.keys(headers).some((key) => key.toLowerCase() === normalized);
+}
+async function toNodeBody(body, headers) {
     if (body === undefined || body === null)
         return undefined;
     if (typeof body === 'string')
@@ -38,8 +42,25 @@ async function toNodeBody(body) {
         return new Uint8Array(body.buffer, body.byteOffset, body.byteLength);
     }
     if (body instanceof Blob) {
+        if (body.type && !hasHeader(headers, 'content-type')) {
+            headers['content-type'] = body.type;
+        }
         return new Uint8Array(await body.arrayBuffer());
     }
+    if (typeof FormData !== 'undefined' && body instanceof FormData) {
+        const request = new Request('https://zentao-api.local/', { method: 'POST', body });
+        const contentType = request.headers.get('content-type');
+        if (contentType && !hasHeader(headers, 'content-type')) {
+            headers['content-type'] = contentType;
+        }
+        return new Uint8Array(await request.arrayBuffer());
+    }
+    if (typeof URLSearchParams !== 'undefined' && body instanceof URLSearchParams) {
+        if (!hasHeader(headers, 'content-type')) {
+            headers['content-type'] = 'application/x-www-form-urlencoded;charset=UTF-8';
+        }
+        return body.toString();
+    }
     return String(body);
 }
 function abortError() {
@@ -60,7 +81,8 @@ async function nodeFetchWithTlsOptions(url, init, rejectUnauthorized) {
     const transport = parsed.protocol === 'https:'
         ? await importNodeModule('node:https')
         : await importNodeModule('node:http');
-    const body = await toNodeBody(init.body);
+    const headers = toNodeRequestHeaders(init.headers);
+    const body = await toNodeBody(init.body, headers);
     return new Promise((resolve, reject) => {
         if (init.signal?.aborted) {
             reject(abortError());
@@ -68,7 +90,7 @@ async function nodeFetchWithTlsOptions(url, init, rejectUnauthorized) {
         }
         const request = transport.request(parsed, {
             method: init.method ?? 'GET',
-            headers: toNodeRequestHeaders(init.headers),
+            headers,
             rejectUnauthorized,
         }, (response) => {
             const chunks = [];

package/dist/misc/errors.d.ts

@@ -23,7 +23,7 @@ export declare const ERRORS: {
     readonly E_INVALID_ACTION_DEFINITION: "Invalid module action definition.";
     readonly E_MISSING_PARAM: "Missing required parameter: {param}";
     readonly E_INVALID_PARAM: "Invalid value for parameter {param}: {value}";
-    readonly E_INVALID_REQUEST_NAME: "Request name must use the form \"moduleName/methodName\".";
+    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}";
 };
 /** SDK 已知错误码，对应 {@link ERRORS} 的 key。 */

package/dist/misc/errors.js

@@ -23,7 +23,7 @@ export const ERRORS = {
     E_INVALID_ACTION_DEFINITION: 'Invalid module action definition.',
     E_MISSING_PARAM: 'Missing required parameter: {param}',
     E_INVALID_PARAM: 'Invalid value for parameter {param}: {value}',
-    E_INVALID_REQUEST_NAME: 'Request name must use the form "moduleName/methodName".',
+    E_INVALID_REQUEST_NAME: 'Request name must use the form "moduleName", "moduleName/methodName", or "moduleName/<objectID>".',
     E_API_FAILED: 'ZenTao API returned failure: {message}',
 };
 /**