# wallet-utils

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

## Installation

```bash
pip install -e ./packages/wallet_utils
```

Or add to your `requirements.txt`:
```
-e ./packages/wallet_utils
```

## Quick Start

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

## Package Structure

```
wallet_utils/
├── src/wallet_utils/      # Package source code
│   ├── __init__.py
│   ├── models.py          # Django models
│   ├── repository.py      # Repository implementation
│   ├── service.py         # Main service class
│   ├── exceptions.py      # Custom exceptions
│   ├── transaction_types.py  # Transaction type constants
│   └── migrations/        # Django migrations
├── docs/
│   └── usage.md          # Complete usage documentation
└── pyproject.toml        # Package configuration
```

## Testing

The test suite is located in `sandbox/` at the project root level (same level as `packages/`).

**Tests are NOT included in the package distribution** - they remain separate for development purposes only.

To run tests:
```bash
cd sandbox
pip install -r requirements.txt
pip install -e ../packages/wallet_utils
python manage.py migrate
python manage.py test test_app.tests
```

See `sandbox/README.md` for detailed test documentation.

## Features

- ✅ Simple repository interface (only define point types)
- ✅ Atomic operations with race condition prevention
- ✅ Built-in Django models and migrations
- ✅ Transaction history retrieval
- ✅ Support for separate wallet balance models
- ✅ Custom field name mapping
- ✅ Integer transaction type constants
- ✅ Decimal precision control per point type

## License

[Add your license here]