@seaverse/payment-sdk 0.8.0 → 0.8.2

package/README.md

@@ -2,7 +2,7 @@
 
 SeaVerse Payment SDK - 一站式支付解决方案，提供积分管理、支付弹窗、订阅管理和订单跟踪功能。
 
-> **最新版本**: v0.8.0 | **文档语言**: 中文优先（包含英文说明）
+> **最新版本**: v0.8.2 | **文档语言**: 中文优先（包含英文说明）
 
 ## 📦 安装
 
@@ -95,6 +95,46 @@ const modal = new GenericPackageModal({
 modal.open();
 ```
 
+## 🏗️ 架构设计
+
+### 代码重构 (v0.8.1)
+
+为了提高代码可维护性和消除重复逻辑，SDK 进行了架构重构：
+
+**核心改进**：
+- ✅ **抽象基类设计** - 创建 `BasePackageModal<TPackage, TOptions>` 抽象基类
+- ✅ **消除重复代码** - 减少 ~400 行重复代码（SDK 初始化、支付流程、事件处理）
+- ✅ **类型安全** - 使用 TypeScript 泛型确保类型安全
+- ✅ **向后兼容** - 公开 API 完全不变，现有代码无需修改
+
+**类继承结构**：
+
+```
+BasePackageModal<TPackage, TOptions>  (抽象基类)
+├── CreditPackageModal                 (积分套餐弹框)
+└── GenericPackageModal                (通用套餐弹框)
+```
+
+**BasePackageModal 提供的共享功能**：
+- SDK 初始化和状态管理
+- 支付流程处理（订单创建、支付弹框）
+- 事件监听和按钮处理
+- 工具方法（formatNumber、cleanup 等）
+
+**子类只需实现**：
+- `createModal()` - 创建和配置 PaymentModal
+- `renderContent()` - 渲染弹框内容（UI 特定逻辑）
+- `getPackages()` - 获取套餐列表
+- `getPackageDisplayName()` - 获取套餐显示名称
+- `getLoadingButtonHTML()` - 获取加载按钮 HTML
+
+这种设计确保：
+- **单一职责** - 基类负责逻辑，子类负责 UI
+- **DRY 原则** - 共享逻辑只需维护一处
+- **易于扩展** - 添加新套餐类型只需继承基类
+
+---
+
 ## 📖 核心功能模块
 
 ### ⭐️ 推荐功能（新用户优先使用）
@@ -562,6 +602,170 @@ if (result.success) {
 
 ---
 
+### DropinPaymentModal - Dropin 支付弹框（带挽留功能）
+
+**适用场景**：
+- ✅ 需要弹框形式的 Dropin 支付（无需自己创建弹框容器）
+- ✅ 支持用户取消支付时的挽留弹框（可选）
+- ✅ 自动处理弹框打开/关闭/清理逻辑
+
+#### 基础用法
+
+```typescript
+import { SeaartPaymentSDK, DropinPaymentModal } from '@seaverse/payment-sdk';
+
+// 1. 初始化 SDK
+const sdk = SeaartPaymentSDK.getInstance();
+await sdk.init({
+  scriptUrl: 'https://your-cdn.com/seaart-payment.js',
+  clientId: 'your-client-id',
+  language: 'en',
+});
+
+// 2. 获取支付方式
+const methods = await sdk.getPaymentMethods({
+  country_code: 'US',
+  business_type: 1,  // 1=一次性购买
+});
+
+// 3. 创建订单支付实例
+const orderPayment = sdk.createOrderPayment({
+  orderId: 'order-123',
+  accountToken: 'user-token',
+});
+
+// 4. 选择 Dropin 支付方式
+const dropinMethod = methods.find(m => m.payment_type === 2);
+
+// 5. 创建 Dropin 支付弹框
+const modal = new DropinPaymentModal(
+  orderPayment,
+  'order-123',
+  'user-token',
+  dropinMethod,
+  {
+    // 弹框配置
+    modalTitle: `Pay with ${dropinMethod.payment_method_name}`,
+    enableRetention: true,  // 启用挽留弹框（默认：true）
+
+    // 挽留弹框配置
+    retentionOptions: {
+      language: 'en',  // 'en' | 'zh-CN'
+      bonusAmount: 990,  // 活动赠送积分（可选）
+    },
+
+    // 支付回调
+    onCompleted: (payload) => {
+      console.log('支付成功！', payload);
+      // 刷新积分、更新 UI 等
+    },
+
+    onFailed: (payload) => {
+      console.error('支付失败：', payload);
+    },
+
+    onLoading: (loading) => {
+      console.log('加载状态：', loading);
+    },
+  }
+);
+
+// 6. 打开弹框
+await modal.open();
+
+// 可选：手动关闭弹框
+// modal.close();
+
+// 可选：检查弹框状态
+// console.log('弹框是否打开：', modal.isOpen());
+```
+
+#### 挽留弹框流程说明
+
+当用户尝试取消支付时（点击关闭按钮或 ESC 键），会触发以下流程：
+
+1. **关闭支付弹框** → 支付弹框关闭
+2. **显示挽留弹框** → 自动弹出挽留弹框，展示：
+   - 订单详情（商品名称、购买数量、优惠价格）
+   - 倒计时提示（15分钟订单过期时间）
+   - 活动赠送（如果有）
+3. **用户选择**：
+   - **继续支付**：关闭挽留弹框 → 重新打开支付弹框
+   - **确认取消**：关闭所有弹框 → 清理资源
+
+#### 配置选项
+
+```typescript
+interface DropinPaymentModalOptions {
+  // 弹框标题
+  modalTitle?: string;
+
+  // 弹框选项
+  modalOptions?: {
+    showCloseButton?: boolean;      // 显示关闭按钮（默认：true）
+    closeOnOverlayClick?: boolean;  // 点击遮罩关闭（默认：false）
+    closeOnEsc?: boolean;           // ESC 键关闭（默认：false）
+    className?: string;             // 自定义类名
+    maxWidth?: string;              // 最大宽度（默认：'600px'）
+  };
+
+  // 是否启用挽留弹框（默认：true）
+  enableRetention?: boolean;
+
+  // 挽留弹框配置
+  retentionOptions?: {
+    language?: 'en' | 'zh-CN';  // 语言（默认：'en'）
+    bonusAmount?: number;        // 活动赠送积分（可选）
+  };
+
+  // 支付回调
+  onSubmit?: (payload: any) => void;
+  onError?: (payload: any, error: any) => void;
+  onCreateOrder?: (payload: any) => void;
+  onCompleted?: (payload: any) => void;
+  onFailed?: (payload: any) => void;
+  onLoading?: (loading: boolean) => void;
+}
+```
+
+#### 挽留弹框预览
+
+挽留弹框采用深色卡片设计，包含：
+- 订单倒计时（15 分钟）
+- 商品信息（名称、购买数量、活动赠送、优惠价）
+- 价格显示（自动根据货币代码映射符号，如 USD→$, EUR→€, JPY→¥ 等）
+- 两个按钮：「取消」和「继续支付」（使用与积分弹框一致的绿色渐变主题色）
+
+**支持的货币符号**：
+- 美元 (USD) → $
+- 欧元 (EUR) → €
+- 英镑 (GBP) → £
+- 日元 (JPY) / 人民币 (CNY) → ¥
+- 新加坡元 (SGD) → S$
+- 港币 (HKD) → HK$
+- 等 30+ 种货币符号...
+
+#### 禁用挽留弹框
+
+如果不需要挽留功能，可以禁用：
+
+```typescript
+const modal = new DropinPaymentModal(
+  orderPayment,
+  'order-123',
+  'user-token',
+  dropinMethod,
+  {
+    enableRetention: false,  // 禁用挽留弹框
+    onCompleted: (payload) => {
+      console.log('支付成功！', payload);
+    },
+  }
+);
+```
+
+---
+
 ## ⚙️ 配置选项
 
 ### 环境配置（Environment）
@@ -838,5 +1042,27 @@ MIT License
 
 ---
 
-**更新日期**: 2026-01-31
-**SDK 版本**: v0.8.0
+**更新日期**: 2026-02-02
+**SDK 版本**: v0.8.2
+
+## 📝 更新日志
+
+### v0.8.2 (2026-02-02)
+
+**架构重构**：
+- 🏗️ 创建 `BasePackageModal` 抽象基类，消除 `CreditPackageModal` 和 `GenericPackageModal` 之间的重复代码
+- 📉 减少约 400 行重复代码（25% 代码量减少）
+- 🎯 `CreditPackageModal`: 从 1042 行减少到 515 行
+- 🎯 `GenericPackageModal`: 从 752 行减少到 340 行
+- ✅ 完全向后兼容，现有代码无需修改
+- 🔒 通过 TypeScript 泛型确保类型安全
+
+**类型系统改进**：
+- 新增 `BasePackage` 接口 - 所有套餐类型的基础接口
+- 新增 `BasePackageModalOptions<TPackage>` 接口 - 通用配置接口
+- `CreditPackage` 和 `GenericPackage` 现在继承自 `BasePackage`
+
+**开发体验提升**：
+- 更容易添加新的套餐类型（只需继承 `BasePackageModal`）
+- 修复 bug 只需在基类中修改一处
+- 更清晰的职责分离（基类处理逻辑，子类处理 UI）