django-referral-system 0.1__tar.gz

django-referral-system-0.1/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2012-2024 Serhii Soldatov and others
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

django-referral-system-0.1/MANIFEST.in

@@ -0,0 +1,7 @@
+include LICENSE
+include README.rst
+
+recursive-include referrals/migrations *
+recursive-include referrals/dtos *
+recursive-include referrals/repositories *
+recursive-include referrals/services *

django-referral-system-0.1/PKG-INFO

@@ -0,0 +1,30 @@
+Metadata-Version: 2.1
+Name: django-referral-system
+Version: 0.1
+Summary: A Django app for managing referral programs, promoters, referrals, and tracking referral performance with advanced features like commission setting, invitation management, and Wise payouts.
+Home-page: https://github.com/soldatov-ss/django-referral-system.git
+Author: Soldatov Serhii
+Author-email: soldatov.own@gmail.com
+License: MIT
+Classifier: Environment :: Web Environment
+Classifier: Framework :: Django
+Classifier: Framework :: Django :: 4
+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 :: Only
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
+Requires-Python: >=3.8
+License-File: LICENSE
+Requires-Dist: Django>=4.1
+Requires-Dist: djangorestframework>=3.14
+Requires-Dist: pandas>=2.0
+Requires-Dist: pydantic>=2.0
+Requires-Dist: python-dotenv>=1.0

django-referral-system-0.1/README.md

@@ -0,0 +1,27 @@
+============
+django-referrals
+============
+
+
+
+Detailed documentation is in the "docs" directory.
+
+Quick start
+-----------
+
+1. Add "referrals" to your INSTALLED_APPS setting like this::
+
+    INSTALLED_APPS = [
+        ...,
+        "referrals",
+    ]
+
+2. Include the polls URLconf in your project urls.py like this::
+
+    path("referrals/", include("django-referrals.urls")),
+
+3. Run ``python manage.py migrate`` to create the models.
+
+4. Start the development server and visit the admin to create a poll.
+
+5. Visit the ``/referrals/`` URL to participate in the poll.

django-referral-system-0.1/django_referral_system.egg-info/PKG-INFO

@@ -0,0 +1,30 @@
+Metadata-Version: 2.1
+Name: django-referral-system
+Version: 0.1
+Summary: A Django app for managing referral programs, promoters, referrals, and tracking referral performance with advanced features like commission setting, invitation management, and Wise payouts.
+Home-page: https://github.com/soldatov-ss/django-referral-system.git
+Author: Soldatov Serhii
+Author-email: soldatov.own@gmail.com
+License: MIT
+Classifier: Environment :: Web Environment
+Classifier: Framework :: Django
+Classifier: Framework :: Django :: 4
+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 :: Only
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
+Requires-Python: >=3.8
+License-File: LICENSE
+Requires-Dist: Django>=4.1
+Requires-Dist: djangorestframework>=3.14
+Requires-Dist: pandas>=2.0
+Requires-Dist: pydantic>=2.0
+Requires-Dist: python-dotenv>=1.0

django-referral-system-0.1/django_referral_system.egg-info/SOURCES.txt

@@ -0,0 +1,43 @@
+LICENSE
+MANIFEST.in
+README.md
+pyproject.toml
+setup.cfg
+setup.py
+django_referral_system.egg-info/PKG-INFO
+django_referral_system.egg-info/SOURCES.txt
+django_referral_system.egg-info/dependency_links.txt
+django_referral_system.egg-info/requires.txt
+django_referral_system.egg-info/top_level.txt
+referrals/__init__.py
+referrals/admin.py
+referrals/apps.py
+referrals/choices.py
+referrals/config.py
+referrals/enums.py
+referrals/exceptions.py
+referrals/helpers.py
+referrals/models.py
+referrals/serializers.py
+referrals/tests.py
+referrals/urls.py
+referrals/utils.py
+referrals/views.py
+referrals/dtos/__init__.py
+referrals/dtos/base_dto.py
+referrals/dtos/promoters_dtos.py
+referrals/migrations/0001_initial.py
+referrals/migrations/0002_alter_payoutmethod_method_and_more.py
+referrals/migrations/__init__.py
+referrals/migrations/__pycache__/0001_initial.cpython-310.pyc
+referrals/migrations/__pycache__/__init__.cpython-310.pyc
+referrals/repositories/__init__.py
+referrals/repositories/base_repository.py
+referrals/repositories/promoter_commission_repository.py
+referrals/repositories/promoter_payout_repository.py
+referrals/repositories/promoter_repository.py
+referrals/repositories/referral_repository.py
+referrals/services/__init__.py
+referrals/services/promoter_payout_service.py
+referrals/services/promoter_service.py
+referrals/services/referral_service.py

django-referral-system-0.1/django_referral_system.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

django-referral-system-0.1/django_referral_system.egg-info/requires.txt

@@ -0,0 +1,5 @@
+Django>=4.1
+djangorestframework>=3.14
+pandas>=2.0
+pydantic>=2.0
+python-dotenv>=1.0

django-referral-system-0.1/django_referral_system.egg-info/top_level.txt

@@ -0,0 +1 @@
+referrals

django-referral-system-0.1/pyproject.toml

@@ -0,0 +1,3 @@
+[build-system]
+requires = ['setuptools>=72.2.0']
+build-backend = 'setuptools.build_meta'

django-referral-system-0.1/referrals/admin.py

@@ -0,0 +1,52 @@
+from django.contrib import admin
+
+from referrals.models import ReferralProgram, PayoutMethod, Referral, Promoter, PromoterCommission, \
+    PromoterPayout
+
+
+@admin.register(ReferralProgram)
+class ReferralProgramAdmin(admin.ModelAdmin):
+    list_display = ("name", "commission_rate", "is_active", "id")
+
+
+@admin.register(PayoutMethod)
+class PayoutMethodAdmin(admin.ModelAdmin):
+    list_display = ("method", "payment_address")
+
+
+@admin.register(Referral)
+class ReferralAdmin(admin.ModelAdmin):
+    autocomplete_fields = (
+        "user",
+        "promoter",
+    )
+    list_display = (
+        "id",
+        "user",
+        "promoter",
+        "invitation_method",
+        "status",
+    )
+    search_fields = ("id",)
+    list_filter = ("status", "invitation_method", "id")
+
+
+@admin.register(Promoter)
+class PromoterAdmin(admin.ModelAdmin):
+    autocomplete_fields = ("user",)
+    search_fields = ("user__email",)
+    list_display = ("referral_link", "referral_token", "user", "id")
+
+
+@admin.register(PromoterCommission)
+class PromoterCommissionAdmin(admin.ModelAdmin):
+    search_fields = ("promoter__user__email",)
+    list_display = ("promoter", "referral", "amount", "status")
+    list_filter = ("status", "amount")
+
+
+@admin.register(PromoterPayout)
+class PromoterPayoutsAdmin(admin.ModelAdmin):
+    search_fields = ("promoter_user_email",)
+    list_display = ("promoter", "amount", "payout_method", "created")
+    list_filter = ("payout_method",)

django-referral-system-0.1/referrals/apps.py

@@ -0,0 +1,7 @@
+from django.apps import AppConfig
+
+
+class ReferralsConfig(AppConfig):
+    default_auto_field = "django.db.models.BigAutoField"
+    name = 'referrals'
+    verbose_name = 'Referrals'

django-referral-system-0.1/referrals/choices.py

@@ -0,0 +1,19 @@
+from django.db import models
+
+
+class ReferralStateChoices(models.TextChoices):
+    SIGNUP = "signup"
+    ACTIVE = "active"
+    REFUND = "refund"
+
+
+class InvitationMethodChoices(models.TextChoices):
+    EMAIL = "email"
+    LINK = "link"
+
+
+class PromoterCommissionStatusChoices(models.TextChoices):
+    PENDING = "pending"
+    PAID = "paid"
+    FAILED = "failed"
+    REFUND = "refund"

django-referral-system-0.1/referrals/config.py

@@ -0,0 +1,13 @@
+import os
+
+from dotenv import load_dotenv
+
+load_dotenv()
+
+
+class Config:
+    BASE_REFERRAL_LINK = os.getenv('BASE_REFERRAL_LINK')
+    BASE_EMAIL = os.getenv('BASE_EMAIL')
+
+
+config = Config()

django-referral-system-0.1/referrals/dtos/base_dto.py

@@ -0,0 +1,6 @@
+from pydantic import BaseModel
+
+
+class BaseModelDTO(BaseModel):
+    class Config:
+        populate_by_name = True

django-referral-system-0.1/referrals/dtos/promoters_dtos.py

@@ -0,0 +1,66 @@
+from datetime import datetime
+from typing import List, Optional
+
+from pydantic import Field
+
+from referrals.dtos.base_dto import BaseModelDTO
+from referrals.enums import PayoutStatusEnum
+
+
+class PromotionDTO(BaseModelDTO):
+    id: int
+    ref_id: str = Field(alias="refId")
+    promoter_id: int = Field(alias="promoterId")
+    referral_link: str = Field(alias="referralLink")
+    visitors_count: int = Field(alias="visitorsCount")
+    leads_count: int = Field(alias="leadsCount")
+    customers_count: int = Field(alias="customersCount")
+    refunds_count: int = Field(alias="refundsCount")
+    cancellations_count: int = Field(alias="cancellationsCount")
+
+
+class BalanceDTO(BaseModelDTO):
+    cash: int
+
+
+class PromoterDTO(BaseModelDTO):
+    id: int
+    status: str
+    cust_id: Optional[str] = Field(alias="custId")
+    email: str
+    created_at: datetime = Field(alias="createdAt")
+    promotions: List[PromotionDTO]
+    earnings_balance: Optional[BalanceDTO] = Field(alias="earningsBalance")
+    current_balance: Optional[BalanceDTO] = Field(alias="currentBalance")
+    paid_balance: Optional[BalanceDTO] = Field(alias="paidBalance")
+
+
+class ReferralDTO(BaseModelDTO):
+    id: int
+    state: str
+    email: str
+    promotion: PromotionDTO
+    promoter: PromoterDTO
+
+
+class ReferralListDTO(BaseModelDTO):
+    count: int | None
+    page_size: int
+    page: int
+    results: List[ReferralDTO]
+
+
+class PromoterPayoutDTO(BaseModelDTO):
+    status: PayoutStatusEnum
+    amount: int
+    unit: str
+    created_at: str = Field(alias="createdAt")
+    date_paid: str | None = Field(default=None, alias="datePaid")
+    due_date: str | None = Field(default=None, alias="dueDate")
+
+
+class PromoterCryptoPayoutDataRow(BaseModelDTO):
+    name: str
+    email: str
+    address: str
+    amount: float

django-referral-system-0.1/referrals/enums.py

@@ -0,0 +1,17 @@
+from enum import Enum
+
+
+class ReferralStateEnum(Enum):
+    SIGNUP = "signup"
+    INVITED = "invited"
+    ACTIVE = "active"
+
+
+class PayoutStatusEnum(Enum):
+    PENDING = "pending"
+    COMPLETED = "completed"
+    PROCESSING = "processing"
+
+
+class CryptoPayoutTokenIdsEnum(Enum):
+    USDC = "usd-coin"

django-referral-system-0.1/referrals/exceptions.py

@@ -0,0 +1,16 @@
+from typing import Union
+
+
+class BaseAPIException(Exception):
+    """
+    Base API exception.
+    """
+
+    def __init__(self, error_message: Union[str, dict], status_code: int):
+        self.error_message = error_message
+        self.status_code = status_code
+        super().__init__(self.error_message)
+
+
+class ViewException(BaseAPIException):
+    """Base view exception."""

django-referral-system-0.1/referrals/helpers.py

@@ -0,0 +1,9 @@
+from io import StringIO
+
+import pandas as pd
+
+
+def parse_df_to_csv_string_without_index_col(df: pd.DataFrame) -> str:
+    with StringIO() as buffer:
+        df.to_csv(buffer, index=False)
+        return buffer.getvalue()

django-referral-system-0.1/referrals/migrations/0001_initial.py

@@ -0,0 +1,107 @@
+# Generated by Django 5.1 on 2024-08-17 19:32
+
+import django.core.validators
+import django.db.models.deletion
+from decimal import Decimal
+from django.conf import settings
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    initial = True
+
+    dependencies = [
+        migrations.swappable_dependency(settings.AUTH_USER_MODEL),
+    ]
+
+    operations = [
+        migrations.CreateModel(
+            name='PayoutMethod',
+            fields=[
+                ('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                ('method', models.CharField(choices=[('wise', 'Wise'), ('crypto', 'Crypto')], max_length=10)),
+                ('payment_address', models.CharField(help_text='Payment address (email or solana wallet)', max_length=100)),
+            ],
+        ),
+        migrations.CreateModel(
+            name='ReferralProgram',
+            fields=[
+                ('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                ('created', models.DateTimeField(auto_now_add=True)),
+                ('updated', models.DateTimeField(auto_now=True)),
+                ('name', models.CharField(max_length=255, unique=True)),
+                ('commission_rate', models.DecimalField(decimal_places=2, help_text='Commission rate as a percentage', max_digits=5, validators=[django.core.validators.MinValueValidator(Decimal('0.01'))])),
+                ('is_active', models.BooleanField(default=True, help_text='Indicates if this is the currently active referral program')),
+                ('min_withdrawal_balance', models.DecimalField(decimal_places=2, default=0.0, help_text='Minimum balance required to withdraw earnings', max_digits=10)),
+            ],
+            options={
+                'abstract': False,
+            },
+        ),
+        migrations.CreateModel(
+            name='Promoter',
+            fields=[
+                ('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                ('created', models.DateTimeField(auto_now_add=True)),
+                ('updated', models.DateTimeField(auto_now=True)),
+                ('referral_token', models.CharField(blank=True, help_text='Referral token', max_length=256, null=True, unique=True)),
+                ('referral_link', models.CharField(blank=True, help_text='Referral link', max_length=256, null=True, unique=True)),
+                ('link_clicked', models.IntegerField(default=0)),
+                ('min_withdrawal_balance', models.DecimalField(decimal_places=2, default=0.0, help_text='Custom minimum balance required to withdraw earnings', max_digits=10)),
+                ('active_payout_method', models.ForeignKey(blank=True, null=True, on_delete=django.db.models.deletion.SET_NULL, to='referrals.payoutmethod')),
+                ('user', models.OneToOneField(on_delete=django.db.models.deletion.CASCADE, related_name='promoter', to=settings.AUTH_USER_MODEL)),
+            ],
+            options={
+                'abstract': False,
+            },
+        ),
+        migrations.CreateModel(
+            name='PromoterPayout',
+            fields=[
+                ('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                ('created', models.DateTimeField(auto_now_add=True)),
+                ('updated', models.DateTimeField(auto_now=True)),
+                ('amount', models.IntegerField()),
+                ('payout_method', models.CharField(choices=[('wise', 'Wise'), ('crypto', 'Crypto')], max_length=10)),
+                ('tx_signature', models.CharField(blank=True, max_length=255, null=True)),
+                ('promoter', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, related_name='promoter_payouts', to='referrals.promoter')),
+            ],
+            options={
+                'abstract': False,
+            },
+        ),
+        migrations.CreateModel(
+            name='Referral',
+            fields=[
+                ('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                ('created', models.DateTimeField(auto_now_add=True)),
+                ('updated', models.DateTimeField(auto_now=True)),
+                ('invitation_method', models.CharField(choices=[('email', 'Email'), ('link', 'Link')], max_length=10)),
+                ('status', models.CharField(choices=[('signup', 'Signup'), ('active', 'Active'), ('refund', 'Refund')], max_length=10)),
+                ('commission_rate', models.DecimalField(decimal_places=2, default=0.0, help_text='Commission rate at the moment of creating the referral', max_digits=5)),
+                ('promoter', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, related_name='referrals', to='referrals.promoter')),
+                ('user', models.OneToOneField(on_delete=django.db.models.deletion.CASCADE, related_name='referral', to=settings.AUTH_USER_MODEL)),
+            ],
+            options={
+                'abstract': False,
+            },
+        ),
+        migrations.CreateModel(
+            name='PromoterCommission',
+            fields=[
+                ('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                ('created', models.DateTimeField(auto_now_add=True)),
+                ('updated', models.DateTimeField(auto_now=True)),
+                ('amount', models.IntegerField(null=True)),
+                ('status', models.CharField(choices=[('pending', 'Pending'), ('paid', 'Paid'), ('failed', 'Failed'), ('refund', 'Refund')], default='pending', max_length=10)),
+                ('failure_reason', models.TextField(blank=True, null=True)),
+                ('invoice_external_id', models.CharField(blank=True, help_text='Chargebee invoice ID', max_length=255, null=True)),
+                ('promoter', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, related_name='promoter_commission', to='referrals.promoter')),
+                ('referral', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, related_name='referral_commission', to='referrals.referral')),
+            ],
+            options={
+                'abstract': False,
+            },
+        ),
+    ]

django-referral-system-0.1/referrals/migrations/0002_alter_payoutmethod_method_and_more.py

@@ -0,0 +1,28 @@
+# Generated by Django 5.1 on 2024-08-24 14:32
+
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('referrals', '0001_initial'),
+    ]
+
+    operations = [
+        migrations.AlterField(
+            model_name='payoutmethod',
+            name='method',
+            field=models.CharField(help_text='Payout method (e.g., wise, crypto, etc.)', max_length=20),
+        ),
+        migrations.AlterField(
+            model_name='promotercommission',
+            name='invoice_external_id',
+            field=models.CharField(blank=True, help_text='e.g. Chargebee invoice ID', max_length=255, null=True),
+        ),
+        migrations.AlterField(
+            model_name='promoterpayout',
+            name='payout_method',
+            field=models.CharField(help_text='Payout method (e.g., wise, crypto, etc.)', max_length=20),
+        ),
+    ]