@jayfong/x-utils 3.3.0 → 3.4.0

package/lib/runner.mjs

@@ -1,36 +1,52 @@
 import { XFs } from "./fs.mjs";
-import inquirer from "inquirer";
 import { ms, wait } from "vtils";
 // src/runner.ts
 /**
 * 带配置持久化与失败重试能力的交互式运行器。
 *
-* 行为概要：
-* 1. 启动时读取历史配置，作为本次提问默认值；
-* 2. 用户确认后回写配置文件，保证下次可复用；
-* 3. 执行业务函数，成功即退出；
-* 4. 失败时按 `delay` 等待后重试，直到成功或出现不可恢复错误。
+* 典型用法：CLI 启动时先询问用户配置并落盘复用，随后循环执行业务函数，
+* 失败时自动等待并重试。
+*
+* 运行流程（详见 {@link XRunner.run}）：
+* 1. 确保配置文件存在（缺失时自动创建）；
+* 2. 读取历史配置，作为本次提问默认值；
+* 3. 用户确认后回写配置文件，保证下次可复用；
+* 4. 执行业务函数，成功即退出；
+* 5. 失败时按 `delay` 等待后重试，直到成功或出现不可恢复错误。
 */
 var XRunner = class {
 	options;
+	/**
+	* 创建运行器实例。
+	*
+	* @param options 运行配置，各字段语义见 {@link XRunnerOptions}。
+	*/
 	constructor(options) {
 		this.options = options;
 	}
 	/**
 	* 启动运行器。
+	*
+	* 依次执行：确保配置文件存在 → 读取历史配置 → 通过 `provideConfig`
+	* 收集本次配置 → 写回配置文件 → 循环执行 `run`。
+	*
+	* 边界与异常说明：
+	* - 配置文件缺失时由 `XFs.ensureFile` 自动补齐目录并创建空文件；
+	* - 配置内容非法（非 JSON）时 `readJson(..., { throws: false })` 返回
+	*   `null`，经 `|| {}` 兜底为空对象，不阻断启动；
+	* - `provideConfig` 抛错或写回配置失败时，错误直接向外抛出，不进入重试；
+	* - `run` 抛错时进入重试分支：`retryCount` 自增后计算等待时长，打印
+	*   错误与重试提示，等待后重新执行；
+	* - `delay` 为函数时按 `retryCount`（从 `1` 开始）动态计算；其返回值
+	*   若无法被 `ms` 解析，`ms` 会抛错并终止重试循环。
+	*
+	* @returns 业务函数成功后 resolve 为 `undefined`；仅在成功或抛出
+	*          不可恢复错误时返回，否则持续重试。
 	*/
 	async run() {
 		await XFs.ensureFile(this.options.configFile);
 		const savedConfig = await XFs.readJson(this.options.configFile, { throws: false }) || {};
-		const questions = this.options.questions.map((item) => {
-			const defaultValue = savedConfig[item.name];
-			if (defaultValue === void 0) return item;
-			return {
-				...item,
-				default: defaultValue
-			};
-		});
-		const config = await inquirer.prompt(questions);
+		const config = await this.options.provideConfig(savedConfig);
 		await XFs.writeJson(this.options.configFile, config, { spaces: 2 });
 		let retryCount = 0;
 		while (true) try {

package/lib/sensitive_words.d.mts

@@ -0,0 +1,82 @@
+export interface XSensitiveWordsOptions {
+  /**
+   * 敏感词列表。
+   *
+   * 支持三种写法：
+   * - 普通文本，如 `赌博`：做大小写不敏感的子串匹配；
+   * - `<手机号>`：匹配 11 位大陆手机号；
+   * - 正则表达式，以 `/` 开头且以 `/` 结尾，如 `/[色情]+/`：
+   *   会去除首尾的 `/` 后编译为正则，对归一化后的文本执行 `test`。
+   *
+   * 构造时会将每个词统一转为小写并去重，因此列表中重复或
+   * 大小写不同的词不会影响匹配结果。
+   */
+  words: string[];
+}
+/**
+ * `XSensitiveWords.validate` 的返回结果。
+ */
+export interface XSensitiveWordsValidateResult {
+  /** 是否通过校验，`true` 表示未命中任何敏感词。 */
+  pass: boolean;
+  /**
+   * 命中的敏感词列表。
+   *
+   * - 默认（`every` 为假）最多包含一个词，命中即停止；
+   * - 传入 `every` 为真时，包含命中的全部词；
+   * - 未命中时为空数组。
+   */
+  words: string[];
+}
+/**
+ * 敏感词校验工具。
+ *
+ * 用于校验文本是否包含敏感词，支持普通词、`<手机号>` 与正则三种
+ * 敏感词写法（见 {@link XSensitiveWordsOptions.words}）。
+ *
+ * 校验前会先对文本做归一化处理，以提升命中率：
+ * 1. 全角转半角（如 `Ａ` → `A`）；
+ * 2. 移除非单词字符（保留中文、字母、数字、下划线等）；
+ * 3. 移除空白字符；
+ * 4. 转小写；
+ * 5. 叠词归一（除字母数字外，连续重复字符折叠为单个），
+ *    以支持 `qq`、手机号等场景。
+ *
+ * @example
+ * const sw = new XSensitiveWords({
+ *   words: ['赌博', '<手机号>', '/[色情]+/'],
+ * });
+ *
+ * await sw.validate('这是一条赌博信息');
+ * // { pass: false, words: ['赌博'] }
+ */
+export declare class XSensitiveWords {
+  private sensitiveWords;
+  constructor(options: XSensitiveWordsOptions);
+  /**
+   * 文本归一化。
+   *
+   * 依次执行：全角转半角 → 移除非单词字符 → 移除空白字符 → 转小写
+   * → 叠词归一。与构造时仅做“转小写 + 去重”的敏感词列表配合，
+   * 实现大小写不敏感、忽略格式干扰的匹配。
+   */
+  private transform;
+  /**
+   * 验证文本是否包含敏感词。
+   *
+   * 对文本做归一化后，按顺序遍历敏感词：
+   * - `<手机号>`：用手机号正则测试；
+   * - `/.../` 形式的正则词：编译后测试；
+   * - 其余普通词：做子串包含判断。
+   *
+   * @param text 待校验的文本。
+   * @param every 是否返回命中的全部敏感词；默认为 `false`，命中一个即停止。
+   * @returns 校验结果，`pass` 表示是否通过，`words` 为命中的敏感词。
+   *
+   * @example
+   * const sw = new XSensitiveWords({ words: ['赌博', '色情'] });
+   * await sw.validate('赌博与色情', true);
+   * // { pass: false, words: ['赌博', '色情'] }
+   */
+  validate(text: string, every?: boolean): Promise<XSensitiveWordsValidateResult>;
+}

package/lib/sensitive_words.mjs

@@ -0,0 +1,73 @@
+import { memoize, removeBlankChars, removeNonWordChars, toHalfWidthString, uniq } from "vtils";
+import { phoneNumberRegExpBuilder } from "vtils/regexp";
+// src/sensitive_words.ts
+const phoneNumberRegExp = phoneNumberRegExpBuilder.build();
+const toRegExp = memoize((re) => new RegExp(re.substring(1, re.length - 1)), (re) => re);
+/**
+* 敏感词校验工具。
+*
+* 用于校验文本是否包含敏感词，支持普通词、`<手机号>` 与正则三种
+* 敏感词写法（见 {@link XSensitiveWordsOptions.words}）。
+*
+* 校验前会先对文本做归一化处理，以提升命中率：
+* 1. 全角转半角（如 `Ａ` → `A`）；
+* 2. 移除非单词字符（保留中文、字母、数字、下划线等）；
+* 3. 移除空白字符；
+* 4. 转小写；
+* 5. 叠词归一（除字母数字外，连续重复字符折叠为单个），
+*    以支持 `qq`、手机号等场景。
+*
+* @example
+* const sw = new XSensitiveWords({
+*   words: ['赌博', '<手机号>', '/[色情]+/'],
+* });
+*
+* await sw.validate('这是一条赌博信息');
+* // { pass: false, words: ['赌博'] }
+*/
+var XSensitiveWords = class {
+	sensitiveWords = [];
+	constructor(options) {
+		this.sensitiveWords = uniq(options.words.map((word) => word.toLowerCase()));
+	}
+	/**
+	* 文本归一化。
+	*
+	* 依次执行：全角转半角 → 移除非单词字符 → 移除空白字符 → 转小写
+	* → 叠词归一。与构造时仅做“转小写 + 去重”的敏感词列表配合，
+	* 实现大小写不敏感、忽略格式干扰的匹配。
+	*/
+	transform(text) {
+		return removeBlankChars(removeNonWordChars(toHalfWidthString(text))).toLowerCase().replace(/([^a-zA-Z0-9])\1+/g, "$1");
+	}
+	/**
+	* 验证文本是否包含敏感词。
+	*
+	* 对文本做归一化后，按顺序遍历敏感词：
+	* - `<手机号>`：用手机号正则测试；
+	* - `/.../` 形式的正则词：编译后测试；
+	* - 其余普通词：做子串包含判断。
+	*
+	* @param text 待校验的文本。
+	* @param every 是否返回命中的全部敏感词；默认为 `false`，命中一个即停止。
+	* @returns 校验结果，`pass` 表示是否通过，`words` 为命中的敏感词。
+	*
+	* @example
+	* const sw = new XSensitiveWords({ words: ['赌博', '色情'] });
+	* await sw.validate('赌博与色情', true);
+	* // { pass: false, words: ['赌博', '色情'] }
+	*/
+	async validate(text, every) {
+		text = this.transform(text);
+		const words = [];
+		for (const word of this.sensitiveWords) if (word === "<手机号>" ? phoneNumberRegExp.test(text) : word[0] === "/" && word[word.length - 1] === "/" ? toRegExp(word).test(text) : text.includes(word)) {
+			words.push(word);
+			if (!every) break;
+		}
+		return {
+			pass: !words.length,
+			words
+		};
+	}
+};
+export { XSensitiveWords };

package/lib/sms.d.mts

@@ -0,0 +1,133 @@
+/**
+ * 短信服务提供商。
+ */
+export declare enum SmsServiceProvider {
+  /** 腾讯云短信。 */
+  TencentCloud = "TencentCloud"
+}
+/**
+ * `XSms` 的构造配置。
+ */
+export interface XSmsOptions {
+  /**
+   * 短信服务提供商。
+   *
+   * 目前仅支持 {@link SmsServiceProvider.TencentCloud}。实际发送时以
+   * {@link XSmsSendPayload.provider} 为准进行路由，本字段作为实例级默认
+   * 配置保留，供后续扩展多提供商时使用。
+   */
+  provider: SmsServiceProvider;
+  /** 云厂商 API 密钥 SecretId（腾讯云访问管理 CAM 中获取）。 */
+  secretId: string;
+  /** 云厂商 API 密钥 SecretKey（腾讯云访问管理 CAM 中获取）。 */
+  secretKey: string;
+  /** 短信应用 ID（腾讯云短信控制台中的应用 SdkAppId）。 */
+  appId: string;
+}
+/**
+ * `XSms.send` 的发送参数。
+ */
+export interface XSmsSendPayload {
+  /**
+   * 本次发送实际使用的短信服务提供商。
+   *
+   * `send` 依据该字段路由到对应厂商的实现；目前仅支持
+   * {@link SmsServiceProvider.TencentCloud}。
+   */
+  provider: SmsServiceProvider;
+  /** 短信签名，必须是已在对应厂商控制台审核通过的签名内容（非签名 ID）。 */
+  signature: string;
+  /** 短信模板 ID，必须是已在对应厂商控制台审核通过的模板。 */
+  templateId: string;
+  /**
+   * 模板变量值列表。
+   *
+   * 按顺序对应模板中的变量，个数需与模板变量个数一致；模板无变量时
+   * 传空数组即可。例如模板为「您的验证码为 {1}，{2} 分钟内有效」时，
+   * 传 `['123456', '5']`。
+   */
+  templateParamValues: string[];
+  /**
+   * 接收短信的手机号。
+   *
+   * 支持两种写法：
+   * - 以 `+` 开头：视为 E.164 国际号码，原样使用，如 `+8613800138000`；
+   * - 不以 `+` 开头：视为大陆手机号，发送时自动补 `+86` 前缀，
+   *   如 `13800138000` → `+8613800138000`。
+   */
+  phoneNumber: string;
+}
+/**
+ * `XSms.send` 的返回结果。
+ */
+export interface XSmsSendResult {
+  /** 是否发送成功。对应厂商返回的首条发送状态码是否为 `Ok`。 */
+  success: boolean;
+  /** 厂商返回的状态描述。成功时通常为 `send success`，失败时为失败原因。 */
+  message: string;
+  /** 厂商返回的短信发送流水号（SerialNo），可用于对账与查询。 */
+  smsId: string;
+}
+/**
+ * 短信发送工具。
+ *
+ * 统一封装各云厂商的短信发送接口，将厂商原始返回转换为统一的
+ * {@link XSmsSendResult}。当前支持腾讯云短信（
+ * {@link SmsServiceProvider.TencentCloud}），后续可在此基础上扩展更多
+ * 厂商。
+ *
+ * 腾讯云实现的几个关键点：
+ * 1. 使用 `tencentcloud-sdk-nodejs-sms` 的 `v20210111` 版本客户端；
+ * 2. 客户端构造必须显式传入 `region`（否则报错缺少 `Region` 参数），
+ *    短信用途下该值不参与实际路由，统一使用 `ap-beijing`；
+ * 3. 手机号规范化：以 `+` 开头视为 E.164 号码原样使用，否则自动补
+ *    `+86` 前缀；
+ * 4. 单次发送一个号码，取返回的 `SendStatusSet[0]` 作为发送结果，
+ *    `Code === 'Ok'` 视为成功；若服务商未返回任何状态则抛出错误。
+ *
+ * @example
+ * const sms = new XSms({
+ *   provider: SmsServiceProvider.TencentCloud,
+ *   secretId: 'your-secret-id',
+ *   secretKey: 'your-secret-key',
+ *   appId: '1400000000',
+ * });
+ *
+ * const result = await sms.send({
+ *   provider: SmsServiceProvider.TencentCloud,
+ *   signature: '我的签名',
+ *   templateId: '1234567',
+ *   templateParamValues: ['123456', '5'],
+ *   phoneNumber: '13800138000',
+ * });
+ * // result = { success: true, message: 'send success', smsId: '...' }
+ */
+export declare class XSms {
+  private options;
+  constructor(options: XSmsOptions);
+  /**
+   * 发送短信。
+   *
+   * 根据 `payload.provider` 路由到对应厂商：
+   * - {@link SmsServiceProvider.TencentCloud}：创建腾讯云短信客户端并调用
+   *   `SendSms`，将返回的首条发送状态映射为 {@link XSmsSendResult}；
+   * - 其他未知提供商：抛出错误。
+   *
+   * 手机号规范化：以 `+` 开头视为 E.164 号码原样使用，否则自动补
+   * `+86` 前缀后发送（与腾讯云「境内号码默认 +86」的规则一致）。
+   *
+   * @param payload 发送参数，见 {@link XSmsSendPayload}。
+   * @returns 发送结果，见 {@link XSmsSendResult}。
+   * @throws 当提供商不受支持，或服务商未返回任何发送状态时抛出错误。
+   *
+   * @example
+   * await sms.send({
+   *   provider: SmsServiceProvider.TencentCloud,
+   *   signature: '我的签名',
+   *   templateId: '1234567',
+   *   templateParamValues: ['123456'],
+   *   phoneNumber: '13800138000',
+   * });
+   */
+  send(payload: XSmsSendPayload): Promise<XSmsSendResult>;
+}

package/lib/sms.mjs

@@ -0,0 +1,100 @@
+import * as TencentCloud from "tencentcloud-sdk-nodejs-sms";
+// src/sms.ts
+/**
+* 短信服务提供商。
+*/
+let SmsServiceProvider = /* @__PURE__ */ function(SmsServiceProvider) {
+	/** 腾讯云短信。 */
+	SmsServiceProvider["TencentCloud"] = "TencentCloud";
+	return SmsServiceProvider;
+}({});
+/**
+* 短信发送工具。
+*
+* 统一封装各云厂商的短信发送接口，将厂商原始返回转换为统一的
+* {@link XSmsSendResult}。当前支持腾讯云短信（
+* {@link SmsServiceProvider.TencentCloud}），后续可在此基础上扩展更多
+* 厂商。
+*
+* 腾讯云实现的几个关键点：
+* 1. 使用 `tencentcloud-sdk-nodejs-sms` 的 `v20210111` 版本客户端；
+* 2. 客户端构造必须显式传入 `region`（否则报错缺少 `Region` 参数），
+*    短信用途下该值不参与实际路由，统一使用 `ap-beijing`；
+* 3. 手机号规范化：以 `+` 开头视为 E.164 号码原样使用，否则自动补
+*    `+86` 前缀；
+* 4. 单次发送一个号码，取返回的 `SendStatusSet[0]` 作为发送结果，
+*    `Code === 'Ok'` 视为成功；若服务商未返回任何状态则抛出错误。
+*
+* @example
+* const sms = new XSms({
+*   provider: SmsServiceProvider.TencentCloud,
+*   secretId: 'your-secret-id',
+*   secretKey: 'your-secret-key',
+*   appId: '1400000000',
+* });
+*
+* const result = await sms.send({
+*   provider: SmsServiceProvider.TencentCloud,
+*   signature: '我的签名',
+*   templateId: '1234567',
+*   templateParamValues: ['123456', '5'],
+*   phoneNumber: '13800138000',
+* });
+* // result = { success: true, message: 'send success', smsId: '...' }
+*/
+var XSms = class {
+	options;
+	constructor(options) {
+		this.options = options;
+	}
+	/**
+	* 发送短信。
+	*
+	* 根据 `payload.provider` 路由到对应厂商：
+	* - {@link SmsServiceProvider.TencentCloud}：创建腾讯云短信客户端并调用
+	*   `SendSms`，将返回的首条发送状态映射为 {@link XSmsSendResult}；
+	* - 其他未知提供商：抛出错误。
+	*
+	* 手机号规范化：以 `+` 开头视为 E.164 号码原样使用，否则自动补
+	* `+86` 前缀后发送（与腾讯云「境内号码默认 +86」的规则一致）。
+	*
+	* @param payload 发送参数，见 {@link XSmsSendPayload}。
+	* @returns 发送结果，见 {@link XSmsSendResult}。
+	* @throws 当提供商不受支持，或服务商未返回任何发送状态时抛出错误。
+	*
+	* @example
+	* await sms.send({
+	*   provider: SmsServiceProvider.TencentCloud,
+	*   signature: '我的签名',
+	*   templateId: '1234567',
+	*   templateParamValues: ['123456'],
+	*   phoneNumber: '13800138000',
+	* });
+	*/
+	async send(payload) {
+		if (payload.provider === "TencentCloud") {
+			const SmsClient = TencentCloud.sms.v20210111.Client;
+			const sendStatus = (await new SmsClient({
+				region: "ap-beijing",
+				credential: {
+					secretId: this.options.secretId,
+					secretKey: this.options.secretKey
+				}
+			}).SendSms({
+				SmsSdkAppId: this.options.appId,
+				SignName: payload.signature,
+				TemplateId: payload.templateId,
+				TemplateParamSet: payload.templateParamValues,
+				PhoneNumberSet: [payload.phoneNumber[0] === "+" ? payload.phoneNumber : `+86${payload.phoneNumber}`]
+			})).SendStatusSet?.[0];
+			if (!sendStatus) throw new Error("腾讯云短信发送失败：服务商未返回发送状态");
+			return {
+				success: sendStatus.Code === "Ok",
+				message: sendStatus.Message,
+				smsId: sendStatus.SerialNo
+			};
+		}
+		throw new Error(`no sms provider: ${payload.provider}`);
+	}
+};
+export { SmsServiceProvider, XSms };

package/lib/task.d.mts

@@ -33,5 +33,5 @@ export declare abstract class XTask {
    * 2. 执行 `start()`，成功后以退出码 `0` 优雅退出；
    * 3. 执行失败时记录错误并以退出码 `1` 优雅退出。
    */
-  run(): Promise<void>;
+  run(): Promise<never>;
 }

package/lib/task.mjs

@@ -1,4 +1,4 @@
-import { asyncExitHook, gracefulExit } from "exit-hook";
+import { XDispose } from "./dispose.mjs";
 import { consola } from "consola";
 // src/task.ts
 /**
@@ -31,12 +31,12 @@ var XTask = class {
 	* 3. 执行失败时记录错误并以退出码 `1` 优雅退出。
 	*/
 	run() {
-		asyncExitHook(() => this.dispose(), { wait: 3e3 });
+		XDispose.exit.add(() => this.dispose());
 		return this.start().then(() => {
-			gracefulExit(0);
+			process.exit(0);
 		}).catch((err) => {
 			consola.error(err);
-			gracefulExit(1);
+			process.exit(1);
 		});
 	}
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jayfong/x-utils",
-  "version": "3.3.0",
+  "version": "3.4.0",
   "license": "ISC",
   "sideEffects": false,
   "type": "module",
@@ -8,24 +8,41 @@
     "lib"
   ],
   "dependencies": {
-    "@jayfong/x-request": "^3.3.0",
+    "@aws-sdk/client-s3": "^3.1166.0",
+    "@aws-sdk/s3-request-presigner": "^3.1166.0",
+    "@inquirer/prompts": "^8.8.0",
+    "@jayfong/x-request": "^3.4.0",
+    "@paralleldrive/cuid2": "^3.3.0",
     "@types/fs-extra": "^11.0.4",
+    "alipay-sdk": "^4.14.0",
     "change-case": "^5.4.4",
     "cli-table3": "^0.6.5",
     "clipboardy": "^5.3.2",
     "consola": "^3.4.2",
     "csv": "^6.6.4",
     "exit-hook": "^5.1.0",
+    "fast-escape-html": "^1.1.0",
     "fs-extra": "^11.4.1",
+    "globby": "^16.2.4",
     "html-entities": "^2.6.0",
-    "inquirer": "^14.3.0",
+    "ioredis": "^6.0.0",
+    "jsonwebtoken": "^9.0.3",
+    "lru-cache": "^11.5.3",
     "mime": "^4.1.2",
+    "mini-svg-data-uri": "^1.4.4",
     "node-html-parser": "^9.0.7",
+    "nodemailer": "^10.5.0",
     "pinyin-pro": "^3.26.0",
+    "randomstring": "^1.3.1",
+    "superjson": "^2.2.6",
+    "svg-captcha": "^1.4.0",
+    "tencentcloud-sdk-nodejs-sms": "^4.0.681",
     "vtils": "^4.138.0",
     "yaml": "^2.9.1"
   },
   "devDependencies": {
+    "@types/jsonwebtoken": "^9.0.10",
+    "@types/randomstring": "^1.3.0",
     "puppeteer": "^25.17.0"
   },
   "peerDependencies": {
@@ -40,18 +57,33 @@
     "access": "public"
   },
   "exports": {
+    "./ai": "./lib/ai.mjs",
+    "./cache": "./lib/cache.mjs",
+    "./captcha": "./lib/captcha.mjs",
     "./case": "./lib/case.mjs",
     "./chinese": "./lib/chinese.mjs",
     "./cli": "./lib/cli.mjs",
     "./clipboard": "./lib/clipboard.mjs",
     "./cmd": "./lib/cmd.mjs",
     "./crawler": "./lib/crawler.mjs",
+    "./crypto": "./lib/crypto.mjs",
     "./csv": "./lib/csv.mjs",
     "./data_set": "./lib/data_set.mjs",
+    "./db_value": "./lib/db_value.mjs",
+    "./dispose": "./lib/dispose.mjs",
+    "./file_store": "./lib/file_store.mjs",
     "./fs": "./lib/fs.mjs",
+    "./html": "./lib/html.mjs",
     "./json": "./lib/json.mjs",
+    "./jwt": "./lib/jwt.mjs",
+    "./mail": "./lib/mail.mjs",
+    "./pay": "./lib/pay.mjs",
     "./puppeteer": "./lib/puppeteer.mjs",
+    "./random": "./lib/random.mjs",
+    "./redis": "./lib/redis.mjs",
     "./runner": "./lib/runner.mjs",
+    "./sensitive_words": "./lib/sensitive_words.mjs",
+    "./sms": "./lib/sms.mjs",
     "./task": "./lib/task.mjs",
     "./text": "./lib/text.mjs",
     "./yaml": "./lib/yaml.mjs",