@seaverse/payment-sdk 0.1.0

package/README.md

@@ -0,0 +1,156 @@
+# @seaverse/payment-sdk
+
+SeaVerse Payment SDK - Credit management and payment checkout for SeaVerse applications.
+
+## Features
+
+- **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
+
+## Installation
+
+```bash
+npm install @seaverse/payment-sdk
+# or
+pnpm add @seaverse/payment-sdk
+```
+
+## Quick Start
+
+### Credit Query
+
+Query user credit accounts and transaction history:
+
+```typescript
+import { PaymentClient } from '@seaverse/payment-sdk';
+
+const client = new PaymentClient({
+  appId: 'seaverse',
+  token: 'your-bearer-token',
+});
+
+// Get credit detail with 4-pool breakdown
+const detail = await client.getCreditDetail();
+console.log(`Total Balance: ${detail.total_balance}`);
+
+detail.pools.forEach(pool => {
+  console.log(`${pool.type}: ${pool.balance}`);
+});
+
+// List transactions
+const transactions = await client.listTransactions({ page_size: 10 });
+```
+
+### Payment Checkout
+
+Show payment modal for purchases:
+
+```typescript
+import { PaymentCheckoutClient } from '@seaverse/payment-sdk';
+
+const checkoutClient = new PaymentCheckoutClient({
+  apiHost: 'https://payment.sg.seaverse.dev',
+  authToken: 'your-jwt-token',
+  environment: 'develop',
+  debug: true,
+});
+
+// Initialize (loads SeaArtPay SDK)
+await checkoutClient.init();
+
+// One-time purchase
+await checkoutClient.checkout({
+  productId: 'pkg_starter',
+  onSuccess: (res) => console.log('Payment success:', res),
+  onError: (err) => console.error('Payment failed:', err),
+});
+
+// Subscription
+await checkoutClient.subscribe({
+  productId: 'pro',
+  period: 'month',
+  periodAmount: 24.99,
+  onSuccess: (res) => console.log('Subscription success:', res),
+});
+```
+
+## API Reference
+
+### PaymentClient (Credit Query)
+
+| 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 |
+
+### PaymentCheckoutClient (Payment Modal)
+
+| Method | Description |
+|--------|-------------|
+| `init()` | Initialize and load SeaArtPay SDK |
+| `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 |
+
+## Credit Pool Types
+
+The 4-pool credit system:
+
+| 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
+
+### 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)
+}
+```
+
+### PaymentCheckoutClient Options
+
+```typescript
+interface CheckoutClientConfig {
+  apiHost: string;               // Payment gateway API URL
+  authToken?: string;            // Static JWT token
+  getAuthToken?: () => string;   // Dynamic token getter
+  environment?: 'develop' | 'release';
+  debug?: boolean;
+  sdkCdnUrl?: string;            // Custom SDK CDN URL
+  sdkTimeout?: number;           // SDK load timeout in ms
+}
+```
+
+## Test Cards (Development)
+
+| Field | Value |
+|-------|-------|
+| Card Number | `4212345678910006` |
+| Expiry | `03/30` |
+| CVC | `737` |
+| 3DS Password | `password` |
+
+## License
+
+MIT
+