@seaverse/payment-sdk 0.3.1 → 0.4.1

package/README.md

@@ -52,7 +52,7 @@ Show payment modal for purchases:
 
 ```typescript
 import { PaymentCheckoutClient } from '@seaverse/payment-sdk';
-// Import the Web Component styles (bundled in SDK)
+// Import the Web Component styles
 import '@seaverse/payment-sdk/style.css';
 
 const checkoutClient = new PaymentCheckoutClient({
@@ -160,7 +160,7 @@ interface CheckoutClientConfig {
 <script setup lang="ts">
 import { ref, onMounted } from 'vue';
 import { PaymentCheckoutClient } from '@seaverse/payment-sdk';
-import '@seaart/payment-component/style.css';
+import '@seaverse/payment-sdk/style.css';
 
 const checkoutClient = ref<PaymentCheckoutClient | null>(null);
 
@@ -187,7 +187,7 @@ async function handlePurchase() {
 ```tsx
 import { useEffect, useRef } from 'react';
 import { PaymentCheckoutClient } from '@seaverse/payment-sdk';
-import '@seaart/payment-component/style.css';
+import '@seaverse/payment-sdk/style.css';
 
 function PaymentPage() {
   const clientRef = useRef<PaymentCheckoutClient | null>(null);
@@ -223,17 +223,12 @@ function PaymentPage() {
    - `'develop'` → `'development'`
    - `'release'` → `'production'`
 
-2. **New peer dependency required:**
-   ```bash
-   npm install @seaart/payment-component
-   ```
-
-3. **Import CSS file:**
+2. **Import CSS file:**
    ```typescript
-   import '@seaart/payment-component/style.css';
+   import '@seaverse/payment-sdk/style.css';
    ```
 
-4. **Configuration options renamed:**
+3. **Configuration options renamed:**
    - `sdkCdnUrl` removed (no longer uses CDN)
    - `sdkTimeout` → `componentTimeout`
 
@@ -247,10 +242,10 @@ const client = new PaymentCheckoutClient({
 });
 ```
 
-### After (v0.2.x)
+### After (v0.2.x+)
 
 ```typescript
-import '@seaart/payment-component/style.css'; // Required!
+import '@seaverse/payment-sdk/style.css'; // Required!
 
 const client = new PaymentCheckoutClient({
   apiHost: 'https://payment.sg.seaverse.dev',
@@ -259,6 +254,70 @@ const client = new PaymentCheckoutClient({
 });
 ```
 
+## Error Handling
+
+### 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
+
+```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('余额不足，请充值后重试');
+      }
+    },
+  });
+} catch (error) {
+  if (isCheckoutPaymentError(error)) {
+    // 处理支付相关错误
+    console.error('Checkout error:', error.code);
+  } else {
+    // 处理其他错误
+    console.error('Unknown error:', error);
+  }
+}
+```
+
 ## Test Cards (Development)
 
 | Field | Value |