@vobs/payment 0.3.0 → 1.2.0

package/src/alipay/refund.ts

@@ -0,0 +1,85 @@
+import type { AlipayClient } from './client'
+import { unwrapResponse } from './response'
+import type {
+  AlipayRefundParams,
+  AlipayRefundResult,
+  AlipayRefundQueryParams,
+  AlipayRefundQueryResult,
+  AlipayCloseParams,
+  AlipayCloseResult
+} from './types'
+
+/**
+ * 退款与交易关闭
+ *
+ * 包含退款、退款查询、交易关闭的完整退款生命周期管理。
+ */
+export function createRefund(client: AlipayClient) {
+  return {
+    /**
+     * 交易退款 (alipay.trade.refund)
+     * 交易发生后 12 个月内可退款，退款资金原路返回。
+     * @throws {AlipayApiError} 业务失败时抛出
+     */
+    async refund(params: AlipayRefundParams): Promise<AlipayRefundResult> {
+      const alipayResponse = unwrapResponse(
+        await client.sdk.exec('alipay.trade.refund', {
+          bizContent: params
+        }),
+        'alipay.trade.refund'
+      )
+
+      return {
+        tradeNo: alipayResponse.trade_no,
+        outTradeNo: alipayResponse.out_trade_no,
+        buyerLogonId: alipayResponse.buyer_logon_id,
+        refundAmount: alipayResponse.refund_fee,
+        fundChange: alipayResponse.fund_change ?? 'N',
+        gmtRefundPay: alipayResponse.gmt_refund_pay ?? '',
+        refundDetailItemList: alipayResponse.refund_detail_item_list ?? null
+      }
+    },
+
+    /**
+     * 退款查询 (alipay.trade.fastpay.refund.query)
+     * 查询退款状态，确认退款是否成功。
+     * @throws {AlipayApiError} 业务失败时抛出
+     */
+    async queryRefund(params: AlipayRefundQueryParams): Promise<AlipayRefundQueryResult> {
+      const alipayResponse = unwrapResponse(
+        await client.sdk.exec('alipay.trade.fastpay.refund.query', {
+          bizContent: params
+        }),
+        'alipay.trade.fastpay.refund.query'
+      )
+
+      return {
+        tradeNo: alipayResponse.trade_no,
+        outTradeNo: alipayResponse.out_trade_no,
+        refundAmount: alipayResponse.refund_amount,
+        refundStatus: alipayResponse.refund_status,
+        outRequestNo: alipayResponse.out_request_no,
+        refundReason: alipayResponse.refund_reason ?? ''
+      }
+    },
+
+    /**
+     * 关闭交易 (alipay.trade.close)
+     * 关闭未支付的订单。
+     * @throws {AlipayApiError} 业务失败时抛出
+     */
+    async close(params: AlipayCloseParams): Promise<AlipayCloseResult> {
+      const alipayResponse = unwrapResponse(
+        await client.sdk.exec('alipay.trade.close', {
+          bizContent: params
+        }),
+        'alipay.trade.close'
+      )
+
+      return {
+        tradeNo: alipayResponse.trade_no,
+        outTradeNo: alipayResponse.out_trade_no
+      }
+    }
+  }
+}

package/src/alipay/response.ts

@@ -0,0 +1,40 @@
+/**
+ * 支付宝开放接口响应解包与业务错误检查。
+ *
+ * 网关应答（HTTP 200）不代表业务成功：业务失败时响应体内
+ * code != '10000' 并携带 sub_code/sub_msg，必须显式检查，
+ * 否则会把失败结果当成功映射（字段全部 undefined）。
+ */
+export class AlipayApiError extends Error {
+  readonly code: string
+  readonly subCode?: string
+  readonly subMsg?: string
+
+  constructor(apiName: string, code: string, subCode: string | undefined, subMsg: string | undefined, msg: string | undefined) {
+    super(`支付宝接口 ${apiName} 调用失败: ${subMsg ?? msg ?? '未知错误'} (code=${code}${subCode ? `, sub_code=${subCode}` : ''})`)
+    this.name = 'AlipayApiError'
+    this.code = code
+    this.subCode = subCode
+    this.subMsg = subMsg
+  }
+}
+
+/** alipay.trade.page.pay -> alipay_trade_page_pay_response */
+function toResponseKey(apiName: string): string {
+  return `${apiName.replace(/\./g, '_')}_response`
+}
+
+/**
+ * 从网关应答中取出业务响应体，code !== '10000' 时抛出 AlipayApiError。
+ */
+export function unwrapResponse(raw: unknown, apiName: string): Record<string, any> {
+  const outer = raw as Record<string, any> | null | undefined
+  const body = (outer && outer[toResponseKey(apiName)]) ?? outer
+  if (!body || typeof body !== 'object') {
+    throw new AlipayApiError(apiName, 'INVALID_RESPONSE', undefined, undefined, '响应体格式异常')
+  }
+  if (body.code !== '10000') {
+    throw new AlipayApiError(apiName, body.code, body.sub_code, body.sub_msg, body.msg)
+  }
+  return body
+}

package/src/alipay/types.ts

@@ -0,0 +1,271 @@
+import type { AlipaySdkConfig, AlipaySdkSignType } from 'alipay-sdk'
+
+// ---- 重新导出 alipay-sdk 类型 ----
+export type { AlipaySdkConfig, AlipaySdkSignType }
+
+// ---- 电脑网站支付 (alipay.trade.page.pay) ----
+export interface AlipayPagePayParams {
+  /** 商户订单号，需保证唯一 */
+  outTradeNo: string
+  /** 订单总金额，单位元，精确到两位小数 */
+  totalAmount: string
+  /** 订单标题 */
+  subject: string
+  /** 产品代码，电脑网站支付固定为 FAST_INSTANT_TRADE_PAY */
+  productCode?: string
+  /** 订单描述 */
+  body?: string
+  /** 绝对超时时间，格式 yyyy-MM-dd HH:mm:ss */
+  timeExpire?: string
+  /** 订单相对超时时间，范围 1m~15d */
+  timeoutExpress?: string
+  /** 商品主类型：0-虚拟，1-实物 */
+  goodsType?: '0' | '1'
+  /** 公用回传参数，异步通知时原样返回 */
+  passbackParams?: string
+  /** 支付完成后同步跳转地址 */
+  returnUrl?: string
+  /** 异步通知地址 */
+  notifyUrl?: string
+  /** 扩展信息 */
+  extendParams?: Record<string, string>
+  /** 商户门店编号 */
+  storeId?: string
+  /** 是否发起实名校验 */
+  qrPayMode?: string
+  /** 扫码支付模式 */
+  qrcodeWidth?: string
+}
+
+export interface AlipayPagePayResult {
+  /** 支付宝返回的 HTML 表单字符串 */
+  formHtml: string
+}
+
+// ---- 手机网站支付 (alipay.trade.wap.pay) ----
+export interface AlipayWapPayParams {
+  /** 商户订单号，需保证唯一 */
+  outTradeNo: string
+  /** 订单总金额，单位元，精确到两位小数 */
+  totalAmount: string
+  /** 订单标题 */
+  subject: string
+  /** 产品代码，手机网站支付固定为 QUICK_WAP_WAY */
+  productCode?: string
+  /** 订单描述 */
+  body?: string
+  /** 绝对超时时间，格式 yyyy-MM-dd HH:mm:ss */
+  timeExpire?: string
+  /** 订单相对超时时间，范围 1m~15d */
+  timeoutExpress?: string
+  /** 公用回传参数，异步通知时原样返回 */
+  passbackParams?: string
+  /** 用户付款中途退出后返回的商户页面地址 */
+  quitUrl?: string
+  /** 支付完成后同步跳转地址 */
+  returnUrl?: string
+  /** 异步通知地址 */
+  notifyUrl?: string
+}
+
+export interface AlipayWapPayResult {
+  /** 支付宝返回的 HTML 表单字符串 */
+  formHtml: string
+}
+
+// ---- 交易查询 (alipay.trade.query) ----
+export interface AlipayQueryParams {
+  outTradeNo?: string
+  tradeNo?: string
+}
+
+export interface AlipayQueryResult {
+  /** 支付宝交易号 */
+  tradeNo: string
+  /** 商户订单号 */
+  outTradeNo: string
+  /** 买家支付宝账号 */
+  buyerLogonId: string
+  /** 交易状态 */
+  tradeStatus: TradeStatus
+  /** 交易的订单金额 */
+  totalAmount: string
+  /** 实收金额 */
+  receiptAmount: string
+  /** 买家实付金额 */
+  buyerPayAmount: string
+  /** 交易创建时间 */
+  sendPayDate: string
+  /** 交易付款时间 */
+  gmtPayment: string | null
+  /** 交易关闭时间 */
+  gmtClose: string | null
+  /** 退款金额 */
+  refundAmount: string
+  /** 商品描述 */
+  subject: string
+  /** 商户传入的回传参数 */
+  passbackParams: string | null
+  /** 本次交易支付工具 */
+  fundChannel: string | null
+}
+
+// ---- 交易退款 (alipay.trade.refund) ----
+export interface AlipayRefundParams {
+  outTradeNo?: string
+  tradeNo?: string
+  refundAmount: string
+  refundReason?: string
+  outRequestNo?: string
+  refundCurrency?: string
+}
+
+export interface AlipayRefundResult {
+  /** 支付宝交易号 */
+  tradeNo: string
+  /** 商户订单号 */
+  outTradeNo: string
+  /** 买家支付宝账号 */
+  buyerLogonId: string
+  /** 本次退款请求金额 */
+  refundAmount: string
+  /** 资金变动明细 */
+  fundChange: string
+  /** 退款时间 */
+  gmtRefundPay: string
+  /** 退款金额（含各渠道） */
+  refundDetailItemList: Array<{
+    contributionType: string
+    amount: string
+  }> | null
+}
+
+// ---- 交易关闭 (alipay.trade.close) ----
+export interface AlipayCloseParams {
+  outTradeNo?: string
+  tradeNo?: string
+}
+
+export interface AlipayCloseResult {
+  /** 支付宝交易号 */
+  tradeNo: string
+  /** 商户订单号 */
+  outTradeNo: string
+}
+
+// ---- 退款查询 (alipay.trade.fastpay.refund.query) ----
+export interface AlipayRefundQueryParams {
+  outTradeNo?: string
+  tradeNo?: string
+  outRequestNo: string
+}
+
+export interface AlipayRefundQueryResult {
+  /** 支付宝交易号 */
+  tradeNo: string
+  /** 商户订单号 */
+  outTradeNo: string
+  /** 退款金额 */
+  refundAmount: string
+  /** 退款状态 */
+  refundStatus: string
+  /** 退款请求号 */
+  outRequestNo: string
+  /** 退款原因 */
+  refundReason: string
+}
+
+// ---- 异步通知 ----
+export interface AlipayNotifyParams {
+  [key: string]: string | undefined
+  notifyTime: string
+  notifyType: string
+  notifyId: string
+  appId: string
+  charset: string
+  version: string
+  signType: string
+  sign: string
+  tradeNo: string
+  outTradeNo: string
+  outBizNo?: string
+  buyerId: string
+  buyerLogonId: string
+  sellerId: string
+  sellerEmail: string
+  tradeStatus: string
+  totalAmount: string
+  receiptAmount: string
+  invoiceAmount: string
+  buyerPayAmount: string
+  pointAmount: string
+  refundFee: string
+  subject: string
+  body: string
+  gmtCreate: string
+  gmtPayment: string
+  gmtClose: string
+  fundBillList: string
+  passbackParams: string
+  voucherDetailList: string
+}
+
+// ---- 通用 ----
+export type TradeStatus =
+  | 'WAIT_BUYER_PAY'
+  | 'TRADE_CLOSED'
+  | 'TRADE_SUCCESS'
+  | 'TRADE_FINISHED'
+
+export type AlipayKeyType = 'PKCS1' | 'PKCS8'
+
+export interface AlipayClientOptions {
+  /** 应用 ID */
+  appId: string
+  /** 应用私钥（Node.js 使用 PKCS#1 格式） */
+  privateKey: string
+  /** 支付宝公钥 */
+  alipayPublicKey: string
+  /** 签名类型，默认 RSA2 */
+  signType?: AlipaySdkSignType
+  /** 网关地址，沙箱使用沙箱网关 */
+  gateway?: string
+  /** 异步通知地址 */
+  notifyUrl?: string
+  /** 同步跳转地址 */
+  returnUrl?: string
+  /** 私钥类型，默认 PKCS1（Node.js 使用 PKCS1） */
+  keyType?: AlipayKeyType
+  /** 请求超时时间，默认 5000ms */
+  timeout?: number
+}
+
+/** 电脑网站支付配置 */
+export interface AlipayPagePayConfig {
+  /** 商户订单号 */
+  outTradeNo: string
+  /** 订单总金额，单位元 */
+  totalAmount: string
+  /** 订单标题 */
+  subject: string
+  /** 订单描述 */
+  body?: string
+  /** 公用回传参数 */
+  passbackParams?: string
+}
+
+/** 手机网站支付配置 */
+export interface AlipayWapPayConfig {
+  /** 商户订单号 */
+  outTradeNo: string
+  /** 订单总金额，单位元 */
+  totalAmount: string
+  /** 订单标题 */
+  subject: string
+  /** 订单描述 */
+  body?: string
+  /** 公用回传参数 */
+  passbackParams?: string
+  /** 用户付款中途退出后返回的商户页面地址（wap 支付必填） */
+  quitUrl?: string
+}

package/src/alipay/wap.ts

@@ -0,0 +1,55 @@
+import type { AlipayClient } from './client'
+import type { AlipayWapPayConfig, AlipayWapPayParams, AlipayWapPayResult } from './types'
+
+/**
+ * 手机网站支付 (alipay.trade.wap.pay)
+ *
+ * 移动端浏览器内拉起支付宝收银台，生成表单 HTML 由前端提交跳转。
+ *
+ * ⚠️ 必须使用 pageExecute() 方法，禁止使用 exec()。
+ * ⚠️ 返回值为 HTML 表单字符串，前端必须渲染 form 并自动提交。
+ * ⚠️ 支付结果以异步通知或查询接口为准，不可依赖同步跳转。
+ */
+export function createWapPay(client: AlipayClient) {
+  return {
+    /**
+     * 发起手机网站支付
+     * @param config 支付配置
+     * @returns 支付表单 HTML
+     */
+    async pay(config: AlipayWapPayConfig): Promise<AlipayWapPayResult> {
+      const { outTradeNo, totalAmount, subject, body, passbackParams, quitUrl } = config
+
+      const bizParams: AlipayWapPayParams = {
+        outTradeNo,
+        totalAmount,
+        subject,
+        productCode: 'QUICK_WAP_WAY',
+        body,
+        passbackParams,
+        quitUrl,
+        returnUrl: client.config.returnUrl,
+        notifyUrl: client.config.notifyUrl
+      }
+
+      const formHtml = client.sdk.pageExecute(
+        'alipay.trade.wap.pay',
+        'POST',
+        { bizContent: sanitizeParams(bizParams) }
+      )
+
+      return { formHtml }
+    }
+  }
+}
+
+/** 移除 undefined 字段 */
+function sanitizeParams<T extends Record<string, any>>(params: T): Record<string, any> {
+  const result: Record<string, any> = {}
+  for (const [key, value] of Object.entries(params)) {
+    if (value !== undefined && value !== null) {
+      result[key] = value
+    }
+  }
+  return result
+}

package/src/index.ts

@@ -0,0 +1,78 @@
+/**
+ * @vobs/payment 根入口
+ *
+ * - 通用工厂中 createRefund / createNotifyHandler 在两个提供商间同名，
+ *   统一通过 alipay.* / wechat.* 命名空间访问，避免同名不同客户端的隐式误用。
+ * - 顶层平铺导出跨提供商无歧义的符号（客户端、配置、错误类、插件、注入键，
+ *   以及名称唯一的工厂 createPagePay / createWapPay / createQuery / createPayment）。
+ */
+export * as alipay from './alipay'
+export * as wechat from './wechat'
+
+export {
+  AlipayClient,
+  AlipayConfig,
+  AlipayApiError,
+  createPagePay,
+  createWapPay,
+  createQuery,
+  alipayPlugin,
+  useAlipay,
+  ALIPAY_KEY
+} from './alipay'
+export type {
+  AlipayClientOptions,
+  AlipayKeyType,
+  AlipaySdkConfig,
+  AlipaySdkSignType,
+  AlipayPagePayConfig,
+  AlipayPagePayParams,
+  AlipayPagePayResult,
+  AlipayWapPayConfig,
+  AlipayWapPayParams,
+  AlipayWapPayResult,
+  AlipayQueryParams,
+  AlipayQueryResult,
+  AlipayRefundParams,
+  AlipayRefundResult,
+  AlipayRefundQueryParams,
+  AlipayRefundQueryResult,
+  AlipayCloseParams,
+  AlipayCloseResult,
+  AlipayNotifyParams,
+  TradeStatus,
+  AlipayPluginOptions
+} from './alipay'
+
+export {
+  WechatClient,
+  WechatConfig,
+  WechatApiError,
+  createPayment,
+  wechatPlugin,
+  useWechat,
+  WECHAT_KEY
+} from './wechat'
+export type {
+  WechatClientOptions,
+  WechatPayParams,
+  WechatH5PayParams,
+  WechatJsapiPayResult,
+  WechatAppPayResult,
+  WechatNativePayResult,
+  WechatH5PayResult,
+  WechatQueryParams,
+  WechatQueryResult,
+  WechatRefundParams,
+  WechatRefundResult,
+  WechatRefundQueryParams,
+  WechatRefundAmount,
+  WechatOrderAmount,
+  WechatTradeState,
+  WechatRefundStatus,
+  WechatNotifyResource,
+  WechatNotifyHeaders,
+  WechatNotifyTransaction,
+  WechatNotifyRefund,
+  WechatPluginOptions
+} from './wechat'

package/src/wechat/client.ts

@@ -0,0 +1,68 @@
+import { Wechatpay } from 'wechatpay-axios-plugin'
+import { WechatConfig } from './config'
+import type { WechatClientOptions } from './types'
+
+/**
+ * 微信支付客户端封装
+ *
+ * 封装官方 wechatpay-axios-plugin 的 Wechatpay 实例，提供统一的生命周期管理。
+ * 可独立使用，也可通过 wechatPlugin 注册到 vobs 框架。
+ *
+ * @example
+ * ```ts
+ * const client = new WechatClient({
+ *   mchid: '1900000000',
+ *   serial: '商户API证书序列号',
+ *   privateKey: '-----BEGIN PRIVATE KEY-----...',
+ *   certs: { 'PUB_KEY_ID_xxx': '-----BEGIN PUBLIC KEY-----...' },
+ *   appid: 'wx1234567890',
+ *   apiv3Key: '32字节APIv3密钥',
+ *   notifyUrl: 'https://your-domain.com/wechat/notify'
+ * })
+ * ```
+ */
+export class WechatClient {
+  readonly config: WechatConfig
+  private _sdk: Wechatpay
+  private _disposed = false
+
+  constructor(options: WechatClientOptions) {
+    this.config = new WechatConfig(options)
+    this._sdk = this.createSdk(options)
+  }
+
+  /** 获取底层 Wechatpay 实例（链式 API：client.sdk.v3.pay.transactions.jsapi.post(...)） */
+  get sdk(): Wechatpay {
+    this.ensureActive()
+    return this._sdk
+  }
+
+  /** 更新配置并重建 SDK 实例 */
+  updateConfig(patch: Partial<WechatClientOptions>): void {
+    this.ensureActive()
+    this.config.update(patch)
+    this._sdk = this.createSdk(this.config.options as WechatClientOptions)
+  }
+
+  /** 销毁客户端 */
+  dispose(): void {
+    this._disposed = true
+    ;(this._sdk as any) = null
+  }
+
+  private createSdk(options: WechatClientOptions): Wechatpay {
+    return new Wechatpay({
+      mchid: options.mchid,
+      serial: options.serial,
+      privateKey: options.privateKey,
+      certs: options.certs,
+      timeout: options.timeout ?? 5000
+    })
+  }
+
+  private ensureActive(): void {
+    if (this._disposed) {
+      throw new Error('WechatClient: 客户端已销毁')
+    }
+  }
+}

package/src/wechat/config.ts

@@ -0,0 +1,81 @@
+import type { WechatClientOptions } from './types'
+
+/**
+ * 微信支付配置管理
+ * 遵循 vobs 生命周期管理：可创建、可校验、可更新、可替换
+ */
+export class WechatConfig {
+  private _options: WechatClientOptions
+
+  constructor(options: WechatClientOptions) {
+    this.validate(options)
+    this._options = { ...options }
+  }
+
+  /** 获取完整配置 */
+  get options(): Readonly<WechatClientOptions> {
+    return this._options
+  }
+
+  /** 商户号 */
+  get mchid(): string {
+    return this._options.mchid
+  }
+
+  /** 应用 ID（公众号 / 小程序 / APP） */
+  get appid(): string {
+    return this._options.appid
+  }
+
+  /** 商户 API 证书序列号 */
+  get serial(): string {
+    return this._options.serial
+  }
+
+  /** APIv3 密钥（回调解密用） */
+  get apiv3Key(): string {
+    return this._options.apiv3Key
+  }
+
+  /** 异步通知地址 */
+  get notifyUrl(): string | undefined {
+    return this._options.notifyUrl
+  }
+
+  /** 更新配置（部分更新） */
+  update(patch: Partial<WechatClientOptions>): void {
+    const merged = { ...this._options, ...patch }
+    this.validate(merged)
+    this._options = merged
+  }
+
+  /** 替换配置 */
+  replace(options: WechatClientOptions): void {
+    this.validate(options)
+    this._options = { ...options }
+  }
+
+  private validate(options: WechatClientOptions): void {
+    if (!options.mchid) {
+      throw new Error('WechatConfig: mchid 不能为空')
+    }
+    if (!options.serial) {
+      throw new Error('WechatConfig: serial（商户 API 证书序列号）不能为空')
+    }
+    if (!options.privateKey) {
+      throw new Error('WechatConfig: privateKey（商户 API 私钥 PEM）不能为空')
+    }
+    if (!options.certs || Object.keys(options.certs).length === 0) {
+      throw new Error('WechatConfig: certs（平台证书/微信支付公钥 {序列号: PEM}）不能为空')
+    }
+    if (!options.appid) {
+      throw new Error('WechatConfig: appid 不能为空')
+    }
+    if (!options.apiv3Key) {
+      throw new Error('WechatConfig: apiv3Key 不能为空')
+    }
+    if (options.apiv3Key.length !== 32) {
+      throw new Error('WechatConfig: apiv3Key 必须为 32 字节字符串')
+    }
+  }
+}

package/src/wechat/index.ts

@@ -0,0 +1,30 @@
+export { WechatClient } from './client'
+export { WechatConfig } from './config'
+export { WechatApiError } from './response'
+export { createPayment } from './payment'
+export { createNotifyHandler } from './notify'
+export { createRefund } from './refund'
+export { wechatPlugin, useWechat, WECHAT_KEY } from './plugin'
+export type { WechatPluginOptions } from './plugin'
+export type {
+  WechatClientOptions,
+  WechatPayParams,
+  WechatH5PayParams,
+  WechatJsapiPayResult,
+  WechatAppPayResult,
+  WechatNativePayResult,
+  WechatH5PayResult,
+  WechatQueryParams,
+  WechatQueryResult,
+  WechatRefundParams,
+  WechatRefundResult,
+  WechatRefundQueryParams,
+  WechatRefundAmount,
+  WechatOrderAmount,
+  WechatTradeState,
+  WechatRefundStatus,
+  WechatNotifyResource,
+  WechatNotifyHeaders,
+  WechatNotifyTransaction,
+  WechatNotifyRefund
+} from './types'