referral-system 0.2.2

Abstract Django referral library: models registry, attribution service, reward ledger helpers

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:

pip install build twine
python -m build

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

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

Consumers:

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:

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

REFERRAL_MODELS

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

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.

Reward transaction entity fields (0.2.0+)

AbstractReferralRewardTransaction includes generic ledger reference columns:

Field	Purpose
transaction_context_type	Business context (e.g. REFERRAL_ATTRIBUTION, CAMPAIGN_REWARD)
transaction_context_id	PK of that context object
transaction_party	Party within the context (e.g. referrer, referee, winner)

Status lifecycle includes INITIATED, PENDING, COMPLETED, FAILED, TIMEOUT, REVERSED.

Use referral.services.referral_reward_transaction_helper for inserts and entity-scoped queries.

---

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.