django-cfg 1.2.20__py3-none-any.whl → 1.2.22__py3-none-any.whl

django_cfg/apps/payments/migrations/__init__.py

@@ -0,0 +1 @@
+# Migrations package

django_cfg/apps/payments/models/__init__.py

@@ -0,0 +1,49 @@
+"""
+Universal payments models package.
+
+Django ORM models for the universal payments system.
+"""
+
+# Base models
+from .base import TimestampedModel
+
+# Currency models
+from .currencies import Currency, CurrencyNetwork
+
+# Payment models  
+from .payments import UniversalPayment
+
+# Balance models
+from .balance import UserBalance, Transaction
+
+# Subscription models
+from .subscriptions import EndpointGroup, Subscription
+
+# Tariff models
+from .tariffs import Tariff, TariffEndpointGroup
+
+# API Keys
+from .api_keys import APIKey
+
+# Event sourcing
+from .events import PaymentEvent
+
+__all__ = [
+    # Base
+    'TimestampedModel',
+    
+    # Currencies
+    'Currency',
+    'CurrencyNetwork',
+    
+    # Models
+    'UniversalPayment',
+    'UserBalance',
+    'Transaction', 
+    'EndpointGroup',
+    'Subscription',
+    'Tariff',
+    'TariffEndpointGroup',
+    'APIKey',
+    'PaymentEvent',
+]

django_cfg/apps/payments/models/api_keys.py

@@ -0,0 +1,96 @@
+"""
+API key models for the universal payments system.
+"""
+
+from django.db import models
+from django.contrib.auth import get_user_model
+from django.utils import timezone
+from .base import TimestampedModel
+
+User = get_user_model()
+
+
+class APIKey(TimestampedModel):
+    """API keys for authentication and usage tracking."""
+    
+    user = models.ForeignKey(
+        User,
+        on_delete=models.CASCADE,
+        related_name='api_keys',
+        help_text="API key owner"
+    )
+    
+    # Key details
+    name = models.CharField(
+        max_length=100,
+        help_text="Human-readable key name"
+    )
+    key_value = models.CharField(
+        max_length=255,
+        unique=True,
+        help_text="API key value (plain text)"
+    )
+    key_prefix = models.CharField(
+        max_length=20,
+        help_text="Key prefix for identification"
+    )
+    
+    # Permissions
+    is_active = models.BooleanField(
+        default=True,
+        help_text="Is key active"
+    )
+    
+    # Usage tracking
+    last_used = models.DateTimeField(
+        null=True,
+        blank=True,
+        help_text="Last usage timestamp"
+    )
+    usage_count = models.PositiveBigIntegerField(
+        default=0,
+        help_text="Total usage count"
+    )
+    
+    # Lifecycle
+    expires_at = models.DateTimeField(
+        null=True,
+        blank=True,
+        help_text="Key expiration"
+    )
+    
+    # Import and assign manager
+    from ..managers import APIKeyManager
+    objects = APIKeyManager()
+    
+    class Meta:
+        db_table = 'api_keys'
+        verbose_name = "API Key"
+        verbose_name_plural = "API Keys"
+        indexes = [
+            models.Index(fields=['user', 'is_active']),
+            models.Index(fields=['key_value']),
+            models.Index(fields=['key_prefix']),
+            models.Index(fields=['last_used']),
+            models.Index(fields=['expires_at']),
+        ]
+        ordering = ['-created_at']
+    
+    def __str__(self):
+        return f"API Key: {self.name} ({self.key_prefix}***)"
+    
+    def is_valid(self) -> bool:
+        """Check if API key is valid."""
+        if not self.is_active:
+            return False
+        
+        if self.expires_at and self.expires_at <= timezone.now():
+            return False
+        
+        return True
+    
+    def record_usage(self):
+        """Record API key usage."""
+        self.usage_count += 1
+        self.last_used = timezone.now()
+        self.save(update_fields=['usage_count', 'last_used'])

django_cfg/apps/payments/models/balance.py

@@ -0,0 +1,209 @@
+"""
+Balance and transaction models for the universal payments system.
+"""
+
+from django.db import models, transaction
+from django.contrib.auth import get_user_model
+from django.core.validators import MinValueValidator
+from django.core.exceptions import ValidationError
+from django.utils import timezone
+from .base import TimestampedModel
+
+User = get_user_model()
+
+
+class UserBalance(TimestampedModel):
+    """User balance model for tracking USD funds."""
+    
+    user = models.OneToOneField(
+        User,
+        on_delete=models.CASCADE,
+        related_name='balance',
+        help_text="User who owns this balance"
+    )
+    amount_usd = models.FloatField(
+        default=0.0,
+        validators=[MinValueValidator(0.0)],
+        help_text="Current balance in USD"
+    )
+    reserved_usd = models.FloatField(
+        default=0.0,
+        validators=[MinValueValidator(0.0)],
+        help_text="Reserved balance in USD (for pending transactions)"
+    )
+    total_earned = models.FloatField(
+        default=0.0,
+        validators=[MinValueValidator(0.0)],
+        help_text="Total amount earned (lifetime)"
+    )
+    total_spent = models.FloatField(
+        default=0.0,
+        validators=[MinValueValidator(0.0)],
+        help_text="Total amount spent (lifetime)"
+    )
+    last_transaction_at = models.DateTimeField(
+        null=True,
+        blank=True,
+        help_text="When the last transaction occurred"
+    )
+
+    # Import and assign manager
+    from ..managers import UserBalanceManager
+    objects = UserBalanceManager()
+
+    class Meta:
+        db_table = 'user_balances'
+        verbose_name = "User Balance"
+        verbose_name_plural = "User Balances"
+        indexes = [
+            models.Index(fields=['user']),
+            models.Index(fields=['amount_usd']),
+            models.Index(fields=['last_transaction_at']),
+        ]
+
+    def __str__(self):
+        return f"{self.user.email} - ${self.amount_usd}"
+
+    @property
+    def total_balance(self) -> float:
+        """Get total balance (available + reserved)."""
+        return self.amount_usd + self.reserved_usd
+
+    @property
+    def has_sufficient_funds(self) -> bool:
+        """Check if user has sufficient available funds."""
+        return self.amount_usd > 0
+
+    def can_debit(self, amount: float) -> bool:
+        """Check if user can be debited the specified amount."""
+        return self.amount_usd >= amount
+
+    def get_transaction_summary(self):
+        """Get transaction summary for this user."""
+        transactions = self.user.transactions.all()
+        return {
+            'total_transactions': transactions.count(),
+            'total_payments': transactions.filter(transaction_type=Transaction.TransactionType.PAYMENT).count(),
+            'total_subscriptions': transactions.filter(transaction_type=Transaction.TransactionType.SUBSCRIPTION).count(),
+            'total_refunds': transactions.filter(transaction_type=Transaction.TransactionType.REFUND).count(),
+        }
+
+
+class Transaction(TimestampedModel):
+    """Transaction history model."""
+    
+    class TransactionType(models.TextChoices):
+        PAYMENT = "payment", "Payment"
+        SUBSCRIPTION = "subscription", "Subscription"
+        REFUND = "refund", "Refund"
+        CREDIT = "credit", "Credit"
+        DEBIT = "debit", "Debit"
+        HOLD = "hold", "Hold"
+        RELEASE = "release", "Release"
+        FEE = "fee", "Fee"
+        ADJUSTMENT = "adjustment", "Adjustment"
+    
+    user = models.ForeignKey(
+        User,
+        on_delete=models.CASCADE,
+        related_name='transactions',
+        help_text="User who made this transaction"
+    )
+    amount_usd = models.FloatField(
+        help_text="Transaction amount in USD (positive for credits, negative for debits)"
+    )
+    transaction_type = models.CharField(
+        max_length=20,
+        choices=TransactionType.choices,
+        help_text="Type of transaction"
+    )
+    description = models.TextField(
+        help_text="Human-readable description of the transaction"
+    )
+    balance_before = models.FloatField(
+        help_text="User balance before this transaction"
+    )
+    balance_after = models.FloatField(
+        help_text="User balance after this transaction"
+    )
+    
+    # Related objects (nullable for flexibility)
+    from .payments import UniversalPayment
+    from .subscriptions import Subscription
+    payment = models.ForeignKey(
+        UniversalPayment,
+        on_delete=models.SET_NULL,
+        null=True,
+        blank=True,
+        related_name='transactions',
+        help_text="Related payment (if applicable)"
+    )
+    subscription = models.ForeignKey(
+        Subscription,
+        on_delete=models.SET_NULL,
+        null=True,
+        blank=True,
+        related_name='transactions',
+        help_text="Related subscription (if applicable)"
+    )
+    
+    # Additional metadata
+    reference_id = models.CharField(
+        max_length=255,
+        null=True,
+        blank=True,
+        help_text="External reference ID"
+    )
+    metadata = models.JSONField(
+        default=dict,
+        help_text="Additional transaction metadata"
+    )
+
+    class Meta:
+        db_table = 'user_transactions'
+        verbose_name = "Transaction"
+        verbose_name_plural = "Transactions"
+        indexes = [
+            models.Index(fields=['user', 'created_at']),
+            models.Index(fields=['transaction_type']),
+            models.Index(fields=['amount_usd']),
+            models.Index(fields=['created_at']),
+            models.Index(fields=['reference_id']),
+        ]
+        ordering = ['-created_at']
+
+    def __str__(self):
+        sign = "+" if self.amount_usd >= 0 else ""
+        return f"{self.user.email} - {sign}${self.amount_usd} ({self.get_transaction_type_display()})"
+
+    @property
+    def is_credit(self) -> bool:
+        """Check if this is a credit transaction."""
+        return self.amount_usd > 0
+
+    @property
+    def is_debit(self) -> bool:
+        """Check if this is a debit transaction."""
+        return self.amount_usd < 0
+
+    def clean(self):
+        """Validate transaction data."""
+        
+        # Validate balance calculation
+        expected_balance = self.balance_before + self.amount_usd
+        if abs(expected_balance - self.balance_after) > 0.01:  # Allow for rounding
+            raise ValidationError(
+                f"Balance calculation error: {self.balance_before} + {self.amount_usd} != {self.balance_after}"
+            )
+        
+        # Validate transaction type and amount sign
+        if self.transaction_type == self.TransactionType.PAYMENT and self.amount_usd <= 0:
+            raise ValidationError("Payment transactions must have positive amounts")
+        
+        if self.transaction_type == self.TransactionType.SUBSCRIPTION and self.amount_usd >= 0:
+            raise ValidationError("Subscription transactions must have negative amounts")
+
+    def save(self, *args, **kwargs):
+        """Override save to run validation."""
+        self.clean()
+        super().save(*args, **kwargs)

django_cfg/apps/payments/models/base.py

@@ -0,0 +1,14 @@
+"""
+Base model classes for the universal payments system.
+"""
+
+from django.db import models
+
+
+class TimestampedModel(models.Model):
+    """Base model with automatic timestamps."""
+    created_at = models.DateTimeField(auto_now_add=True, db_index=True)
+    updated_at = models.DateTimeField(auto_now=True)
+    
+    class Meta:
+        abstract = True

django_cfg/apps/payments/models/currencies.py

@@ -0,0 +1,138 @@
+"""
+Currency models for the universal payments system.
+"""
+
+from django.db import models
+from .base import TimestampedModel
+
+
+class Currency(TimestampedModel):
+    """Supported currencies for payments."""
+    
+    class CurrencyType(models.TextChoices):
+        FIAT = "fiat", "Fiat Currency"
+        CRYPTO = "crypto", "Cryptocurrency"
+    
+    code = models.CharField(
+        max_length=10,
+        unique=True,
+        help_text="Currency code (e.g., USD, BTC, ETH)"
+    )
+    name = models.CharField(
+        max_length=100,
+        help_text="Full currency name"
+    )
+    symbol = models.CharField(
+        max_length=10,
+        help_text="Currency symbol (e.g., $, ₿, Ξ)"
+    )
+    currency_type = models.CharField(
+        max_length=10,
+        choices=CurrencyType.choices,
+        help_text="Type of currency"
+    )
+    decimal_places = models.PositiveSmallIntegerField(
+        default=2,
+        help_text="Number of decimal places for this currency"
+    )
+    is_active = models.BooleanField(
+        default=True,
+        help_text="Whether this currency is active for payments"
+    )
+    min_payment_amount = models.FloatField(
+        default=1.0,
+        help_text="Minimum payment amount for this currency"
+    )
+    
+    # Exchange rate to USD (base currency)
+    usd_rate = models.FloatField(
+        default=1.0,
+        help_text="Exchange rate to USD (1 unit of this currency = X USD)"
+    )
+    rate_updated_at = models.DateTimeField(
+        null=True,
+        blank=True,
+        help_text="When the exchange rate was last updated"
+    )
+    
+    # Import and assign manager
+    from ..managers import CurrencyManager
+    objects = CurrencyManager()
+    
+    class Meta:
+        db_table = 'payment_currencies'
+        verbose_name = "Currency"
+        verbose_name_plural = "Currencies"
+        indexes = [
+            models.Index(fields=['code']),
+            models.Index(fields=['currency_type']),
+            models.Index(fields=['is_active']),
+        ]
+        ordering = ['code']
+    
+    def __str__(self):
+        return f"{self.code} - {self.name}"
+    
+    @property
+    def is_fiat(self) -> bool:
+        """Check if this is a fiat currency."""
+        return self.currency_type == self.CurrencyType.FIAT
+    
+    @property
+    def is_crypto(self) -> bool:
+        """Check if this is a cryptocurrency."""
+        return self.currency_type == self.CurrencyType.CRYPTO
+    
+    def to_usd(self, amount: float) -> float:
+        """Convert amount of this currency to USD."""
+        return amount * self.usd_rate
+    
+    def from_usd(self, usd_amount: float) -> float:
+        """Convert USD amount to this currency."""
+        if self.usd_rate == 0:
+            return 0
+        return usd_amount / self.usd_rate
+
+
+class CurrencyNetwork(TimestampedModel):
+    """Networks/blockchains for cryptocurrencies."""
+    
+    currency = models.ForeignKey(
+        Currency,
+        on_delete=models.CASCADE,
+        related_name='networks',
+        help_text="Currency this network supports"
+    )
+    network_name = models.CharField(
+        max_length=50,
+        help_text="Network name (e.g., mainnet, polygon, bsc)"
+    )
+    network_code = models.CharField(
+        max_length=20,
+        help_text="Network code for API integration"
+    )
+    is_active = models.BooleanField(
+        default=True,
+        help_text="Whether this network is active"
+    )
+    confirmation_blocks = models.PositiveIntegerField(
+        default=1,
+        help_text="Number of confirmations required"
+    )
+    
+    # Import and assign manager
+    from ..managers import CurrencyNetworkManager
+    objects = CurrencyNetworkManager()
+    
+    class Meta:
+        db_table = 'payment_currency_networks'
+        verbose_name = "Currency Network"
+        verbose_name_plural = "Currency Networks"
+        unique_together = [['currency', 'network_code']]
+        indexes = [
+            models.Index(fields=['currency', 'is_active']),
+            models.Index(fields=['network_code']),
+        ]
+    
+    def __str__(self):
+        return f"{self.currency.code} - {self.network_name}"

django_cfg/apps/payments/models/events.py

@@ -0,0 +1,73 @@
+"""
+Event sourcing models for the universal payments system.
+"""
+
+from django.db import models
+from .base import TimestampedModel
+
+
+class PaymentEvent(TimestampedModel):
+    """Event sourcing for payment operations - immutable audit trail."""
+    
+    class EventType(models.TextChoices):
+        PAYMENT_CREATED = 'payment_created', 'Payment Created'
+        WEBHOOK_RECEIVED = 'webhook_received', 'Webhook Received'
+        WEBHOOK_PROCESSED = 'webhook_processed', 'Webhook Processed'
+        BALANCE_UPDATED = 'balance_updated', 'Balance Updated'
+        REFUND_PROCESSED = 'refund_processed', 'Refund Processed'
+        STATUS_CHANGED = 'status_changed', 'Status Changed'
+        ERROR_OCCURRED = 'error_occurred', 'Error Occurred'
+    
+    # Event identification
+    payment_id = models.CharField(
+        max_length=255,
+        db_index=True,
+        help_text="Payment identifier"
+    )
+    event_type = models.CharField(
+        max_length=50,
+        choices=EventType.choices,
+        db_index=True,
+        help_text="Type of event"
+    )
+    sequence_number = models.PositiveBigIntegerField(
+        help_text="Sequential number per payment"
+    )
+    
+    # Event data (JSON for flexibility)
+    event_data = models.JSONField(
+        help_text="Event data payload"
+    )
+    
+    # Operational metadata
+    processed_by = models.CharField(
+        max_length=100,
+        help_text="Worker/server that processed this event"
+    )
+    correlation_id = models.CharField(
+        max_length=255,
+        null=True,
+        blank=True,
+        help_text="Correlation ID for tracing"
+    )
+    idempotency_key = models.CharField(
+        max_length=255,
+        unique=True,
+        help_text="Idempotency key to prevent duplicates"
+    )
+    
+    class Meta:
+        db_table = 'payment_events'
+        verbose_name = "Payment Event"
+        verbose_name_plural = "Payment Events"
+        indexes = [
+            models.Index(fields=['payment_id', 'sequence_number']),
+            models.Index(fields=['event_type', 'created_at']),
+            models.Index(fields=['idempotency_key']),
+            models.Index(fields=['correlation_id']),
+            models.Index(fields=['created_at']),
+        ]
+        ordering = ['sequence_number']
+    
+    def __str__(self):
+        return f"Event {self.sequence_number}: {self.event_type} for {self.payment_id}"