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

## Installation

```bash
pip install django-wallet-utils
```

Or install from source:

```bash
git clone https://github.com/yourusername/django-wallet-utils.git
cd django-wallet-utils
pip install -e .
```

## 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

See [docs/usage.md](docs/usage.md) for complete documentation.

## Requirements

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

## Development

### Running Tests

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

# Run tests
python manage.py test
```

### Development Setup

```bash
# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install package with dev dependencies
pip install -e ".[dev]"

# Run tests
python manage.py test
```

## License

MIT License

## Contributing

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