@djangocfg/ext-payments 1.0.0

package/README.md

@@ -0,0 +1,206 @@
+# @djangocfg/ext-payments
+
+Payment processing and subscription management extension for DjangoCFG.
+
+**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
+
+## Install
+
+```bash
+pnpm add @djangocfg/ext-payments
+```
+
+## Usage
+
+### Provider Setup
+
+```typescript
+import { PaymentsExtensionProvider } from '@djangocfg/ext-payments/hooks';
+
+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',
+    });
+
+    // Redirect to payment URL
+    window.location.href = payment.payment_url;
+  };
+
+  return (
+    <button onClick={handleCheckout} disabled={isCreatingPayment}>
+      {isCreatingPayment ? 'Processing...' : 'Pay $99.99'}
+    </button>
+  );
+}
+```
+
+### Balance Management
+
+```typescript
+import { useBalancesContext } from '@djangocfg/ext-payments/hooks';
+
+function WalletPage() {
+  const { balances, isLoadingBalances, refreshBalances } = useBalancesContext();
+
+  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>
+      ))}
+    </div>
+  );
+}
+```
+
+### Currency Management
+
+```typescript
+import { useCurrenciesContext } from '@djangocfg/ext-payments/hooks';
+
+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>
+  );
+}
+```
+
+### Payment History
+
+```typescript
+import { usePaymentsContext } from '@djangocfg/ext-payments/hooks';
+
+function TransactionsPage() {
+  const { payments, isLoadingPayments } = usePaymentsContext();
+
+  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>
+      ))}
+    </div>
+  );
+}
+```
+
+### Payment Overview
+
+```typescript
+import { useOverviewContext } from '@djangocfg/ext-payments/hooks';
+
+function DashboardPage() {
+  const { overview, isLoadingOverview } = useOverviewContext();
+
+  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>
+  );
+}
+```
+
+## 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
+
+## License
+
+MIT
+
+## Links
+
+- [DjangoCFG Documentation](https://djangocfg.com)
+- [GitHub](https://github.com/markolofsen/django-cfg)