@seaverse/payment-sdk 0.8.0 → 0.8.2

package/dist/index.d.ts

@@ -1315,9 +1315,9 @@ interface BindCard {
     user_type?: number;
 }
 /**
- * Generic package interface that supports all package types
+ * Base package interface - common fields for all package types
  */
-interface GenericPackage {
+interface BasePackage {
     /** Unique package ID */
     id: string;
     /** Display name */
@@ -1332,6 +1332,11 @@ interface GenericPackage {
     base_credits?: string;
     /** Bonus credits (optional) */
     bonus_credits?: string;
+}
+/**
+ * Generic package interface that supports all package types
+ */
+interface GenericPackage extends BasePackage {
     /** Bonus percentage (e.g., 20 for +20%) */
     bonus_percentage?: number;
     /** Daily purchase limit (0 = unlimited) */
@@ -1546,6 +1551,93 @@ declare class PaymentModal {
     isModalOpen(): boolean;
 }
 
+/**
+ * RetentionModal - 支付挽留弹框
+ * 当用户尝试取消支付时弹出，提供优惠信息以挽留用户
+ * 参考图片中的深色卡片设计风格
+ */
+interface RetentionModalOptions {
+    /** 语言，默认 'en' */
+    language?: 'en' | 'zh-CN';
+    /** 商品名称 */
+    productName: string;
+    /** 购买数量（积分数等） */
+    purchaseAmount: number;
+    /** 活动赠送（例如：990） */
+    bonusAmount?: number;
+    /** 优惠价格（例如："US$4.99"） */
+    discountPrice: string;
+    /** 确认继续支付回调 */
+    onContinue: () => void;
+    /** 确认取消回调 */
+    onCancel: () => void;
+    /** 弹框关闭回调 */
+    onClose?: () => void;
+}
+/**
+ * 支付挽留弹框类
+ */
+declare class RetentionModal {
+    private overlay;
+    private modal;
+    private options;
+    private isExiting;
+    private scrollY;
+    private boundHandleEscKey;
+    private countdownInterval;
+    private remainingSeconds;
+    constructor(options: RetentionModalOptions);
+    /**
+     * 打开弹框
+     */
+    open(): void;
+    /**
+     * 关闭弹框
+     */
+    close(): void;
+    /**
+     * 创建弹框元素
+     */
+    private createModal;
+    /**
+     * 添加 CSS 动画
+     */
+    private addStyles;
+    /**
+     * 添加事件监听
+     */
+    private attachEventListeners;
+    /**
+     * 处理 ESC 键
+     */
+    private handleEscKey;
+    /**
+     * 启动倒计时
+     */
+    private startCountdown;
+    /**
+     * 停止倒计时
+     */
+    private stopCountdown;
+    /**
+     * 更新倒计时显示
+     */
+    private updateCountdownDisplay;
+    /**
+     * 清理资源
+     */
+    private cleanup;
+    /**
+     * HTML 转义工具函数
+     * 防止 XSS 攻击
+     */
+    private escapeHtml;
+    /**
+     * 检查弹框是否打开
+     */
+    isOpen(): boolean;
+}
+
 /**
  * DropinPaymentModal - Dropin 支付弹框
  * 封装 DropinPaymentComponent 并在弹框中展示
@@ -1556,6 +1648,10 @@ interface DropinPaymentModalOptions extends Omit<DropinPaymentOptions, 'containe
     modalTitle?: string;
     /** 弹框选项 */
     modalOptions?: Omit<PaymentModalOptions, 'title'>;
+    /** 是否启用挽留弹框（默认：true） */
+    enableRetention?: boolean;
+    /** 挽留弹框配置 */
+    retentionOptions?: Partial<RetentionModalOptions>;
 }
 declare class DropinPaymentModal {
     private paymentInstance;
@@ -1566,6 +1662,9 @@ declare class DropinPaymentModal {
     private modal;
     private dropinPayment;
     private containerElement;
+    private retentionModal;
+    private shouldShowRetention;
+    private paymentCompleted;
     constructor(paymentInstance: SeaartPaymentInstance, orderId: string, accountToken: string | undefined, paymentMethod: PaymentMethod, options: DropinPaymentModalOptions);
     /**
      * 打开弹框并渲染支付组件
@@ -1587,6 +1686,10 @@ declare class DropinPaymentModal {
      * 隐藏加载状态
      */
     private hideLoading;
+    /**
+     * 显示挽留弹框
+     */
+    private showRetentionModal;
     /**
      * 检查弹框是否打开
      */
@@ -1667,10 +1770,33 @@ declare class SeaartPaymentSDK {
     destroy(): void;
 }
 
+/**
+ * 积分套餐数据
+ */
+
+interface CreditPackage extends BasePackage {
+    day_limit: number;
+    is_popular?: boolean;
+}
+declare const CREDIT_PACKAGES: CreditPackage[];
+/**
+ * 创作力量类型和对应的积分消耗
+ */
+interface CreativePowerType {
+    icon: string;
+    name: string;
+    name_cn: string;
+    credits_range: string;
+    description: string;
+    description_cn: string;
+}
+declare const CREATIVE_POWER_TYPES: CreativePowerType[];
+
 /**
  * 共享类型定义
  * Shared types for CreditPackageModal and GenericPackageModal
  */
+
 /** 环境类型 */
 type Environment = 'development' | 'production';
 /** 环境配置接口 */
@@ -1713,237 +1839,229 @@ interface PaymentSDKConfig {
     /** 自定义 CSS URL（覆盖环境配置） */
     cssUrl?: string;
 }
-
 /**
- * CreditPackageModal - 积分套餐选择弹框
- * 展示不同的积分套餐供用户选择
+ * Base package modal options - common configuration for all package modals
  */
-
-interface CreditPackageModalOptions {
-    /** SDK 配置（必填 - 用于自动初始化支付 SDK） */
+interface BasePackageModalOptions<TPackage extends BasePackage> {
+    /** SDK configuration (required for automatic SDK initialization) */
     sdkConfig: PaymentSDKConfig;
-    /** 语言（默认 'en'） */
+    /** Language (default 'en') */
     language?: 'en' | 'zh-CN';
-    /** 弹框标题 */
-    title?: string;
-    /** 弹框标题（中文） */
-    title_cn?: string;
-    /** 副标题 */
-    subtitle?: string;
-    /** 副标题（中文） */
-    subtitle_cn?: string;
     /**
-     * 支付成功回调 - 弹框内部完成支付后通知使用方
-     * @param orderId 订单ID
-     * @param transactionId 交易ID
+     * Payment success callback - notifies when payment is completed
+     * @param orderId Order ID
+     * @param transactionId Transaction ID
+     * @param pkg Purchased package
      */
-    onPaymentSuccess?: (orderId: string, transactionId: string) => void;
+    onPaymentSuccess?: (orderId: string, transactionId: string, pkg: TPackage) => void;
     /**
-     * 支付失败回调
-     * @param error 错误信息
+     * Payment failed callback
+     * @param error Error information
+     * @param pkg Package that failed to purchase
      */
-    onPaymentFailed?: (error: Error) => void;
-    /** 弹框关闭回调 */
+    onPaymentFailed?: (error: Error, pkg: TPackage) => void;
+    /** Modal close callback */
     onClose?: () => void;
     paymentMethod?: PaymentMethod;
     accountToken?: string;
 }
-declare class CreditPackageModal {
-    private modal;
-    private options;
-    private language;
-    private resizeHandler;
-    private isInitializingSDK;
-    private sdkInitialized;
-    private readonly SPACING;
-    private readonly COLORS;
-    constructor(options: CreditPackageModalOptions);
+
+/**
+ * BasePackageModal - Abstract base class for package modals
+ * Provides shared logic for SDK initialization, payment flow, and event handling
+ */
+
+/**
+ * Abstract base class for package modals
+ * Provides common functionality for SDK initialization, payment flow, and event handling
+ */
+declare abstract class BasePackageModal<TPackage extends BasePackage, TOptions extends BasePackageModalOptions<TPackage>> {
+    protected modal: PaymentModal;
+    protected options: TOptions;
+    protected language: 'en' | 'zh-CN';
+    protected resizeHandler: (() => void) | null;
+    protected isInitializingSDK: boolean;
+    protected sdkInitialized: boolean;
+    protected paymentMethod?: PaymentMethod;
+    protected accountToken?: string;
+    constructor(options: TOptions);
     /**
-     * 打开弹框
+     * Create and configure the PaymentModal instance
+     * Subclasses define modal title, width, close behavior
      */
-    open(): Promise<void>;
+    protected abstract createModal(): PaymentModal;
     /**
-     * 等待 SDK 初始化完成（支持超时和重试）
-     * @param timeout 超时时间（毫秒），默认 30 秒
-     * @param maxRetries 最大重试次数，默认 1 次
-     * @returns 是否初始化成功
+     * Render the modal content (UI-specific logic)
+     * Subclasses implement their own UI rendering
      */
-    private waitForSDKInitialization;
+    protected abstract renderContent(): void;
     /**
-     * 初始化支付SDK（后台静默执行）
+     * Get packages to display
+     * CreditPackageModal returns CREDIT_PACKAGES
+     * GenericPackageModal returns this.options.packages
      */
-    private initializeSDK;
+    protected abstract getPackages(): TPackage[];
     /**
-     * 关闭弹框
+     * Get package display name for payment modal title
+     */
+    protected abstract getPackageDisplayName(pkg: TPackage): string;
+    /**
+     * Get loading button HTML with spinner
+     * @param text Loading text
+     * @param args Additional arguments (e.g., isPopular for CreditPackageModal)
+     */
+    protected abstract getLoadingButtonHTML(text: string, ...args: any[]): string;
+    /**
+     * Open the modal
+     */
+    open(): Promise<void>;
+    /**
+     * Close the modal
      */
     close(): void;
     /**
-     * 获取响应式样式配置
+     * Check if modal is open
      */
-    private getResponsiveStyles;
+    isOpen(): boolean;
     /**
-     * 渲染弹框内容
+     * Apply modal styling (hook method)
+     * Subclasses can override to customize modal appearance
      */
-    private renderContent;
+    protected applyModalStyling(): void;
     /**
-     * 渲染套餐卡片
+     * Initialize payment SDK (identical in both classes)
      */
-    private renderPackageCard;
+    protected initializeSDK(): Promise<void>;
     /**
-     * 格式化数字（添加逗号）
+     * Wait for SDK initialization with timeout and retry
+     * @param timeout Timeout in milliseconds (default 30 seconds)
+     * @param maxRetries Maximum retry count (default 1)
+     * @returns Whether initialization succeeded
      */
-    private formatNumber;
+    protected waitForSDKInitialization(timeout?: number, maxRetries?: number): Promise<boolean>;
     /**
-     * 获取加载按钮的 HTML（带旋转动画）
-     * @param text 加载文本
-     * @param isPopular 是否为 Popular 套餐（用于调整颜色）
+     * Handle payment flow (order creation + payment modal)
      */
-    private getLoadingButtonHTML;
+    protected handlePaymentFlow(pkg: TPackage, button: HTMLButtonElement, originalHTML: string): Promise<void>;
     /**
-     * 添加事件监听
+     * Open payment modal (DropinPaymentModal + PurchaseSuccessModal)
      */
-    private attachEventListeners;
+    protected openPaymentModal(orderId: string, pkg: TPackage): Promise<void>;
     /**
-     * 处理支付流程
+     * Attach event listeners to package buttons
      */
-    private handlePaymentFlow;
+    protected attachEventListeners(container: HTMLElement): void;
     /**
-     * 打开支付弹框
+     * Cleanup resources
      */
-    private openPaymentModal;
+    protected cleanup(): void;
     /**
-     * 清理资源
+     * Format number with commas
      */
-    private cleanup;
+    protected formatNumber(num: string): string;
     /**
-     * 检查弹框是否打开
+     * Get content container from modal
      */
-    isOpen(): boolean;
+    protected getContentContainer(): HTMLElement | null;
 }
 
 /**
- * GenericPackageModal - 通用套餐选择弹框
- * 支持多种套餐类型（破冰包、告急包、首充包等）
- * 套餐数据从外部配置传入,无硬编码
+ * CreditPackageModal - 积分套餐选择弹框
+ * 展示不同的积分套餐供用户选择
  */
 
-interface GenericPackageModalOptions {
-    /** 套餐数据（必填 - 从外部配置传入） */
-    packages: GenericPackage[];
-    /** SDK 配置（必填 - 用于自动初始化支付 SDK） */
-    sdkConfig: PaymentSDKConfig;
-    /** 语言（默认 'en'） */
-    language?: 'en' | 'zh-CN';
+interface CreditPackageModalOptions extends BasePackageModalOptions<CreditPackage> {
+    /** Modal title */
+    title?: string;
+    /** Modal title (Chinese) */
+    title_cn?: string;
+    /** Subtitle */
+    subtitle?: string;
+    /** Subtitle (Chinese) */
+    subtitle_cn?: string;
+}
+declare class CreditPackageModal extends BasePackageModal<CreditPackage, CreditPackageModalOptions> {
+    private readonly SPACING;
+    private readonly COLORS;
     /**
-     * 支付成功回调 - 弹框内部完成支付后通知使用方
-     * @param orderId 订单ID
-     * @param transactionId 交易ID
-     * @param pkg 购买的套餐
+     * Create and configure the PaymentModal instance
      */
-    onPaymentSuccess?: (orderId: string, transactionId: string, pkg: GenericPackage) => void;
+    protected createModal(): PaymentModal;
     /**
-     * 支付失败回调
-     * @param error 错误信息
-     * @param pkg 购买失败的套餐
+     * Get packages to display
      */
-    onPaymentFailed?: (error: Error, pkg: GenericPackage) => void;
-    /** 弹框关闭回调 */
-    onClose?: () => void;
-}
-declare class GenericPackageModal {
-    private modal;
-    private options;
-    private language;
-    private resizeHandler;
-    private isInitializingSDK;
-    private sdkInitialized;
-    private paymentMethod?;
-    private accountToken?;
-    constructor(options: GenericPackageModalOptions);
+    protected getPackages(): CreditPackage[];
     /**
-     * 打开弹框
+     * Get package display name for payment modal title
      */
-    open(): Promise<void>;
+    protected getPackageDisplayName(pkg: CreditPackage): string;
     /**
-     * 等待 SDK 初始化完成（支持超时和重试）
-     * @param timeout 超时时间（毫秒），默认 30 秒
-     * @param maxRetries 最大重试次数，默认 1 次
-     * @returns 是否初始化成功
+     * Get loading button HTML with spinner
      */
-    private waitForSDKInitialization;
+    protected getLoadingButtonHTML(text: string, isPopular?: boolean): string;
     /**
-     * 初始化支付SDK（后台静默执行）
+     * Apply modal styling (hook method override)
      */
-    private initializeSDK;
+    protected applyModalStyling(): void;
     /**
-     * 关闭弹框
+     * Render modal content
      */
-    close(): void;
+    protected renderContent(): void;
+    /**
+     * Get responsive style configuration
+     */
+    private getResponsiveStyles;
     /**
-     * 渲染弹框内容
+     * Render compute credits cards
      */
-    private renderContent;
+    private renderComputeCreditsCards;
     /**
-     * 渲染套餐卡片
+     * Render package card
      */
     private renderPackageCard;
+}
+
+/**
+ * GenericPackageModal - 通用套餐选择弹框
+ * 支持多种套餐类型（破冰包、告急包、首充包等）
+ * 套餐数据从外部配置传入,无硬编码
+ */
+
+interface GenericPackageModalOptions extends BasePackageModalOptions<GenericPackage> {
+    /** Package data (required - passed from external configuration) */
+    packages: GenericPackage[];
+}
+declare class GenericPackageModal extends BasePackageModal<GenericPackage, GenericPackageModalOptions> {
+    constructor(options: GenericPackageModalOptions);
     /**
-     * 格式化数字（添加逗号）
+     * Create and configure the PaymentModal instance
      */
-    private formatNumber;
+    protected createModal(): PaymentModal;
     /**
-     * 获取加载按钮的 HTML（带旋转动画）
+     * Get packages to display
      */
-    private getLoadingButtonHTML;
+    protected getPackages(): GenericPackage[];
     /**
-     * 添加事件监听
+     * Get package display name for payment modal title
      */
-    private attachEventListeners;
+    protected getPackageDisplayName(pkg: GenericPackage): string;
     /**
-     * 处理支付流程
+     * Get loading button HTML with spinner
      */
-    private handlePaymentFlow;
+    protected getLoadingButtonHTML(text: string): string;
     /**
-     * 打开支付弹框
+     * Apply modal styling (hook method override)
      */
-    private openPaymentModal;
+    protected applyModalStyling(): void;
     /**
-     * 清理资源
+     * Render modal content
      */
-    private cleanup;
+    protected renderContent(): void;
     /**
-     * 检查弹框是否打开
+     * Render package card
      */
-    isOpen(): boolean;
-}
-
-/**
- * 积分套餐数据
- */
-interface CreditPackage {
-    id: string;
-    name: string;
-    price: string;
-    currency: string;
-    base_credits: string;
-    bonus_credits: string;
-    credits: string;
-    day_limit: number;
-    is_popular?: boolean;
-}
-declare const CREDIT_PACKAGES: CreditPackage[];
-/**
- * 创作力量类型和对应的积分消耗
- */
-interface CreativePowerType {
-    icon: string;
-    name: string;
-    name_cn: string;
-    credits_range: string;
-    description: string;
-    description_cn: string;
+    private renderPackageCard;
 }
-declare const CREATIVE_POWER_TYPES: CreativePowerType[];
 
 /**
  * 共享配置文件
@@ -2452,5 +2570,5 @@ declare function pollOrderStatus(transactionId: string, apiHost: string, authTok
  */
 declare const VERSION = "0.8.0";
 
-export { API_ENDPOINTS, BIZ_CODE, BindCardPaymentComponent, COMPONENT_LOAD_TIMEOUT, CREATIVE_POWER_TYPES, CREDIT_PACKAGES, CheckoutAPI, CreditPackageModal, DEFAULT_CHECKOUT_CONFIG, DropinPaymentComponent, DropinPaymentModal, ENVIRONMENT_CONFIGS, ENV_CONFIG, ErrorHandler, GRID_COLUMNS, GenericPackageModal, HTTP_STATUS, LinkPaymentComponent, OrderPayment, PAYMENT_ELEMENT_NAME, PaymentAPIError, PaymentCheckoutClient, PaymentClient, PaymentError, PaymentModal, PaymentStorage, PurchaseSuccessModal, RESPONSIVE_BREAKPOINTS, SDK_CONFIG, ScriptLoader, SeaArtPayLoader, SeaartPaymentSDK, StylesheetLoader, VERSION, centsToDollars, changeSubscription, checkOrderStatus, createCheckoutPaymentError, createOrder, delay, dollarsToCents, formatPrice, generateOrderReference, getActiveSubscription, getCreditDetail, getCurrentSubscription, getCurrentUrl, getGlobalLoader, getSDKLocale, hideLoadingIndicator, isBrowser, isCheckoutPaymentError, pollOrderStatus, resetGlobalLoader, restartSubscription, safeJsonParse, showErrorMessage, showInfoMessage, showLoadingIndicator, showSuccessMessage, withTimeout };
-export type { ActiveSubscription, ApiErrorResponse, ApiResponse, ApiSuccessResponse, BaseCheckoutOptions, BillingPeriod, BindCard, BindCardCallbacks, BindCardPaymentOptions, CheckoutAPIConfig, CheckoutAPIResponse, CheckoutClientConfig, CheckoutClientStatus, CheckoutOptions, CheckoutPaymentError, CheckoutPaymentErrorCode, CheckoutResult, ComponentLoadStatus, CreateOrderResponse, CreativePowerType, CreditAccount, CreditAccountStatus, CreditDetailResponse$1 as CreditDetailResponse, CreditDetailSuccessResponse, CreditPackage, CreditPackageModalOptions, CreditPoolDetail, CreditPoolType$1 as CreditPoolType, CreditTransaction, CurrentSubscription, DropinCallbacks, DropinPaymentModalOptions, DropinPaymentOptions, Environment, EnvironmentConfig, GenericPackage, GenericPackageModalOptions, LinkPaymentOptions, ListTransactionsRequest, LoaderConfig, OrderInfo, OrderStatus, OrderStatusResponse, PaymentClientOptions, PaymentEnvironment, PaymentMethod, PaymentMethodsParams, PaymentModalOptions, PaymentReadyEventDetail, PaymentResult, PaymentSDKConfig, PaymentSuccessEventDetail, PaymentUnsuccessEventDetail, PaymentUnsuccessResult, PurchaseSuccessData, PurchaseSuccessModalOptions, PurchaseType, SDKCheckoutRequest, SDKCheckoutResponse, SDKConfig, SDKLoadStatus, ScriptLoaderOptions, SeaArtPaymentElement, SeaartBindCardPayment, SeaartDropinPayment, SeaartLinkPayment, SeaartPaymentComponentSDK, SeaartPaymentInstance, SeaartPaymentSDKConfig, ShowPaymentOptions, SubscribeOptions, SubscriptionParams, SubscriptionPeriod, TransactionListResponse, TransactionStatus, TransactionStorageData, TransactionType, UnifiedResponse };
+export { API_ENDPOINTS, BIZ_CODE, BindCardPaymentComponent, COMPONENT_LOAD_TIMEOUT, CREATIVE_POWER_TYPES, CREDIT_PACKAGES, CheckoutAPI, CreditPackageModal, DEFAULT_CHECKOUT_CONFIG, DropinPaymentComponent, DropinPaymentModal, ENVIRONMENT_CONFIGS, ENV_CONFIG, ErrorHandler, GRID_COLUMNS, GenericPackageModal, HTTP_STATUS, LinkPaymentComponent, OrderPayment, PAYMENT_ELEMENT_NAME, PaymentAPIError, PaymentCheckoutClient, PaymentClient, PaymentError, PaymentModal, PaymentStorage, PurchaseSuccessModal, RESPONSIVE_BREAKPOINTS, RetentionModal, SDK_CONFIG, ScriptLoader, SeaArtPayLoader, SeaartPaymentSDK, StylesheetLoader, VERSION, centsToDollars, changeSubscription, checkOrderStatus, createCheckoutPaymentError, createOrder, delay, dollarsToCents, formatPrice, generateOrderReference, getActiveSubscription, getCreditDetail, getCurrentSubscription, getCurrentUrl, getGlobalLoader, getSDKLocale, hideLoadingIndicator, isBrowser, isCheckoutPaymentError, pollOrderStatus, resetGlobalLoader, restartSubscription, safeJsonParse, showErrorMessage, showInfoMessage, showLoadingIndicator, showSuccessMessage, withTimeout };
+export type { ActiveSubscription, ApiErrorResponse, ApiResponse, ApiSuccessResponse, BaseCheckoutOptions, BillingPeriod, BindCard, BindCardCallbacks, BindCardPaymentOptions, CheckoutAPIConfig, CheckoutAPIResponse, CheckoutClientConfig, CheckoutClientStatus, CheckoutOptions, CheckoutPaymentError, CheckoutPaymentErrorCode, CheckoutResult, ComponentLoadStatus, CreateOrderResponse, CreativePowerType, CreditAccount, CreditAccountStatus, CreditDetailResponse$1 as CreditDetailResponse, CreditDetailSuccessResponse, CreditPackage, CreditPackageModalOptions, CreditPoolDetail, CreditPoolType$1 as CreditPoolType, CreditTransaction, CurrentSubscription, DropinCallbacks, DropinPaymentModalOptions, DropinPaymentOptions, Environment, EnvironmentConfig, GenericPackage, GenericPackageModalOptions, LinkPaymentOptions, ListTransactionsRequest, LoaderConfig, OrderInfo, OrderStatus, OrderStatusResponse, PaymentClientOptions, PaymentEnvironment, PaymentMethod, PaymentMethodsParams, PaymentModalOptions, PaymentReadyEventDetail, PaymentResult, PaymentSDKConfig, PaymentSuccessEventDetail, PaymentUnsuccessEventDetail, PaymentUnsuccessResult, PurchaseSuccessData, PurchaseSuccessModalOptions, PurchaseType, RetentionModalOptions, SDKCheckoutRequest, SDKCheckoutResponse, SDKConfig, SDKLoadStatus, ScriptLoaderOptions, SeaArtPaymentElement, SeaartBindCardPayment, SeaartDropinPayment, SeaartLinkPayment, SeaartPaymentComponentSDK, SeaartPaymentInstance, SeaartPaymentSDKConfig, ShowPaymentOptions, SubscribeOptions, SubscriptionParams, SubscriptionPeriod, TransactionListResponse, TransactionStatus, TransactionStorageData, TransactionType, UnifiedResponse };