Complete documentation refactoring: updated CHANGELOG with wallet system and...

Complete documentation refactoring: updated CHANGELOG with wallet system and docs reorganization, fixed PYPI.md versions, added wallet API examples to API_EXAMPLES.md

API_EXAMPLES.md

@@ -1022,6 +1022,144 @@ curl -X POST http://localhost:17765/mcp/tools/call \
   }'
 ```
 
+## Wallet API Examples
+
+### Check Wallet Balance
+
+Using cURL:
+```bash
+curl -H "Authorization: Bearer YOUR_TOKEN" http://localhost:17765/api/wallet/balance
+```
+
+Response:
+```json
+{
+  "balance": 25.50,
+  "currency": "USD",
+  "auto_topup_enabled": true,
+  "auto_topup_threshold": 10.00
+}
+```
+
+Using Python:
+```python
+import requests
+
+headers = {"Authorization": "Bearer YOUR_TOKEN"}
+response = requests.get("http://localhost:17765/api/wallet/balance", headers=headers)
+balance = response.json()
+print(f"Balance: {balance['balance']} {balance['currency']}")
+```
+
+### Top Up Wallet
+
+#### Stripe Top Up
+```bash
+curl -X POST http://localhost:17765/api/wallet/topup \
+  -H "Authorization: Bearer YOUR_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "amount": 20.00,
+    "payment_method": "stripe"
+  }'
+```
+
+#### PayPal Top Up
+```bash
+curl -X POST http://localhost:17765/api/wallet/topup \
+  -H "Authorization: Bearer YOUR_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "amount": 15.00,
+    "payment_method": "paypal"
+  }'
+```
+
+#### Crypto Top Up
+```bash
+curl -X POST http://localhost:17765/api/wallet/topup \
+  -H "Authorization: Bearer YOUR_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "amount": 50.00,
+    "payment_method": "bitcoin"
+  }'
+```
+
+### Configure Auto Top Up
+
+```bash
+curl -X POST http://localhost:17765/api/wallet/auto-topup \
+  -H "Authorization: Bearer YOUR_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "enabled": true,
+    "amount": 15.00,
+    "threshold": 5.00,
+    "payment_method_id": "pm_stripe_123456"
+  }'
+```
+
+### Transaction History
+
+```bash
+curl -H "Authorization: Bearer YOUR_TOKEN" \
+  "http://localhost:17765/api/wallet/transactions?page=1&limit=10"
+```
+
+Response:
+```json
+{
+  "transactions": [
+    {
+      "id": 123,
+      "type": "credit",
+      "amount": 10.00,
+      "description": "Stripe top-up",
+      "created_at": "2026-04-21T10:30:00Z"
+    },
+    {
+      "id": 124,
+      "type": "debit",
+      "amount": 5.99,
+      "description": "Monthly subscription renewal",
+      "created_at": "2026-04-21T11:00:00Z"
+    }
+  ],
+  "total": 45,
+  "page": 1,
+  "pages": 5
+}
+```
+
+### Wallet Integration with Chat Completions
+
+The wallet system automatically handles subscription renewals. When a subscription renewal is due:
+
+1. **Check wallet balance** first
+2. **Sufficient balance** → Deduct renewal amount → Success ✅
+3. **Insufficient balance** → Auto top-up (if enabled) → Retry deduction → Success ✅
+4. **Auto top-up fails** → Renewal fails → Grace period → Future retry ❌
+
+Example workflow:
+```bash
+# User makes a chat request
+curl -X POST http://localhost:17765/api/v1/chat/completions \
+  -H "Authorization: Bearer YOUR_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "model": "openai/gpt-4",
+    "messages": [{"role": "user", "content": "Hello!"}]
+  }'
+
+# System automatically:
+# 1. Checks subscription status
+# 2. If renewal needed, checks wallet balance
+# 3. If low, triggers auto top-up (if configured)
+# 4. Processes renewal with wallet funds
+# 5. Returns chat response
+```
+
 ## License
 
 Copyright (C) 2026 Stefy Lanza <stefy@nexlab.net>

CHANGELOG.md

@@ -7,6 +7,31 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.99.47] - 2026-04-21
+
+### Added
+- **Unified Wallet System**
+  - Fiat wallet per user with configurable currency
+  - Top-up support via Crypto (BTC, ETH, USDT, USDC), PayPal, Stripe
+  - Fixed amount presets: 10, 15, 20, 50, 100 + custom amounts
+  - Auto top-up with threshold triggers for Stripe
+  - Complete transaction history and audit trail
+  - Subscription renewal integration with wallet deduction
+  - Wallet API endpoints for balance, top-up, transactions
+  - Dashboard wallet management interface
+
+- **Documentation Reorganization**
+  - Moved donations to top of README for better visibility
+  - Streamlined README to focus on user essentials
+  - Comprehensive DOCUMENTATION.md with wallet system details
+  - Updated project structure and directory tree
+  - Fixed examples and removed duplications
+  - Clarified token access patterns (global vs user tokens)
+
+### Changed
+- Updated all version numbers to 0.99.47
+- Added wallet package to pyproject.toml
+
 ## [0.99.26] - 2026-04-16
 
 ### Added

PYPI.md

@@ -41,8 +41,8 @@ python -m build
 ```
 
 This creates:
-- `dist/aisbf-0.99.5.tar.gz` - Source distribution
-- `dist/aisbf-0.99.5-py3-none-any.whl` - Wheel distribution
+- `dist/aisbf-0.99.47.tar.gz` - Source distribution
+- `dist/aisbf-0.99.47-py3-none-any.whl` - Wheel distribution
 
 ## Testing the Package
 
@@ -50,7 +50,7 @@ This creates:
 
 ```bash
 # Install from the built wheel
-pip install dist/aisbf-0.99.5-py3-none-any.whl
+pip install dist/aisbf-0.99.47-py3-none-any.whl
 
 # Test the installation
 aisbf status