@vobs/payment 0.3.0 → 1.2.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 vobsjs
+Copyright (c) 2026 vobs contributors
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -0,0 +1,182 @@
+# @vobs/payment
+
+Payment integration SDK for the vobs framework: Alipay and WeChat payment adapters built on top of the official SDKs (alipay-sdk, wechatpay-axios-plugin), with vobs plugin registration support.
+
+## Install
+
+```bash
+npm install @vobs/payment alipay-sdk wechatpay-axios-plugin
+```
+
+## Exports
+
+- `@vobs/payment/alipay` / `@vobs/payment/wechat`: provider-scoped imports (recommended).
+- `@vobs/payment` root: flat exports of provider-unique symbols (`AlipayClient`, `wechatPlugin`, `WechatApiError`, ...) plus `alipay` / `wechat` namespaces for the shared factories (`createRefund`, `createNotifyHandler`, ...) whose names collide across providers.
+
+## Quick start
+
+### Standalone usage (without vobs framework)
+
+```ts
+import { AlipayClient, createPagePay } from '@vobs/payment/alipay'
+
+const client = new AlipayClient({
+  appId: '202100...',
+  privateKey: '-----BEGIN PRIVATE KEY-----\n...',
+  alipayPublicKey: '-----BEGIN PUBLIC KEY-----\n...',
+  notifyUrl: 'https://your-domain.com/alipay/notify',
+  returnUrl: 'https://your-domain.com/order/123'
+})
+
+const pagePay = createPagePay(client)
+
+const { formHtml } = await pagePay.pay({
+  outTradeNo: 'ORDER2026090812345678',
+  totalAmount: '99.00',
+  subject: 'Premium Subscription'
+})
+```
+
+### With vobs plugin
+
+```ts
+import { createVobs } from '@vobs/vobs'
+import { alipayPlugin, useAlipay } from '@vobs/payment'
+
+const app = createVobs({
+  render: App,
+  plugins: [
+    alipayPlugin({
+      config: {
+        appId: '202100...',
+        privateKey: '...',
+        alipayPublicKey: '...',
+        notifyUrl: 'https://your-domain.com/alipay/notify'
+      }
+    })
+  ]
+})
+
+// In your component:
+function CheckoutButton() {
+  const alipay = useAlipay()
+  const handlePay = async () => {
+    const { formHtml } = await alipay.pay({
+      outTradeNo: 'ORDER...',
+      totalAmount: '99.00',
+      subject: 'Premium Subscription'
+    })
+    // Render formHtml to redirect to Alipay
+  }
+  return <button onClick={handlePay}>Pay with Alipay</button>
+}
+```
+
+## API
+
+### Alipay
+
+| Signature | Description |
+| --- | --- |
+| `AlipayClient(options)` | Wraps the official `AlipaySdk` instance with config validation and disposal. `client.sdk` exposes the underlying SDK. |
+| `AlipayConfig` | Validated configuration: `appId`, `privateKey`, `alipayPublicKey`, `gateway`, `notifyUrl`, `returnUrl`, `keyType`, `timeout`. `AlipayConfig.forSandbox()` presets the sandbox gateway. |
+| `createPagePay(client)` | Computer website payment (`alipay.trade.page.pay`). Returns the POST form HTML via `pageExecute()`. |
+| `createQuery(client)` | Trade query (`alipay.trade.query`) with `isSuccessful()` helper. |
+| `createRefund(client)` | Refund lifecycle: `refund()` (`alipay.trade.refund`), `queryRefund()` (`alipay.trade.fastpay.refund.query`), `close()` (`alipay.trade.close`). |
+| `createNotifyHandler(client)` | Async notification helpers: `verify(params, raw?)` signature check, `validate(params, expected?)` business-field check, `successResponse()` / `failResponse()`. |
+| `alipayPlugin(options)` | Vobs plugin that registers the Alipay client in the plugin context. Disposes only self-created clients on uninstall. |
+| `useAlipay()` | Returns the Alipay client from the vobs plugin context. |
+
+### Error handling
+
+All gateway calls (`query`, `refund`, `queryRefund`, `close`) throw `AlipayApiError` when Alipay responds with a non-`10000` business code (e.g. `ACQ.TRADE_NOT_EXIST`):
+
+```ts
+import { AlipayApiError } from '@vobs/payment/alipay'
+
+try {
+  const result = await query.query({ outTradeNo: 'ORDER...' })
+} catch (error) {
+  if (error instanceof AlipayApiError) {
+    error.code    // e.g. '40004'
+    error.subCode // e.g. 'ACQ.TRADE_NOT_EXIST'
+    error.subMsg  // human-readable reason
+  }
+}
+```
+
+For async notifications, signature verification only proves the notification came from Alipay — always validate it against your own order records:
+
+```ts
+const notify = createNotifyHandler(client)
+
+if (!notify.verify(params, true) /* raw mode recommended */) {
+  return notify.failResponse()
+}
+
+const check = notify.validate(params, {
+  outTradeNo: 'ORDER...',   // from your order store
+  totalAmount: '99.00'
+})
+if (!check.valid) {
+  return notify.failResponse()
+}
+
+// Idempotent business handling is the caller's responsibility (dedupe by notifyId).
+return notify.successResponse() // exactly "success"
+```
+
+### WeChat
+
+| Signature | Description |
+| --- | --- |
+| `WechatClient(options)` | Wraps the official `wechatpay-axios-plugin` `Wechatpay` instance (`mchid`, `serial`, `privateKey`, `certs`, `appid`, `apiv3Key`, `notifyUrl`). `client.sdk` exposes the chained API. |
+| `WechatConfig` | Validated configuration; `apiv3Key` must be a 32-byte string. |
+| `createPayment(client)` | `jsapiPay()` (JSAPI / mini-program, returns signed `wx.requestPayment` params), `appPay()` (APP SDK params), `nativePay()` (returns `codeUrl` QR link), `h5Pay()` (returns `h5Url`, requires `payerClientIp`), `query()` by `outTradeNo` or `transactionId`. |
+| `createRefund(client)` | `refund()` (`POST /v3/refund/domestic/refunds`), `queryRefund()` by `outRefundNo` or `refundId`. |
+| `createNotifyHandler(client)` | `verify(headers, body)` (platform-cert / public-key signature check on the RAW body), `decrypt(resource)` (AES-256-GCM with `apiv3Key`), `validate(payload, expected)`, `successResponse()` / `failResponse()`. |
+| `wechatPlugin(options)` / `useWechat()` | Vobs plugin registering the WeChat client; disposes only self-created clients. |
+
+#### Error handling
+
+Gateway failures throw `WechatApiError` with `status` (HTTP code) and `code` (e.g. `PARAM_ERROR`, `RESOURCE_NOT_EXISTS`):
+
+```ts
+import { WechatApiError } from '@vobs/payment'
+
+try {
+  const result = await payment.jsapiPay({ outTradeNo: 'ORDER...', description: '...', amount: { total: 9900 }, openid: '...' })
+} catch (error) {
+  if (error instanceof WechatApiError) {
+    error.status // e.g. 400
+    error.code   // e.g. 'PARAM_ERROR'
+  }
+}
+```
+
+Notifications require signature verification on the **raw** body plus merchant-side order matching:
+
+```ts
+import { createNotifyHandler } from '@vobs/payment/wechat'
+
+const notify = createNotifyHandler(wechatClient)
+
+if (!notify.verify(headers, rawBody)) {
+  return notify.failResponse('签名校验失败')
+}
+
+const payload = notify.decrypt(resource)
+const check = notify.validate(payload, { outTradeNo: 'ORDER...', total: 9900 })
+if (!check.valid) {
+  return notify.failResponse(check.errors.join('; '))
+}
+
+// Idempotent business handling is the caller's responsibility (dedupe by notification id).
+return notify.successResponse() // {"code":"SUCCESS"}
+```
+
+Amounts in the WeChat v3 API are integers in **fen** (分).
+
+## Types
+
+AlipayClientOptions, AlipayKeyType, TradeStatus, AlipayPagePayConfig, AlipayPagePayParams, AlipayPagePayResult, AlipayQueryParams, AlipayQueryResult, AlipayRefundParams, AlipayRefundResult, AlipayRefundQueryParams, AlipayRefundQueryResult, AlipayCloseParams, AlipayCloseResult, AlipayNotifyParams, AlipayPluginOptions

package/dist/alipay/client.cjs

@@ -0,0 +1,112 @@
+'use strict';
+
+var alipaySdk = require('alipay-sdk');
+
+var __defProp = Object.defineProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+
+// packages/payment/src/alipay/config.ts
+var _AlipayConfig = class _AlipayConfig {
+  constructor(options) {
+    this.validate(options);
+    this._options = { ...options };
+  }
+  /** 获取完整配置 */
+  get options() {
+    return this._options;
+  }
+  /** 应用 ID */
+  get appId() {
+    return this._options.appId;
+  }
+  /** 网关地址 */
+  get gateway() {
+    return this._options.gateway ?? "https://openapi.alipay.com/gateway.do";
+  }
+  /** 异步通知地址 */
+  get notifyUrl() {
+    return this._options.notifyUrl;
+  }
+  /** 同步跳转地址 */
+  get returnUrl() {
+    return this._options.returnUrl;
+  }
+  /** 更新配置（部分更新） */
+  update(patch) {
+    const merged = { ...this._options, ...patch };
+    this.validate(merged);
+    this._options = merged;
+  }
+  /** 替换配置 */
+  replace(options) {
+    this.validate(options);
+    this._options = { ...options };
+  }
+  /** 创建沙箱配置的快捷方法 */
+  static forSandbox(options) {
+    return new _AlipayConfig({
+      ...options,
+      gateway: "https://openapi-sandbox.dl.alipaydev.com/gateway.do"
+    });
+  }
+  validate(options) {
+    if (!options.appId) {
+      throw new Error("AlipayConfig: appId \u4E0D\u80FD\u4E3A\u7A7A");
+    }
+    if (!options.privateKey) {
+      throw new Error("AlipayConfig: privateKey \u4E0D\u80FD\u4E3A\u7A7A");
+    }
+    if (!options.alipayPublicKey) {
+      throw new Error("AlipayConfig: alipayPublicKey \u4E0D\u80FD\u4E3A\u7A7A");
+    }
+  }
+};
+__name(_AlipayConfig, "AlipayConfig");
+var AlipayConfig = _AlipayConfig;
+
+// packages/payment/src/alipay/client.ts
+var _AlipayClient = class _AlipayClient {
+  constructor(options) {
+    this._disposed = false;
+    this.config = new AlipayConfig(options);
+    this._sdk = this.createSdk(options);
+  }
+  /** 获取底层 AlipaySdk 实例 */
+  get sdk() {
+    this.ensureActive();
+    return this._sdk;
+  }
+  /** 更新配置并重建 SDK 实例 */
+  updateConfig(patch) {
+    this.ensureActive();
+    this.config.update(patch);
+    this._sdk = this.createSdk(this.config.options);
+  }
+  /** 销毁客户端 */
+  dispose() {
+    this._disposed = true;
+    this._sdk = null;
+  }
+  createSdk(options) {
+    return new alipaySdk.AlipaySdk({
+      appId: options.appId,
+      privateKey: options.privateKey,
+      alipayPublicKey: options.alipayPublicKey,
+      signType: options.signType ?? "RSA2",
+      gateway: options.gateway,
+      timeout: options.timeout ?? 5e3,
+      keyType: options.keyType ?? "PKCS1"
+    });
+  }
+  ensureActive() {
+    if (this._disposed) {
+      throw new Error("AlipayClient: \u5BA2\u6237\u7AEF\u5DF2\u9500\u6BC1");
+    }
+  }
+};
+__name(_AlipayClient, "AlipayClient");
+var AlipayClient = _AlipayClient;
+
+exports.AlipayClient = AlipayClient;
+//# sourceMappingURL=client.cjs.map
+//# sourceMappingURL=client.cjs.map

package/dist/alipay/client.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/alipay/config.ts","../../src/alipay/client.ts"],"names":["AlipaySdk"],"mappings":"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","file":"client.cjs","sourcesContent":["import type { AlipayClientOptions } from './types'\n\n/**\n * 支付宝配置管理\n * 遵循 vobs 生命周期管理：可创建、可销毁、可替换\n */\nexport class AlipayConfig {\n  private _options: AlipayClientOptions\n\n  constructor(options: AlipayClientOptions) {\n    this.validate(options)\n    this._options = { ...options }\n  }\n\n  /** 获取完整配置 */\n  get options(): Readonly<AlipayClientOptions> {\n    return this._options\n  }\n\n  /** 应用 ID */\n  get appId(): string {\n    return this._options.appId\n  }\n\n  /** 网关地址 */\n  get gateway(): string {\n    return this._options.gateway ?? 'https://openapi.alipay.com/gateway.do'\n  }\n\n  /** 异步通知地址 */\n  get notifyUrl(): string | undefined {\n    return this._options.notifyUrl\n  }\n\n  /** 同步跳转地址 */\n  get returnUrl(): string | undefined {\n    return this._options.returnUrl\n  }\n\n  /** 更新配置（部分更新） */\n  update(patch: Partial<AlipayClientOptions>): void {\n    const merged = { ...this._options, ...patch }\n    this.validate(merged)\n    this._options = merged\n  }\n\n  /** 替换配置 */\n  replace(options: AlipayClientOptions): void {\n    this.validate(options)\n    this._options = { ...options }\n  }\n\n  /** 创建沙箱配置的快捷方法 */\n  static forSandbox(options: Omit<AlipayClientOptions, 'gateway'>): AlipayConfig {\n    return new AlipayConfig({\n      ...options,\n      gateway: 'https://openapi-sandbox.dl.alipaydev.com/gateway.do'\n    })\n  }\n\n  private validate(options: AlipayClientOptions): void {\n    if (!options.appId) {\n      throw new Error('AlipayConfig: appId 不能为空')\n    }\n    if (!options.privateKey) {\n      throw new Error('AlipayConfig: privateKey 不能为空')\n    }\n    if (!options.alipayPublicKey) {\n      throw new Error('AlipayConfig: alipayPublicKey 不能为空')\n    }\n  }\n}","import { AlipaySdk } from 'alipay-sdk'\nimport { AlipayConfig } from './config'\nimport type { AlipayClientOptions, AlipayKeyType } from './types'\n\n/**\n * 支付宝客户端封装\n *\n * 封装 alipay-sdk 的 AlipaySdk 实例，提供统一的生命周期管理。\n * 可独立使用，也可通过 alipayPlugin 注册到 vobs 框架。\n *\n * @example\n * ```ts\n * const client = new AlipayClient({\n *   appId: '202100...',\n *   privateKey: '...',\n *   alipayPublicKey: '...',\n *   gateway: 'https://openapi-sandbox.dl.alipaydev.com/gateway.do'\n * })\n * ```\n */\nexport class AlipayClient {\n  readonly config: AlipayConfig\n  private _sdk: AlipaySdk\n  private _disposed = false\n\n  constructor(options: AlipayClientOptions) {\n    this.config = new AlipayConfig(options)\n    this._sdk = this.createSdk(options)\n  }\n\n  /** 获取底层 AlipaySdk 实例 */\n  get sdk(): AlipaySdk {\n    this.ensureActive()\n    return this._sdk\n  }\n\n  /** 更新配置并重建 SDK 实例 */\n  updateConfig(patch: Partial<AlipayClientOptions>): void {\n    this.ensureActive()\n    this.config.update(patch)\n    this._sdk = this.createSdk(this.config.options as AlipayClientOptions)\n  }\n\n  /** 销毁客户端 */\n  dispose(): void {\n    this._disposed = true\n    ;(this._sdk as any) = null\n  }\n\n  private createSdk(options: AlipayClientOptions): AlipaySdk {\n    return new AlipaySdk({\n      appId: options.appId,\n      privateKey: options.privateKey,\n      alipayPublicKey: options.alipayPublicKey,\n      signType: options.signType ?? 'RSA2',\n      gateway: options.gateway,\n      timeout: options.timeout ?? 5000,\n      keyType: (options.keyType ?? 'PKCS1') as AlipayKeyType\n    })\n  }\n\n  private ensureActive(): void {\n    if (this._disposed) {\n      throw new Error('AlipayClient: 客户端已销毁')\n    }\n  }\n}"]}

package/dist/alipay/client.d.cts

@@ -0,0 +1,36 @@
+import { AlipaySdk } from 'alipay-sdk';
+import { AlipayConfig } from './config.cjs';
+import { AlipayClientOptions } from './types.cjs';
+
+/**
+ * 支付宝客户端封装
+ *
+ * 封装 alipay-sdk 的 AlipaySdk 实例，提供统一的生命周期管理。
+ * 可独立使用，也可通过 alipayPlugin 注册到 vobs 框架。
+ *
+ * @example
+ * ```ts
+ * const client = new AlipayClient({
+ *   appId: '202100...',
+ *   privateKey: '...',
+ *   alipayPublicKey: '...',
+ *   gateway: 'https://openapi-sandbox.dl.alipaydev.com/gateway.do'
+ * })
+ * ```
+ */
+declare class AlipayClient {
+    readonly config: AlipayConfig;
+    private _sdk;
+    private _disposed;
+    constructor(options: AlipayClientOptions);
+    /** 获取底层 AlipaySdk 实例 */
+    get sdk(): AlipaySdk;
+    /** 更新配置并重建 SDK 实例 */
+    updateConfig(patch: Partial<AlipayClientOptions>): void;
+    /** 销毁客户端 */
+    dispose(): void;
+    private createSdk;
+    private ensureActive;
+}
+
+export { AlipayClient };

package/dist/alipay/client.d.ts

@@ -0,0 +1,36 @@
+import { AlipaySdk } from 'alipay-sdk';
+import { AlipayConfig } from './config.js';
+import { AlipayClientOptions } from './types.js';
+
+/**
+ * 支付宝客户端封装
+ *
+ * 封装 alipay-sdk 的 AlipaySdk 实例，提供统一的生命周期管理。
+ * 可独立使用，也可通过 alipayPlugin 注册到 vobs 框架。
+ *
+ * @example
+ * ```ts
+ * const client = new AlipayClient({
+ *   appId: '202100...',
+ *   privateKey: '...',
+ *   alipayPublicKey: '...',
+ *   gateway: 'https://openapi-sandbox.dl.alipaydev.com/gateway.do'
+ * })
+ * ```
+ */
+declare class AlipayClient {
+    readonly config: AlipayConfig;
+    private _sdk;
+    private _disposed;
+    constructor(options: AlipayClientOptions);
+    /** 获取底层 AlipaySdk 实例 */
+    get sdk(): AlipaySdk;
+    /** 更新配置并重建 SDK 实例 */
+    updateConfig(patch: Partial<AlipayClientOptions>): void;
+    /** 销毁客户端 */
+    dispose(): void;
+    private createSdk;
+    private ensureActive;
+}
+
+export { AlipayClient };

package/dist/alipay/client.js

@@ -0,0 +1,110 @@
+import { AlipaySdk } from 'alipay-sdk';
+
+var __defProp = Object.defineProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+
+// packages/payment/src/alipay/config.ts
+var _AlipayConfig = class _AlipayConfig {
+  constructor(options) {
+    this.validate(options);
+    this._options = { ...options };
+  }
+  /** 获取完整配置 */
+  get options() {
+    return this._options;
+  }
+  /** 应用 ID */
+  get appId() {
+    return this._options.appId;
+  }
+  /** 网关地址 */
+  get gateway() {
+    return this._options.gateway ?? "https://openapi.alipay.com/gateway.do";
+  }
+  /** 异步通知地址 */
+  get notifyUrl() {
+    return this._options.notifyUrl;
+  }
+  /** 同步跳转地址 */
+  get returnUrl() {
+    return this._options.returnUrl;
+  }
+  /** 更新配置（部分更新） */
+  update(patch) {
+    const merged = { ...this._options, ...patch };
+    this.validate(merged);
+    this._options = merged;
+  }
+  /** 替换配置 */
+  replace(options) {
+    this.validate(options);
+    this._options = { ...options };
+  }
+  /** 创建沙箱配置的快捷方法 */
+  static forSandbox(options) {
+    return new _AlipayConfig({
+      ...options,
+      gateway: "https://openapi-sandbox.dl.alipaydev.com/gateway.do"
+    });
+  }
+  validate(options) {
+    if (!options.appId) {
+      throw new Error("AlipayConfig: appId \u4E0D\u80FD\u4E3A\u7A7A");
+    }
+    if (!options.privateKey) {
+      throw new Error("AlipayConfig: privateKey \u4E0D\u80FD\u4E3A\u7A7A");
+    }
+    if (!options.alipayPublicKey) {
+      throw new Error("AlipayConfig: alipayPublicKey \u4E0D\u80FD\u4E3A\u7A7A");
+    }
+  }
+};
+__name(_AlipayConfig, "AlipayConfig");
+var AlipayConfig = _AlipayConfig;
+
+// packages/payment/src/alipay/client.ts
+var _AlipayClient = class _AlipayClient {
+  constructor(options) {
+    this._disposed = false;
+    this.config = new AlipayConfig(options);
+    this._sdk = this.createSdk(options);
+  }
+  /** 获取底层 AlipaySdk 实例 */
+  get sdk() {
+    this.ensureActive();
+    return this._sdk;
+  }
+  /** 更新配置并重建 SDK 实例 */
+  updateConfig(patch) {
+    this.ensureActive();
+    this.config.update(patch);
+    this._sdk = this.createSdk(this.config.options);
+  }
+  /** 销毁客户端 */
+  dispose() {
+    this._disposed = true;
+    this._sdk = null;
+  }
+  createSdk(options) {
+    return new AlipaySdk({
+      appId: options.appId,
+      privateKey: options.privateKey,
+      alipayPublicKey: options.alipayPublicKey,
+      signType: options.signType ?? "RSA2",
+      gateway: options.gateway,
+      timeout: options.timeout ?? 5e3,
+      keyType: options.keyType ?? "PKCS1"
+    });
+  }
+  ensureActive() {
+    if (this._disposed) {
+      throw new Error("AlipayClient: \u5BA2\u6237\u7AEF\u5DF2\u9500\u6BC1");
+    }
+  }
+};
+__name(_AlipayClient, "AlipayClient");
+var AlipayClient = _AlipayClient;
+
+export { AlipayClient };
+//# sourceMappingURL=client.js.map
+//# sourceMappingURL=client.js.map

package/dist/alipay/client.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/alipay/config.ts","../../src/alipay/client.ts"],"names":[],"mappings":";;;;;;AAMO,IAAM,aAAA,GAAN,MAAM,aAAA,CAAa;AAAA,EAGxB,YAAY,OAAA,EAA8B;AACxC,IAAA,IAAA,CAAK,SAAS,OAAO,CAAA;AACrB,IAAA,IAAA,CAAK,QAAA,GAAW,EAAE,GAAG,OAAA,EAAQ;AAAA,EAC/B;AAAA;AAAA,EAGA,IAAI,OAAA,GAAyC;AAC3C,IAAA,OAAO,IAAA,CAAK,QAAA;AAAA,EACd;AAAA;AAAA,EAGA,IAAI,KAAA,GAAgB;AAClB,IAAA,OAAO,KAAK,QAAA,CAAS,KAAA;AAAA,EACvB;AAAA;AAAA,EAGA,IAAI,OAAA,GAAkB;AACpB,IAAA,OAAO,IAAA,CAAK,SAAS,OAAA,IAAW,uCAAA;AAAA,EAClC;AAAA;AAAA,EAGA,IAAI,SAAA,GAAgC;AAClC,IAAA,OAAO,KAAK,QAAA,CAAS,SAAA;AAAA,EACvB;AAAA;AAAA,EAGA,IAAI,SAAA,GAAgC;AAClC,IAAA,OAAO,KAAK,QAAA,CAAS,SAAA;AAAA,EACvB;AAAA;AAAA,EAGA,OAAO,KAAA,EAA2C;AAChD,IAAA,MAAM,SAAS,EAAE,GAAG,IAAA,CAAK,QAAA,EAAU,GAAG,KAAA,EAAM;AAC5C,IAAA,IAAA,CAAK,SAAS,MAAM,CAAA;AACpB,IAAA,IAAA,CAAK,QAAA,GAAW,MAAA;AAAA,EAClB;AAAA;AAAA,EAGA,QAAQ,OAAA,EAAoC;AAC1C,IAAA,IAAA,CAAK,SAAS,OAAO,CAAA;AACrB,IAAA,IAAA,CAAK,QAAA,GAAW,EAAE,GAAG,OAAA,EAAQ;AAAA,EAC/B;AAAA;AAAA,EAGA,OAAO,WAAW,OAAA,EAA6D;AAC7E,IAAA,OAAO,IAAI,aAAA,CAAa;AAAA,MACtB,GAAG,OAAA;AAAA,MACH,OAAA,EAAS;AAAA,KACV,CAAA;AAAA,EACH;AAAA,EAEQ,SAAS,OAAA,EAAoC;AACnD,IAAA,IAAI,CAAC,QAAQ,KAAA,EAAO;AAClB,MAAA,MAAM,IAAI,MAAM,8CAA0B,CAAA;AAAA,IAC5C;AACA,IAAA,IAAI,CAAC,QAAQ,UAAA,EAAY;AACvB,MAAA,MAAM,IAAI,MAAM,mDAA+B,CAAA;AAAA,IACjD;AACA,IAAA,IAAI,CAAC,QAAQ,eAAA,EAAiB;AAC5B,MAAA,MAAM,IAAI,MAAM,wDAAoC,CAAA;AAAA,IACtD;AAAA,EACF;AACF,CAAA;AAjE0B,MAAA,CAAA,aAAA,EAAA,cAAA,CAAA;AAAnB,IAAM,YAAA,GAAN,aAAA;;;ACcA,IAAM,aAAA,GAAN,MAAM,aAAA,CAAa;AAAA,EAKxB,YAAY,OAAA,EAA8B;AAF1C,IAAA,IAAA,CAAQ,SAAA,GAAY,KAAA;AAGlB,IAAA,IAAA,CAAK,MAAA,GAAS,IAAI,YAAA,CAAa,OAAO,CAAA;AACtC,IAAA,IAAA,CAAK,IAAA,GAAO,IAAA,CAAK,SAAA,CAAU,OAAO,CAAA;AAAA,EACpC;AAAA;AAAA,EAGA,IAAI,GAAA,GAAiB;AACnB,IAAA,IAAA,CAAK,YAAA,EAAa;AAClB,IAAA,OAAO,IAAA,CAAK,IAAA;AAAA,EACd;AAAA;AAAA,EAGA,aAAa,KAAA,EAA2C;AACtD,IAAA,IAAA,CAAK,YAAA,EAAa;AAClB,IAAA,IAAA,CAAK,MAAA,CAAO,OAAO,KAAK,CAAA;AACxB,IAAA,IAAA,CAAK,IAAA,GAAO,IAAA,CAAK,SAAA,CAAU,IAAA,CAAK,OAAO,OAA8B,CAAA;AAAA,EACvE;AAAA;AAAA,EAGA,OAAA,GAAgB;AACd,IAAA,IAAA,CAAK,SAAA,GAAY,IAAA;AAChB,IAAC,KAAK,IAAA,GAAe,IAAA;AAAA,EACxB;AAAA,EAEQ,UAAU,OAAA,EAAyC;AACzD,IAAA,OAAO,IAAI,SAAA,CAAU;AAAA,MACnB,OAAO,OAAA,CAAQ,KAAA;AAAA,MACf,YAAY,OAAA,CAAQ,UAAA;AAAA,MACpB,iBAAiB,OAAA,CAAQ,eAAA;AAAA,MACzB,QAAA,EAAU,QAAQ,QAAA,IAAY,MAAA;AAAA,MAC9B,SAAS,OAAA,CAAQ,OAAA;AAAA,MACjB,OAAA,EAAS,QAAQ,OAAA,IAAW,GAAA;AAAA,MAC5B,OAAA,EAAU,QAAQ,OAAA,IAAW;AAAA,KAC9B,CAAA;AAAA,EACH;AAAA,EAEQ,YAAA,GAAqB;AAC3B,IAAA,IAAI,KAAK,SAAA,EAAW;AAClB,MAAA,MAAM,IAAI,MAAM,oDAAsB,CAAA;AAAA,IACxC;AAAA,EACF;AACF,CAAA;AA9C0B,MAAA,CAAA,aAAA,EAAA,cAAA,CAAA;AAAnB,IAAM,YAAA,GAAN","file":"client.js","sourcesContent":["import type { AlipayClientOptions } from './types'\n\n/**\n * 支付宝配置管理\n * 遵循 vobs 生命周期管理：可创建、可销毁、可替换\n */\nexport class AlipayConfig {\n  private _options: AlipayClientOptions\n\n  constructor(options: AlipayClientOptions) {\n    this.validate(options)\n    this._options = { ...options }\n  }\n\n  /** 获取完整配置 */\n  get options(): Readonly<AlipayClientOptions> {\n    return this._options\n  }\n\n  /** 应用 ID */\n  get appId(): string {\n    return this._options.appId\n  }\n\n  /** 网关地址 */\n  get gateway(): string {\n    return this._options.gateway ?? 'https://openapi.alipay.com/gateway.do'\n  }\n\n  /** 异步通知地址 */\n  get notifyUrl(): string | undefined {\n    return this._options.notifyUrl\n  }\n\n  /** 同步跳转地址 */\n  get returnUrl(): string | undefined {\n    return this._options.returnUrl\n  }\n\n  /** 更新配置（部分更新） */\n  update(patch: Partial<AlipayClientOptions>): void {\n    const merged = { ...this._options, ...patch }\n    this.validate(merged)\n    this._options = merged\n  }\n\n  /** 替换配置 */\n  replace(options: AlipayClientOptions): void {\n    this.validate(options)\n    this._options = { ...options }\n  }\n\n  /** 创建沙箱配置的快捷方法 */\n  static forSandbox(options: Omit<AlipayClientOptions, 'gateway'>): AlipayConfig {\n    return new AlipayConfig({\n      ...options,\n      gateway: 'https://openapi-sandbox.dl.alipaydev.com/gateway.do'\n    })\n  }\n\n  private validate(options: AlipayClientOptions): void {\n    if (!options.appId) {\n      throw new Error('AlipayConfig: appId 不能为空')\n    }\n    if (!options.privateKey) {\n      throw new Error('AlipayConfig: privateKey 不能为空')\n    }\n    if (!options.alipayPublicKey) {\n      throw new Error('AlipayConfig: alipayPublicKey 不能为空')\n    }\n  }\n}","import { AlipaySdk } from 'alipay-sdk'\nimport { AlipayConfig } from './config'\nimport type { AlipayClientOptions, AlipayKeyType } from './types'\n\n/**\n * 支付宝客户端封装\n *\n * 封装 alipay-sdk 的 AlipaySdk 实例，提供统一的生命周期管理。\n * 可独立使用，也可通过 alipayPlugin 注册到 vobs 框架。\n *\n * @example\n * ```ts\n * const client = new AlipayClient({\n *   appId: '202100...',\n *   privateKey: '...',\n *   alipayPublicKey: '...',\n *   gateway: 'https://openapi-sandbox.dl.alipaydev.com/gateway.do'\n * })\n * ```\n */\nexport class AlipayClient {\n  readonly config: AlipayConfig\n  private _sdk: AlipaySdk\n  private _disposed = false\n\n  constructor(options: AlipayClientOptions) {\n    this.config = new AlipayConfig(options)\n    this._sdk = this.createSdk(options)\n  }\n\n  /** 获取底层 AlipaySdk 实例 */\n  get sdk(): AlipaySdk {\n    this.ensureActive()\n    return this._sdk\n  }\n\n  /** 更新配置并重建 SDK 实例 */\n  updateConfig(patch: Partial<AlipayClientOptions>): void {\n    this.ensureActive()\n    this.config.update(patch)\n    this._sdk = this.createSdk(this.config.options as AlipayClientOptions)\n  }\n\n  /** 销毁客户端 */\n  dispose(): void {\n    this._disposed = true\n    ;(this._sdk as any) = null\n  }\n\n  private createSdk(options: AlipayClientOptions): AlipaySdk {\n    return new AlipaySdk({\n      appId: options.appId,\n      privateKey: options.privateKey,\n      alipayPublicKey: options.alipayPublicKey,\n      signType: options.signType ?? 'RSA2',\n      gateway: options.gateway,\n      timeout: options.timeout ?? 5000,\n      keyType: (options.keyType ?? 'PKCS1') as AlipayKeyType\n    })\n  }\n\n  private ensureActive(): void {\n    if (this._disposed) {\n      throw new Error('AlipayClient: 客户端已销毁')\n    }\n  }\n}"]}

package/dist/alipay/config.cjs

@@ -0,0 +1,67 @@
+'use strict';
+
+var __defProp = Object.defineProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+
+// packages/payment/src/alipay/config.ts
+var _AlipayConfig = class _AlipayConfig {
+  constructor(options) {
+    this.validate(options);
+    this._options = { ...options };
+  }
+  /** 获取完整配置 */
+  get options() {
+    return this._options;
+  }
+  /** 应用 ID */
+  get appId() {
+    return this._options.appId;
+  }
+  /** 网关地址 */
+  get gateway() {
+    return this._options.gateway ?? "https://openapi.alipay.com/gateway.do";
+  }
+  /** 异步通知地址 */
+  get notifyUrl() {
+    return this._options.notifyUrl;
+  }
+  /** 同步跳转地址 */
+  get returnUrl() {
+    return this._options.returnUrl;
+  }
+  /** 更新配置（部分更新） */
+  update(patch) {
+    const merged = { ...this._options, ...patch };
+    this.validate(merged);
+    this._options = merged;
+  }
+  /** 替换配置 */
+  replace(options) {
+    this.validate(options);
+    this._options = { ...options };
+  }
+  /** 创建沙箱配置的快捷方法 */
+  static forSandbox(options) {
+    return new _AlipayConfig({
+      ...options,
+      gateway: "https://openapi-sandbox.dl.alipaydev.com/gateway.do"
+    });
+  }
+  validate(options) {
+    if (!options.appId) {
+      throw new Error("AlipayConfig: appId \u4E0D\u80FD\u4E3A\u7A7A");
+    }
+    if (!options.privateKey) {
+      throw new Error("AlipayConfig: privateKey \u4E0D\u80FD\u4E3A\u7A7A");
+    }
+    if (!options.alipayPublicKey) {
+      throw new Error("AlipayConfig: alipayPublicKey \u4E0D\u80FD\u4E3A\u7A7A");
+    }
+  }
+};
+__name(_AlipayConfig, "AlipayConfig");
+var AlipayConfig = _AlipayConfig;
+
+exports.AlipayConfig = AlipayConfig;
+//# sourceMappingURL=config.cjs.map
+//# sourceMappingURL=config.cjs.map

package/dist/alipay/config.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/alipay/config.ts"],"names":[],"mappings":";;;;;;AAMO,IAAM,aAAA,GAAN,MAAM,aAAA,CAAa;AAAA,EAGxB,YAAY,OAAA,EAA8B;AACxC,IAAA,IAAA,CAAK,SAAS,OAAO,CAAA;AACrB,IAAA,IAAA,CAAK,QAAA,GAAW,EAAE,GAAG,OAAA,EAAQ;AAAA,EAC/B;AAAA;AAAA,EAGA,IAAI,OAAA,GAAyC;AAC3C,IAAA,OAAO,IAAA,CAAK,QAAA;AAAA,EACd;AAAA;AAAA,EAGA,IAAI,KAAA,GAAgB;AAClB,IAAA,OAAO,KAAK,QAAA,CAAS,KAAA;AAAA,EACvB;AAAA;AAAA,EAGA,IAAI,OAAA,GAAkB;AACpB,IAAA,OAAO,IAAA,CAAK,SAAS,OAAA,IAAW,uCAAA;AAAA,EAClC;AAAA;AAAA,EAGA,IAAI,SAAA,GAAgC;AAClC,IAAA,OAAO,KAAK,QAAA,CAAS,SAAA;AAAA,EACvB;AAAA;AAAA,EAGA,IAAI,SAAA,GAAgC;AAClC,IAAA,OAAO,KAAK,QAAA,CAAS,SAAA;AAAA,EACvB;AAAA;AAAA,EAGA,OAAO,KAAA,EAA2C;AAChD,IAAA,MAAM,SAAS,EAAE,GAAG,IAAA,CAAK,QAAA,EAAU,GAAG,KAAA,EAAM;AAC5C,IAAA,IAAA,CAAK,SAAS,MAAM,CAAA;AACpB,IAAA,IAAA,CAAK,QAAA,GAAW,MAAA;AAAA,EAClB;AAAA;AAAA,EAGA,QAAQ,OAAA,EAAoC;AAC1C,IAAA,IAAA,CAAK,SAAS,OAAO,CAAA;AACrB,IAAA,IAAA,CAAK,QAAA,GAAW,EAAE,GAAG,OAAA,EAAQ;AAAA,EAC/B;AAAA;AAAA,EAGA,OAAO,WAAW,OAAA,EAA6D;AAC7E,IAAA,OAAO,IAAI,aAAA,CAAa;AAAA,MACtB,GAAG,OAAA;AAAA,MACH,OAAA,EAAS;AAAA,KACV,CAAA;AAAA,EACH;AAAA,EAEQ,SAAS,OAAA,EAAoC;AACnD,IAAA,IAAI,CAAC,QAAQ,KAAA,EAAO;AAClB,MAAA,MAAM,IAAI,MAAM,8CAA0B,CAAA;AAAA,IAC5C;AACA,IAAA,IAAI,CAAC,QAAQ,UAAA,EAAY;AACvB,MAAA,MAAM,IAAI,MAAM,mDAA+B,CAAA;AAAA,IACjD;AACA,IAAA,IAAI,CAAC,QAAQ,eAAA,EAAiB;AAC5B,MAAA,MAAM,IAAI,MAAM,wDAAoC,CAAA;AAAA,IACtD;AAAA,EACF;AACF,CAAA;AAjE0B,MAAA,CAAA,aAAA,EAAA,cAAA,CAAA;AAAnB,IAAM,YAAA,GAAN","file":"config.cjs","sourcesContent":["import type { AlipayClientOptions } from './types'\n\n/**\n * 支付宝配置管理\n * 遵循 vobs 生命周期管理：可创建、可销毁、可替换\n */\nexport class AlipayConfig {\n  private _options: AlipayClientOptions\n\n  constructor(options: AlipayClientOptions) {\n    this.validate(options)\n    this._options = { ...options }\n  }\n\n  /** 获取完整配置 */\n  get options(): Readonly<AlipayClientOptions> {\n    return this._options\n  }\n\n  /** 应用 ID */\n  get appId(): string {\n    return this._options.appId\n  }\n\n  /** 网关地址 */\n  get gateway(): string {\n    return this._options.gateway ?? 'https://openapi.alipay.com/gateway.do'\n  }\n\n  /** 异步通知地址 */\n  get notifyUrl(): string | undefined {\n    return this._options.notifyUrl\n  }\n\n  /** 同步跳转地址 */\n  get returnUrl(): string | undefined {\n    return this._options.returnUrl\n  }\n\n  /** 更新配置（部分更新） */\n  update(patch: Partial<AlipayClientOptions>): void {\n    const merged = { ...this._options, ...patch }\n    this.validate(merged)\n    this._options = merged\n  }\n\n  /** 替换配置 */\n  replace(options: AlipayClientOptions): void {\n    this.validate(options)\n    this._options = { ...options }\n  }\n\n  /** 创建沙箱配置的快捷方法 */\n  static forSandbox(options: Omit<AlipayClientOptions, 'gateway'>): AlipayConfig {\n    return new AlipayConfig({\n      ...options,\n      gateway: 'https://openapi-sandbox.dl.alipaydev.com/gateway.do'\n    })\n  }\n\n  private validate(options: AlipayClientOptions): void {\n    if (!options.appId) {\n      throw new Error('AlipayConfig: appId 不能为空')\n    }\n    if (!options.privateKey) {\n      throw new Error('AlipayConfig: privateKey 不能为空')\n    }\n    if (!options.alipayPublicKey) {\n      throw new Error('AlipayConfig: alipayPublicKey 不能为空')\n    }\n  }\n}"]}

package/dist/alipay/config.d.cts

@@ -0,0 +1,30 @@
+import { AlipayClientOptions } from './types.cjs';
+import 'alipay-sdk';
+
+/**
+ * 支付宝配置管理
+ * 遵循 vobs 生命周期管理：可创建、可销毁、可替换
+ */
+declare class AlipayConfig {
+    private _options;
+    constructor(options: AlipayClientOptions);
+    /** 获取完整配置 */
+    get options(): Readonly<AlipayClientOptions>;
+    /** 应用 ID */
+    get appId(): string;
+    /** 网关地址 */
+    get gateway(): string;
+    /** 异步通知地址 */
+    get notifyUrl(): string | undefined;
+    /** 同步跳转地址 */
+    get returnUrl(): string | undefined;
+    /** 更新配置（部分更新） */
+    update(patch: Partial<AlipayClientOptions>): void;
+    /** 替换配置 */
+    replace(options: AlipayClientOptions): void;
+    /** 创建沙箱配置的快捷方法 */
+    static forSandbox(options: Omit<AlipayClientOptions, 'gateway'>): AlipayConfig;
+    private validate;
+}
+
+export { AlipayConfig };

package/dist/alipay/config.d.ts

@@ -0,0 +1,30 @@
+import { AlipayClientOptions } from './types.js';
+import 'alipay-sdk';
+
+/**
+ * 支付宝配置管理
+ * 遵循 vobs 生命周期管理：可创建、可销毁、可替换
+ */
+declare class AlipayConfig {
+    private _options;
+    constructor(options: AlipayClientOptions);
+    /** 获取完整配置 */
+    get options(): Readonly<AlipayClientOptions>;
+    /** 应用 ID */
+    get appId(): string;
+    /** 网关地址 */
+    get gateway(): string;
+    /** 异步通知地址 */
+    get notifyUrl(): string | undefined;
+    /** 同步跳转地址 */
+    get returnUrl(): string | undefined;
+    /** 更新配置（部分更新） */
+    update(patch: Partial<AlipayClientOptions>): void;
+    /** 替换配置 */
+    replace(options: AlipayClientOptions): void;
+    /** 创建沙箱配置的快捷方法 */
+    static forSandbox(options: Omit<AlipayClientOptions, 'gateway'>): AlipayConfig;
+    private validate;
+}
+
+export { AlipayConfig };