geek-cafe-saas-sdk 0.6.0__py3-none-any.whl

geek_cafe_saas_sdk/domains/tenancy/models/subscription.py

@@ -0,0 +1,440 @@
+"""
+Geek Cafe, LLC
+MIT License.  See Project Root for the license information.
+
+Subscription model for tenant billing and plan management.
+"""
+
+import time
+from boto3_assist.dynamodb.dynamodb_index import DynamoDBIndex, DynamoDBKey
+from typing import Dict, Any, Optional
+from datetime import datetime, timezone
+from geek_cafe_saas_sdk.models.base_model import BaseModel
+
+
+class Subscription(BaseModel):
+    """
+    Subscription/billing model for tenant plans.
+    
+    Tracks subscription history with one active subscription per tenant.
+    Uses date-sorted SK in GSI1 to maintain sortable history.
+    
+    Key Features:
+    - Full billing history (all subscriptions for a tenant)
+    - Active subscription pointer (separate item for O(1) access)
+    - Trial period tracking
+    - Billing period management
+    - Payment status tracking
+    
+    Access Patterns:
+    - Get subscription by ID (primary key)
+    - List subscription history for tenant (GSI1, date-sorted)
+    - Query subscriptions by status (GSI2, for billing jobs)
+    - Get active subscription via pointer item
+    
+    Active Subscription Pointer:
+    - Separate DynamoDB item with SK="subscription#active"
+    - Contains active_subscription_id for O(1) lookups
+    - Updated atomically with TransactWrite when subscription changes
+    """
+    
+    def __init__(self):
+        super().__init__()
+        # tenant_id inherited from BaseModel
+        
+        # Subscription status
+        self._status: str = "trial"  # trial|active|past_due|canceled|expired
+        
+        # Plan details
+        self._plan_code: str | None = None  # "free"|"basic"|"pro"|"enterprise"
+        self._plan_name: str | None = None  # Display name
+        self._seat_count: int = 1  # Number of users/seats
+        
+        # Pricing
+        self._price_cents: int = 0  # Price in cents (e.g., 2999 = $29.99)
+        self._currency: str = "USD"
+        self._billing_interval: str = "month"  # month|year
+        
+        # Trial period
+        self._trial_ends_utc_ts: float | None = None
+        self._is_trial: bool = False
+        
+        # Billing periods
+        self._current_period_start_utc_ts: float | None = None
+        self._current_period_end_utc_ts: float | None = None
+        
+        # Cancellation
+        self._canceled_utc_ts: float | None = None
+        self._cancel_at_period_end: bool = False
+        self._cancellation_reason: str | None = None
+        
+        # Payment tracking
+        self._last_payment_utc_ts: float | None = None
+        self._last_payment_amount_cents: int | None = None
+        self._next_billing_utc_ts: float | None = None
+        self._payment_method: str | None = None  # "card"|"invoice"|"paypal", etc.
+        
+        # External billing integration
+        self._external_subscription_id: str | None = None  # Stripe, Paddle, etc.
+        self._external_customer_id: str | None = None
+        
+        # Metadata
+        self._notes: str | None = None
+        
+        self._setup_indexes()
+    
+    def _setup_indexes(self):
+        """Setup DynamoDB indexes for efficient subscription queries."""
+        
+        # Primary index: subscription by ID
+        primary: DynamoDBIndex = DynamoDBIndex()
+        primary.name = "primary"
+        primary.partition_key.attribute_name = "pk"
+        primary.partition_key.value = lambda: DynamoDBKey.build_key(
+            ("subscription", self.id)
+        )
+        primary.sort_key.attribute_name = "sk"
+        primary.sort_key.value = lambda: DynamoDBKey.build_key(
+            ("subscription", self.id)
+        )
+        self.indexes.add_primary(primary)
+        
+        # GSI1: Subscriptions by tenant (history sorted by period start date)
+        # SK includes date prefix for sortable history
+        gsi: DynamoDBIndex = DynamoDBIndex()
+        gsi.name = "gsi1"
+        gsi.partition_key.attribute_name = f"{gsi.name}_pk"
+        gsi.partition_key.value = lambda: DynamoDBKey.build_key(
+            ("tenant", self.tenant_id)
+        )
+        gsi.sort_key.attribute_name = f"{gsi.name}_sk"
+        gsi.sort_key.value = lambda: DynamoDBKey.build_key(
+            ("subscription", self._get_date_prefix()),
+            ("id", self.id)
+        )
+        self.indexes.add_secondary(gsi)
+        
+        # GSI2: Subscriptions by status (for billing queries/jobs)
+        # Sorted by next_billing_date for processing queues
+        gsi: DynamoDBIndex = DynamoDBIndex()
+        gsi.name = "gsi2"
+        gsi.partition_key.attribute_name = f"{gsi.name}_pk"
+        gsi.partition_key.value = lambda: DynamoDBKey.build_key(
+            ("subscription_status", self.status)
+        )
+        gsi.sort_key.attribute_name = f"{gsi.name}_sk"
+        gsi.sort_key.value = lambda: DynamoDBKey.build_key(
+            ("next_billing", self.next_billing_utc_ts or 0)
+        )
+        self.indexes.add_secondary(gsi)
+        
+        # GSI3: Subscriptions by plan code (for analytics)
+        gsi: DynamoDBIndex = DynamoDBIndex()
+        gsi.name = "gsi3"
+        gsi.partition_key.attribute_name = f"{gsi.name}_pk"
+        gsi.partition_key.value = lambda: DynamoDBKey.build_key(
+            ("plan_code", self.plan_code or "unknown")
+        )
+        gsi.sort_key.attribute_name = f"{gsi.name}_sk"
+        gsi.sort_key.value = lambda: DynamoDBKey.build_key(
+            ("ts", self.created_utc_ts)
+        )
+        self.indexes.add_secondary(gsi)
+    
+    def _get_date_prefix(self) -> str | None:
+        """
+        Get date prefix for sortable history (yyyyMMdd).
+        
+        Uses current_period_start_utc_ts if available, otherwise created_utc_ts.
+        """
+        timestamp = self.current_period_start_utc_ts or self.created_utc_ts
+        if timestamp is None or timestamp == 0:
+            return None
+        dt = datetime.fromtimestamp(timestamp, tz=timezone.utc)
+        return dt.strftime("%Y%m%d")
+    
+    # Status
+    @property
+    def status(self) -> str:
+        """Subscription status."""
+        return self._status
+    
+    @status.setter
+    def status(self, value: str):
+        valid_statuses = ["trial", "active", "past_due", "canceled", "expired"]
+        if value not in valid_statuses:
+            raise ValueError(f"Invalid status: {value}. Must be one of {valid_statuses}")
+        self._status = value
+    
+    # Plan Code
+    @property
+    def plan_code(self) -> str | None:
+        """Plan identifier code."""
+        return self._plan_code
+    
+    @plan_code.setter
+    def plan_code(self, value: str | None):
+        self._plan_code = value
+    
+    # Plan Name
+    @property
+    def plan_name(self) -> str | None:
+        """Plan display name."""
+        return self._plan_name
+    
+    @plan_name.setter
+    def plan_name(self, value: str | None):
+        self._plan_name = value
+    
+    # Seat Count
+    @property
+    def seat_count(self) -> int:
+        """Number of seats/users."""
+        return self._seat_count
+    
+    @seat_count.setter
+    def seat_count(self, value: int):
+        if value < 1:
+            raise ValueError("seat_count must be at least 1")
+        self._seat_count = value
+    
+    # Price Cents
+    @property
+    def price_cents(self) -> int:
+        """Price in cents."""
+        return self._price_cents
+    
+    @price_cents.setter
+    def price_cents(self, value: int):
+        if value < 0:
+            raise ValueError("price_cents cannot be negative")
+        self._price_cents = value
+    
+    # Currency
+    @property
+    def currency(self) -> str:
+        """Currency code (e.g., USD, EUR)."""
+        return self._currency
+    
+    @currency.setter
+    def currency(self, value: str):
+        self._currency = value.upper() if value else "USD"
+    
+    # Billing Interval
+    @property
+    def billing_interval(self) -> str:
+        """Billing interval (month|year)."""
+        return self._billing_interval
+    
+    @billing_interval.setter
+    def billing_interval(self, value: str):
+        if value not in ["month", "year"]:
+            raise ValueError("billing_interval must be 'month' or 'year'")
+        self._billing_interval = value
+    
+    # Trial Ends
+    @property
+    def trial_ends_utc_ts(self) -> float | None:
+        """Trial period end timestamp."""
+        return self._trial_ends_utc_ts
+    
+    @trial_ends_utc_ts.setter
+    def trial_ends_utc_ts(self, value: float | None):
+        self._trial_ends_utc_ts = value
+    
+    # Is Trial
+    @property
+    def is_trial(self) -> bool:
+        """Whether subscription is in trial period."""
+        return self._is_trial
+    
+    @is_trial.setter
+    def is_trial(self, value: bool):
+        self._is_trial = value
+    
+    # Current Period Start
+    @property
+    def current_period_start_utc_ts(self) -> float | None:
+        """Current billing period start timestamp."""
+        return self._current_period_start_utc_ts
+    
+    @current_period_start_utc_ts.setter
+    def current_period_start_utc_ts(self, value: float | None):
+        self._current_period_start_utc_ts = value
+    
+    # Current Period End
+    @property
+    def current_period_end_utc_ts(self) -> float | None:
+        """Current billing period end timestamp."""
+        return self._current_period_end_utc_ts
+    
+    @current_period_end_utc_ts.setter
+    def current_period_end_utc_ts(self, value: float | None):
+        self._current_period_end_utc_ts = value
+    
+    # Canceled
+    @property
+    def canceled_utc_ts(self) -> float | None:
+        """Cancellation timestamp."""
+        return self._canceled_utc_ts
+    
+    @canceled_utc_ts.setter
+    def canceled_utc_ts(self, value: float | None):
+        self._canceled_utc_ts = value
+    
+    # Cancel at Period End
+    @property
+    def cancel_at_period_end(self) -> bool:
+        """Whether to cancel at end of current period."""
+        return self._cancel_at_period_end
+    
+    @cancel_at_period_end.setter
+    def cancel_at_period_end(self, value: bool):
+        self._cancel_at_period_end = value
+    
+    # Cancellation Reason
+    @property
+    def cancellation_reason(self) -> str | None:
+        """Reason for cancellation."""
+        return self._cancellation_reason
+    
+    @cancellation_reason.setter
+    def cancellation_reason(self, value: str | None):
+        self._cancellation_reason = value
+    
+    # Last Payment
+    @property
+    def last_payment_utc_ts(self) -> float | None:
+        """Last successful payment timestamp."""
+        return self._last_payment_utc_ts
+    
+    @last_payment_utc_ts.setter
+    def last_payment_utc_ts(self, value: float | None):
+        self._last_payment_utc_ts = value
+    
+    # Last Payment Amount
+    @property
+    def last_payment_amount_cents(self) -> int | None:
+        """Last payment amount in cents."""
+        return self._last_payment_amount_cents
+    
+    @last_payment_amount_cents.setter
+    def last_payment_amount_cents(self, value: int | None):
+        self._last_payment_amount_cents = value
+    
+    # Next Billing
+    @property
+    def next_billing_utc_ts(self) -> float | None:
+        """Next billing date timestamp."""
+        return self._next_billing_utc_ts
+    
+    @next_billing_utc_ts.setter
+    def next_billing_utc_ts(self, value: float | None):
+        self._next_billing_utc_ts = value
+    
+    # Payment Method
+    @property
+    def payment_method(self) -> str | None:
+        """Payment method type."""
+        return self._payment_method
+    
+    @payment_method.setter
+    def payment_method(self, value: str | None):
+        self._payment_method = value
+    
+    # External Subscription ID
+    @property
+    def external_subscription_id(self) -> str | None:
+        """External billing provider subscription ID."""
+        return self._external_subscription_id
+    
+    @external_subscription_id.setter
+    def external_subscription_id(self, value: str | None):
+        self._external_subscription_id = value
+    
+    # External Customer ID
+    @property
+    def external_customer_id(self) -> str | None:
+        """External billing provider customer ID."""
+        return self._external_customer_id
+    
+    @external_customer_id.setter
+    def external_customer_id(self, value: str | None):
+        self._external_customer_id = value
+    
+    # Notes
+    @property
+    def notes(self) -> str | None:
+        """Internal notes about subscription."""
+        return self._notes
+    
+    @notes.setter
+    def notes(self, value: str | None):
+        self._notes = value
+    
+    # Helper Methods
+    
+    def is_active(self) -> bool:
+        """Check if subscription is active."""
+        return self._status == "active"
+    
+    def is_trial_active(self) -> bool:
+        """Check if subscription is in active trial."""
+        return self._status == "trial"
+    
+    def is_canceled(self) -> bool:
+        """Check if subscription is canceled."""
+        return self._status == "canceled"
+    
+    def is_past_due(self) -> bool:
+        """Check if subscription payment is past due."""
+        return self._status == "past_due"
+    
+    def is_expired(self) -> bool:
+        """Check if subscription is expired."""
+        return self._status == "expired"
+    
+    def cancel(self, reason: str | None = None, immediate: bool = False):
+        """
+        Cancel subscription.
+        
+        Args:
+            reason: Optional cancellation reason
+            immediate: If True, cancel immediately; if False, cancel at period end
+        """
+        import datetime as dt
+        
+        self._status = "canceled"
+        self._canceled_utc_ts = dt.datetime.now(dt.UTC).timestamp()
+        self._cancellation_reason = reason
+        
+        if not immediate:
+            self._cancel_at_period_end = True
+    
+    def reactivate(self):
+        """Reactivate a canceled subscription."""
+        if self._status == "canceled":
+            self._status = "active"
+            self._canceled_utc_ts = None
+            self._cancel_at_period_end = False
+            self._cancellation_reason = None
+    
+    def record_payment(self, amount_cents: int):
+        """Record a successful payment."""
+        import datetime as dt
+        
+        self._last_payment_utc_ts = dt.datetime.now(dt.UTC).timestamp()
+        self._last_payment_amount_cents = amount_cents
+        
+        # Update status if was past_due
+        if self._status == "past_due":
+            self._status = "active"
+    
+    def mark_past_due(self):
+        """Mark subscription as past due (payment failed)."""
+        self._status = "past_due"
+    
+    def get_price_display(self) -> str:
+        """Get formatted price for display."""
+        dollars = self._price_cents / 100
+        return f"${dollars:.2f} {self._currency}"

geek_cafe_saas_sdk/domains/tenancy/models/tenant.py

@@ -0,0 +1,258 @@
+"""
+Geek Cafe, LLC
+MIT License.  See Project Root for the license information.
+
+Tenant model for multi-tenant SaaS organizations.
+"""
+
+from boto3_assist.dynamodb.dynamodb_index import DynamoDBIndex, DynamoDBKey
+from typing import Dict, Any, Optional
+from geek_cafe_saas_sdk.models.base_model import BaseModel
+
+
+class Tenant(BaseModel):
+    """
+    Tenant/Organization model for multi-tenant SaaS.
+    
+    Represents a customer organization with multiple users and a subscription.
+    Each tenant has a plan tier, status, and customizable feature flags.
+    
+    Key Features:
+    - Multi-user support (one or many users per tenant)
+    - Subscription management (linked via tenant_id)
+    - Feature flags for plan differentiation
+    - Primary contact tracking
+    
+    Access Patterns:
+    - Get tenant by ID (primary key)
+    - List tenants by status (GSI1)
+    - List all tenants sorted by name (GSI2)
+    """
+    
+    def __init__(self):
+        super().__init__()
+        
+        # Basic info
+        self._name: str | None = None
+        self._status: str = "active"  # active|inactive|archived
+        self._plan_tier: str = "free"  # free|basic|pro|enterprise
+        
+        # Relationships
+        self._primary_contact_user_id: str | None = None
+        
+        # Limits & settings
+        self._max_users: int | None = None  # Null = unlimited
+        self._features: Dict[str, Any] = {}  # Feature flags per tenant
+        
+        # Metadata
+        self._description: str | None = None
+        self._website: str | None = None
+        self._logo_url: str | None = None
+        
+        self._setup_indexes()
+    
+    def _setup_indexes(self):
+        """Setup DynamoDB indexes for efficient tenant queries."""
+        
+        # Primary index: tenant by ID
+        primary: DynamoDBIndex = DynamoDBIndex()
+        primary.name = "primary"
+        primary.partition_key.attribute_name = "pk"
+        primary.partition_key.value = lambda: DynamoDBKey.build_key(("tenant", self.id))
+        primary.sort_key.attribute_name = "sk"
+        primary.sort_key.value = lambda: DynamoDBKey.build_key(("tenant", self.id))
+        self.indexes.add_primary(primary)
+        
+        # GSI1: Tenants by status (for admin queries - active, inactive, archived)
+        gsi: DynamoDBIndex = DynamoDBIndex()
+        gsi.name = "gsi1"
+        gsi.partition_key.attribute_name = f"{gsi.name}_pk"
+        gsi.partition_key.value = lambda: DynamoDBKey.build_key(
+            ("tenant_status", self.status)
+        )
+        gsi.sort_key.attribute_name = f"{gsi.name}_sk"
+        gsi.sort_key.value = lambda: DynamoDBKey.build_key(
+            ("ts", self.created_utc_ts)
+        )
+        self.indexes.add_secondary(gsi)
+        
+        # GSI2: All tenants sorted by name (for admin listing)
+        gsi: DynamoDBIndex = DynamoDBIndex()
+        gsi.name = "gsi2"
+        gsi.partition_key.attribute_name = f"{gsi.name}_pk"
+        gsi.partition_key.value = lambda: DynamoDBKey.build_key(("tenant", "all"))
+        gsi.sort_key.attribute_name = f"{gsi.name}_sk"
+        gsi.sort_key.value = lambda: DynamoDBKey.build_key(
+            ("name", self.name or ""),
+            ("ts", self.created_utc_ts)
+        )
+        self.indexes.add_secondary(gsi)
+        
+        # GSI3: Tenants by plan tier (for analytics/reporting)
+        gsi: DynamoDBIndex = DynamoDBIndex()
+        gsi.name = "gsi3"
+        gsi.partition_key.attribute_name = f"{gsi.name}_pk"
+        gsi.partition_key.value = lambda: DynamoDBKey.build_key(
+            ("plan_tier", self.plan_tier)
+        )
+        gsi.sort_key.attribute_name = f"{gsi.name}_sk"
+        gsi.sort_key.value = lambda: DynamoDBKey.build_key(
+            ("ts", self.created_utc_ts)
+        )
+        self.indexes.add_secondary(gsi)
+    
+    # Name
+    @property
+    def name(self) -> str | None:
+        """Tenant organization name."""
+        return self._name
+    
+    @name.setter
+    def name(self, value: str | None):
+        self._name = value
+    
+    # Status
+    @property
+    def status(self) -> str:
+        """Tenant status (active|inactive|archived)."""
+        return self._status
+    
+    @status.setter
+    def status(self, value: str):
+        if value not in ["active", "inactive", "archived"]:
+            raise ValueError(f"Invalid status: {value}. Must be active, inactive, or archived.")
+        self._status = value
+    
+    # Plan Tier
+    @property
+    def plan_tier(self) -> str:
+        """Subscription plan tier (free|basic|pro|enterprise)."""
+        return self._plan_tier
+    
+    @plan_tier.setter
+    def plan_tier(self, value: str):
+        if value not in ["free", "basic", "pro", "enterprise"]:
+            raise ValueError(f"Invalid plan_tier: {value}. Must be free, basic, pro, or enterprise.")
+        self._plan_tier = value
+    
+    # Primary Contact User ID
+    @property
+    def primary_contact_user_id(self) -> str | None:
+        """User ID of primary contact/admin."""
+        return self._primary_contact_user_id
+    
+    @primary_contact_user_id.setter
+    def primary_contact_user_id(self, value: str | None):
+        self._primary_contact_user_id = value
+    
+    # Max Users
+    @property
+    def max_users(self) -> int | None:
+        """Maximum users allowed (None = unlimited)."""
+        return self._max_users
+    
+    @max_users.setter
+    def max_users(self, value: int | None):
+        if value is not None and value < 1:
+            raise ValueError("max_users must be at least 1 or None for unlimited")
+        self._max_users = value
+    
+    # Features
+    @property
+    def features(self) -> Dict[str, Any]:
+        """
+        Feature flags for tenant.
+        
+        Example:
+        {
+            "chat": True,
+            "events": True,
+            "analytics": False,
+            "api_access": True,
+            "custom_branding": True
+        }
+        """
+        return self._features
+    
+    @features.setter
+    def features(self, value: Dict[str, Any]):
+        if value is None:
+            self._features = {}
+        elif isinstance(value, dict):
+            self._features = value
+        else:
+            self._features = {}
+    
+    # Description
+    @property
+    def description(self) -> str | None:
+        """Tenant description."""
+        return self._description
+    
+    @description.setter
+    def description(self, value: str | None):
+        self._description = value
+    
+    # Website
+    @property
+    def website(self) -> str | None:
+        """Tenant website URL."""
+        return self._website
+    
+    @website.setter
+    def website(self, value: str | None):
+        self._website = value
+    
+    # Logo URL
+    @property
+    def logo_url(self) -> str | None:
+        """Tenant logo URL."""
+        return self._logo_url
+    
+    @logo_url.setter
+    def logo_url(self, value: str | None):
+        self._logo_url = value
+    
+    # Helper Methods
+    
+    def is_active(self) -> bool:
+        """Check if tenant is active."""
+        return self._status == "active"
+    
+    def is_inactive(self) -> bool:
+        """Check if tenant is inactive."""
+        return self._status == "inactive"
+    
+    def is_archived(self) -> bool:
+        """Check if tenant is archived."""
+        return self._status == "archived"
+    
+    def has_feature(self, feature_key: str) -> bool:
+        """Check if tenant has a specific feature enabled."""
+        return self._features.get(feature_key, False) is True
+    
+    def enable_feature(self, feature_key: str):
+        """Enable a feature for this tenant."""
+        self._features[feature_key] = True
+    
+    def disable_feature(self, feature_key: str):
+        """Disable a feature for this tenant."""
+        self._features[feature_key] = False
+    
+    def is_at_user_limit(self, current_user_count: int) -> bool:
+        """Check if tenant is at maximum user limit."""
+        if self._max_users is None:
+            return False  # Unlimited
+        return current_user_count >= self._max_users
+    
+    def activate(self):
+        """Set tenant status to active."""
+        self._status = "active"
+    
+    def deactivate(self):
+        """Set tenant status to inactive."""
+        self._status = "inactive"
+    
+    def archive(self):
+        """Set tenant status to archived."""
+        self._status = "archived"

geek_cafe_saas_sdk/domains/tenancy/services/__init__.py

@@ -0,0 +1,6 @@
+# Tenancy Domain Services
+
+from .tenant_service import TenantService
+from .subscription_service import SubscriptionService
+
+__all__ = ["TenantService", "SubscriptionService"]