Metadata-Version: 2.4
Name: django-wallet-utils
Version: 0.1.0
Summary: Wallet point transaction utilities for Django
Author-email: Your Name <your.email@example.com>
License: MIT
Project-URL: Homepage, https://github.com/yourusername/django-wallet-utils
Project-URL: Documentation, https://github.com/yourusername/django-wallet-utils#readme
Project-URL: Repository, https://github.com/yourusername/django-wallet-utils
Project-URL: Issues, https://github.com/yourusername/django-wallet-utils/issues
Keywords: django,wallet,points,transactions,mlm
Classifier: Development Status :: 4 - Beta
Classifier: Framework :: Django
Classifier: Framework :: Django :: 4.2
Classifier: Framework :: Django :: 5.0
Classifier: Framework :: Django :: 5.1
Classifier: Framework :: Django :: 5.2
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: django<6.0,>=4.2
Provides-Extra: test
Requires-Dist: django<6.0,>=4.2; extra == "test"
Provides-Extra: dev
Requires-Dist: django<6.0,>=4.2; extra == "dev"
Requires-Dist: black; extra == "dev"
Requires-Dist: flake8; extra == "dev"
Requires-Dist: mypy; extra == "dev"

# django-wallet-utils

Wallet point transaction utilities for Django, ported from PHP `WalletPoint` class.

## Features

- ✅ Simple repository interface (only define point types and decimal places)
- ✅ Atomic SQL operations (prevents race conditions)
- ✅ Built-in Django models and migrations
- ✅ Transaction history retrieval
- ✅ Support for separate wallet balance models
- ✅ Custom field name mapping
- ✅ Integer transaction type constants
- ✅ Comprehensive error handling
- ✅ **Hook System** - Extensible PRE/POST transaction hooks (NEW!)

## Hook System - NEW! 🎉

Extend wallet transactions with custom validation, fraud detection, notifications, and more!

```python
from wallet_utils import register_hook, HookType, HookContext, HookRejectionError

# Register a PRE hook to validate transactions
def check_daily_limit(context: HookContext) -> bool:
    if context.amount > Decimal("1000.00"):
        raise HookRejectionError(
            error_code="DAILY_LIMIT_EXCEEDED",
            message="Daily limit exceeded",
            details={"limit": 1000.00}
        )
    return True

register_hook("daily_limit", HookType.PRE, check_daily_limit, priority=50)

# Hooks execute automatically on all transactions
result = service.deduct_point(user_id=123, point_type="cash", amount=Decimal("500.00"))
```

**Learn more:**
- 📚 [Complete Hook System Guide](docs/usage.md#hook-system)
- 📖 [Complete Hook Documentation](docs/usage.md#hook-system)
- 🎯 [Production Examples](examples/hooks/)
- 💻 [Frontend Integration](docs/frontend-integration.md)
- 🏗️ [Design Specification](docs/hook-system-design.md)

**Hook System Status**: ✅ **PRODUCTION READY** - Fully tested with 44 passing tests, comprehensive documentation, and 5 production-ready examples.

## Installation

### From Git Repository (Recommended for Production)

```bash
pip install git+https://github.com/mscumec/django-downline-utils.git
```

### From Local Path (Recommended for Development)

```bash
pip install -e /path/to/django-wallet-utils
```

See [docs/usage.md](docs/usage.md) for detailed installation instructions and all available options.

## Quick Start

### 1. Add to Django INSTALLED_APPS

```python
INSTALLED_APPS = [
    # ... other apps
    "wallet_utils",
]
```

### 2. Run Migrations

```bash
python manage.py migrate wallet_utils
```

### 3. Use the Service

```python
from decimal import Decimal
from wallet_utils import WalletService, WalletRepository
from wallet_utils.transaction_types import WALLET_DEPOSIT
from your_app.models import User

# Define point types
point_types = {
    "credit_balance": 2,  # 2 decimal places
    "reward_points": 0,   # No decimal places
}

# Create repository
repo = WalletRepository(
    user_model=User,
    point_types=point_types,
)

# Use the service
service = WalletService(repo)
transaction_id = service.add_point(
    user_id=123,
    point_type="credit_balance",
    amount=Decimal("100.00"),
    remarks="Deposit",
    trans_type=WALLET_DEPOSIT,
)
```

## Documentation

- **[Complete Usage Guide](docs/usage.md)** - Comprehensive documentation with examples
- **[Testing Documentation](docs/testing-wallet-utils.md)** - Test suite documentation and coverage

## Requirements

- Python >= 3.9
- Django >= 4.2, < 6.0

## Development

```bash
# Install in editable mode with test dependencies
pip install -e ".[test]"

# Run migrations
python manage.py migrate

# Run tests
python manage.py test
```

See [docs/testing-wallet-utils.md](docs/testing-wallet-utils.md) for detailed testing documentation.

## License

MIT License

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.