@seaverse/payment-sdk 0.8.2 → 0.9.1

package/README.md

@@ -1,281 +1,286 @@
 # @seaverse/payment-sdk
 
-SeaVerse Payment SDK - 一站式支付解决方案，提供积分管理、支付弹窗、订阅管理和订单跟踪功能。
+> **Version**: 0.9.1 | **Language**: English
 
-> **最新版本**: v0.8.2 | **文档语言**: 中文优先（包含英文说明）
+A comprehensive payment solution for SeaVerse platform, providing credit management, payment checkout, subscription management, and order tracking.
 
-## 📦 安装
+## 📦 Installation
 
 ```bash
 npm install @seaverse/payment-sdk
-# 或
+# or
 pnpm add @seaverse/payment-sdk
+# or
+yarn add @seaverse/payment-sdk
 ```
 
-## 🚀 快速开始
+## 🚀 Quick Start
 
-### 1. 积分套餐购买弹窗（推荐使用）
+### 1. Credit Package Modal (Recommended)
 
-最简单的集成方式 - 3 行代码完成支付流程：
+The simplest integration - complete payment flow in 3 lines of code:
 
 ```typescript
 import { CreditPackageModal } from '@seaverse/payment-sdk';
 
-// 创建弹窗
+// Create modal
 const modal = new CreditPackageModal({
+  language: 'en',  // 'en' | 'zh' | 'zh-TW' | 'ja' | 'ko' | 'es' | 'fr' | 'de' | 'pt' | 'ru' | 'ar' | 'hi' | 'id'
+
   sdkConfig: {
-    environment: 'development',     // 环境：'development' | 'production'
-    countryCode: 'SG',              // 国家代码
-    accountToken: 'user-token',     // 用户认证令牌（可选）
+    environment: 'development',     // 'development' | 'production'
+    accountToken: 'user-token',     // User authentication token
   },
-  onPaymentSuccess: (orderId, transactionId) => {
-    console.log('支付成功！', { orderId, transactionId });
+
+  onPaymentSuccess: (orderId, transactionId, pkg) => {
+    console.log('Payment successful!', { orderId, transactionId, credits: pkg.total_credits });
   },
 });
 
-// 打开弹窗
+// Open modal
 modal.open();
 ```
 
-**效果**：
-- ✅ 自动展示预设积分套餐（120/240/520/1200 积分）
-- ✅ 自动初始化支付 SDK
-- ✅ 自动创建订单
-- ✅ 显示购买成功弹窗（带动画效果）
-- ✅ 自动刷新积分余额
+**What you get**:
+- ✅ Pre-configured credit packages (fetched from API)
+- ✅ Automatic SDK initialization
+- ✅ Auto order creation
+- ✅ Animated success modal
+- ✅ Auto credit balance refresh
 
-### 2. 通用套餐弹窗（自定义套餐）
+### 2. Generic Package Modal (Custom Packages)
 
-适用于特殊促销、破冰包、首充包等场景：
+For promotions, special offers, and custom packages:
 
 ```typescript
 import { GenericPackageModal, type GenericPackage } from '@seaverse/payment-sdk';
 
-// 定义自定义套餐
+// Define custom packages
 const packages: GenericPackage[] = [
   {
-    id: 'pkg_value',
+    id: 'pkg_ice_breaker',
     name: 'Ice Breaker Pack',
     price: '0.49',
     currency: 'USD',
     credits: '120',
+    base_credits: '100',
+    bonus_credits: '20',
     bonus_percentage: 20,
-    day_limit: 1,  // 每日限购1次
     package_type: 'iceBreaker',
   },
-  {
-    id: 'pkg_pro',
-    name: 'Emergency Pack',
-    price: '0.99',
-    currency: 'USD',
-    credits: '240',
-    day_limit: 3,  // 每日限购3次
-    package_type: 'emergency',
-  },
 ];
 
-// 创建弹窗
+// Create modal
 const modal = new GenericPackageModal({
   packages: packages,
+  language: 'en',
+
   sdkConfig: {
     environment: 'development',
-    countryCode: 'SG',
     accountToken: 'user-token',
   },
+
   onPaymentSuccess: (orderId, transactionId, pkg) => {
-    console.log(`${pkg.name} 购买成功！`, orderId);
+    console.log(`${pkg.name} purchased!`, orderId);
   },
-  onPaymentFailed: (error, pkg) => {
-    if (error.message.includes('limit')) {
-      alert(`${pkg.name} 已达购买限额`);
-    }
+});
+
+modal.open();
+```
+
+### 3. Payment Checkout Modal (Full Checkout Experience)
+
+Complete checkout flow with payment method selection:
+
+```typescript
+import { PaymentCheckoutModal, PRODUCT_TYPE } from '@seaverse/payment-sdk';
+
+const modal = new PaymentCheckoutModal({
+  product: {
+    id: 'pkg_credit_100',
+    name: '100 Credits Package',
+    price: 9.99,
+    currency: 'USD',
+    type: PRODUCT_TYPE.CREDITPACK,
+  },
+
+  autoCreateOrder: {
+    productId: 'pkg_credit_100',
+    purchaseType: 1,  // 1 = one-time purchase, 2 = subscription
+    apiHost: 'https://payment.seaverse.com',
+    accountToken: 'user-token',
+    clientId: 'your-client-id',
+    language_code: 'en',
+  },
+
+  language: 'en',
+
+  onPaymentSuccess: (payload) => {
+    console.log('Payment completed!', payload);
   },
 });
 
 modal.open();
 ```
 
-## 🏗️ 架构设计
+---
+
+## 🏗️ Architecture
+
+### Version 0.9.0 - Critical Bug Fixes
+
+**Major fixes in this release**:
 
-### 代码重构 (v0.8.1)
+1. **Fixed SDK Initialization Error** 🔧
+   - Resolved "Payment method 'dropin' not found" error
+   - Issue: BasePackageModal tried to find Dropin payment when only Link payments available
+   - Solution: Override `initializeSDK()` in CreditPackageModal and GenericPackageModal to skip legacy initialization
+   - Now PaymentCheckoutModal handles all SDK initialization independently
 
-为了提高代码可维护性和消除重复逻辑，SDK 进行了架构重构：
+2. **Fixed Link Payment Auto-Execution** 🔧
+   - Prevented immediate redirect before users see checkout modal
+   - Issue: `autoSelectDefaultPaymentMethod()` auto-executed Link payment, causing instant redirect
+   - Solution: Only auto-select Dropin payments, wait for manual selection when only Link available
+   - Improved user experience with proper checkout flow
 
-**核心改进**：
-- ✅ **抽象基类设计** - 创建 `BasePackageModal<TPackage, TOptions>` 抽象基类
-- ✅ **消除重复代码** - 减少 ~400 行重复代码（SDK 初始化、支付流程、事件处理）
-- ✅ **类型安全** - 使用 TypeScript 泛型确保类型安全
-- ✅ **向后兼容** - 公开 API 完全不变，现有代码无需修改
+3. **UI/UX Enhancements** 🎨
+   - Increased payment method card spacing from 8px to 14px
+   - Better visual hierarchy and click targets
+   - Consistent spacing in both skeleton and main UI
 
-**类继承结构**：
+### Class Hierarchy
 
 ```
-BasePackageModal<TPackage, TOptions>  (抽象基类)
-├── CreditPackageModal                 (积分套餐弹框)
-└── GenericPackageModal                (通用套餐弹框)
+BasePackageModal<TPackage, TOptions>  (Abstract base class)
+├── CreditPackageModal                (Standard credit packages)
+└── GenericPackageModal               (Custom promotional packages)
+
+PaymentCheckoutModal                   (Standalone checkout system)
+├── PaymentStrategyFactory
+│   ├── LinkPaymentStrategy           (Redirect payments)
+│   ├── DropinPaymentStrategy         (Embedded forms)
+│   └── BasePaymentStrategy           (Strategy base)
+└── Services
+    ├── PaymentOrderService           (Order management)
+    ├── PaymentLoadingManager         (Loading states)
+    └── PaymentStateManager           (State management)
 ```
 
-**BasePackageModal 提供的共享功能**：
-- SDK 初始化和状态管理
-- 支付流程处理（订单创建、支付弹框）
-- 事件监听和按钮处理
-- 工具方法（formatNumber、cleanup 等）
+### Design Patterns Used
 
-**子类只需实现**：
-- `createModal()` - 创建和配置 PaymentModal
-- `renderContent()` - 渲染弹框内容（UI 特定逻辑）
-- `getPackages()` - 获取套餐列表
-- `getPackageDisplayName()` - 获取套餐显示名称
-- `getLoadingButtonHTML()` - 获取加载按钮 HTML
-
-这种设计确保：
-- **单一职责** - 基类负责逻辑，子类负责 UI
-- **DRY 原则** - 共享逻辑只需维护一处
-- **易于扩展** - 添加新套餐类型只需继承基类
+- **Singleton Pattern**: SeaartPaymentSDK.getInstance()
+- **Strategy Pattern**: Payment strategy selection (Link vs Dropin)
+- **Template Method Pattern**: BasePackageModal with abstract methods
+- **Factory Pattern**: PaymentStrategyFactory.createStrategy()
+- **Service Locator Pattern**: Service injection in PaymentCheckoutModal
 
 ---
 
-## 📖 核心功能模块
+## 📚 Core Features
 
-### ⭐️ 推荐功能（新用户优先使用）
+### 🌟 Recommended Features (For New Users)
 
-| 功能               | 组件                   | 使用场景               | 文档                                            |
-| ------------------ | ---------------------- | ---------------------- | ----------------------------------------------- |
-| **积分套餐购买**   | `CreditPackageModal`   | 标准积分购买（最简单） | [👉 查看](#creditpackagemodal---标准积分购买)    |
-| **自定义套餐购买** | `GenericPackageModal`  | 促销活动、特殊套餐     | [👉 查看](#genericpackagemodal---自定义套餐购买) |
-| **购买成功弹窗**   | `PurchaseSuccessModal` | 自动集成，无需手动调用 | [👉 查看](#purchasesuccessmodal---购买成功弹窗)  |
+| Feature | Component | Use Case | Documentation |
+|---------|-----------|----------|---------------|
+| **Credit Packages** | `CreditPackageModal` | Standard credit purchases | [👉 View](#creditpackagemodal---standard-credit-purchases) |
+| **Custom Packages** | `GenericPackageModal` | Promotions & special offers | [👉 View](#genericpackagemodal---custom-packages) |
+| **Checkout System** | `PaymentCheckoutModal` | Full checkout experience | [👉 View](#paymentcheckoutmodal---checkout-system) |
+| **Success Modal** | `PurchaseSuccessModal` | Auto-integrated, no manual call needed | [👉 View](#purchasesuccessmodal---purchase-success) |
 
-### 🔧 高级功能（进阶用户）
+### 🔧 Advanced Features
 
-| 功能                  | API                                            | 使用场景                   |
-| --------------------- | ---------------------------------------------- | -------------------------- |
-| **积分查询**          | `PaymentClient`                                | 查询用户积分余额、交易记录 |
-| **订阅管理**          | `getCurrentSubscription`, `changeSubscription` | 订阅状态查询、升级/降级    |
-| **订单管理**          | `checkOrderStatus`, `pollOrderStatus`          | 订单状态查询、轮询         |
-| **SeaartPayment SDK** | `SeaartPaymentSDK`                             | 完全自定义支付流程         |
+| Feature | API | Use Case |
+|---------|-----|----------|
+| **Credit Query** | `getCreditDetail` | Check user credit balance |
+| **Subscription Management** | `getCurrentSubscription`, `changeSubscription` | Manage subscriptions |
+| **Order Management** | `checkOrderStatus`, `pollOrderStatus` | Track order status |
+| **Custom Payment Flows** | `SeaartPaymentSDK` | Full control over payment process |
 
 ---
 
-## 📚 详细使用文档
+## 📖 Detailed Documentation
 
-### CreditPackageModal - 标准积分购买
+### CreditPackageModal - Standard Credit Purchases
 
-**适用场景**：
-- ✅ 标准积分套餐购买（120/240/520/1200 积分）
-- ✅ 展示创作力量类型（文生图、图生图等）
-- ✅ 最简单的集成方式
+**Use Cases**:
+- ✅ Standard credit package purchases
+- ✅ Dynamic packages from API
+- ✅ Simplest integration method
 
-#### 基础用法
+#### Basic Usage
 
 ```typescript
 import { CreditPackageModal } from '@seaverse/payment-sdk';
 
 const modal = new CreditPackageModal({
-  // 语言设置（可选，默认 'en'）
-  language: 'zh-CN',  // 'en' | 'zh-CN'
+  // Language (optional, defaults to 'en')
+  language: 'en',  // 'en' | 'zh' | 'zh-TW' | 'ja' | 'ko' | etc.
+
+  // Modal title (optional)
+  title: 'Purchase Credits',
+  title_cn: '购买积分',  // Chinese title
 
-  // SDK 配置（必填）
+  // SDK Configuration (required)
   sdkConfig: {
-    environment: 'development',  // 'development' | 'production'
-    countryCode: 'SG',           // ISO 3166-1 国家代码
-    accountToken: 'user-token',  // 用户认证令牌（可选）
-    businessType: 1,             // 1=一次性购买, 2=订阅（可选，默认1）
+    environment: 'production',
+    accountToken: 'user-token',
+
+    // Optional overrides
+    businessType: 1,  // 1 = one-time, 2 = subscription
+    clientId: 'custom-client-id',
+    orderApiUrl: 'https://custom-api.com',
   },
 
-  // 回调函数
-  onPaymentSuccess: (orderId: string, transactionId: string) => {
-    console.log('支付成功！', { orderId, transactionId });
-    // 刷新用户积分、更新 UI 等
+  // Callbacks
+  onPaymentSuccess: (orderId, transactionId, pkg) => {
+    console.log('Payment successful!', {
+      orderId,
+      transactionId,
+      credits: pkg.total_credits
+    });
   },
 
-  onPaymentFailed: (error: Error) => {
-    console.error('支付失败：', error.message);
-    // 显示错误提示
+  onPaymentFailed: (error, pkg) => {
+    console.error('Payment failed:', error.message);
   },
 
   onClose: () => {
-    console.log('弹窗关闭');
+    console.log('Modal closed');
   },
 });
 
-// 打开弹窗
+// Open modal
 modal.open();
 
-// 关闭弹窗（可选）
+// Close modal (optional)
 modal.close();
 
-// 检查弹窗状态
-console.log('弹窗是否打开：', modal.isOpen());
-```
-
-#### 预设积分套餐
-
-SDK 内置以下积分套餐：
-
-| 套餐    | 积分 | 价格  | 说明     |
-| ------- | ---- | ----- | -------- |
-| Starter | 120  | $0.49 | 入门套餐 |
-| Value   | 240  | $0.99 | 超值套餐 |
-| Pro     | 520  | $1.99 | 专业套餐 |
-| Ultra   | 1200 | $4.99 | 旗舰套餐 |
-
-#### 环境配置
-
-SDK 根据 `environment` 自动配置以下参数：
-
-**开发环境 (development)**:
-```typescript
-{
-  scriptUrl: 'https://seaart-publish.sc-api-release.saconsole.com/payment-component/client.js',
-  clientId: 'XF49NOfyZ54O16GujB0ptio2',
-  orderApiUrl: 'https://payment.sg.seaverse.dev',
-  walletApiUrl: 'https://wallet.sg.seaverse.dev',
-}
-```
-
-**生产环境 (production)**:
-```typescript
-{
-  scriptUrl: 'https://payment-static.seaverse.com/sdk/seaart-payment-component.js',
-  clientId: 'prod_client_id',
-  orderApiUrl: 'https://payment.seaverse.com',
-  walletApiUrl: 'https://wallet.seaverse.com',
-}
+// Check status
+console.log('Is open:', modal.isOpen());
 ```
 
-#### 高级配置（可选）
-
-如需覆盖环境配置：
-
-```typescript
-const modal = new CreditPackageModal({
-  sdkConfig: {
-    environment: 'production',
-    countryCode: 'US',
+#### Dynamic Package Fetching
 
-    // 覆盖默认配置
-    scriptUrl: 'https://custom-cdn.com/payment.js',
-    clientId: 'custom-client-id',
-    orderApiUrl: 'https://custom-api.com',
-  },
-});
-```
+Packages are automatically fetched from the API based on:
+- Environment (`development` or `production`)
+- Account token (for user-specific packages)
+- Business type (one-time vs subscription)
 
 ---
 
-### GenericPackageModal - 自定义套餐购买
+### GenericPackageModal - Custom Packages
 
-**适用场景**：
-- ✅ 特殊促销套餐（破冰包、告急包、首充包）
-- ✅ 限时优惠活动
-- ✅ 自定义套餐数据和样式
+**Use Cases**:
+- ✅ Special promotions (ice breaker packs, emergency packs)
+- ✅ Limited-time offers
+- ✅ First-purchase bonuses
+- ✅ Custom package configurations
 
-#### 基础用法
+#### Basic Usage
 
 ```typescript
 import { GenericPackageModal, type GenericPackage } from '@seaverse/payment-sdk';
 
-// 定义套餐数据
 const packages: GenericPackage[] = [
   {
     id: 'pkg_ice_breaker',
@@ -285,523 +290,394 @@ const packages: GenericPackage[] = [
     credits: '120',
     base_credits: '100',
     bonus_credits: '20',
-    bonus_percentage: 20,
-    day_limit: 1,
-    package_type: 'iceBreaker',
+    bonus_percentage: 20,        // Show "+20%" badge
+    package_type: 'iceBreaker',  // Display "One-time Only"
+  },
+  {
+    id: 'pkg_emergency',
+    name: 'Emergency Pack',
+    price: '0.99',
+    currency: 'USD',
+    credits: '240',
+    package_type: 'emergency',
   },
 ];
 
-// 创建弹窗
 const modal = new GenericPackageModal({
-  language: 'zh-CN',
   packages: packages,
+  language: 'en',
 
   sdkConfig: {
     environment: 'development',
-    countryCode: 'SG',
     accountToken: 'user-token',
   },
 
   onPaymentSuccess: (orderId, transactionId, pkg) => {
-    console.log(`${pkg.name} 购买成功！`, { orderId, transactionId });
-  },
-
-  onPaymentFailed: (error, pkg) => {
-    console.error(`${pkg.name} 购买失败：`, error.message);
+    console.log(`${pkg.name} purchased successfully!`);
   },
 });
 
 modal.open();
 ```
 
-#### GenericPackage 接口定义
+#### GenericPackage Interface
 
 ```typescript
 interface GenericPackage {
-  // 基础信息（必填）
-  id: string;              // 套餐唯一标识
-  name: string;            // 套餐名称
-  price: string;           // 价格（字符串，支持小数）
-  currency: string;        // 货币代码（如 'USD'）
-  credits: string;         // 总积分数
-
-  // 奖励信息（可选）
-  base_credits?: string;       // 基础积分
-  bonus_credits?: string;      // 奖励积分
-  bonus_percentage?: number;   // 奖励百分比（如 20 表示 +20%）
-
-  // 购买限制（可选，仅用于展示，后端验证）
-  day_limit?: number;          // 每日限购次数（0 = 无限制）
-  lifetime_limit?: number;     // 终身限购次数（0 = 无限制）
-
-  // 分类标识（可选）
+  // Required fields
+  id: string;              // Unique package identifier
+  name: string;            // Package name
+  price: string;           // Price (string to support decimals)
+  currency: string;        // Currency code (e.g., 'USD')
+  credits: string;         // Total credits
+
+  // Optional bonus fields
+  base_credits?: string;       // Base credits
+  bonus_credits?: string;      // Bonus credits
+  bonus_percentage?: number;   // Bonus percentage (e.g., 20 for +20%)
+
+  // Optional classification
   package_type?: 'iceBreaker' | 'emergency' | 'firstCharge' | 'custom';
 }
 ```
 
-#### 预定义套餐示例
+---
+
+### PaymentCheckoutModal - Checkout System
+
+**Use Cases**:
+- ✅ Full checkout experience with payment method selection
+- ✅ Support for multiple payment types (Link, Dropin, BindCard)
+- ✅ Auto order creation and payment
+- ✅ Advanced customization and control
 
-SDK 提供以下预定义套餐供参考：
+#### Basic Usage
 
 ```typescript
-import {
-  EXAMPLE_ICE_BREAKER,    // 破冰包
-  EXAMPLE_EMERGENCY,      // 告急包
-  EXAMPLE_FIRST_CHARGE,   // 首充包
-  EXAMPLE_PACKAGES,       // 所有示例套餐数组
-} from '@seaverse/payment-sdk';
+import { PaymentCheckoutModal, PRODUCT_TYPE } from '@seaverse/payment-sdk';
+
+const modal = new PaymentCheckoutModal({
+  // Product information
+  product: {
+    id: 'pkg_credit_100',
+    name: '100 Credits Package',
+    price: 9.99,
+    currency: 'USD',
+    type: PRODUCT_TYPE.CREDITPACK,  // CREDITPACK | SUBSCRIPTION | CHANGE_SUBSCRIPTION
+  },
 
-// 使用预定义套餐
-const modal = new GenericPackageModal({
-  packages: [EXAMPLE_ICE_BREAKER, EXAMPLE_EMERGENCY],
-  sdkConfig: { /* ... */ },
+  // Auto create order (recommended)
+  autoCreateOrder: {
+    productId: 'pkg_credit_100',
+    purchaseType: 1,              // 1 = one-time, 2 = subscription
+    apiHost: 'https://payment.seaverse.com',
+    accountToken: 'user-token',
+    clientId: 'your-client-id',
+    language_code: 'en',
+  },
+
+  // Optional configuration
+  accountName: 'John Doe',        // Display in order summary
+  language: 'en',
+
+  // Callbacks
+  onPaymentSuccess: (payload) => {
+    console.log('Payment successful!', payload);
+  },
+
+  onPaymentFailed: (error) => {
+    console.error('Payment failed:', error.message);
+  },
+
+  onPaymentMethodSelect: (method) => {
+    console.log('Payment method selected:', method.payment_method_name);
+  },
+
+  onLinkPaymentStart: (methodName) => {
+    console.log('Link payment started:', methodName);
+    // Show "Please complete payment in new window" message
+  },
+
+  onLoading: (loading) => {
+    console.log('Loading state:', loading);
+  },
 });
+
+modal.open();
 ```
 
-**预定义套餐详情**：
+#### Payment Methods Supported
+
+1. **Link Payment** (payment_type = 1)
+   - Redirect to external payment page
+   - Auto order status polling
+   - Verification modal after redirect
+
+2. **Dropin Payment** (payment_type = 2)
+   - Embedded payment form
+   - Support credit cards, PayPal, etc.
+   - Inline validation and submission
+
+3. **BindCard Payment** (payment_type = 2 with saved cards)
+   - Display saved payment methods
+   - Quick payment with saved cards
+   - Add new card option
 
-| 套餐                   | 价格  | 积分 | 限制    | 说明                     |
-| ---------------------- | ----- | ---- | ------- | ------------------------ |
-| `EXAMPLE_ICE_BREAKER`  | $0.49 | 120  | 每日1次 | 破冰包 - 超低价首次破冰  |
-| `EXAMPLE_EMERGENCY`    | $0.99 | 240  | 每日3次 | 告急包 - 日常转化主力    |
-| `EXAMPLE_FIRST_CHARGE` | $1.99 | 620  | 终身1次 | 首充包 - 提升首充用户LTV |
+#### Auto-Selection Strategy (Fixed in v0.9.0)
+
+The checkout modal intelligently handles payment method selection:
+
+- ✅ **When Dropin available**: Auto-select first Dropin and render payment form
+- ✅ **When only Link available**: Wait for user manual selection (no auto-execution)
+- ✅ **Prevents issue**: No more instant redirect before users see checkout
 
 ---
 
-### PurchaseSuccessModal - 购买成功弹窗
+### PurchaseSuccessModal - Purchase Success
 
-**✨ 自动集成** - 无需手动调用，在 `CreditPackageModal` 和 `GenericPackageModal` 支付成功后自动显示。
+**✨ Auto-integrated** - Automatically displays after successful payment in CreditPackageModal and GenericPackageModal.
 
-#### 功能特性
+#### Features
 
-- ✅ 邮件确认卡片风格设计
-- ✅ 精美动画效果（淡入淡出、缩放、顺序动画）
-- ✅ 显示购买详情（套餐名称、积分数、支付金额）
-- ✅ 支持 ESC 键、点击遮罩、关闭按钮关闭
-- ✅ 自动阻止 body 滚动
-- ✅ 支持中英文切换
+- ✅ Email confirmation card design
+- ✅ Beautiful animations (fade in/out, scale, sequential)
+- ✅ Display purchase details (package name, credits, amount)
+- ✅ Support ESC key, overlay click, close button
+- ✅ Auto prevent body scroll
+- ✅ Multi-language support (13+ languages)
 
-#### 自动触发流程
+#### Auto-trigger Flow
 
 ```
-用户点击购买按钮
+User clicks purchase button
   ↓
-支付成功
+Payment successful
   ↓
-CreditPackageModal/GenericPackageModal 关闭
+CreditPackageModal/GenericPackageModal closes
   ↓
-PurchaseSuccessModal 自动显示（带动画）
+PurchaseSuccessModal displays (with animation)
   ↓
-用户关闭成功弹窗
+User closes success modal
   ↓
-自动刷新积分余额
+Auto credit balance refresh
   ↓
-触发 onPaymentSuccess 回调
+Trigger onPaymentSuccess callback
 ```
 
-#### 手动使用（可选）
-
-如需在其他场景手动调用：
+#### Manual Usage (Optional)
 
 ```typescript
 import { PurchaseSuccessModal } from '@seaverse/payment-sdk';
 
-const successModal = new PurchaseSuccessModal({
+const modal = new PurchaseSuccessModal({
   data: {
     packName: 'Ice Breaker Pack',
     credits: 120,
     amount: '0.49',
-    currency: '$',
+    currency: '$',  // Auto-converted from currency code
     orderId: 'order_123',
     transactionId: 'txn_456',
   },
-  language: 'zh-CN',
+  language: 'en',
   onClose: () => {
-    console.log('成功弹窗关闭');
+    console.log('Success modal closed');
   },
 });
 
-successModal.open();
+modal.open();
 ```
 
 ---
 
-## 🔍 高级功能
+## 🌍 Internationalization
 
-### 积分查询（PaymentClient）
+### Supported Languages (13+)
 
-查询用户积分余额和交易记录：
+| Language | Code | Country Mapping |
+|----------|------|-----------------|
+| English | `en` | US |
+| Simplified Chinese | `zh` | CN |
+| Traditional Chinese | `zh-TW` | TW |
+| Japanese | `ja` | JP |
+| Korean | `ko` | KR |
+| Spanish | `es` | ES |
+| French | `fr` | FR |
+| German | `de` | DE |
+| Portuguese | `pt` | PT |
+| Russian | `ru` | RU |
+| Arabic | `ar` | SA |
+| Hindi | `hi` | IN |
+| Indonesian | `id` | ID |
 
-```typescript
-import { PaymentClient } from '@seaverse/payment-sdk';
-
-const client = new PaymentClient({
-  appId: 'seaverse',
-  token: 'your-bearer-token',
-  baseURL: 'https://payment.sg.seaverse.dev',  // 可选
-});
+### Language Auto-Mapping
 
-// 查询积分详情（4 池结构）
-const detail = await client.getCreditDetail();
-console.log('总余额：', detail.total_balance);
-
-detail.pools.forEach(pool => {
-  console.log(`${pool.type} 池：${pool.balance} 积分`);
-});
+The SDK automatically maps language codes to country codes for payment method retrieval:
 
-// 查询交易记录
-const transactions = await client.listTransactions({
-  page: 1,
-  page_size: 20,
-  start_time: '2024-01-01T00:00:00Z',
-  end_time: '2024-12-31T23:59:59Z',
+```typescript
+// User sets language
+const modal = new CreditPackageModal({
+  language: 'ja',  // Japanese
+  sdkConfig: { /* ... */ }
 });
 
-transactions.transactions.forEach(txn => {
-  console.log(`${txn.type}: ${txn.amount} 积分`);
-});
+// SDK automatically uses country_code: 'JP' when fetching payment methods
 ```
 
-#### 4 池积分系统
-
-| 池类型      | 说明     | 过期时间       |
-| ----------- | -------- | -------------- |
-| `daily`     | 每日积分 | 次日 00:00 UTC |
-| `event`     | 活动积分 | 活动截止日期   |
-| `monthly`   | 月度积分 | 授予后 30 天   |
-| `permanent` | 永久积分 | 永不过期       |
+### Custom Language Handling
 
-**消费优先级**：Daily → Event → Monthly → Permanent
-
----
-
-### 订阅管理
-
-查询和管理用户订阅：
+For SDK initialization, some languages require special formatting:
 
 ```typescript
-import {
-  getCurrentSubscription,
-  getActiveSubscription,
-  changeSubscription,
-  restartSubscription,
-} from '@seaverse/payment-sdk';
-
-const apiUrl = 'https://payment.sg.seaverse.dev';
-const token = 'user-token';
-
-// 查询当前订阅状态
-const current = await getCurrentSubscription(apiUrl, token);
-console.log('订阅状态：', current.subscription_status);
-
-// 查询活跃订阅详情
-const active = await getActiveSubscription(apiUrl, token);
-console.log('当前套餐：', active.product_name);
-
-// 升级/降级订阅
-const changeResult = await changeSubscription(apiUrl, token, {
-  productId: 'pro_plan',
-  billingPeriod: 'year',
-  redirectUrl: window.location.href,
-});
-
-// 重启已取消的订阅
-const restartResult = await restartSubscription(apiUrl, token, {
-  subscriptionId: 'sub_123',
-});
+// SDK Language Format Conversion
+'zh'    → 'zhCN'   // Simplified Chinese
+'zh-TW' → 'zhTW'   // Traditional Chinese
+'en'    → 'en'     // English (no conversion)
+'ja'    → 'ja'     // Japanese (no conversion)
+// ... other languages use code directly
 ```
 
 ---
 
-### 订单管理
-
-检查订单状态和轮询支付结果：
-
-```typescript
-import { checkOrderStatus, pollOrderStatus } from '@seaverse/payment-sdk';
-
-const apiUrl = 'https://payment.sg.seaverse.dev';
-const token = 'user-token';
+## ⚙️ Configuration
 
-// 单次查询订单状态
-const status = await checkOrderStatus('transaction_id', apiUrl, token);
-console.log('订单状态：', status.order_status);
+### Environment Configuration
 
-// 轮询订单状态直到最终状态
-const finalStatus = await pollOrderStatus('transaction_id', apiUrl, token, {
-  interval: 2000,      // 轮询间隔（毫秒）
-  maxAttempts: 30,     // 最大尝试次数
-  onPoll: (status, attempt) => {
-    console.log(`第 ${attempt} 次查询：${status}`);
-  },
-});
+The SDK auto-configures based on `environment`:
 
-console.log('最终状态：', finalStatus.order_status);
+**Development**:
+```typescript
+{
+  scriptUrl: 'https://seaart-publish.sc-api-release.saconsole.com/payment-component/client.js',
+  clientId: 'XF49NOfyZ54O16GujB0ptio2',
+  orderApiUrl: 'https://payment.sg.seaverse.dev',
+  walletApiUrl: 'https://wallet.sg.seaverse.dev',
+  cssUrl: 'https://seaart-publish.sc-api-release.saconsole.com/payment-component/client.css',
+}
 ```
 
----
-
-### SeaartPayment SDK（完全自定义）
-
-适用于需要完全控制支付流程的高级场景：
-
+**Production**:
 ```typescript
-import { SeaartPaymentSDK } 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',
-  cssUrl: 'https://your-cdn.com/seaart-payment.css',  // 可选
-});
-
-// 2. 获取支付方式
-const methods = await sdk.getPaymentMethods({
-  country_code: 'US',
-  business_type: 2,  // 1=一次性, 2=订阅
-});
+{
+  scriptUrl: 'https://payment-static.seaverse.com/sdk/seaart-payment-component.js',
+  clientId: 'prod_client_id',
+  orderApiUrl: 'https://payment.seaverse.com',
+  walletApiUrl: 'https://wallet.seaverse.com',
+  cssUrl: 'https://payment-static.seaverse.com/sdk/seaart-payment-component.css',
+}
+```
 
-// 3. 创建订单支付实例
-const orderPayment = sdk.createOrderPayment({
-  orderId: 'order-123',
-  accountToken: 'user-token',
-});
+### PaymentSDKConfig Interface
 
-// 4a. 跳转支付（Link Payment）
-const linkMethod = methods.find(m => m.payment_type === 1);
-const linkPayment = orderPayment.createLinkPayment(linkMethod, {
-  callback_url: `${window.location.origin}/payment-callback`,
-});
-await linkPayment.redirectToPayment();
-
-// 4b. 嵌入式支付（Dropin Payment）
-const dropinMethod = methods.find(m => m.payment_type === 2);
-const dropinPayment = orderPayment.createDropinPayment(dropinMethod, {
-  containerId: '#payment-container',
-  onCompleted: (payload) => {
-    console.log('支付成功：', payload);
-  },
-  onFailed: (payload) => {
-    console.error('支付失败：', payload);
-  },
-});
-await dropinPayment.render();
-
-// 5. 处理支付回调（回调页面）
-const result = await sdk.handleCallback(
-  { type: 'subscription' },
-  'https://payment-api.com',
-  'auth-token'
-);
-if (result.success) {
-  console.log('支付验证成功：', result.data);
+```typescript
+interface PaymentSDKConfig {
+  // Required
+  environment: 'development' | 'production';
+  accountToken: string;
+
+  // Optional (with sensible defaults)
+  businessType?: 1 | 2;       // 1 = one-time, 2 = subscription
+  scriptTimeout?: number;     // Default: 10000ms
+  paymentMethodType?: string; // Default: 'dropin'
+
+  // Advanced overrides
+  scriptUrl?: string;         // Override environment config
+  clientId?: string;          // Override environment config
+  orderApiUrl?: string;       // Override environment config
+  cssUrl?: string;            // Override environment config
 }
 ```
 
 ---
 
-### DropinPaymentModal - Dropin 支付弹框（带挽留功能）
-
-**适用场景**：
-- ✅ 需要弹框形式的 Dropin 支付（无需自己创建弹框容器）
-- ✅ 支持用户取消支付时的挽留弹框（可选）
-- ✅ 自动处理弹框打开/关闭/清理逻辑
+## 🔍 Advanced Features
 
-#### 基础用法
+### Credit Query
 
 ```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);
+import { getCreditDetail } from '@seaverse/payment-sdk';
 
-// 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);
-    },
-  }
-);
+const apiHost = 'https://wallet.seaverse.com';
+const token = 'user-token';
 
-// 6. 打开弹框
-await modal.open();
+const detail = await getCreditDetail(apiHost, token);
 
-// 可选：手动关闭弹框
-// modal.close();
+console.log('Total balance:', detail.total_balance);
+console.log('Tier:', detail.tier);
 
-// 可选：检查弹框状态
-// console.log('弹框是否打开：', modal.isOpen());
+detail.pools.forEach(pool => {
+  console.log(`${pool.type} pool: ${pool.balance} credits`);
+});
 ```
 
-#### 挽留弹框流程说明
+#### Credit Pool System
 
-当用户尝试取消支付时（点击关闭按钮或 ESC 键），会触发以下流程：
+| Pool Type | Description | Expiration |
+|-----------|-------------|------------|
+| `daily` | Daily credits | Next day 00:00 UTC |
+| `event` | Event credits | Event end date |
+| `monthly` | Monthly credits | 30 days after grant |
+| `permanent` | Permanent credits | Never expires |
 
-1. **关闭支付弹框** → 支付弹框关闭
-2. **显示挽留弹框** → 自动弹出挽留弹框，展示：
-   - 订单详情（商品名称、购买数量、优惠价格）
-   - 倒计时提示（15分钟订单过期时间）
-   - 活动赠送（如果有）
-3. **用户选择**：
-   - **继续支付**：关闭挽留弹框 → 重新打开支付弹框
-   - **确认取消**：关闭所有弹框 → 清理资源
+**Consumption Priority**: Daily → Event → Monthly → Permanent
 
-#### 配置选项
+### Subscription Management
 
 ```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→¥ 等）
-- 两个按钮：「取消」和「继续支付」（使用与积分弹框一致的绿色渐变主题色）
+import {
+  getCurrentSubscription,
+  getActiveSubscription,
+  changeSubscription,
+} from '@seaverse/payment-sdk';
 
-**支持的货币符号**：
-- 美元 (USD) → $
-- 欧元 (EUR) → €
-- 英镑 (GBP) → £
-- 日元 (JPY) / 人民币 (CNY) → ¥
-- 新加坡元 (SGD) → S$
-- 港币 (HKD) → HK$
-- 等 30+ 种货币符号...
+const apiUrl = 'https://payment.seaverse.com';
+const token = 'user-token';
 
-#### 禁用挽留弹框
+// Query current subscription status
+const current = await getCurrentSubscription(apiUrl, token);
+console.log('Status:', current.subscription_status);
 
-如果不需要挽留功能，可以禁用：
+// Get active subscription details
+const active = await getActiveSubscription(apiUrl, token);
+console.log('Plan:', active.product_name);
 
-```typescript
-const modal = new DropinPaymentModal(
-  orderPayment,
-  'order-123',
-  'user-token',
-  dropinMethod,
-  {
-    enableRetention: false,  // 禁用挽留弹框
-    onCompleted: (payload) => {
-      console.log('支付成功！', payload);
-    },
-  }
-);
+// Upgrade/downgrade subscription
+const result = await changeSubscription(apiUrl, token, {
+  productId: 'pro_plan',
+  billingPeriod: 'year',
+  redirectUrl: window.location.href,
+});
 ```
 
----
+### Order Status Tracking
 
-## ⚙️ 配置选项
+```typescript
+import { checkOrderStatus, pollOrderStatus } from '@seaverse/payment-sdk';
 
-### 环境配置（Environment）
+const apiUrl = 'https://payment.seaverse.com';
+const token = 'user-token';
+const transactionId = 'txn_123';
 
-| 环境     | 值              | 说明         |
-| -------- | --------------- | ------------ |
-| 开发环境 | `'development'` | 开发测试环境 |
-| 生产环境 | `'production'`  | 正式生产环境 |
+// Single status check
+const status = await checkOrderStatus(transactionId, apiUrl, token);
+console.log('Order status:', status.order_status);
 
-### SDK 配置（sdkConfig）
+// Poll until final status
+const finalStatus = await pollOrderStatus(transactionId, apiUrl, token, {
+  interval: 2000,      // Poll interval (ms)
+  maxAttempts: 30,     // Max attempts
+  onPoll: (status, attempt) => {
+    console.log(`Attempt ${attempt}: ${status}`);
+  },
+});
 
-```typescript
-interface PaymentSDKConfig {
-  // 必填参数
-  environment: 'development' | 'production';  // 环境变量
-  countryCode: string;                        // 国家代码（ISO 3166-1）
-
-  // 可选参数
-  accountToken?: string;      // 用户认证令牌
-  businessType?: 1 | 2;       // 1=一次性购买, 2=订阅（默认 1）
-
-  // 高级选项（覆盖环境配置）
-  scriptUrl?: string;         // 自定义脚本 URL
-  clientId?: string;          // 自定义客户端 ID
-  orderApiUrl?: string;       // 自定义订单 API 地址
-  cssUrl?: string;            // 自定义 CSS URL
-  scriptTimeout?: number;     // 脚本加载超时（默认 10000ms）
-  paymentMethodType?: string; // 支付方式类型过滤（默认 'dropin'）
-}
+console.log('Final status:', finalStatus.order_status);
 ```
 
 ---
 
-## 🎨 UI 反馈工具
+## 🎨 UI Feedback Utilities
 
-SDK 提供统一的 UI 反馈工具，替代浏览器原生 `alert()`：
+SDK provides unified UI feedback tools (replacement for browser `alert()`):
 
 ```typescript
 import {
@@ -812,46 +688,44 @@ import {
   hideLoadingIndicator,
 } from '@seaverse/payment-sdk';
 
-// 错误提示（红色渐变背景）
-showErrorMessage('支付失败，请重试', 3000);
+// Error message (red gradient)
+showErrorMessage('Payment failed, please try again', 3000);
 
-// 成功提示（绿色渐变背景）
-showSuccessMessage('支付成功！', 3000);
+// Success message (green gradient)
+showSuccessMessage('Payment successful!', 3000);
 
-// 信息提示（蓝色渐变背景）
-showInfoMessage('正在处理您的请求...', 3000);
+// Info message (blue gradient)
+showInfoMessage('Processing your request...', 3000);
 
-// 加载指示器
-const loader = showLoadingIndicator('初始化支付系统...');
-// ... 异步操作
+// Loading indicator
+const loader = showLoadingIndicator('Initializing payment system...');
+// ... async operation
 hideLoadingIndicator(loader);
 ```
 
-**特性**：
-- ✅ 精美渐变背景 + 图标
-- ✅ 自动淡入淡出动画
-- ✅ 自动移除（可配置时长）
-- ✅ 防止重复显示
-- ✅ XSS 防护
+**Features**:
+- ✅ Beautiful gradient backgrounds + icons
+- ✅ Auto fade in/out animations
+- ✅ Auto removal (configurable duration)
+- ✅ Prevent duplicate display
+- ✅ XSS protection
 
 ---
 
-## 🛡️ 错误处理
+## 🛡️ Error Handling
 
-### 业务错误码（BIZ_CODE）
+### Common Error Codes
 
-| 错误码 | 常量                   | 说明         |
-| ------ | ---------------------- | ------------ |
-| `0`    | `SUCCESS`              | 操作成功     |
-| `400`  | `BAD_REQUEST`          | 请求参数错误 |
-| `401`  | `UNAUTHORIZED`         | 未授权       |
-| `500`  | `SERVER_ERROR`         | 服务器错误   |
-| `4001` | `DAILY_LIMIT_EXCEEDED` | 超过每日限额 |
-| `4002` | `PRODUCT_NOT_FOUND`    | 产品不存在   |
-| `4004` | `INSUFFICIENT_BALANCE` | 余额不足     |
-| `4005` | `ORDER_NOT_FOUND`      | 订单不存在   |
+| Code | Constant | Description |
+|------|----------|-------------|
+| `0` | `SUCCESS` | Success |
+| `400` | `BAD_REQUEST` | Invalid parameters |
+| `401` | `UNAUTHORIZED` | Unauthorized |
+| `500` | `SERVER_ERROR` | Server error |
+| `4001` | `DAILY_LIMIT_EXCEEDED` | Daily limit exceeded |
+| `4002` | `PRODUCT_NOT_FOUND` | Product not found |
 
-### 错误处理示例
+### Error Handling Example
 
 ```typescript
 const modal = new GenericPackageModal({
@@ -859,13 +733,12 @@ const modal = new GenericPackageModal({
   sdkConfig: { /* ... */ },
 
   onPaymentFailed: (error, pkg) => {
-    // 处理限额错误
-    if (error.message.includes('Daily limit')) {
-      showErrorMessage(`您已达到 ${pkg.name} 的每日购买限额`);
-    } else if (error.message.includes('Lifetime limit')) {
-      showErrorMessage('此套餐仅限购买一次，您已购买过');
+    if (error.message.includes('limit')) {
+      showErrorMessage(`Daily limit reached for ${pkg.name}`);
+    } else if (error.message.includes('payment')) {
+      showErrorMessage('Payment processing failed');
     } else {
-      showErrorMessage(`支付失败：${error.message}`);
+      showErrorMessage(`Error: ${error.message}`);
     }
   },
 });
@@ -873,64 +746,22 @@ const modal = new GenericPackageModal({
 
 ---
 
-## 🧪 测试卡号（开发环境）
-
-在开发环境测试支付功能：
-
-| 字段     | 值                 |
-| -------- | ------------------ |
-| 卡号     | `4212345678910006` |
-| 有效期   | `03/30`            |
-| CVC      | `737`              |
-| 3DS 密码 | `password`         |
-
----
-
-## 📊 API 对比表
-
-### CreditPackageModal vs GenericPackageModal
-
-| 特性           | CreditPackageModal | GenericPackageModal               |
-| -------------- | ------------------ | --------------------------------- |
-| **套餐数据**   | 内置预设套餐       | 外部配置（灵活）                  |
-| **套餐类型**   | 标准积分套餐       | 任意类型（破冰/告急/首充/自定义） |
-| **购买限制**   | 无                 | 支持每日/终身限购                 |
-| **奖励展示**   | 无                 | 支持奖励百分比                    |
-| **配置复杂度** | ⭐️ 简单             | ⭐️⭐️ 中等                           |
-| **使用场景**   | 标准积分购买       | 特殊促销、限时活动                |
-
-**选择建议**：
-- 🎯 **标准积分购买** → 使用 `CreditPackageModal`（推荐新手）
-- 🎁 **特殊促销活动** → 使用 `GenericPackageModal`
-
----
-
-## 🔄 迁移指南
-
-### 从 v0.8.x 迁移到 v0.9.x
+## 🧪 Testing
 
-**主要变化**：引入环境配置，简化参数
+### Test Card Numbers (Development Only)
 
-```typescript
-// ✅ 新版本（v0.8.x）
-const modal = new GenericPackageModal({
-  packages: packages,
-  sdkConfig: {
-    environment: 'development',  // 只需指定环境
-    countryCode: 'SG',           // 扁平化参数
-    businessType: 1,             // 可选，默认 1
-  },
-});
-```
+For testing payment functionality in development environment:
 
-**参数变化**：
-- ✅ 新增：`environment` - 自动配置所有 URL
-- ✅ 简化：`countryCode` - 从 `paymentMethodsParams.country_code` 扁平化
-- ✅ 简化：`businessType` - 从 `paymentMethodsParams.business_type` 扁平化
+| Field | Value |
+|-------|-------|
+| Card Number | `4212345678910006` |
+| Expiry | `03/30` |
+| CVC | `737` |
+| 3DS Password | `password` |
 
 ---
 
-## 🌐 框架集成
+## 🌐 Framework Integration
 
 ### Vue 3
 
@@ -939,16 +770,18 @@ const modal = new GenericPackageModal({
 import { ref } from 'vue';
 import { CreditPackageModal } from '@seaverse/payment-sdk';
 
-const showModal = () => {
+const userToken = ref('user-token-here');
+
+const openPaymentModal = () => {
   const modal = new CreditPackageModal({
+    language: 'en',
     sdkConfig: {
       environment: import.meta.env.DEV ? 'development' : 'production',
-      countryCode: 'SG',
       accountToken: userToken.value,
     },
-    onPaymentSuccess: (orderId, transactionId) => {
-      console.log('支付成功', { orderId, transactionId });
-      // 刷新用户数据
+    onPaymentSuccess: (orderId, transactionId, pkg) => {
+      console.log('Payment successful', { orderId, transactionId });
+      // Refresh user data
     },
   });
   modal.open();
@@ -956,7 +789,7 @@ const showModal = () => {
 </script>
 
 <template>
-  <button @click="showModal">购买积分</button>
+  <button @click="openPaymentModal">Purchase Credits</button>
 </template>
 ```
 
@@ -968,101 +801,170 @@ import { CreditPackageModal } from '@seaverse/payment-sdk';
 function PurchaseButton() {
   const handlePurchase = () => {
     const modal = new CreditPackageModal({
+      language: 'en',
       sdkConfig: {
         environment: process.env.NODE_ENV === 'development' ? 'development' : 'production',
-        countryCode: 'SG',
         accountToken: getUserToken(),
       },
-      onPaymentSuccess: (orderId, transactionId) => {
-        console.log('支付成功', { orderId, transactionId });
-        // 刷新用户数据
+      onPaymentSuccess: (orderId, transactionId, pkg) => {
+        console.log('Payment successful', { orderId, transactionId });
+        // Refresh user data
       },
     });
     modal.open();
   };
 
-  return <button onClick={handlePurchase}>购买积分</button>;
+  return <button onClick={handlePurchase}>Purchase Credits</button>;
 }
 ```
 
+### Svelte
+
+```svelte
+<script lang="ts">
+  import { CreditPackageModal } from '@seaverse/payment-sdk';
+
+  let userToken = 'user-token-here';
+
+  function openPaymentModal() {
+    const modal = new CreditPackageModal({
+      language: 'en',
+      sdkConfig: {
+        environment: 'development',
+        accountToken: userToken,
+      },
+      onPaymentSuccess: (orderId, transactionId, pkg) => {
+        console.log('Payment successful', { orderId, transactionId });
+      },
+    });
+    modal.open();
+  }
+</script>
+
+<button on:click={openPaymentModal}>Purchase Credits</button>
+```
+
 ---
 
-## 📝 TypeScript 支持
+## 📝 TypeScript Support
 
-SDK 包含完整的 TypeScript 类型定义：
+Full TypeScript type definitions included:
 
 ```typescript
 import type {
-  // Modal 相关
+  // Modal types
   CreditPackageModalOptions,
   GenericPackageModalOptions,
   GenericPackage,
-  PurchaseSuccessData,
+  CreditPackageItem,
 
-  // 配置相关
+  // Configuration types
   PaymentSDKConfig,
   Environment,
   EnvironmentConfig,
+  LocaleCode,
+  CountryCode,
 
-  // 积分相关
-  CreditDetailResponse,
-  CreditTransaction,
-  CreditPoolType,
+  // Payment types
+  Product,
+  ProductType,
+  AutoCreateOrderConfig,
+  PaymentMethod,
+  BindCard,
 
-  // 订阅相关
+  // Response types
+  OrderStatusResponse,
+  CreditDetailResponse,
   CurrentSubscription,
   ActiveSubscription,
-
-  // 订单相关
-  OrderStatus,
-  OrderStatusResponse,
 } from '@seaverse/payment-sdk';
 ```
 
 ---
 
-## 🔗 相关链接
+## 📊 Comparison Table
 
-- 📦 [NPM Package](https://www.npmjs.com/package/@seaverse/payment-sdk)
-- 🐙 [GitHub Repository](https://github.com/SeaVerseAI/sv-sdk)
-- 📖 [API Documentation](https://github.com/SeaVerseAI/sv-sdk/tree/main/packages/payment-sdk)
-- 🐛 [Issue Tracker](https://github.com/SeaVerseAI/sv-sdk/issues)
+### CreditPackageModal vs GenericPackageModal vs PaymentCheckoutModal
+
+| Feature | CreditPackageModal | GenericPackageModal | PaymentCheckoutModal |
+|---------|-------------------|---------------------|---------------------|
+| **Package Data** | API-fetched | User-provided | User-provided product |
+| **Package Type** | Dynamic credit packs | Custom (promo/special) | Any product type |
+| **Complexity** | ⭐️ Simple | ⭐️⭐️ Medium | ⭐️⭐️⭐️ Advanced |
+| **Use Case** | Standard purchases | Promotions/offers | Full checkout control |
+| **Customization** | Limited | Medium | Full control |
+| **SDK Initialization** | Auto (via PaymentCheckoutModal) | Auto (via PaymentCheckoutModal) | Auto |
+| **Payment Methods** | All supported | All supported | All supported |
+
+**Selection Guide**:
+- 🎯 **Standard credit purchases** → Use `CreditPackageModal` (recommended for beginners)
+- 🎁 **Special promotions** → Use `GenericPackageModal`
+- 🔧 **Advanced custom flows** → Use `PaymentCheckoutModal`
 
 ---
 
-## 📄 许可证
+## 📄 Changelog
 
-MIT License
+### v0.9.0 (2026-02-07) - Critical Bug Fixes
+
+**🔧 Critical Fixes**:
+- Fixed SDK initialization failure when only Link payment methods available
+  - Issue: `BasePackageModal.initializeSDK()` required Dropin payment (payment_type === 2)
+  - Solution: Override `initializeSDK()` in CreditPackageModal and GenericPackageModal
+  - Now PaymentCheckoutModal handles all SDK initialization independently
+
+- Fixed Link payment auto-execution issue
+  - Issue: `autoSelectDefaultPaymentMethod()` auto-executed Link payment, causing instant redirect
+  - Solution: Refined strategy - only auto-select when Dropin exists; wait for manual selection when only Link available
+  - Improved UX: Users now see checkout modal before any payment action
+
+**🎨 UI/UX Improvements**:
+- Increased payment method card spacing from 8px to 14px
+- Better visual breathing room and click targets
+- Consistent spacing in both skeleton and main UI
+
+**📁 Files Changed** (5 files, +86 -53 lines):
+- `CreditPackageModal.ts`: Added `initializeSDK()` and `waitForSDKInitialization()` overrides
+- `GenericPackageModal.ts`: Added `initializeSDK()` and `waitForSDKInitialization()` overrides
+- `PaymentCheckoutModal.ts`: Refined `autoSelectDefaultPaymentMethod()` logic (lines 485-517)
+- `PaymentUIRenderer.ts`: Updated card gap from 8px to 14px (lines 207, 276)
+- `index.ts`: Version bump
+
+### v0.8.2 (2026-02-02) - Architecture Refactoring
+
+**🏗️ Architecture**:
+- Created `BasePackageModal` abstract base class
+- Eliminated ~400 lines of duplicate code between CreditPackageModal and GenericPackageModal
+- Improved type safety with TypeScript generics
+- 100% backward compatible - no breaking changes
+
+**📦 Package Size**:
+- CreditPackageModal: 1042 lines → 515 lines (50% reduction)
+- GenericPackageModal: 752 lines → 340 lines (55% reduction)
+- Total code reduction: ~25%
 
 ---
 
-## 🤝 贡献
+## 🔗 Links
 
-欢迎提交 Issue 和 Pull Request！
+- 📦 [NPM Package](https://www.npmjs.com/package/@seaverse/payment-sdk)
+- 🐙 [GitHub Repository](https://github.com/SeaVerseAI/sv-sdk)
+- 📖 [API Documentation](https://github.com/SeaVerseAI/sv-sdk/tree/main/packages/payment-sdk)
+- 🐛 [Issue Tracker](https://github.com/SeaVerseAI/sv-sdk/issues)
 
 ---
 
-**更新日期**: 2026-02-02
-**SDK 版本**: v0.8.2
+## 📄 License
 
-## 📝 更新日志
+MIT License
+
+---
 
-### v0.8.2 (2026-02-02)
+## 🤝 Contributing
 
-**架构重构**：
-- 🏗️ 创建 `BasePackageModal` 抽象基类，消除 `CreditPackageModal` 和 `GenericPackageModal` 之间的重复代码
-- 📉 减少约 400 行重复代码（25% 代码量减少）
-- 🎯 `CreditPackageModal`: 从 1042 行减少到 515 行
-- 🎯 `GenericPackageModal`: 从 752 行减少到 340 行
-- ✅ 完全向后兼容，现有代码无需修改
-- 🔒 通过 TypeScript 泛型确保类型安全
+Issues and Pull Requests are welcome!
 
-**类型系统改进**：
-- 新增 `BasePackage` 接口 - 所有套餐类型的基础接口
-- 新增 `BasePackageModalOptions<TPackage>` 接口 - 通用配置接口
-- `CreditPackage` 和 `GenericPackage` 现在继承自 `BasePackage`
+---
 
-**开发体验提升**：
-- 更容易添加新的套餐类型（只需继承 `BasePackageModal`）
-- 修复 bug 只需在基类中修改一处
-- 更清晰的职责分离（基类处理逻辑，子类处理 UI）
+**Last Updated**: 2026-02-07
+**SDK Version**: 0.9.0