zentao-api 0.1.0 → 0.2.0-beta.2

package/dist/misc/environment.js

@@ -0,0 +1,124 @@
+import { ZentaoError } from './errors.js';
+/** 判断当前运行时是否为 Node.js。 */
+export function isNodeRuntime() {
+    return typeof process !== 'undefined' && Boolean(process.versions?.node);
+}
+async function importNodeModule(specifier) {
+    const dynamicImport = new Function('specifier', 'return import(specifier)');
+    return dynamicImport(specifier);
+}
+function toNodeRequestHeaders(headers) {
+    const result = {};
+    new Headers(headers).forEach((value, key) => {
+        result[key] = value;
+    });
+    return result;
+}
+function toResponseHeaders(headers) {
+    const result = new Headers();
+    for (const [key, value] of Object.entries(headers)) {
+        if (value === undefined)
+            continue;
+        result.set(key, Array.isArray(value) ? value.join(', ') : String(value));
+    }
+    return result;
+}
+async function toNodeBody(body) {
+    if (body === undefined || body === null)
+        return undefined;
+    if (typeof body === 'string')
+        return body;
+    if (body instanceof Uint8Array)
+        return body;
+    if (body instanceof ArrayBuffer)
+        return new Uint8Array(body);
+    if (ArrayBuffer.isView(body)) {
+        return new Uint8Array(body.buffer, body.byteOffset, body.byteLength);
+    }
+    if (body instanceof Blob) {
+        return new Uint8Array(await body.arrayBuffer());
+    }
+    return String(body);
+}
+function abortError() {
+    return new DOMException('The operation was aborted.', 'AbortError');
+}
+function concatenateChunks(chunks) {
+    const totalLength = chunks.reduce((total, chunk) => total + chunk.byteLength, 0);
+    const result = new Uint8Array(totalLength);
+    let offset = 0;
+    for (const chunk of chunks) {
+        result.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return result.buffer;
+}
+async function nodeFetchWithTlsOptions(url, init, rejectUnauthorized) {
+    const parsed = new URL(url);
+    const transport = parsed.protocol === 'https:'
+        ? await importNodeModule('node:https')
+        : await importNodeModule('node:http');
+    const body = await toNodeBody(init.body);
+    return new Promise((resolve, reject) => {
+        if (init.signal?.aborted) {
+            reject(abortError());
+            return;
+        }
+        const request = transport.request(parsed, {
+            method: init.method ?? 'GET',
+            headers: toNodeRequestHeaders(init.headers),
+            rejectUnauthorized,
+        }, (response) => {
+            const chunks = [];
+            response.on('data', (chunk) => {
+                chunks.push(typeof chunk === 'string' ? new TextEncoder().encode(chunk) : chunk);
+            });
+            response.on('end', () => {
+                cleanup();
+                const responseBody = chunks.length > 0 ? concatenateChunks(chunks) : undefined;
+                const fetchResponse = new Response(responseBody, {
+                    status: response.statusCode ?? 200,
+                    statusText: response.statusMessage ?? '',
+                    headers: toResponseHeaders(response.headers),
+                });
+                Object.defineProperty(fetchResponse, 'url', { value: url });
+                resolve(fetchResponse);
+            });
+        });
+        const cleanup = () => {
+            init.signal?.removeEventListener('abort', abortHandler);
+        };
+        const abortHandler = () => {
+            cleanup();
+            request.destroy(abortError());
+        };
+        request.on('error', (error) => {
+            cleanup();
+            reject(error);
+        });
+        init.signal?.addEventListener('abort', abortHandler, { once: true });
+        if (body !== undefined)
+            request.write(body);
+        request.end();
+    });
+}
+/** 浏览器无法跳过 TLS 校验，因此在发起请求前提前失败。 */
+export function assertInsecureSupported(enabled) {
+    if (enabled && !isNodeRuntime()) {
+        throw new ZentaoError('E_INSECURE_BROWSER');
+    }
+}
+/** 发起 fetch 请求；Node.js 下的 `insecure` 只作用于当前 HTTPS 请求。 */
+export async function fetchWithInsecureTls(enabled, url, init) {
+    if (!enabled)
+        return fetch(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

@@ -0,0 +1,30 @@
+export declare const ERRORS: {
+    readonly E_INVALID_BASE_URL: "Invalid ZenTao baseUrl.";
+    readonly E_NO_GLOBAL_CLIENT: "No global client configured. Call ZentaoClient.init() or pass options.client.";
+    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_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.";
+    readonly E_NO_PROFILE: "No ZenTao profile is configured.";
+    readonly E_PROFILE_NOT_FOUND: "ZenTao profile not found: {profileKey}";
+    readonly E_PROFILE_STORAGE_INVALID: "ZenTao profile storage is not valid JSON.";
+    readonly E_PROFILE_STORAGE_UNAVAILABLE: "ZenTao profile storage is unavailable in this runtime.";
+    readonly E_INVALID_MODULE: "Unknown module: {module}";
+    readonly E_INVALID_ACTION: "Unknown action: {module}-{action}";
+    readonly E_INVALID_MODULE_DEFINITION: "Invalid module definition.";
+    readonly E_INVALID_ACTION_DEFINITION: "Invalid module action definition.";
+    readonly E_MISSING_PARAM: "Missing required parameter: {param}";
+    readonly E_INVALID_REQUEST_NAME: "Request name must use the form \"moduleName/methodName\".";
+};
+export type ErrorCode = keyof typeof ERRORS;
+/** SDK 统一错误类型，所有可预期错误都会携带稳定错误码。 */
+export declare class ZentaoError extends Error {
+    /** 错误码，对应 {@link ERRORS} 的 key。 */
+    readonly code: ErrorCode;
+    /** 附加上下文，例如 HTTP 响应详情或原始异常。 */
+    readonly details?: unknown;
+    /** 根据错误码和占位符替换值创建错误。 */
+    constructor(code: ErrorCode, replacements?: Record<string, string | number>, details?: unknown);
+}

package/dist/misc/errors.js

@@ -0,0 +1,40 @@
+export const ERRORS = {
+    E_INVALID_BASE_URL: 'Invalid ZenTao baseUrl.',
+    E_NO_GLOBAL_CLIENT: 'No global client configured. Call ZentaoClient.init() or pass options.client.',
+    E_HTTP_ERROR: 'HTTP request failed: {status} {statusText}',
+    E_NETWORK_ERROR: 'Network request failed: {message}',
+    E_TIMEOUT: 'Request timed out.',
+    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.',
+    E_NO_PROFILE: 'No ZenTao profile is configured.',
+    E_PROFILE_NOT_FOUND: 'ZenTao profile not found: {profileKey}',
+    E_PROFILE_STORAGE_INVALID: 'ZenTao profile storage is not valid JSON.',
+    E_PROFILE_STORAGE_UNAVAILABLE: 'ZenTao profile storage is unavailable in this runtime.',
+    E_INVALID_MODULE: 'Unknown module: {module}',
+    E_INVALID_ACTION: 'Unknown action: {module}-{action}',
+    E_INVALID_MODULE_DEFINITION: 'Invalid module definition.',
+    E_INVALID_ACTION_DEFINITION: 'Invalid module action definition.',
+    E_MISSING_PARAM: 'Missing required parameter: {param}',
+    E_INVALID_REQUEST_NAME: 'Request name must use the form "moduleName/methodName".',
+};
+/** SDK 统一错误类型，所有可预期错误都会携带稳定错误码。 */
+export class ZentaoError extends Error {
+    /** 错误码，对应 {@link ERRORS} 的 key。 */
+    code;
+    /** 附加上下文，例如 HTTP 响应详情或原始异常。 */
+    details;
+    /** 根据错误码和占位符替换值创建错误。 */
+    constructor(code, replacements, details) {
+        let message = ERRORS[code];
+        if (replacements) {
+            for (const [key, value] of Object.entries(replacements)) {
+                message = message.replaceAll(`{${key}}`, String(value));
+            }
+        }
+        super(message);
+        this.name = 'ZentaoError';
+        this.code = code;
+        this.details = details;
+    }
+}

package/dist/misc/global-options.d.ts

@@ -0,0 +1,5 @@
+import type { GlobalOptions } from '../types/index.js';
+/** 获取当前全局选项快照；返回副本，避免调用方直接改写内部状态。 */
+export declare function getGlobalOptions(): GlobalOptions;
+/** 合并设置全局选项；传入 `undefined` 可清空对应字段。 */
+export declare function setGlobalOptions(options: Partial<GlobalOptions>): void;

package/dist/misc/global-options.js

@@ -0,0 +1,9 @@
+let globalOptions = {};
+/** 获取当前全局选项快照；返回副本，避免调用方直接改写内部状态。 */
+export function getGlobalOptions() {
+    return { ...globalOptions };
+}
+/** 合并设置全局选项；传入 `undefined` 可清空对应字段。 */
+export function setGlobalOptions(options) {
+    globalOptions = { ...globalOptions, ...options };
+}

package/dist/modules/generated.d.ts

@@ -0,0 +1,8 @@
+import type { ModuleDefinition } from '../types/index.js';
+/**
+ * 内置模块注册表：key 为模块名（小写），value 为对应禅道 REST 资源元数据。
+ * 新增模块时优先更新 OpenAPI 数据并重新生成此文件。
+ *
+ * 此文件由 scripts/update-registry.ts 自动生成，请勿手动编辑。
+ */
+export declare const BUILTIN_MODULES: ModuleDefinition[];