@zucker-framework/payment 1.0.0 → 1.0.2

package/README.md

@@ -0,0 +1,35 @@
+# Payment persistence and provider access
+
+`PaymentService` routes external provider calls. `OrderPersistence<T>` owns asynchronous order storage, and `DatabaseOrderPersistence<T>` binds that contract to an existing `ModelOperations<T>` database model. It preserves native Decimal, Date and JSON values, accepts existing include/select/filter arguments and performs `compareAndSet(id, expected, data)` through one conditional `updateMany` statement. The database must enforce a unique order ID. A transaction-bound model stays on that transaction; the persistence class never starts a transaction or switches to another connection.
+
+Applications with existing order schemas use this public persistence contract directly. They retain their status vocabulary, pricing, product line items, fulfillment and event projections. They do not need a second order table or to translate amounts into another storage format. Confirmed external payment status must be validated before invoking a paid transition.
+
+## Configured Framework order workflow
+
+`OrderService` now requires `OrderPersistence<Order>` as its second constructor argument. `ZuckerPaymentModule.forRoot` / `forRootAsync` require `orderPersistence`; there is no implicit Map store. Configure the module once. `getOrder`, `listOrders`, `cancelOrder` and recovery reads are asynchronous.
+
+Provider operations execute outside database transactions. The service persists creation before calling a provider and uses conditional status updates to claim confirmation/refund work. Concurrent callers cannot both claim the same transition. Unknown create/confirm/refund outcomes remain `created` / `confirming` / `refunding` for reconciliation; errors do not authorize automatic repeated payment attempts. A confirmation response of `pending` or `processing` also stays `confirming`, while `refunded` stays terminal. A failed write of a returned provider ID is surfaced instead of returning a successful unsaved order.
+
+The supplied store must persist the `Order` contract's fields. In-memory implementations may be explicitly supplied in isolated tests but do not prove durability or database concurrency. The generic workflow is not an application fulfillment engine and does not guarantee exactly-once external effects; applications retain provider idempotency, reconciliation and any required durable delivery/outbox.
+
+## Recovery attempts
+
+Recovery mail requires `RecoveryAttemptStore`, configured as `recoveryAttempts` or through `RECOVERY_ATTEMPT_STORE`. Its `claim` must atomically persist a unique attempt number under the configured limit before returning. `get` reads persisted attempts. There is no built-in counter, implicit memory fallback or database table assumption; callers supply storage matching their existing schema. A missing sender skips without reserving; a missing attempt store fails explicitly; database failures propagate.
+
+Each reserved mail attempt receives `payment-recovery:<orderId>:<attemptNumber>` as its idempotency key. Failed or unknown sends keep their reservation. The sender must forward the key to its provider; this is an attempt limit, not a promise of exactly-once mail delivery. Recipient selection, cooldown windows, templates and business recovery policy remain in the consumer.
+
+## Migration and verification
+
+This is a breaking source change: configure an order store, await the formerly synchronous methods, provide recovery-attempt persistence when enabling recovery mail, and replace direct mutation of a returned order with persisted operations. `retryOrder` now delegates to the durable order service. `OrderNotFoundError` distinguishes absence from database failure.
+
+Validation on 2026-09-11: all 7 payment unit-test files (38 tests) and the package no-emit typecheck passed, covering durable-order ports, in-flight outcomes, recovery attempts and mocked provider adapters. The consumer PostgreSQL contract and real provider paths are not established by this unit run. Consumers require a new immutable version and application/CI verification before release; existing published versions remain unchanged.
+
+## Hosted provider observations
+
+Stripe access exposes `createStripeCheckoutSession`, `retrieveStripeCheckoutSession` and `retrieveStripePaymentIntent`. Each delegates exactly once with the supplied SDK request parameters and returns both the untouched `raw` response and normalized evidence. The pure `observeStripeCheckoutSession` / `observeStripePaymentIntent` functions also handle verified webhook objects. Expandable payment-intent/subscription/charge IDs are normalized; payment-method type is returned only when the charge is already expanded. Expanding a charge remains an explicit caller request.
+
+`PayPalPaymentTransport.createOrder`, `captureOrder` and `getOrder` preserve the installed SDK request shape and return `raw`, ID, approval URL, first capture ID and settlement evidence. `observePayPalOrder` works on stored responses without a request. `getOrder` never invokes capture; `APPROVED`, `CREATED` and other nonterminal states are `unknown`, `COMPLETED` is `paid`, and `VOIDED` is `unpaid`. Stripe likewise distinguishes paid evidence from expired/canceled objects and leaves pending evidence unknown.
+
+`decodePayPalWebhookEvent` decodes standard capture event/resource fields after the caller has verified the signature. Recognized capture events require a nonempty resource ID, preventing an undefined identity from reaching a consumer's database filter. Unknown event types remain unhandled observations. Decoding does not verify signatures or apply product effects.
+
+These APIs do not interpret product metadata, choose prices/currencies or success URLs, change retries/SDK versions, activate refunds, or write orders/subscriptions. Consumers decide whether an explicit capture result is a business failure and own all reconciliation/fulfillment. The existing optional refund API is unchanged; this migration covers active hosted-payment paths only.

package/dist/index.d.mts

@@ -1,5 +1,9 @@
+import { ModelOperations } from '@zucker-framework/core';
 import { EventEmitter2 } from '@nestjs/event-emitter';
 import { Type, DynamicModule, InjectionToken } from '@nestjs/common';
+import Stripe from 'stripe';
+import * as _paypal_paypal_server_sdk from '@paypal/paypal-server-sdk';
+import { OrdersController } from '@paypal/paypal-server-sdk';
 
 /**
  * 支付网关接口 — 不绑定任何具体支付商。
@@ -113,7 +117,31 @@ declare class PaymentService {
     handleWebhook(providerId: string, payload: unknown, signature: string): Promise<WebhookEvent>;
 }
 
-type OrderStatus = 'created' | 'paying' | 'paid' | 'failed' | 'refunding' | 'refunded' | 'cancelled';
+declare const ORDER_PERSISTENCE = "PAYMENT_ORDER_PERSISTENCE";
+/**
+ * Durable order data access. Implementations preserve native money/date/JSON values.
+ * A transaction-bound model keeps every operation in the caller's transaction.
+ * compareAndSet must execute its predicate and update as one database statement.
+ */
+interface OrderPersistence<T> extends Pick<ModelOperations<T>, 'create' | 'findUnique' | 'findMany' | 'update' | 'updateMany' | 'count'> {
+    compareAndSet(id: string, expected: Record<string, unknown>, data: Record<string, unknown>): Promise<boolean>;
+}
+/** Uses the existing database port; there is no implicit in-memory fallback. */
+declare class DatabaseOrderPersistence<T> implements OrderPersistence<T> {
+    private readonly model;
+    constructor(model: Pick<ModelOperations<T>, 'create' | 'findUnique' | 'findMany' | 'update' | 'updateMany' | 'count'>);
+    create(args: Record<string, unknown>): Promise<T>;
+    findUnique(args: Record<string, unknown>): Promise<T | null>;
+    findMany(args?: Record<string, unknown>): Promise<T[]>;
+    update(args: Record<string, unknown>): Promise<T>;
+    updateMany(args: Record<string, unknown>): Promise<{
+        count: number;
+    }>;
+    count(args?: Record<string, unknown>): Promise<number>;
+    compareAndSet(id: string, expected: Record<string, unknown>, data: Record<string, unknown>): Promise<boolean>;
+}
+
+type OrderStatus = 'created' | 'paying' | 'confirming' | 'paid' | 'failed' | 'refunding' | 'refunded' | 'cancelled';
 interface Order {
     id: string;
     providerId: string;
@@ -133,28 +161,24 @@ interface CreateOrderParams {
     providerId: string;
     payment: CreatePaymentParams;
 }
-/**
- * 订单管理服务 — 创建订单 -> 支付 -> 完成/退款。
- *
- * 提供内存订单存储（生产环境应替换为数据库持久化）。
- */
+declare class OrderNotFoundError extends Error {
+    readonly orderId: string;
+    constructor(orderId: string);
+}
+/** Durable provider workflow. External calls never run inside a database transaction here. */
 declare class OrderService {
     private readonly paymentService;
-    private readonly logger;
     private readonly orders;
-    constructor(paymentService: PaymentService);
-    /** 创建订单并发起支付 */
+    constructor(paymentService: PaymentService, orders: OrderPersistence<Order>);
     createOrder(params: CreateOrderParams): Promise<Order>;
-    /** 确认订单支付 */
+    private initiatePayment;
     confirmOrder(orderId: string): Promise<PaymentResult>;
-    /** 订单退款 */
     refundOrder(orderId: string, amount?: number, reason?: string): Promise<RefundResult>;
-    /** 取消订单 */
-    cancelOrder(orderId: string): Order;
-    /** 查询订单 */
-    getOrder(orderId: string): Order;
-    /** 列出所有订单 */
-    listOrders(): Order[];
+    retryOrder(orderId: string): Promise<Order>;
+    cancelOrder(orderId: string): Promise<Order>;
+    getOrder(orderId: string): Promise<Order>;
+    listOrders(): Promise<Order[]>;
+    private transition;
 }
 
 /** 挽回邮件发送接口 — 由业务项目实现 */
@@ -171,6 +195,8 @@ interface RecoveryEmailParams {
     errorReason: string;
     retryUrl: string;
     expireHours: number;
+    /** Stable key for this persisted send attempt. */
+    idempotencyKey: string;
 }
 /** 用户信息查询接口 — 由业务项目实现 */
 interface RecoveryUserLookup {
@@ -186,6 +212,17 @@ interface RecoveryUrlGenerator {
 declare const RECOVERY_MAIL_SENDER = "RECOVERY_MAIL_SENDER";
 declare const RECOVERY_USER_LOOKUP = "RECOVERY_USER_LOOKUP";
 declare const RECOVERY_URL_GENERATOR = "RECOVERY_URL_GENERATOR";
+declare const RECOVERY_ATTEMPT_STORE = "RECOVERY_ATTEMPT_STORE";
+/** Persisted attempt limits. claim must atomically reserve a unique number below maxAttempts. */
+interface RecoveryAttemptStore {
+    claim(orderId: string, maxAttempts: number, at: Date): Promise<{
+        attemptNumber: number;
+    } | null>;
+    get(orderId: string): Promise<{
+        count: number;
+        lastAt: Date;
+    } | undefined>;
+}
 interface RecoveryOptions {
     /** 最大挽回次数（默认 3） */
     maxAttempts?: number;
@@ -206,16 +243,14 @@ interface RecoveryOptions {
  */
 declare class PaymentRecoveryService {
     private readonly orderService;
-    private readonly paymentService;
+    private readonly attempts;
     private readonly mailSender?;
     private readonly userLookup?;
     private readonly urlGenerator?;
     private readonly eventEmitter?;
     private readonly logger;
     private readonly options;
-    /** 内存挽回计数（生产环境建议由业务项目持久化） */
-    private readonly recoveryAttempts;
-    constructor(orderService: OrderService, paymentService: PaymentService, mailSender?: RecoveryMailSender | undefined, userLookup?: RecoveryUserLookup | undefined, urlGenerator?: RecoveryUrlGenerator | undefined, eventEmitter?: EventEmitter2);
+    constructor(orderService: OrderService, attempts: RecoveryAttemptStore | null, mailSender?: RecoveryMailSender | undefined, userLookup?: RecoveryUserLookup | undefined, urlGenerator?: RecoveryUrlGenerator | undefined, eventEmitter?: EventEmitter2);
     /** 设置挽回选项 */
     configure(options: RecoveryOptions): void;
     /**
@@ -226,11 +261,10 @@ declare class PaymentRecoveryService {
      * 重试失败订单 — 将 failed → created 并重新发起支付
      */
     retryOrder(orderId: string): Promise<Order>;
-    /** 获取订单挽回记录 */
-    getRecoveryAttempts(orderId: string): {
+    getRecoveryAttempts(orderId: string): Promise<{
         count: number;
         lastAt: Date;
-    } | undefined;
+    } | undefined>;
     private generateRetryUrl;
 }
 /** Stripe 错误码 → 用户友好中文描述 */
@@ -269,6 +303,9 @@ interface PaymentRecoverySentEvent {
 declare const PAYMENT_PROVIDERS = "PAYMENT_PROVIDERS";
 interface PaymentModuleOptions {
     providers?: PaymentProvider[];
+    orderPersistence: OrderPersistence<Order>;
+    /** Required when using payment recovery mail; no process-memory default. */
+    recoveryAttempts?: RecoveryAttemptStore;
 }
 interface PaymentModuleAsyncOptions {
     imports?: Array<Type | DynamicModule>;
@@ -276,8 +313,122 @@ interface PaymentModuleAsyncOptions {
     inject?: InjectionToken[];
 }
 declare class ZuckerPaymentModule {
-    static forRoot(options?: PaymentModuleOptions): DynamicModule;
+    static forRoot(options: PaymentModuleOptions): DynamicModule;
     static forRootAsync(options: PaymentModuleAsyncOptions): DynamicModule;
 }
 
-export { type CreateOrderParams, type CreatePaymentParams, type Order, type OrderFailedEvent, OrderService, type OrderStatus, PAYMENT_PROVIDERS, type PaymentEventType, PaymentEvents, type PaymentIntent, type PaymentModuleAsyncOptions, type PaymentModuleOptions, type PaymentProvider, type PaymentRecoverySentEvent, PaymentRecoveryService, type PaymentResult, PaymentService, type PaymentStatus, RECOVERY_MAIL_SENDER, RECOVERY_URL_GENERATOR, RECOVERY_USER_LOOKUP, type RecoveryEmailParams, type RecoveryMailSender, type RecoveryOptions, type RecoveryUrlGenerator, type RecoveryUserLookup, type RefundResult, type Subscription, type SubscriptionPlan, type SubscriptionProvider, type WebhookEvent, ZuckerPaymentModule, friendlyErrorReason };
+/** Read-only provider evidence; unknown must never be treated as an instruction to charge. */
+type PaymentSettlementState = 'paid' | 'unpaid' | 'unknown';
+
+/** Construct the installed Stripe peer with the consumer's explicit API/transport configuration. */
+declare function createStripeClient(secretKey: string, options: Stripe.StripeConfig): Stripe;
+/** Verify raw webhook bytes using the installed SDK's timestamp/signature checks. */
+declare function verifyStripeWebhookEvent(client: Pick<Stripe, 'webhooks'>, payload: Buffer | string, signature: string, webhookSecret: string): Stripe.Event;
+/** Stripe expandable references can be an ID, an expanded object, or absent. */
+declare function stripeResourceId(value: string | {
+    id: string;
+} | null | undefined): string | undefined;
+interface StripeCheckoutObservation {
+    raw: Stripe.Checkout.Session;
+    id: string;
+    url?: string;
+    clientReferenceId?: string;
+    paymentIntentId?: string;
+    subscriptionId?: string;
+    settlement: PaymentSettlementState;
+}
+declare function observeStripeCheckoutSession(raw: Stripe.Checkout.Session): StripeCheckoutObservation;
+declare function createStripeCheckoutSession(client: Pick<Stripe, 'checkout'>, params: Stripe.Checkout.SessionCreateParams): Promise<StripeCheckoutObservation>;
+declare function retrieveStripeCheckoutSession(client: Pick<Stripe, 'checkout'>, id: string): Promise<StripeCheckoutObservation>;
+interface StripePaymentIntentObservation {
+    raw: Stripe.PaymentIntent;
+    id: string;
+    chargeId: string | null;
+    paymentMethodType?: string;
+    failureCode?: string;
+    failureMessage?: string;
+    settlement: PaymentSettlementState;
+}
+declare function observeStripePaymentIntent(raw: Stripe.PaymentIntent): StripePaymentIntentObservation;
+declare function retrieveStripePaymentIntent(client: Pick<Stripe, 'paymentIntents'>, id: string, params?: Stripe.PaymentIntentRetrieveParams): Promise<StripePaymentIntentObservation>;
+
+interface PayPalPaymentTransportOptions {
+    clientId: string;
+    clientSecret: string;
+    mode: 'live' | 'sandbox';
+    fetcher?: typeof fetch;
+    logger?: {
+        warn: (message: string) => void;
+        error: (message: string) => void;
+    };
+}
+interface PayPalCaptureRefundRequest {
+    amount: {
+        value: string;
+        currency_code: string;
+    };
+    note_to_payer?: string;
+}
+interface PayPalCaptureRefundResponse {
+    id?: string;
+    status?: string;
+    message?: string;
+}
+interface PayPalOrderRepresentation {
+    id?: string;
+    status?: string;
+    links?: Array<{
+        rel?: string;
+        href?: string;
+    }>;
+    purchaseUnits?: Array<{
+        payments?: {
+            captures?: Array<{
+                id?: string;
+            }>;
+        };
+    }>;
+}
+interface PayPalOrderObservation<T extends PayPalOrderRepresentation = PayPalOrderRepresentation> {
+    raw: T;
+    id?: string;
+    approveUrl?: string;
+    captureId?: string;
+    settlement: PaymentSettlementState;
+}
+/** APPROVED means approval only, never evidence of a captured payment. */
+declare function observePayPalOrder<T extends PayPalOrderRepresentation>(raw: T): PayPalOrderObservation<T>;
+interface PayPalCaptureObservation {
+    raw: Record<string, unknown>;
+    id: string;
+    failureReason?: string;
+}
+type PayPalWebhookObservation = {
+    raw: Record<string, unknown>;
+    type: string;
+    kind: 'capture-succeeded' | 'capture-failed';
+    capture: PayPalCaptureObservation;
+} | {
+    raw: Record<string, unknown>;
+    type: string;
+    kind: 'unknown';
+};
+/** Decode only after signature verification; this performs no authentication or network call. */
+declare function decodePayPalWebhookEvent(payload: string): PayPalWebhookObservation;
+/** SDK order transport plus the OAuth-backed REST endpoints absent from the current SDK integration. */
+declare class PayPalPaymentTransport {
+    private readonly options;
+    readonly orders: OrdersController;
+    private readonly baseUrl;
+    private readonly fetcher;
+    constructor(options: PayPalPaymentTransportOptions);
+    createOrder(input: Parameters<OrdersController['createOrder']>[0]): Promise<PayPalOrderObservation<_paypal_paypal_server_sdk.Order>>;
+    /** An explicit capture command; never invoked by getOrder or status observation. */
+    captureOrder(input: Parameters<OrdersController['captureOrder']>[0]): Promise<PayPalOrderObservation<_paypal_paypal_server_sdk.Order>>;
+    getOrder(input: Parameters<OrdersController['getOrder']>[0]): Promise<PayPalOrderObservation<_paypal_paypal_server_sdk.Order>>;
+    private getAccessToken;
+    verifyWebhookSignature(payload: string, headers: Record<string, string>, webhookId: string): Promise<boolean>;
+    refundCapture(captureId: string, request: PayPalCaptureRefundRequest): Promise<PayPalCaptureRefundResponse>;
+}
+
+export { type CreateOrderParams, type CreatePaymentParams, DatabaseOrderPersistence, ORDER_PERSISTENCE, type Order, type OrderFailedEvent, OrderNotFoundError, type OrderPersistence, OrderService, type OrderStatus, PAYMENT_PROVIDERS, type PayPalCaptureObservation, type PayPalCaptureRefundRequest, type PayPalCaptureRefundResponse, type PayPalOrderObservation, type PayPalOrderRepresentation, PayPalPaymentTransport, type PayPalPaymentTransportOptions, type PayPalWebhookObservation, type PaymentEventType, PaymentEvents, type PaymentIntent, type PaymentModuleAsyncOptions, type PaymentModuleOptions, type PaymentProvider, type PaymentRecoverySentEvent, PaymentRecoveryService, type PaymentResult, PaymentService, type PaymentSettlementState, type PaymentStatus, RECOVERY_ATTEMPT_STORE, RECOVERY_MAIL_SENDER, RECOVERY_URL_GENERATOR, RECOVERY_USER_LOOKUP, type RecoveryAttemptStore, type RecoveryEmailParams, type RecoveryMailSender, type RecoveryOptions, type RecoveryUrlGenerator, type RecoveryUserLookup, type RefundResult, type StripeCheckoutObservation, type StripePaymentIntentObservation, type Subscription, type SubscriptionPlan, type SubscriptionProvider, type WebhookEvent, ZuckerPaymentModule, createStripeCheckoutSession, createStripeClient, decodePayPalWebhookEvent, friendlyErrorReason, observePayPalOrder, observeStripeCheckoutSession, observeStripePaymentIntent, retrieveStripeCheckoutSession, retrieveStripePaymentIntent, stripeResourceId, verifyStripeWebhookEvent };

package/dist/index.d.ts

@@ -1,5 +1,9 @@
+import { ModelOperations } from '@zucker-framework/core';
 import { EventEmitter2 } from '@nestjs/event-emitter';
 import { Type, DynamicModule, InjectionToken } from '@nestjs/common';
+import Stripe from 'stripe';
+import * as _paypal_paypal_server_sdk from '@paypal/paypal-server-sdk';
+import { OrdersController } from '@paypal/paypal-server-sdk';
 
 /**
  * 支付网关接口 — 不绑定任何具体支付商。
@@ -113,7 +117,31 @@ declare class PaymentService {
     handleWebhook(providerId: string, payload: unknown, signature: string): Promise<WebhookEvent>;
 }
 
-type OrderStatus = 'created' | 'paying' | 'paid' | 'failed' | 'refunding' | 'refunded' | 'cancelled';
+declare const ORDER_PERSISTENCE = "PAYMENT_ORDER_PERSISTENCE";
+/**
+ * Durable order data access. Implementations preserve native money/date/JSON values.
+ * A transaction-bound model keeps every operation in the caller's transaction.
+ * compareAndSet must execute its predicate and update as one database statement.
+ */
+interface OrderPersistence<T> extends Pick<ModelOperations<T>, 'create' | 'findUnique' | 'findMany' | 'update' | 'updateMany' | 'count'> {
+    compareAndSet(id: string, expected: Record<string, unknown>, data: Record<string, unknown>): Promise<boolean>;
+}
+/** Uses the existing database port; there is no implicit in-memory fallback. */
+declare class DatabaseOrderPersistence<T> implements OrderPersistence<T> {
+    private readonly model;
+    constructor(model: Pick<ModelOperations<T>, 'create' | 'findUnique' | 'findMany' | 'update' | 'updateMany' | 'count'>);
+    create(args: Record<string, unknown>): Promise<T>;
+    findUnique(args: Record<string, unknown>): Promise<T | null>;
+    findMany(args?: Record<string, unknown>): Promise<T[]>;
+    update(args: Record<string, unknown>): Promise<T>;
+    updateMany(args: Record<string, unknown>): Promise<{
+        count: number;
+    }>;
+    count(args?: Record<string, unknown>): Promise<number>;
+    compareAndSet(id: string, expected: Record<string, unknown>, data: Record<string, unknown>): Promise<boolean>;
+}
+
+type OrderStatus = 'created' | 'paying' | 'confirming' | 'paid' | 'failed' | 'refunding' | 'refunded' | 'cancelled';
 interface Order {
     id: string;
     providerId: string;
@@ -133,28 +161,24 @@ interface CreateOrderParams {
     providerId: string;
     payment: CreatePaymentParams;
 }
-/**
- * 订单管理服务 — 创建订单 -> 支付 -> 完成/退款。
- *
- * 提供内存订单存储（生产环境应替换为数据库持久化）。
- */
+declare class OrderNotFoundError extends Error {
+    readonly orderId: string;
+    constructor(orderId: string);
+}
+/** Durable provider workflow. External calls never run inside a database transaction here. */
 declare class OrderService {
     private readonly paymentService;
-    private readonly logger;
     private readonly orders;
-    constructor(paymentService: PaymentService);
-    /** 创建订单并发起支付 */
+    constructor(paymentService: PaymentService, orders: OrderPersistence<Order>);
     createOrder(params: CreateOrderParams): Promise<Order>;
-    /** 确认订单支付 */
+    private initiatePayment;
     confirmOrder(orderId: string): Promise<PaymentResult>;
-    /** 订单退款 */
     refundOrder(orderId: string, amount?: number, reason?: string): Promise<RefundResult>;
-    /** 取消订单 */
-    cancelOrder(orderId: string): Order;
-    /** 查询订单 */
-    getOrder(orderId: string): Order;
-    /** 列出所有订单 */
-    listOrders(): Order[];
+    retryOrder(orderId: string): Promise<Order>;
+    cancelOrder(orderId: string): Promise<Order>;
+    getOrder(orderId: string): Promise<Order>;
+    listOrders(): Promise<Order[]>;
+    private transition;
 }
 
 /** 挽回邮件发送接口 — 由业务项目实现 */
@@ -171,6 +195,8 @@ interface RecoveryEmailParams {
     errorReason: string;
     retryUrl: string;
     expireHours: number;
+    /** Stable key for this persisted send attempt. */
+    idempotencyKey: string;
 }
 /** 用户信息查询接口 — 由业务项目实现 */
 interface RecoveryUserLookup {
@@ -186,6 +212,17 @@ interface RecoveryUrlGenerator {
 declare const RECOVERY_MAIL_SENDER = "RECOVERY_MAIL_SENDER";
 declare const RECOVERY_USER_LOOKUP = "RECOVERY_USER_LOOKUP";
 declare const RECOVERY_URL_GENERATOR = "RECOVERY_URL_GENERATOR";
+declare const RECOVERY_ATTEMPT_STORE = "RECOVERY_ATTEMPT_STORE";
+/** Persisted attempt limits. claim must atomically reserve a unique number below maxAttempts. */
+interface RecoveryAttemptStore {
+    claim(orderId: string, maxAttempts: number, at: Date): Promise<{
+        attemptNumber: number;
+    } | null>;
+    get(orderId: string): Promise<{
+        count: number;
+        lastAt: Date;
+    } | undefined>;
+}
 interface RecoveryOptions {
     /** 最大挽回次数（默认 3） */
     maxAttempts?: number;
@@ -206,16 +243,14 @@ interface RecoveryOptions {
  */
 declare class PaymentRecoveryService {
     private readonly orderService;
-    private readonly paymentService;
+    private readonly attempts;
     private readonly mailSender?;
     private readonly userLookup?;
     private readonly urlGenerator?;
     private readonly eventEmitter?;
     private readonly logger;
     private readonly options;
-    /** 内存挽回计数（生产环境建议由业务项目持久化） */
-    private readonly recoveryAttempts;
-    constructor(orderService: OrderService, paymentService: PaymentService, mailSender?: RecoveryMailSender | undefined, userLookup?: RecoveryUserLookup | undefined, urlGenerator?: RecoveryUrlGenerator | undefined, eventEmitter?: EventEmitter2);
+    constructor(orderService: OrderService, attempts: RecoveryAttemptStore | null, mailSender?: RecoveryMailSender | undefined, userLookup?: RecoveryUserLookup | undefined, urlGenerator?: RecoveryUrlGenerator | undefined, eventEmitter?: EventEmitter2);
     /** 设置挽回选项 */
     configure(options: RecoveryOptions): void;
     /**
@@ -226,11 +261,10 @@ declare class PaymentRecoveryService {
      * 重试失败订单 — 将 failed → created 并重新发起支付
      */
     retryOrder(orderId: string): Promise<Order>;
-    /** 获取订单挽回记录 */
-    getRecoveryAttempts(orderId: string): {
+    getRecoveryAttempts(orderId: string): Promise<{
         count: number;
         lastAt: Date;
-    } | undefined;
+    } | undefined>;
     private generateRetryUrl;
 }
 /** Stripe 错误码 → 用户友好中文描述 */
@@ -269,6 +303,9 @@ interface PaymentRecoverySentEvent {
 declare const PAYMENT_PROVIDERS = "PAYMENT_PROVIDERS";
 interface PaymentModuleOptions {
     providers?: PaymentProvider[];
+    orderPersistence: OrderPersistence<Order>;
+    /** Required when using payment recovery mail; no process-memory default. */
+    recoveryAttempts?: RecoveryAttemptStore;
 }
 interface PaymentModuleAsyncOptions {
     imports?: Array<Type | DynamicModule>;
@@ -276,8 +313,122 @@ interface PaymentModuleAsyncOptions {
     inject?: InjectionToken[];
 }
 declare class ZuckerPaymentModule {
-    static forRoot(options?: PaymentModuleOptions): DynamicModule;
+    static forRoot(options: PaymentModuleOptions): DynamicModule;
     static forRootAsync(options: PaymentModuleAsyncOptions): DynamicModule;
 }
 
-export { type CreateOrderParams, type CreatePaymentParams, type Order, type OrderFailedEvent, OrderService, type OrderStatus, PAYMENT_PROVIDERS, type PaymentEventType, PaymentEvents, type PaymentIntent, type PaymentModuleAsyncOptions, type PaymentModuleOptions, type PaymentProvider, type PaymentRecoverySentEvent, PaymentRecoveryService, type PaymentResult, PaymentService, type PaymentStatus, RECOVERY_MAIL_SENDER, RECOVERY_URL_GENERATOR, RECOVERY_USER_LOOKUP, type RecoveryEmailParams, type RecoveryMailSender, type RecoveryOptions, type RecoveryUrlGenerator, type RecoveryUserLookup, type RefundResult, type Subscription, type SubscriptionPlan, type SubscriptionProvider, type WebhookEvent, ZuckerPaymentModule, friendlyErrorReason };
+/** Read-only provider evidence; unknown must never be treated as an instruction to charge. */
+type PaymentSettlementState = 'paid' | 'unpaid' | 'unknown';
+
+/** Construct the installed Stripe peer with the consumer's explicit API/transport configuration. */
+declare function createStripeClient(secretKey: string, options: Stripe.StripeConfig): Stripe;
+/** Verify raw webhook bytes using the installed SDK's timestamp/signature checks. */
+declare function verifyStripeWebhookEvent(client: Pick<Stripe, 'webhooks'>, payload: Buffer | string, signature: string, webhookSecret: string): Stripe.Event;
+/** Stripe expandable references can be an ID, an expanded object, or absent. */
+declare function stripeResourceId(value: string | {
+    id: string;
+} | null | undefined): string | undefined;
+interface StripeCheckoutObservation {
+    raw: Stripe.Checkout.Session;
+    id: string;
+    url?: string;
+    clientReferenceId?: string;
+    paymentIntentId?: string;
+    subscriptionId?: string;
+    settlement: PaymentSettlementState;
+}
+declare function observeStripeCheckoutSession(raw: Stripe.Checkout.Session): StripeCheckoutObservation;
+declare function createStripeCheckoutSession(client: Pick<Stripe, 'checkout'>, params: Stripe.Checkout.SessionCreateParams): Promise<StripeCheckoutObservation>;
+declare function retrieveStripeCheckoutSession(client: Pick<Stripe, 'checkout'>, id: string): Promise<StripeCheckoutObservation>;
+interface StripePaymentIntentObservation {
+    raw: Stripe.PaymentIntent;
+    id: string;
+    chargeId: string | null;
+    paymentMethodType?: string;
+    failureCode?: string;
+    failureMessage?: string;
+    settlement: PaymentSettlementState;
+}
+declare function observeStripePaymentIntent(raw: Stripe.PaymentIntent): StripePaymentIntentObservation;
+declare function retrieveStripePaymentIntent(client: Pick<Stripe, 'paymentIntents'>, id: string, params?: Stripe.PaymentIntentRetrieveParams): Promise<StripePaymentIntentObservation>;
+
+interface PayPalPaymentTransportOptions {
+    clientId: string;
+    clientSecret: string;
+    mode: 'live' | 'sandbox';
+    fetcher?: typeof fetch;
+    logger?: {
+        warn: (message: string) => void;
+        error: (message: string) => void;
+    };
+}
+interface PayPalCaptureRefundRequest {
+    amount: {
+        value: string;
+        currency_code: string;
+    };
+    note_to_payer?: string;
+}
+interface PayPalCaptureRefundResponse {
+    id?: string;
+    status?: string;
+    message?: string;
+}
+interface PayPalOrderRepresentation {
+    id?: string;
+    status?: string;
+    links?: Array<{
+        rel?: string;
+        href?: string;
+    }>;
+    purchaseUnits?: Array<{
+        payments?: {
+            captures?: Array<{
+                id?: string;
+            }>;
+        };
+    }>;
+}
+interface PayPalOrderObservation<T extends PayPalOrderRepresentation = PayPalOrderRepresentation> {
+    raw: T;
+    id?: string;
+    approveUrl?: string;
+    captureId?: string;
+    settlement: PaymentSettlementState;
+}
+/** APPROVED means approval only, never evidence of a captured payment. */
+declare function observePayPalOrder<T extends PayPalOrderRepresentation>(raw: T): PayPalOrderObservation<T>;
+interface PayPalCaptureObservation {
+    raw: Record<string, unknown>;
+    id: string;
+    failureReason?: string;
+}
+type PayPalWebhookObservation = {
+    raw: Record<string, unknown>;
+    type: string;
+    kind: 'capture-succeeded' | 'capture-failed';
+    capture: PayPalCaptureObservation;
+} | {
+    raw: Record<string, unknown>;
+    type: string;
+    kind: 'unknown';
+};
+/** Decode only after signature verification; this performs no authentication or network call. */
+declare function decodePayPalWebhookEvent(payload: string): PayPalWebhookObservation;
+/** SDK order transport plus the OAuth-backed REST endpoints absent from the current SDK integration. */
+declare class PayPalPaymentTransport {
+    private readonly options;
+    readonly orders: OrdersController;
+    private readonly baseUrl;
+    private readonly fetcher;
+    constructor(options: PayPalPaymentTransportOptions);
+    createOrder(input: Parameters<OrdersController['createOrder']>[0]): Promise<PayPalOrderObservation<_paypal_paypal_server_sdk.Order>>;
+    /** An explicit capture command; never invoked by getOrder or status observation. */
+    captureOrder(input: Parameters<OrdersController['captureOrder']>[0]): Promise<PayPalOrderObservation<_paypal_paypal_server_sdk.Order>>;
+    getOrder(input: Parameters<OrdersController['getOrder']>[0]): Promise<PayPalOrderObservation<_paypal_paypal_server_sdk.Order>>;
+    private getAccessToken;
+    verifyWebhookSignature(payload: string, headers: Record<string, string>, webhookId: string): Promise<boolean>;
+    refundCapture(captureId: string, request: PayPalCaptureRefundRequest): Promise<PayPalCaptureRefundResponse>;
+}
+
+export { type CreateOrderParams, type CreatePaymentParams, DatabaseOrderPersistence, ORDER_PERSISTENCE, type Order, type OrderFailedEvent, OrderNotFoundError, type OrderPersistence, OrderService, type OrderStatus, PAYMENT_PROVIDERS, type PayPalCaptureObservation, type PayPalCaptureRefundRequest, type PayPalCaptureRefundResponse, type PayPalOrderObservation, type PayPalOrderRepresentation, PayPalPaymentTransport, type PayPalPaymentTransportOptions, type PayPalWebhookObservation, type PaymentEventType, PaymentEvents, type PaymentIntent, type PaymentModuleAsyncOptions, type PaymentModuleOptions, type PaymentProvider, type PaymentRecoverySentEvent, PaymentRecoveryService, type PaymentResult, PaymentService, type PaymentSettlementState, type PaymentStatus, RECOVERY_ATTEMPT_STORE, RECOVERY_MAIL_SENDER, RECOVERY_URL_GENERATOR, RECOVERY_USER_LOOKUP, type RecoveryAttemptStore, type RecoveryEmailParams, type RecoveryMailSender, type RecoveryOptions, type RecoveryUrlGenerator, type RecoveryUserLookup, type RefundResult, type StripeCheckoutObservation, type StripePaymentIntentObservation, type Subscription, type SubscriptionPlan, type SubscriptionProvider, type WebhookEvent, ZuckerPaymentModule, createStripeCheckoutSession, createStripeClient, decodePayPalWebhookEvent, friendlyErrorReason, observePayPalOrder, observeStripeCheckoutSession, observeStripePaymentIntent, retrieveStripeCheckoutSession, retrieveStripePaymentIntent, stripeResourceId, verifyStripeWebhookEvent };