zentao-api 0.6.4 → 0.6.6

package/dist/client/index.d.ts

@@ -42,6 +42,7 @@ export declare class ZentaoClient {
      *
      * 特殊处理：
      * - 默认 HTTP 方法为 `GET`，`GET` 请求即使提供了 `options.body` 也不会发送，避免被部分代理/浏览器拒绝。
+     * - 不自动跟随重定向，避免把 `Token` 或请求体转发到另一个地址。
      * - 非空响应优先按 JSON 解析；解析失败时回落为字符串原文。
      * - 业务层失败（即响应体 `{ status: "fail" }`）不会抛出，仍按原样返回；只有 HTTP/网络/超时等传输层错误才会抛错。
      * - `insecure` 仅在 Node.js 下可用，浏览器中传入会抛 `E_INSECURE_BROWSER`。
@@ -50,7 +51,9 @@ export declare class ZentaoClient {
      * @param options - 单次请求选项，参见 {@link ClientRequestOptions}。
      * @returns 解析后的响应体；当响应为空字符串时返回 `undefined`。
      * @throws {ZentaoError} 可能抛出 `E_HTTP_ERROR`（非 2xx 状态）、`E_NETWORK_ERROR`（底层 fetch 失败）、
-     *   `E_TIMEOUT`（超过 `timeout`）或 `E_INSECURE_BROWSER`（浏览器中开启了 `insecure`）。
+     *   `E_TIMEOUT`（超过 `timeout`）、`E_ABORTED`（外部信号取消）或
+     *   `E_INSECURE_BROWSER`（浏览器中开启了 `insecure`）；传入 `ReadableStream` 请求体时会抛
+     *   `E_INVALID_PARAM`。
      */
     request(path: string, options: ClientRequestOptions & {
         responseType: 'response';

package/dist/client/index.js

@@ -4,14 +4,27 @@ import { getGlobalOptions, setGlobalOptions } from '../misc/global-options.js';
 import { addProfile, switchProfile } from '../profiles/index.js';
 import { isRecord, normalizeSiteUrl } from '../utils/index.js';
 const DEFAULT_TIMEOUT = 10000;
-/** 拼接 API 路径与查询参数，跳过值为 `undefined` 的查询项。 */
+function appendQueryValue(search, key, value) {
+    if (value === undefined)
+        return;
+    if (Array.isArray(value)) {
+        value.forEach((item, index) => appendQueryValue(search, `${key}[${index}]`, item));
+        return;
+    }
+    if (isPlainObject(value)) {
+        for (const [childKey, childValue] of Object.entries(value)) {
+            appendQueryValue(search, `${key}[${childKey}]`, childValue);
+        }
+        return;
+    }
+    search.append(key, value === null ? '' : String(value));
+}
+/** 拼接 API 路径与查询参数；结构化值使用 deepObject 风格的方括号键。 */
 function buildUrl(baseUrl, path, query) {
     const normalizedPath = path.startsWith('/') ? path : `/${path}`;
     const url = new URL(`${baseUrl}${normalizedPath}`);
     for (const [key, value] of Object.entries(query ?? {})) {
-        if (value === undefined)
-            continue;
-        url.searchParams.set(key, String(value));
+        appendQueryValue(url.searchParams, key, value);
     }
     return url.toString();
 }
@@ -41,6 +54,9 @@ function appendFormValue(form, key, value) {
 function serializeBody(body, bodyType, headers) {
     if (body === undefined || body === null)
         return undefined;
+    if (isInstanceOfGlobal(body, 'ReadableStream')) {
+        throw new ZentaoError('E_INVALID_PARAM', { param: 'body', value: 'ReadableStream' });
+    }
     if (bodyType === 'form') {
         const form = body instanceof URLSearchParams ? body : new URLSearchParams();
         if (!(body instanceof URLSearchParams) && isPlainObject(body)) {
@@ -60,8 +76,7 @@ function serializeBody(body, bodyType, headers) {
         isArrayBufferBody(body) ||
         isInstanceOfGlobal(body, 'FormData') ||
         isInstanceOfGlobal(body, 'URLSearchParams') ||
-        isInstanceOfGlobal(body, 'Blob') ||
-        isInstanceOfGlobal(body, 'ReadableStream')) {
+        isInstanceOfGlobal(body, 'Blob')) {
         return body;
     }
     if (!headers.has('Content-Type')) {
@@ -71,8 +86,26 @@ function serializeBody(body, bodyType, headers) {
 }
 function createRequestSignal(timeout, externalSignal) {
     const controller = new AbortController();
-    const abortFromExternal = () => controller.abort(externalSignal?.reason);
-    const timer = setTimeout(() => controller.abort(), timeout);
+    let timedOut = false;
+    let cleaned = false;
+    let timer;
+    const cleanup = () => {
+        if (cleaned)
+            return;
+        cleaned = true;
+        clearTimeout(timer);
+        externalSignal?.removeEventListener('abort', abortFromExternal);
+    };
+    const abortFromExternal = () => {
+        controller.abort(externalSignal?.reason);
+        cleanup();
+    };
+    timer = setTimeout(() => {
+        timedOut = true;
+        controller.abort();
+        cleanup();
+    }, timeout);
+    timer.unref?.();
     if (externalSignal?.aborted) {
         abortFromExternal();
     }
@@ -81,12 +114,145 @@ function createRequestSignal(timeout, externalSignal) {
     }
     return {
         signal: controller.signal,
-        cleanup: () => {
-            clearTimeout(timer);
-            externalSignal?.removeEventListener('abort', abortFromExternal);
-        },
+        cleanup,
+        didTimeout: () => timedOut,
     };
 }
+function keepResponseSignalUntilBodyEnds(response, cleanup, state = { branches: new Set(), cleanup, complete: false }) {
+    const branch = Symbol();
+    state.branches.add(branch);
+    let branchFinished = false;
+    const finishBranch = (bodyComplete) => {
+        if (branchFinished)
+            return;
+        branchFinished = true;
+        state.branches.delete(branch);
+        if (!state.complete && (bodyComplete || state.branches.size === 0)) {
+            state.complete = true;
+            state.cleanup();
+        }
+    };
+    let prototype = response;
+    let nativeBodyGetter;
+    while (prototype && !nativeBodyGetter) {
+        const descriptor = Object.getOwnPropertyDescriptor(prototype, 'body');
+        if (descriptor?.get) {
+            nativeBodyGetter = descriptor.get.bind(response);
+        }
+        prototype = Object.getPrototypeOf(prototype);
+    }
+    if (!nativeBodyGetter) {
+        finishBranch(true);
+        return response;
+    }
+    if (!nativeBodyGetter()) {
+        finishBranch(true);
+        return response;
+    }
+    let wrappedBody;
+    Object.defineProperty(response, 'body', {
+        configurable: true,
+        get() {
+            const nativeBody = nativeBodyGetter();
+            if (!nativeBody) {
+                wrappedBody = null;
+                finishBranch(true);
+                return null;
+            }
+            if (wrappedBody === undefined) {
+                let reader;
+                const getReader = () => reader ??= nativeBodyGetter().getReader();
+                wrappedBody = new ReadableStream({
+                    type: 'bytes',
+                    async pull(controller) {
+                        let activeReader;
+                        try {
+                            activeReader = getReader();
+                        }
+                        catch (error) {
+                            controller.error(error);
+                            return;
+                        }
+                        try {
+                            const chunk = await activeReader.read();
+                            if (chunk.done) {
+                                finishBranch(true);
+                                const byobRequest = 'byobRequest' in controller ? controller.byobRequest : null;
+                                controller.close();
+                                byobRequest?.respond(0);
+                            }
+                            else {
+                                const value = new Uint8Array(chunk.value.byteLength);
+                                value.set(chunk.value);
+                                controller.enqueue(value);
+                            }
+                        }
+                        catch (error) {
+                            finishBranch(true);
+                            controller.error(error);
+                        }
+                    },
+                    async cancel(reason) {
+                        const activeReader = getReader();
+                        try {
+                            await activeReader.cancel(reason);
+                        }
+                        finally {
+                            finishBranch(false);
+                        }
+                    },
+                }, { highWaterMark: 0 });
+            }
+            return wrappedBody;
+        },
+    });
+    for (const name of ['arrayBuffer', 'blob', 'formData', 'json', 'text', 'bytes']) {
+        const original = Reflect.get(response, name);
+        if (typeof original !== 'function')
+            continue;
+        Object.defineProperty(response, name, {
+            configurable: true,
+            value: (...args) => {
+                if (wrappedBody?.locked) {
+                    return Promise.reject(new TypeError('Response body is locked.'));
+                }
+                const nativeBody = nativeBodyGetter();
+                const canConsume = !response.bodyUsed && !nativeBody?.locked;
+                const wrapperReader = canConsume ? response.body?.getReader() : undefined;
+                let result;
+                try {
+                    result = Reflect.apply(original, response, args);
+                }
+                catch (error) {
+                    wrapperReader?.releaseLock();
+                    throw error;
+                }
+                if (!canConsume)
+                    return result;
+                return result.then((value) => {
+                    wrapperReader?.releaseLock();
+                    finishBranch(true);
+                    return value;
+                }, (error) => {
+                    wrapperReader?.releaseLock();
+                    if (response.bodyUsed)
+                        finishBranch(true);
+                    throw error;
+                });
+            },
+        });
+    }
+    const clone = response.clone.bind(response);
+    Object.defineProperty(response, 'clone', {
+        configurable: true,
+        value: () => {
+            if (wrappedBody?.locked)
+                throw new TypeError('Response body is locked.');
+            return keepResponseSignalUntilBodyEnds(clone(), cleanup, state);
+        },
+    });
+    return response;
+}
 /** 按指定策略解析响应；默认优先 JSON，失败后保留原始文本。 */
 async function parseResponse(response, responseType = 'auto') {
     if (responseType === 'response')
@@ -151,16 +317,19 @@ export class ZentaoClient {
         if (this.token) {
             headers.set('Token', this.token);
         }
-        const { signal, cleanup } = createRequestSignal(timeout, options.signal);
         const init = {
             method,
             headers,
-            signal,
+            redirect: 'manual',
         };
         // GET 请求不携带 body，避免浏览器和部分代理拒绝请求。
         if (options.body !== undefined && method !== 'GET') {
             init.body = serializeBody(options.body, options.bodyType, headers);
         }
+        // 先完成同步序列化，再启动计时器，避免序列化失败遗留活动 timer。
+        const { signal, cleanup, didTimeout } = createRequestSignal(timeout, options.signal);
+        init.signal = signal;
+        let keepResponseSignal = false;
         try {
             const response = await fetchWithInsecureTls(insecure, url, init);
             if (!response.ok) {
@@ -174,18 +343,26 @@ export class ZentaoClient {
                     body: await response.text().catch(() => undefined),
                 });
             }
-            return parseResponse(response, options.responseType);
+            if (options.responseType === 'response') {
+                keepResponseSignal = true;
+                return keepResponseSignalUntilBodyEnds(response, cleanup);
+            }
+            return await parseResponse(response, options.responseType);
         }
         catch (error) {
+            if (signal.aborted) {
+                throw new ZentaoError(didTimeout() ? 'E_TIMEOUT' : 'E_ABORTED', undefined, error);
+            }
             if (error instanceof ZentaoError)
                 throw error;
             if (error instanceof DOMException && error.name === 'AbortError') {
-                throw new ZentaoError('E_TIMEOUT');
+                throw new ZentaoError('E_ABORTED', undefined, error);
             }
             throw new ZentaoError('E_NETWORK_ERROR', { message: error.message ?? String(error) }, error);
         }
         finally {
-            cleanup();
+            if (!keepResponseSignal)
+                cleanup();
         }
     }
     /**

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, 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';
+export type * from './types/index.js';

package/dist/misc/environment.d.ts

@@ -4,5 +4,3 @@ export declare function isNodeRuntime(): boolean;
 export declare function assertInsecureSupported(enabled: boolean | undefined): void;
 /** 发起 fetch 请求；Node.js 下的 `insecure` 只作用于当前 HTTPS 请求。 */
 export declare function fetchWithInsecureTls(enabled: boolean | undefined, url: string, init: RequestInit): Promise<Response>;
-/** 保留给内部测试和兼容调用：校验 TLS 选项，但不再改写进程级环境变量。 */
-export declare function withInsecureTls<T>(enabled: boolean | undefined, fn: () => Promise<T>): Promise<T>;

package/dist/misc/environment.js

@@ -61,6 +61,9 @@ async function toNodeBody(body, headers) {
         }
         return body.toString();
     }
+    if (typeof ReadableStream !== 'undefined' && body instanceof ReadableStream) {
+        throw new ZentaoError('E_INVALID_PARAM', { param: 'body', value: 'ReadableStream' });
+    }
     return String(body);
 }
 function abortError() {
@@ -82,23 +85,55 @@ async function nodeFetchWithTlsOptions(url, init, rejectUnauthorized) {
         ? await importNodeModule('node:https')
         : await importNodeModule('node:http');
     const headers = toNodeRequestHeaders(init.headers);
+    if (!hasHeader(headers, 'accept-encoding')) {
+        headers['accept-encoding'] = 'identity';
+    }
     const body = await toNodeBody(init.body, headers);
     return new Promise((resolve, reject) => {
         if (init.signal?.aborted) {
             reject(abortError());
             return;
         }
+        let settled = false;
+        let activeResponse;
+        const cleanup = () => {
+            init.signal?.removeEventListener('abort', abortHandler);
+        };
+        const rejectOnce = (error) => {
+            if (settled)
+                return;
+            settled = true;
+            cleanup();
+            reject(error);
+        };
+        const resolveOnce = (response) => {
+            if (settled)
+                return;
+            settled = true;
+            cleanup();
+            resolve(response);
+        };
         const request = transport.request(parsed, {
             method: init.method ?? 'GET',
             headers,
             rejectUnauthorized,
         }, (response) => {
+            activeResponse = response;
             const chunks = [];
+            let ended = false;
             response.on('data', (chunk) => {
                 chunks.push(typeof chunk === 'string' ? new TextEncoder().encode(chunk) : chunk);
             });
-            response.on('end', () => {
-                cleanup();
+            response.once('aborted', () => {
+                rejectOnce(new Error('HTTP response was aborted before completion.'));
+            });
+            response.once('error', rejectOnce);
+            response.once('close', () => {
+                if (!ended)
+                    rejectOnce(new Error('HTTP response closed before completion.'));
+            });
+            response.once('end', () => {
+                ended = true;
                 const responseBody = chunks.length > 0 ? concatenateChunks(chunks) : undefined;
                 const fetchResponse = new Response(responseBody, {
                     status: response.statusCode ?? 200,
@@ -106,20 +141,16 @@ async function nodeFetchWithTlsOptions(url, init, rejectUnauthorized) {
                     headers: toResponseHeaders(response.headers),
                 });
                 Object.defineProperty(fetchResponse, 'url', { value: url });
-                resolve(fetchResponse);
+                resolveOnce(fetchResponse);
             });
         });
-        const cleanup = () => {
-            init.signal?.removeEventListener('abort', abortHandler);
-        };
         const abortHandler = () => {
-            cleanup();
-            request.destroy(abortError());
+            const error = abortError();
+            rejectOnce(error);
+            activeResponse?.destroy(error);
+            request.destroy(error);
         };
-        request.on('error', (error) => {
-            cleanup();
-            reject(error);
-        });
+        request.once('error', rejectOnce);
         init.signal?.addEventListener('abort', abortHandler, { once: true });
         if (body !== undefined)
             request.write(body);
@@ -139,10 +170,3 @@ export async function fetchWithInsecureTls(enabled, url, init) {
     assertInsecureSupported(enabled);
     return nodeFetchWithTlsOptions(url, init, false);
 }
-/** 保留给内部测试和兼容调用：校验 TLS 选项，但不再改写进程级环境变量。 */
-export async function withInsecureTls(enabled, fn) {
-    if (!enabled)
-        return fn();
-    assertInsecureSupported(enabled);
-    return fn();
-}

package/dist/misc/errors.d.ts

@@ -10,6 +10,7 @@ export declare const ERRORS: {
     readonly E_HTTP_ERROR: "HTTP request failed: {status} {statusText}";
     readonly E_NETWORK_ERROR: "Network request failed: {message}";
     readonly E_TIMEOUT: "Request timed out.";
+    readonly E_ABORTED: "Request was aborted.";
     readonly E_INSECURE_BROWSER: "The insecure option is only supported in Node.js runtimes.";
     readonly E_LOGIN_FAILED: "ZenTao login failed.";
     readonly E_INVALID_PROFILE: "Invalid ZenTao profile.";

package/dist/misc/errors.js

@@ -10,6 +10,7 @@ export const ERRORS = {
     E_HTTP_ERROR: 'HTTP request failed: {status} {statusText}',
     E_NETWORK_ERROR: 'Network request failed: {message}',
     E_TIMEOUT: 'Request timed out.',
+    E_ABORTED: 'Request was aborted.',
     E_INSECURE_BROWSER: 'The insecure option is only supported in Node.js runtimes.',
     E_LOGIN_FAILED: 'ZenTao login failed.',
     E_INVALID_PROFILE: 'Invalid ZenTao profile.',