Metadata-Version: 2.4
Name: referral-system
Version: 0.1.0
Summary: Abstract Django referral library: models registry, attribution service, reward ledger helpers
Author: Amit Pandey
License-Expression: LicenseRef-LCN-Proprietary
Keywords: django,referral,instamoney
Classifier: Framework :: Django
Classifier: Framework :: Django :: 4.2
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: Django<6,>=4.2
Requires-Dist: djangorestframework>=3.14
Requires-Dist: pydantic<3,>=1.10
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: twine>=5.0; extra == "dev"

# `referral-system` (abstract `referral` package)

This wheel ships **only** the Django app package **`referral`**: abstract referral models, `referral.model_registry`, `ReferralAttributionService`, and related helpers.

It does **not** include **`referral_program`** or any product-specific InstaMoney glue (`loan`, `user`, etc.). Host projects must define **concrete** models subclassing `referral.models` abstracts and point `settings.REFERRAL_MODELS` at those models.

---

## Install (private index)

Build locally:

```bash
pip install build twine
python -m build
```

Upload to your **private** PyPI-compatible registry (GitHub Packages, CodeArtifact, Devpi, etc.):

```bash
twine upload --repository-url https://YOUR_REGISTRY/simple dist/*
```

Consumers:

```bash
pip install referral-system --extra-index-url https://TOKEN@YOUR_REGISTRY/simple
```

---

## Django settings

### `INSTALLED_APPS`

Add **`referral`** before any app that defines concrete referral models registered via `REFERRAL_MODELS`:

```python
INSTALLED_APPS = [
    # ...
    "referral",
    "your_app_with_concrete_referral_models",
]
```

### `REFERRAL_MODELS`

Map logical roles to **your** concrete models (`app_label` + `model_name`):

```python
REFERRAL_MODELS = {
    "attribution": {
        "app_label": "your_app_with_concrete_referral_models",
        "model_name": "ReferralAttribution",
    },
    "scheme": {
        "app_label": "your_app_with_concrete_referral_models",
        "model_name": "ReferralScheme",
    },
    "code_map": {
        "app_label": "your_app_with_concrete_referral_models",
        "model_name": "ReferralCodeMap",
    },
    "reward_transaction": {
        "app_label": "your_app_with_concrete_referral_models",
        "model_name": "ReferralRewardTransaction",
    },
}
```

Concrete classes must subclass:

- `referral.models.AbstractReferralAttribution`
- `referral.models.AbstractReferralScheme`
- `referral.models.AbstractReferralCodeMap`
- `referral.models.AbstractReferralRewardTransaction`

Run **`migrate`** in the host app that owns those tables.

---

## Dependencies

Declared in `pyproject.toml`: **Django**, **djangorestframework**, **pydantic** (used by optional schema paths).

The **`referral`** package imports **`shared.helper.shared_models`** (`DefaultTimeStamp` on abstracts). Either:

- vendor a compatible `DefaultTimeStamp` base in your project and adjust forked abstracts, or  
- keep **`shared`** on `PYTHONPATH` / install your internal `shared` package alongside this wheel.

Same applies if you copy code that referenced other internal modules—**this PyPI distribution contains only `referral/`**.

---

## Versioning

Bump **`version`** in `pyproject.toml` before each release; rebuild and re-upload the wheel.

---

## Publishing to PyPI.org

Step-by-step (tokens, TestPyPI, production upload, GitHub Actions): **[PYPI_PUBLISH.md](./PYPI_PUBLISH.md)**.
