@jayfong/x-utils 1.0.0-202510061015 → 3.4.0

package/lib/random.d.mts

@@ -0,0 +1,71 @@
+/**
+ * 随机 ID 与随机字符串生成工具。
+ *
+ * 提供碰撞概率极低的全局唯一 ID（CUID2）以及基于指定字符集的随机
+ * 字符串生成能力（字母数字、纯字母、纯数字）。所有方法均为静态方法，
+ * 可直接通过 `XRandom.xxx()` 调用。
+ *
+ * @example
+ * XRandom.cuid2() // 'dj8fyuqt57ejnnbsnik8q1d6'
+ * XRandom.generateAlphanumeric(8) // 'a3Fk9Zx2'
+ * XRandom.generateAlphabetic(8) // 'AbCdEfGh'
+ * XRandom.generateNumeric(6) // '386251'
+ *
+ * @remarks
+ * - `cuid2()` 生成的 ID 长度固定为 24 位，仅包含小写字母与数字，
+ *   适用于数据库主键、文件名等需要高唯一性的场景；
+ * - 随机字符串基于 `randomstring` 生成，各方法的字符集见对应说明；
+ * - 随机字符串不保证密码学安全，请勿用于令牌、密钥等安全敏感场景。
+ */
+export declare class XRandom {
+  /**
+   * 生成 24 位 CUID2 全局唯一 ID。
+   *
+   * CUID2 是 CUID 的改进版本，专为水平扩展与防碰撞设计，默认由
+   * 24 位小写字母与数字组成，无需配置即可直接使用。
+   *
+   * @returns 24 位小写字母与数字组成的唯一 ID 字符串。
+   *
+   * @example
+   * XRandom.cuid2() // 'dj8fyuqt57ejnnbsnik8q1d6'
+   *
+   * @see https://github.com/paralleldrive/cuid2
+   */
+  static cuid2(): string;
+  /**
+   * 生成由大小写字母与数字组成的随机字符串。
+   *
+   * 字符集为 `[0-9 a-z A-Z]`，共 62 种字符。
+   *
+   * @param length 生成字符串的长度，需为不小于 0 的整数，传 0 时返回空字符串。
+   * @returns 指定长度的字母数字随机字符串。
+   *
+   * @example
+   * XRandom.generateAlphanumeric(8) // 'a3Fk9Zx2'
+   */
+  static generateAlphanumeric(length: number): string;
+  /**
+   * 生成由大小写英文字母组成的随机字符串。
+   *
+   * 字符集为 `[a-z A-Z]`，不包含数字。
+   *
+   * @param length 生成字符串的长度，需为不小于 0 的整数，传 0 时返回空字符串。
+   * @returns 指定长度的字母随机字符串。
+   *
+   * @example
+   * XRandom.generateAlphabetic(8) // 'AbCdEfGh'
+   */
+  static generateAlphabetic(length: number): string;
+  /**
+   * 生成由数字组成的随机字符串。
+   *
+   * 字符集为 `[0-9]`，首位允许为 0（例如 `'086251'`）。
+   *
+   * @param length 生成字符串的长度，需为不小于 0 的整数，传 0 时返回空字符串。
+   * @returns 指定长度的数字随机字符串。
+   *
+   * @example
+   * XRandom.generateNumeric(6) // '386251'
+   */
+  static generateNumeric(length: number): string;
+}

package/lib/random.mjs

@@ -0,0 +1,92 @@
+import { createId } from "@paralleldrive/cuid2";
+import * as randomstring from "randomstring";
+// src/random.ts
+/**
+* 随机 ID 与随机字符串生成工具。
+*
+* 提供碰撞概率极低的全局唯一 ID（CUID2）以及基于指定字符集的随机
+* 字符串生成能力（字母数字、纯字母、纯数字）。所有方法均为静态方法，
+* 可直接通过 `XRandom.xxx()` 调用。
+*
+* @example
+* XRandom.cuid2() // 'dj8fyuqt57ejnnbsnik8q1d6'
+* XRandom.generateAlphanumeric(8) // 'a3Fk9Zx2'
+* XRandom.generateAlphabetic(8) // 'AbCdEfGh'
+* XRandom.generateNumeric(6) // '386251'
+*
+* @remarks
+* - `cuid2()` 生成的 ID 长度固定为 24 位，仅包含小写字母与数字，
+*   适用于数据库主键、文件名等需要高唯一性的场景；
+* - 随机字符串基于 `randomstring` 生成，各方法的字符集见对应说明；
+* - 随机字符串不保证密码学安全，请勿用于令牌、密钥等安全敏感场景。
+*/
+var XRandom = class {
+	/**
+	* 生成 24 位 CUID2 全局唯一 ID。
+	*
+	* CUID2 是 CUID 的改进版本，专为水平扩展与防碰撞设计，默认由
+	* 24 位小写字母与数字组成，无需配置即可直接使用。
+	*
+	* @returns 24 位小写字母与数字组成的唯一 ID 字符串。
+	*
+	* @example
+	* XRandom.cuid2() // 'dj8fyuqt57ejnnbsnik8q1d6'
+	*
+	* @see https://github.com/paralleldrive/cuid2
+	*/
+	static cuid2() {
+		return createId();
+	}
+	/**
+	* 生成由大小写字母与数字组成的随机字符串。
+	*
+	* 字符集为 `[0-9 a-z A-Z]`，共 62 种字符。
+	*
+	* @param length 生成字符串的长度，需为不小于 0 的整数，传 0 时返回空字符串。
+	* @returns 指定长度的字母数字随机字符串。
+	*
+	* @example
+	* XRandom.generateAlphanumeric(8) // 'a3Fk9Zx2'
+	*/
+	static generateAlphanumeric(length) {
+		return randomstring.generate({
+			charset: "alphanumeric",
+			length
+		});
+	}
+	/**
+	* 生成由大小写英文字母组成的随机字符串。
+	*
+	* 字符集为 `[a-z A-Z]`，不包含数字。
+	*
+	* @param length 生成字符串的长度，需为不小于 0 的整数，传 0 时返回空字符串。
+	* @returns 指定长度的字母随机字符串。
+	*
+	* @example
+	* XRandom.generateAlphabetic(8) // 'AbCdEfGh'
+	*/
+	static generateAlphabetic(length) {
+		return randomstring.generate({
+			charset: "alphabetic",
+			length
+		});
+	}
+	/**
+	* 生成由数字组成的随机字符串。
+	*
+	* 字符集为 `[0-9]`，首位允许为 0（例如 `'086251'`）。
+	*
+	* @param length 生成字符串的长度，需为不小于 0 的整数，传 0 时返回空字符串。
+	* @returns 指定长度的数字随机字符串。
+	*
+	* @example
+	* XRandom.generateNumeric(6) // '386251'
+	*/
+	static generateNumeric(length) {
+		return randomstring.generate({
+			charset: "numeric",
+			length
+		});
+	}
+};
+export { XRandom };

package/lib/redis.d.mts

@@ -0,0 +1,32 @@
+import { Redis, RedisOptions } from "ioredis";
+/**
+ * Redis 连接与行为配置项。
+ *
+ * 直接继承 ioredis 的 `RedisOptions`，作为 {@link XRedis} 构造时的入参类型。
+ * 保留为空继承的原因：
+ * - 调用方可继续使用 ioredis 原生的全部配置项（如 `host`、`port`、`db`、
+ *   `password`、`keyPrefix` 等）；
+ * - 后续若需追加项目级默认配置或扩展字段，只需在此声明，无需改动调用方。
+ */
+export interface XRedisOptions extends RedisOptions {}
+/**
+ * Redis 客户端封装。
+ *
+ * 直接继承 ioredis 的 `Redis`，完整保留其命令、事件与类型定义，当前仅作为
+ * 统一入口存在，便于：
+ * - 集中管理连接实例的创建与复用；
+ * - 在需要时统一注入默认配置、日志或监控逻辑，而不影响调用方；
+ * - 后续按需覆写/扩展方法，同时保持对原有 API 的兼容。
+ *
+ * @example
+ * const redis = new XRedis({
+ *   host: '127.0.0.1',
+ *   port: 6379,
+ * });
+ *
+ * await redis.set('key', 'value');
+ * // 'OK'
+ * const value = await redis.get('key');
+ * // 'value'
+ */
+export declare class XRedis extends Redis {}

package/lib/redis.mjs

@@ -0,0 +1,24 @@
+import { Redis } from "ioredis";
+// src/redis.ts
+/**
+* Redis 客户端封装。
+*
+* 直接继承 ioredis 的 `Redis`，完整保留其命令、事件与类型定义，当前仅作为
+* 统一入口存在，便于：
+* - 集中管理连接实例的创建与复用；
+* - 在需要时统一注入默认配置、日志或监控逻辑，而不影响调用方；
+* - 后续按需覆写/扩展方法，同时保持对原有 API 的兼容。
+*
+* @example
+* const redis = new XRedis({
+*   host: '127.0.0.1',
+*   port: 6379,
+* });
+*
+* await redis.set('key', 'value');
+* // 'OK'
+* const value = await redis.get('key');
+* // 'value'
+*/
+var XRedis = class extends Redis {};
+export { XRedis };

package/lib/runner.d.mts

@@ -0,0 +1,80 @@
+import { MsValue } from "vtils";
+import { AsyncOrSync } from "vtils/types";
+/**
+ * `XRunner` 的运行配置。
+ */
+export interface XRunnerOptions<TConfig extends Record<string, any>> {
+  /**
+   * 交互配置持久化文件路径（JSON）。
+   *
+   * 启动时若文件不存在会自动创建；读取到的历史配置会传给 `provideConfig`，
+   * 收集到的新配置最终以 2 空格缩进写回该文件，供下次运行复用。
+   */
+  configFile: string;
+  /**
+   * 失败重试间隔。
+   *
+   * - 固定值：每次失败都等待同一个时长；
+   * - 函数：可按重试次数动态计算，`retryCount` 从 `1` 开始计数。
+   *
+   * 时长取值与 `vtils.ms` 一致：数字表示毫秒，字符串需带单位
+   * （如 `'500ms'`、`'1s'`）；值非法时 `ms` 会抛错并终止重试循环。
+   */
+  delay: MsValue | ((retryCount: number) => MsValue);
+  /**
+   * 收集本次运行配置的交互函数。
+   *
+   * 入参 `prevConfig` 为启动时读取到的历史配置（文件缺失或内容非法时兜底为 `{}`），
+   * 通常用于回填交互默认值；返回最终配置，支持同步或异步返回。
+   */
+  provideConfig: (prevConfig: Partial<TConfig>) => AsyncOrSync<TConfig>;
+  /**
+   * 核心执行函数，接收 `provideConfig` 收集到的最终配置。
+   *
+   * - 成功（resolve）：结束运行，`run()` 正常返回；
+   * - 失败（reject）：进入重试分支，按 `delay` 等待后再次调用。
+   */
+  run: (config: TConfig) => Promise<void> | void;
+}
+/**
+ * 带配置持久化与失败重试能力的交互式运行器。
+ *
+ * 典型用法：CLI 启动时先询问用户配置并落盘复用，随后循环执行业务函数，
+ * 失败时自动等待并重试。
+ *
+ * 运行流程（详见 {@link XRunner.run}）：
+ * 1. 确保配置文件存在（缺失时自动创建）；
+ * 2. 读取历史配置，作为本次提问默认值；
+ * 3. 用户确认后回写配置文件，保证下次可复用；
+ * 4. 执行业务函数，成功即退出；
+ * 5. 失败时按 `delay` 等待后重试，直到成功或出现不可恢复错误。
+ */
+export declare class XRunner<TConfig extends Record<string, any>> {
+  private options;
+  /**
+   * 创建运行器实例。
+   *
+   * @param options 运行配置，各字段语义见 {@link XRunnerOptions}。
+   */
+  constructor(options: XRunnerOptions<TConfig>);
+  /**
+   * 启动运行器。
+   *
+   * 依次执行：确保配置文件存在 → 读取历史配置 → 通过 `provideConfig`
+   * 收集本次配置 → 写回配置文件 → 循环执行 `run`。
+   *
+   * 边界与异常说明：
+   * - 配置文件缺失时由 `XFs.ensureFile` 自动补齐目录并创建空文件；
+   * - 配置内容非法（非 JSON）时 `readJson(..., { throws: false })` 返回
+   *   `null`，经 `|| {}` 兜底为空对象，不阻断启动；
+   * - `provideConfig` 抛错或写回配置失败时，错误直接向外抛出，不进入重试；
+   * - `run` 抛错时进入重试分支：`retryCount` 自增后计算等待时长，打印
+   *   错误与重试提示，等待后重新执行；
+   * - `delay` 为函数时按 `retryCount`（从 `1` 开始）动态计算；其返回值
+   *   若无法被 `ms` 解析，`ms` 会抛错并终止重试循环。
+   *
+   * @returns 业务函数成功后 resolve 为 `undefined`；仅在成功或抛出
+   *          不可恢复错误时返回，否则持续重试。
+   */
+  run(): Promise<void>;
+}

package/lib/runner.mjs

@@ -0,0 +1,66 @@
+import { XFs } from "./fs.mjs";
+import { ms, wait } from "vtils";
+// src/runner.ts
+/**
+* 带配置持久化与失败重试能力的交互式运行器。
+*
+* 典型用法：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 config = await this.options.provideConfig(savedConfig);
+		await XFs.writeJson(this.options.configFile, config, { spaces: 2 });
+		let retryCount = 0;
+		while (true) try {
+			await this.options.run(config);
+			return;
+		} catch (err) {
+			retryCount++;
+			const delay = typeof this.options.delay === "function" ? this.options.delay(retryCount) : this.options.delay;
+			const delayMs = ms(delay);
+			if (delayMs == null) throw new Error(`无效的重试等待时长: ${String(delay)}`);
+			console.error(err);
+			console.log(`执行报错, 第${retryCount}次重试前等待${delay}`);
+			await wait(delayMs);
+		}
+	}
+};
+export { XRunner };

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>;
+}