zentao-api 0.2.0-beta.2 → 0.2.1

package/dist/request/index.js

@@ -4,13 +4,25 @@ 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');
+    const [moduleName, actionName] = name.split('/');
+    // 如果没有指定 actionName
+    if (!actionName?.length) {
+        return {
+            moduleName,
+            actionName: 'list',
+        };
+    }
+    // 如果 actionName 为数值
+    if (Number.isInteger(Number(actionName))) {
+        return {
+            moduleName,
+            actionName: 'get',
+            id: Number(actionName),
+        };
     }
     return {
-        moduleName: name.slice(0, index),
-        actionName: name.slice(index + 1),
+        moduleName,
+        actionName,
     };
 }
 /** 将禅道原始响应归一化为稳定的 ResponseData 结构。 */
@@ -29,7 +41,7 @@ function normalizeResponse(command, raw, limit) {
     return {
         status,
         message: typeof record.message === 'string' ? record.message : undefined,
-        data,
+        data: data,
         pager: pager ? {
             total: Number(pager.recTotal),
             page: Number(pager.pageID),
@@ -41,6 +53,15 @@ function normalizeResponse(command, raw, limit) {
  * 按模块动作名请求禅道 API。
  *
  * 选项优先级为：本次调用 options > 全局 options > 客户端默认值。
+ * 当响应 `status` 为 `"fail"` 时，默认按原样返回；若 `options.throwOnFail`
+ * 或全局 `throwOnFail` 为真，则改为抛出 `E_API_FAILED`。
+ *
+ * @typeParam T 期望的 `data` 字段类型；不传时为 `unknown`，调用方需要自行收窄。
+ * @param name - 模块动作名，例如 `product/list`。
+ * @param params - 请求参数。
+ * @param options - 请求选项。
+ * @returns 归一化后的禅道 API 响应。
+ * @throws {ZentaoError} 传输层错误、参数缺失或 `throwOnFail` 启用时的业务失败。
  */
 export async function request(name, params = {}, options = {}) {
     const globals = getGlobalOptions();
@@ -48,11 +69,15 @@ export async function request(name, params = {}, options = {}) {
     if (!client) {
         throw new ZentaoError('E_NO_GLOBAL_CLIENT');
     }
-    const { moduleName, actionName } = splitRequestName(name);
+    const { moduleName, actionName, id } = splitRequestName(name);
     const module = getModule(moduleName);
     // recPerPage 是最常用的列表参数，允许在全局或本次调用中统一覆盖。
     const recPerPage = params.recPerPage ?? options.recPerPage ?? globals.recPerPage;
-    const mergedParams = recPerPage === undefined ? params : { ...params, recPerPage };
+    const mergedParams = {
+        ...(id !== undefined ? { id } : {}),
+        ...params,
+        ...(recPerPage !== undefined ? { recPerPage } : {}),
+    };
     const command = resolveModuleCommand(module, actionName, mergedParams);
     const raw = await client.request(command.path, {
         method: String(command.action.method).toUpperCase(),
@@ -61,5 +86,9 @@ export async function request(name, params = {}, options = {}) {
         timeout: options.timeout ?? globals.timeout,
         insecure: options.insecure ?? globals.insecure,
     });
-    return normalizeResponse(command, raw, options.limit ?? globals.limit);
+    const response = normalizeResponse(command, raw, options.limit ?? globals.limit);
+    if (response.status === 'fail' && (options.throwOnFail ?? globals.throwOnFail)) {
+        throw new ZentaoError('E_API_FAILED', { message: response.message ?? '' }, response);
+    }
+    return response;
 }

package/dist/types/index.d.ts

@@ -24,6 +24,8 @@ export interface GlobalOptions {
     insecure?: boolean;
     /** 是否在登录成功后把账号、Token 和配置持久化为本地 profile。 */
     persistProfiles?: boolean;
+    /** 当禅道服务端返回 `{ status: "fail" }` 时是否抛出 `E_API_FAILED`，默认 false。 */
+    throwOnFail?: boolean;
 }
 /** SDK 支持的 HTTP 方法。 */
 export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'DELETE';
@@ -32,7 +34,7 @@ export interface ClientRequestOptions {
     /** HTTP 方法，默认 `GET`。 */
     method?: HttpMethod;
     /** JSON 请求体；`GET` 请求会忽略该字段。 */
-    body?: Record<string, unknown>;
+    body?: unknown;
     /** URL 查询参数；`undefined` 值会被跳过。 */
     query?: Record<string, string | number | boolean | undefined>;
     /** 单次请求超时时间，优先级高于全局和客户端默认值。 */
@@ -52,15 +54,20 @@ export interface RequestOptions {
     timeout?: number;
     /** 本次调用 TLS 跳过证书验证选项；仅 Node.js 运行时支持。 */
     insecure?: boolean;
+    /**
+     * 当禅道服务端返回 `{ status: "fail" }` 时是否抛出 `E_API_FAILED`。
+     * 不传时回落到全局 `throwOnFail`，默认 false（保留原始失败响应）。
+     */
+    throwOnFail?: boolean;
 }
 /** 高阶 `request()` 归一化后的返回数据。 */
-export interface ResponseData {
+export interface ResponseData<T = unknown> {
     /** 禅道服务端状态；非标准响应会按成功响应包装到 `data`。 */
     status: 'success' | 'fail';
     /** 禅道服务端返回的消息。 */
     message?: string;
     /** 根据模块动作 `resultGetter` 提取后的业务数据。 */
-    data?: any;
+    data?: T;
     /** 统一分页信息。 */
     pager?: {
         /** 总记录数。 */
@@ -127,8 +134,6 @@ export interface ZentaoProfileConfig {
     defaultRecPerPage?: number;
     /** 是否跳过 TLS 证书验证；仅 Node.js 运行时支持。 */
     insecure?: boolean;
-    /** 是否将对象属性中的 HTML 转换为 Markdown。 */
-    htmlToMarkdown?: boolean;
     /** 请求超时时间，单位毫秒。 */
     timeout?: number;
     /** 是否在批量操作出错时停止执行后续操作。 */

package/dist/utils/index.js

@@ -8,7 +8,18 @@ export function normalizeSiteUrl(baseUrl) {
     const trimmed = baseUrl.trim().replace(/\/+$/, '');
     if (!trimmed)
         throw new ZentaoError('E_INVALID_BASE_URL');
-    return trimmed.replace(/\/api\.php\/v2$/i, '');
+    const siteUrl = trimmed.replace(/\/api\.php\/v2$/i, '');
+    let parsed;
+    try {
+        parsed = new URL(siteUrl);
+    }
+    catch {
+        throw new ZentaoError('E_INVALID_BASE_URL');
+    }
+    if (!['http:', 'https:'].includes(parsed.protocol) || parsed.search || parsed.hash) {
+        throw new ZentaoError('E_INVALID_BASE_URL');
+    }
+    return parsed.toString().replace(/\/+$/, '');
 }
 export function getNestedValue(obj, path) {
     const keys = path.split('.');

package/dist/version.d.ts

@@ -1,2 +1,12 @@
+/**
+ * 构建标识，由构建脚本通过 `__ZENTAO_API_BUILD__` 注入。
+ *
+ * 通常是 commit hash 或 CI 构建号；本地 `tsc` 直接编译时回落为 `'development'`。
+ */
 export declare const BUILD: string;
+/**
+ * SDK 版本号，由构建脚本通过 `__ZENTAO_API_VERSION__` 注入。
+ *
+ * 通常等于 `package.json` 的 `version` 字段；本地 `tsc` 直接编译时回落为 `'0.0.0-dev'`。
+ */
 export declare const VERSION: string;

package/dist/version.js

@@ -1,4 +1,14 @@
-const fallbackBuild = "2026-05-11T13:46:14.715Z";
-const fallbackVersion = "0.2.0-beta.2";
+const fallbackBuild = "2026-06-23T08:50:58.737Z";
+const fallbackVersion = "0.2.1";
+/**
+ * 构建标识，由构建脚本通过 `__ZENTAO_API_BUILD__` 注入。
+ *
+ * 通常是 commit hash 或 CI 构建号；本地 `tsc` 直接编译时回落为 `'development'`。
+ */
 export const BUILD = typeof __ZENTAO_API_BUILD__ === 'string' ? __ZENTAO_API_BUILD__ : fallbackBuild;
+/**
+ * SDK 版本号，由构建脚本通过 `__ZENTAO_API_VERSION__` 注入。
+ *
+ * 通常等于 `package.json` 的 `version` 字段；本地 `tsc` 直接编译时回落为 `'0.0.0-dev'`。
+ */
 export const VERSION = typeof __ZENTAO_API_VERSION__ === 'string' ? __ZENTAO_API_VERSION__ : fallbackVersion;

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "zentao-api",
-  "version": "0.2.0-beta.2",
+  "version": "0.2.1",
   "type": "module",
   "description": "Browser and Node.js SDK for ZenTao API",
   "license": "MIT",
   "author": "Sun Hao <sunhao@chandao.com>",
   "repository": {
     "type": "git",
-    "url": "https://github.com/catouse/zentao-api"
+    "url": "https://github.com/easysoft/zentao-api"
   },
   "keywords": [
     "zentao",
@@ -18,12 +18,21 @@
   ],
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
+  "sideEffects": [
+    "./dist/browser-global.js",
+    "./dist/browser/zentao-api.global.js"
+  ],
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
+      "browser": "./dist/browser.js",
       "import": "./dist/index.js"
     },
-    "./browser": "./dist/browser/zentao-api.global.js",
+    "./browser": {
+      "types": "./dist/browser.d.ts",
+      "import": "./dist/browser.js"
+    },
+    "./browser/global": "./dist/browser/zentao-api.global.js",
     "./package.json": "./package.json"
   },
   "files": [
@@ -50,13 +59,9 @@
     "check": "bun run test:coverage && bun run typecheck && bun run typecheck:tests && bun run registry:check && bun run build && bun run smoke:node && bun run smoke:package",
     "prepublishOnly": "bun run check"
   },
-  "dependencies": {
-    "turndown": "^7.2.0"
-  },
   "devDependencies": {
     "@types/bun": "^1.3.13",
     "@types/node": "^24.10.0",
-    "@types/turndown": "^5.0.5",
     "typedoc": "^0.28.19",
     "typedoc-plugin-markdown": "^4.11.0",
     "typedoc-vitepress-theme": "^1.1.2",

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

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

package/dist/misc/browser-global.js

@@ -1,8 +0,0 @@
-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';