zentao-api 0.1.0 → 0.2.0-beta.1

package/dist/modules/registry.d.ts

@@ -0,0 +1,22 @@
+import type { ModuleAction, ModuleDefinition } from '../types/index.js';
+import { BUILTIN_MODULES } from './generated.js';
+export { BUILTIN_MODULES };
+export declare const MODULES: ModuleDefinition[];
+export interface DefineModulesOptions {
+    /** 同名模块是否整体替换；默认合并模块定义和动作。 */
+    relace?: boolean;
+}
+/** 定义或扩展模块；同名模块默认合并动作，`relace` 为真时整体替换，未知模块追加。 */
+export declare function defineModules(input: ModuleDefinition | ModuleDefinition[], options?: DefineModulesOptions): void;
+/** 为已存在模块定义或覆盖动作；同名动作替换，未知动作追加。 */
+export declare function defineModuleActions(moduleName: string, input: ModuleAction | ModuleAction[]): void;
+/** 获取模块定义；模块不存在时抛出 {@link ZentaoError}。 */
+export declare function getModule(moduleName: string): ModuleDefinition;
+/** 获取指定模块动作；`ls` 会作为 `list` 的别名处理。 */
+export declare function getModuleAction(moduleName: string, actionName: string): ModuleAction;
+/** 返回当前运行时注册表中的所有模块名。 */
+export declare function getModuleNames(): string[];
+/** 判断模块名是否已注册，大小写不敏感。 */
+export declare function isModuleName(moduleName: string): boolean;
+/** @internal */
+export declare function resetModuleDefinitions(): void;

package/dist/modules/registry.js

@@ -0,0 +1,129 @@
+import { ZentaoError } from '../misc/errors.js';
+import { asArray } from '../utils/index.js';
+import { BUILTIN_MODULES } from './generated.js';
+export { BUILTIN_MODULES };
+export const MODULES = BUILTIN_MODULES;
+// 运行时注册表使用内置定义的浅克隆，避免用户扩展污染生成文件导出的常量。
+let modules = cloneModules(BUILTIN_MODULES);
+let moduleMap = buildModuleMap(modules);
+function cloneActions(source) {
+    return source.map((action) => ({ ...action }));
+}
+function cloneModules(source) {
+    return source.map((module) => ({
+        ...module,
+        actions: cloneActions(module.actions),
+    }));
+}
+function findActionIndex(source, actionName) {
+    const key = actionName.toLowerCase();
+    return source.findIndex((action) => String(action.name).toLowerCase() === key);
+}
+function mergeActions(base, extension) {
+    const next = cloneActions(base);
+    for (const action of extension) {
+        const index = findActionIndex(next, String(action.name));
+        const clone = { ...action };
+        if (index >= 0) {
+            next[index] = clone;
+        }
+        else {
+            next.push(clone);
+        }
+    }
+    return next;
+}
+function mergeModule(base, extension) {
+    return {
+        ...base,
+        ...extension,
+        actions: mergeActions(base.actions, extension.actions),
+    };
+}
+function buildModuleMap(source) {
+    return new Map(source.map((module) => [module.name.toLowerCase(), module]));
+}
+function rebuildMap() {
+    moduleMap = buildModuleMap(modules);
+}
+function validateModule(module) {
+    if (!module || typeof module.name !== 'string' || !Array.isArray(module.actions)) {
+        throw new ZentaoError('E_INVALID_MODULE_DEFINITION');
+    }
+}
+function validateAction(action) {
+    if (!action || typeof action.name !== 'string' || typeof action.path !== 'string' || typeof action.method !== 'string') {
+        throw new ZentaoError('E_INVALID_ACTION_DEFINITION');
+    }
+}
+/** 定义或扩展模块；同名模块默认合并动作，`relace` 为真时整体替换，未知模块追加。 */
+export function defineModules(input, options = {}) {
+    for (const module of asArray(input)) {
+        validateModule(module);
+        const key = module.name.toLowerCase();
+        const index = modules.findIndex((item) => item.name.toLowerCase() === key);
+        const next = { ...module, actions: cloneActions(module.actions) };
+        if (index >= 0) {
+            modules[index] = options.relace ? next : mergeModule(modules[index], module);
+        }
+        else {
+            modules.push(next);
+        }
+    }
+    rebuildMap();
+}
+/** 为已存在模块定义或覆盖动作；同名动作替换，未知动作追加。 */
+export function defineModuleActions(moduleName, input) {
+    const module = moduleMap.get(moduleName.toLowerCase());
+    if (!module) {
+        throw new ZentaoError('E_INVALID_MODULE', { module: moduleName });
+    }
+    for (const action of asArray(input)) {
+        validateAction(action);
+        const index = findActionIndex(module.actions, String(action.name));
+        const next = { ...action };
+        // 同名动作替换，未知动作追加；不做深度合并，避免 schema/数组字段出现隐式规则。
+        if (index >= 0) {
+            module.actions[index] = next;
+        }
+        else {
+            module.actions.push(next);
+        }
+    }
+}
+/** 获取模块定义；模块不存在时抛出 {@link ZentaoError}。 */
+export function getModule(moduleName) {
+    const module = moduleMap.get(moduleName.toLowerCase());
+    if (!module) {
+        throw new ZentaoError('E_INVALID_MODULE', { module: moduleName });
+    }
+    return module;
+}
+/** 获取指定模块动作；`ls` 会作为 `list` 的别名处理。 */
+export function getModuleAction(moduleName, actionName) {
+    const module = getModule(moduleName);
+    const normalized = actionName === 'ls' ? 'list' : actionName;
+    const direct = module.actions.find((action) => String(action.name).toLowerCase() === normalized.toLowerCase());
+    if (direct)
+        return direct;
+    const crud = new Set(['list', 'get', 'create', 'update', 'delete']);
+    if (!crud.has(normalized)) {
+        const custom = module.actions.find((action) => action.type === 'action' && String(action.name).toLowerCase() === normalized.toLowerCase());
+        if (custom)
+            return custom;
+    }
+    throw new ZentaoError('E_INVALID_ACTION', { module: moduleName, action: actionName });
+}
+/** 返回当前运行时注册表中的所有模块名。 */
+export function getModuleNames() {
+    return modules.map((module) => module.name);
+}
+/** 判断模块名是否已注册，大小写不敏感。 */
+export function isModuleName(moduleName) {
+    return moduleMap.has(moduleName.toLowerCase());
+}
+/** @internal */
+export function resetModuleDefinitions() {
+    modules = cloneModules(BUILTIN_MODULES);
+    rebuildMap();
+}

package/dist/modules/resolve.d.ts

@@ -0,0 +1,7 @@
+import type { ListPagerInfo, ModuleAction, ModuleDefinition, ResolvedModuleCommand } from '../types/index.js';
+/** 将模块名、动作名和调用参数解析为实际 API 请求路径、查询参数和请求体。 */
+export declare function resolveModuleCommand(module: ModuleDefinition, actionName: string, params?: Record<string, unknown>): ResolvedModuleCommand;
+/** 根据动作定义中的 resultGetter，从原始响应里提取业务数据。 */
+export declare function extractResult(action: ModuleAction, response: Record<string, unknown>): unknown;
+/** 根据动作定义中的 pagerGetter，从原始响应里提取分页信息。 */
+export declare function extractPager(action: ModuleAction, response: Record<string, unknown>): ListPagerInfo | undefined;

package/dist/modules/resolve.js

@@ -0,0 +1,196 @@
+import { ZentaoError } from '../misc/errors.js';
+import { getNestedValue } from '../utils/index.js';
+import { getModuleAction } from './registry.js';
+const SCOPE_MAP = {
+    product: 'products',
+    project: 'projects',
+    execution: 'executions',
+};
+const SCOPE_KEY_ORDER = ['execution', 'project', 'product'];
+/** 从调用参数中推断作用域列表路径，优先级为执行 > 项目 > 产品。 */
+function pickScope(params) {
+    for (const key of SCOPE_KEY_ORDER) {
+        const value = params[key] ?? params[`${key}ID`];
+        if (value === undefined || value === null || value === '')
+            continue;
+        const numberValue = Number(value);
+        if (!Number.isNaN(numberValue)) {
+            return { scope: SCOPE_MAP[key], scopeID: numberValue };
+        }
+    }
+    return undefined;
+}
+/** 替换动作路径模板中的 `{param}` 占位符。 */
+function resolvePath(action, values) {
+    return action.path.replace(/\{(\w+)\}/g, (_, key) => {
+        const value = values[key];
+        if (value === undefined || value === '') {
+            throw new ZentaoError('E_MISSING_PARAM', { param: key });
+        }
+        return String(value);
+    });
+}
+/** 支持用户通过 `params.data` 传入 JSON 字符串或对象作为请求体基础值。 */
+function parseData(value) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value === 'string') {
+        try {
+            const parsed = JSON.parse(value);
+            return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    return value && typeof value === 'object' && !Array.isArray(value) ? value : undefined;
+}
+function isPlainObject(value) {
+    return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+/** 按 OpenAPI schema 的基础类型对参数做轻量转换。 */
+function coerceValue(value, type) {
+    if (value === undefined)
+        return undefined;
+    if (type === 'number' || type === 'integer') {
+        const numberValue = Number(value);
+        return Number.isNaN(numberValue) ? value : numberValue;
+    }
+    if (type === 'boolean') {
+        if (value === 'true')
+            return true;
+        if (value === 'false')
+            return false;
+        return Boolean(value);
+    }
+    return value;
+}
+/** 将模块名、动作名和调用参数解析为实际 API 请求路径、查询参数和请求体。 */
+export function resolveModuleCommand(module, actionName, params = {}) {
+    const action = getModuleAction(module.name, actionName);
+    const pathValues = {};
+    const pathParamNames = Object.keys(action.pathParams ?? {});
+    // 生成定义中的 scope 列表接口会统一成 /{scope}/{scopeID}/xxx。
+    if (pathParamNames.includes('scope')) {
+        const scope = pickScope(params);
+        if (!scope)
+            throw new ZentaoError('E_MISSING_PARAM', { param: 'product/project/execution' });
+        pathValues.scope = scope.scope;
+        pathValues.scopeID = scope.scopeID;
+    }
+    const idParamName = pathParamNames.find((key) => key.endsWith('ID') && key !== 'scopeID');
+    const idValue = params.id ?? params[`${module.name}ID`] ?? (idParamName ? params[idParamName] : undefined);
+    const id = idValue === undefined ? undefined : Number(idValue);
+    if (idParamName && id !== undefined && !Number.isNaN(id)) {
+        pathValues[idParamName] = id;
+    }
+    // pathParams 中未显式传值的参数，可从定义里的默认值或第一个可选项补齐。
+    for (const key of pathParamNames) {
+        if (key === 'scope' || key === 'scopeID' || pathValues[key] !== undefined)
+            continue;
+        const definition = action.pathParams?.[key];
+        const value = params[key];
+        if (value !== undefined) {
+            pathValues[key] = value;
+            continue;
+        }
+        if (typeof definition === 'object') {
+            if (definition.defaultValue !== undefined) {
+                pathValues[key] = definition.defaultValue;
+            }
+            else if (definition.options?.[0]?.value !== undefined) {
+                pathValues[key] = definition.options[0].value;
+            }
+        }
+        if (pathValues[key] === undefined) {
+            throw new ZentaoError('E_MISSING_PARAM', { param: key });
+        }
+    }
+    // 查询参数只从 action.params 中声明过的字段生成，避免把 body 字段误放到 URL 上。
+    const query = {};
+    for (const param of action.params ?? []) {
+        let value = params[param.name];
+        if (value === undefined && param.name === 'pageID') {
+            value = params.page;
+        }
+        if (value === undefined) {
+            value = param.defaultValue ?? param.options?.[0]?.value;
+        }
+        if (value === undefined && param.required) {
+            throw new ZentaoError('E_MISSING_PARAM', { param: param.name });
+        }
+        if (value !== undefined) {
+            query[param.name] = value;
+        }
+    }
+    let data = parseData(params.data);
+    if (action.requestBody?.schema?.type === 'object') {
+        data = data ? { ...data } : {};
+        const schema = action.requestBody.schema;
+        const required = new Set(schema.required ?? []);
+        for (const [key, property] of Object.entries(schema.properties ?? {})) {
+            // body 字段优先级：params.data 中的字段 > 平铺 params 字段 > schema 默认值。
+            const hasDataValue = Object.prototype.hasOwnProperty.call(data, key);
+            let value = data[key] ?? params[key] ?? property.defaultValue;
+            if (value === undefined && (property.required || required.has(key))) {
+                throw new ZentaoError('E_MISSING_PARAM', { param: key });
+            }
+            value = coerceValue(value, property.type);
+            if (property.type === 'array' && value !== undefined && !Array.isArray(value)) {
+                if (typeof value === 'string') {
+                    value = value.split(',');
+                }
+                else if (!hasDataValue || !isPlainObject(value)) {
+                    value = [value];
+                }
+            }
+            if (value !== undefined) {
+                data[key] = value;
+            }
+        }
+    }
+    return {
+        module: module.name,
+        action,
+        params,
+        path: resolvePath(action, pathValues),
+        query,
+        data,
+        id: id === undefined || Number.isNaN(id) ? undefined : id,
+    };
+}
+/** 根据动作定义中的 resultGetter，从原始响应里提取业务数据。 */
+export function extractResult(action, response) {
+    const getter = action.resultGetter;
+    if (!getter)
+        return response.data ?? response;
+    if (typeof getter === 'function')
+        return getter(response, {});
+    if (typeof getter === 'string')
+        return getNestedValue(response, getter);
+    const result = {};
+    for (const [targetKey, sourceKey] of Object.entries(getter)) {
+        result[targetKey] = response[sourceKey];
+    }
+    return result;
+}
+/** 根据动作定义中的 pagerGetter，从原始响应里提取分页信息。 */
+export function extractPager(action, response) {
+    const getter = action.pagerGetter;
+    if (!getter)
+        return response.pager;
+    if (typeof getter === 'function')
+        return getter(response, {});
+    if (typeof getter === 'string')
+        return getNestedValue(response, getter);
+    const page = response[getter.pageID];
+    const recPerPage = response[getter.recPerPage];
+    const recTotal = response[getter.recTotal];
+    if (page === undefined || recPerPage === undefined || recTotal === undefined)
+        return undefined;
+    return {
+        pageID: Number(page),
+        recPerPage: Number(recPerPage),
+        recTotal: Number(recTotal),
+    };
+}

package/dist/request/index.d.ts

@@ -0,0 +1,7 @@
+import type { RequestOptions, ResponseData } from '../types/index.js';
+/**
+ * 按模块动作名请求禅道 API。
+ *
+ * 选项优先级为：本次调用 options > 全局 options > 客户端默认值。
+ */
+export declare function request(name: `${string}/${string}`, params?: Record<string, unknown>, options?: RequestOptions): Promise<ResponseData>;

package/dist/request/index.js

@@ -0,0 +1,65 @@
+import { ZentaoError } from '../misc/errors.js';
+import { getGlobalOptions } from '../misc/global-options.js';
+import { getModule } from '../modules/registry.js';
+import { extractPager, extractResult, resolveModuleCommand } from '../modules/resolve.js';
+/** 将 `moduleName/methodName` 形式的请求名拆成模块名和动作名。 */
+function splitRequestName(name) {
+    const index = name.indexOf('/');
+    if (index <= 0 || index === name.length - 1) {
+        throw new ZentaoError('E_INVALID_REQUEST_NAME');
+    }
+    return {
+        moduleName: name.slice(0, index),
+        actionName: name.slice(index + 1),
+    };
+}
+/** 将禅道原始响应归一化为稳定的 ResponseData 结构。 */
+function normalizeResponse(command, raw, limit) {
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+        return { status: 'success', data: raw };
+    }
+    const record = raw;
+    const status = record.status === 'fail' ? 'fail' : 'success';
+    let data = extractResult(command.action, record);
+    const numericLimit = limit === undefined ? undefined : Number(limit);
+    if (Array.isArray(data) && numericLimit !== undefined && !Number.isNaN(numericLimit)) {
+        data = data.slice(0, numericLimit);
+    }
+    const pager = extractPager(command.action, record);
+    return {
+        status,
+        message: typeof record.message === 'string' ? record.message : undefined,
+        data,
+        pager: pager ? {
+            total: Number(pager.recTotal),
+            page: Number(pager.pageID),
+            recPerPage: Number(pager.recPerPage),
+        } : undefined,
+    };
+}
+/**
+ * 按模块动作名请求禅道 API。
+ *
+ * 选项优先级为：本次调用 options > 全局 options > 客户端默认值。
+ */
+export async function request(name, params = {}, options = {}) {
+    const globals = getGlobalOptions();
+    const client = options.client ?? globals.client;
+    if (!client) {
+        throw new ZentaoError('E_NO_GLOBAL_CLIENT');
+    }
+    const { moduleName, actionName } = splitRequestName(name);
+    const module = getModule(moduleName);
+    // recPerPage 是最常用的列表参数，允许在全局或本次调用中统一覆盖。
+    const recPerPage = params.recPerPage ?? options.recPerPage ?? globals.recPerPage;
+    const mergedParams = recPerPage === undefined ? params : { ...params, recPerPage };
+    const command = resolveModuleCommand(module, actionName, mergedParams);
+    const raw = await client.request(command.path, {
+        method: String(command.action.method).toUpperCase(),
+        query: command.query,
+        body: command.data,
+        timeout: options.timeout ?? globals.timeout,
+        insecure: options.insecure ?? globals.insecure,
+    });
+    return normalizeResponse(command, raw, options.limit ?? globals.limit);
+}

package/dist/types/index.d.ts

@@ -0,0 +1,235 @@
+import type { ZentaoClient } from '../client/index.js';
+/** 创建 {@link ZentaoClient} 时使用的配置。 */
+export interface ZentaoClientOptions {
+    /** 禅道站点根地址，例如 `https://zentao.example.com`；SDK 会自动拼接 `/api.php/v2`。 */
+    baseUrl: string;
+    /** 禅道 API Token；未提供时可稍后通过 {@link ZentaoClient.login} 获取并写入实例。 */
+    token?: string;
+    /** 默认请求超时时间，单位毫秒。 */
+    timeout?: number;
+    /** 是否跳过 TLS 证书验证；仅 Node.js 运行时支持，浏览器中会抛错。 */
+    insecure?: boolean;
+}
+/** SDK 进程级全局默认选项，供高阶 {@link request} 调用复用。 */
+export interface GlobalOptions {
+    /** 默认客户端；通常由 `ZentaoClient.init()` 设置。 */
+    client?: ZentaoClient;
+    /** 默认每页记录数，会映射到模块动作的 `recPerPage` 参数。 */
+    recPerPage?: string;
+    /** 默认限制返回列表数量，只影响 SDK 归一化后的 `data`。 */
+    limit?: string;
+    /** 默认请求超时时间，优先级低于单次请求选项。 */
+    timeout?: number;
+    /** 默认 TLS 跳过证书验证选项；仅 Node.js 运行时支持。 */
+    insecure?: boolean;
+}
+/** SDK 支持的 HTTP 方法。 */
+export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'DELETE';
+/** `ZentaoClient.request()` 的单次请求选项。 */
+export interface ClientRequestOptions {
+    /** HTTP 方法，默认 `GET`。 */
+    method?: HttpMethod;
+    /** JSON 请求体；`GET` 请求会忽略该字段。 */
+    body?: Record<string, unknown>;
+    /** URL 查询参数；`undefined` 值会被跳过。 */
+    query?: Record<string, string | number | boolean | undefined>;
+    /** 单次请求超时时间，优先级高于全局和客户端默认值。 */
+    timeout?: number;
+    /** 单次请求 TLS 跳过证书验证选项；仅 Node.js 运行时支持。 */
+    insecure?: boolean;
+}
+/** 高阶 `request("moduleName/methodName")` 的单次调用选项。 */
+export interface RequestOptions {
+    /** 本次调用使用的客户端；优先级高于全局客户端。 */
+    client?: ZentaoClient;
+    /** 本次调用使用的每页记录数，优先级高于全局 `recPerPage`。 */
+    recPerPage?: string;
+    /** 本次调用限制返回列表数量，优先级高于全局 `limit`。 */
+    limit?: string;
+    /** 本次调用超时时间。 */
+    timeout?: number;
+    /** 本次调用 TLS 跳过证书验证选项；仅 Node.js 运行时支持。 */
+    insecure?: boolean;
+}
+/** 高阶 `request()` 归一化后的返回数据。 */
+export interface ResponseData {
+    /** 禅道服务端状态；非标准响应会按成功响应包装到 `data`。 */
+    status: 'success' | 'fail';
+    /** 禅道服务端返回的消息。 */
+    message?: string;
+    /** 根据模块动作 `resultGetter` 提取后的业务数据。 */
+    data?: any;
+    /** 统一分页信息。 */
+    pager?: {
+        /** 总记录数。 */
+        total: number;
+        /** 当前页码。 */
+        page: number;
+        /** 每页记录数。 */
+        recPerPage: number;
+    };
+}
+/** 禅道 API 原始分页结构。 */
+export interface Pager {
+    /** 总记录数。 */
+    recTotal: number;
+    /** 每页记录数。 */
+    recPerPage: number;
+    /** 总页数，部分接口不返回。 */
+    pageTotal?: number;
+    /** 当前页码。 */
+    pageID: number;
+}
+/** 禅道 API 通用响应结构，允许携带任意业务字段。 */
+export interface ApiResponse {
+    /** 服务端返回状态。 */
+    status: 'success' | 'fail';
+    /** 服务端消息，可能是字符串、对象或数组。 */
+    message?: unknown;
+    /** 其他业务字段。 */
+    [key: string]: unknown;
+}
+/** 禅道 API 列表响应结构。 */
+export interface ApiListResponse extends ApiResponse {
+    /** 原始分页信息。 */
+    pager?: Pager;
+}
+/** 登录接口响应结构。 */
+export interface LoginResponse extends ApiResponse {
+    /** 登录成功后返回的 API Token。 */
+    token?: string;
+}
+/** 禅道 `?mode=getconfig` 返回的服务端配置。 */
+export interface ServerConfig {
+    version: string;
+    systemMode: string;
+    sprintConcept: string;
+    requestType: string;
+    requestFix: string;
+    moduleVar: string;
+    methodVar: string;
+    viewVar: string;
+    sessionVar: string;
+}
+/** 模块动作类型：基础 CRUD 或自定义动作。 */
+export type ModuleActionType = 'list' | 'get' | 'create' | 'update' | 'delete' | 'action';
+/** 模块动作使用的 HTTP 方法；兼容生成定义中的小写方法。 */
+export type ModuleActionMethod = HttpMethod | Lowercase<HttpMethod>;
+/** 模块动作名称，允许除基础动作外的自定义名称。 */
+export type ModuleActionName = ModuleActionType | (string & {});
+/** 模块动作参数可选项。 */
+export type ModuleActionParamOption = {
+    value: unknown;
+    label: string;
+};
+/** 模块动作的查询参数定义。 */
+export interface ModuleActionParam {
+    /** 参数名称。 */
+    name: string;
+    /** 参数说明。 */
+    description?: string;
+    /** 是否必填。 */
+    required?: boolean;
+    /** 未显式传入时使用的默认值。 */
+    defaultValue?: unknown;
+    /** 参数值类型，用于基础类型转换。 */
+    type?: 'string' | 'number' | 'boolean';
+    /** 参数可选值。 */
+    options?: ModuleActionParamOption[];
+}
+/** 模块动作结果形态。 */
+export type ModuleActionResultType = 'text' | 'object' | 'list';
+/** 列表分页信息别名。 */
+export type ListPagerInfo = Pager;
+/** 模块动作请求体定义。 */
+export interface ModuleActionRequestBody {
+    /** 请求体类型。 */
+    type?: 'object' | 'string';
+    /** 请求体是否必填。 */
+    required?: boolean;
+    /** OpenAPI 风格 schema，用于从 params 组装 body。 */
+    schema: Record<string, unknown>;
+    /** 请求体示例。 */
+    example?: unknown;
+}
+/** 模块动作响应定义。 */
+export interface ModuleActionResponse {
+    /** 响应说明。 */
+    description?: string;
+    /** 响应 schema。 */
+    schema: Record<string, unknown>;
+    /** 响应示例。 */
+    example?: unknown;
+}
+/** 模块动作渲染目标类型；保留给 CLI 等上层应用使用。 */
+export type ModuleActionResultRenderType = 'markdown' | 'json' | 'raw';
+/** 模块动作自定义渲染函数类型；SDK 本身不直接渲染终端输出。 */
+export type ModuleActionResultRender = (result: unknown, type: ModuleActionResultRenderType, action: ModuleAction) => string;
+/** 从原始响应中提取分页字段时使用的字段映射。 */
+export interface ModuleActionPagerGetterMap {
+    /** 当前页码字段名。 */
+    pageID: string;
+    /** 每页记录数字段名。 */
+    recPerPage: string;
+    /** 总记录数字段名。 */
+    recTotal: string;
+}
+/** 禅道模块中的单个 API 动作定义。 */
+export interface ModuleAction {
+    /** 动作名称，例如 `list`、`get`、`close`。 */
+    name: ModuleActionName;
+    /** 动作类型，决定高阶 request 的路径/参数解析策略。 */
+    type: ModuleActionType;
+    /** 面向用户展示的动作名称。 */
+    display?: string;
+    /** 动作说明。 */
+    description?: string;
+    /** HTTP 方法。 */
+    method: ModuleActionMethod;
+    /** API 路径模板，可包含 `{productID}` 等路径参数。 */
+    path: string;
+    /** 路径参数定义；字符串为说明，对象可携带默认值和可选项。 */
+    pathParams?: Record<string, string | Omit<ModuleActionParam, 'name'>>;
+    /** 查询参数定义。 */
+    params?: ModuleActionParam[];
+    /** 请求体定义。 */
+    requestBody?: ModuleActionRequestBody;
+    /** 结果形态。 */
+    resultType: ModuleActionResultType;
+    /** 从原始响应中提取分页信息的位置或函数。 */
+    pagerGetter?: string | ModuleActionPagerGetterMap | ((data: unknown, params: Record<string, unknown>) => ListPagerInfo);
+    /** 从原始响应中提取业务数据的位置或函数。 */
+    resultGetter?: string | Record<string, string> | ((data: unknown, params: Record<string, unknown>) => unknown);
+    /** 供上层应用使用的渲染配置。 */
+    render?: string | ModuleActionResultRender | Record<ModuleActionResultRenderType, ModuleActionResultRender>;
+}
+/** 内置模块名称，同时允许用户扩展自定义模块名。 */
+export type ModuleName = 'user' | 'program' | 'product' | 'project' | 'execution' | 'productplan' | 'story' | 'epic' | 'requirement' | 'bug' | 'testcase' | 'task' | 'feedback' | 'ticket' | 'system' | 'build' | 'testtask' | 'release' | 'file' | (string & {});
+/** 禅道模块定义，由多个动作组成。 */
+export interface ModuleDefinition {
+    /** 模块名称，例如 `product`、`bug`。 */
+    name: ModuleName;
+    /** 面向用户展示的模块名称。 */
+    display?: string;
+    /** 模块说明。 */
+    description?: string;
+    /** 模块支持的动作集合。 */
+    actions: ModuleAction[];
+}
+/** 将模块动作和参数解析后的可执行请求描述。 */
+export interface ResolvedModuleCommand {
+    /** 模块名称。 */
+    module: string;
+    /** 匹配到的动作定义。 */
+    action: ModuleAction;
+    /** 原始调用参数。 */
+    params: Record<string, unknown>;
+    /** 已替换路径参数后的 API 路径。 */
+    path: string;
+    /** 已组装的查询参数。 */
+    query?: Record<string, string | number>;
+    /** 已组装的请求体。 */
+    data?: Record<string, unknown>;
+    /** 从 `id` 或 `{module}ID` 推断出的对象 ID。 */
+    id?: number;
+}

package/dist/types/index.js

@@ -0,0 +1 @@
+export {};

package/dist/utils/index.d.ts

@@ -0,0 +1,2 @@
+export declare function getNestedValue(obj: unknown, path: string): unknown;
+export declare function asArray<T>(value: T | T[]): T[];