@seaverse/payment-sdk 0.7.0 → 0.8.0

package/README.md

@@ -1,408 +1,842 @@
 # @seaverse/payment-sdk
 
-SeaVerse Payment SDK - Credit management and payment checkout for SeaVerse applications.
+SeaVerse Payment SDK - 一站式支付解决方案，提供积分管理、支付弹窗、订阅管理和订单跟踪功能。
 
-## Features
+> **最新版本**: v0.8.0 | **文档语言**: 中文优先（包含英文说明）
 
-- **Credit Query** - Query user credit balance, pool details, and transaction history
-- **Payment Checkout** - Show payment modal for one-time purchases and subscriptions
-- **Multi-tenant Support** - Isolated credit accounts per application
-- **TypeScript** - Full type definitions included
-- **Web Component** - Uses `@seaart/payment-component` for payment UI
-
-## Installation
+## 📦 安装
 
 ```bash
 npm install @seaverse/payment-sdk
-# or
+# 或
 pnpm add @seaverse/payment-sdk
 ```
 
-> **Note**: `@seaart/payment-component` is bundled into the SDK, no need to install it separately.
-
-## Quick Start
+## 🚀 快速开始
 
-### Credit Query
+### 1. 积分套餐购买弹窗（推荐使用）
 
-Query user credit accounts and transaction history:
+最简单的集成方式 - 3 行代码完成支付流程：
 
 ```typescript
-import { PaymentClient } from '@seaverse/payment-sdk';
-
-const client = new PaymentClient({
-  appId: 'seaverse',
-  token: 'your-bearer-token',
+import { CreditPackageModal } from '@seaverse/payment-sdk';
+
+// 创建弹窗
+const modal = new CreditPackageModal({
+  sdkConfig: {
+    environment: 'development',     // 环境：'development' | 'production'
+    countryCode: 'SG',              // 国家代码
+    accountToken: 'user-token',     // 用户认证令牌（可选）
+  },
+  onPaymentSuccess: (orderId, transactionId) => {
+    console.log('支付成功！', { orderId, transactionId });
+  },
 });
 
-// Get credit detail with 4-pool breakdown
-const detail = await client.getCreditDetail();
-console.log(`Total Balance: ${detail.total_balance}`);
+// 打开弹窗
+modal.open();
+```
 
-detail.pools.forEach(pool => {
-  console.log(`${pool.type}: ${pool.balance}`);
+**效果**：
+- ✅ 自动展示预设积分套餐（120/240/520/1200 积分）
+- ✅ 自动初始化支付 SDK
+- ✅ 自动创建订单
+- ✅ 显示购买成功弹窗（带动画效果）
+- ✅ 自动刷新积分余额
+
+### 2. 通用套餐弹窗（自定义套餐）
+
+适用于特殊促销、破冰包、首充包等场景：
+
+```typescript
+import { GenericPackageModal, type GenericPackage } from '@seaverse/payment-sdk';
+
+// 定义自定义套餐
+const packages: GenericPackage[] = [
+  {
+    id: 'pkg_value',
+    name: 'Ice Breaker Pack',
+    price: '0.49',
+    currency: 'USD',
+    credits: '120',
+    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',
+  },
+];
+
+// 创建弹窗
+const modal = new GenericPackageModal({
+  packages: packages,
+  sdkConfig: {
+    environment: 'development',
+    countryCode: 'SG',
+    accountToken: 'user-token',
+  },
+  onPaymentSuccess: (orderId, transactionId, pkg) => {
+    console.log(`${pkg.name} 购买成功！`, orderId);
+  },
+  onPaymentFailed: (error, pkg) => {
+    if (error.message.includes('limit')) {
+      alert(`${pkg.name} 已达购买限额`);
+    }
+  },
 });
 
-// List transactions
-const transactions = await client.listTransactions({ page_size: 10 });
+modal.open();
 ```
 
-### Payment Checkout
+## 📖 核心功能模块
+
+### ⭐️ 推荐功能（新用户优先使用）
+
+| 功能               | 组件                   | 使用场景               | 文档                                            |
+| ------------------ | ---------------------- | ---------------------- | ----------------------------------------------- |
+| **积分套餐购买**   | `CreditPackageModal`   | 标准积分购买（最简单） | [👉 查看](#creditpackagemodal---标准积分购买)    |
+| **自定义套餐购买** | `GenericPackageModal`  | 促销活动、特殊套餐     | [👉 查看](#genericpackagemodal---自定义套餐购买) |
+| **购买成功弹窗**   | `PurchaseSuccessModal` | 自动集成，无需手动调用 | [👉 查看](#purchasesuccessmodal---购买成功弹窗)  |
+
+### 🔧 高级功能（进阶用户）
+
+| 功能                  | API                                            | 使用场景                   |
+| --------------------- | ---------------------------------------------- | -------------------------- |
+| **积分查询**          | `PaymentClient`                                | 查询用户积分余额、交易记录 |
+| **订阅管理**          | `getCurrentSubscription`, `changeSubscription` | 订阅状态查询、升级/降级    |
+| **订单管理**          | `checkOrderStatus`, `pollOrderStatus`          | 订单状态查询、轮询         |
+| **SeaartPayment SDK** | `SeaartPaymentSDK`                             | 完全自定义支付流程         |
+
+---
+
+## 📚 详细使用文档
 
-Show payment modal for purchases:
+### CreditPackageModal - 标准积分购买
+
+**适用场景**：
+- ✅ 标准积分套餐购买（120/240/520/1200 积分）
+- ✅ 展示创作力量类型（文生图、图生图等）
+- ✅ 最简单的集成方式
+
+#### 基础用法
 
 ```typescript
-import { PaymentCheckoutClient } from '@seaverse/payment-sdk';
-// Import the Web Component styles
-import '@seaverse/payment-sdk/style.css';
-
-const checkoutClient = new PaymentCheckoutClient({
-  apiHost: 'https://payment.sg.seaverse.dev',
-  authToken: 'your-jwt-token',
-  environment: 'development', // or 'production'
-  debug: true,
+import { CreditPackageModal } from '@seaverse/payment-sdk';
+
+const modal = new CreditPackageModal({
+  // 语言设置（可选，默认 'en'）
+  language: 'zh-CN',  // 'en' | 'zh-CN'
+
+  // SDK 配置（必填）
+  sdkConfig: {
+    environment: 'development',  // 'development' | 'production'
+    countryCode: 'SG',           // ISO 3166-1 国家代码
+    accountToken: 'user-token',  // 用户认证令牌（可选）
+    businessType: 1,             // 1=一次性购买, 2=订阅（可选，默认1）
+  },
+
+  // 回调函数
+  onPaymentSuccess: (orderId: string, transactionId: string) => {
+    console.log('支付成功！', { orderId, transactionId });
+    // 刷新用户积分、更新 UI 等
+  },
+
+  onPaymentFailed: (error: Error) => {
+    console.error('支付失败：', error.message);
+    // 显示错误提示
+  },
+
+  onClose: () => {
+    console.log('弹窗关闭');
+  },
 });
 
-// Initialize (loads Web Component)
-await checkoutClient.init();
+// 打开弹窗
+modal.open();
 
-// One-time purchase
-await checkoutClient.checkout({
-  productId: 'pkg_starter', // Required
-  onSuccess: (res) => console.log('Payment success:', res),
-  onError: (err) => console.error('Payment failed:', err),
-});
+// 关闭弹窗（可选）
+modal.close();
 
-// Subscription
-await checkoutClient.subscribe({
-  productId: 'pro', // Required
-  billing_period: 'month', // Optional: 'month' | 'year' (default: 'month')
-  onSuccess: (res) => console.log('Subscription success:', res),
-});
+// 检查弹窗状态
+console.log('弹窗是否打开：', modal.isOpen());
 ```
 
-## API Reference
+#### 预设积分套餐
 
-### PaymentClient (Credit Query)
+SDK 内置以下积分套餐：
 
-| Method | Description |
-|--------|-------------|
-| `getCreditDetail()` | Get credit balance with 4-pool breakdown |
-| `getCreditAccount()` | Get credit account information (deprecated) |
-| `listTransactions(request)` | List credit transactions with filters |
-| `setToken(token)` | Update bearer token |
-| `setBaseURL(baseURL)` | Update API base URL |
-| `setAppId(appId)` | Update application ID |
+| 套餐    | 积分 | 价格  | 说明     |
+| ------- | ---- | ----- | -------- |
+| Starter | 120  | $0.49 | 入门套餐 |
+| Value   | 240  | $0.99 | 超值套餐 |
+| Pro     | 520  | $1.99 | 专业套餐 |
+| Ultra   | 1200 | $4.99 | 旗舰套餐 |
 
-### PaymentCheckoutClient (Payment Modal)
+#### 环境配置
 
-| Method | Description |
-|--------|-------------|
-| `init()` | Initialize and load Web Component |
-| `checkout(options)` | One-time purchase with payment modal |
-| `subscribe(options)` | Subscription purchase with payment modal |
-| `showPayment(options)` | Show payment modal with existing transactionId |
-| `close()` | Close payment modal |
-| `getStatus()` | Get client status |
-| `isReady()` | Check if client is initialized |
+SDK 根据 `environment` 自动配置以下参数：
 
-## Credit Pool Types
+**开发环境 (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',
+}
+```
 
-The 4-pool credit system:
+**生产环境 (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',
+}
+```
 
-| Pool | Description | Expiration |
-|------|-------------|------------|
-| `daily` | Daily credits | Next day 00:00 UTC |
-| `event` | Event credits | Event deadline |
-| `monthly` | Monthly credits | 30 days after grant |
-| `permanent` | Permanent credits | Never |
+#### 高级配置（可选）
 
-**Consumption Priority:** Daily → Event → Monthly → Permanent
+如需覆盖环境配置：
 
-## Configuration
+```typescript
+const modal = new CreditPackageModal({
+  sdkConfig: {
+    environment: 'production',
+    countryCode: 'US',
+
+    // 覆盖默认配置
+    scriptUrl: 'https://custom-cdn.com/payment.js',
+    clientId: 'custom-client-id',
+    orderApiUrl: 'https://custom-api.com',
+  },
+});
+```
+
+---
+
+### GenericPackageModal - 自定义套餐购买
 
-### PaymentClient Options
+**适用场景**：
+- ✅ 特殊促销套餐（破冰包、告急包、首充包）
+- ✅ 限时优惠活动
+- ✅ 自定义套餐数据和样式
+
+#### 基础用法
 
 ```typescript
-interface PaymentClientOptions {
-  appId: string;      // Application ID for multi-tenant isolation
-  token: string;      // Bearer token for authentication
-  baseURL?: string;   // API base URL (default: 'https://payment.sg.seaverse.dev')
-  timeout?: number;   // Request timeout in ms (default: 30000)
-}
+import { GenericPackageModal, type GenericPackage } from '@seaverse/payment-sdk';
+
+// 定义套餐数据
+const packages: GenericPackage[] = [
+  {
+    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,
+    package_type: 'iceBreaker',
+  },
+];
+
+// 创建弹窗
+const modal = new GenericPackageModal({
+  language: 'zh-CN',
+  packages: packages,
+
+  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);
+  },
+});
+
+modal.open();
 ```
 
-### PaymentCheckoutClient Options
+#### GenericPackage 接口定义
 
 ```typescript
-interface CheckoutClientConfig {
-  apiHost: string;                    // Payment gateway API URL
-  authToken?: string;                 // Static JWT token
-  getAuthToken?: () => string;        // Dynamic token getter
-  environment?: 'development' | 'production';  // Environment
-  debug?: boolean;                    // Debug mode
-  componentTimeout?: number;          // Web Component load timeout in ms
+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 = 无限制）
+
+  // 分类标识（可选）
+  package_type?: 'iceBreaker' | 'emergency' | 'firstCharge' | 'custom';
 }
 ```
 
-### Checkout Options
+#### 预定义套餐示例
+
+SDK 提供以下预定义套餐供参考：
 
 ```typescript
-interface CheckoutOptions {
-  productId: string;            // Product ID (required)
-  language?: string;            // Language setting
-  userName?: string;            // User name for display
-  redirectUrl?: string;         // Redirect URL after payment
-  onSuccess?: (result: PaymentResult) => void;        // Success callback
-  onError?: (error: CheckoutPaymentError) => void;    // Error callback
-  onClose?: () => void;         // Close callback
-}
+import {
+  EXAMPLE_ICE_BREAKER,    // 破冰包
+  EXAMPLE_EMERGENCY,      // 告急包
+  EXAMPLE_FIRST_CHARGE,   // 首充包
+  EXAMPLE_PACKAGES,       // 所有示例套餐数组
+} from '@seaverse/payment-sdk';
+
+// 使用预定义套餐
+const modal = new GenericPackageModal({
+  packages: [EXAMPLE_ICE_BREAKER, EXAMPLE_EMERGENCY],
+  sdkConfig: { /* ... */ },
+});
 ```
 
-### Subscription Options
+**预定义套餐详情**：
 
-```typescript
-interface SubscribeOptions extends CheckoutOptions {
-  billing_period?: 'month' | 'year';  // Optional: billing period (default: 'month')
-}
+| 套餐                   | 价格  | 积分 | 限制    | 说明                     |
+| ---------------------- | ----- | ---- | ------- | ------------------------ |
+| `EXAMPLE_ICE_BREAKER`  | $0.49 | 120  | 每日1次 | 破冰包 - 超低价首次破冰  |
+| `EXAMPLE_EMERGENCY`    | $0.99 | 240  | 每日3次 | 告急包 - 日常转化主力    |
+| `EXAMPLE_FIRST_CHARGE` | $1.99 | 620  | 终身1次 | 首充包 - 提升首充用户LTV |
+
+---
+
+### PurchaseSuccessModal - 购买成功弹窗
+
+**✨ 自动集成** - 无需手动调用，在 `CreditPackageModal` 和 `GenericPackageModal` 支付成功后自动显示。
+
+#### 功能特性
+
+- ✅ 邮件确认卡片风格设计
+- ✅ 精美动画效果（淡入淡出、缩放、顺序动画）
+- ✅ 显示购买详情（套餐名称、积分数、支付金额）
+- ✅ 支持 ESC 键、点击遮罩、关闭按钮关闭
+- ✅ 自动阻止 body 滚动
+- ✅ 支持中英文切换
+
+#### 自动触发流程
+
+```
+用户点击购买按钮
+  ↓
+支付成功
+  ↓
+CreditPackageModal/GenericPackageModal 关闭
+  ↓
+PurchaseSuccessModal 自动显示（带动画）
+  ↓
+用户关闭成功弹窗
+  ↓
+自动刷新积分余额
+  ↓
+触发 onPaymentSuccess 回调
 ```
 
-### Environment Configuration
+#### 手动使用（可选）
 
-| Environment | API Host |
-|-------------|----------|
-| `development` | `https://aiart-openresty.dev.seaart.dev` |
-| `production` | `https://www.seaart.ai` |
+如需在其他场景手动调用：
 
-## Styling and CSS
+```typescript
+import { PurchaseSuccessModal } from '@seaverse/payment-sdk';
+
+const successModal = new PurchaseSuccessModal({
+  data: {
+    packName: 'Ice Breaker Pack',
+    credits: 120,
+    amount: '0.49',
+    currency: '$',
+    orderId: 'order_123',
+    transactionId: 'txn_456',
+  },
+  language: 'zh-CN',
+  onClose: () => {
+    console.log('成功弹窗关闭');
+  },
+});
 
-### Style Isolation
+successModal.open();
+```
 
-The SDK uses the bundled `@seaart/payment-component` Web Component for the payment UI. The component's styles (30KB) are optimized for minimal global impact:
+---
 
-**✅ Well-isolated styles:**
-- 218 component-scoped selectors using Vue's `[data-v-*]` attributes
-- All component-specific styles are scoped to avoid conflicts
-- Major global resets (`*{...}`, `html,body{...}`) have been removed
+## 🔍 高级功能
 
-**⚠️ Remaining global styles (low risk):**
+### 积分查询（PaymentClient）
 
-The following global styles are included and may affect your application:
+查询用户积分余额和交易记录：
 
-```css
-/* App root container (may conflict if you use #app as root element ID) */
-#app {
-  width: 100%;
-  height: 100%;
-  background: transparent;
-}
+```typescript
+import { PaymentClient } from '@seaverse/payment-sdk';
 
-/* Custom scrollbar styling (WebKit browsers only) */
-::-webkit-scrollbar { width: 6px; height: 6px }
-::-webkit-scrollbar-track { background: transparent }
-::-webkit-scrollbar-thumb { background: #d0d0d0; border-radius: 3px }
+const client = new PaymentClient({
+  appId: 'seaverse',
+  token: 'your-bearer-token',
+  baseURL: 'https://payment.sg.seaverse.dev',  // 可选
+});
 
-/* Text selection color */
-::selection {
-  background: #6366f1;
-  color: #fff;
-}
+// 查询积分详情（4 池结构）
+const detail = await client.getCreditDetail();
+console.log('总余额：', detail.total_balance);
+
+detail.pools.forEach(pool => {
+  console.log(`${pool.type} 池：${pool.balance} 积分`);
+});
+
+// 查询交易记录
+const transactions = await client.listTransactions({
+  page: 1,
+  page_size: 20,
+  start_time: '2024-01-01T00:00:00Z',
+  end_time: '2024-12-31T23:59:59Z',
+});
+
+transactions.transactions.forEach(txn => {
+  console.log(`${txn.type}: ${txn.amount} 积分`);
+});
 ```
 
-**Risk assessment:**
-- `#app` selector: **Medium risk** - Only conflicts if your root element uses `id="app"`
-- Scrollbar styles: **Low risk** - Only affects scrollbar appearance in WebKit browsers
-- Selection color: **Low risk** - Only changes text selection highlight color
+#### 4 池积分系统
+
+| 池类型      | 说明     | 过期时间       |
+| ----------- | -------- | -------------- |
+| `daily`     | 每日积分 | 次日 00:00 UTC |
+| `event`     | 活动积分 | 活动截止日期   |
+| `monthly`   | 月度积分 | 授予后 30 天   |
+| `permanent` | 永久积分 | 永不过期       |
 
-**Recommendations:**
-1. ✅ Avoid using `id="app"` for your application's root element
-2. ✅ If you encounter conflicts, please report them as an issue
-3. ✅ Future SDK versions may provide additional isolation options if needed
+**消费优先级**：Daily → Event → Monthly → Permanent
 
-### CSS Import
+---
 
-Always import the SDK styles in your application:
+### 订阅管理
+
+查询和管理用户订阅：
 
 ```typescript
-import '@seaverse/payment-sdk/style.css';
+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',
+});
 ```
 
-**Note:** The Web Component is already bundled into the SDK, so you do **not** need to install `@seaart/payment-component` separately.
+---
 
-## Usage with Frameworks
+### 订单管理
 
-### Vue 3
+检查订单状态和轮询支付结果：
 
-```vue
-<script setup lang="ts">
-import { ref, onMounted } from 'vue';
-import { PaymentCheckoutClient } from '@seaverse/payment-sdk';
-import '@seaverse/payment-sdk/style.css';
+```typescript
+import { checkOrderStatus, pollOrderStatus } from '@seaverse/payment-sdk';
+
+const apiUrl = 'https://payment.sg.seaverse.dev';
+const token = 'user-token';
+
+// 单次查询订单状态
+const status = await checkOrderStatus('transaction_id', apiUrl, token);
+console.log('订单状态：', status.order_status);
+
+// 轮询订单状态直到最终状态
+const finalStatus = await pollOrderStatus('transaction_id', apiUrl, token, {
+  interval: 2000,      // 轮询间隔（毫秒）
+  maxAttempts: 30,     // 最大尝试次数
+  onPoll: (status, attempt) => {
+    console.log(`第 ${attempt} 次查询：${status}`);
+  },
+});
 
-const checkoutClient = ref<PaymentCheckoutClient | null>(null);
+console.log('最终状态：', finalStatus.order_status);
+```
 
-onMounted(async () => {
-  checkoutClient.value = new PaymentCheckoutClient({
-    apiHost: 'https://payment.sg.seaverse.dev',
-    authToken: 'your-token',
-    environment: import.meta.env.DEV ? 'development' : 'production',
-  });
-  await checkoutClient.value.init();
+---
+
+### SeaartPayment SDK（完全自定义）
+
+适用于需要完全控制支付流程的高级场景：
+
+```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',  // 可选
 });
 
-async function handlePurchase() {
-  await checkoutClient.value?.checkout({
-    productId: 'pkg_starter',
-    onSuccess: (res) => console.log('Success:', res),
-  });
+// 2. 获取支付方式
+const methods = await sdk.getPaymentMethods({
+  country_code: 'US',
+  business_type: 2,  // 1=一次性, 2=订阅
+});
+
+// 3. 创建订单支付实例
+const orderPayment = sdk.createOrderPayment({
+  orderId: 'order-123',
+  accountToken: 'user-token',
+});
+
+// 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);
 }
-</script>
 ```
 
-### React
+---
 
-```tsx
-import { useEffect, useRef } from 'react';
-import { PaymentCheckoutClient } from '@seaverse/payment-sdk';
-import '@seaverse/payment-sdk/style.css';
-
-function PaymentPage() {
-  const clientRef = useRef<PaymentCheckoutClient | null>(null);
-
-  useEffect(() => {
-    const init = async () => {
-      clientRef.current = new PaymentCheckoutClient({
-        apiHost: 'https://payment.sg.seaverse.dev',
-        authToken: 'your-token',
-        environment: process.env.NODE_ENV === 'development' ? 'development' : 'production',
-      });
-      await clientRef.current.init();
-    };
-    init();
-  }, []);
-
-  const handlePurchase = async () => {
-    await clientRef.current?.checkout({
-      productId: 'pkg_starter',
-      onSuccess: (res) => console.log('Success:', res),
-    });
-  };
+## ⚙️ 配置选项
+
+### 环境配置（Environment）
+
+| 环境     | 值              | 说明         |
+| -------- | --------------- | ------------ |
+| 开发环境 | `'development'` | 开发测试环境 |
+| 生产环境 | `'production'`  | 正式生产环境 |
+
+### SDK 配置（sdkConfig）
 
-  return <button onClick={handlePurchase}>Purchase</button>;
+```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'）
 }
 ```
 
-## Migration from v0.1.x
+---
+
+## 🎨 UI 反馈工具
+
+SDK 提供统一的 UI 反馈工具，替代浏览器原生 `alert()`：
 
-### Breaking Changes
+```typescript
+import {
+  showErrorMessage,
+  showSuccessMessage,
+  showInfoMessage,
+  showLoadingIndicator,
+  hideLoadingIndicator,
+} from '@seaverse/payment-sdk';
+
+// 错误提示（红色渐变背景）
+showErrorMessage('支付失败，请重试', 3000);
+
+// 成功提示（绿色渐变背景）
+showSuccessMessage('支付成功！', 3000);
+
+// 信息提示（蓝色渐变背景）
+showInfoMessage('正在处理您的请求...', 3000);
+
+// 加载指示器
+const loader = showLoadingIndicator('初始化支付系统...');
+// ... 异步操作
+hideLoadingIndicator(loader);
+```
 
-1. **Environment naming changed:**
-   - `'develop'` → `'development'`
-   - `'release'` → `'production'`
+**特性**：
+- ✅ 精美渐变背景 + 图标
+- ✅ 自动淡入淡出动画
+- ✅ 自动移除（可配置时长）
+- ✅ 防止重复显示
+- ✅ XSS 防护
 
-2. **Import CSS file:**
-   ```typescript
-   import '@seaverse/payment-sdk/style.css';
-   ```
+---
 
-3. **Configuration options renamed:**
-   - `sdkCdnUrl` removed (no longer uses CDN)
-   - `sdkTimeout` → `componentTimeout`
+## 🛡️ 错误处理
 
-### Before (v0.1.x)
+### 业务错误码（BIZ_CODE）
+
+| 错误码 | 常量                   | 说明         |
+| ------ | ---------------------- | ------------ |
+| `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`      | 订单不存在   |
+
+### 错误处理示例
 
 ```typescript
-const client = new PaymentCheckoutClient({
-  apiHost: 'https://payment.sg.seaverse.dev',
-  authToken: 'token',
-  environment: 'develop', // Old naming
+const modal = new GenericPackageModal({
+  packages: packages,
+  sdkConfig: { /* ... */ },
+
+  onPaymentFailed: (error, pkg) => {
+    // 处理限额错误
+    if (error.message.includes('Daily limit')) {
+      showErrorMessage(`您已达到 ${pkg.name} 的每日购买限额`);
+    } else if (error.message.includes('Lifetime limit')) {
+      showErrorMessage('此套餐仅限购买一次，您已购买过');
+    } else {
+      showErrorMessage(`支付失败：${error.message}`);
+    }
+  },
 });
 ```
 
-### After (v0.2.x+)
+---
 
-```typescript
-import '@seaverse/payment-sdk/style.css'; // Required!
+## 🧪 测试卡号（开发环境）
+
+在开发环境测试支付功能：
+
+| 字段     | 值                 |
+| -------- | ------------------ |
+| 卡号     | `4212345678910006` |
+| 有效期   | `03/30`            |
+| CVC      | `737`              |
+| 3DS 密码 | `password`         |
+
+---
+
+## 📊 API 对比表
+
+### CreditPackageModal vs GenericPackageModal
 
-const client = new PaymentCheckoutClient({
-  apiHost: 'https://payment.sg.seaverse.dev',
-  authToken: 'token',
-  environment: 'development', // New naming
+| 特性           | CreditPackageModal | GenericPackageModal               |
+| -------------- | ------------------ | --------------------------------- |
+| **套餐数据**   | 内置预设套餐       | 外部配置（灵活）                  |
+| **套餐类型**   | 标准积分套餐       | 任意类型（破冰/告急/首充/自定义） |
+| **购买限制**   | 无                 | 支持每日/终身限购                 |
+| **奖励展示**   | 无                 | 支持奖励百分比                    |
+| **配置复杂度** | ⭐️ 简单             | ⭐️⭐️ 中等                           |
+| **使用场景**   | 标准积分购买       | 特殊促销、限时活动                |
+
+**选择建议**：
+- 🎯 **标准积分购买** → 使用 `CreditPackageModal`（推荐新手）
+- 🎁 **特殊促销活动** → 使用 `GenericPackageModal`
+
+---
+
+## 🔄 迁移指南
+
+### 从 v0.8.x 迁移到 v0.9.x
+
+**主要变化**：引入环境配置，简化参数
+
+```typescript
+// ✅ 新版本（v0.8.x）
+const modal = new GenericPackageModal({
+  packages: packages,
+  sdkConfig: {
+    environment: 'development',  // 只需指定环境
+    countryCode: 'SG',           // 扁平化参数
+    businessType: 1,             // 可选，默认 1
+  },
 });
 ```
 
-## Error Handling
+**参数变化**：
+- ✅ 新增：`environment` - 自动配置所有 URL
+- ✅ 简化：`countryCode` - 从 `paymentMethodsParams.country_code` 扁平化
+- ✅ 简化：`businessType` - 从 `paymentMethodsParams.business_type` 扁平化
 
-### Business Error Codes (BIZ_CODE)
+---
 
-The SDK uses standardized business error codes returned from the API:
+## 🌐 框架集成
 
-| Code | Constant | Description |
-|------|----------|-------------|
-| `0` | `SUCCESS` | 操作成功 |
-| `400` | `BAD_REQUEST` | 请求参数错误 |
-| `401` | `UNAUTHORIZED` | 未授权 |
-| `500` | `SERVER_ERROR` | 服务器错误 |
-| `4001` | `DAILY_LIMIT_EXCEEDED` | 超过每日限额 |
-| `4002` | `PRODUCT_NOT_FOUND` | 商品不存在 |
-| `4003` | `PRODUCT_DISABLED` | 商品已禁用 |
-| `4004` | `INSUFFICIENT_BALANCE` | 余额不足 |
-| `4005` | `ORDER_NOT_FOUND` | 订单不存在 |
-| `4006` | `INVALID_ORDER_STATUS` | 订单状态无效 |
-
-### Checkout Error Codes
-
-Payment checkout operations may throw errors with these codes:
-
-| Code | Description |
-|------|-------------|
-| `COMPONENT_LOAD_FAILED` | Web Component 加载失败 |
-| `COMPONENT_NOT_READY` | Web Component 未就绪 |
-| `API_ERROR` | API 请求错误 |
-| `CHECKOUT_FAILED` | 结账失败 |
-| `PAYMENT_CANCELLED` | 用户取消支付 |
-| `PAYMENT_FAILED` | 支付失败 |
-| `INVALID_PARAMS` | 参数无效 |
-| `UNAUTHORIZED` | 未授权 |
-| `NETWORK_ERROR` | 网络错误 |
-| `UNKNOWN_ERROR` | 未知错误 |
-
-### Error Handling Example
+### Vue 3
 
-```typescript
-import { PaymentCheckoutClient, isCheckoutPaymentError } from '@seaverse/payment-sdk';
-
-try {
-  await checkoutClient.checkout({
-    productId: 'pkg_starter',
-    onError: (error) => {
-      console.error('Payment error:', error.code, error.message);
-
-      // 检查业务错误码
-      if (error.bizCode === 4004) {
-        alert('余额不足，请充值后重试');
-      }
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { CreditPackageModal } from '@seaverse/payment-sdk';
+
+const showModal = () => {
+  const modal = new CreditPackageModal({
+    sdkConfig: {
+      environment: import.meta.env.DEV ? 'development' : 'production',
+      countryCode: 'SG',
+      accountToken: userToken.value,
+    },
+    onPaymentSuccess: (orderId, transactionId) => {
+      console.log('支付成功', { orderId, transactionId });
+      // 刷新用户数据
     },
   });
-} catch (error) {
-  if (isCheckoutPaymentError(error)) {
-    // 处理支付相关错误
-    console.error('Checkout error:', error.code);
-  } else {
-    // 处理其他错误
-    console.error('Unknown error:', error);
-  }
+  modal.open();
+};
+</script>
+
+<template>
+  <button @click="showModal">购买积分</button>
+</template>
+```
+
+### React
+
+```tsx
+import { CreditPackageModal } from '@seaverse/payment-sdk';
+
+function PurchaseButton() {
+  const handlePurchase = () => {
+    const modal = new CreditPackageModal({
+      sdkConfig: {
+        environment: process.env.NODE_ENV === 'development' ? 'development' : 'production',
+        countryCode: 'SG',
+        accountToken: getUserToken(),
+      },
+      onPaymentSuccess: (orderId, transactionId) => {
+        console.log('支付成功', { orderId, transactionId });
+        // 刷新用户数据
+      },
+    });
+    modal.open();
+  };
+
+  return <button onClick={handlePurchase}>购买积分</button>;
 }
 ```
 
-## Test Cards (Development)
+---
+
+## 📝 TypeScript 支持
+
+SDK 包含完整的 TypeScript 类型定义：
+
+```typescript
+import type {
+  // Modal 相关
+  CreditPackageModalOptions,
+  GenericPackageModalOptions,
+  GenericPackage,
+  PurchaseSuccessData,
+
+  // 配置相关
+  PaymentSDKConfig,
+  Environment,
+  EnvironmentConfig,
+
+  // 积分相关
+  CreditDetailResponse,
+  CreditTransaction,
+  CreditPoolType,
+
+  // 订阅相关
+  CurrentSubscription,
+  ActiveSubscription,
+
+  // 订单相关
+  OrderStatus,
+  OrderStatusResponse,
+} from '@seaverse/payment-sdk';
+```
+
+---
+
+## 🔗 相关链接
+
+- 📦 [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)
+
+---
+
+## 📄 许可证
+
+MIT License
+
+---
+
+## 🤝 贡献
 
-| Field | Value |
-|-------|-------|
-| Card Number | `4212345678910006` |
-| Expiry | `03/30` |
-| CVC | `737` |
-| 3DS Password | `password` |
+欢迎提交 Issue 和 Pull Request！
 
-## License
+---
 
-MIT
+**更新日期**: 2026-01-31
+**SDK 版本**: v0.8.0