geek-cafe-saas-sdk 0.7.0__py3-none-any.whl → 0.7.1__py3-none-any.whl

geek_cafe_saas_sdk/domains/tenancy/models/subscription.py

@@ -45,11 +45,21 @@ class Subscription(BaseModel):
         # Subscription status
         self._status: str = "trial"  # trial|active|past_due|canceled|expired
         
-        # Plan details
+        # Plan details (NEW: References platform-wide Plan model)
+        self._plan_id: str | None = None  # Reference to subscriptions.Plan.id
         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
         
+        # Addons (NEW: Support for add-on modules)
+        self._active_addons: list[str] = []  # List of active addon codes
+        self._addon_metadata: dict[str, dict] = {}  # Per-addon settings
+        
+        # Discounts (NEW: Promotional discounts)
+        self._discount_id: str | None = None  # Reference to subscriptions.Discount.id
+        self._discount_code: str | None = None  # Promo code used
+        self._discount_amount_cents: int = 0  # Discount applied per period
+        
         # Pricing
         self._price_cents: int = 0  # Price in cents (e.g., 2999 = $29.99)
         self._currency: str = "USD"
@@ -166,6 +176,16 @@ class Subscription(BaseModel):
             raise ValueError(f"Invalid status: {value}. Must be one of {valid_statuses}")
         self._status = value
     
+    # Plan ID (NEW)
+    @property
+    def plan_id(self) -> str | None:
+        """Plan ID reference."""
+        return self._plan_id
+    
+    @plan_id.setter
+    def plan_id(self, value: str | None):
+        self._plan_id = value
+    
     # Plan Code
     @property
     def plan_code(self) -> str | None:
@@ -372,6 +392,58 @@ class Subscription(BaseModel):
     def notes(self, value: str | None):
         self._notes = value
     
+    # Active Addons (NEW)
+    @property
+    def active_addons(self) -> list[str]:
+        """List of active addon codes."""
+        return self._active_addons
+    
+    @active_addons.setter
+    def active_addons(self, value: list[str]):
+        self._active_addons = value if value else []
+    
+    # Addon Metadata (NEW)
+    @property
+    def addon_metadata(self) -> dict[str, dict]:
+        """Per-addon metadata."""
+        return self._addon_metadata
+    
+    @addon_metadata.setter
+    def addon_metadata(self, value: dict[str, dict]):
+        self._addon_metadata = value if value else {}
+    
+    # Discount ID (NEW)
+    @property
+    def discount_id(self) -> str | None:
+        """Discount ID reference."""
+        return self._discount_id
+    
+    @discount_id.setter
+    def discount_id(self, value: str | None):
+        self._discount_id = value
+    
+    # Discount Code (NEW)
+    @property
+    def discount_code(self) -> str | None:
+        """Promo code used."""
+        return self._discount_code
+    
+    @discount_code.setter
+    def discount_code(self, value: str | None):
+        self._discount_code = value
+    
+    # Discount Amount Cents (NEW)
+    @property
+    def discount_amount_cents(self) -> int:
+        """Discount amount per period in cents."""
+        return self._discount_amount_cents
+    
+    @discount_amount_cents.setter
+    def discount_amount_cents(self, value: int):
+        if value < 0:
+            raise ValueError("discount_amount_cents cannot be negative")
+        self._discount_amount_cents = value
+    
     # Helper Methods
     
     def is_active(self) -> bool:
@@ -438,3 +510,53 @@ class Subscription(BaseModel):
         """Get formatted price for display."""
         dollars = self._price_cents / 100
         return f"${dollars:.2f} {self._currency}"
+    
+    # NEW Helper Methods for Addons and Discounts
+    
+    def has_addon(self, addon_code: str) -> bool:
+        """Check if addon is active on subscription."""
+        return addon_code in self._active_addons
+    
+    def add_addon(self, addon_code: str, metadata: dict | None = None):
+        """Add an addon to subscription."""
+        if addon_code not in self._active_addons:
+            self._active_addons.append(addon_code)
+        
+        if metadata:
+            self._addon_metadata[addon_code] = metadata
+    
+    def remove_addon(self, addon_code: str):
+        """Remove an addon from subscription."""
+        if addon_code in self._active_addons:
+            self._active_addons.remove(addon_code)
+        
+        if addon_code in self._addon_metadata:
+            del self._addon_metadata[addon_code]
+    
+    def get_addon_metadata(self, addon_code: str) -> dict | None:
+        """Get metadata for specific addon."""
+        return self._addon_metadata.get(addon_code)
+    
+    def set_addon_metadata(self, addon_code: str, metadata: dict):
+        """Set metadata for specific addon."""
+        self._addon_metadata[addon_code] = metadata
+    
+    def has_discount(self) -> bool:
+        """Check if subscription has an active discount."""
+        return self._discount_id is not None
+    
+    def apply_discount(self, discount_id: str, discount_code: str, discount_amount_cents: int):
+        """Apply a discount to subscription."""
+        self._discount_id = discount_id
+        self._discount_code = discount_code
+        self._discount_amount_cents = discount_amount_cents
+    
+    def remove_discount(self):
+        """Remove discount from subscription."""
+        self._discount_id = None
+        self._discount_code = None
+        self._discount_amount_cents = 0
+    
+    def get_final_price_cents(self) -> int:
+        """Get final price after discount."""
+        return max(0, self._price_cents - self._discount_amount_cents)

geek_cafe_saas_sdk/domains/tenancy/services/subscription_service.py

@@ -555,3 +555,216 @@ class SubscriptionService(DatabaseService[Subscription]):
         except Exception as e:
             return self._handle_service_exception(e, 'delete_subscription',
                                                  resource_id=resource_id, tenant_id=tenant_id)
+    
+    # ========================================================================
+    # NEW: Plan and Addon Integration Methods
+    # ========================================================================
+    
+    def create_from_plan(
+        self,
+        tenant_id: str,
+        user_id: str,
+        plan_id: str,
+        plan_code: str,
+        plan_name: str,
+        price_cents: int,
+        seat_count: int = 1,
+        billing_interval: str = "month",
+        **kwargs
+    ) -> ServiceResult[Subscription]:
+        """
+        Create a subscription from a Plan definition.
+        
+        This links the tenant subscription to a platform-wide Plan,
+        copying pricing and configuration at subscription time.
+        
+        Args:
+            tenant_id: Tenant ID
+            user_id: User creating subscription
+            plan_id: Reference to subscriptions.Plan.id
+            plan_code: Plan code
+            plan_name: Plan name
+            price_cents: Price in cents
+            seat_count: Number of seats
+            billing_interval: "month" or "year"
+            **kwargs: Additional fields
+            
+        Returns:
+            ServiceResult with Subscription
+        """
+        payload = {
+            "plan_id": plan_id,
+            "plan_code": plan_code,
+            "plan_name": plan_name,
+            "price_cents": price_cents,
+            "seat_count": seat_count,
+            "billing_interval": billing_interval,
+            **kwargs
+        }
+        
+        return self.activate_subscription(tenant_id, user_id, payload)
+    
+    def add_addon_to_subscription(
+        self,
+        subscription_id: str,
+        tenant_id: str,
+        user_id: str,
+        addon_code: str,
+        addon_metadata: Optional[Dict[str, Any]] = None
+    ) -> ServiceResult[Subscription]:
+        """
+        Add an addon to an existing subscription.
+        
+        Args:
+            subscription_id: Subscription ID
+            tenant_id: Tenant ID
+            user_id: User performing action
+            addon_code: Addon code to add
+            addon_metadata: Optional addon-specific settings
+            
+        Returns:
+            ServiceResult with updated Subscription
+        """
+        try:
+            # Get subscription
+            result = self.get_by_id(subscription_id, tenant_id, user_id)
+            if not result.success:
+                return result
+            
+            subscription = result.data
+            
+            # Add addon
+            subscription.add_addon(addon_code, addon_metadata)
+            
+            # Update
+            subscription.updated_by_id = user_id
+            subscription.updated_utc_ts = dt.datetime.now(dt.UTC).timestamp()
+            subscription.version += 1
+            
+            # Save
+            return self._save_model(subscription)
+            
+        except Exception as e:
+            return self._handle_service_exception(
+                e, 'add_addon_to_subscription',
+                subscription_id=subscription_id, tenant_id=tenant_id
+            )
+    
+    def remove_addon_from_subscription(
+        self,
+        subscription_id: str,
+        tenant_id: str,
+        user_id: str,
+        addon_code: str
+    ) -> ServiceResult[Subscription]:
+        """
+        Remove an addon from a subscription.
+        
+        Args:
+            subscription_id: Subscription ID
+            tenant_id: Tenant ID
+            user_id: User performing action
+            addon_code: Addon code to remove
+            
+        Returns:
+            ServiceResult with updated Subscription
+        """
+        try:
+            result = self.get_by_id(subscription_id, tenant_id, user_id)
+            if not result.success:
+                return result
+            
+            subscription = result.data
+            subscription.remove_addon(addon_code)
+            
+            subscription.updated_by_id = user_id
+            subscription.updated_utc_ts = dt.datetime.now(dt.UTC).timestamp()
+            subscription.version += 1
+            
+            return self._save_model(subscription)
+            
+        except Exception as e:
+            return self._handle_service_exception(
+                e, 'remove_addon_from_subscription',
+                subscription_id=subscription_id, tenant_id=tenant_id
+            )
+    
+    def apply_discount_to_subscription(
+        self,
+        subscription_id: str,
+        tenant_id: str,
+        user_id: str,
+        discount_id: str,
+        discount_code: str,
+        discount_amount_cents: int
+    ) -> ServiceResult[Subscription]:
+        """
+        Apply a discount to a subscription.
+        
+        Args:
+            subscription_id: Subscription ID
+            tenant_id: Tenant ID
+            user_id: User performing action
+            discount_id: Reference to subscriptions.Discount.id
+            discount_code: Discount code
+            discount_amount_cents: Discount amount per period
+            
+        Returns:
+            ServiceResult with updated Subscription
+        """
+        try:
+            result = self.get_by_id(subscription_id, tenant_id, user_id)
+            if not result.success:
+                return result
+            
+            subscription = result.data
+            subscription.apply_discount(discount_id, discount_code, discount_amount_cents)
+            
+            subscription.updated_by_id = user_id
+            subscription.updated_utc_ts = dt.datetime.now(dt.UTC).timestamp()
+            subscription.version += 1
+            
+            return self._save_model(subscription)
+            
+        except Exception as e:
+            return self._handle_service_exception(
+                e, 'apply_discount_to_subscription',
+                subscription_id=subscription_id, tenant_id=tenant_id
+            )
+    
+    def remove_discount_from_subscription(
+        self,
+        subscription_id: str,
+        tenant_id: str,
+        user_id: str
+    ) -> ServiceResult[Subscription]:
+        """
+        Remove discount from a subscription.
+        
+        Args:
+            subscription_id: Subscription ID
+            tenant_id: Tenant ID
+            user_id: User performing action
+            
+        Returns:
+            ServiceResult with updated Subscription
+        """
+        try:
+            result = self.get_by_id(subscription_id, tenant_id, user_id)
+            if not result.success:
+                return result
+            
+            subscription = result.data
+            subscription.remove_discount()
+            
+            subscription.updated_by_id = user_id
+            subscription.updated_utc_ts = dt.datetime.now(dt.UTC).timestamp()
+            subscription.version += 1
+            
+            return self._save_model(subscription)
+            
+        except Exception as e:
+            return self._handle_service_exception(
+                e, 'remove_discount_from_subscription',
+                subscription_id=subscription_id, tenant_id=tenant_id
+            )

geek_cafe_saas_sdk/lambda_handlers/_base/base_handler.py

@@ -14,6 +14,8 @@ from geek_cafe_saas_sdk.utilities.response import (
     service_result_to_response,
 )
 from geek_cafe_saas_sdk.utilities.lambda_event_utility import LambdaEventUtility
+from geek_cafe_saas_sdk.utilities.logging_utility import LoggingUtility
+from geek_cafe_saas_sdk.utilities.environment_variables import EnvironmentVariables
 from geek_cafe_saas_sdk.middleware.auth import extract_user_context
 from .service_pool import ServicePool
 
@@ -94,6 +96,11 @@ class BaseLambdaHandler:
             Lambda response dictionary
         """
         try:
+            # Log event payload if enabled (sanitized for security)
+            if EnvironmentVariables.should_log_lambda_events():
+                sanitized_event = LoggingUtility.sanitize_event_for_logging(event)
+                logger.info("Lambda event received", extra={"event": sanitized_event})
+            
             # Unwrap message if needed (SQS, SNS, etc.)
             if self.unwrap_message and "message" in event:
                 event = event["message"]

geek_cafe_saas_sdk/services/database_service.py

@@ -142,7 +142,7 @@ class DatabaseService(ABC, Generic[T]):
             return None
 
     def _get_model_by_id_with_tenant_check(
-        self, resource_id: str, model_class, tenant_id: str
+        self, resource_id: str, model_class, tenant_id: str, include_deleted: bool = True
     ) -> Optional[T]:
         """
         Get model by ID with automatic tenant validation.
@@ -155,13 +155,16 @@ class DatabaseService(ABC, Generic[T]):
             resource_id: The resource ID to fetch
             model_class: The model class to instantiate
             tenant_id: The tenant ID from JWT (authenticated user's tenant)
+            include_deleted: If True, returns deleted items. If False, returns None for deleted items.
+                           Default is True since get-by-id operations typically need to verify deletion,
+                           perform restores, or show audit history.
             
         Returns:
             The model if found and belongs to tenant, None otherwise
             
         Security:
             - Returns None for resources in different tenants (prevents enumeration)
-            - Returns None for deleted resources
+            - Optionally filters deleted resources based on include_deleted parameter
             - Single source of truth: tenant_id from JWT only
         """
         model = self._get_model_by_id(resource_id, model_class)
@@ -175,10 +178,11 @@ class DatabaseService(ABC, Generic[T]):
             # from users in other tenants (prevent enumeration attacks)
             return None
         
-        # Hide deleted resources
-        if hasattr(model, 'is_deleted') and callable(model.is_deleted):
-            if model.is_deleted():
-                return None
+        # Optionally hide deleted resources
+        if not include_deleted:
+            if hasattr(model, 'is_deleted') and callable(model.is_deleted):
+                if model.is_deleted():
+                    return None
         
         return model
 

geek_cafe_saas_sdk/utilities/environment_variables.py

@@ -226,3 +226,19 @@ class EnvironmentVariables:
         """
         env = EnvironmentVariables.get_environment_setting()
         return env.lower().startswith("dev")
+    
+    @staticmethod
+    def should_log_lambda_events() -> bool:
+        """
+        Determine if Lambda event payloads should be logged.
+        
+        Set LOG_LAMBDA_EVENTS=true to enable event logging for debugging.
+        Useful for troubleshooting Lambda invocations.
+        
+        Note: Event payloads are sanitized to remove sensitive fields before logging.
+        
+        Returns:
+            True if event logging is enabled, False otherwise.
+        """
+        value = os.getenv("LOG_LAMBDA_EVENTS", "false").lower() == "true"
+        return value

geek_cafe_saas_sdk/utilities/logging_utility.py

@@ -1,3 +1,5 @@
+import json
+from typing import Any, Dict
 from aws_lambda_powertools import Logger
 from geek_cafe_saas_sdk.utilities.environment_variables import (
     EnvironmentVariables,
@@ -48,6 +50,81 @@ class LoggingUtility:
             "metric_filter": metric_filter,
         }
         return response
+    
+    @staticmethod
+    def sanitize_event_for_logging(event: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Sanitize a Lambda event dictionary by masking sensitive fields.
+        
+        This removes or masks sensitive information like:
+        - Authorization headers
+        - API keys
+        - Passwords
+        - Tokens
+        - SSNs, credit cards, etc.
+        
+        Args:
+            event: The Lambda event dictionary to sanitize
+            
+        Returns:
+            A sanitized copy of the event safe for logging
+        """
+        if not isinstance(event, dict):
+            return event
+        
+        # Fields that should be completely removed
+        REMOVE_FIELDS = {
+            'password', 'passwd', 'pwd',
+            'secret', 'api_key', 'apikey',
+            'token', 'access_token', 'refresh_token',
+            'private_key', 'privatekey',
+            'ssn', 'credit_card', 'creditcard',
+            'cvv', 'pin'
+        }
+        
+        # Fields that should be masked (show first few chars)
+        MASK_FIELDS = {
+            'authorization', 'x_api_key',
+            'cookie', 'session'
+        }
+        
+        def sanitize_value(key: str, value: Any) -> Any:
+            """Recursively sanitize values."""
+            try:
+                key_lower = key.lower().replace('-', '_').replace(' ', '_')
+                
+                # Remove sensitive fields entirely (exact match)
+                if key_lower in REMOVE_FIELDS:
+                    return '[REDACTED]'
+                
+                # Mask partially visible fields (exact match)
+                if key_lower in MASK_FIELDS:
+                    if isinstance(value, str) and len(value) > 20:
+                        return f"{value[:4]}...{value[-4:]}"
+                    return '[MASKED]'
+                
+                # Recursively handle nested structures
+                if isinstance(value, dict):
+                    return {k: sanitize_value(k, v) for k, v in value.items()}
+                elif isinstance(value, list):
+                    return [sanitize_value(key, item) if isinstance(item, dict) else item 
+                            for item in value]
+                
+                return value
+            except Exception:
+                # If we can't safely process the value, redact it
+                return '[SANITIZATION_ERROR]'
+        
+        # Create a deep copy and sanitize
+        try:
+            sanitized = {k: sanitize_value(k, v) for k, v in event.items()}
+            # Validate that the result is JSON-serializable
+            import json
+            json.dumps(sanitized)
+            return sanitized
+        except Exception as e:
+            # If sanitization fails, return safe fallback
+            return {"error": "Failed to sanitize event"}
 
 
 class LogLevels:

{geek_cafe_saas_sdk-0.7.0.dist-info → geek_cafe_saas_sdk-0.7.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: geek_cafe_saas_sdk
-Version: 0.7.0
+Version: 0.7.1
 Summary: Base Reusable Services for SaaS
 Project-URL: Homepage, https://github.com/geekcafe/geek-cafe-services
 Project-URL: Documentation, https://github.com/geekcafe/geek-cafe-services/blob/main/README.md