payplus-python 0.1.2__py3-none-any.whl

payplus/models/payment.py

@@ -0,0 +1,179 @@
+"""
+Payment model for tracking payments.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Optional, Any
+from decimal import Decimal
+from enum import Enum
+
+from pydantic import BaseModel, Field
+
+
+class PaymentStatus(str, Enum):
+    """Payment status."""
+    PENDING = "pending"
+    PROCESSING = "processing"
+    SUCCEEDED = "succeeded"
+    FAILED = "failed"
+    CANCELED = "canceled"
+    REFUNDED = "refunded"
+    PARTIALLY_REFUNDED = "partially_refunded"
+
+
+class PaymentMethod(str, Enum):
+    """Payment method type."""
+    CARD = "card"
+    BANK_TRANSFER = "bank_transfer"
+    DIRECT_DEBIT = "direct_debit"
+
+
+class RefundReason(str, Enum):
+    """Refund reason codes."""
+    REQUESTED_BY_CUSTOMER = "requested_by_customer"
+    DUPLICATE = "duplicate"
+    FRAUDULENT = "fraudulent"
+    SERVICE_NOT_PROVIDED = "service_not_provided"
+    OTHER = "other"
+
+
+class Refund(BaseModel):
+    """Refund record."""
+    
+    id: str
+    amount: Decimal
+    currency: str = "ILS"
+    reason: Optional[RefundReason] = None
+    status: str = "succeeded"
+    payplus_refund_uid: Optional[str] = None
+    created_at: datetime = Field(default_factory=datetime.utcnow)
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+
+class Payment(BaseModel):
+    """
+    Payment model for tracking individual payments.
+    
+    This tracks both successful and failed payment attempts,
+    linked to subscriptions and invoices.
+    """
+    
+    id: str = Field(..., description="Unique payment ID")
+    customer_id: str = Field(..., description="Customer ID")
+    subscription_id: Optional[str] = Field(None, description="Subscription ID if recurring")
+    invoice_id: Optional[str] = Field(None, description="Invoice ID")
+    
+    # PayPlus integration
+    payplus_transaction_uid: Optional[str] = Field(None, description="PayPlus transaction UID")
+    payplus_approval_number: Optional[str] = Field(None, description="Credit card approval number")
+    
+    # Amount
+    amount: Decimal = Field(..., description="Payment amount")
+    currency: str = Field(default="ILS", description="Currency code")
+    
+    # Payment method
+    payment_method_type: PaymentMethod = Field(default=PaymentMethod.CARD)
+    payment_method_id: Optional[str] = Field(None, description="Payment method ID used")
+    card_last_four: Optional[str] = Field(None, description="Last 4 digits of card")
+    card_brand: Optional[str] = Field(None, description="Card brand")
+    
+    # Status
+    status: PaymentStatus = Field(default=PaymentStatus.PENDING)
+    failure_code: Optional[str] = Field(None, description="Failure code if failed")
+    failure_message: Optional[str] = Field(None, description="Failure message")
+    
+    # Refunds
+    refunds: list[Refund] = Field(default_factory=list)
+    amount_refunded: Decimal = Field(default=Decimal("0"))
+    
+    # Installments
+    installments: int = Field(default=1, description="Number of installments")
+    installment_number: Optional[int] = Field(None, description="Current installment number")
+    
+    # Description
+    description: Optional[str] = None
+    statement_descriptor: Optional[str] = None
+    
+    # Receipt
+    receipt_email: Optional[str] = None
+    receipt_url: Optional[str] = None
+    
+    # Metadata
+    metadata: dict[str, Any] = Field(default_factory=dict)
+    
+    # Timestamps
+    created_at: datetime = Field(default_factory=datetime.utcnow)
+    updated_at: datetime = Field(default_factory=datetime.utcnow)
+    paid_at: Optional[datetime] = None
+    
+    @property
+    def is_successful(self) -> bool:
+        """Check if payment was successful."""
+        return self.status == PaymentStatus.SUCCEEDED
+    
+    @property
+    def is_refunded(self) -> bool:
+        """Check if payment was fully refunded."""
+        return self.status == PaymentStatus.REFUNDED
+    
+    @property
+    def net_amount(self) -> Decimal:
+        """Get net amount after refunds."""
+        return self.amount - self.amount_refunded
+    
+    def add_refund(
+        self,
+        refund_id: str,
+        amount: Decimal,
+        reason: Optional[RefundReason] = None,
+        payplus_refund_uid: Optional[str] = None,
+    ) -> Refund:
+        """Add a refund to this payment."""
+        refund = Refund(
+            id=refund_id,
+            amount=amount,
+            currency=self.currency,
+            reason=reason,
+            payplus_refund_uid=payplus_refund_uid,
+        )
+        self.refunds.append(refund)
+        self.amount_refunded += amount
+        self.updated_at = datetime.utcnow()
+        
+        if self.amount_refunded >= self.amount:
+            self.status = PaymentStatus.REFUNDED
+        else:
+            self.status = PaymentStatus.PARTIALLY_REFUNDED
+        
+        return refund
+    
+    def mark_succeeded(
+        self,
+        transaction_uid: Optional[str] = None,
+        approval_number: Optional[str] = None,
+    ) -> None:
+        """Mark payment as succeeded."""
+        self.status = PaymentStatus.SUCCEEDED
+        self.paid_at = datetime.utcnow()
+        self.updated_at = datetime.utcnow()
+        
+        if transaction_uid:
+            self.payplus_transaction_uid = transaction_uid
+        if approval_number:
+            self.payplus_approval_number = approval_number
+    
+    def mark_failed(
+        self,
+        failure_code: Optional[str] = None,
+        failure_message: Optional[str] = None,
+    ) -> None:
+        """Mark payment as failed."""
+        self.status = PaymentStatus.FAILED
+        self.failure_code = failure_code
+        self.failure_message = failure_message
+        self.updated_at = datetime.utcnow()
+    
+    class Config:
+        use_enum_values = True

payplus/models/subscription.py

@@ -0,0 +1,193 @@
+"""
+Subscription model for SaaS subscription management.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime, date
+from typing import Optional, Any
+from decimal import Decimal
+from enum import Enum
+
+from pydantic import BaseModel, Field
+
+
+class SubscriptionStatus(str, Enum):
+    """Subscription status."""
+    ACTIVE = "active"
+    TRIALING = "trialing"
+    PAST_DUE = "past_due"
+    PAUSED = "paused"
+    CANCELED = "canceled"
+    UNPAID = "unpaid"
+    INCOMPLETE = "incomplete"
+    INCOMPLETE_EXPIRED = "incomplete_expired"
+
+
+class BillingCycle(str, Enum):
+    """Billing cycle interval."""
+    DAILY = "daily"
+    WEEKLY = "weekly"
+    MONTHLY = "monthly"
+    QUARTERLY = "quarterly"
+    YEARLY = "yearly"
+    
+    def to_interval(self) -> tuple[str, int]:
+        """Convert to interval and count."""
+        mapping = {
+            BillingCycle.DAILY: ("day", 1),
+            BillingCycle.WEEKLY: ("week", 1),
+            BillingCycle.MONTHLY: ("month", 1),
+            BillingCycle.QUARTERLY: ("month", 3),
+            BillingCycle.YEARLY: ("year", 1),
+        }
+        return mapping[self]
+
+
+class SubscriptionItem(BaseModel):
+    """Item in a subscription (for metered billing)."""
+    
+    id: str
+    tier_id: str
+    quantity: int = 1
+    unit_amount: Decimal = Decimal("0")
+    
+    @property
+    def total_amount(self) -> Decimal:
+        return self.unit_amount * self.quantity
+
+
+class Subscription(BaseModel):
+    """
+    Subscription model for managing SaaS subscriptions.
+    
+    This model tracks the subscription lifecycle, billing, and links
+    to the customer and tier.
+    """
+    
+    id: str = Field(..., description="Unique subscription ID")
+    customer_id: str = Field(..., description="Customer ID")
+    tier_id: str = Field(..., description="Pricing tier ID")
+    
+    # PayPlus integration
+    payplus_recurring_uid: Optional[str] = Field(None, description="PayPlus recurring payment UID")
+    payment_method_id: Optional[str] = Field(None, description="Payment method ID used")
+    
+    # Status
+    status: SubscriptionStatus = Field(default=SubscriptionStatus.INCOMPLETE)
+    
+    # Pricing
+    amount: Decimal = Field(..., description="Subscription amount per period")
+    currency: str = Field(default="ILS", description="Currency code")
+    
+    # Billing
+    billing_cycle: BillingCycle = Field(default=BillingCycle.MONTHLY)
+    billing_anchor: Optional[int] = Field(None, description="Day of month for billing (1-28)")
+    
+    # Items (for metered/quantity-based billing)
+    items: list[SubscriptionItem] = Field(default_factory=list)
+    
+    # Trial
+    trial_start: Optional[datetime] = None
+    trial_end: Optional[datetime] = None
+    
+    # Period tracking
+    current_period_start: datetime = Field(default_factory=datetime.utcnow)
+    current_period_end: Optional[datetime] = None
+    
+    # Cancellation
+    cancel_at_period_end: bool = Field(default=False)
+    canceled_at: Optional[datetime] = None
+    ended_at: Optional[datetime] = None
+    cancellation_reason: Optional[str] = None
+    
+    # Pause
+    pause_collection: Optional[dict[str, Any]] = None
+    paused_at: Optional[datetime] = None
+    
+    # Counters
+    invoice_count: int = Field(default=0)
+    failed_payment_count: int = Field(default=0)
+    
+    # Metadata
+    metadata: dict[str, Any] = Field(default_factory=dict)
+    
+    # Timestamps
+    created_at: datetime = Field(default_factory=datetime.utcnow)
+    updated_at: datetime = Field(default_factory=datetime.utcnow)
+    
+    @property
+    def is_active(self) -> bool:
+        """Check if subscription is currently active."""
+        return self.status in (SubscriptionStatus.ACTIVE, SubscriptionStatus.TRIALING)
+    
+    @property
+    def is_trialing(self) -> bool:
+        """Check if subscription is in trial period."""
+        return self.status == SubscriptionStatus.TRIALING
+    
+    @property
+    def is_canceled(self) -> bool:
+        """Check if subscription is canceled."""
+        return self.status == SubscriptionStatus.CANCELED or self.cancel_at_period_end
+    
+    @property
+    def will_renew(self) -> bool:
+        """Check if subscription will renew at period end."""
+        return self.is_active and not self.cancel_at_period_end
+    
+    def cancel(self, at_period_end: bool = True, reason: Optional[str] = None) -> None:
+        """Cancel the subscription."""
+        self.cancel_at_period_end = at_period_end
+        self.cancellation_reason = reason
+        self.canceled_at = datetime.utcnow()
+        self.updated_at = datetime.utcnow()
+        
+        if not at_period_end:
+            self.status = SubscriptionStatus.CANCELED
+            self.ended_at = datetime.utcnow()
+    
+    def pause(self, resume_at: Optional[datetime] = None) -> None:
+        """Pause the subscription."""
+        self.status = SubscriptionStatus.PAUSED
+        self.paused_at = datetime.utcnow()
+        self.pause_collection = {
+            "paused_at": self.paused_at.isoformat(),
+            "resume_at": resume_at.isoformat() if resume_at else None,
+        }
+        self.updated_at = datetime.utcnow()
+    
+    def resume(self) -> None:
+        """Resume a paused subscription."""
+        if self.status == SubscriptionStatus.PAUSED:
+            self.status = SubscriptionStatus.ACTIVE
+            self.paused_at = None
+            self.pause_collection = None
+            self.updated_at = datetime.utcnow()
+    
+    def mark_payment_failed(self) -> None:
+        """Mark a payment as failed."""
+        self.failed_payment_count += 1
+        self.updated_at = datetime.utcnow()
+        
+        # Update status based on failure count
+        if self.failed_payment_count >= 4:
+            self.status = SubscriptionStatus.UNPAID
+        else:
+            self.status = SubscriptionStatus.PAST_DUE
+    
+    def mark_payment_succeeded(self) -> None:
+        """Mark a payment as succeeded."""
+        self.failed_payment_count = 0
+        self.status = SubscriptionStatus.ACTIVE
+        self.invoice_count += 1
+        self.updated_at = datetime.utcnow()
+    
+    def change_tier(self, new_tier_id: str, new_amount: Decimal) -> None:
+        """Change subscription tier."""
+        self.tier_id = new_tier_id
+        self.amount = new_amount
+        self.updated_at = datetime.utcnow()
+    
+    class Config:
+        use_enum_values = True

payplus/models/tier.py

@@ -0,0 +1,226 @@
+"""
+Tier model for pricing plans.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Optional, Any
+from decimal import Decimal
+from enum import Enum
+
+from pydantic import BaseModel, Field
+
+from payplus.models.subscription import BillingCycle
+
+
+class TierType(str, Enum):
+    """Tier pricing type."""
+    FLAT = "flat"
+    PER_UNIT = "per_unit"
+    TIERED = "tiered"
+    VOLUME = "volume"
+
+
+class UsageType(str, Enum):
+    """Usage tracking type."""
+    LICENSED = "licensed"
+    METERED = "metered"
+
+
+class TierFeature(BaseModel):
+    """Feature included in a tier."""
+    
+    id: str = Field(..., description="Feature ID")
+    name: str = Field(..., description="Feature name")
+    description: Optional[str] = None
+    
+    # Limits
+    included_quantity: Optional[int] = Field(None, description="Included quantity (None = unlimited)")
+    limit: Optional[int] = Field(None, description="Hard limit (None = unlimited)")
+    
+    # Overage
+    overage_price: Optional[Decimal] = Field(None, description="Price per unit over included")
+    
+    # Metadata
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+
+class Tier(BaseModel):
+    """
+    Pricing tier model for SaaS subscriptions.
+    
+    Define different tiers (Free, Basic, Pro, Enterprise) with
+    features, limits, and pricing.
+    """
+    
+    id: str = Field(..., description="Unique tier ID")
+    name: str = Field(..., description="Tier display name")
+    description: Optional[str] = None
+    
+    # Pricing
+    price: Decimal = Field(..., description="Price per billing cycle")
+    currency: str = Field(default="ILS")
+    billing_cycle: BillingCycle = Field(default=BillingCycle.MONTHLY)
+    
+    # Pricing type
+    tier_type: TierType = Field(default=TierType.FLAT)
+    usage_type: UsageType = Field(default=UsageType.LICENSED)
+    
+    # Per-unit pricing
+    unit_amount: Optional[Decimal] = Field(None, description="Price per unit for per_unit pricing")
+    minimum_units: int = Field(default=1)
+    maximum_units: Optional[int] = None
+    
+    # Trial
+    trial_days: int = Field(default=0, description="Trial period in days")
+    
+    # Features
+    features: list[TierFeature] = Field(default_factory=list)
+    
+    # Limits
+    limits: dict[str, Any] = Field(default_factory=dict, description="Resource limits")
+    
+    # Display
+    display_order: int = Field(default=0, description="Order for display")
+    is_popular: bool = Field(default=False, description="Mark as popular/recommended")
+    is_active: bool = Field(default=True, description="Tier is available for subscription")
+    is_public: bool = Field(default=True, description="Show in public pricing page")
+    
+    # Annual discount
+    annual_discount_percent: Optional[Decimal] = Field(None, description="Discount for annual billing")
+    
+    # Metadata
+    metadata: dict[str, Any] = Field(default_factory=dict)
+    
+    # Timestamps
+    created_at: datetime = Field(default_factory=datetime.utcnow)
+    updated_at: datetime = Field(default_factory=datetime.utcnow)
+    
+    def get_annual_price(self) -> Decimal:
+        """Calculate annual price with discount."""
+        yearly_price = self.price * 12
+        
+        if self.annual_discount_percent:
+            discount = yearly_price * (self.annual_discount_percent / 100)
+            return yearly_price - discount
+        
+        return yearly_price
+    
+    def get_monthly_equivalent(self, for_annual: bool = False) -> Decimal:
+        """Get monthly equivalent price."""
+        if for_annual:
+            return self.get_annual_price() / 12
+        return self.price
+    
+    def add_feature(
+        self,
+        feature_id: str,
+        name: str,
+        description: Optional[str] = None,
+        included_quantity: Optional[int] = None,
+        limit: Optional[int] = None,
+        overage_price: Optional[Decimal] = None,
+    ) -> TierFeature:
+        """Add a feature to this tier."""
+        feature = TierFeature(
+            id=feature_id,
+            name=name,
+            description=description,
+            included_quantity=included_quantity,
+            limit=limit,
+            overage_price=overage_price,
+        )
+        self.features.append(feature)
+        self.updated_at = datetime.utcnow()
+        return feature
+    
+    def get_feature(self, feature_id: str) -> Optional[TierFeature]:
+        """Get a feature by ID."""
+        for feature in self.features:
+            if feature.id == feature_id:
+                return feature
+        return None
+    
+    def has_feature(self, feature_id: str) -> bool:
+        """Check if tier has a feature."""
+        return self.get_feature(feature_id) is not None
+    
+    def set_limit(self, key: str, value: Any) -> None:
+        """Set a resource limit."""
+        self.limits[key] = value
+        self.updated_at = datetime.utcnow()
+    
+    def get_limit(self, key: str, default: Any = None) -> Any:
+        """Get a resource limit."""
+        return self.limits.get(key, default)
+    
+    class Config:
+        use_enum_values = True
+
+
+# Preset tier templates
+class TierTemplates:
+    """Common tier templates for quick setup."""
+    
+    @staticmethod
+    def free(tier_id: str = "free") -> Tier:
+        """Create a free tier template."""
+        return Tier(
+            id=tier_id,
+            name="Free",
+            description="Get started with basic features",
+            price=Decimal("0"),
+            billing_cycle=BillingCycle.MONTHLY,
+            display_order=0,
+        )
+    
+    @staticmethod
+    def basic(
+        tier_id: str = "basic",
+        price: Decimal = Decimal("29"),
+    ) -> Tier:
+        """Create a basic tier template."""
+        return Tier(
+            id=tier_id,
+            name="Basic",
+            description="Perfect for individuals and small teams",
+            price=price,
+            billing_cycle=BillingCycle.MONTHLY,
+            trial_days=14,
+            display_order=1,
+        )
+    
+    @staticmethod
+    def pro(
+        tier_id: str = "pro",
+        price: Decimal = Decimal("79"),
+    ) -> Tier:
+        """Create a pro tier template."""
+        return Tier(
+            id=tier_id,
+            name="Pro",
+            description="For growing teams that need more power",
+            price=price,
+            billing_cycle=BillingCycle.MONTHLY,
+            trial_days=14,
+            is_popular=True,
+            display_order=2,
+            annual_discount_percent=Decimal("20"),
+        )
+    
+    @staticmethod
+    def enterprise(
+        tier_id: str = "enterprise",
+        price: Decimal = Decimal("199"),
+    ) -> Tier:
+        """Create an enterprise tier template."""
+        return Tier(
+            id=tier_id,
+            name="Enterprise",
+            description="Advanced features for large organizations",
+            price=price,
+            billing_cycle=BillingCycle.MONTHLY,
+            display_order=3,
+            annual_discount_percent=Decimal("25"),
+        )

payplus/subscriptions/__init__.py

@@ -0,0 +1,11 @@
+"""
+Subscription management module.
+"""
+
+from payplus.subscriptions.manager import SubscriptionManager
+from payplus.subscriptions.billing import BillingService
+
+__all__ = [
+    "SubscriptionManager",
+    "BillingService",
+]