@jayfong/x-utils 1.0.0-202510061015 → 3.4.0

package/lib/pay.mjs

@@ -0,0 +1,343 @@
+import { xr } from "@jayfong/x-request";
+import crypto from "node:crypto";
+import { AlipaySdk } from "alipay-sdk";
+// src/pay.ts
+/**
+* 支付工具。
+*
+* 封装支付宝（网页支付）与微信支付（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 完成支付
+*/
+var XPay = class {
+	options;
+	alipaySdk;
+	constructor(options) {
+		this.options = options;
+	}
+	/**
+	* 支付宝网页支付下单，生成支付链接。
+	*
+	* 调用支付宝 `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',
+	* });
+	*/
+	async prepareAlipay(options) {
+		return { payUrl: this.getAlipaySdk().pageExecute("alipay.trade.page.pay", "GET", {
+			notifyUrl: options.notifyUrl,
+			...options.returnUrl ? { returnUrl: options.returnUrl } : {},
+			bizContent: {
+				outTradeNo: options.tradeNumber,
+				productCode: "FAST_INSTANT_TRADE_PAY",
+				totalAmount: options.totalMoney.toFixed(2),
+				subject: options.goodsName,
+				goodsType: "0",
+				passbackParams: "alipay"
+			}
+		}) };
+	}
+	/**
+	* 微信支付 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',
+	* });
+	*/
+	async prepareWepay(options) {
+		const wepay = this.getWepayConfig();
+		const res = await this.wepayRequest("https://api.mch.weixin.qq.com/v3/pay/transactions/jsapi", {
+			appid: wepay.appId,
+			mchid: wepay.merchantId,
+			description: options.goodsName,
+			out_trade_no: options.tradeNumber,
+			attach: "wepay",
+			notify_url: options.notifyUrl,
+			amount: {
+				total: Math.round(options.totalMoney * 100),
+				currency: "CNY"
+			},
+			payer: { openid: options.openid }
+		});
+		if (!res || !res.prepay_id) throw new Error(res?.message || "微信支付下单失败，未返回 prepay_id");
+		const params = {
+			appId: wepay.appId,
+			timestamp: String(Math.round(Date.now() / 1e3)),
+			nonceStr: this.generateNonceStr(),
+			package: `prepay_id=${res.prepay_id}`,
+			signType: "RSA",
+			paySign: ""
+		};
+		params.paySign = this.wepaySign([
+			params.appId,
+			params.timestamp,
+			params.nonceStr,
+			params.package
+		]);
+		return { payParams: params };
+	}
+	/**
+	* 校验并解析支付回调通知数据。
+	*
+	* 先判断数据是否为对象，再按渠道标记识别：
+	* - 支付宝：当 `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) {
+		try {
+			if (!data || typeof data !== "object") return false;
+			if (data.passback_params === "alipay") {
+				if (!this.getAlipaySdk().checkNotifySign(data)) return false;
+				return { channelOrderNo: data.trade_no };
+			}
+			if (data.resource) {
+				const params = JSON.parse(this.wepayDecrypt(data.resource));
+				if (params.attach === "wepay" && params.transaction_id) return { channelOrderNo: params.transaction_id };
+				return false;
+			}
+			return false;
+		} catch {
+			return false;
+		}
+	}
+	/**
+	* 校验并解析支付回调通知数据，失败时抛出错误。
+	*
+	* 行为与 {@link verifyNotifyData} 一致，区别在于校验失败时抛出
+	* `Error`，便于在需要强制校验的流程中使用。
+	*
+	* @param data 支付平台 POST 过来的回调数据。
+	* @param message 校验失败时抛出的错误信息。
+	* @returns 校验通过时的渠道订单号。
+	*
+	* @example
+	* const res = pay.verifyNotifyDataOrFail(req.body, '回调验签失败');
+	*/
+	verifyNotifyDataOrFail(data, message) {
+		const res = this.verifyNotifyData(data);
+		if (!res) throw new Error(message);
+		return res;
+	}
+	/**
+	* 查询订单状态。
+	*
+	* 按渠道分别调用微信支付订单查询接口或支付宝 `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' }
+	*/
+	async getOrderInfo(payload) {
+		if (payload.channel === "wepay") {
+			const wepay = this.getWepayConfig();
+			const res = await this.wepayRequest(payload.orderNo ? `https://api.mch.weixin.qq.com/v3/pay/transactions/out-trade-no/${payload.orderNo}?mchid=${wepay.merchantId}` : `https://api.mch.weixin.qq.com/v3/pay/transactions/id/${payload.channelOrderNo}?mchid=${wepay.merchantId}`);
+			return {
+				channelOrderNo: res.transaction_id,
+				orderNo: res.out_trade_no,
+				status: res.trade_state === "SUCCESS" ? "success" : "fail"
+			};
+		}
+		const res = await this.getAlipaySdk().exec("alipay.trade.query", { biz_content: payload.orderNo ? { out_trade_no: payload.orderNo } : { trade_no: payload.channelOrderNo } });
+		return {
+			channelOrderNo: res.tradeNo,
+			orderNo: res.outTradeNo,
+			status: res.tradeStatus === "TRADE_SUCCESS" || res.tradeStatus === "TRADE_FINISHED" ? "success" : "fail"
+		};
+	}
+	/**
+	* 获取（并按需创建）支付宝 SDK 实例。
+	*
+	* 首次调用时才初始化 SDK，后续复用同一实例；未配置支付宝时抛出
+	* 明确错误。
+	*/
+	getAlipaySdk() {
+		const alipay = this.getAlipayConfig();
+		if (!this.alipaySdk) this.alipaySdk = new AlipaySdk({
+			appId: alipay.appId,
+			privateKey: alipay.privateKey,
+			alipayPublicKey: alipay.publicKey
+		});
+		return this.alipaySdk;
+	}
+	/**
+	* 获取支付宝配置，未配置时抛出错误。
+	*/
+	getAlipayConfig() {
+		if (!this.options.alipay) throw new Error("未配置支付宝(alipay)，无法使用支付宝相关能力");
+		return this.options.alipay;
+	}
+	/**
+	* 获取微信支付配置，未配置时抛出错误。
+	*/
+	getWepayConfig() {
+		if (!this.options.wepay) throw new Error("未配置微信支付(wepay)，无法使用微信支付相关能力");
+		return this.options.wepay;
+	}
+	/**
+	* 生成随机字符串，用于微信支付请求的 `nonce_str` 与支付参数。
+	*
+	* 使用密码学安全的随机字节生成 12 位十六进制字符串。
+	*/
+	generateNonceStr() {
+		return crypto.randomBytes(6).toString("hex");
+	}
+	/**
+	* 微信支付 RSA 签名。
+	*
+	* 将每个字段拼接换行符（`\n`）后使用 `RSA-SHA256` 私钥签名，返回
+	* base64 编码的签名；同一方法同时用于请求头签名与 JSSDK 支付参数
+	* 签名。
+	*
+	* @param data 待签名字段，按顺序依次拼接，每个字段后追加换行符。
+	* @returns base64 编码的签名串。
+	*/
+	wepaySign(data) {
+		return crypto.createSign("RSA-SHA256").update(data.map((v) => `${v}\n`).join("")).sign(this.getWepayConfig().privateKey, "base64");
+	}
+	/**
+	* 微信支付回调数据解密。
+	*
+	* 使用 APIv3 密钥对 `resource` 做 AES-256-GCM 解密：密文末尾 16
+	* 字节为认证标签，前面为加密数据，`nonce` 作为 IV，
+	* `associated_data` 作为附加认证数据。
+	*
+	* @param resource 回调数据中的 `resource` 字段。
+	* @returns 解密后的 JSON 字符串。
+	*/
+	wepayDecrypt(resource) {
+		const ciphertext = Buffer.from(resource.ciphertext, "base64");
+		const authTag = ciphertext.subarray(ciphertext.length - 16);
+		const encryptedData = ciphertext.subarray(0, ciphertext.length - 16);
+		const decipher = crypto.createDecipheriv("aes-256-gcm", Buffer.from(this.getWepayConfig().secretKey, "utf8"), Buffer.from(resource.nonce, "utf8"));
+		decipher.setAuthTag(authTag);
+		decipher.setAAD(Buffer.from(resource.associated_data ?? "", "utf8"));
+		return Buffer.concat([decipher.update(encryptedData), decipher.final()]).toString("utf8");
+	}
+	/**
+	* 发起微信支付 APIv3 请求。
+	*
+	* 根据 URL 计算请求路径，按 `方法\nURL\n时间戳\n随机串\n请求体\n`
+	* 构造签名并生成 `Authorization` 请求头；GET 请求体为空字符串，
+	* POST 请求体为 `data` 的 JSON 字符串。
+	*
+	* @param url 完整请求地址。
+	* @param data 请求体，缺省表示 GET 请求。
+	* @returns 响应数据。
+	*/
+	async wepayRequest(url, data) {
+		const wepay = this.getWepayConfig();
+		const path = url.replace(/^https?:\/\/[^/]+/, "");
+		const method = data == null ? "GET" : "POST";
+		const body = method === "POST" ? JSON.stringify(data) : "";
+		const params = {
+			method,
+			url: path,
+			time: String(Math.round(Date.now() / 1e3)),
+			rand: this.generateNonceStr(),
+			body,
+			signature: ""
+		};
+		params.signature = this.wepaySign([
+			params.method,
+			params.url,
+			params.time,
+			params.rand,
+			params.body
+		]);
+		const Authorization = [
+			`WECHATPAY2-SHA256-RSA2048 `,
+			`mchid="${wepay.merchantId}",`,
+			`nonce_str="${params.rand}",`,
+			`signature="${params.signature}",`,
+			`timestamp="${params.time}",`,
+			`serial_no="${wepay.certificateSerialNumber}"`
+		].join("");
+		const { data: res } = method === "POST" ? await xr.postJson({
+			url,
+			headers: { Authorization },
+			data
+		}) : await xr.getJson({
+			url,
+			headers: { Authorization }
+		});
+		return res;
+	}
+};
+export { XPay };

package/lib/puppeteer.d.mts

@@ -0,0 +1,88 @@
+import { Browser, ElementHandle, Frame, Page } from "puppeteer";
+export type XPuppeteerBrowser = Browser;
+export type XPuppeteerPage = Page;
+export interface XPuppeteerOpenBrowserOptions {
+  /** 是否以有头模式启动浏览器；默认 `false`（无头）。 */
+  headful?: boolean;
+  /** 代理地址，例如 `http://127.0.0.1:7890`。 */
+  proxy?: string;
+  /** 浏览器用户数据目录。 */
+  dataDir?: string;
+}
+export interface XPuppeteerOpenPageOptions {
+  /**
+   * 当目标 URL 已在现有页面中打开时的匹配规则。
+   *
+   * - `string`：匹配 `pathname + search` 是否包含该片段；
+   * - `RegExp`：匹配 `pathname + search`。
+   */
+  match?: string | RegExp;
+  /** 是否拦截图片/字体/样式资源，以提升打开速度。 */
+  blockAssets?: boolean;
+  /** `goto` 时使用的 referer；未传则使用目标 URL。 */
+  referer?: string;
+}
+export interface XPuppeteerGetPageHtmlOptions extends XPuppeteerOpenBrowserOptions, XPuppeteerOpenPageOptions {
+  /** 复用浏览器实例的标识；传入后会命中 memoized 实例。 */
+  instanceId?: string | number;
+  /** 是否连接系统已启动的调试浏览器（默认 `false`）。 */
+  useSystemBrowser?: boolean;
+  /**
+   * 页面打开后的扩展逻辑钩子，例如等待某个 selector 出现再取 HTML。
+   */
+  afterOpenPage?: (payload: {
+    /** 当前 `XPuppeteer` 实例。 */
+    browser: XPuppeteer;
+    /** 已打开的页面实例。 */
+    page: XPuppeteerPage;
+  }) => any;
+}
+export declare class XPuppeteer {
+  browser: Browser;
+  /**
+   * 连接系统中已开启远程调试端口（9222）的浏览器。
+   */
+  connectSystemBrowser(): Promise<XPuppeteerBrowser>;
+  /**
+   * 启动新的浏览器实例并绑定退出钩子。
+   */
+  openBrowser(options?: XPuppeteerOpenBrowserOptions): Promise<XPuppeteerBrowser>;
+  /**
+   * 打开 URL 或直接渲染 HTML。
+   *
+   * 当入参为 URL 时，会优先尝试复用已打开且匹配的页面。
+   */
+  openPage(urlOrHtml: string, options?: XPuppeteerOpenPageOptions): Promise<XPuppeteerPage>;
+  input(page: Page, selector: string, textOrHtml: string, frameIndex?: number): Promise<void>;
+  /**
+   * 在当前激活元素上执行“全选”。
+   */
+  selectAll(page: Page | Frame): Promise<void>;
+  /**
+   * 通过键盘事件执行粘贴（Shift + Insert）。
+   */
+  paste(page: Page): Promise<void>;
+  queryByText<T extends Node = HTMLDivElement>(page: Page, text: string | RegExp | ((el: T) => boolean)): Promise<ElementHandle<T>>;
+  /**
+   * 断开与浏览器的连接（不关闭浏览器进程）。
+   */
+  disconnect(): Promise<void>;
+  /**
+   * 关闭当前浏览器实例。
+   */
+  close(): Promise<void>;
+  /**
+   * 创建并打开浏览器，返回 `XPuppeteer` 实例。
+   */
+  static openBrowser(options?: XPuppeteerOpenBrowserOptions): Promise<XPuppeteer>;
+  /**
+   * 便捷方法：打开页面并返回 `Page`。
+   *
+   * 返回的 `page.close()` 会被替换为关闭整个浏览器实例。
+   */
+  static openPage(urlOrHtml: string, options?: XPuppeteerGetPageHtmlOptions): Promise<XPuppeteerPage>;
+  static getPageHtmlXp: ((options: XPuppeteerGetPageHtmlOptions) => Promise<XPuppeteer>) & {
+    cache: import("vtils").AsyncMemoizeCacheMap;
+  };
+  static getPageHtml(url: string, options?: XPuppeteerGetPageHtmlOptions): Promise<string>;
+}

package/lib/puppeteer.mjs

@@ -0,0 +1,219 @@
+import { XClipboard } from "./clipboard.mjs";
+import { XDispose } from "./dispose.mjs";
+import { xr } from "@jayfong/x-request";
+import { asyncMemoize, isFunction, isRegExp } from "vtils";
+import puppeteer from "puppeteer";
+// src/puppeteer.ts
+var XPuppeteer = class XPuppeteer {
+	browser;
+	/**
+	* 连接系统中已开启远程调试端口（9222）的浏览器。
+	*/
+	async connectSystemBrowser() {
+		const { data: { webSocketDebuggerUrl } } = await xr.getJson({ url: "http://localhost:9222/json/version" });
+		const browser = await puppeteer.connect({
+			browserWSEndpoint: webSocketDebuggerUrl,
+			defaultViewport: {
+				width: 0,
+				height: 0
+			}
+		});
+		this.browser = browser;
+		XDispose.exit.add(() => this.disconnect());
+		return browser;
+	}
+	/**
+	* 启动新的浏览器实例并绑定退出钩子。
+	*/
+	async openBrowser(options = {}) {
+		const browser = await puppeteer.launch({
+			headless: !options.headful,
+			defaultViewport: {
+				width: 1440,
+				height: 900
+			},
+			userDataDir: options.dataDir,
+			args: options.proxy ? [`--proxy-server=${options.proxy}`] : void 0
+		});
+		this.browser = browser;
+		XDispose.exit.add(() => this.close());
+		return browser;
+	}
+	/**
+	* 打开 URL 或直接渲染 HTML。
+	*
+	* 当入参为 URL 时，会优先尝试复用已打开且匹配的页面。
+	*/
+	async openPage(urlOrHtml, options = {}) {
+		const isUrl = /^https?:\/\//i.test(urlOrHtml);
+		const pages = await this.browser.pages();
+		if (isUrl) {
+			const inputUrl = new URL(urlOrHtml);
+			const foundPage = pages.find((item) => {
+				const pageUrl = item.url();
+				if (!/^https?:\/\//i.test(pageUrl)) return false;
+				const url = new URL(pageUrl);
+				return inputUrl.origin === url.origin && (pageUrl === urlOrHtml || !!options.match && (typeof options.match === "string" ? `${url.pathname}${url.search}`.includes(options.match) : options.match.test(`${url.pathname}${url.search}`)));
+			});
+			if (foundPage) return foundPage;
+		}
+		const page = await this.browser.newPage();
+		await page.setUserAgent("Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/87.0.4280.88 Safari/537.36");
+		if (options.blockAssets) {
+			await page.setRequestInterception(true);
+			page.on("request", (req) => {
+				const resourceType = req.resourceType();
+				if (resourceType === "stylesheet" || resourceType === "font" || resourceType === "image") req.abort();
+				else req.continue();
+			});
+		}
+		if (isUrl) await page.goto(urlOrHtml, { referer: options.referer || urlOrHtml });
+		else await page.setContent(urlOrHtml);
+		return page;
+	}
+	async input(page, selector, textOrHtml, frameIndex) {
+		const mainPage = page;
+		const keyboard = page.keyboard;
+		let queryRoot = page;
+		if (frameIndex != null) {
+			const frame = page.frames()[frameIndex];
+			if (!frame) throw new Error(`Frame 不存在: ${frameIndex}`);
+			queryRoot = frame;
+		}
+		const el = await queryRoot.$(selector);
+		if (!el) throw new Error(`未找到输入元素: ${selector}`);
+		if (await el.evaluate((el) => {
+			return el.tagName === "INPUT" || el.tagName === "TEXTAREA" || el.tagName === "SPAN";
+		})) await XClipboard.writeText(textOrHtml);
+		else await XClipboard.writeHtml(textOrHtml);
+		await el.click();
+		await this.selectAll(queryRoot);
+		await keyboard.press("Backspace");
+		await this.paste(mainPage);
+	}
+	/**
+	* 在当前激活元素上执行“全选”。
+	*/
+	async selectAll(page) {
+		await page.evaluate(() => {
+			const isMac = /Mac|iPod|iPhone|iPad/.test(window.navigator.platform);
+			document.activeElement.dispatchEvent(new KeyboardEvent("keydown", {
+				bubbles: true,
+				cancelable: true,
+				key: isMac ? "Meta" : "Control",
+				code: isMac ? "MetaLeft" : "ControlLeft",
+				location: window.KeyboardEvent.DOM_KEY_LOCATION_LEFT,
+				getModifierState: (keyArg) => keyArg === (isMac ? "Meta" : "Control"),
+				ctrlKey: !isMac,
+				metaKey: isMac,
+				charCode: 0,
+				keyCode: isMac ? 93 : 17,
+				which: isMac ? 93 : 17
+			}));
+			const preventableEvent = new KeyboardEvent("keydown", {
+				bubbles: true,
+				cancelable: true,
+				key: "a",
+				code: "KeyA",
+				location: window.KeyboardEvent.DOM_KEY_LOCATION_STANDARD,
+				getModifierState: (keyArg) => keyArg === (isMac ? "Meta" : "Control"),
+				ctrlKey: !isMac,
+				metaKey: isMac,
+				charCode: 0,
+				keyCode: 65,
+				which: 65
+			});
+			if (!(!document.activeElement.dispatchEvent(preventableEvent) || preventableEvent.defaultPrevented)) document.execCommand("selectall", false, null);
+			document.activeElement.dispatchEvent(new KeyboardEvent("keyup", {
+				bubbles: true,
+				cancelable: true,
+				key: isMac ? "Meta" : "Control",
+				code: isMac ? "MetaLeft" : "ControlLeft",
+				location: window.KeyboardEvent.DOM_KEY_LOCATION_LEFT,
+				getModifierState: () => false,
+				charCode: 0,
+				keyCode: isMac ? 93 : 17,
+				which: isMac ? 93 : 17
+			}));
+		});
+	}
+	/**
+	* 通过键盘事件执行粘贴（Shift + Insert）。
+	*/
+	async paste(page) {
+		await page.keyboard.down("Shift");
+		await page.keyboard.press("Insert");
+		await page.keyboard.up("Shift");
+	}
+	async queryByText(page, text) {
+		const el = await page.evaluateHandle((text, isRegExp, isFunction) => {
+			const textRe = isRegExp ? (() => {
+				const m = text.match(/^\/(.+)\/([^/]*)$/);
+				return new RegExp(m[1], m[2] || void 0);
+			})() : void 0;
+			const textFn = isFunction ? eval(`(() => {return ${text}})()`) : void 0;
+			const walker = document.createTreeWalker(document.body, NodeFilter.SHOW_TEXT, { acceptNode: (node) => {
+				return (isRegExp ? textRe.test(node.textContent) : isFunction ? textFn(node) : node.textContent.includes(text)) ? NodeFilter.FILTER_ACCEPT : NodeFilter.FILTER_REJECT;
+			} });
+			walker.nextNode();
+			return walker.currentNode.parentElement;
+		}, String(text), isRegExp(text), isFunction(text));
+		return el;
+	}
+	/**
+	* 断开与浏览器的连接（不关闭浏览器进程）。
+	*/
+	async disconnect() {
+		await this.browser.disconnect();
+	}
+	/**
+	* 关闭当前浏览器实例。
+	*/
+	async close() {
+		await this.browser.close();
+	}
+	/**
+	* 创建并打开浏览器，返回 `XPuppeteer` 实例。
+	*/
+	static async openBrowser(options = {}) {
+		const xp = new XPuppeteer();
+		await xp.openBrowser(options);
+		return xp;
+	}
+	/**
+	* 便捷方法：打开页面并返回 `Page`。
+	*
+	* 返回的 `page.close()` 会被替换为关闭整个浏览器实例。
+	*/
+	static async openPage(urlOrHtml, options = {}) {
+		const xp = new XPuppeteer();
+		await xp.openBrowser(options);
+		const page = await xp.openPage(urlOrHtml, options);
+		page.close = () => xp.close();
+		return page;
+	}
+	static getPageHtmlXp = asyncMemoize(async (options) => {
+		const xp = new XPuppeteer();
+		await (options.useSystemBrowser ? xp.connectSystemBrowser() : xp.openBrowser(options));
+		return xp;
+	}, { cacheKey: (options) => options.instanceId });
+	static async getPageHtml(url, options = {}) {
+		const hasInstanceId = !!options.instanceId;
+		options.instanceId ||= Date.now();
+		const xp = await XPuppeteer.getPageHtmlXp(options);
+		try {
+			const page = await xp.openPage(url, options);
+			if (options.afterOpenPage) await options.afterOpenPage({
+				browser: xp,
+				page
+			});
+			return await page.content();
+		} finally {
+			if (!hasInstanceId) {
+				if (options.useSystemBrowser) await xp.disconnect();
+				else await xp.close();
+			}
+		}
+	}
+};
+export { XPuppeteer };