@zucker-framework/payment 1.0.0 → 1.0.3

package/dist/index.js

@@ -21,20 +21,194 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  DatabaseOrderPersistence: () => DatabaseOrderPersistence,
+  ORDER_PERSISTENCE: () => ORDER_PERSISTENCE,
+  OrderNotFoundError: () => OrderNotFoundError,
   OrderService: () => OrderService,
   PAYMENT_PROVIDERS: () => PAYMENT_PROVIDERS,
+  PAYPAL_SUPPORTED_CURRENCIES: () => PAYPAL_SUPPORTED_CURRENCIES,
+  PayPalPaymentTransport: () => PayPalPaymentTransport,
   PaymentEvents: () => PaymentEvents,
+  PaymentProviderRegistry: () => PaymentProviderRegistry,
   PaymentRecoveryService: () => PaymentRecoveryService,
-  PaymentService: () => PaymentService,
+  RECOVERY_ATTEMPT_STORE: () => RECOVERY_ATTEMPT_STORE,
   RECOVERY_MAIL_SENDER: () => RECOVERY_MAIL_SENDER,
   RECOVERY_URL_GENERATOR: () => RECOVERY_URL_GENERATOR,
   RECOVERY_USER_LOOKUP: () => RECOVERY_USER_LOOKUP,
+  SETTLEMENT_STATES: () => SETTLEMENT_STATES,
   ZuckerPaymentModule: () => ZuckerPaymentModule,
-  friendlyErrorReason: () => friendlyErrorReason
+  adapterSupportsCurrency: () => adapterSupportsCurrency,
+  checkPaymentAdapterContract: () => checkPaymentAdapterContract,
+  createFakeAdapter: () => createFakeAdapter,
+  createPayPalAdapter: () => createPayPalAdapter,
+  createStripeAdapter: () => createStripeAdapter,
+  createStripeCheckoutSession: () => createStripeCheckoutSession,
+  createStripeClient: () => createStripeClient,
+  currencyExponent: () => currencyExponent,
+  decodePayPalMoneyReturnedEvent: () => decodePayPalMoneyReturnedEvent,
+  decodePayPalWebhookEvent: () => decodePayPalWebhookEvent,
+  friendlyErrorReason: () => friendlyErrorReason,
+  fromMinorUnits: () => fromMinorUnits,
+  isMoneyMoved: () => isMoneyMoved,
+  isTerminal: () => isTerminal,
+  observePayPalOrder: () => observePayPalOrder,
+  observePayPalState: () => observePayPalState,
+  observeStripeCheckoutSession: () => observeStripeCheckoutSession,
+  observeStripePaymentIntent: () => observeStripePaymentIntent,
+  observeStripeState: () => observeStripeState,
+  reconcile: () => reconcile,
+  retrieveStripeCheckoutSession: () => retrieveStripeCheckoutSession,
+  retrieveStripePaymentIntent: () => retrieveStripePaymentIntent,
+  stripeResourceId: () => stripeResourceId,
+  toMinorUnits: () => toMinorUnits,
+  verifyStripeWebhookEvent: () => verifyStripeWebhookEvent
 });
 module.exports = __toCommonJS(index_exports);
 
-// src/payment.service.ts
+// src/contract/payment-contract.ts
+function adapterSupportsCurrency(adapter, currency) {
+  return !adapter.supportedCurrencies || adapter.supportedCurrencies.includes(currency.toUpperCase());
+}
+__name(adapterSupportsCurrency, "adapterSupportsCurrency");
+
+// src/contract/settlement.ts
+var SETTLEMENT_STATES = [
+  /** 已创建，用户尚未授权 */
+  "created",
+  /** 用户已授权但尚未扣款（PayPal APPROVED / Stripe requires_capture） */
+  "authorized",
+  /** 已扣款 */
+  "captured",
+  /** 已全额退款 */
+  "refunded",
+  /** 已部分退款 */
+  "partially_refunded",
+  /** 终态失败 */
+  "failed",
+  /** 终态取消（用户放弃 / 商户撤单） */
+  "canceled",
+  /**
+  * 无法判定。
+  * 不是"失败"，也不是一个可持久化的终态——查询异常、供应商返回中间态、
+  * 回调迟到都会落到这里，必须保留原状继续观察。
+  */
+  "unknown"
+];
+var MONEY_MOVED = /* @__PURE__ */ new Set([
+  "captured",
+  "refunded",
+  "partially_refunded"
+]);
+var TERMINAL = /* @__PURE__ */ new Set([
+  "refunded",
+  "failed",
+  "canceled"
+]);
+function isMoneyMoved(state) {
+  return MONEY_MOVED.has(state);
+}
+__name(isMoneyMoved, "isMoneyMoved");
+function isTerminal(state) {
+  return TERMINAL.has(state);
+}
+__name(isTerminal, "isTerminal");
+function reconcile(current, observed) {
+  if (observed === "unknown") {
+    return {
+      next: current,
+      changed: false,
+      rejected: "not-observable"
+    };
+  }
+  if (observed === current) {
+    return {
+      next: current,
+      changed: false
+    };
+  }
+  if (isMoneyMoved(current) && (observed === "failed" || observed === "canceled")) {
+    return {
+      next: current,
+      changed: false,
+      rejected: "money-already-moved"
+    };
+  }
+  if (current === "refunded") {
+    return {
+      next: current,
+      changed: false,
+      rejected: "already-terminal"
+    };
+  }
+  if (current === "partially_refunded" && observed === "captured") {
+    return {
+      next: current,
+      changed: false,
+      rejected: "already-terminal"
+    };
+  }
+  if (isTerminal(current) && !isMoneyMoved(observed)) {
+    return {
+      next: current,
+      changed: false,
+      rejected: "already-terminal"
+    };
+  }
+  return {
+    next: observed,
+    changed: true
+  };
+}
+__name(reconcile, "reconcile");
+
+// src/contract/money.ts
+var ZERO_DECIMAL = /* @__PURE__ */ new Set([
+  "BIF",
+  "CLP",
+  "DJF",
+  "GNF",
+  "JPY",
+  "KMF",
+  "KRW",
+  "MGA",
+  "PYG",
+  "RWF",
+  "UGX",
+  "VND",
+  "VUV",
+  "XAF",
+  "XOF",
+  "XPF"
+]);
+function currencyExponent(currency) {
+  return ZERO_DECIMAL.has(currency.toUpperCase()) ? 0 : 2;
+}
+__name(currencyExponent, "currencyExponent");
+function toMinorUnits(amount, currency) {
+  const exponent = currencyExponent(currency);
+  const match = /^(-?)(\d+)(?:\.(\d*))?$/.exec(amount.trim());
+  if (!match) throw new Error(`\u91D1\u989D\u683C\u5F0F\u975E\u6CD5\uFF1A${amount}`);
+  const [, sign, whole, fraction = ""] = match;
+  if (fraction.length > exponent && /[^0]/.test(fraction.slice(exponent))) {
+    throw new Error(`${currency} \u6700\u591A\u652F\u6301 ${exponent} \u4F4D\u5C0F\u6570\uFF0C\u6536\u5230 ${amount}`);
+  }
+  const padded = (fraction + "0".repeat(exponent)).slice(0, exponent);
+  const value = Number(`${whole}${padded}`);
+  if (!Number.isSafeInteger(value)) throw new Error(`\u91D1\u989D\u8D85\u51FA\u5B89\u5168\u6574\u6570\u8303\u56F4\uFF1A${amount}`);
+  return sign === "-" ? -value : value;
+}
+__name(toMinorUnits, "toMinorUnits");
+function fromMinorUnits(value, currency) {
+  if (!Number.isInteger(value)) throw new Error(`\u6700\u5C0F\u5355\u4F4D\u5FC5\u987B\u662F\u6574\u6570\uFF1A${value}`);
+  const exponent = currencyExponent(currency);
+  const sign = value < 0 ? "-" : "";
+  const digits = String(Math.abs(value)).padStart(exponent + 1, "0");
+  if (exponent === 0) return `${sign}${digits}`;
+  return `${sign}${digits.slice(0, -exponent)}.${digits.slice(-exponent)}`;
+}
+__name(fromMinorUnits, "fromMinorUnits");
+
+// src/contract/registry.ts
 var import_common = require("@nestjs/common");
 function _ts_decorate(decorators, target, key, desc) {
   var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
@@ -50,76 +224,631 @@ function _ts_decorate(decorators, target, key, desc) {
   return c > 3 && r && Object.defineProperty(target, key, r), r;
 }
 __name(_ts_decorate, "_ts_decorate");
-var PaymentService = class _PaymentService {
+function _ts_metadata(metadataKey, metadataValue) {
+  if (typeof Reflect === "object" && typeof Reflect.metadata === "function") {
+    return Reflect.metadata(metadataKey, metadataValue);
+  }
+}
+__name(_ts_metadata, "_ts_metadata");
+var PaymentProviderRegistry = class _PaymentProviderRegistry {
   static {
-    __name(this, "PaymentService");
-  }
-  logger = new import_common.Logger(_PaymentService.name);
-  providers = /* @__PURE__ */ new Map();
-  /** 注册支付提供商 */
-  register(provider) {
-    if (this.providers.has(provider.id)) {
-      this.logger.warn(`PaymentProvider "${provider.id}" \u5DF2\u6CE8\u518C\uFF0C\u5C06\u88AB\u8986\u76D6`);
-    }
-    this.providers.set(provider.id, provider);
-    this.logger.log(`PaymentProvider "${provider.id}" (${provider.name}) \u5DF2\u6CE8\u518C`);
-  }
-  /** 注销支付提供商 */
-  unregister(providerId) {
-    const removed = this.providers.delete(providerId);
-    if (removed) {
-      this.logger.log(`PaymentProvider "${providerId}" \u5DF2\u6CE8\u9500`);
-    }
-    return removed;
-  }
-  /** 获取已注册的提供商列表 */
-  listProviders() {
-    return Array.from(this.providers.values());
-  }
-  /** 获取指定提供商 */
-  getProvider(providerId) {
-    const provider = this.providers.get(providerId);
-    if (!provider) {
-      throw new Error(`PaymentProvider "${providerId}" \u672A\u6CE8\u518C\u3002\u5DF2\u6CE8\u518C: [${Array.from(this.providers.keys()).join(", ")}]`);
-    }
-    return provider;
-  }
-  /** 创建支付意图 */
-  async createPaymentIntent(providerId, params) {
-    const provider = this.getProvider(providerId);
-    this.logger.log(`[${providerId}] \u521B\u5EFA\u652F\u4ED8\u610F\u56FE: ${params.amount} ${params.currency}`);
-    return provider.createPaymentIntent(params);
-  }
-  /** 确认支付 */
-  async confirmPayment(providerId, intentId) {
-    const provider = this.getProvider(providerId);
-    this.logger.log(`[${providerId}] \u786E\u8BA4\u652F\u4ED8: ${intentId}`);
-    return provider.confirmPayment(intentId);
-  }
-  /** 退款 */
-  async refund(providerId, paymentId, amount, reason) {
-    const provider = this.getProvider(providerId);
-    this.logger.log(`[${providerId}] \u9000\u6B3E: ${paymentId}, amount=${amount ?? "full"}`);
-    return provider.refund(paymentId, amount, reason);
-  }
-  /** 查询支付状态 */
-  async getPaymentStatus(providerId, intentId) {
-    const provider = this.getProvider(providerId);
-    return provider.getPaymentStatus(intentId);
-  }
-  /** 处理 Webhook */
-  async handleWebhook(providerId, payload, signature) {
-    const provider = this.getProvider(providerId);
-    this.logger.log(`[${providerId}] \u5904\u7406 Webhook`);
-    return provider.handleWebhook(payload, signature);
+    __name(this, "PaymentProviderRegistry");
+  }
+  logger = new import_common.Logger(_PaymentProviderRegistry.name);
+  adapters = /* @__PURE__ */ new Map();
+  constructor(adapters = []) {
+    for (const adapter of adapters) this.register(adapter);
+  }
+  register(adapter) {
+    if (this.adapters.has(adapter.id)) {
+      throw new Error(`\u6E20\u9053 "${adapter.id}" \u5DF2\u6CE8\u518C\uFF1B\u91CD\u590D\u6CE8\u518C\u901A\u5E38\u610F\u5473\u7740\u88C5\u914D\u9519\u8BEF\uFF0C\u4E0D\u4E88\u9759\u9ED8\u8986\u76D6`);
+    }
+    this.adapters.set(adapter.id, adapter);
+    this.logger.log(`\u5DF2\u6CE8\u518C\u652F\u4ED8\u6E20\u9053 "${adapter.id}"`);
+  }
+  has(id) {
+    return this.adapters.has(id);
+  }
+  get(id) {
+    const adapter = this.adapters.get(id);
+    if (!adapter) {
+      throw new Error(`\u6E20\u9053 "${id}" \u672A\u6CE8\u518C\u3002\u5DF2\u6CE8\u518C\uFF1A[${[
+        ...this.adapters.keys()
+      ].join(", ")}]`);
+    }
+    return adapter;
+  }
+  list() {
+    return [
+      ...this.adapters.values()
+    ];
+  }
+  /** 能处理该币种的渠道；"本产品卖不卖这个币种"由上层决定，不在这里过滤。 */
+  listForCurrency(currency) {
+    return this.list().filter((adapter) => adapterSupportsCurrency(adapter, currency));
   }
 };
-PaymentService = _ts_decorate([
-  (0, import_common.Injectable)()
-], PaymentService);
+PaymentProviderRegistry = _ts_decorate([
+  (0, import_common.Injectable)(),
+  _ts_metadata("design:type", Function),
+  _ts_metadata("design:paramtypes", [
+    Object
+  ])
+], PaymentProviderRegistry);
+
+// src/contract/adapters/paypal.adapter.ts
+var CAPTURE_INTENT = "CAPTURE";
+var PAY_NOW = "PAY_NOW";
+var NO_SHIPPING = "NO_SHIPPING";
+var PAYPAL_SUPPORTED_CURRENCIES = [
+  "AUD",
+  "BRL",
+  "CAD",
+  "CNY",
+  "CZK",
+  "DKK",
+  "EUR",
+  "HKD",
+  "HUF",
+  "ILS",
+  "JPY",
+  "MYR",
+  "MXN",
+  "TWD",
+  "NZD",
+  "NOK",
+  "PHP",
+  "PLN",
+  "GBP",
+  "RUB",
+  "SGD",
+  "SEK",
+  "CHF",
+  "THB",
+  "USD"
+];
+function observePayPalState(order) {
+  const captures = order.purchaseUnits?.[0]?.payments?.captures ?? [];
+  switch (order.status) {
+    case "CREATED":
+    case "SAVED":
+    case "PAYER_ACTION_REQUIRED":
+      return "created";
+    case "APPROVED":
+      return "authorized";
+    case "VOIDED":
+      return "canceled";
+    case "COMPLETED": {
+      if (captures.some((capture) => capture.status === "COMPLETED")) return "captured";
+      if (captures.some((c) => c.status === "DECLINED" || c.status === "FAILED")) return "failed";
+      return "authorized";
+    }
+    default:
+      return "unknown";
+  }
+}
+__name(observePayPalState, "observePayPalState");
+function createPayPalAdapter(options) {
+  const { transport } = options;
+  const toSession = /* @__PURE__ */ __name((order) => {
+    const unit = order.purchaseUnits?.[0];
+    const approve = order.links?.find((link) => link.rel === "approve")?.href;
+    return {
+      providerRef: order.id ?? "",
+      nextAction: approve ? {
+        kind: "redirect",
+        url: approve
+      } : {
+        kind: "none"
+      },
+      state: observePayPalState(order),
+      money: {
+        amount: unit?.amount?.value ?? "0",
+        currency: unit?.amount?.currencyCode ?? ""
+      },
+      raw: order
+    };
+  }, "toSession");
+  return {
+    id: "paypal",
+    supportedCurrencies: PAYPAL_SUPPORTED_CURRENCIES,
+    async createPayment(input2) {
+      const payment = await transport.createOrder({
+        body: {
+          intent: CAPTURE_INTENT,
+          purchaseUnits: [
+            {
+              referenceId: input2.reference,
+              amount: {
+                currencyCode: input2.money.currency,
+                // 原样透传十进制字符串，不经过 Number
+                value: input2.money.amount
+              },
+              description: input2.description
+            }
+          ],
+          applicationContext: {
+            returnUrl: input2.returnUrl,
+            cancelUrl: input2.cancelUrl,
+            userAction: PAY_NOW,
+            shippingPreference: NO_SHIPPING,
+            brandName: options.brandName
+          }
+        },
+        // 幂等：同一个键重试，PayPal 返回同一笔订单
+        paypalRequestId: input2.idempotencyKey,
+        prefer: "return=representation"
+      });
+      return toSession(payment.raw);
+    },
+    async capture(providerRef, idempotencyKey) {
+      const payment = await transport.captureOrder({
+        id: providerRef,
+        paypalRequestId: idempotencyKey,
+        prefer: "return=representation"
+      });
+      return toSession(payment.raw);
+    },
+    /** 只读。对账会反复调用它，绝不能在这里触发 captureOrder。 */
+    async retrieve(providerRef) {
+      const payment = await transport.getOrder({
+        id: providerRef
+      });
+      return toSession(payment.raw);
+    },
+    async refund(input2) {
+      const refund = await transport.refundCapture(input2.providerRef, {
+        ...input2.money ? {
+          amount: {
+            value: input2.money.amount,
+            currency_code: input2.money.currency
+          }
+        } : {},
+        note_to_payer: input2.reason
+      }, input2.idempotencyKey);
+      return {
+        refundRef: refund.id ?? "",
+        state: refund.status === "COMPLETED" ? "refunded" : "unknown"
+      };
+    },
+    async parseWebhook(request) {
+      if (!options.webhookId) {
+        throw new Error("PayPal webhookId is not configured; refusing to trust the request");
+      }
+      const body = typeof request.rawBody === "string" ? request.rawBody : new TextDecoder().decode(request.rawBody);
+      const valid = await transport.verifyWebhookSignature(body, request.headers, options.webhookId);
+      if (!valid) throw new Error("PayPal webhook signature verification failed");
+      const event = JSON.parse(body);
+      const type = event.event_type ?? "unknown";
+      const providerRef = event.resource?.supplementary_data?.related_ids?.order_id;
+      const state = type === "PAYMENT.CAPTURE.COMPLETED" ? "captured" : type === "PAYMENT.CAPTURE.DENIED" || type === "PAYMENT.CAPTURE.DECLINED" ? "failed" : type === "PAYMENT.CAPTURE.REFUNDED" ? "refunded" : type === "PAYMENT.CAPTURE.REVERSED" ? "refunded" : "unknown";
+      return {
+        type,
+        providerRef,
+        state,
+        raw: event
+      };
+    }
+  };
+}
+__name(createPayPalAdapter, "createPayPalAdapter");
+
+// src/providers/stripe.ts
+var import_node_module = require("module");
+var import_meta = {};
+var requireSdk = (0, import_node_module.createRequire)(typeof __filename === "string" ? __filename : import_meta.url);
+function createStripeClient(secretKey, options) {
+  const StripeSdk = requireSdk("stripe");
+  return new StripeSdk(secretKey, options);
+}
+__name(createStripeClient, "createStripeClient");
+function verifyStripeWebhookEvent(client, payload, signature, webhookSecret) {
+  return client.webhooks.constructEvent(payload, signature, webhookSecret);
+}
+__name(verifyStripeWebhookEvent, "verifyStripeWebhookEvent");
+function stripeResourceId(value) {
+  return typeof value === "string" ? value : value?.id;
+}
+__name(stripeResourceId, "stripeResourceId");
+function observeStripeCheckoutSession(raw) {
+  return {
+    raw,
+    id: raw.id,
+    url: raw.url || void 0,
+    clientReferenceId: raw.client_reference_id || void 0,
+    paymentIntentId: stripeResourceId(raw.payment_intent),
+    subscriptionId: stripeResourceId(raw.subscription),
+    settlement: raw.payment_status === "paid" ? "paid" : raw.status === "expired" ? "unpaid" : "unknown"
+  };
+}
+__name(observeStripeCheckoutSession, "observeStripeCheckoutSession");
+async function createStripeCheckoutSession(client, params, options) {
+  return observeStripeCheckoutSession(options ? await client.checkout.sessions.create(params, options) : await client.checkout.sessions.create(params));
+}
+__name(createStripeCheckoutSession, "createStripeCheckoutSession");
+async function retrieveStripeCheckoutSession(client, id) {
+  return observeStripeCheckoutSession(await client.checkout.sessions.retrieve(id));
+}
+__name(retrieveStripeCheckoutSession, "retrieveStripeCheckoutSession");
+function observeStripePaymentIntent(raw) {
+  const charge = typeof raw.latest_charge === "object" ? raw.latest_charge : null;
+  return {
+    raw,
+    id: raw.id,
+    chargeId: stripeResourceId(raw.latest_charge) ?? null,
+    paymentMethodType: charge?.payment_method_details?.type,
+    failureCode: raw.last_payment_error?.code,
+    failureMessage: raw.last_payment_error?.message,
+    settlement: raw.status === "succeeded" ? "paid" : raw.status === "canceled" ? "unpaid" : "unknown"
+  };
+}
+__name(observeStripePaymentIntent, "observeStripePaymentIntent");
+async function retrieveStripePaymentIntent(client, id, params) {
+  const raw = params ? await client.paymentIntents.retrieve(id, params) : await client.paymentIntents.retrieve(id);
+  return observeStripePaymentIntent(raw);
+}
+__name(retrieveStripePaymentIntent, "retrieveStripePaymentIntent");
+
+// src/contract/adapters/stripe.adapter.ts
+function observeStripeState(session) {
+  if (session.payment_status === "paid" || session.payment_status === "no_payment_required") {
+    return "captured";
+  }
+  if (session.status === "expired") return "canceled";
+  if (session.status === "open") return "created";
+  return "unknown";
+}
+__name(observeStripeState, "observeStripeState");
+function createStripeAdapter(options) {
+  const { client } = options;
+  const toSession = /* @__PURE__ */ __name((raw) => ({
+    providerRef: raw.id,
+    nextAction: raw.url ? {
+      kind: "redirect",
+      url: raw.url
+    } : {
+      kind: "none"
+    },
+    state: observeStripeState(raw),
+    money: {
+      amount: fromMinorUnits(raw.amount_total ?? 0, raw.currency ?? "usd"),
+      currency: (raw.currency ?? "").toUpperCase()
+    },
+    raw
+  }), "toSession");
+  return {
+    id: "stripe",
+    // Stripe 支持的币种远超本契约会用到的范围，不声明限制；
+    // 不受支持的币种由 Stripe 自己拒绝，胡乱穷举一份只会过期。
+    supportedCurrencies: void 0,
+    async createPayment(input2) {
+      const observation = await createStripeCheckoutSession(client, {
+        mode: "payment",
+        line_items: [
+          {
+            price_data: {
+              currency: input2.money.currency.toLowerCase(),
+              product_data: {
+                name: input2.description || input2.reference
+              },
+              unit_amount: toMinorUnits(input2.money.amount, input2.money.currency)
+            },
+            quantity: 1
+          }
+        ],
+        success_url: input2.returnUrl,
+        cancel_url: input2.cancelUrl,
+        client_reference_id: input2.reference,
+        metadata: input2.metadata,
+        ...options.paymentMethodConfiguration ? {
+          payment_method_configuration: options.paymentMethodConfiguration
+        } : {}
+      }, {
+        idempotencyKey: input2.idempotencyKey
+      });
+      return toSession(observation.raw);
+    },
+    /**
+    * Stripe Checkout 默认自动扣款，没有独立的 capture 步骤。
+    * 按契约仍需实现：返回当前真实状态即可，不得伪造成已扣款。
+    */
+    async capture(providerRef) {
+      const observation = await retrieveStripeCheckoutSession(client, providerRef);
+      return toSession(observation.raw);
+    },
+    async retrieve(providerRef) {
+      const observation = await retrieveStripeCheckoutSession(client, providerRef);
+      return toSession(observation.raw);
+    },
+    async refund(input2) {
+      const session = await retrieveStripeCheckoutSession(client, input2.providerRef);
+      const paymentIntent = session.paymentIntentId;
+      if (!paymentIntent) throw new Error("\u8BE5 Checkout \u4F1A\u8BDD\u6CA1\u6709\u53EF\u9000\u6B3E\u7684 PaymentIntent");
+      const refund = await client.refunds.create({
+        payment_intent: paymentIntent,
+        ...input2.money ? {
+          amount: toMinorUnits(input2.money.amount, input2.money.currency)
+        } : {}
+      }, {
+        idempotencyKey: input2.idempotencyKey
+      });
+      return {
+        refundRef: refund.id,
+        state: refund.status === "succeeded" ? "refunded" : "unknown"
+      };
+    },
+    async parseWebhook(request) {
+      if (!options.webhookSecret) {
+        throw new Error("Stripe webhookSecret is not configured; refusing to trust the request");
+      }
+      const signature = request.headers["stripe-signature"];
+      if (!signature) throw new Error("Stripe webhook is missing the stripe-signature header");
+      const event = verifyStripeWebhookEvent(client, typeof request.rawBody === "string" ? request.rawBody : Buffer.from(request.rawBody), signature, options.webhookSecret);
+      const object = event.data.object;
+      const state = event.type === "checkout.session.completed" ? observeStripeState(event.data.object) : event.type === "checkout.session.expired" ? "canceled" : event.type === "charge.refunded" ? "refunded" : "unknown";
+      return {
+        type: event.type,
+        providerRef: object.id,
+        state,
+        raw: event
+      };
+    }
+  };
+}
+__name(createStripeAdapter, "createStripeAdapter");
+
+// src/contract/contract-suite.ts
+var MUTATING = [
+  "capture",
+  "refund",
+  "cancel"
+];
+async function checkPaymentAdapterContract(probe) {
+  const checks = [];
+  const captureNames = probe.captureCallNames ?? MUTATING;
+  const run = /* @__PURE__ */ __name(async (name, fn) => {
+    try {
+      const detail = await fn();
+      checks.push({
+        name,
+        ok: detail === void 0,
+        detail
+      });
+    } catch (error) {
+      checks.push({
+        name,
+        ok: false,
+        detail: `\u629B\u51FA\u5F02\u5E38\uFF1A${error instanceof Error ? error.message : String(error)}`
+      });
+    }
+  }, "run");
+  await run("retrieve \u5FC5\u987B\u53EA\u8BFB", async () => {
+    const { adapter, mutatingCalls } = probe.create();
+    const created = await adapter.createPayment(input(probe.supportedCurrency));
+    const before = mutatingCalls().filter((c) => captureNames.includes(c)).length;
+    await adapter.retrieve(created.providerRef);
+    const after = mutatingCalls().filter((c) => captureNames.includes(c)).length;
+    return after > before ? `retrieve \u89E6\u53D1\u4E86\u5199\u64CD\u4F5C\uFF1A${mutatingCalls().join(", ")}` : void 0;
+  });
+  await run("\u76F8\u540C\u5E42\u7B49\u952E\u4E0D\u5F97\u4EA7\u751F\u7B2C\u4E8C\u7B14\u652F\u4ED8", async () => {
+    const { adapter } = probe.create();
+    const key = "contract-idempotency-key";
+    const first = await adapter.createPayment(input(probe.supportedCurrency, key));
+    const second = await adapter.createPayment(input(probe.supportedCurrency, key));
+    return first.providerRef === second.providerRef ? void 0 : `\u4EA7\u751F\u4E86\u4E24\u7B14\uFF1A${first.providerRef} \u4E0E ${second.providerRef}`;
+  });
+  await run("\u9A8C\u7B7E\u5931\u8D25\u5FC5\u987B\u629B\u9519\u800C\u975E\u8FD4\u56DE\u672A\u77E5\u4E8B\u4EF6", async () => {
+    const { adapter } = probe.create();
+    try {
+      const observation = await adapter.parseWebhook(probe.invalidWebhook);
+      return `\u672A\u629B\u9519\uFF0C\u8FD4\u56DE\u4E86 ${JSON.stringify(observation.type)}`;
+    } catch {
+      return void 0;
+    }
+  });
+  await run("\u91D1\u989D\u5FC5\u987B\u4EE5\u5341\u8FDB\u5236\u5B57\u7B26\u4E32\u539F\u6837\u900F\u4F20", async () => {
+    const { adapter } = probe.create();
+    const amount = "29.00";
+    const created = await adapter.createPayment({
+      ...input(probe.supportedCurrency),
+      money: {
+        amount,
+        currency: probe.supportedCurrency
+      }
+    });
+    return created.money.amount === amount ? void 0 : `\u671F\u671B "${amount}"\uFF0C\u5B9E\u9645 ${JSON.stringify(created.money.amount)}`;
+  });
+  await run("\u5728\u9014\u652F\u4ED8\u4E0D\u5F97\u88AB\u5224\u4E3A failed", async () => {
+    const { adapter } = probe.create();
+    const created = await adapter.createPayment(input(probe.supportedCurrency));
+    const retrieved = await adapter.retrieve(created.providerRef);
+    return retrieved.state === "failed" ? "\u521A\u521B\u5EFA\u3001\u7528\u6237\u5C1A\u672A\u64CD\u4F5C\u7684\u652F\u4ED8\u88AB\u5224\u4E3A failed" : void 0;
+  });
+  await run("nextAction \u5FC5\u987B\u662F\u5951\u7EA6\u5185\u7684 kind", async () => {
+    const { adapter } = probe.create();
+    const created = await adapter.createPayment(input(probe.supportedCurrency));
+    const known = [
+      "redirect",
+      "qrcode",
+      "form_post",
+      "sdk_params",
+      "none"
+    ];
+    return known.includes(created.nextAction.kind) ? void 0 : `\u672A\u77E5 kind\uFF1A${created.nextAction.kind}`;
+  });
+  await run("\u5E01\u79CD\u80FD\u529B\u58F0\u660E\u4E0E\u5B9E\u9645\u4E00\u81F4", async () => {
+    const { adapter } = probe.create();
+    if (!adapter.supportedCurrencies) return void 0;
+    if (!adapterSupportsCurrency(adapter, probe.supportedCurrency)) {
+      return `\u58F0\u660E\u4E0D\u652F\u6301 ${probe.supportedCurrency}\uFF0C\u4F46\u63A2\u9488\u79F0\u5176\u652F\u6301`;
+    }
+    if (probe.unsupportedCurrency && adapterSupportsCurrency(adapter, probe.unsupportedCurrency)) {
+      return `\u58F0\u660E\u652F\u6301 ${probe.unsupportedCurrency}\uFF0C\u4F46\u63A2\u9488\u79F0\u5176\u4E0D\u652F\u6301`;
+    }
+    return void 0;
+  });
+  return checks;
+}
+__name(checkPaymentAdapterContract, "checkPaymentAdapterContract");
+function input(currency, idempotencyKey = "contract-default-key") {
+  return {
+    reference: "contract-order",
+    money: {
+      amount: "10.00",
+      currency
+    },
+    idempotencyKey
+  };
+}
+__name(input, "input");
+
+// src/contract/fake-adapter.ts
+function createFakeAdapter(options = {}) {
+  const defects = options.defects ?? {};
+  const payments = /* @__PURE__ */ new Map();
+  const byIdempotencyKey = /* @__PURE__ */ new Map();
+  const mutatingCalls = [];
+  let counter = 0;
+  const adapter = {
+    id: options.id ?? "fake",
+    supportedCurrencies: options.supportedCurrencies,
+    async createPayment(input2) {
+      mutatingCalls.push("createPayment");
+      const existing = defects.ignoreIdempotency ? void 0 : byIdempotencyKey.get(input2.idempotencyKey);
+      if (existing) {
+        const payment2 = payments.get(existing);
+        return session(payment2);
+      }
+      const ref = `fake_${++counter}`;
+      const amount = defects.mangleAmount ? String(Number(input2.money.amount)) : input2.money.amount;
+      const payment = {
+        ref,
+        state: "created",
+        amount,
+        currency: input2.money.currency
+      };
+      payments.set(ref, payment);
+      byIdempotencyKey.set(input2.idempotencyKey, ref);
+      return session(payment);
+    },
+    async capture(providerRef) {
+      mutatingCalls.push("capture");
+      const payment = expect(providerRef);
+      payment.state = "captured";
+      return session(payment);
+    },
+    async retrieve(providerRef) {
+      if (defects.retrieveCaptures) {
+        mutatingCalls.push("capture");
+        expect(providerRef).state = "captured";
+      }
+      const payment = expect(providerRef);
+      if (defects.guessesPendingAsFailed && payment.state === "created") {
+        return {
+          ...session(payment),
+          state: "failed"
+        };
+      }
+      return session(payment);
+    },
+    async refund(input2) {
+      mutatingCalls.push("refund");
+      const payment = expect(input2.providerRef);
+      payment.state = input2.money ? "partially_refunded" : "refunded";
+      return {
+        refundRef: `refund_${payment.ref}`,
+        state: payment.state
+      };
+    },
+    async parseWebhook(request) {
+      const valid = request.headers["x-fake-signature"] === "valid";
+      if (!valid && !defects.acceptsBadSignature) {
+        throw new Error("webhook signature verification failed");
+      }
+      const ref = request.headers["x-fake-ref"];
+      return {
+        type: "fake.payment.updated",
+        providerRef: ref,
+        state: ref && payments.has(ref) ? payments.get(ref).state : "unknown",
+        raw: {}
+      };
+    }
+  };
+  function expect(ref) {
+    const payment = payments.get(ref);
+    if (!payment) throw new Error(`unknown payment ${ref}`);
+    return payment;
+  }
+  __name(expect, "expect");
+  function session(payment) {
+    return {
+      providerRef: payment.ref,
+      nextAction: {
+        kind: "redirect",
+        url: `https://fake.test/pay/${payment.ref}`
+      },
+      state: payment.state,
+      money: {
+        amount: payment.amount,
+        currency: payment.currency
+      },
+      raw: {}
+    };
+  }
+  __name(session, "session");
+  return {
+    adapter,
+    mutatingCalls: /* @__PURE__ */ __name(() => [
+      ...mutatingCalls
+    ], "mutatingCalls")
+  };
+}
+__name(createFakeAdapter, "createFakeAdapter");
 
 // src/order.service.ts
 var import_common2 = require("@nestjs/common");
+
+// src/order-persistence.ts
+var ORDER_PERSISTENCE = "PAYMENT_ORDER_PERSISTENCE";
+var DatabaseOrderPersistence = class {
+  static {
+    __name(this, "DatabaseOrderPersistence");
+  }
+  model;
+  constructor(model) {
+    this.model = model;
+  }
+  create(args) {
+    return this.model.create(args);
+  }
+  findUnique(args) {
+    return this.model.findUnique(args);
+  }
+  findMany(args) {
+    return this.model.findMany(args);
+  }
+  update(args) {
+    return this.model.update(args);
+  }
+  updateMany(args) {
+    return this.model.updateMany(args);
+  }
+  count(args) {
+    return this.model.count(args);
+  }
+  async compareAndSet(id, expected, data) {
+    const result = await this.model.updateMany({
+      where: {
+        ...expected,
+        id
+      },
+      data
+    });
+    return result.count === 1;
+  }
+};
+
+// src/order.service.ts
 function _ts_decorate2(decorators, target, key, desc) {
   var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
   if (typeof Reflect === "object" && typeof Reflect.decorate === "function") {
@@ -134,138 +863,198 @@ function _ts_decorate2(decorators, target, key, desc) {
   return c > 3 && r && Object.defineProperty(target, key, r), r;
 }
 __name(_ts_decorate2, "_ts_decorate");
-function _ts_metadata(metadataKey, metadataValue) {
+function _ts_metadata2(metadataKey, metadataValue) {
   if (typeof Reflect === "object" && typeof Reflect.metadata === "function") {
     return Reflect.metadata(metadataKey, metadataValue);
   }
 }
-__name(_ts_metadata, "_ts_metadata");
-var OrderService = class _OrderService {
+__name(_ts_metadata2, "_ts_metadata");
+function _ts_param(paramIndex, decorator) {
+  return function(target, key) {
+    decorator(target, key, paramIndex);
+  };
+}
+__name(_ts_param, "_ts_param");
+var OrderNotFoundError = class extends Error {
+  static {
+    __name(this, "OrderNotFoundError");
+  }
+  orderId;
+  constructor(orderId) {
+    super(`\u8BA2\u5355 "${orderId}" \u4E0D\u5B58\u5728`), this.orderId = orderId;
+    this.name = "OrderNotFoundError";
+  }
+};
+var OrderService = class {
   static {
     __name(this, "OrderService");
   }
-  paymentService;
-  logger = new import_common2.Logger(_OrderService.name);
-  orders = /* @__PURE__ */ new Map();
-  constructor(paymentService) {
-    this.paymentService = paymentService;
+  providers;
+  orders;
+  constructor(providers, orders) {
+    this.providers = providers;
+    this.orders = orders;
+    if (!orders) throw new Error("Order persistence must be configured");
   }
-  /** 创建订单并发起支付 */
   async createOrder(params) {
-    const { orderId, providerId, payment } = params;
-    if (this.orders.has(orderId)) {
-      throw new Error(`\u8BA2\u5355 "${orderId}" \u5DF2\u5B58\u5728`);
+    if (await this.orders.findUnique({
+      where: {
+        id: params.orderId
+      }
+    })) {
+      throw new Error(`\u8BA2\u5355 "${params.orderId}" \u5DF2\u5B58\u5728`);
     }
     const now = /* @__PURE__ */ new Date();
-    const order = {
-      id: orderId,
-      providerId,
-      amount: payment.amount,
-      currency: payment.currency,
-      status: "created",
-      metadata: payment.metadata,
-      createdAt: now,
-      updatedAt: now
-    };
-    this.orders.set(orderId, order);
-    this.logger.log(`\u8BA2\u5355 "${orderId}" \u5DF2\u521B\u5EFA`);
-    try {
-      const intent = await this.paymentService.createPaymentIntent(providerId, payment);
-      order.paymentIntentId = intent.id;
-      order.status = "paying";
-      order.updatedAt = /* @__PURE__ */ new Date();
-      this.logger.log(`\u8BA2\u5355 "${orderId}" \u652F\u4ED8\u5DF2\u53D1\u8D77, intentId=${intent.id}`);
-    } catch (error) {
-      order.status = "failed";
-      order.updatedAt = /* @__PURE__ */ new Date();
-      this.logger.error(`\u8BA2\u5355 "${orderId}" \u652F\u4ED8\u53D1\u8D77\u5931\u8D25`, error);
-      throw error;
+    const order = await this.orders.create({
+      data: {
+        id: params.orderId,
+        providerId: params.providerId,
+        amount: params.payment.money.amount,
+        currency: params.payment.money.currency,
+        metadata: params.payment.metadata,
+        status: "created",
+        createdAt: now,
+        updatedAt: now
+      }
+    });
+    return this.initiatePayment(order, params.payment);
+  }
+  async initiatePayment(order, payment) {
+    const session = await this.providers.get(order.providerId).createPayment(payment);
+    await this.transition(order.id, [
+      "created"
+    ], "paying", {
+      paymentIntentId: session.providerRef
+    });
+    return this.getOrder(order.id);
+  }
+  /**
+  * 扣款。幂等键由调用方给出——同一笔订单重试必须复用同一个键，否则渠道会认为是新支付。
+  * 判定不了的结果保持 confirming，交由只读对账解决，绝不在这里重复扣款。
+  */
+  async confirmOrder(orderId, idempotencyKey) {
+    const order = await this.getOrder(orderId);
+    if (!order.paymentIntentId) throw new Error(`\u8BA2\u5355 "${orderId}" \u7F3A\u5C11 paymentIntentId`);
+    await this.transition(orderId, [
+      "paying"
+    ], "confirming");
+    const session = await this.providers.get(order.providerId).capture(order.paymentIntentId, idempotencyKey);
+    await this.applySettlement(orderId, "confirming", session.state, session.providerRef);
+    return session;
+  }
+  /**
+  * 把渠道观察到的结算状态落到订单上。
+  * 迁移是否允许由 reconcile() 统一裁决，保证所有渠道遵守同一套安全性质
+  * （unknown 不覆盖已知状态、已收款不被迟到的失败回调回退）。
+  */
+  async applySettlement(orderId, from, observed, paymentRef) {
+    const current = from === "paid" ? "captured" : from === "refunded" ? "refunded" : "created";
+    const decision = reconcile(current, observed);
+    if (!decision.changed) return;
+    if (decision.next === "captured") {
+      await this.transition(orderId, [
+        from
+      ], "paid", {
+        paymentId: paymentRef,
+        paidAt: /* @__PURE__ */ new Date()
+      });
+    } else if (decision.next === "failed" || decision.next === "canceled") {
+      await this.transition(orderId, [
+        from
+      ], "failed");
+    } else if (decision.next === "refunded" || decision.next === "partially_refunded") {
+      await this.transition(orderId, [
+        from
+      ], "refunded", {
+        refundedAt: /* @__PURE__ */ new Date()
+      });
     }
-    return {
-      ...order
-    };
   }
-  /** 确认订单支付 */
-  async confirmOrder(orderId) {
-    const order = this.getOrder(orderId);
-    if (order.status !== "paying") {
-      throw new Error(`\u8BA2\u5355 "${orderId}" \u72B6\u6001\u4E3A "${order.status}"\uFF0C\u65E0\u6CD5\u786E\u8BA4\u652F\u4ED8`);
-    }
-    if (!order.paymentIntentId) {
-      throw new Error(`\u8BA2\u5355 "${orderId}" \u7F3A\u5C11 paymentIntentId`);
-    }
-    const result = await this.paymentService.confirmPayment(order.providerId, order.paymentIntentId);
-    if (result.status === "succeeded") {
-      order.status = "paid";
-      order.paymentId = result.id;
-      order.paidAt = result.paidAt ?? /* @__PURE__ */ new Date();
-    } else {
-      order.status = "failed";
-    }
-    order.updatedAt = /* @__PURE__ */ new Date();
-    this.logger.log(`\u8BA2\u5355 "${orderId}" \u652F\u4ED8\u7ED3\u679C: ${result.status}`);
+  async refundOrder(orderId, idempotencyKey, options = {}) {
+    const order = await this.getOrder(orderId);
+    if (!order.paymentId) throw new Error(`\u8BA2\u5355 "${orderId}" \u7F3A\u5C11 paymentId`);
+    await this.transition(orderId, [
+      "paid"
+    ], "refunding");
+    const result = await this.providers.get(order.providerId).refund({
+      providerRef: order.paymentId,
+      money: options.money,
+      reason: options.reason,
+      idempotencyKey
+    });
+    if (result.state === "refunded") {
+      await this.transition(orderId, [
+        "refunding"
+      ], "refunded", {
+        refundedAt: /* @__PURE__ */ new Date()
+      });
+    } else if (result.state === "failed") {
+      await this.transition(orderId, [
+        "refunding"
+      ], "paid");
+    }
     return result;
   }
-  /** 订单退款 */
-  async refundOrder(orderId, amount, reason) {
-    const order = this.getOrder(orderId);
-    if (order.status !== "paid" && order.status !== "refunding") {
-      throw new Error(`\u8BA2\u5355 "${orderId}" \u72B6\u6001\u4E3A "${order.status}"\uFF0C\u65E0\u6CD5\u9000\u6B3E`);
-    }
-    if (!order.paymentId) {
-      throw new Error(`\u8BA2\u5355 "${orderId}" \u7F3A\u5C11 paymentId`);
-    }
-    order.status = "refunding";
-    order.updatedAt = /* @__PURE__ */ new Date();
-    const result = await this.paymentService.refund(order.providerId, order.paymentId, amount, reason);
-    if (result.status === "succeeded") {
-      order.status = "refunded";
-      order.refundedAt = /* @__PURE__ */ new Date();
-    } else if (result.status === "failed") {
-      order.status = "paid";
-    }
-    order.updatedAt = /* @__PURE__ */ new Date();
-    this.logger.log(`\u8BA2\u5355 "${orderId}" \u9000\u6B3E\u7ED3\u679C: ${result.status}`);
-    return result;
+  /**
+  * 重试失败订单。
+  * idempotencyKey 必须与上一次不同：沿用旧键会让渠道原样返回那笔已失败的支付，
+  * 看起来"重试了"其实什么都没发生。
+  */
+  async retryOrder(orderId, idempotencyKey) {
+    const order = await this.getOrder(orderId);
+    await this.transition(orderId, [
+      "failed"
+    ], "created");
+    return this.initiatePayment(order, {
+      reference: order.id,
+      money: {
+        amount: order.amount,
+        currency: order.currency
+      },
+      metadata: order.metadata,
+      idempotencyKey
+    });
   }
-  /** 取消订单 */
-  cancelOrder(orderId) {
-    const order = this.getOrder(orderId);
-    const cancellableStates = [
+  async cancelOrder(orderId) {
+    await this.transition(orderId, [
       "created",
       "paying",
       "failed"
-    ];
-    if (!cancellableStates.includes(order.status)) {
-      throw new Error(`\u8BA2\u5355 "${orderId}" \u72B6\u6001\u4E3A "${order.status}"\uFF0C\u65E0\u6CD5\u53D6\u6D88`);
-    }
-    order.status = "cancelled";
-    order.updatedAt = /* @__PURE__ */ new Date();
-    this.logger.log(`\u8BA2\u5355 "${orderId}" \u5DF2\u53D6\u6D88`);
-    return {
-      ...order
-    };
+    ], "cancelled");
+    return this.getOrder(orderId);
   }
-  /** 查询订单 */
-  getOrder(orderId) {
-    const order = this.orders.get(orderId);
-    if (!order) {
-      throw new Error(`\u8BA2\u5355 "${orderId}" \u4E0D\u5B58\u5728`);
-    }
+  async getOrder(orderId) {
+    const order = await this.orders.findUnique({
+      where: {
+        id: orderId
+      }
+    });
+    if (!order) throw new OrderNotFoundError(orderId);
     return order;
   }
-  /** 列出所有订单 */
   listOrders() {
-    return Array.from(this.orders.values()).map((o) => ({
-      ...o
-    }));
+    return this.orders.findMany();
+  }
+  async transition(id, from, to, data = {}) {
+    const changed = await this.orders.compareAndSet(id, {
+      status: {
+        in: from
+      }
+    }, {
+      ...data,
+      status: to,
+      updatedAt: /* @__PURE__ */ new Date()
+    });
+    if (!changed) throw new Error(`\u8BA2\u5355 "${id}" \u4E0D\u5B58\u5728\u6216\u72B6\u6001\u5DF2\u53D8\u5316\uFF0C\u65E0\u6CD5\u8F6C\u6362\u4E3A ${to}`);
   }
 };
 OrderService = _ts_decorate2([
   (0, import_common2.Injectable)(),
-  _ts_metadata("design:type", Function),
-  _ts_metadata("design:paramtypes", [
-    typeof PaymentService === "undefined" ? Object : PaymentService
+  _ts_param(1, (0, import_common2.Inject)(ORDER_PERSISTENCE)),
+  _ts_metadata2("design:type", Function),
+  _ts_metadata2("design:paramtypes", [
+    typeof PaymentProviderRegistry === "undefined" ? Object : PaymentProviderRegistry,
+    typeof OrderPersistence === "undefined" ? Object : OrderPersistence
   ])
 ], OrderService);
 
@@ -298,21 +1087,22 @@ function _ts_decorate3(decorators, target, key, desc) {
   return c > 3 && r && Object.defineProperty(target, key, r), r;
 }
 __name(_ts_decorate3, "_ts_decorate");
-function _ts_metadata2(metadataKey, metadataValue) {
+function _ts_metadata3(metadataKey, metadataValue) {
   if (typeof Reflect === "object" && typeof Reflect.metadata === "function") {
     return Reflect.metadata(metadataKey, metadataValue);
   }
 }
-__name(_ts_metadata2, "_ts_metadata");
-function _ts_param(paramIndex, decorator) {
+__name(_ts_metadata3, "_ts_metadata");
+function _ts_param2(paramIndex, decorator) {
   return function(target, key) {
     decorator(target, key, paramIndex);
   };
 }
-__name(_ts_param, "_ts_param");
+__name(_ts_param2, "_ts_param");
 var RECOVERY_MAIL_SENDER = "RECOVERY_MAIL_SENDER";
 var RECOVERY_USER_LOOKUP = "RECOVERY_USER_LOOKUP";
 var RECOVERY_URL_GENERATOR = "RECOVERY_URL_GENERATOR";
+var RECOVERY_ATTEMPT_STORE = "RECOVERY_ATTEMPT_STORE";
 var DEFAULT_OPTIONS = {
   maxAttempts: 3,
   retryLinkExpireHours: 48,
@@ -323,18 +1113,16 @@ var PaymentRecoveryService = class _PaymentRecoveryService {
     __name(this, "PaymentRecoveryService");
   }
   orderService;
-  paymentService;
+  attempts;
   mailSender;
   userLookup;
   urlGenerator;
   eventEmitter;
   logger = new import_common3.Logger(_PaymentRecoveryService.name);
   options;
-  /** 内存挽回计数（生产环境建议由业务项目持久化） */
-  recoveryAttempts = /* @__PURE__ */ new Map();
-  constructor(orderService, paymentService, mailSender, userLookup, urlGenerator, eventEmitter) {
+  constructor(orderService, attempts, mailSender, userLookup, urlGenerator, eventEmitter) {
     this.orderService = orderService;
-    this.paymentService = paymentService;
+    this.attempts = attempts;
     this.mailSender = mailSender;
     this.userLookup = userLookup;
     this.urlGenerator = urlGenerator;
@@ -353,8 +1141,9 @@ var PaymentRecoveryService = class _PaymentRecoveryService {
   async handleFailedPayment(orderId, errorCode, errorMessage) {
     let order;
     try {
-      order = this.orderService.getOrder(orderId);
-    } catch {
+      order = await this.orderService.getOrder(orderId);
+    } catch (error) {
+      if (!(error instanceof OrderNotFoundError)) throw error;
       this.logger.warn(`\u8BA2\u5355 ${orderId} \u4E0D\u5B58\u5728\uFF0C\u8DF3\u8FC7\u633D\u56DE`);
       return;
     }
@@ -362,11 +1151,11 @@ var PaymentRecoveryService = class _PaymentRecoveryService {
       this.logger.warn(`\u8BA2\u5355 ${orderId} \u72B6\u6001\u4E3A ${order.status}\uFF0C\u8DF3\u8FC7\u633D\u56DE`);
       return;
     }
-    const attempts = this.recoveryAttempts.get(orderId);
-    if (attempts && attempts.count >= this.options.maxAttempts) {
-      this.logger.log(`\u8BA2\u5355 ${orderId} \u5DF2\u633D\u56DE ${attempts.count} \u6B21\uFF0C\u4E0D\u518D\u53D1\u9001`);
+    if (!this.mailSender) {
+      this.logger.warn("Recovery mail sender is not configured; no attempt was reserved");
       return;
     }
+    if (!this.attempts) throw new Error("Recovery attempt persistence must be configured");
     const userId = order.metadata?.userId;
     let email;
     let userName = "";
@@ -387,32 +1176,20 @@ var PaymentRecoveryService = class _PaymentRecoveryService {
       this.logger.warn(`\u8BA2\u5355 ${orderId} \u65E0\u6CD5\u751F\u6210\u91CD\u8BD5\u94FE\u63A5`);
       return;
     }
-    const errorReason = friendlyErrorReason(errorCode, errorMessage);
-    const attemptNumber = (attempts?.count ?? 0) + 1;
-    if (this.mailSender) {
-      try {
-        await this.mailSender.sendRecoveryEmail({
-          to: email,
-          userName: userName || email.split("@")[0],
-          orderId: order.id,
-          orderNumber: order.metadata?.orderNumber,
-          amount: order.amount,
-          currency: order.currency,
-          errorReason,
-          retryUrl,
-          expireHours: this.options.retryLinkExpireHours
-        });
-        this.logger.log(`\u633D\u56DE\u90AE\u4EF6\u5DF2\u53D1\u9001: ${email}, \u8BA2\u5355 ${orderId} (\u7B2C ${attemptNumber} \u6B21)`);
-      } catch (err) {
-        this.logger.error(`\u633D\u56DE\u90AE\u4EF6\u53D1\u9001\u5931\u8D25: ${err instanceof Error ? err.message : String(err)}`);
-        return;
-      }
-    } else {
-      this.logger.log(`[Recovery:NoMailSender] \u8BA2\u5355 ${orderId} \u9700\u8981\u633D\u56DE, email=${email}, retryUrl=${retryUrl}, reason=${errorReason}`);
-    }
-    this.recoveryAttempts.set(orderId, {
-      count: attemptNumber,
-      lastAt: /* @__PURE__ */ new Date()
+    const reservation = await this.attempts.claim(orderId, this.options.maxAttempts, /* @__PURE__ */ new Date());
+    if (!reservation) return;
+    const attemptNumber = reservation.attemptNumber;
+    await this.mailSender.sendRecoveryEmail({
+      to: email,
+      userName: userName || email.split("@")[0],
+      orderId: order.id,
+      orderNumber: order.metadata?.orderNumber,
+      amount: order.amount,
+      currency: order.currency,
+      errorReason: friendlyErrorReason(errorCode, errorMessage),
+      retryUrl,
+      expireHours: this.options.retryLinkExpireHours,
+      idempotencyKey: `payment-recovery:${orderId}:${attemptNumber}`
     });
     if (this.eventEmitter) {
       const event = {
@@ -426,30 +1203,15 @@ var PaymentRecoveryService = class _PaymentRecoveryService {
     }
   }
   /**
-  * 重试失败订单 — 将 failed → created 并重新发起支付
+  * 重试失败订单 — 将 failed → created 并重新发起支付。
+  * 幂等键由调用方给出且必须与上次不同，否则渠道会原样返回那笔已失败的支付。
   */
-  async retryOrder(orderId) {
-    const order = this.orderService.getOrder(orderId);
-    if (order.status !== "failed") {
-      throw new Error(`\u8BA2\u5355 ${orderId} \u72B6\u6001\u4E3A ${order.status}\uFF0C\u4EC5 failed \u8BA2\u5355\u53EF\u91CD\u8BD5`);
-    }
-    const intent = await this.paymentService.createPaymentIntent(order.providerId, {
-      amount: order.amount,
-      currency: order.currency,
-      metadata: order.metadata
-    });
-    const internalOrder = this.orderService.getOrder(orderId);
-    internalOrder.paymentIntentId = intent.id;
-    internalOrder.status = "paying";
-    internalOrder.updatedAt = /* @__PURE__ */ new Date();
-    this.logger.log(`\u8BA2\u5355 ${orderId} \u91CD\u8BD5\u652F\u4ED8, \u65B0 intentId=${intent.id}`);
-    return {
-      ...internalOrder
-    };
+  retryOrder(orderId, idempotencyKey) {
+    return this.orderService.retryOrder(orderId, idempotencyKey);
   }
-  /** 获取订单挽回记录 */
   getRecoveryAttempts(orderId) {
-    return this.recoveryAttempts.get(orderId);
+    if (!this.attempts) throw new Error("Recovery attempt persistence must be configured");
+    return this.attempts.get(orderId);
   }
   async generateRetryUrl(order) {
     if (this.urlGenerator) {
@@ -460,17 +1222,18 @@ var PaymentRecoveryService = class _PaymentRecoveryService {
 };
 PaymentRecoveryService = _ts_decorate3([
   (0, import_common3.Injectable)(),
-  _ts_param(2, (0, import_common3.Optional)()),
-  _ts_param(2, (0, import_common3.Inject)(RECOVERY_MAIL_SENDER)),
-  _ts_param(3, (0, import_common3.Optional)()),
-  _ts_param(3, (0, import_common3.Inject)(RECOVERY_USER_LOOKUP)),
-  _ts_param(4, (0, import_common3.Optional)()),
-  _ts_param(4, (0, import_common3.Inject)(RECOVERY_URL_GENERATOR)),
-  _ts_param(5, (0, import_common3.Optional)()),
-  _ts_metadata2("design:type", Function),
-  _ts_metadata2("design:paramtypes", [
+  _ts_param2(1, (0, import_common3.Inject)(RECOVERY_ATTEMPT_STORE)),
+  _ts_param2(2, (0, import_common3.Optional)()),
+  _ts_param2(2, (0, import_common3.Inject)(RECOVERY_MAIL_SENDER)),
+  _ts_param2(3, (0, import_common3.Optional)()),
+  _ts_param2(3, (0, import_common3.Inject)(RECOVERY_USER_LOOKUP)),
+  _ts_param2(4, (0, import_common3.Optional)()),
+  _ts_param2(4, (0, import_common3.Inject)(RECOVERY_URL_GENERATOR)),
+  _ts_param2(5, (0, import_common3.Optional)()),
+  _ts_metadata3("design:type", Function),
+  _ts_metadata3("design:paramtypes", [
     typeof OrderService === "undefined" ? Object : OrderService,
-    typeof PaymentService === "undefined" ? Object : PaymentService,
+    Object,
     typeof RecoveryMailSender === "undefined" ? Object : RecoveryMailSender,
     typeof RecoveryUserLookup === "undefined" ? Object : RecoveryUserLookup,
     typeof RecoveryUrlGenerator === "undefined" ? Object : RecoveryUrlGenerator,
@@ -510,33 +1273,62 @@ function _ts_decorate4(decorators, target, key, desc) {
 }
 __name(_ts_decorate4, "_ts_decorate");
 var PAYMENT_PROVIDERS = "PAYMENT_PROVIDERS";
+var PAYMENT_OPTIONS = /* @__PURE__ */ Symbol("PAYMENT_OPTIONS");
+function configuredProviders() {
+  return [
+    {
+      provide: ORDER_PERSISTENCE,
+      inject: [
+        PAYMENT_OPTIONS
+      ],
+      useFactory: /* @__PURE__ */ __name((options) => {
+        if (!options.orderPersistence) throw new Error("Order persistence must be configured");
+        return options.orderPersistence;
+      }, "useFactory")
+    },
+    {
+      provide: RECOVERY_ATTEMPT_STORE,
+      inject: [
+        PAYMENT_OPTIONS
+      ],
+      useFactory: /* @__PURE__ */ __name((options) => options.recoveryAttempts ?? null, "useFactory")
+    },
+    {
+      provide: PaymentProviderRegistry,
+      inject: [
+        PAYMENT_OPTIONS
+      ],
+      useFactory: /* @__PURE__ */ __name((options) => new PaymentProviderRegistry(options.providers ?? []), "useFactory")
+    },
+    OrderService,
+    PaymentRecoveryService,
+    {
+      provide: PAYMENT_PROVIDERS,
+      inject: [
+        PaymentProviderRegistry
+      ],
+      useFactory: /* @__PURE__ */ __name((registry) => registry.list(), "useFactory")
+    }
+  ];
+}
+__name(configuredProviders, "configuredProviders");
 var ZuckerPaymentModule = class _ZuckerPaymentModule {
   static {
     __name(this, "ZuckerPaymentModule");
   }
-  static forRoot(options = {}) {
+  static forRoot(options) {
     return {
       module: _ZuckerPaymentModule,
       global: true,
       providers: [
-        PaymentService,
-        OrderService,
-        PaymentRecoveryService,
         {
-          provide: PAYMENT_PROVIDERS,
-          useFactory: /* @__PURE__ */ __name((paymentService) => {
-            for (const provider of options.providers ?? []) {
-              paymentService.register(provider);
-            }
-            return paymentService.listProviders();
-          }, "useFactory"),
-          inject: [
-            PaymentService
-          ]
-        }
+          provide: PAYMENT_OPTIONS,
+          useValue: options
+        },
+        ...configuredProviders()
       ],
       exports: [
-        PaymentService,
+        PaymentProviderRegistry,
         OrderService,
         PaymentRecoveryService
       ]
@@ -548,27 +1340,15 @@ var ZuckerPaymentModule = class _ZuckerPaymentModule {
       global: true,
       imports: options.imports ?? [],
       providers: [
-        PaymentService,
-        OrderService,
-        PaymentRecoveryService,
         {
-          provide: PAYMENT_PROVIDERS,
-          useFactory: /* @__PURE__ */ __name(async (paymentService, ...args) => {
-            const factoryFn = options.useFactory;
-            const moduleOptions = await factoryFn(...args);
-            for (const provider of moduleOptions.providers ?? []) {
-              paymentService.register(provider);
-            }
-            return paymentService.listProviders();
-          }, "useFactory"),
-          inject: [
-            PaymentService,
-            ...options.inject ?? []
-          ]
-        }
+          provide: PAYMENT_OPTIONS,
+          useFactory: options.useFactory,
+          inject: options.inject ?? []
+        },
+        ...configuredProviders()
       ],
       exports: [
-        PaymentService,
+        PaymentProviderRegistry,
         OrderService,
         PaymentRecoveryService
       ]
@@ -579,16 +1359,258 @@ ZuckerPaymentModule = _ts_decorate4([
   (0, import_common4.Global)(),
   (0, import_common4.Module)({})
 ], ZuckerPaymentModule);
+
+// src/providers/paypal.ts
+var import_node_module2 = require("module");
+var import_meta2 = {};
+var requireSdk2 = (0, import_node_module2.createRequire)(typeof __filename === "string" ? __filename : import_meta2.url);
+function observePayPalOrder(raw) {
+  return {
+    raw,
+    id: raw.id,
+    approveUrl: raw.links?.find((link) => link.rel === "approve")?.href,
+    captureId: raw.purchaseUnits?.[0]?.payments?.captures?.[0]?.id,
+    settlement: raw.status === "COMPLETED" ? "paid" : raw.status === "VOIDED" ? "unpaid" : "unknown"
+  };
+}
+__name(observePayPalOrder, "observePayPalOrder");
+function captureLinkId(resource) {
+  if (!Array.isArray(resource.links)) return void 0;
+  for (const value of resource.links) {
+    const link = asRecord(value);
+    if (link?.rel !== "up" || typeof link.href !== "string") continue;
+    try {
+      const url = new URL(link.href);
+      if (url.protocol !== "https:" || !/^api(?:-m)?(?:\.sandbox)?\.paypal\.com$/.test(url.hostname)) continue;
+      const match = /^\/v2\/payments\/captures\/([A-Za-z0-9_-]+)$/.exec(url.pathname);
+      if (match) return match[1];
+    } catch {
+    }
+  }
+  return void 0;
+}
+__name(captureLinkId, "captureLinkId");
+function asRecord(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value) ? value : void 0;
+}
+__name(asRecord, "asRecord");
+function decodePayPalWebhookEvent(payload) {
+  const raw = asRecord(JSON.parse(payload));
+  if (!raw || typeof raw.event_type !== "string") throw new Error("Invalid PayPal webhook event");
+  const type = raw.event_type;
+  const kind = type === "PAYMENT.CAPTURE.COMPLETED" ? "capture-succeeded" : type === "PAYMENT.CAPTURE.DENIED" || type === "PAYMENT.CAPTURE.DECLINED" ? "capture-failed" : "unknown";
+  if (kind === "unknown") return {
+    raw,
+    type,
+    kind
+  };
+  const resource = asRecord(raw.resource);
+  if (!resource || typeof resource.id !== "string" || !resource.id) {
+    throw new Error("PayPal capture event is missing its resource ID");
+  }
+  const reason = asRecord(resource.status_details)?.reason;
+  return {
+    raw,
+    type,
+    kind,
+    capture: {
+      raw: resource,
+      id: resource.id,
+      failureReason: typeof reason === "string" ? reason : void 0
+    }
+  };
+}
+__name(decodePayPalWebhookEvent, "decodePayPalWebhookEvent");
+function decodePayPalMoneyReturnedEvent(payload) {
+  const raw = asRecord(JSON.parse(payload));
+  if (!raw || typeof raw.event_type !== "string") throw new Error("Invalid PayPal webhook event");
+  const type = raw.event_type;
+  if (type === "PAYMENT.CAPTURE.REFUNDED" || type === "PAYMENT.CAPTURE.REVERSED") {
+    const resource = asRecord(raw.resource);
+    const amount = asRecord(resource?.amount);
+    const related = asRecord(asRecord(resource?.supplementary_data)?.related_ids);
+    const reversal = type === "PAYMENT.CAPTURE.REVERSED";
+    if (!resource || typeof resource.id !== "string" || !resource.id || typeof amount?.value !== "string" || !/^\d+(?:\.\d{1,2})?$/.test(amount.value) || typeof amount.currency_code !== "string" || !/^[A-Z]{3}$/.test(amount.currency_code)) {
+      throw new Error("Invalid PayPal money-returned event");
+    }
+    const status = reversal ? "COMPLETED" : resource.status;
+    if (status !== "PENDING" && status !== "COMPLETED" && status !== "FAILED" && status !== "CANCELLED") {
+      throw new Error("Unknown PayPal refund status");
+    }
+    const captureId = reversal ? resource.id : typeof related?.capture_id === "string" ? related.capture_id : captureLinkId(resource);
+    const orderId = typeof related?.order_id === "string" ? related.order_id : void 0;
+    if (!captureId && !orderId) throw new Error("PayPal refund event has no capture or order identity");
+    return {
+      raw,
+      type,
+      kind: reversal ? "capture-reversed" : "capture-refunded",
+      returned: {
+        id: reversal ? `reversal:${resource.id}` : resource.id,
+        captureId,
+        orderId,
+        amount: amount.value,
+        currency: amount.currency_code,
+        status
+      }
+    };
+  }
+  return null;
+}
+__name(decodePayPalMoneyReturnedEvent, "decodePayPalMoneyReturnedEvent");
+var PayPalPaymentTransport = class {
+  static {
+    __name(this, "PayPalPaymentTransport");
+  }
+  options;
+  orders;
+  baseUrl;
+  fetcher;
+  constructor(options) {
+    this.options = options;
+    const { Client, Environment, LogLevel, OrdersController } = requireSdk2("@paypal/paypal-server-sdk");
+    const client = new Client({
+      clientCredentialsAuthCredentials: {
+        oAuthClientId: options.clientId,
+        oAuthClientSecret: options.clientSecret
+      },
+      timeout: 0,
+      environment: options.mode === "live" ? Environment.Production : Environment.Sandbox,
+      logging: {
+        logLevel: LogLevel.Info,
+        logRequest: {
+          logBody: false
+        },
+        logResponse: {
+          logHeaders: false
+        }
+      }
+    });
+    this.orders = new OrdersController(client);
+    this.baseUrl = options.mode === "live" ? "https://api.paypal.com" : "https://api.sandbox.paypal.com";
+    this.fetcher = options.fetcher ?? fetch;
+  }
+  async createOrder(input2) {
+    const { result } = await this.orders.createOrder(input2);
+    return observePayPalOrder(result);
+  }
+  /** An explicit capture command; never invoked by getOrder or status observation. */
+  async captureOrder(input2) {
+    const { result } = await this.orders.captureOrder(input2);
+    return observePayPalOrder(result);
+  }
+  async getOrder(input2) {
+    const { result } = await this.orders.getOrder(input2);
+    return observePayPalOrder(result);
+  }
+  async getAccessToken() {
+    const response = await this.fetcher(`${this.baseUrl}/v1/oauth2/token`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/x-www-form-urlencoded",
+        Authorization: `Basic ${Buffer.from(`${this.options.clientId}:${this.options.clientSecret}`).toString("base64")}`
+      },
+      body: "grant_type=client_credentials"
+    });
+    const data = await response.json();
+    if (!response.ok || typeof data.access_token !== "string" || !data.access_token) {
+      throw new Error("Unable to obtain PayPal access token");
+    }
+    return data.access_token;
+  }
+  async verifyWebhookSignature(payload, headers, webhookId) {
+    const transmissionId = headers["paypal-transmission-id"];
+    const transmissionTime = headers["paypal-transmission-time"];
+    const certUrl = headers["paypal-cert-url"];
+    const authAlgo = headers["paypal-auth-algo"];
+    const transmissionSig = headers["paypal-transmission-sig"];
+    if (!transmissionId || !transmissionTime || !certUrl || !authAlgo || !transmissionSig) {
+      this.options.logger?.warn("PayPal webhook is missing required signature headers");
+      return false;
+    }
+    try {
+      const accessToken = await this.getAccessToken();
+      const response = await this.fetcher(`${this.baseUrl}/v1/notifications/verify-webhook-signature`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: `Bearer ${accessToken}`
+        },
+        body: JSON.stringify({
+          auth_algo: authAlgo,
+          cert_url: certUrl,
+          transmission_id: transmissionId,
+          transmission_sig: transmissionSig,
+          transmission_time: transmissionTime,
+          webhook_id: webhookId,
+          webhook_event: JSON.parse(payload)
+        })
+      });
+      const result = await response.json();
+      return response.ok && result.verification_status === "SUCCESS";
+    } catch (error) {
+      this.options.logger?.error(`PayPal webhook verification failed: ${error instanceof Error ? error.message : String(error)}`);
+      return false;
+    }
+  }
+  async refundCapture(captureId, request, requestId) {
+    const accessToken = await this.getAccessToken();
+    const response = await this.fetcher(`${this.baseUrl}/v2/payments/captures/${encodeURIComponent(captureId)}/refund`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${accessToken}`,
+        ...requestId ? {
+          "PayPal-Request-Id": requestId
+        } : {}
+      },
+      body: JSON.stringify(request)
+    });
+    const result = await response.json();
+    if (!response.ok) throw new Error(`PayPal refund request failed (${response.status})`);
+    return result;
+  }
+};
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  DatabaseOrderPersistence,
+  ORDER_PERSISTENCE,
+  OrderNotFoundError,
   OrderService,
   PAYMENT_PROVIDERS,
+  PAYPAL_SUPPORTED_CURRENCIES,
+  PayPalPaymentTransport,
   PaymentEvents,
+  PaymentProviderRegistry,
   PaymentRecoveryService,
-  PaymentService,
+  RECOVERY_ATTEMPT_STORE,
   RECOVERY_MAIL_SENDER,
   RECOVERY_URL_GENERATOR,
   RECOVERY_USER_LOOKUP,
+  SETTLEMENT_STATES,
   ZuckerPaymentModule,
-  friendlyErrorReason
+  adapterSupportsCurrency,
+  checkPaymentAdapterContract,
+  createFakeAdapter,
+  createPayPalAdapter,
+  createStripeAdapter,
+  createStripeCheckoutSession,
+  createStripeClient,
+  currencyExponent,
+  decodePayPalMoneyReturnedEvent,
+  decodePayPalWebhookEvent,
+  friendlyErrorReason,
+  fromMinorUnits,
+  isMoneyMoved,
+  isTerminal,
+  observePayPalOrder,
+  observePayPalState,
+  observeStripeCheckoutSession,
+  observeStripePaymentIntent,
+  observeStripeState,
+  reconcile,
+  retrieveStripeCheckoutSession,
+  retrieveStripePaymentIntent,
+  stripeResourceId,
+  toMinorUnits,
+  verifyStripeWebhookEvent
 });