zentao-api 0.1.0 → 0.2.0-beta.1

package/dist/client/index.js

@@ -0,0 +1,149 @@
+import { ZentaoError } from '../misc/errors.js';
+import { assertInsecureSupported, withInsecureTls } from '../misc/environment.js';
+import { getGlobalOptions, setGlobalOptions } from '../misc/global-options.js';
+const DEFAULT_TIMEOUT = 10000;
+/** 将用户传入的站点根地址规范化，兼容误传入 `/api.php/v2` 的场景。 */
+function normalizeSiteUrl(baseUrl) {
+    const trimmed = baseUrl.trim().replace(/\/+$/, '');
+    if (!trimmed)
+        throw new ZentaoError('E_INVALID_BASE_URL');
+    return trimmed.replace(/\/api\.php\/v2$/i, '');
+}
+/** 拼接 API 路径与查询参数，跳过值为 `undefined` 的查询项。 */
+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));
+    }
+    return url.toString();
+}
+/** 优先解析 JSON；非 JSON 响应保留为原始文本。 */
+async function parseResponse(response) {
+    const text = await response.text();
+    if (text === '')
+        return undefined;
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return text;
+    }
+}
+/** 禅道 API 客户端，负责 Token 注入、请求超时、TLS 选项和响应解析。 */
+export class ZentaoClient {
+    /** 禅道站点根地址，不包含 `/api.php/v2`。 */
+    siteUrl;
+    /** 禅道 API v2 根地址。 */
+    baseUrl;
+    token;
+    timeout;
+    insecure;
+    constructor(input) {
+        const options = typeof input === 'string' ? { baseUrl: input } : input;
+        this.siteUrl = normalizeSiteUrl(options.baseUrl);
+        this.baseUrl = `${this.siteUrl}/api.php/v2`;
+        this.token = options.token;
+        this.timeout = options.timeout;
+        this.insecure = options.insecure;
+    }
+    /**
+     * 发起一次原始 API 请求。
+     *
+     * 默认使用 GET；当服务端返回 `{ status: "fail" }` 时仍按原始内容返回，
+     * 只有 HTTP/网络/超时等传输层错误会抛出 {@link ZentaoError}。
+     */
+    async request(path, options = {}) {
+        const globals = getGlobalOptions();
+        const method = options.method ?? 'GET';
+        const timeout = options.timeout ?? globals.timeout ?? this.timeout ?? DEFAULT_TIMEOUT;
+        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 = {
+            'Content-Type': 'application/json',
+        };
+        if (this.token) {
+            headers.Token = this.token;
+        }
+        const init = {
+            method,
+            headers,
+            signal: controller.signal,
+        };
+        // GET 请求不携带 body，避免浏览器和部分代理拒绝请求。
+        if (options.body && method !== 'GET') {
+            init.body = JSON.stringify(options.body);
+        }
+        try {
+            return await withInsecureTls(insecure, async () => {
+                const response = await fetch(url, init);
+                if (!response.ok) {
+                    throw new ZentaoError('E_HTTP_ERROR', {
+                        status: response.status,
+                        statusText: response.statusText,
+                    }, {
+                        url: response.url,
+                        status: response.status,
+                        statusText: response.statusText,
+                        body: await response.text().catch(() => undefined),
+                    });
+                }
+                return parseResponse(response);
+            });
+        }
+        catch (error) {
+            if (error instanceof ZentaoError)
+                throw error;
+            if (error instanceof DOMException && error.name === 'AbortError') {
+                throw new ZentaoError('E_TIMEOUT');
+            }
+            throw new ZentaoError('E_NETWORK_ERROR', { message: error.message ?? String(error) }, error);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    /** 发起 GET 请求并按调用方指定类型返回。 */
+    async get(path) {
+        return this.request(path, { method: 'GET' });
+    }
+    /** 发起 POST 请求并发送 JSON body。 */
+    async post(path, body) {
+        return this.request(path, { method: 'POST', body });
+    }
+    /** 发起 PUT 请求并发送 JSON body。 */
+    async put(path, body) {
+        return this.request(path, { method: 'PUT', body });
+    }
+    /** 发起 DELETE 请求。 */
+    async delete(path) {
+        return this.request(path, { method: 'DELETE' });
+    }
+    /** 使用账号密码登录，成功后把返回 Token 写入当前客户端实例。 */
+    async login(account, password) {
+        const response = await this.post('/users/login', { account, password });
+        if (response.status !== 'success' || !response.token) {
+            throw new ZentaoError('E_LOGIN_FAILED');
+        }
+        this.token = response.token;
+        return response.token;
+    }
+    /** 创建客户端实例，语义等同于 `new ZentaoClient(options)`。 */
+    static create(options) {
+        return new ZentaoClient(options);
+    }
+    /** 创建客户端并写入全局选项，供高阶 `request()` 默认使用。 */
+    static init(options) {
+        const client = new ZentaoClient(options);
+        setGlobalOptions({ client });
+        return client;
+    }
+}
+export function createClient(options) {
+    return ZentaoClient.create(options);
+}

package/dist/index.d.ts

@@ -1,4 +1,7 @@
-import * as utils from './utils';
-import Zentao from './zentao';
-import Zentao12 from './zentao12';
-export { utils, Zentao, Zentao12 };
+export { ZentaoClient } from './client/index.js';
+export { ERRORS, ZentaoError, type ErrorCode } from './misc/errors.js';
+export { getGlobalOptions, setGlobalOptions } from './misc/global-options.js';
+export { defineModuleActions, defineModules, type DefineModulesOptions, getModule, getModuleAction, } from './modules/registry.js';
+export { request } from './request/index.js';
+export { BUILD, VERSION } from './version.js';
+export type { ApiListResponse, ApiResponse, ClientRequestOptions, GlobalOptions, HttpMethod, ListPagerInfo, LoginResponse, ModuleAction, ModuleActionMethod, ModuleActionName, ModuleActionPagerGetterMap, ModuleActionParam, ModuleActionParamOption, ModuleActionRequestBody, ModuleActionResponse, ModuleActionResultRender, ModuleActionResultRenderType, ModuleActionResultType, ModuleActionType, ModuleDefinition, ModuleName, Pager, RequestOptions, ResolvedModuleCommand, ResponseData, ServerConfig, ZentaoClientOptions, } from './types/index.js';

package/dist/index.js

@@ -1,8 +1,6 @@
-
-'use strict'
-
-if (process.env.NODE_ENV === 'production') {
-  module.exports = require('./zentao-api.cjs.production.min.js')
-} else {
-  module.exports = require('./zentao-api.cjs.development.js')
-}
+export { ZentaoClient } from './client/index.js';
+export { ERRORS, ZentaoError } from './misc/errors.js';
+export { getGlobalOptions, setGlobalOptions } from './misc/global-options.js';
+export { defineModuleActions, defineModules, getModule, getModuleAction, } from './modules/registry.js';
+export { request } from './request/index.js';
+export { BUILD, VERSION } from './version.js';

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

@@ -0,0 +1 @@
+export * from '../index.js';

package/dist/misc/browser-global.js

@@ -0,0 +1,8 @@
+import * as api from '../index.js';
+// Bun 的 IIFE bundle 不总是自动挂载 globalName；这里显式暴露浏览器全局对象。
+const globalTarget = globalThis;
+globalTarget.ZentaoAPI = api;
+if (globalTarget.window) {
+    globalTarget.window.ZentaoAPI = api;
+}
+export * from '../index.js';

package/dist/misc/environment.d.ts

@@ -0,0 +1,6 @@
+/** 判断当前运行时是否为 Node.js。 */
+export declare function isNodeRuntime(): boolean;
+/** 浏览器无法跳过 TLS 校验，因此在发起请求前提前失败。 */
+export declare function assertInsecureSupported(enabled: boolean | undefined): void;
+/** 在 Node.js 中临时关闭 TLS 校验，并在本次请求结束后恢复原值。 */
+export declare function withInsecureTls<T>(enabled: boolean | undefined, fn: () => Promise<T>): Promise<T>;

package/dist/misc/environment.js

@@ -0,0 +1,30 @@
+import { ZentaoError } from './errors.js';
+/** 判断当前运行时是否为 Node.js。 */
+export function isNodeRuntime() {
+    return typeof process !== 'undefined' && Boolean(process.versions?.node);
+}
+/** 浏览器无法跳过 TLS 校验，因此在发起请求前提前失败。 */
+export function assertInsecureSupported(enabled) {
+    if (enabled && !isNodeRuntime()) {
+        throw new ZentaoError('E_INSECURE_BROWSER');
+    }
+}
+/** 在 Node.js 中临时关闭 TLS 校验，并在本次请求结束后恢复原值。 */
+export async function withInsecureTls(enabled, fn) {
+    if (!enabled)
+        return fn();
+    assertInsecureSupported(enabled);
+    const previous = process.env.NODE_TLS_REJECT_UNAUTHORIZED;
+    process.env.NODE_TLS_REJECT_UNAUTHORIZED = '0';
+    try {
+        return await fn();
+    }
+    finally {
+        if (previous === undefined) {
+            delete process.env.NODE_TLS_REJECT_UNAUTHORIZED;
+        }
+        else {
+            process.env.NODE_TLS_REJECT_UNAUTHORIZED = previous;
+        }
+    }
+}

package/dist/misc/errors.d.ts

@@ -0,0 +1,25 @@
+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_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,35 @@
+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_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[];