@h-ai/payment 0.1.0-alpha.66 → 0.1.0-alpha.68

package/dist/payment-types-D02t-Pc9.d.ts

@@ -0,0 +1,500 @@
+import * as _h_ai_core from '@h-ai/core';
+import { HaiResult } from '@h-ai/core';
+import { z } from 'zod';
+
+/**
+ * @h-ai/payment — 错误码 + 配置 Schema
+ *
+ * 支付模块的错误码、Zod 配置 Schema 与配置类型。
+ * @module payment-config
+ */
+
+/**
+ * 微信公众号 JSAPI 配置 Schema；平台密钥按受信 serial 精确配置。
+ * @example
+ * ```ts
+ * import { WechatPayConfigSchema } from '@h-ai/payment'
+ * // 部署系统注入可信配置；Schema 校验形状，不证明密钥、证书或渠道账户可用。
+ * const platformKeys: unknown = JSON.parse(process.env.HAI_PAYMENT_WECHAT_PLATFORMKEYS ?? '{}')
+ * const parsed = WechatPayConfigSchema.safeParse({
+ *   mchId: process.env.HAI_PAYMENT_WECHAT_MCHID,
+ *   apiV3Key: process.env.HAI_PAYMENT_WECHAT_APIV3KEY,
+ *   serialNo: process.env.HAI_PAYMENT_WECHAT_SERIALNO,
+ *   privateKey: process.env.HAI_PAYMENT_WECHAT_PRIVATEKEY,
+ *   platformKeys,
+ *   appId: process.env.HAI_PAYMENT_WECHAT_APPID,
+ * })
+ * if (!parsed.success) throw new Error('Payment configuration is invalid')
+ * const config = parsed.data
+ * ```
+ */
+declare const WechatPayConfigSchema: z.ZodObject<{
+    mchId: z.ZodString;
+    apiV3Key: z.ZodString;
+    serialNo: z.ZodString;
+    privateKey: z.ZodString;
+    platformKeys: z.ZodRecord<z.ZodString, z.ZodString>;
+    appId: z.ZodString;
+}, z.core.$strip>;
+/**
+ * 支付宝手机网站支付配置 Schema；returnUrl 为可信 HTTPS 导航地址。
+ * @example
+ * ```ts
+ * import { AlipayConfigSchema } from '@h-ai/payment'
+ * // 部署系统注入可信配置；Schema 校验形状，不证明密钥、证书或渠道账户可用。
+ * const parsed = AlipayConfigSchema.safeParse({
+ *   appId: process.env.HAI_PAYMENT_ALIPAY_APPID,
+ *   sellerId: process.env.HAI_PAYMENT_ALIPAY_SELLERID,
+ *   privateKey: process.env.HAI_PAYMENT_ALIPAY_PRIVATEKEY,
+ *   alipayPublicKey: process.env.HAI_PAYMENT_ALIPAY_ALIPAYPUBLICKEY,
+ *   returnUrl: 'https://shop.example.com/payment/result',
+ * })
+ * if (!parsed.success) throw new Error('Payment configuration is invalid')
+ * const config = parsed.data
+ * ```
+ */
+declare const AlipayConfigSchema: z.ZodObject<{
+    appId: z.ZodString;
+    sellerId: z.ZodString;
+    privateKey: z.ZodString;
+    alipayPublicKey: z.ZodString;
+    returnUrl: z.ZodURL;
+    signType: z.ZodDefault<z.ZodEnum<{
+        RSA2: "RSA2";
+        RSA: "RSA";
+    }>>;
+    sandbox: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strip>;
+/**
+ * Stripe 托管 Checkout 配置 Schema；初始化前要求共享 reldb 就绪。
+ * @example
+ * ```ts
+ * import { StripeConfigSchema } from '@h-ai/payment'
+ * // 部署系统注入可信配置；Schema 校验形状，不证明密钥、证书或渠道账户可用。
+ * const parsed = StripeConfigSchema.safeParse({
+ *   secretKey: process.env.HAI_PAYMENT_STRIPE_SECRETKEY,
+ *   webhookSecret: process.env.HAI_PAYMENT_STRIPE_WEBHOOKSECRET,
+ *   successUrl: 'https://shop.example.com/payment/result?session={CHECKOUT_SESSION_ID}',
+ * })
+ * if (!parsed.success) throw new Error('Payment configuration is invalid')
+ * const config = parsed.data
+ * ```
+ */
+declare const StripeConfigSchema: z.ZodObject<{
+    secretKey: z.ZodString;
+    webhookSecret: z.ZodString;
+    successUrl: z.ZodURL;
+    cancelUrl: z.ZodOptional<z.ZodURL>;
+    webhookToleranceSeconds: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strict>;
+/**
+ * 支付模块配置 Schema；按配置注册渠道，密钥与运行时依赖由宿主提供。
+ * @example
+ * ```ts
+ * import { PaymentConfigSchema } from '@h-ai/payment'
+ * const parsed = PaymentConfigSchema.safeParse({ stripe: {
+ *   secretKey: process.env.HAI_PAYMENT_STRIPE_SECRETKEY,
+ *   webhookSecret: process.env.HAI_PAYMENT_STRIPE_WEBHOOKSECRET,
+ *   successUrl: 'https://shop.example.com/payment/result?session={CHECKOUT_SESSION_ID}',
+ * } })
+ * if (!parsed.success) throw new Error('Payment configuration is invalid')
+ * const toleranceSeconds = parsed.data.stripe?.webhookToleranceSeconds
+ * ```
+ */
+declare const PaymentConfigSchema: z.ZodObject<{
+    wechat: z.ZodOptional<z.ZodObject<{
+        mchId: z.ZodString;
+        apiV3Key: z.ZodString;
+        serialNo: z.ZodString;
+        privateKey: z.ZodString;
+        platformKeys: z.ZodRecord<z.ZodString, z.ZodString>;
+        appId: z.ZodString;
+    }, z.core.$strip>>;
+    alipay: z.ZodOptional<z.ZodObject<{
+        appId: z.ZodString;
+        sellerId: z.ZodString;
+        privateKey: z.ZodString;
+        alipayPublicKey: z.ZodString;
+        returnUrl: z.ZodURL;
+        signType: z.ZodDefault<z.ZodEnum<{
+            RSA2: "RSA2";
+            RSA: "RSA";
+        }>>;
+        sandbox: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$strip>>;
+    stripe: z.ZodOptional<z.ZodObject<{
+        secretKey: z.ZodString;
+        webhookSecret: z.ZodString;
+        successUrl: z.ZodURL;
+        cancelUrl: z.ZodOptional<z.ZodURL>;
+        webhookToleranceSeconds: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strict>>;
+}, z.core.$strip>;
+/**
+ * PaymentConfigSchema 解析后的配置类型；不能把未解析输入当作该类型。
+ * @example
+ * ```ts
+ * import { PaymentConfigSchema, type PaymentConfig } from '@h-ai/payment'
+ * const parsed = PaymentConfigSchema.safeParse({ stripe: {
+ *   secretKey: process.env.HAI_PAYMENT_STRIPE_SECRETKEY,
+ *   webhookSecret: process.env.HAI_PAYMENT_STRIPE_WEBHOOKSECRET,
+ *   successUrl: 'https://shop.example.com/payment/result?session={CHECKOUT_SESSION_ID}',
+ * } })
+ * if (!parsed.success) throw new Error('Payment configuration is invalid')
+ * const config: PaymentConfig = parsed.data
+ * config.stripe?.webhookToleranceSeconds // 解析输出包含默认的签名容差。
+ * ```
+ */
+type PaymentConfig = z.infer<typeof PaymentConfigSchema>;
+/**
+ * 支付初始化输入；允许省略由 Schema 补齐的配置默认值。
+ * @example
+ * ```ts
+ * import { payment, type PaymentConfigInput } from '@h-ai/payment'
+ * async function initializePayment(input: PaymentConfigInput) {
+ *   // 启用 Stripe 时，宿主已经先初始化共享 reldb 并检查成功。
+ *   const result = await payment.init(input)
+ *   if (!result.success) throw new Error(result.error.message)
+ * }
+ * ```
+ */
+type PaymentConfigInput = z.input<typeof PaymentConfigSchema>;
+/**
+ * 微信配置的解析输出类型；默认值已经由对应 Schema 补齐。
+ * @example
+ * ```ts
+ * import { WechatPayConfigSchema, type WechatPayConfig } from '@h-ai/payment'
+ * const platformKeys: unknown = JSON.parse(process.env.HAI_PAYMENT_WECHAT_PLATFORMKEYS ?? '{}')
+ * const parsed = WechatPayConfigSchema.safeParse({
+ *   mchId: process.env.HAI_PAYMENT_WECHAT_MCHID,
+ *   apiV3Key: process.env.HAI_PAYMENT_WECHAT_APIV3KEY,
+ *   serialNo: process.env.HAI_PAYMENT_WECHAT_SERIALNO,
+ *   privateKey: process.env.HAI_PAYMENT_WECHAT_PRIVATEKEY,
+ *   platformKeys,
+ *   appId: process.env.HAI_PAYMENT_WECHAT_APPID,
+ * })
+ * if (!parsed.success) throw new Error('Payment configuration is invalid')
+ * const config: WechatPayConfig = parsed.data
+ * ```
+ */
+type WechatPayConfig = z.infer<typeof WechatPayConfigSchema>;
+/**
+ * 支付宝配置的解析输出类型；默认值已经由对应 Schema 补齐。
+ * @example
+ * ```ts
+ * import { AlipayConfigSchema, type AlipayConfig } from '@h-ai/payment'
+ * const parsed = AlipayConfigSchema.safeParse({
+ *   appId: process.env.HAI_PAYMENT_ALIPAY_APPID,
+ *   sellerId: process.env.HAI_PAYMENT_ALIPAY_SELLERID,
+ *   privateKey: process.env.HAI_PAYMENT_ALIPAY_PRIVATEKEY,
+ *   alipayPublicKey: process.env.HAI_PAYMENT_ALIPAY_ALIPAYPUBLICKEY,
+ *   returnUrl: 'https://shop.example.com/payment/result',
+ * })
+ * if (!parsed.success) throw new Error('Payment configuration is invalid')
+ * const config: AlipayConfig = parsed.data
+ * ```
+ */
+type AlipayConfig = z.infer<typeof AlipayConfigSchema>;
+/**
+ * Stripe配置的解析输出类型；默认值已经由对应 Schema 补齐。
+ * @example
+ * ```ts
+ * import { StripeConfigSchema, type StripeConfig } from '@h-ai/payment'
+ * const parsed = StripeConfigSchema.safeParse({
+ *   secretKey: process.env.HAI_PAYMENT_STRIPE_SECRETKEY,
+ *   webhookSecret: process.env.HAI_PAYMENT_STRIPE_WEBHOOKSECRET,
+ *   successUrl: 'https://shop.example.com/payment/result?session={CHECKOUT_SESSION_ID}',
+ * })
+ * if (!parsed.success) throw new Error('Payment configuration is invalid')
+ * const config: StripeConfig = parsed.data
+ * ```
+ */
+type StripeConfig = z.infer<typeof StripeConfigSchema>;
+
+/**
+ * 支付错误码定义；调用方先判断 HaiResult.success，再按 code 分类处理。
+ * @example
+ * ```ts
+ * import { payment, HaiPaymentError } from '@h-ai/payment'
+ * const result = await payment.queryOrder('stripe', 'ORDER_1')
+ * if (!result.success && result.error.code === HaiPaymentError.NOT_INITIALIZED.code) {
+ *   // 应用启动流程应检查 init 结果，不能把未就绪查询当成未付款。
+ *   throw new Error(result.error.message)
+ * }
+ * ```
+ */
+declare const HaiPaymentError: {
+    readonly CREATE_ORDER_FAILED: _h_ai_core.HaiErrorDef;
+    readonly QUERY_ORDER_FAILED: _h_ai_core.HaiErrorDef;
+    readonly REFUND_FAILED: _h_ai_core.HaiErrorDef;
+    readonly CLOSE_ORDER_FAILED: _h_ai_core.HaiErrorDef;
+    readonly NOT_INITIALIZED: _h_ai_core.HaiErrorDef;
+    readonly SIGN_FAILED: _h_ai_core.HaiErrorDef;
+    readonly PROVIDER_NOT_FOUND: _h_ai_core.HaiErrorDef;
+    readonly INVALID_AMOUNT: _h_ai_core.HaiErrorDef;
+    readonly UNSUPPORTED_TRADE_TYPE: _h_ai_core.HaiErrorDef;
+    readonly INVALID_INPUT: _h_ai_core.HaiErrorDef;
+    readonly NOTIFY_VERIFY_FAILED: _h_ai_core.HaiErrorDef;
+    readonly NOTIFY_PARSE_FAILED: _h_ai_core.HaiErrorDef;
+    readonly INVOKE_WEB_FAILED: _h_ai_core.HaiErrorDef;
+    readonly CONFIG_ERROR: _h_ai_core.HaiErrorDef;
+};
+/**
+ * 已实现的支付场景：微信 jsapi，支付宝/Stripe h5；各 Provider 不接受其它组合。
+ * @example
+ * ```ts
+ * import type { TradeType } from '@h-ai/payment'
+ * const wechatScene: TradeType = 'jsapi'
+ * const hostedPageScene: TradeType = 'h5'
+ * ```
+ */
+type TradeType = 'jsapi' | 'h5';
+/**
+ * 订单状态
+ * @example
+ * ```ts
+ * import type { OrderStatusValue } from '@h-ai/payment'
+ * function isPaid(status: OrderStatusValue): boolean {
+ *   return status === 'paid' // pending、closed 和客户端跳转均不能证明付款。
+ * }
+ * ```
+ */
+type OrderStatusValue = 'pending' | 'paid' | 'closed' | 'refunded' | 'failed';
+/**
+ * 创建订单入参
+ * @example
+ * ```ts
+ * import type { CreateOrderInput } from '@h-ai/payment'
+ * const input: CreateOrderInput = {
+ *   orderNo: 'ORDER_1', amount: 100, currency: 'CNY', description: '测试商品',
+ *   tradeType: 'h5', notifyUrl: 'https://api.example.com/payment/notify/stripe',
+ * }
+ * // 微信改为 jsapi，并提供属于服务端 appId 的 openid；Stripe/支付宝使用 h5。
+ * ```
+ */
+interface CreateOrderInput {
+    /** 商户订单号 */
+    orderNo: string;
+    /** 金额（分） */
+    amount: number;
+    /** 大写币种；微信/支付宝使用 CNY，Stripe 省略时使用 USD，必须与业务订单一致。 */
+    currency?: string;
+    /** 商品描述 */
+    description: string;
+    /** 支付场景：微信仅 jsapi，支付宝仅 h5，Stripe 仅 h5（托管 Checkout 页面）。 */
+    tradeType: TradeType;
+    /** 微信公众号 openid，微信 jsapi 必填；必须属于服务端配置的 appId。 */
+    userId?: string;
+    /** 异步通知 URL */
+    notifyUrl: string;
+    /** 附加数据（透传） */
+    metadata?: Record<string, string>;
+}
+/**
+ * 支付订单（返回给客户端调起支付）
+ * @example
+ * ```ts
+ * import { payment, type PaymentOrder } from '@h-ai/payment'
+ * // 应用已初始化 Stripe 与其共享 reldb；订单号由业务持久化生成。
+ * const created = await payment.createOrder('stripe', {
+ *   orderNo: 'ORDER_1', amount: 100, currency: 'CNY', description: '测试商品',
+ *   tradeType: 'h5', notifyUrl: 'https://api.example.com/payment/notify/stripe',
+ * })
+ * if (!created.success) throw new Error(created.error.message)
+ * const order: PaymentOrder = created.data
+ * order.clientParams // 经受信应用接口交给 @h-ai/payment/client，不含商户私钥。
+ * ```
+ */
+interface PaymentOrder {
+    /** Provider 名称 */
+    provider: string;
+    /** 支付场景 */
+    tradeType: TradeType;
+    /** 微信 JSAPI 签名字段、支付宝 { gateway, fields } POST 参数或 Stripe { checkoutUrl }；不含 HTML。 */
+    clientParams: Record<string, unknown>;
+    /** 预支付 ID（如微信 prepay_id） */
+    prepayId?: string;
+}
+/**
+ * 回调请求（原始 HTTP 数据）
+ * @example
+ * ```ts
+ * import type { PaymentNotifyRequest } from '@h-ai/payment'
+ * async function rawNotification(request: Request): Promise<PaymentNotifyRequest> {
+ *   return { body: await request.text(), headers: Object.fromEntries(request.headers) }
+ *   // 必须保留原始 body；不能先 JSON.parse 再序列化后验签。
+ * }
+ * ```
+ */
+interface PaymentNotifyRequest {
+    /** 请求 body */
+    body: string;
+    /** 请求 headers */
+    headers: Record<string, string>;
+}
+/**
+ * 回调解析结果；验签与解析成功不等于已付款，履约前必须检查 status。
+ *
+ * 宿主需用共享持久存储核对订单、金额、币种并去重，阻止乱序事件倒退已完成状态。
+ * @example
+ * ```ts
+ * import { payment, type PaymentNotifyRequest } from '@h-ai/payment'
+ * async function verifyNotification(request: PaymentNotifyRequest) {
+ *   const result = await payment.handleNotify('stripe', request)
+ *   if (!result.success) return result
+ *   if (result.data.status === 'paid') {
+ *     // 宿主在共享业务事务中核对商户订单、金额、币种，并按 eventId 持久去重后履约。
+ *   }
+ *   return result // 验签成功的 pending 结果仍然不能发货。
+ * }
+ * ```
+ */
+interface PaymentNotifyResult {
+    /** 商户订单号 */
+    orderNo: string;
+    /** 支付渠道交易号 */
+    transactionId: string;
+    /** 渠道通知事件 ID：微信 id、支付宝 notify_id、Stripe event.id；宿主按渠道/商户命名空间持久去重。 */
+    eventId: string;
+    /** 支付金额（分） */
+    amount: number;
+    /** ISO 4217 大写币种；支付宝为 CNY，宿主必须与订单核对。 */
+    currency: string;
+    /** 支付状态 */
+    status: OrderStatusValue;
+    /** 渠道支付时间；Stripe 为支付成功事件的创建时间，非本次通知接收时间。 */
+    paidAt?: Date;
+    /** 原始数据 */
+    raw?: Record<string, unknown>;
+}
+/**
+ * 订单状态查询结果
+ * @example
+ * ```ts
+ * import { payment, type OrderStatus } from '@h-ai/payment'
+ * const result = await payment.queryOrder('stripe', 'ORDER_1')
+ * if (!result.success) throw new Error(result.error.message)
+ * const status: OrderStatus = result.data
+ * const hasPaymentConfirmation = status.status === 'paid'
+ * ```
+ */
+interface OrderStatus {
+    /** 商户订单号 */
+    orderNo: string;
+    /** 渠道交易号 */
+    transactionId?: string;
+    /** 订单状态 */
+    status: OrderStatusValue;
+    /** 金额（分） */
+    amount: number;
+    /** 支付时间 */
+    paidAt?: Date;
+}
+/**
+ * 退款入参
+ * @example
+ * ```ts
+ * import type { RefundInput } from '@h-ai/payment'
+ * const refund: RefundInput = {
+ *   orderNo: 'ORDER_1', refundNo: 'REFUND_1', amount: 50, totalAmount: 100, reason: '部分退货',
+ * }
+ * // 同一业务退款重试复用 refundNo，不能变更金额；微信必须提供原订单总额。
+ * ```
+ */
+interface RefundInput {
+    /** 商户订单号 */
+    orderNo: string;
+    /** 退款单号 */
+    refundNo: string;
+    /** 退款金额（分） */
+    amount: number;
+    /** 订单总金额（分），微信退款必填 */
+    totalAmount?: number;
+    /** 退款原因 */
+    reason?: string;
+}
+/**
+ * 退款结果
+ * @example
+ * ```ts
+ * import { payment, type RefundResult } from '@h-ai/payment'
+ * const result = await payment.refund('stripe', { orderNo: 'ORDER_1', refundNo: 'REFUND_1', amount: 50 })
+ * if (!result.success) throw new Error(result.error.message)
+ * const refund: RefundResult = result.data
+ * const confirmed = refund.status === 'success' // processing 仅表示仍待渠道确认。
+ * ```
+ */
+interface RefundResult {
+    /** 退款单号 */
+    refundNo: string;
+    /** 渠道退款标识；支付宝返回原交易号，需同时使用 refundNo 标识本次退款。 */
+    refundId: string;
+    /** 退款状态；支付宝 fund_change 为 N 或缺失时是 processing，须向渠道确认后才能判定退款成功。 */
+    status: 'processing' | 'success' | 'failed';
+}
+/**
+ * 支付 Provider 接口
+ *
+ * 各支付渠道（微信/支付宝/Stripe）实现此接口，
+ * 由 payment 模块统一调度。
+ * @example
+ * ```ts
+ * import { payment, type PaymentProvider } from '@h-ai/payment'
+ * function registerPartner(provider: PaymentProvider) {
+ *   // 实现方负责完整的创建、验签解析、查单、退款和关单契约，并返回 HaiResult。
+ *   payment.registerProvider(provider)
+ *   return payment.getProvider(provider.name)
+ * }
+ * ```
+ */
+interface PaymentProvider {
+    /** Provider 名称（如 'wechat', 'alipay', 'stripe'） */
+    readonly name: string;
+    /** 创建完整客户端契约的订单；unsupported 场景返回失败，不能以空参数占位成功。 */
+    createOrder: (input: CreateOrderInput) => Promise<HaiResult<PaymentOrder>>;
+    /** 对原始通知验签并解析；成功可为 pending，不能代替业务核对、持久去重和履约事务。 */
+    handleNotify: (request: PaymentNotifyRequest) => Promise<HaiResult<PaymentNotifyResult>>;
+    /** 读取并核对指定商户订单的渠道状态；未知订单或未知状态必须返回失败。 */
+    queryOrder: (orderNo: string) => Promise<HaiResult<OrderStatus>>;
+    /** 申请指定 refundNo 的退款；成功后还要区分 processing 与资金确认 success。 */
+    refund: (input: RefundInput) => Promise<HaiResult<RefundResult>>;
+    /** 只有渠道确认关闭/过期才成功；禁止无操作返回成功或关闭已付款订单。 */
+    closeOrder: (orderNo: string) => Promise<HaiResult<void>>;
+}
+/**
+ * 支付模块函数接口
+ * @example
+ * ```ts
+ * import { payment, type PaymentFunctions } from '@h-ai/payment'
+ * const service: PaymentFunctions = payment
+ * if (!service.isInitialized) throw new Error('Payment is not initialized')
+ * const result = await service.queryOrder('stripe', 'ORDER_1')
+ * if (!result.success) throw new Error(result.error.message)
+ * ```
+ */
+interface PaymentFunctions {
+    /** 按 Schema 注册渠道；Stripe 要求共享 reldb 已初始化，失败后不能启动依赖支付的业务。 */
+    init: (config: PaymentConfigInput) => Promise<HaiResult<void>>;
+    /** 清理本进程注册表与配置；不会删除持久幂等记录或关闭宿主 reldb，不返回 HaiResult。 */
+    close: () => Promise<void>;
+    /** 当前解析后的配置，关闭或未初始化时为 null；包含密钥，禁止下发浏览器或记录日志。 */
+    readonly config: PaymentConfig | null;
+    /** 是否已有成功发布的配置；不代表渠道实时可用或商户凭据已被远端验证。 */
+    readonly isInitialized: boolean;
+    /** 创建订单并返回对应场景的最小客户端参数；调用方必须先检查 success。 */
+    createOrder: (providerName: string, input: CreateOrderInput) => Promise<HaiResult<PaymentOrder>>;
+    /** 验签并解析原始回调；宿主核对金额/币种并持久去重后才可确认业务履约。 */
+    handleNotify: (providerName: string, request: PaymentNotifyRequest) => Promise<HaiResult<PaymentNotifyResult>>;
+    /** 查渠道状态；失败不能映射成未付款或直接重建订单。 */
+    queryOrder: (providerName: string, orderNo: string) => Promise<HaiResult<OrderStatus>>;
+    /** 退款标识与参数保持稳定；processing 仍需渠道核对，不能视作最终退款成功。 */
+    refund: (providerName: string, input: RefundInput) => Promise<HaiResult<RefundResult>>;
+    /** 主动关单；Stripe 只在确认 Session expired 后成功，页面返回不是关单证明。 */
+    closeOrder: (providerName: string, orderNo: string) => Promise<HaiResult<void>>;
+    /** 按名称读取本进程 Provider；未注册时为 undefined，应用通常使用统一操作入口。 */
+    getProvider: (name: string) => PaymentProvider | undefined;
+    /** 注册完整实现 PaymentProvider 的自定义渠道；同名会替换本进程注册项，生命周期由宿主协调。 */
+    registerProvider: (provider: PaymentProvider) => void;
+}
+
+export { type AlipayConfig as A, type CreateOrderInput as C, HaiPaymentError as H, type OrderStatus as O, type PaymentOrder as P, type RefundInput as R, type StripeConfig as S, type TradeType as T, type WechatPayConfig as W, type PaymentFunctions as a, AlipayConfigSchema as b, type OrderStatusValue as c, type PaymentConfig as d, type PaymentConfigInput as e, PaymentConfigSchema as f, type PaymentNotifyRequest as g, type PaymentNotifyResult as h, type PaymentProvider as i, type RefundResult as j, StripeConfigSchema as k, WechatPayConfigSchema as l };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@h-ai/payment",
   "type": "module",
-  "version": "0.1.0-alpha.66",
+  "version": "0.1.0-alpha.68",
   "description": "Hai Framework payment module for WeChat Pay, Alipay, and Stripe.",
   "license": "Apache-2.0",
   "exports": {
@@ -26,12 +26,14 @@
     "node": "^22.22.2 || ^24.15.0 || >=26.0.0"
   },
   "dependencies": {
-    "@h-ai/audit": "0.1.0-alpha.66",
-    "@h-ai/core": "0.1.0-alpha.66",
+    "@h-ai/audit": "0.1.0-alpha.68",
+    "@h-ai/core": "0.1.0-alpha.68",
+    "@h-ai/reldb": "0.1.0-alpha.68",
     "zod": "^4.6.5"
   },
   "devDependencies": {
     "@types/node": "^26.6.5",
+    "jsdom": "^30.1.2",
     "rimraf": "^6.1.3",
     "tsup": "^8.5.1",
     "typescript": "^6.0.3",

package/dist/chunk-4IUARFWH.js

@@ -1,67 +0,0 @@
-import { core } from '@h-ai/core';
-
-// src/payment-types.ts
-var PaymentErrorInfo = {
-  CREATE_ORDER_FAILED: "001:500",
-  QUERY_ORDER_FAILED: "002:500",
-  REFUND_FAILED: "003:500",
-  CLOSE_ORDER_FAILED: "004:500",
-  NOT_INITIALIZED: "010:500",
-  SIGN_FAILED: "020:500",
-  PROVIDER_NOT_FOUND: "030:404",
-  INVALID_AMOUNT: "040:400",
-  NOTIFY_VERIFY_FAILED: "050:400",
-  NOTIFY_PARSE_FAILED: "051:400",
-  INVOKE_WEB_FAILED: "060:500",
-  INVOKE_APP_FAILED: "061:500",
-  CONFIG_ERROR: "070:500"
-};
-var HaiPaymentError = core.error.buildHaiErrorsDef("payment", PaymentErrorInfo);
-
-// messages/en-US.json
-var en_US_default = {
-  payment_createOrderFailed: "Failed to create payment order",
-  payment_queryOrderFailed: "Failed to query order status",
-  payment_refundFailed: "Refund request failed",
-  payment_closeOrderFailed: "Failed to close order",
-  payment_notifyVerifyFailed: "Payment notification verification failed",
-  payment_notifyParseFailed: "Failed to parse payment notification",
-  payment_signFailed: "Payment signature generation failed",
-  payment_providerNotFound: "Payment provider not found",
-  payment_invalidAmount: "Invalid payment amount",
-  payment_notInitialized: "Payment module not initialized, call payment.init() first",
-  payment_invokeWebFailed: "Failed to invoke web payment",
-  payment_invokeAppFailed: "Failed to invoke app payment",
-  payment_configError: "Payment config validation failed: {error}",
-  payment_initFailed: "Payment module initialization failed: {error}",
-  payment_configFieldRequired: "This config field is required"
-};
-
-// messages/zh-CN.json
-var zh_CN_default = {
-  payment_createOrderFailed: "\u521B\u5EFA\u652F\u4ED8\u8BA2\u5355\u5931\u8D25",
-  payment_queryOrderFailed: "\u67E5\u8BE2\u8BA2\u5355\u72B6\u6001\u5931\u8D25",
-  payment_refundFailed: "\u9000\u6B3E\u8BF7\u6C42\u5931\u8D25",
-  payment_closeOrderFailed: "\u5173\u95ED\u8BA2\u5355\u5931\u8D25",
-  payment_notifyVerifyFailed: "\u652F\u4ED8\u56DE\u8C03\u9A8C\u7B7E\u5931\u8D25",
-  payment_notifyParseFailed: "\u89E3\u6790\u652F\u4ED8\u56DE\u8C03\u5931\u8D25",
-  payment_signFailed: "\u652F\u4ED8\u7B7E\u540D\u751F\u6210\u5931\u8D25",
-  payment_providerNotFound: "\u672A\u627E\u5230\u652F\u4ED8 Provider",
-  payment_invalidAmount: "\u652F\u4ED8\u91D1\u989D\u65E0\u6548",
-  payment_notInitialized: "\u652F\u4ED8\u6A21\u5757\u672A\u521D\u59CB\u5316\uFF0C\u8BF7\u5148\u8C03\u7528 payment.init()",
-  payment_invokeWebFailed: "\u8C03\u8D77\u7F51\u9875\u652F\u4ED8\u5931\u8D25",
-  payment_invokeAppFailed: "\u8C03\u8D77 App \u652F\u4ED8\u5931\u8D25",
-  payment_configError: "\u652F\u4ED8\u6A21\u5757\u914D\u7F6E\u6821\u9A8C\u5931\u8D25\uFF1A{error}",
-  payment_initFailed: "\u652F\u4ED8\u6A21\u5757\u521D\u59CB\u5316\u5931\u8D25\uFF1A{error}",
-  payment_configFieldRequired: "\u6B64\u914D\u7F6E\u5B57\u6BB5\u5FC5\u586B"
-};
-
-// src/payment-i18n.ts
-var paymentM = core.i18n.createMessageGetter({
-  "zh-CN": zh_CN_default,
-  "en-US": en_US_default
-});
-
-export { HaiPaymentError, paymentM };
-//# sourceMappingURL=chunk-4IUARFWH.js.map
-//# sourceMappingURL=chunk-4IUARFWH.js.map

package/dist/chunk-4IUARFWH.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/payment-types.ts","../messages/en-US.json","../messages/zh-CN.json","../src/payment-i18n.ts"],"names":["core"],"mappings":";;;AAaA,IAAM,gBAAA,GAAmB;AAAA,EACvB,mBAAA,EAAqB,SAAA;AAAA,EACrB,kBAAA,EAAoB,SAAA;AAAA,EACpB,aAAA,EAAe,SAAA;AAAA,EACf,kBAAA,EAAoB,SAAA;AAAA,EACpB,eAAA,EAAiB,SAAA;AAAA,EACjB,WAAA,EAAa,SAAA;AAAA,EACb,kBAAA,EAAoB,SAAA;AAAA,EACpB,cAAA,EAAgB,SAAA;AAAA,EAChB,oBAAA,EAAsB,SAAA;AAAA,EACtB,mBAAA,EAAqB,SAAA;AAAA,EACrB,iBAAA,EAAmB,SAAA;AAAA,EACnB,iBAAA,EAAmB,SAAA;AAAA,EACnB,YAAA,EAAc;AAChB,CAAA;AAEO,IAAM,eAAA,GAAkB,IAAA,CAAK,KAAA,CAAM,iBAAA,CAAkB,WAAW,gBAAgB;;;AC7BvF,IAAA,aAAA,GAAA;AAAA,EACE,yBAAA,EAA6B,gCAAA;AAAA,EAC7B,wBAAA,EAA4B,8BAAA;AAAA,EAC5B,oBAAA,EAAwB,uBAAA;AAAA,EACxB,wBAAA,EAA4B,uBAAA;AAAA,EAC5B,0BAAA,EAA8B,0CAAA;AAAA,EAC9B,yBAAA,EAA6B,sCAAA;AAAA,EAC7B,kBAAA,EAAsB,qCAAA;AAAA,EACtB,wBAAA,EAA4B,4BAAA;AAAA,EAC5B,qBAAA,EAAyB,wBAAA;AAAA,EACzB,sBAAA,EAA0B,2DAAA;AAAA,EAC1B,uBAAA,EAA2B,8BAAA;AAAA,EAC3B,uBAAA,EAA2B,8BAAA;AAAA,EAC3B,mBAAA,EAAuB,2CAAA;AAAA,EACvB,kBAAA,EAAsB,+CAAA;AAAA,EACtB,2BAAA,EAA+B;AACjC,CAAA;;;AChBA,IAAA,aAAA,GAAA;AAAA,EACE,yBAAA,EAA6B,kDAAA;AAAA,EAC7B,wBAAA,EAA4B,kDAAA;AAAA,EAC5B,oBAAA,EAAwB,sCAAA;AAAA,EACxB,wBAAA,EAA4B,sCAAA;AAAA,EAC5B,0BAAA,EAA8B,kDAAA;AAAA,EAC9B,yBAAA,EAA6B,kDAAA;AAAA,EAC7B,kBAAA,EAAsB,kDAAA;AAAA,EACtB,wBAAA,EAA4B,yCAAA;AAAA,EAC5B,qBAAA,EAAyB,sCAAA;AAAA,EACzB,sBAAA,EAA0B,+FAAA;AAAA,EAC1B,uBAAA,EAA2B,kDAAA;AAAA,EAC3B,uBAAA,EAA2B,2CAAA;AAAA,EAC3B,mBAAA,EAAuB,2EAAA;AAAA,EACvB,kBAAA,EAAsB,qEAAA;AAAA,EACtB,2BAAA,EAA+B;AACjC,CAAA;;;ACGO,IAAM,QAAA,GAAWA,IAAAA,CAAK,IAAA,CAAK,mBAAA,CAAuC;AAAA,EACvE,OAAA,EAAS,aAAA;AAAA,EACT,OAAA,EAAS;AACX,CAAC","file":"chunk-4IUARFWH.js","sourcesContent":["/**\n * @h-ai/payment — 类型定义\n *\n * 统一支付模块的公共类型、Provider 接口与错误类型。\n * @module payment-types\n */\n\nimport type { ErrorInfo, HaiResult } from '@h-ai/core'\nimport type { PaymentConfig, PaymentConfigInput } from './payment-config.js'\nimport { core } from '@h-ai/core'\n\n// ─── 错误定义（照 @h-ai/core 范式） ───\n\nconst PaymentErrorInfo = {\n  CREATE_ORDER_FAILED: '001:500',\n  QUERY_ORDER_FAILED: '002:500',\n  REFUND_FAILED: '003:500',\n  CLOSE_ORDER_FAILED: '004:500',\n  NOT_INITIALIZED: '010:500',\n  SIGN_FAILED: '020:500',\n  PROVIDER_NOT_FOUND: '030:404',\n  INVALID_AMOUNT: '040:400',\n  NOTIFY_VERIFY_FAILED: '050:400',\n  NOTIFY_PARSE_FAILED: '051:400',\n  INVOKE_WEB_FAILED: '060:500',\n  INVOKE_APP_FAILED: '061:500',\n  CONFIG_ERROR: '070:500',\n} as const satisfies ErrorInfo\n\nexport const HaiPaymentError = core.error.buildHaiErrorsDef('payment', PaymentErrorInfo)\n\n// ─── 支付场景 ───\n\n/** 支付场景（tradeType） */\nexport type TradeType = 'jsapi' | 'h5' | 'app' | 'native' | 'mini_program'\n\n/** 订单状态 */\nexport type OrderStatusValue = 'pending' | 'paid' | 'closed' | 'refunded' | 'failed'\n\n// ─── 创建订单 ───\n\n/** 创建订单入参 */\nexport interface CreateOrderInput {\n  /** 商户订单号 */\n  orderNo: string\n  /** 金额（分） */\n  amount: number\n  /** 币种（默认 CNY） */\n  currency?: string\n  /** 商品描述 */\n  description: string\n  /** 支付场景 */\n  tradeType: TradeType\n  /** 用户标识（微信 openid 等，jsapi 必填） */\n  userId?: string\n  /** 异步通知 URL */\n  notifyUrl: string\n  /** 附加数据（透传） */\n  metadata?: Record<string, string>\n}\n\n/** 支付订单（返回给客户端调起支付） */\nexport interface PaymentOrder {\n  /** Provider 名称 */\n  provider: string\n  /** 支付场景 */\n  tradeType: TradeType\n  /** 客户端调起参数（各平台差异） */\n  clientParams: Record<string, unknown>\n  /** 预支付 ID（如微信 prepay_id） */\n  prepayId?: string\n}\n\n// ─── 回调通知 ───\n\n/** 回调请求（原始 HTTP 数据） */\nexport interface PaymentNotifyRequest {\n  /** 请求 body */\n  body: string\n  /** 请求 headers */\n  headers: Record<string, string>\n}\n\n/** 回调解析结果 */\nexport interface PaymentNotifyResult {\n  /** 商户订单号 */\n  orderNo: string\n  /** 支付渠道交易号 */\n  transactionId: string\n  /** 支付金额（分） */\n  amount: number\n  /** 支付状态 */\n  status: OrderStatusValue\n  /** 支付时间 */\n  paidAt?: Date\n  /** 原始数据 */\n  raw?: Record<string, unknown>\n}\n\n// ─── 查询订单 ───\n\n/** 订单状态查询结果 */\nexport interface OrderStatus {\n  /** 商户订单号 */\n  orderNo: string\n  /** 渠道交易号 */\n  transactionId?: string\n  /** 订单状态 */\n  status: OrderStatusValue\n  /** 金额（分） */\n  amount: number\n  /** 支付时间 */\n  paidAt?: Date\n}\n\n// ─── 退款 ───\n\n/** 退款入参 */\nexport interface RefundInput {\n  /** 商户订单号 */\n  orderNo: string\n  /** 退款单号 */\n  refundNo: string\n  /** 退款金额（分） */\n  amount: number\n  /** 订单总金额（分），微信退款必填 */\n  totalAmount?: number\n  /** 退款原因 */\n  reason?: string\n}\n\n/** 退款结果 */\nexport interface RefundResult {\n  /** 退款单号 */\n  refundNo: string\n  /** 渠道退款 ID */\n  refundId: string\n  /** 退款状态 */\n  status: 'processing' | 'success' | 'failed'\n}\n\n// ─── Provider 接口 ───\n\n/**\n * 支付 Provider 接口\n *\n * 各支付渠道（微信/支付宝/Stripe）实现此接口，\n * 由 payment 模块统一调度。\n */\nexport interface PaymentProvider {\n  /** Provider 名称（如 'wechat', 'alipay', 'stripe'） */\n  readonly name: string\n\n  /** 创建支付订单 */\n  createOrder: (input: CreateOrderInput) => Promise<HaiResult<PaymentOrder>>\n\n  /** 处理异步通知回调（验签 + 解析） */\n  handleNotify: (request: PaymentNotifyRequest) => Promise<HaiResult<PaymentNotifyResult>>\n\n  /** 查询订单状态 */\n  queryOrder: (orderNo: string) => Promise<HaiResult<OrderStatus>>\n\n  /** 申请退款 */\n  refund: (input: RefundInput) => Promise<HaiResult<RefundResult>>\n\n  /** 关闭订单 */\n  closeOrder: (orderNo: string) => Promise<HaiResult<void>>\n}\n\n// ─── 函数接口 ───\n\n/** 支付模块函数接口 */\nexport interface PaymentFunctions {\n  init: (config: PaymentConfigInput) => Promise<HaiResult<void>>\n  close: () => Promise<void>\n  readonly config: PaymentConfig | null\n  readonly isInitialized: boolean\n  createOrder: (providerName: string, input: CreateOrderInput) => Promise<HaiResult<PaymentOrder>>\n  handleNotify: (providerName: string, request: PaymentNotifyRequest) => Promise<HaiResult<PaymentNotifyResult>>\n  queryOrder: (providerName: string, orderNo: string) => Promise<HaiResult<OrderStatus>>\n  refund: (providerName: string, input: RefundInput) => Promise<HaiResult<RefundResult>>\n  closeOrder: (providerName: string, orderNo: string) => Promise<HaiResult<void>>\n  getProvider: (name: string) => PaymentProvider | undefined\n  registerProvider: (provider: PaymentProvider) => void\n}\n","{\n  \"payment_createOrderFailed\": \"Failed to create payment order\",\n  \"payment_queryOrderFailed\": \"Failed to query order status\",\n  \"payment_refundFailed\": \"Refund request failed\",\n  \"payment_closeOrderFailed\": \"Failed to close order\",\n  \"payment_notifyVerifyFailed\": \"Payment notification verification failed\",\n  \"payment_notifyParseFailed\": \"Failed to parse payment notification\",\n  \"payment_signFailed\": \"Payment signature generation failed\",\n  \"payment_providerNotFound\": \"Payment provider not found\",\n  \"payment_invalidAmount\": \"Invalid payment amount\",\n  \"payment_notInitialized\": \"Payment module not initialized, call payment.init() first\",\n  \"payment_invokeWebFailed\": \"Failed to invoke web payment\",\n  \"payment_invokeAppFailed\": \"Failed to invoke app payment\",\n  \"payment_configError\": \"Payment config validation failed: {error}\",\n  \"payment_initFailed\": \"Payment module initialization failed: {error}\",\n  \"payment_configFieldRequired\": \"This config field is required\"\n}\n","{\n  \"payment_createOrderFailed\": \"创建支付订单失败\",\n  \"payment_queryOrderFailed\": \"查询订单状态失败\",\n  \"payment_refundFailed\": \"退款请求失败\",\n  \"payment_closeOrderFailed\": \"关闭订单失败\",\n  \"payment_notifyVerifyFailed\": \"支付回调验签失败\",\n  \"payment_notifyParseFailed\": \"解析支付回调失败\",\n  \"payment_signFailed\": \"支付签名生成失败\",\n  \"payment_providerNotFound\": \"未找到支付 Provider\",\n  \"payment_invalidAmount\": \"支付金额无效\",\n  \"payment_notInitialized\": \"支付模块未初始化，请先调用 payment.init()\",\n  \"payment_invokeWebFailed\": \"调起网页支付失败\",\n  \"payment_invokeAppFailed\": \"调起 App 支付失败\",\n  \"payment_configError\": \"支付模块配置校验失败：{error}\",\n  \"payment_initFailed\": \"支付模块初始化失败：{error}\",\n  \"payment_configFieldRequired\": \"此配置字段必填\"\n}\n","/**\n * @h-ai/payment — i18n\n *\n * 模块 i18n 文案访问入口。\n * @module payment-i18n\n */\n\nimport { core } from '@h-ai/core'\nimport messagesEnUS from '../messages/en-US.json'\nimport messagesZhCN from '../messages/zh-CN.json'\n\ntype PaymentMessageKey = keyof typeof messagesZhCN\n\n/**\n * payment 模块 i18n 文案获取器\n *\n * @param key - 文案 Key\n * @returns 本地化后的文案字符串\n */\nexport const paymentM = core.i18n.createMessageGetter<PaymentMessageKey>({\n  'zh-CN': messagesZhCN,\n  'en-US': messagesEnUS,\n})\n"]}