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

geek_cafe_saas_sdk/domains/files/services/file_version_service.py

@@ -133,21 +133,11 @@ class FileVersionService(DatabaseService[FileVersion]):
                 self._mark_version_as_not_current(tenant_id, file_id, file.current_version_id)
             
             # Save version metadata to DynamoDB
-            pk = f"FILE#{tenant_id}#{file_id}"
-            sk = f"VERSION#{version.version_id}"
-            
-            item = version.to_dictionary()
-            item["pk"] = pk
-            item["sk"] = sk
+            version.prep_for_save()
+            save_result = self._save_model(version)
             
-            # GSI1: Versions by file (ordered by version number)
-            item["gsi1_pk"] = f"FILE#{tenant_id}#{file_id}"
-            item["gsi1_sk"] = f"VERSION#{new_version_num:010d}"  # Pad for sorting
-            
-            self.dynamodb.save(
-                item=item,
-                table_name=self.table_name
-            )
+            if not save_result.success:
+                return save_result
             
             # Update file record with new current version
             self._update_file_current_version(
@@ -194,29 +184,22 @@ class FileVersionService(DatabaseService[FileVersion]):
             ServiceResult with FileVersion model
         """
         try:
-            if not file_id:
-                raise ValidationError("file_id is required", "file_id")
-            
-            pk = f"FILE#{tenant_id}#{file_id}"
-            sk = f"VERSION#{resource_id}"
+            # Use helper method with tenant check
+            version = self._get_model_by_id_with_tenant_check(resource_id, FileVersion, tenant_id)
             
-            result = self.dynamodb.get(
-                table_name=self.table_name,
-                key={"pk": pk, "sk": sk}
-            )
-            
-            # Check if version exists
-            if not result or 'Item' not in result:
+            if not version:
                 raise NotFoundError(f"Version not found: {resource_id}")
             
-            # Convert to FileVersion model
-            version = FileVersion()
-            version.map(result['Item'])
-            
             # Access control: Check file ownership
-            file_result = self._get_file(tenant_id, file_id, user_id)
-            if not file_result.success:
-                raise AccessDeniedError("You do not have access to this file version")
+            if file_id:
+                file_result = self._get_file(tenant_id, file_id, user_id)
+                if not file_result.success:
+                    raise AccessDeniedError("You do not have access to this file version")
+            else:
+                # If no file_id provided, check using version's file_id
+                file_result = self._get_file(tenant_id, version.file_id, user_id)
+                if not file_result.success:
+                    raise AccessDeniedError("You do not have access to this file version")
             
             return ServiceResult.success_result(version)
             
@@ -280,23 +263,8 @@ class FileVersionService(DatabaseService[FileVersion]):
             version.updated_utc_ts = dt.datetime.now(dt.UTC).timestamp()
             
             # Save to DynamoDB
-            pk = f"FILE#{tenant_id}#{file_id}"
-            sk = f"VERSION#{resource_id}"
-            
-            item = version.to_dictionary()
-            item["pk"] = pk
-            item["sk"] = sk
-            
-            # Preserve GSI1 keys
-            item["gsi1_pk"] = f"FILE#{tenant_id}#{file_id}"
-            item["gsi1_sk"] = f"VERSION#{version.version_number:010d}"
-            
-            self.dynamodb.save(
-                item=item,
-                table_name=self.table_name
-            )
-            
-            return ServiceResult.success_result(version)
+            version.prep_for_save()
+            return self._save_model(version)
             
         except (ValidationError, AccessDeniedError) as e:
             return ServiceResult.error_result(
@@ -348,21 +316,11 @@ class FileVersionService(DatabaseService[FileVersion]):
             version.status = "archived"
             version.deleted_utc_ts = dt.datetime.now(dt.UTC).timestamp()
             
-            pk = f"FILE#{tenant_id}#{file_id}"
-            sk = f"VERSION#{resource_id}"
-            
-            item = version.to_dictionary()
-            item["pk"] = pk
-            item["sk"] = sk
-            
-            # Preserve GSI1 keys
-            item["gsi1_pk"] = f"FILE#{tenant_id}#{file_id}"
-            item["gsi1_sk"] = f"VERSION#{version.version_number:010d}"
+            version.prep_for_save()
+            save_result = self._save_model(version)
             
-            self.dynamodb.save(
-                item=item,
-                table_name=self.table_name
-            )
+            if not save_result.success:
+                return save_result
             
             # Note: S3 file is kept for potential recovery
             
@@ -408,22 +366,19 @@ class FileVersionService(DatabaseService[FileVersion]):
                     error_code=ErrorCode.ACCESS_DENIED
                 )
             
-            # Query GSI1 for versions
-            gsi1_pk = f"FILE#{tenant_id}#{file_id}"
+            # Use GSI1 to query versions by file
+            temp_version = FileVersion()
+            temp_version.file_id = file_id
             
-            results = self.dynamodb.query(
-                key=Key('gsi1_pk').eq(gsi1_pk) & Key('gsi1_sk').begins_with("VERSION#"),
-                table_name=self.table_name,
-                index_name="gsi1",
-                limit=limit,
-                ascending=False  # Newest first
-            )
+            # Query using helper method (descending to get newest first)
+            query_result = self._query_by_index(temp_version, "gsi1", limit=limit, ascending=False)
+            
+            if not query_result.success:
+                return query_result
             
+            # Filter results
             versions = []
-            for item in results.get('Items', []):
-                version = FileVersion()
-                version.map(item)
-                
+            for version in query_result.data:
                 # Filter out archived versions (which includes deleted ones)
                 if version.status == "active":
                     versions.append(version)
@@ -479,21 +434,11 @@ class FileVersionService(DatabaseService[FileVersion]):
             version_to_restore.is_current = True
             version_to_restore.updated_utc_ts = dt.datetime.now(dt.UTC).timestamp()
             
-            pk = f"FILE#{tenant_id}#{file_id}"
-            sk = f"VERSION#{version_id}"
-            
-            item = version_to_restore.to_dictionary()
-            item["pk"] = pk
-            item["sk"] = sk
+            version_to_restore.prep_for_save()
+            save_result = self._save_model(version_to_restore)
             
-            # Preserve GSI1 keys
-            item["gsi1_pk"] = f"FILE#{tenant_id}#{file_id}"
-            item["gsi1_sk"] = f"VERSION#{version_to_restore.version_number:010d}"
-            
-            self.dynamodb.save(
-                item=item,
-                table_name=self.table_name
-            )
+            if not save_result.success:
+                return save_result
             
             # Update file record
             self._update_file_current_version(
@@ -571,7 +516,7 @@ class FileVersionService(DatabaseService[FileVersion]):
         """Get file with access control."""
         try:
             pk = f"FILE#{tenant_id}#{file_id}"
-            sk = "METADATA"
+            sk = "metadata"
             
             result = self.dynamodb.get(
                 table_name=self.table_name,
@@ -640,18 +585,8 @@ class FileVersionService(DatabaseService[FileVersion]):
                 version.map(result['Item'])
                 version.is_current = False
                 
-                item = version.to_dictionary()
-                item["pk"] = pk
-                item["sk"] = sk
-                
-                # Preserve GSI1 keys
-                item["gsi1_pk"] = result['Item'].get('gsi1_pk')
-                item["gsi1_sk"] = result['Item'].get('gsi1_sk')
-                
-                self.dynamodb.save(
-                    item=item,
-                    table_name=self.table_name
-                )
+                version.prep_for_save()
+                self._save_model(version)
         except Exception:
             pass  # Best effort
     
@@ -665,7 +600,7 @@ class FileVersionService(DatabaseService[FileVersion]):
         """Update file record with current version info."""
         try:
             pk = f"FILE#{tenant_id}#{file_id}"
-            sk = "METADATA"
+            sk = "metadata"
             
             result = self.dynamodb.get(
                 table_name=self.table_name,
@@ -680,14 +615,8 @@ class FileVersionService(DatabaseService[FileVersion]):
                 file.version_count = version_number
                 file.updated_utc_ts = dt.datetime.now(dt.UTC).timestamp()
                 
-                item = file.to_dictionary()
-                item["pk"] = pk
-                item["sk"] = sk
-                
-                self.dynamodb.save(
-                    item=item,
-                    table_name=self.table_name
-                )
+                file.prep_for_save()
+                self._save_model(file)
         except Exception:
             pass  # Best effort
     
@@ -719,17 +648,8 @@ class FileVersionService(DatabaseService[FileVersion]):
                         version.status = "archived"
                         version.updated_utc_ts = dt.datetime.now(dt.UTC).timestamp()
                         
-                        pk = f"FILE#{tenant_id}#{file_id}"
-                        sk = f"VERSION#{version.version_id}"
-                        
-                        item_dict = version.to_dictionary()
-                        item_dict["pk"] = pk
-                        item_dict["sk"] = sk
-                        
-                        self.dynamodb.save(
-                            item=item_dict,
-                            table_name=self.table_name
-                        )
+                        version.prep_for_save()
+                        self._save_model(version)
         except Exception:
             pass  # Best effort
     

geek_cafe_saas_sdk/domains/messaging/services/contact_thread_service.py

@@ -20,6 +20,40 @@ class ContactThreadService(DatabaseService[ContactThread]):
     def __init__(self, *, dynamodb: DynamoDB = None, table_name: str = None):
         super().__init__(dynamodb=dynamodb, table_name=table_name)
 
+    def _user_has_cross_tenant_access(self, user_context: Optional[Dict[str, str]]) -> bool:
+        """
+        Determine if user has cross-tenant access to contact threads.
+        
+        Users with cross-tenant access can see threads from any tenant:
+        - Platform admins (roles contains "platform_admin")
+        - Support staff (roles contains "support_staff" or "support_admin")
+        - General admins (roles contains "admin")
+        
+        Args:
+            user_context: User context from JWT containing roles
+            
+        Returns:
+            True if user has cross-tenant access, False otherwise
+        """
+        if not user_context:
+            return False
+        
+        roles = user_context.get("roles", "")
+        
+        cross_tenant_roles = [
+            "platform_admin",
+            "support_admin", 
+            "support_staff",
+            "admin"
+        ]
+        
+        # Check if user has any cross-tenant role
+        for role in cross_tenant_roles:
+            if role in roles:
+                return True
+        
+        return False
+
     def create(self, tenant_id: str, user_id: str, payload: Dict[str, Any]) -> ServiceResult[ContactThread]:
         """
         Create a new contact thread from a payload.
@@ -115,16 +149,22 @@ class ContactThreadService(DatabaseService[ContactThread]):
             return self._handle_service_exception(e, 'get_contact_thread', resource_id=resource_id, tenant_id=tenant_id)
 
     def list_by_inbox_and_status(self, inbox_id: str, status: str, tenant_id: str, 
-                                  priority: str = None, limit: int = 50) -> ServiceResult[List[ContactThread]]:
+                                  priority: str = None, limit: int = 50,
+                                  user_context: Optional[Dict[str, str]] = None) -> ServiceResult[List[ContactThread]]:
         """
         List contact threads by inbox and status using GSI1.
         
+        Supports role-based access control:
+        - Admins/support staff see ALL threads in the inbox (cross-tenant access)
+        - Regular users only see threads from their own tenant
+        
         Args:
             inbox_id: Inbox ID (support, sales, etc.)
             status: Status filter (open, in_progress, resolved, closed)
-            tenant_id: Tenant ID for filtering
+            tenant_id: Tenant ID for filtering (ignored for admins/support)
             priority: Optional priority filter
             limit: Maximum number of results
+            user_context: Optional user context with roles for access control
             
         Returns:
             ServiceResult with list of ContactThreads
@@ -148,11 +188,19 @@ class ContactThreadService(DatabaseService[ContactThread]):
             if not result.success:
                 return result
 
-            # Filter by tenant and exclude deleted threads
-            active_threads = [
-                t for t in result.data 
-                if not t.is_deleted() and t.tenant_id == tenant_id
-            ]
+            # Apply role-based filtering
+            if self._user_has_cross_tenant_access(user_context):
+                # Admins/support: See all threads in the inbox, regardless of tenant
+                active_threads = [
+                    t for t in result.data 
+                    if not t.is_deleted()
+                ]
+            else:
+                # Regular users: Only see threads from their own tenant
+                active_threads = [
+                    t for t in result.data 
+                    if not t.is_deleted() and t.tenant_id == tenant_id
+                ]
 
             return ServiceResult.success_result(active_threads)
 

geek_cafe_saas_sdk/domains/notifications/__init__.py

@@ -0,0 +1,18 @@
+"""
+Notifications Domain.
+
+Multi-channel notification delivery with user preferences and webhook support.
+
+Geek Cafe, LLC
+MIT License. See Project Root for the license information.
+"""
+
+from .models import Notification, NotificationPreference, WebhookSubscription
+from .services import NotificationService
+
+__all__ = [
+    "Notification",
+    "NotificationPreference",
+    "WebhookSubscription",
+    "NotificationService"
+]

geek_cafe_saas_sdk/domains/notifications/handlers/__init__.py

@@ -0,0 +1 @@
+# Notifications Domain Handlers

geek_cafe_saas_sdk/domains/notifications/handlers/create_webhook/app.py

@@ -0,0 +1,73 @@
+"""Lambda handler for creating webhook subscriptions."""
+
+from typing import Dict, Any
+from geek_cafe_saas_sdk.lambda_handlers import create_handler
+from geek_cafe_saas_sdk.domains.notifications.services import NotificationService
+
+
+handler_wrapper = create_handler(
+    service_class=NotificationService,
+    require_body=True,
+    convert_case=True
+)
+
+
+def handler(event: Dict[str, Any], context: Any, injected_service=None) -> Dict[str, Any]:
+    """
+    Create webhook subscription.
+    
+    POST /webhooks
+    
+    Body:
+    {
+        "subscriptionName": "Payment Events",
+        "url": "https://example.com/webhooks/payments",
+        "eventTypes": ["payment.completed", "payment.failed"],
+        "secret": "webhook_secret_key"
+    }
+    """
+    return handler_wrapper.execute(event, context, create_webhook, injected_service)
+
+
+def create_webhook(
+    event: Dict[str, Any],
+    service: NotificationService,
+    user_context: Dict[str, str]
+) -> Any:
+    """Business logic for creating webhook."""
+    tenant_id = user_context.get("tenant_id")
+    payload = event["parsed_body"]
+    
+    subscription_name = payload.get("subscription_name")
+    if not subscription_name:
+        raise ValueError("subscription_name is required")
+    
+    url = payload.get("url")
+    if not url:
+        raise ValueError("url is required")
+    
+    event_types = payload.get("event_types")
+    if not event_types:
+        raise ValueError("event_types is required")
+    
+    # Extract optional fields
+    kwargs = {}
+    optional_fields = [
+        "secret", "api_key", "custom_headers", "http_method", "content_type",
+        "timeout_seconds", "retry_enabled", "max_retries", "retry_delay_seconds",
+        "event_filters", "description", "metadata"
+    ]
+    
+    for field in optional_fields:
+        if field in payload:
+            kwargs[field] = payload[field]
+    
+    result = service.create_webhook_subscription(
+        tenant_id=tenant_id,
+        subscription_name=subscription_name,
+        url=url,
+        event_types=event_types,
+        **kwargs
+    )
+    
+    return result

geek_cafe_saas_sdk/domains/notifications/handlers/get/app.py

@@ -0,0 +1,40 @@
+"""Lambda handler for getting a notification."""
+
+from typing import Dict, Any
+from geek_cafe_saas_sdk.lambda_handlers import create_handler
+from geek_cafe_saas_sdk.domains.notifications.services import NotificationService
+
+
+handler_wrapper = create_handler(
+    service_class=NotificationService,
+    require_body=False,
+    convert_case=True
+)
+
+
+def handler(event: Dict[str, Any], context: Any, injected_service=None) -> Dict[str, Any]:
+    """
+    Get a notification by ID.
+    
+    GET /notifications/{notificationId}
+    """
+    return handler_wrapper.execute(event, context, get_notification, injected_service)
+
+
+def get_notification(
+    event: Dict[str, Any],
+    service: NotificationService,
+    user_context: Dict[str, str]
+) -> Any:
+    """Business logic for getting notification."""
+    tenant_id = user_context.get("tenant_id")
+    
+    path_params = event.get("pathParameters") or {}
+    notification_id = path_params.get("notification_id")
+    
+    if not notification_id:
+        raise ValueError("notification_id is required in path")
+    
+    result = service.get_notification(tenant_id, notification_id)
+    
+    return result

geek_cafe_saas_sdk/domains/notifications/handlers/get_preferences/app.py

@@ -0,0 +1,34 @@
+"""Lambda handler for getting user notification preferences."""
+
+from typing import Dict, Any
+from geek_cafe_saas_sdk.lambda_handlers import create_handler
+from geek_cafe_saas_sdk.domains.notifications.services import NotificationService
+
+
+handler_wrapper = create_handler(
+    service_class=NotificationService,
+    require_body=False,
+    convert_case=True
+)
+
+
+def handler(event: Dict[str, Any], context: Any, injected_service=None) -> Dict[str, Any]:
+    """
+    Get user notification preferences.
+    
+    GET /notifications/preferences
+    """
+    return handler_wrapper.execute(event, context, get_preferences, injected_service)
+
+
+def get_preferences(
+    event: Dict[str, Any],
+    service: NotificationService,
+    user_context: Dict[str, str]
+) -> Any:
+    """Business logic for getting preferences."""
+    user_id = user_context.get("user_id")
+    
+    result = service.get_user_preferences(user_id)
+    
+    return result

geek_cafe_saas_sdk/domains/notifications/handlers/list/app.py

@@ -0,0 +1,43 @@
+"""Lambda handler for listing notifications."""
+
+from typing import Dict, Any
+from geek_cafe_saas_sdk.lambda_handlers import create_handler
+from geek_cafe_saas_sdk.domains.notifications.services import NotificationService
+
+
+handler_wrapper = create_handler(
+    service_class=NotificationService,
+    require_body=False,
+    convert_case=True
+)
+
+
+def handler(event: Dict[str, Any], context: Any, injected_service=None) -> Dict[str, Any]:
+    """
+    List notifications for current user.
+    
+    GET /notifications?unreadOnly=true&limit=50
+    """
+    return handler_wrapper.execute(event, context, list_notifications, injected_service)
+
+
+def list_notifications(
+    event: Dict[str, Any],
+    service: NotificationService,
+    user_context: Dict[str, str]
+) -> Any:
+    """Business logic for listing notifications."""
+    user_id = user_context.get("user_id")
+    
+    params = event.get("queryStringParameters") or {}
+    
+    limit = int(params.get("limit", "50"))
+    unread_only = params.get("unread_only", "false").lower() == "true"
+    
+    result = service.list_notifications(
+        recipient_id=user_id,
+        limit=limit,
+        unread_only=unread_only
+    )
+    
+    return result

geek_cafe_saas_sdk/domains/notifications/handlers/list_webhooks/app.py

@@ -0,0 +1,40 @@
+"""Lambda handler for listing webhook subscriptions."""
+
+from typing import Dict, Any
+from geek_cafe_saas_sdk.lambda_handlers import create_handler
+from geek_cafe_saas_sdk.domains.notifications.services import NotificationService
+
+
+handler_wrapper = create_handler(
+    service_class=NotificationService,
+    require_body=False,
+    convert_case=True
+)
+
+
+def handler(event: Dict[str, Any], context: Any, injected_service=None) -> Dict[str, Any]:
+    """
+    List webhook subscriptions.
+    
+    GET /webhooks?activeOnly=true
+    """
+    return handler_wrapper.execute(event, context, list_webhooks, injected_service)
+
+
+def list_webhooks(
+    event: Dict[str, Any],
+    service: NotificationService,
+    user_context: Dict[str, str]
+) -> Any:
+    """Business logic for listing webhooks."""
+    tenant_id = user_context.get("tenant_id")
+    
+    params = event.get("queryStringParameters") or {}
+    active_only = params.get("active_only", "true").lower() == "true"
+    
+    result = service.list_webhook_subscriptions(
+        tenant_id=tenant_id,
+        active_only=active_only
+    )
+    
+    return result

geek_cafe_saas_sdk/domains/notifications/handlers/mark_read/app.py

@@ -0,0 +1,40 @@
+"""Lambda handler for marking notification as read."""
+
+from typing import Dict, Any
+from geek_cafe_saas_sdk.lambda_handlers import create_handler
+from geek_cafe_saas_sdk.domains.notifications.services import NotificationService
+
+
+handler_wrapper = create_handler(
+    service_class=NotificationService,
+    require_body=False,
+    convert_case=True
+)
+
+
+def handler(event: Dict[str, Any], context: Any, injected_service=None) -> Dict[str, Any]:
+    """
+    Mark notification as read.
+    
+    PATCH /notifications/{notificationId}/read
+    """
+    return handler_wrapper.execute(event, context, mark_read, injected_service)
+
+
+def mark_read(
+    event: Dict[str, Any],
+    service: NotificationService,
+    user_context: Dict[str, str]
+) -> Any:
+    """Business logic for marking as read."""
+    tenant_id = user_context.get("tenant_id")
+    
+    path_params = event.get("pathParameters") or {}
+    notification_id = path_params.get("notification_id")
+    
+    if not notification_id:
+        raise ValueError("notification_id is required in path")
+    
+    result = service.mark_as_read(tenant_id, notification_id)
+    
+    return result