@volr/react-ui 0.1.93 → 0.1.95

package/README.md

@@ -1,6 +1,6 @@
 # @volr/react-ui
 
-Pre-built UI components for Volr, built on top of `@volr/react` and `@volr/sdk-core`, with minimal, modern design.
+Pre-built UI components for Volr Payment Gateway, built on top of `@volr/react` and `@volr/sdk-core`, with minimal, modern design.
 
 ## Installation
 
@@ -23,7 +23,7 @@ const volrConfig: VolrUIConfig = {
   projectApiKey: 'your-project-api-key',
   appName: 'My App',
   accentColor: '#3b82f6',
-  enabledLoginMethods: ['email', 'social', 'siwe'],
+  enabledLoginMethods: ['email', 'social'],
   socialProviders: ['google', 'twitter'],
 };
 
@@ -36,12 +36,154 @@ function App() {
 }
 ```
 
-### 2. Use useVolrModal Hook
+---
+
+## Payment Integration
+
+Volr provides a simple, Stripe-like payment experience for Web3 applications.
+
+### Basic Payment
+
+```tsx
+import { useVolrPay } from '@volr/react-ui';
+// Or from @volr/react if not using UI components
+
+function CheckoutButton() {
+  const { pay } = useVolrPay();
+
+  const handleCheckout = async () => {
+    const payment = await pay({
+      amount: 9.99,
+      item: {
+        name: 'Premium Plan',
+        description: 'Monthly subscription',
+      },
+      handlers: {
+        onSuccess: (result) => {
+          console.log('Payment confirmed!', result.txHash);
+        },
+        onError: (error) => {
+          console.error('Payment failed:', error.message);
+        },
+      },
+    });
+
+    // Optionally wait for confirmation
+    const result = await payment.wait();
+  };
+
+  return <button onClick={handleCheckout}>Subscribe $9.99</button>;
+}
+```
+
+### Payment with Reference ID
+
+Track payments with your own order ID:
+
+```tsx
+const payment = await pay({
+  amount: 29.99,
+  item: { name: 'Pro License' },
+  referenceId: 'order_12345', // Your order ID
+  metadata: {
+    userId: 'user_abc',
+    plan: 'pro',
+  },
+});
+```
+
+### Idempotent Payments
+
+Prevent duplicate payments with idempotency key:
+
+```tsx
+const payment = await pay({
+  amount: 49.99,
+  item: { name: 'Enterprise License' },
+  idempotencyKey: `order_${orderId}_${userId}`, // Unique per payment intent
+});
+```
+
+### Check Payment Status
+
+```tsx
+import { useVolrPay } from '@volr/react-ui';
+
+function OrderStatus({ paymentId }: { paymentId: string }) {
+  const { checkPayment } = useVolrPay();
+  const [status, setStatus] = useState<string>('loading');
+
+  useEffect(() => {
+    checkPayment(paymentId).then((result) => {
+      setStatus(result.status); // 'CONFIRMED' | 'PENDING' | 'FAILED' | ...
+    });
+  }, [paymentId]);
+
+  return <div>Payment Status: {status}</div>;
+}
+```
+
+### Payment History
+
+```tsx
+import { useVolrPay } from '@volr/react-ui';
+
+function PaymentHistory() {
+  const { getPaymentHistory } = useVolrPay();
+  const [payments, setPayments] = useState([]);
+
+  useEffect(() => {
+    getPaymentHistory({ take: 10 }).then((result) => {
+      setPayments(result.payments);
+    });
+  }, []);
+
+  return (
+    <ul>
+      {payments.map((p) => (
+        <li key={p.id}>
+          {p.itemName} - {p.amount} {p.token.symbol} - {p.status}
+        </li>
+      ))}
+    </ul>
+  );
+}
+```
+
+### PayOptions Reference
+
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| `amount` | `number` | ✅ | Amount in token units (before decimals) |
+| `item.name` | `string` | ❌ | Item name displayed in modal |
+| `item.description` | `string` | ❌ | Item description |
+| `item.image` | `string` | ❌ | Item image URL (falls back to project logo) |
+| `referenceId` | `string` | ❌ | Your order/reference ID |
+| `metadata` | `Record<string, string>` | ❌ | Custom metadata (max 50 keys) |
+| `idempotencyKey` | `string` | ❌ | Unique key to prevent duplicates |
+| `expiresInSec` | `number` | ❌ | Expiration time (default: 900 = 15 min) |
+| `handlers.onCreated` | `(payment) => void` | ❌ | Called when payment is created |
+| `handlers.onProcessing` | `(payment) => void` | ❌ | Called when transaction is broadcasted |
+| `handlers.onSuccess` | `(result) => void` | ❌ | Called when payment is confirmed |
+| `handlers.onError` | `(error) => void` | ❌ | Called on error |
+| `handlers.onCancel` | `() => void` | ❌ | Called when user cancels |
+
+### Payment Modal Flow
+
+1. **Payment Info** - Shows item details, amount, and user's balance
+2. **Processing** - Passkey signing → Transaction broadcast → On-chain confirmation
+3. **Result** - Success or failure with retry option
+
+---
+
+## Account & Authentication
+
+### Login / Account Modal
 
 ```tsx
 import { useVolrModal, useVolr } from '@volr/react-ui';
 
-function Example() {
+function AuthButton() {
   const { open } = useVolrModal();
   const { evmAddress, isLoggedIn, logout } = useVolr();
 
@@ -50,12 +192,7 @@ function Example() {
       {isLoggedIn ? (
         <>
           <p>Wallet: {evmAddress}</p>
-          <button onClick={() => open({ mode: 'account' })}>
-            My Account
-          </button>
-          <button onClick={() => open({ mode: 'deposit' })}>
-            Deposit
-          </button>
+          <button onClick={() => open({ mode: 'account' })}>My Account</button>
           <button onClick={logout}>Logout</button>
         </>
       ) : (
@@ -66,84 +203,118 @@ function Example() {
 }
 ```
 
-### 3. Direct Asset Deposit
+### Deposit Modal
 
-Open deposit modal with a specific asset pre-selected:
+Open deposit modal to let users top up their wallet:
 
 ```tsx
+import { useVolrModal } from '@volr/react-ui';
+
 function DepositButton() {
   const { open } = useVolrModal();
 
-  const handleDeposit = () => {
-    open({
-      mode: 'deposit',
-      asset: { chainId: 8453, symbol: 'USDC' },
-    });
-  };
-
-  return <button onClick={handleDeposit}>Deposit USDC</button>;
+  return (
+    <button onClick={() => open({ mode: 'deposit' })}>
+      Deposit
+    </button>
+  );
 }
+
+// With specific asset pre-selected
+<button onClick={() => open({ mode: 'deposit', asset: { chainId: 8453, symbol: 'USDC' } })}>
+  Deposit USDC
+</button>
 ```
 
+---
+
 ## Configuration
 
 ### VolrUIProvider Props
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
-| `config` | `VolrUIConfig` | **Required** | Volr UI configuration (extends VolrConfig) |
 | `config.defaultChainId` | `number` | **Required** | Default chain ID |
 | `config.projectApiKey` | `string` | **Required** | Project API key |
 | `config.appName` | `string` | **Required** | Application name |
-| `config.accentColor` | `string` | `'#303030'` | Accent color for buttons and links |
-| `config.enabledLoginMethods` | `('email' \| 'social' \| 'siwe')[]` | `['email', 'social', 'siwe']` | Enabled login methods |
-| `config.socialProviders` | `('google' \| 'twitter' \| 'apple')[]` | `['google', 'twitter', 'apple']` | Enabled social providers |
+| `config.accentColor` | `string` | `'#303030'` | Accent color for buttons |
+| `config.enabledLoginMethods` | `('email' \| 'social' \| 'siwe')[]` | `['email', 'social', 'siwe']` | Login methods |
+| `config.socialProviders` | `('google' \| 'twitter')[]` | `['google', 'twitter']` | Social providers |
 | `config.keyStorageType` | `'passkey' \| 'mpc'` | `'passkey'` | Key storage type |
-| `config.branding` | `BrandingConfig` | `undefined` | Custom branding configuration |
-| `config.providerPolicy` | `object` | `{ enforceOnFirstLogin: true }` | Provider policy settings |
+| `config.branding` | `BrandingConfig` | `undefined` | Custom branding |
 
-> **Note:** Deposit assets are now configured via the Volr Dashboard, not in the SDK config.
+> **Note:** Payment token and deposit assets are configured via the Volr Dashboard.
+
+---
 
 ## API Reference
 
-### useVolrModal
+### useVolrPay
 
-Hook for controlling modals.
+Hook for payment operations with PaymentModal integration.
 
 ```tsx
-import { useVolrModal } from '@volr/react-ui';
+import { useVolrPay } from '@volr/react-ui';
 
-const { isOpen, mode, asset, open, close } = useVolrModal();
+const {
+  pay,                // (options: PayOptions) => Promise<PaymentHandle>
+  checkPayment,       // (id: string) => Promise<PaymentResult>
+  getPaymentHistory,  // (options?) => Promise<{ payments, total }>
+  isPaymentInProgress // boolean
+} = useVolrPay();
+
+// PaymentHandle returned from pay()
+interface PaymentHandle {
+  id: string;
+  status: PaymentStatus;
+  wait: () => Promise<PaymentResult>;  // Wait for completion
+  cancel: () => Promise<void>;          // Cancel (PENDING only)
+}
+```
 
-// Open account modal (default) - shows login if not logged in, account info if logged in
-open();
-open({ mode: 'account' });
+### useVolrPaymentApi (Advanced)
 
-// Open deposit modal
-open({ mode: 'deposit' });
+Headless payment API for advanced use cases (no UI).
 
-// Open deposit with specific asset
-open({ mode: 'deposit', asset: { chainId: 8453, symbol: 'ETH' } });
+```tsx
+import { useVolrPaymentApi } from '@volr/react-ui';
 
-// Close modal
-close();
+const {
+  createPayment,            // (options: PayOptions) => Promise<PaymentResult>
+  checkPayment,             // (id: string) => Promise<PaymentResult>
+  getPaymentHistory,        // (options?) => Promise<{ payments, total }>
+  updatePaymentToProcessing,// (id, txId) => Promise<PaymentResult>
+  cancelPayment,            // (id) => Promise<PaymentResult>
+  pollPaymentStatus,        // (id) => Promise<PaymentResult>
+  isLoading,                // boolean
+} = useVolrPaymentApi();
 ```
 
-| Property | Type | Description |
-|----------|------|-------------|
-| `isOpen` | `boolean` | Whether modal is open |
-| `mode` | `'account' \| 'deposit'` | Current modal mode |
-| `asset` | `{ chainId: number; symbol: string } \| null` | Selected asset for deposit |
-| `open` | `(options?) => void` | Open modal with optional mode/asset |
-| `close` | `() => void` | Close modal |
+### useVolrModal
+
+Hook for controlling modals.
+
+```tsx
+import { useVolrModal } from '@volr/react-ui';
+
+const { isOpen, mode, open, close } = useVolrModal();
+
+open();                                    // Account modal (login or account info)
+open({ mode: 'account' });                 // Same as above
+open({ mode: 'deposit' });                 // Deposit modal
+open({ mode: 'deposit', asset: {...} });   // Deposit with specific asset
+open({ mode: 'payment', payment: {...} }); // Payment modal (internal)
+close();
+```
 
 ### useVolr
 
+Hook for wallet and user state.
+
 ```tsx
 import { useVolr } from '@volr/react-ui';
 
 const {
-  evm,        // (chainId: number) => EvmClient
   evmAddress, // `0x${string}` | undefined
   email,      // string | undefined
   isLoggedIn, // boolean
@@ -154,156 +325,94 @@ const {
 } = useVolr();
 ```
 
-### EvmClient
-
-Returned by `evm(chainId)`.
+---
 
-```tsx
-const client = evm(8453);
-
-// Read contract
-const balance = await client.readContract({
-  address: tokenAddress,
-  abi: erc20Abi,
-  functionName: 'balanceOf',
-  args: [userAddress],
-});
+## Advanced: Web3 Transactions
 
-// Send single transaction
-const result = await client.sendTransaction({
-  to: '0x...',
-  data: '0x...',
-  value: 0n,
-});
+For advanced use cases beyond payments, you can send arbitrary transactions.
 
-// Send batch (with ABI)
-const result = await client.sendBatch([
-  {
-    target: tokenAddress,
-    abi: erc20Abi,
-    functionName: 'transfer',
-    args: [recipient, amount],
-    gasLimit: 100000n,
-  },
-]);
-```
+### EvmClient
 
-## Modal Modes
+```tsx
+import { useVolr } from '@volr/react-ui';
 
-### Account Mode (`mode: 'account'`)
+function SendToken() {
+  const { evm, evmAddress } = useVolr();
 
-- **Not logged in**: Shows login screen (email, social, SIWE)
-- **Logged in**: Shows account info (wallet address, email) and logout button
+  const handleSend = async () => {
+    const client = evm(8453); // Base chain
 
-### Deposit Mode (`mode: 'deposit'`)
+    // Read contract
+    const balance = await client.readContract({
+      address: tokenAddress,
+      abi: erc20Abi,
+      functionName: 'balanceOf',
+      args: [evmAddress],
+    });
 
-- **Not logged in**: Shows login first, then deposit screen
-- **Logged in**: Shows deposit QR code and address
-- **With asset**: Pre-selects the specified asset
+    // Send transaction
+    const result = await client.sendTransaction({
+      to: '0x...',
+      data: '0x...',
+      value: 0n,
+    });
 
-## Features
+    // Send batch
+    const result = await client.sendBatch([
+      {
+        target: tokenAddress,
+        abi: erc20Abi,
+        functionName: 'transfer',
+        args: [recipient, amount],
+        gasLimit: 100000n,
+      },
+    ]);
+  };
+}
+```
 
-- **Email Login**: Email verification with 6-digit code
-- **Social Login**: Google, Twitter, Apple OAuth
-- **SIWE**: Sign-In with Ethereum (wallet login)
-- **Passkey Wallet**: Automatic passkey-based wallet creation
-- **Deposit**: QR code-based crypto deposits
-- **Minimal Design**: Clean, modern UI
-- **Customizable**: Accent color and enabled methods
-- **Type-Safe**: Full TypeScript support
+---
 
-## Login Flow
+## Login Flows
 
 ### Email Login
-1. User clicks "Email Login"
-2. Enter email address
-3. Receive 6-digit verification code
-4. Enter code
-5. **New users**: Passkey setup
-6. **Existing users**: Success
-
-### Social Login (Google, Twitter, Apple)
-1. User clicks social login button
-2. Redirect to OAuth provider
-3. Authorize and return
-4. **New users**: Passkey setup
-5. **Existing users**: Success
-
-### Wallet Login (SIWE)
-1. User clicks "Wallet Login"
-2. Connect MetaMask or other wallet
-3. Sign SIWE message
-4. **New users**: Passkey setup
-5. **Existing users**: Success
-
-## Examples
-
-### Login/Account Button
-
-```tsx
-import { useVolrModal, useVolr } from '@volr/react-ui';
-
-function AuthButton() {
-  const { open } = useVolrModal();
-  const { isLoggedIn, evmAddress } = useVolr();
-
-  if (isLoggedIn) {
-    return (
-      <button onClick={() => open({ mode: 'account' })}>
-        {evmAddress?.slice(0, 6)}...{evmAddress?.slice(-4)}
-      </button>
-    );
-  }
-
-  return <button onClick={() => open()}>Connect</button>;
-}
-```
+1. Enter email → Receive 6-digit code → Enter code → Passkey setup (new users)
 
-### Deposit Button
+### Social Login (Google, Twitter)
+1. Click social button → OAuth redirect → Authorize → Passkey setup (new users)
 
-```tsx
-import { useVolrModal, useVolr } from '@volr/react-ui';
+### Wallet Login (SIWE)
+1. Click Wallet Login → Connect wallet → Sign message → Passkey setup (new users)
 
-function DepositButton() {
-  const { open } = useVolrModal();
-  const { isLoggedIn } = useVolr();
+---
 
-  return (
-    <button 
-      onClick={() => open({ mode: 'deposit' })}
-      disabled={!isLoggedIn}
-    >
-      Deposit
-    </button>
-  );
-}
-```
+## Examples
 
 ### Email Only Config
 
 ```tsx
 const volrConfig: VolrUIConfig = {
   defaultChainId: 8453,
-  projectApiKey: 'your-project-api-key',
+  projectApiKey: 'your-api-key',
   appName: 'My App',
-  accentColor: '#6366f1',
   enabledLoginMethods: ['email'],
 };
 ```
 
-### Google and Apple Only
+### Social Only Config
 
 ```tsx
 const volrConfig: VolrUIConfig = {
   defaultChainId: 8453,
-  projectApiKey: 'your-project-api-key',
+  projectApiKey: 'your-api-key',
   appName: 'My App',
-  accentColor: '#8b5cf6',
   enabledLoginMethods: ['social'],
-  socialProviders: ['google', 'apple'],
+  socialProviders: ['google'],
 };
 ```
 
+---
+
 ## License
 
 MIT