@djangocfg/ext-payments 1.0.19 → 1.0.21

package/README.md

@@ -2,25 +2,24 @@
 
 ![DjangoCFG Extension Preview](https://unpkg.com/@djangocfg/ext-payments@latest/preview.png)
 
-**[📦 View in Marketplace](https://hub.djangocfg.com/extensions/djangocfg-ext-payments)** • **[📖 Documentation](https://djangocfg.com)** • **[⭐ GitHub](https://github.com/markolofsen/django-cfg)**
+**[View in Marketplace](https://hub.djangocfg.com/extensions/djangocfg-ext-payments)** • **[Documentation](https://djangocfg.com)** • **[GitHub](https://github.com/markolofsen/django-cfg)**
 
 </div>
 
 # @djangocfg/ext-payments
 
-Payment processing and subscription management extension for DjangoCFG.
+Wallet-style payment system extension for DjangoCFG with Apple-inspired UX.
 
 **Part of [DjangoCFG](https://djangocfg.com)** — modern Django framework for production-ready SaaS applications.
 
 ## Features
 
-- 💳 **Payment Processing** - Handle cryptocurrency and fiat payments
-- 🔄 **Subscription Management** - Recurring billing and subscriptions
-- 💰 **Multi-Currency Support** - Support for multiple cryptocurrencies
-- 📊 **Balance Tracking** - Real-time balance and transaction history
-- 🔔 **Webhook Integration** - Receive payment notifications
-- 📈 **Analytics Dashboard** - Payment statistics and insights
-- 🔒 **Secure Payments** - PCI-compliant payment handling
+- 💳 **Wallet Page** - Apple-style single page with balance and activity
+- 💰 **Multi-Currency** - Support for crypto (USDT, BTC, ETH) and fiat
+- 📊 **Real-time Balance** - Live balance updates via WebSocket
+- 🔄 **Withdrawals** - Request withdrawals with status tracking
+- 📜 **Transaction History** - Full payment and withdrawal history
+- 🎨 **Ready Components** - BalanceHero, ActivityList, PaymentSheet
 
 ## Install
 
@@ -28,181 +27,154 @@ Payment processing and subscription management extension for DjangoCFG.
 pnpm add @djangocfg/ext-payments
 ```
 
-## Usage
+## Exports
 
-### Provider Setup
+| Path | Description |
+|------|-------------|
+| `@djangocfg/ext-payments` | Main exports (WalletPage, components, types) |
+| `@djangocfg/ext-payments/api` | API client, fetchers, schemas |
+| `@djangocfg/ext-payments/api/hooks` | SWR hooks for API |
+| `@djangocfg/ext-payments/config` | Extension config (server-safe) |
 
-```typescript
-import { PaymentsExtensionProvider } from '@djangocfg/ext-payments/hooks';
+## Quick Start
 
-export default function RootLayout({ children }) {
-  return (
-    <PaymentsExtensionProvider>
-      {children}
-    </PaymentsExtensionProvider>
-  );
-}
-```
-
-### Create Payment
-
-```typescript
-import { usePaymentsContext } from '@djangocfg/ext-payments/hooks';
-
-function CheckoutPage() {
-  const { createPayment, isCreatingPayment } = usePaymentsContext();
-
-  const handleCheckout = async () => {
-    const payment = await createPayment({
-      amount: 99.99,
-      currency: 'USD',
-      description: 'Premium subscription',
-      success_url: '/success',
-      cancel_url: '/cancel',
-    });
+### Full Wallet Page
 
-    // Redirect to payment URL
-    window.location.href = payment.payment_url;
-  };
+```tsx
+// app/wallet/page.tsx
+import { WalletPage } from '@djangocfg/ext-payments';
 
-  return (
-    <button onClick={handleCheckout} disabled={isCreatingPayment}>
-      {isCreatingPayment ? 'Processing...' : 'Pay $99.99'}
-    </button>
-  );
-}
+export default WalletPage;
 ```
 
-### Balance Management
+### API Hooks
+
+```tsx
+import {
+  usePaymentsBalanceRetrieve,
+  usePaymentsPaymentsList,
+  usePaymentsWithdrawalsList,
+  useCreatePaymentsPaymentsCreateCreate,
+} from '@djangocfg/ext-payments/api/hooks';
 
-```typescript
-import { useBalancesContext } from '@djangocfg/ext-payments/hooks';
+function BalanceCard() {
+  const { data: balance, isLoading } = usePaymentsBalanceRetrieve();
 
-function WalletPage() {
-  const { balances, isLoadingBalances, refreshBalances } = useBalancesContext();
+  if (isLoading) return <Skeleton />;
 
   return (
     <div>
-      <h2>Your Balances</h2>
-      <button onClick={refreshBalances}>Refresh</button>
-      {balances?.map(balance => (
-        <div key={balance.currency}>
-          <strong>{balance.currency}:</strong> {balance.amount}
-        </div>
-      ))}
+      <h2>Balance: ${balance?.amount}</h2>
+      <p>Currency: {balance?.currency}</p>
     </div>
   );
 }
 ```
 
-### Currency Management
+### API Client
 
-```typescript
-import { useCurrenciesContext } from '@djangocfg/ext-payments/hooks';
+```tsx
+import { apiPayments } from '@djangocfg/ext-payments/api';
 
-function CurrencySelector() {
-  const { currencies, selectedCurrency, setCurrency } = useCurrenciesContext();
-
-  return (
-    <select
-      value={selectedCurrency?.code}
-      onChange={(e) => {
-        const currency = currencies.find(c => c.code === e.target.value);
-        if (currency) setCurrency(currency);
-      }}
-    >
-      {currencies.map(currency => (
-        <option key={currency.code} value={currency.code}>
-          {currency.name} ({currency.symbol})
-        </option>
-      ))}
-    </select>
-  );
-}
+// Direct API calls
+const balance = await apiPayments.payments.balanceRetrieve();
+const payments = await apiPayments.payments.paymentsList({ page: 1 });
 ```
 
-### Payment History
+### Individual Components
 
-```typescript
-import { usePaymentsContext } from '@djangocfg/ext-payments/hooks';
+```tsx
+import {
+  BalanceHero,
+  ActivityList,
+  AddFundsSheet,
+  WithdrawSheet,
+  PaymentSheet,
+  WithdrawalSheet,
+} from '@djangocfg/ext-payments';
 
-function TransactionsPage() {
-  const { payments, isLoadingPayments } = usePaymentsContext();
+function CustomWallet() {
+  const [addFundsOpen, setAddFundsOpen] = useState(false);
 
   return (
     <div>
-      <h2>Transaction History</h2>
-      {payments.map(payment => (
-        <div key={payment.id}>
-          <span>{payment.description}</span>
-          <span>{payment.amount} {payment.currency}</span>
-          <span>Status: {payment.status}</span>
-          <span>{new Date(payment.created_at).toLocaleDateString()}</span>
-        </div>
-      ))}
+      <BalanceHero
+        onAddFunds={() => setAddFundsOpen(true)}
+        onWithdraw={() => {}}
+      />
+      <ActivityList limit={10} />
+      <AddFundsSheet
+        open={addFundsOpen}
+        onOpenChange={setAddFundsOpen}
+      />
     </div>
   );
 }
 ```
 
-### Payment Overview
+### Context Provider
 
-```typescript
-import { useOverviewContext } from '@djangocfg/ext-payments/hooks';
+```tsx
+import { WalletProvider, useWallet } from '@djangocfg/ext-payments';
 
-function DashboardPage() {
-  const { overview, isLoadingOverview } = useOverviewContext();
+// Wrap your app
+<WalletProvider>
+  <MyWalletPage />
+</WalletProvider>
 
-  if (isLoadingOverview) return <div>Loading...</div>;
-
-  return (
-    <div>
-      <h2>Payment Overview</h2>
-      <div>
-        <p>Total Revenue: ${overview.total_revenue}</p>
-        <p>Pending Payments: {overview.pending_count}</p>
-        <p>Completed Payments: {overview.completed_count}</p>
-        <p>This Month: ${overview.current_month_revenue}</p>
-      </div>
-    </div>
-  );
+// Use in components
+function MyComponent() {
+  const { balance, payments, withdrawals, isLoading } = useWallet();
+  // ...
 }
 ```
 
 ## API Reference
 
-### Payments Context
-
-- `payments` - List of all payments
-- `createPayment(data)` - Create new payment
-- `getPaymentById(id)` - Get payment details
-- `cancelPayment(id)` - Cancel payment
-- `isLoadingPayments` - Loading state
-
-### Balances Context
-
-- `balances` - User's cryptocurrency balances
-- `refreshBalances()` - Refresh balance data
-- `isLoadingBalances` - Loading state
-
-### Currencies Context
-
-- `currencies` - Available cryptocurrencies
-- `selectedCurrency` - Currently selected currency
-- `setCurrency(currency)` - Set active currency
-- `getCurrencyByCode(code)` - Get currency details
-
-### Overview Context
-
-- `overview` - Payment statistics and analytics
-- `refreshOverview()` - Refresh overview data
-- `isLoadingOverview` - Loading state
-
-### Root Payments Context
-
-- `currencies` - Global currencies list
-- `refreshCurrencies()` - Refresh currency data
-- `isLoadingCurrencies` - Loading state
+### SWR Hooks
+
+| Hook | Description |
+|------|-------------|
+| `usePaymentsBalanceRetrieve()` | Get user balance |
+| `usePaymentsCurrenciesList()` | Get available currencies |
+| `usePaymentsCurrenciesEstimateRetrieve(code, { amount })` | Get payment estimate |
+| `usePaymentsPaymentsList({ page, page_size })` | List payments |
+| `usePaymentsPaymentsRetrieve(id)` | Get payment details |
+| `usePaymentsWithdrawalsList({ page, page_size })` | List withdrawals |
+| `usePaymentsWithdrawalsRetrieve(id)` | Get withdrawal details |
+| `useCreatePaymentsPaymentsCreateCreate()` | Create payment mutation |
+| `useCreatePaymentsWithdrawalsCreateCreate()` | Create withdrawal mutation |
+| `useCreatePaymentsWithdrawalsCancelCreate()` | Cancel withdrawal mutation |
+
+### Components
+
+| Component | Description |
+|-----------|-------------|
+| `WalletPage` | Full wallet page with all features |
+| `BalanceHero` | Balance display with action buttons |
+| `ActivityList` | Combined payments + withdrawals list |
+| `AddFundsSheet` | Sheet for adding funds |
+| `WithdrawSheet` | Sheet for withdrawing |
+| `PaymentSheet` | Payment details sheet |
+| `WithdrawalSheet` | Withdrawal details sheet |
+| `CurrencyCombobox` | Currency selector |
+
+### Types
+
+```tsx
+import type {
+  Balance,
+  PaymentDetail,
+  PaymentList,
+  PaymentCreateRequest,
+  PaymentCreateResponse,
+  WithdrawalDetail,
+  WithdrawalList,
+  WithdrawalCreateRequest,
+  Currency,
+  Transaction,
+} from '@djangocfg/ext-payments';
+```
 
 ## License