@seayoo-web/captcha 1.0.1 → 2.0.0

package/README.md

@@ -1 +1,52 @@
-# Captcha
+# @seayoo-web/captcha
+
+腾讯天御验证码（Captcha）前端封装，对接 [腾讯云验证码](https://cloud.tencent.com/document/product/1110/36841)。
+
+负责动态加载腾讯 `TJCaptcha.js`、弹出验证码、并把结果归一化返回。**不包含**「向自家服务端拉取验证码开关 / 配置」这类业务编排，`captchaAppId` 等由调用方（通常来自服务端下发）传入。
+
+## 用法
+
+```ts
+import { TencentCaptchaAgent } from "@seayoo-web/captcha";
+
+// 可选：首屏渲染完成后提前预热 SDK，减少首次弹窗延迟
+TencentCaptchaAgent.preloadSDK();
+
+const agent = new TencentCaptchaAgent({
+  captchaAppId, // 验证码应用 id，通常由服务端下发
+  // aidEncrypted、userLanguage、needFeedBack、enableDarkMode 可选
+});
+
+const result = await agent.verify();
+if (result.code === 0) {
+  // 验证通过，用 result.ticket / result.randstr 交服务端二次校验
+} else if (result.code === 2) {
+  // 用户主动关闭
+} else {
+  // 验证失败或容灾（code === 1001，ticket 为 trerror_ 前缀容灾票据）
+}
+```
+
+## API
+
+### `new TencentCaptchaAgent(option)`
+
+- `option.captchaAppId` — 必填，验证码应用 id。
+- 其余字段（`aidEncrypted` / `userLanguage` / `needFeedBack` / `enableDarkMode`）透传给腾讯 SDK。
+
+### `agent.verify(): Promise<CaptchaResult>`
+
+触发一次人机验证。**不会抛错**：SDK 加载失败、用户关闭、超时（3 分钟）都会以 `CaptchaResult` 返回，其中加载 / 运行异常返回 `trerror_` 前缀的容灾票据（`code === 1001`），交由服务端识别降级。
+
+`CaptchaResult`：
+
+| 字段      | 说明                                                       |
+| --------- | ---------------------------------------------------------- |
+| `code`    | `0` 通过 / `2` 用户关闭 / `1001` 容灾 / 其它 失败          |
+| `ticket`  | 验证票据（`code === 0` 时有效）                            |
+| `randstr` | 本次验证随机串                                             |
+| `message` | 错误信息（正常时为空串）                                   |
+
+### `TencentCaptchaAgent.preloadSDK()`
+
+提前加载腾讯 js sdk。建议在首屏渲染完成后调用——过早加载会在 Safari 上因样式未就绪而闪现一个很大的图标。

package/dist/index.js

@@ -1,54 +1,59 @@
-import { useConsole as r, EventBus as c, usePromise as d, loadJS as h } from "@seayoo-web/utils";
-const p = r("CaptchaSDK");
-let e;
-async function s() {
-  return "TencentCaptcha" in window && window.TencentCaptcha ? window.TencentCaptcha : e ? await e : (e = h("https://turing.captcha.qcloud.com/TJCaptcha.js").then(() => window.TencentCaptcha ?? null), await e);
+import { loadJS as e, useConsole as t } from "@seayoo-web/utils";
+//#region src/tencent.ts
+var n = t("CaptchaSDK"), r = "https://turing.captcha.qcloud.com/TJCaptcha.js", i = 6e4 * 3, a = null;
+function o() {
+	return typeof document > "u" || typeof window > "u" ? Promise.resolve(null) : window.TencentCaptcha ? Promise.resolve(window.TencentCaptcha) : (a ||= e(r).then((e) => {
+		let t = e ? window.TencentCaptcha ?? null : null;
+		return t || (a = null), t;
+	}), a);
 }
-class u {
-  sdk = null;
-  isReady = !1;
-  event = new c();
-  /** 提前加载腾讯 js sdk */
-  static preloadSDK() {
-    s();
-  }
-  /**
-   * 创建验证码实例，创建后立即开始加载腾讯天御 SDK
-   */
-  constructor(a) {
-    s().then((t) => {
-      if (!t)
-        p.error("Load TencentCaptcha Error!");
-      else {
-        const { captchaAppId: o, ...i } = a;
-        this.sdk = new t(
-          o,
-          (n) => {
-            this.event.emit("done", n);
-          },
-          {
-            ...i,
-            ready: (n) => {
-              this.isReady = !0, this.event.emit("ready", n);
-            }
-          }
-        );
-      }
-    });
-  }
-  async ready() {
-    if (this.isReady)
-      return;
-    const { promise: a, resolve: t } = d();
-    this.event.once("ready", t), await a;
-  }
-  async show() {
-    await this.ready(), this.sdk?.show();
-  }
-  async destroy() {
-    await this.ready(), this.sdk?.destroy();
-  }
+function s(e, t) {
+	return {
+		code: 1001,
+		ticket: `trerror_1001_${e}_${Math.floor(Date.now() / 1e3)}`,
+		randstr: `@${Math.random().toString(36).slice(2)}`,
+		message: t
+	};
 }
-export {
-  u as TencentCaptchaAgent
+var c = class {
+	static preloadSDK() {
+		o();
+	}
+	constructor(e) {
+		this.option = e;
+	}
+	async verify() {
+		let { captchaAppId: e, ...t } = this.option, r = await o();
+		if (!r) return n.error("Load TencentCaptcha Error!"), s(e, "Captcha init Error");
+		try {
+			return await new Promise((n, a) => {
+				let o = new r(e, (e) => {
+					s(), n({
+						code: e.errorCode || e.ret,
+						ticket: e.ticket,
+						randstr: e.randstr,
+						message: e.errorMessage ?? ""
+					});
+				}, t);
+				function s() {
+					window.removeEventListener("resize", c), clearTimeout(l);
+				}
+				function c() {
+					let e = document.getElementById("tcaptcha_transform_dy");
+					if (!e) return;
+					let t = e.style.opacity;
+					t === "1" ? o.show() : t === "0" && (o.destroy(), s(), a(/* @__PURE__ */ Error("Captcha is hidden")));
+				}
+				window.addEventListener("resize", c);
+				let l = setTimeout(() => {
+					o.destroy(), s(), a(/* @__PURE__ */ Error("Captcha Timeout"));
+				}, i);
+				o.show();
+			});
+		} catch (t) {
+			return s(e, t instanceof Error ? t.message : `Captcha Error: ${String(t)}`);
+		}
+	}
 };
+//#endregion
+export { c as TencentCaptchaAgent };

package/package.json

@@ -1,42 +1,47 @@
 {
   "name": "@seayoo-web/captcha",
+  "version": "2.0.0",
   "description": "captcha agent",
-  "version": "1.0.1",
-  "type": "module",
-  "main": "./dist/index.js",
-  "module": "./dist/index.js",
+  "keywords": [
+    "captcha"
+  ],
+  "license": "MIT",
+  "author": "web@seayoo.com",
   "source": "./index.ts",
-  "types": "./types/index.d.ts",
   "files": [
     "dist",
     "types",
     "README.md"
   ],
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./types/index.d.ts",
   "publishConfig": {
     "access": "public"
   },
-  "engines": {
-    "node": ">=22"
-  },
-  "keywords": [
-    "captcha"
-  ],
-  "author": "web@seayoo.com",
-  "license": "MIT",
   "devDependencies": {
-    "@seayoo-web/scripts": "^3.0.0",
-    "@seayoo-web/tsconfig": "^1.0.5",
-    "@seayoo-web/utils": "^4.0.2"
+    "@vitest/coverage-istanbul": "^4.1.4",
+    "happy-dom": "^13.10.1",
+    "vitest": "^4.1.4",
+    "@seayoo-web/scripts": "^4.3.10",
+    "@seayoo-web/utils": "^4.5.4",
+    "@seayoo-web/tsconfig": "^1.0.6"
   },
   "peerDependencies": {
-    "@seayoo-web/utils": "^4.0.2"
+    "@seayoo-web/utils": "^4.5.4"
+  },
+  "engines": {
+    "node": ">=22"
   },
   "scripts": {
     "prebuild": "pnpm -F utils build",
-    "build": "vite build && tsc --emitDeclarationOnly",
+    "build": "vite build && tsc --build --emitDeclarationOnly",
     "type-check": "tsc --noEmit",
-    "lint": "eslint ./src/**/*.ts",
-    "lint:fix": "eslint  \"./src/**/*.{ts,js}\" --fix",
-    "prepublish": "pnpm lint:fix && pnpm build"
+    "test": "vitest --dom",
+    "coverage": "vitest run --coverage",
+    "lint": "oxlint -c ../../oxlint.config.mjs",
+    "lint:fix": "oxlint -c ../../oxlint.config.mjs --fix"
   }
 }

package/types/src/tencent.d.ts

@@ -1,19 +1,18 @@
-/** spell-checker:ignore trerror_, randstr */
-/** 对腾讯的sdk做简单声明 */
+/** spell-checker:ignore trerror_, randstr, tcaptcha */
+/** 对腾讯的 sdk 做简单声明 */
 declare global {
     interface Window {
         TencentCaptcha?: TencentCaptchaSDK;
     }
 }
-interface VerifyResult {
+/** 腾讯 sdk 回调返回的原始结构 */
+interface TencentVerifyResponse {
     /**
-     * 验证结果。等于 2 时表示用户关闭，不等于 0 表示失败
+     * 验证结果。0 = 成功；2 = 用户主动关闭；其它 = 失败
      */
     ret: number;
     /**
-     * 验证票据，验证成功的票据，当且仅当 ret = 0 时 ticket 有值
-     *
-     * 请求验证码发生错误，验证码自动返回 trerror_ 前缀的容灾票据
+     * 验证票据，ret = 0 时有值；客户端发生异常时返回 trerror_ 前缀的容灾票据
      */
     ticket: string;
     /**
@@ -21,108 +20,99 @@ interface VerifyResult {
      */
     randstr: string;
     /**
-     * 自定义透传参数
-     */
-    bizState?: unknown;
-    /**
-     *  验证码校验接口耗时（ms）
+     * 客户端异常错误码，出现时仍可能返回可用票据
      */
-    verifyDuration: number;
+    errorCode?: number;
     /**
-     *  操作校验成功耗时（用户动作+校验完成）(ms)
+     * 客户端异常错误信息
      */
-    actionDuration: number;
-    /**
-     * 链路 sid
-     */
-    sid: string;
-}
-interface TencentCaptchaSDK {
-    new (captchaAppId: string, callback: (result: VerifyResult) => void, option?: Omit<TencentCaptchaOption, "captchaAppId"> & {
-        showFn?: () => void;
-    }): TencentCaptchaSDKIns;
-}
-interface TencentCaptchaSDKIns {
-    /** 显示验证码，可以反复调用 */
-    show(): void;
-    /** 隐藏验证码，可以反复调用 */
-    destroy(): void;
-    /** 获取验证成功后的 ticket */
-    getTicket(): {
-        CaptchaAppId: string;
-        ticket: string;
-    };
+    errorMessage?: string;
 }
+/** 透传给腾讯 sdk 的配置项 */
 interface TencentCaptchaOption {
-    captchaAppId: string;
-    /**
-     * 验证码相关资源加载完成的回调，回调参数为验证码实际的宽高（单位：px）
-     *
-     * 该参数仅为查看验证码宽高使用
-     */
-    ready?: (info: {
-        sdkView: {
-            width: number;
-            height: number;
-        };
-    }) => void;
     /**
-     * 开启自适应深夜模式或强制深夜模式
-     *
-     * - true 开启自适应深夜模式
-     * - "force" 强制深夜模式
+     * 指定验证码提示文案的语言，优先级高于控制台配置。大小写不敏感。
      */
-    enableDarkMode?: boolean | "force";
+    userLanguage?: string;
     /**
-     * 仅支持移动端原生 webview 调用时传入，用来设置验证码 loading 加载弹窗的大小
-     *
-     * 💡注意，此参数调整的并非验证码弹窗大小
+     * CaptchaAppId 加密校验串，详见 [CaptchaAppid 加密校验能力接入指引](https://cloud.tencent.com/document/product/1110/36841#c6a3e517-4962-4932-9bf8-9fb10fd03166)
      */
-    sdkOpts?: {
-        width: number;
-        height: number;
-    };
+    aidEncrypted?: string;
     /**
      * 隐藏帮助按钮或自定义帮助按钮链接
      */
     needFeedBack?: boolean | `https://${string}`;
     /**
-     * 是否在验证码加载过程中显示 loading 框。默认 true
+     * 开启自适应深夜模式或强制深夜模式
      *
-     * 💡 如果隐藏 loading，则对应的 loading 半透蒙层也会一并隐藏
-     */
-    loading?: boolean;
-    /**
-     * 指定验证码提示文案的语言，优先级高于控制台配置。大小写不敏感。
+     * - true 开启自适应深夜模式
+     * - "force" 强制深夜模式
      */
-    userLanguage?: string;
+    enableDarkMode?: boolean | "force";
+}
+interface TencentCaptchaSDK {
+    new (captchaAppId: string, callback: (res: TencentVerifyResponse) => void, option?: TencentCaptchaOption): TencentCaptchaSDKIns;
+}
+interface TencentCaptchaSDKIns {
+    /** 显示验证码，可反复调用 */
+    show(): void;
+    /** 重新加载验证码 */
+    reload(): void;
+    /** 销毁验证码，可反复调用 */
+    destroy(): void;
+}
+/** 归一化后的验证结果 */
+export interface CaptchaResult {
     /**
-     * 验证码展示方式，默认 "popup"
+     * 结果码
      *
-     * - popup 弹出式，以浮层形式居中弹出展示验证码
-     * - embed 嵌入式，以嵌入指定容器元素中的方式展示验证码
-     */
-    type?: "popup" | "embed";
-    /**
-     * CaptchaAppId 加密校验串，详见 [CaptchaAppid 加密校验能力接入指引](https://cloud.tencent.com/document/product/1110/36841#c6a3e517-4962-4932-9bf8-9fb10fd03166)
+     * - 0    验证通过，ticket 有效
+     * - 2    用户主动关闭验证码
+     * - 1001 容灾（加载失败 / 超时 / 异常关闭），ticket 为 trerror_ 前缀票据
+     * - 其它 验证失败
      */
-    aidEncrypted?: string;
+    code: number;
+    ticket: string;
+    randstr: string;
+    message: string;
+}
+/** {@link TencentCaptchaAgent} 构造参数 */
+export interface TencentCaptchaAgentOption extends TencentCaptchaOption {
+    /** 验证码应用 id，通常由服务端下发 */
+    captchaAppId: string;
 }
 /**
  * 腾讯天御验证码
+ *
+ * https://cloud.tencent.com/document/product/1110/36841
+ *
+ * @example
+ * ```ts
+ * // 建议在首屏渲染后提前预热，减少首次弹窗延迟
+ * TencentCaptchaAgent.preloadSDK();
+ *
+ * const agent = new TencentCaptchaAgent({ captchaAppId });
+ * const result = await agent.verify();
+ * if (result.code === 0) {
+ *   // 用 result.ticket / result.randstr 去服务端校验
+ * }
+ * ```
  */
 export declare class TencentCaptchaAgent {
-    private sdk;
-    private isReady;
-    private event;
-    /** 提前加载腾讯 js sdk */
+    private readonly option;
+    /**
+     * 提前加载腾讯 js sdk。
+     *
+     * 建议在首屏渲染完成后调用：过早加载会在 Safari 上因样式未就绪而闪现一个很大的图标。
+     */
     static preloadSDK(): void;
+    constructor(option: TencentCaptchaAgentOption);
     /**
-     * 创建验证码实例，创建后立即开始加载腾讯天御 SDK
+     * 触发一次人机验证，返回归一化结果。
+     *
+     * 该方法**不会抛错**：SDK 加载失败、用户关闭、超时等都会以 {@link CaptchaResult} 返回，
+     * 其中加载/运行异常返回 `trerror_` 前缀的容灾票据（`code === 1001`），交由服务端降级。
      */
-    constructor(option: Omit<TencentCaptchaOption, "ready">);
-    ready(): Promise<void>;
-    show(): Promise<void>;
-    destroy(): Promise<void>;
+    verify(): Promise<CaptchaResult>;
 }
 export {};