@jayfong/x-utils 3.3.0 → 3.4.0

package/lib/mail.d.mts

@@ -0,0 +1,125 @@
+import { SendMailOptions, SentMessageInfo } from "nodemailer";
+/**
+ * `XMail` 的构造配置。
+ */
+export interface XMailOptions {
+  /** SMTP 服务器地址，例如 `smtp.qq.com`、`smtp.163.com`。 */
+  host: string;
+  /**
+   * SMTP 服务器端口。
+   *
+   * 常见取值：
+   * - `465`：TLS 加密连接（配合 `secure: true`）；
+   * - `587`：STARTTLS 升级加密（配合 `secure: false`）；
+   * - `25`：明文连接，不推荐。
+   */
+  port: number;
+  /**
+   * 是否使用 TLS 加密连接。
+   *
+   * - `true`：连接即建立 TLS 通道，通常配合端口 `465`；
+   * - `false`：先建立明文连接，再视服务器能力通过 STARTTLS 升级，
+   *   通常配合端口 `587`。
+   */
+  secure: boolean;
+  /** SMTP 认证用户名，通常是邮箱地址。 */
+  user: string;
+  /** SMTP 认证密码，通常是邮箱登录密码或服务商签发的授权码。 */
+  pass: string;
+}
+/**
+ * 发送邮件时的邮件内容选项。
+ *
+ * 直接复用 nodemailer 的 {@link SendMailOptions}，字段包括
+ * `from`、`to`、`subject`、`text`、`html`、`attachments` 等。
+ */
+export interface XMailSendOptions extends SendMailOptions {}
+/**
+ * 发送邮件成功后的返回信息。
+ *
+ * 直接复用 nodemailer 的 {@link SentMessageInfo}，不同 transport
+ * 返回的字段略有差异：SMTP 下通常包含 `messageId`、`accepted`、
+ * `rejected`、`response` 等。
+ */
+export interface XMailSendResult extends SentMessageInfo {}
+/**
+ * 邮件发送工具。
+ *
+ * 基于 nodemailer 封装，创建实例即建立 SMTP 连接配置；首次发送前
+ * 会自动校验连接是否可用（`verify`），校验结果会被缓存，校验失败时
+ * 自动清除缓存，以便下一次发送重新校验。
+ *
+ * 实例使用完毕后建议通过 `using` 释放底层连接（也可手动调用
+ * `dispose`），避免连接泄漏。
+ *
+ * @example
+ * using mail = new XMail({
+ *   host: 'smtp.qq.com',
+ *   port: 465,
+ *   secure: true,
+ *   user: 'you@qq.com',
+ *   pass: '授权码',
+ * });
+ * await mail.send({
+ *   from: 'you@qq.com',
+ *   to: 'friend@example.com',
+ *   subject: 'Hello',
+ *   text: 'Hi!',
+ * });
+ * // 邮件已发送，作用域结束后连接自动释放
+ */
+export declare class XMail implements Disposable {
+  private options;
+  private transporter;
+  private disposed;
+  constructor(options: XMailOptions);
+  /**
+   * 校验 SMTP 连接是否可用。
+   *
+   * 通过 `asyncMemoize` 缓存校验结果：
+   * - 校验成功后永久缓存（直到实例被释放），后续发送不再重复校验；
+   * - 校验失败时自动清除缓存，因此失败后下一次 `send` 会重新校验，
+   *   而不是一直使用失败的缓存。
+   */
+  private verify;
+  /**
+   * 发送邮件。
+   *
+   * 发送前会先执行连接校验（首次发送或校验缓存失效时），校验通过后
+   * 再调用 nodemailer 的 `sendMail` 完成实际发送；若实例已通过
+   * `dispose` 或 `using` 释放，则直接抛出错误。
+   *
+   * @param options 邮件内容选项，见 {@link XMailSendOptions}。
+   * @returns 发送结果，见 {@link XMailSendResult}。
+   *
+   * @example
+   * await mail.send({
+   *   from: 'you@qq.com',
+   *   to: ['friend@example.com'],
+   *   subject: 'Hello',
+   *   html: '<p>Hi!</p>',
+   * });
+   */
+  send(options: XMailSendOptions): Promise<XMailSendResult>;
+  /**
+   * 手动释放 SMTP 连接。
+   *
+   * 关闭底层 transporter 的连接（nodemailer 的 `close` 为同步操作）；
+   * 该方法幂等，重复调用只会执行一次关闭。关闭后该实例不再可用，
+   * 如需再次发送请重新创建实例。
+   *
+   * 通常在 `using` 语法之外需要提前释放连接时手动调用。
+   *
+   * @example
+   * const mail = new XMail(options);
+   * await mail.send({ from: 'a', to: 'b', text: 'x' });
+   * mail.dispose();
+   */
+  dispose(): void;
+  /**
+   * 实现 `Disposable`，使实例支持 `using` 语法。
+   *
+   * 直接委托 {@link dispose} 释放连接，在作用域结束时自动调用。
+   */
+  [Symbol.dispose](): void;
+}

package/lib/mail.mjs

@@ -0,0 +1,108 @@
+import { asyncMemoize } from "vtils";
+import { createTransport } from "nodemailer";
+// src/mail.ts
+/**
+* 邮件发送工具。
+*
+* 基于 nodemailer 封装，创建实例即建立 SMTP 连接配置；首次发送前
+* 会自动校验连接是否可用（`verify`），校验结果会被缓存，校验失败时
+* 自动清除缓存，以便下一次发送重新校验。
+*
+* 实例使用完毕后建议通过 `using` 释放底层连接（也可手动调用
+* `dispose`），避免连接泄漏。
+*
+* @example
+* using mail = new XMail({
+*   host: 'smtp.qq.com',
+*   port: 465,
+*   secure: true,
+*   user: 'you@qq.com',
+*   pass: '授权码',
+* });
+* await mail.send({
+*   from: 'you@qq.com',
+*   to: 'friend@example.com',
+*   subject: 'Hello',
+*   text: 'Hi!',
+* });
+* // 邮件已发送，作用域结束后连接自动释放
+*/
+var XMail = class {
+	options;
+	transporter;
+	disposed = false;
+	constructor(options) {
+		this.options = options;
+		this.transporter = createTransport({
+			host: this.options.host,
+			port: this.options.port,
+			secure: this.options.secure,
+			auth: {
+				user: this.options.user,
+				pass: this.options.pass
+			}
+		});
+	}
+	/**
+	* 校验 SMTP 连接是否可用。
+	*
+	* 通过 `asyncMemoize` 缓存校验结果：
+	* - 校验成功后永久缓存（直到实例被释放），后续发送不再重复校验；
+	* - 校验失败时自动清除缓存，因此失败后下一次 `send` 会重新校验，
+	*   而不是一直使用失败的缓存。
+	*/
+	verify = asyncMemoize(async () => {
+		await this.transporter.verify();
+	});
+	/**
+	* 发送邮件。
+	*
+	* 发送前会先执行连接校验（首次发送或校验缓存失效时），校验通过后
+	* 再调用 nodemailer 的 `sendMail` 完成实际发送；若实例已通过
+	* `dispose` 或 `using` 释放，则直接抛出错误。
+	*
+	* @param options 邮件内容选项，见 {@link XMailSendOptions}。
+	* @returns 发送结果，见 {@link XMailSendResult}。
+	*
+	* @example
+	* await mail.send({
+	*   from: 'you@qq.com',
+	*   to: ['friend@example.com'],
+	*   subject: 'Hello',
+	*   html: '<p>Hi!</p>',
+	* });
+	*/
+	async send(options) {
+		if (this.disposed) throw new Error("邮件连接已释放，无法继续发送，请重新创建 XMail 实例");
+		await this.verify();
+		return this.transporter.sendMail(options);
+	}
+	/**
+	* 手动释放 SMTP 连接。
+	*
+	* 关闭底层 transporter 的连接（nodemailer 的 `close` 为同步操作）；
+	* 该方法幂等，重复调用只会执行一次关闭。关闭后该实例不再可用，
+	* 如需再次发送请重新创建实例。
+	*
+	* 通常在 `using` 语法之外需要提前释放连接时手动调用。
+	*
+	* @example
+	* const mail = new XMail(options);
+	* await mail.send({ from: 'a', to: 'b', text: 'x' });
+	* mail.dispose();
+	*/
+	dispose() {
+		if (this.disposed) return;
+		this.disposed = true;
+		this.transporter.close();
+	}
+	/**
+	* 实现 `Disposable`，使实例支持 `using` 语法。
+	*
+	* 直接委托 {@link dispose} 释放连接，在作用域结束时自动调用。
+	*/
+	[Symbol.dispose]() {
+		this.dispose();
+	}
+};
+export { XMail };

package/lib/pay.d.mts

@@ -0,0 +1,394 @@
+/**
+ * `XPay` 的构造配置。
+ */
+export interface XPayOptions {
+  /**
+   * 支付宝配置。
+   *
+   * 缺省时，支付宝相关方法（`prepareAlipay`、`getOrderInfo` 等）会抛出
+   * “未配置支付宝”的错误。
+   */
+  alipay?: {
+    /** 应用 ID（支付宝开放平台分配）。 */
+    appId: string;
+    /** 应用私钥，用于对请求进行签名。 */
+    privateKey: string;
+    /** 支付宝公钥，用于对回调通知与查询结果进行验签。 */
+    publicKey: string;
+  };
+  /**
+   * 微信支付（APIv3）配置。
+   *
+   * 缺省时，微信支付相关方法（`prepareWepay`、`getOrderInfo` 等）会抛出
+   * “未配置微信支付”的错误。
+   *
+   * 说明：当前未实现微信支付回调验签，回调数据仅做 AES-GCM 解密，
+   * 验证微信支付身份时需业务方自行补充签名校验。
+   */
+  wepay?: {
+    /** 公众号 APPID。 */
+    appId: string;
+    /** 商户 ID。 */
+    merchantId: string;
+    /** 商户 API 证书私钥，用于对请求与支付参数签名。 */
+    privateKey: string;
+    /** 商户 API 证书序列号，用于构造请求头 `serial_no`。 */
+    certificateSerialNumber: string;
+    /** APIv3 密钥（32 字节），用于解密回调数据。 */
+    secretKey: string;
+  };
+}
+/**
+ * `XPay.prepareAlipay` 的入参。
+ */
+export interface XPayPrepareAlipayOptions {
+  /** 商品名称（订单标题）。 */
+  goodsName: string;
+  /** 商家订单号（`out_trade_no`），需保证在商户侧唯一。 */
+  tradeNumber: string;
+  /** 订单总金额，单位：元，如 `0.01` 表示 1 分钱。 */
+  totalMoney: number;
+  /** 支付宝异步通知地址（POST）。 */
+  notifyUrl: string;
+  /** 支付完成后同步跳转地址，缺省时不传入支付宝。 */
+  returnUrl?: string;
+}
+/**
+ * `XPay.prepareAlipay` 的返回结果。
+ */
+export interface XPayPrepareAlipayResult {
+  /** 支付地址，需跳转到该地址完成支付。 */
+  payUrl: string;
+}
+/**
+ * `XPay.prepareWepay` 的入参。
+ */
+export interface XPayPrepareWepayOptions {
+  /** 商品名称（订单描述）。 */
+  goodsName: string;
+  /** 商家订单号（`out_trade_no`）。 */
+  tradeNumber: string;
+  /** 订单总金额，单位：元，内部会转换为分（乘以 100 后四舍五入）。 */
+  totalMoney: number;
+  /** 微信支付异步通知地址（POST）。 */
+  notifyUrl: string;
+  /** 公众号用户的 openid。 */
+  openid: string;
+}
+/**
+ * 微信支付 JSSDK 支付参数。
+ *
+ * 对应公众号 JSAPI 支付 `wx.requestPayment` 所需的参数对象。
+ */
+export interface XPayWepayPayParams {
+  /** 公众号 APPID。 */
+  appId: string;
+  /** 生成签名时的时间戳，单位：秒。 */
+  timestamp: string;
+  /** 随机字符串。 */
+  nonceStr: string;
+  /** 预支付标识，格式为 `prepay_id=...`。 */
+  package: string;
+  /** 签名类型，固定为 `RSA`。 */
+  signType: string;
+  /** 支付签名。 */
+  paySign: string;
+}
+/**
+ * `XPay.prepareWepay` 的返回结果。
+ */
+export interface XPayPrepareWepayResult {
+  /** 支付参数，可直接传给 JSSDK 的 `wx.requestPayment` 调用。 */
+  payParams: XPayWepayPayParams;
+}
+/**
+ * `XPay.verifyNotifyData` 的返回结果。
+ */
+export interface XPayVerifyNotifyDataResult {
+  /**
+   * 渠道订单号。
+   *
+   * - 支付宝最长 64 位；
+   * - 微信支付最长 32 位。
+   */
+  channelOrderNo: string;
+}
+/**
+ * `XPay.getOrderInfo` 的入参。
+ */
+export interface XPayGetOrderInfoPayload {
+  /** 渠道：`alipay` 支付宝、`wepay` 微信支付。 */
+  channel: 'alipay' | 'wepay';
+  /** 商家订单号；与 `channelOrderNo` 二选一，两者都传时优先使用它。 */
+  orderNo?: string;
+  /** 渠道订单号；未传 `orderNo` 时使用。 */
+  channelOrderNo?: string;
+}
+/**
+ * `XPay.getOrderInfo` 的返回结果。
+ */
+export interface XPayGetOrderInfoResult {
+  /** 商家订单号。 */
+  orderNo: string;
+  /**
+   * 渠道订单号。
+   *
+   * - 支付宝最长 64 位；
+   * - 微信支付最长 32 位。
+   */
+  channelOrderNo: string;
+  /** 订单状态：`success` 支付成功、`fail` 未支付或支付失败。 */
+  status: 'success' | 'fail';
+}
+/**
+ * 微信支付回调通知中的 `resource` 字段（AES-GCM 加密数据）。
+ *
+ * @see https://pay.weixin.qq.com/wiki/doc/apiv3/apis/chapter3_1_5.shtml
+ */
+export interface XPayWepayResource {
+  /** 原始回调类型，如 `transaction`。 */
+  original_type?: string;
+  /** 加密算法类型，如 `AEAD_AES_256_GCM`。 */
+  algorithm: string;
+  /** 附加数据，用于校验密文完整性，可能为空字符串。 */
+  associated_data?: string;
+  /** 密文内容（base64）。 */
+  ciphertext: string;
+  /** 随机串，作为 AES-GCM 解密的 IV。 */
+  nonce: string;
+}
+/**
+ * 微信支付回调数据解密后的内容（本工具用到的字段）。
+ */
+export interface XPayWepayNotifyData {
+  /** 附加数据，用于标记支付渠道，本工具使用 `wepay`。 */
+  attach?: string;
+  /** 微信支付订单号。 */
+  transaction_id?: string;
+}
+/**
+ * 微信支付 JSAPI 下单的响应。
+ */
+export interface XPayWepayPrepayResult {
+  /** 预支付交易会话标识。 */
+  prepay_id?: string;
+  /** 错误描述，下单失败时返回。 */
+  message?: string;
+}
+/**
+ * 微信支付订单查询的响应（本工具用到的字段）。
+ */
+export interface XPayWepayOrderInfoData {
+  /** 交易状态，如 `SUCCESS`、`NOTPAY`、`CLOSED`、`REVOKED`、`PAYERROR` 等。 */
+  trade_state: string;
+  /** 商家订单号。 */
+  out_trade_no: string;
+  /** 微信支付订单号。 */
+  transaction_id: string;
+}
+/**
+ * 支付宝订单查询的响应（本工具用到的字段）。
+ *
+ * 支付宝 SDK 默认开启驼峰转换，因此字段为驼峰命名。
+ */
+export interface XPayAlipayOrderInfoData {
+  /** 支付宝交易号。 */
+  tradeNo: string;
+  /** 商家订单号。 */
+  outTradeNo: string;
+  /** 交易状态，如 `TRADE_SUCCESS`、`TRADE_FINISHED`、`WAIT_BUYER_PAY` 等。 */
+  tradeStatus: string;
+}
+/**
+ * 支付工具。
+ *
+ * 封装支付宝（网页支付）与微信支付（JSAPI 支付）的下单、回调验签与
+ * 订单查询能力：
+ * - 支付宝：`prepareAlipay` 生成支付链接、`getOrderInfo` 查询订单；
+ * - 微信支付：`prepareWepay` 生成 JSSDK 支付参数、`getOrderInfo` 查询订单；
+ * - 回调：`verifyNotifyData` 统一校验并解析两个渠道的回调数据。
+ *
+ * 支付宝 SDK 按需惰性创建，只有首次使用支付宝能力时才初始化。
+ * 注意：微信支付回调目前只做 AES-GCM 解密，未实现签名验签，
+ * 业务方如需严格校验身份，请自行补充。
+ *
+ * @example
+ * const pay = new XPay({
+ *   alipay: {
+ *     appId: '2021000000000000',
+ *     privateKey: '应用私钥',
+ *     publicKey: '支付宝公钥',
+ *   },
+ *   wepay: {
+ *     appId: 'wx1234567890',
+ *     merchantId: '1234567890',
+ *     privateKey: '商户 API 证书私钥',
+ *     certificateSerialNumber: '证书序列号',
+ *     secretKey: '32 字节 APIv3 密钥',
+ *   },
+ * });
+ *
+ * const { payUrl } = await pay.prepareAlipay({
+ *   goodsName: '测试商品',
+ *   tradeNumber: 'T20260101001',
+ *   totalMoney: 0.01,
+ *   notifyUrl: 'https://example.com/notify/alipay',
+ * });
+ * // 跳转到 payUrl 完成支付
+ */
+export declare class XPay {
+  private options;
+  private alipaySdk;
+  constructor(options: XPayOptions);
+  /**
+   * 支付宝网页支付下单，生成支付链接。
+   *
+   * 调用支付宝 `alipay.trade.page.pay` 接口生成 GET 形式的支付地址，
+   * 用户跳转到该地址即可在支付宝收银台完成支付。订单金额会格式化为
+   * 两位小数字符串，并通过 `passback_params` 标记渠道为 `alipay`，
+   * 以便回调时识别。
+   *
+   * @param options 下单参数，见 {@link XPayPrepareAlipayOptions}。
+   * @returns 支付地址，见 {@link XPayPrepareAlipayResult}。
+   *
+   * @example
+   * const { payUrl } = await pay.prepareAlipay({
+   *   goodsName: '测试商品',
+   *   tradeNumber: 'T20260101001',
+   *   totalMoney: 0.01,
+   *   notifyUrl: 'https://example.com/notify/alipay',
+   * });
+   */
+  prepareAlipay(options: XPayPrepareAlipayOptions): Promise<XPayPrepareAlipayResult>;
+  /**
+   * 微信支付 JSAPI 下单，生成 JSSDK 支付参数。
+   *
+   * 调用微信支付 `v3/pay/transactions/jsapi` 接口获取 `prepay_id`，
+   * 再按 JSSDK 规则签名得到支付参数，可直接传给前端
+   * `wx.requestPayment`。金额由元转换为分（乘以 100 后四舍五入），
+   * 避免浮点误差；下单请求会通过 `attach` 字段标记渠道为 `wepay`。
+   *
+   * @param options 下单参数，见 {@link XPayPrepareWepayOptions}。
+   * @returns 支付参数，见 {@link XPayPrepareWepayResult}。
+   *
+   * @example
+   * const { payParams } = await pay.prepareWepay({
+   *   goodsName: '测试商品',
+   *   tradeNumber: 'T20260101002',
+   *   totalMoney: 0.01,
+   *   notifyUrl: 'https://example.com/notify/wepay',
+   *   openid: 'oABC123',
+   * });
+   */
+  prepareWepay(options: XPayPrepareWepayOptions): Promise<XPayPrepareWepayResult>;
+  /**
+   * 校验并解析支付回调通知数据。
+   *
+   * 先判断数据是否为对象，再按渠道标记识别：
+   * - 支付宝：当 `passback_params` 为 `alipay` 时，调用支付宝 SDK 验签，
+   *   验签通过后返回支付宝交易号；
+   * - 微信支付：当存在 `resource` 字段时，先 AES-GCM 解密，再校验
+   *   `attach` 是否为 `wepay`，通过后返回微信支付订单号。
+   *
+   * 任何一步失败（数据非法、未配置渠道、验签失败、解密失败）都会
+   * 返回 `false`，不会抛出异常。
+   *
+   * @param data 支付平台 POST 过来的回调数据（支付宝为表单 JSON，
+   *   微信支付为通知报文 JSON）。
+   * @returns 校验通过时返回渠道订单号，否则返回 `false`。
+   *
+   * @example
+   * const res = pay.verifyNotifyData(req.body);
+   * if (res) {
+   *   // 校验通过，res.channelOrderNo 为渠道订单号
+   * }
+   */
+  verifyNotifyData(data: any): false | XPayVerifyNotifyDataResult;
+  /**
+   * 校验并解析支付回调通知数据，失败时抛出错误。
+   *
+   * 行为与 {@link verifyNotifyData} 一致，区别在于校验失败时抛出
+   * `Error`，便于在需要强制校验的流程中使用。
+   *
+   * @param data 支付平台 POST 过来的回调数据。
+   * @param message 校验失败时抛出的错误信息。
+   * @returns 校验通过时的渠道订单号。
+   *
+   * @example
+   * const res = pay.verifyNotifyDataOrFail(req.body, '回调验签失败');
+   */
+  verifyNotifyDataOrFail(data: any, message?: string): XPayVerifyNotifyDataResult;
+  /**
+   * 查询订单状态。
+   *
+   * 按渠道分别调用微信支付订单查询接口或支付宝 `alipay.trade.query`：
+   * - 优先使用 `orderNo`（商家订单号）查询，未提供时使用
+   *   `channelOrderNo`（渠道订单号）；
+   * - 微信支付 `trade_state` 为 `SUCCESS` 时视为成功；
+   * - 支付宝 `trade_status` 为 `TRADE_SUCCESS` 或 `TRADE_FINISHED` 时
+   *   视为成功，其余状态视为失败。
+   *
+   * @param payload 查询条件，见 {@link XPayGetOrderInfoPayload}。
+   * @returns 订单信息，见 {@link XPayGetOrderInfoResult}。
+   *
+   * @example
+   * await pay.getOrderInfo({ channel: 'alipay', orderNo: 'T20260101001' });
+   * // { channelOrderNo: '2026...', orderNo: 'T20260101001', status: 'success' }
+   */
+  getOrderInfo(payload: XPayGetOrderInfoPayload): Promise<XPayGetOrderInfoResult>;
+  /**
+   * 获取（并按需创建）支付宝 SDK 实例。
+   *
+   * 首次调用时才初始化 SDK，后续复用同一实例；未配置支付宝时抛出
+   * 明确错误。
+   */
+  private getAlipaySdk;
+  /**
+   * 获取支付宝配置，未配置时抛出错误。
+   */
+  private getAlipayConfig;
+  /**
+   * 获取微信支付配置，未配置时抛出错误。
+   */
+  private getWepayConfig;
+  /**
+   * 生成随机字符串，用于微信支付请求的 `nonce_str` 与支付参数。
+   *
+   * 使用密码学安全的随机字节生成 12 位十六进制字符串。
+   */
+  private generateNonceStr;
+  /**
+   * 微信支付 RSA 签名。
+   *
+   * 将每个字段拼接换行符（`\n`）后使用 `RSA-SHA256` 私钥签名，返回
+   * base64 编码的签名；同一方法同时用于请求头签名与 JSSDK 支付参数
+   * 签名。
+   *
+   * @param data 待签名字段，按顺序依次拼接，每个字段后追加换行符。
+   * @returns base64 编码的签名串。
+   */
+  private wepaySign;
+  /**
+   * 微信支付回调数据解密。
+   *
+   * 使用 APIv3 密钥对 `resource` 做 AES-256-GCM 解密：密文末尾 16
+   * 字节为认证标签，前面为加密数据，`nonce` 作为 IV，
+   * `associated_data` 作为附加认证数据。
+   *
+   * @param resource 回调数据中的 `resource` 字段。
+   * @returns 解密后的 JSON 字符串。
+   */
+  private wepayDecrypt;
+  /**
+   * 发起微信支付 APIv3 请求。
+   *
+   * 根据 URL 计算请求路径，按 `方法\nURL\n时间戳\n随机串\n请求体\n`
+   * 构造签名并生成 `Authorization` 请求头；GET 请求体为空字符串，
+   * POST 请求体为 `data` 的 JSON 字符串。
+   *
+   * @param url 完整请求地址。
+   * @param data 请求体，缺省表示 GET 请求。
+   * @returns 响应数据。
+   */
+  private wepayRequest;
+}