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

geek_cafe_saas_sdk/decorators/core.py

@@ -0,0 +1,358 @@
+"""
+Core Lambda handler decorators for common cross-cutting concerns.
+
+These decorators handle:
+- Error handling and standardized error responses
+- CORS headers
+- Request body parsing and case conversion
+- Service injection with pooling
+- Path parameter validation
+- User context extraction
+- Execution logging
+"""
+
+import json
+import time
+import functools
+from typing import Callable, Any, Dict, Optional, Type, List
+from aws_lambda_powertools import Logger
+
+from geek_cafe_saas_sdk.utilities.response import error_response, success_response
+from geek_cafe_saas_sdk.utilities.lambda_event_utility import LambdaEventUtility
+from geek_cafe_saas_sdk.middleware.auth import extract_user_context
+from geek_cafe_saas_sdk.lambda_handlers._base.service_pool import ServicePool
+
+logger = Logger()
+
+
+def handle_errors(handler: Callable) -> Callable:
+    """
+    Catch exceptions and return standardized error responses.
+    
+    Converts Python exceptions into API Gateway-compatible error responses
+    with appropriate status codes and error messages.
+    
+    Usage:
+        @handle_errors
+        def handler(event, context):
+            # Any exception becomes a 500 response
+            raise ValueError("Something went wrong")
+    
+    Returns:
+        Decorated handler that catches exceptions
+    """
+    @functools.wraps(handler)
+    def wrapper(event: Dict[str, Any], context: Any, *args, **kwargs) -> Dict[str, Any]:
+        try:
+            return handler(event, context, *args, **kwargs)
+        except ValueError as e:
+            # Validation errors -> 400
+            logger.warning(f"Validation error: {e}")
+            return error_response(str(e), "VALIDATION_ERROR", 400)
+        except PermissionError as e:
+            # Permission errors -> 403
+            logger.warning(f"Permission error: {e}")
+            return error_response(str(e), "PERMISSION_DENIED", 403)
+        except KeyError as e:
+            # Missing required field -> 400
+            logger.warning(f"Missing field: {e}")
+            return error_response(f"Missing required field: {str(e)}", "MISSING_FIELD", 400)
+        except Exception as e:
+            # Unexpected errors -> 500
+            logger.exception(f"Unexpected error in handler: {e}")
+            return error_response(
+                "An unexpected error occurred",
+                "INTERNAL_ERROR",
+                500
+            )
+    return wrapper
+
+
+def add_cors(
+    allow_origin: str = "*",
+    allow_methods: str = "GET,POST,PUT,DELETE,OPTIONS",
+    allow_headers: str = "Content-Type,Authorization,X-Api-Key"
+) -> Callable:
+    """
+    Add CORS headers to response.
+    
+    Args:
+        allow_origin: Allowed origins (default: "*")
+        allow_methods: Allowed HTTP methods
+        allow_headers: Allowed headers
+    
+    Usage:
+        @add_cors()
+        def handler(event, context):
+            return {'statusCode': 200, 'body': '{}'}
+        
+        # Custom CORS
+        @add_cors(allow_origin="https://example.com")
+        def handler(event, context):
+            return {'statusCode': 200, 'body': '{}'}
+    
+    Returns:
+        Decorated handler with CORS headers
+    """
+    def decorator(handler: Callable) -> Callable:
+        @functools.wraps(handler)
+        def wrapper(event: Dict[str, Any], context: Any, *args, **kwargs) -> Dict[str, Any]:
+            response = handler(event, context, *args, **kwargs)
+            
+            # Ensure headers dict exists
+            if 'headers' not in response:
+                response['headers'] = {}
+            
+            # Add CORS headers
+            response['headers']['Access-Control-Allow-Origin'] = allow_origin
+            response['headers']['Access-Control-Allow-Methods'] = allow_methods
+            response['headers']['Access-Control-Allow-Headers'] = allow_headers
+            
+            return response
+        return wrapper
+    return decorator
+
+
+def parse_request_body(
+    required: bool = False,
+    convert_case: bool = True
+) -> Callable:
+    """
+    Parse request body from JSON and optionally convert case.
+    
+    Parses event['body'] as JSON and adds it to event['parsed_body'].
+    Optionally converts camelCase to snake_case for backend processing.
+    
+    Args:
+        required: If True, returns 400 error if body is missing
+        convert_case: If True, converts camelCase keys to snake_case
+    
+    Usage:
+        @parse_request_body(required=True)
+        def handler(event, context):
+            payload = event['parsed_body']
+            return {'statusCode': 200, 'body': json.dumps(payload)}
+    
+    Returns:
+        Decorated handler with parsed body in event['parsed_body']
+    """
+    def decorator(handler: Callable) -> Callable:
+        @functools.wraps(handler)
+        def wrapper(event: Dict[str, Any], context: Any, *args, **kwargs) -> Dict[str, Any]:
+            # Check if body is required
+            if required and not event.get('body'):
+                return error_response(
+                    "Request body is required",
+                    "MISSING_BODY",
+                    400
+                )
+            
+            # Parse body if present
+            if event.get('body'):
+                try:
+                    body = LambdaEventUtility.get_body_from_event(event, raise_on_error=required)
+                    
+                    if body and convert_case:
+                        body = LambdaEventUtility.to_snake_case_for_backend(body)
+                    
+                    if body:
+                        event['parsed_body'] = body
+                        
+                except (ValueError, json.JSONDecodeError) as e:
+                    logger.warning(f"Failed to parse request body: {e}")
+                    return error_response(
+                        "Invalid JSON in request body",
+                        "INVALID_JSON",
+                        400
+                    )
+            
+            return handler(event, context, *args, **kwargs)
+        return wrapper
+    return decorator
+
+
+def inject_service(
+    service_class: Type,
+    param_name: str = "service",
+    use_pooling: bool = True,
+    **service_kwargs
+) -> Callable:
+    """
+    Inject service instance into handler.
+    
+    Creates and injects a service instance, optionally using connection pooling.
+    The service is passed as a keyword argument to the handler.
+    
+    Args:
+        service_class: Service class to instantiate
+        param_name: Parameter name to inject (default: "service")
+        use_pooling: Use connection pooling (default: True)
+        **service_kwargs: Additional arguments for service constructor
+    
+    Usage:
+        @inject_service(MessageService)
+        def handler(event, context, service):
+            return service.get_by_id(message_id)
+        
+        # Custom parameter name
+        @inject_service(MessageService, param_name="msg_service")
+        def handler(event, context, msg_service):
+            return msg_service.get_by_id(message_id)
+    
+    Returns:
+        Decorated handler with service injected
+    """
+    # Initialize service pool if using pooling
+    if use_pooling:
+        service_pool = ServicePool(service_class, **service_kwargs)
+    
+    def decorator(handler: Callable) -> Callable:
+        @functools.wraps(handler)
+        def wrapper(event: Dict[str, Any], context: Any, *args, **kwargs) -> Dict[str, Any]:
+            # Get service from pool or create new instance
+            if use_pooling:
+                service = service_pool.get()
+            else:
+                service = service_class(**service_kwargs)
+            
+            # Inject service as keyword argument
+            kwargs[param_name] = service
+            
+            return handler(event, context, *args, **kwargs)
+        return wrapper
+    return decorator
+
+
+def log_execution(
+    log_request: bool = True,
+    log_response: bool = False,
+    log_duration: bool = True
+) -> Callable:
+    """
+    Log handler execution details.
+    
+    Logs request/response details and execution duration for monitoring
+    and debugging purposes.
+    
+    Args:
+        log_request: Log incoming request details
+        log_response: Log response details (be careful with sensitive data)
+        log_duration: Log execution duration
+    
+    Usage:
+        @log_execution(log_response=True)
+        def handler(event, context):
+            return {'statusCode': 200, 'body': '{}'}
+    
+    Returns:
+        Decorated handler with execution logging
+    """
+    def decorator(handler: Callable) -> Callable:
+        @functools.wraps(handler)
+        def wrapper(event: Dict[str, Any], context: Any, *args, **kwargs) -> Dict[str, Any]:
+            start_time = time.time()
+            
+            if log_request:
+                logger.info(
+                    "Handler execution started",
+                    extra={
+                        'function_name': context.function_name if context else 'unknown',
+                        'http_method': event.get('httpMethod'),
+                        'path': event.get('path'),
+                        'request_id': context.aws_request_id if context else 'unknown'
+                    }
+                )
+            
+            # Execute handler
+            response = handler(event, context, *args, **kwargs)
+            
+            duration = time.time() - start_time
+            
+            if log_duration:
+                logger.info(
+                    "Handler execution completed",
+                    extra={
+                        'duration_ms': round(duration * 1000, 2),
+                        'status_code': response.get('statusCode')
+                    }
+                )
+            
+            if log_response:
+                logger.debug(
+                    "Response details",
+                    extra={
+                        'status_code': response.get('statusCode'),
+                        'has_body': 'body' in response
+                    }
+                )
+            
+            return response
+        return wrapper
+    return decorator
+
+
+def validate_path_params(required_params: List[str]) -> Callable:
+    """
+    Validate that required path parameters are present.
+    
+    Args:
+        required_params: List of required path parameter names
+    
+    Usage:
+        @validate_path_params(['tenant_id', 'user_id', 'message_id'])
+        def handler(event, context):
+            # All required params guaranteed to exist
+            message_id = event['pathParameters']['message_id']
+            return {'statusCode': 200}
+    
+    Returns:
+        Decorated handler with validated path parameters
+    """
+    def decorator(handler: Callable) -> Callable:
+        @functools.wraps(handler)
+        def wrapper(event: Dict[str, Any], context: Any, *args, **kwargs) -> Dict[str, Any]:
+            path_params = event.get('pathParameters', {})
+            
+            # Check for missing parameters
+            missing_params = [
+                param for param in required_params
+                if not path_params.get(param)
+            ]
+            
+            if missing_params:
+                return error_response(
+                    f"Missing required path parameters: {', '.join(missing_params)}",
+                    "MISSING_PATH_PARAMS",
+                    400
+                )
+            
+            return handler(event, context, *args, **kwargs)
+        return wrapper
+    return decorator
+
+
+def extract_user_context_decorator(handler: Callable) -> Callable:
+    """
+    Extract user context from JWT and add to event.
+    
+    Extracts user context from API Gateway authorizer and adds it to
+    event['user_context'] for easy access in handler.
+    
+    Usage:
+        @extract_user_context_decorator
+        def handler(event, context):
+            user_id = event['user_context']['user_id']
+            tenant_id = event['user_context']['tenant_id']
+            return {'statusCode': 200}
+    
+    Returns:
+        Decorated handler with user_context in event
+    """
+    @functools.wraps(handler)
+    def wrapper(event: Dict[str, Any], context: Any, *args, **kwargs) -> Dict[str, Any]:
+        # Extract user context from authorizer
+        user_context = extract_user_context(event)
+        event['user_context'] = user_context
+        
+        return handler(event, context, *args, **kwargs)
+    return wrapper

geek_cafe_saas_sdk/domains/analytics/models/__init__.py

@@ -0,0 +1,9 @@
+# Analytics Domain Models
+
+from .website_analytics import WebsiteAnalytics
+from .website_analytics_summary import WebsiteAnalyticsSummary
+
+__all__ = [
+    "WebsiteAnalytics",
+    "WebsiteAnalyticsSummary",
+]

geek_cafe_saas_sdk/domains/analytics/models/website_analytics.py

@@ -0,0 +1,219 @@
+
+from boto3_assist.dynamodb.dynamodb_index import DynamoDBIndex, DynamoDBKey
+from boto3_assist.utilities.string_utility import StringUtility
+import datetime as dt
+from typing import Dict, Any
+from geek_cafe_saas_sdk.models.base_model import BaseModel
+
+
+class WebsiteAnalytics(BaseModel):
+    """
+    Model for storing website analytics data.
+    
+    Supports different analytics types:
+    - general: Page views, sessions, user interactions
+    - error: Error tracking and debugging info
+    - performance: Load times, resource metrics
+    - custom: Custom event tracking
+    """
+    
+    def __init__(self):
+        super().__init__()
+        self._route: str | None = None  # URL route/path (e.g., "/blog/post-123")
+        self._slug: str | None = None  # Slug for the page (e.g., "post-123")
+        self._analytics_type: str = "general"  # general, error, performance, custom
+        self._data: Dict[str, Any] = {}  # Flexible storage for analytics data
+        self._session_id: str | None = None
+        self._user_agent: str | None = None
+        self._ip_address: str | None = None
+        self._referrer: str | None = None
+        
+        self._setup_indexes()
+
+    def _setup_indexes(self):
+        # Primary index: analytics by ID
+        primary: DynamoDBIndex = DynamoDBIndex()
+        primary.name = "primary"
+        primary.partition_key.attribute_name = "pk"
+        primary.partition_key.value = lambda: DynamoDBKey.build_key(
+            ("analytics", self.id)
+        )
+        primary.sort_key.attribute_name = "sk"
+        primary.sort_key.value = lambda: DynamoDBKey.build_key(("analytics", self.id))
+        self.indexes.add_primary(primary)
+        
+        ## GSI: 1
+        # GSI: all analytics records sorted by timestamp
+        gsi: DynamoDBIndex = DynamoDBIndex()
+        gsi.name = "gsi1"
+        gsi.partition_key.attribute_name = f"{gsi.name}_pk"
+        gsi.partition_key.value = lambda: DynamoDBKey.build_key(("analytics", "all"))
+        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)
+
+        ## GSI: 2
+        # GSI: analytics by route/slug for page-specific queries
+        gsi: DynamoDBIndex = DynamoDBIndex()
+        gsi.name = "gsi2"
+        gsi.partition_key.attribute_name = f"{gsi.name}_pk"
+        gsi.partition_key.value = lambda: DynamoDBKey.build_key(
+            ("route", self.route or self.slug)
+        )
+        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)
+
+        ## GSI: 3
+        # GSI: analytics by tenant sorted by timestamp
+        gsi: DynamoDBIndex = DynamoDBIndex()
+        gsi.name = "gsi3"
+        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(
+            ("model", "analytics"), ("ts", self.created_utc_ts)
+        )
+        self.indexes.add_secondary(gsi)
+
+        ## GSI: 4
+        # GSI: analytics by type and timestamp (e.g., all errors, all performance metrics)
+        gsi: DynamoDBIndex = DynamoDBIndex()
+        gsi.name = "gsi4"
+        gsi.partition_key.attribute_name = f"{gsi.name}_pk"
+        gsi.partition_key.value = lambda: DynamoDBKey.build_key(
+            ("analytics-type", self.analytics_type)
+        )
+        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)
+
+        ## GSI: 5
+        # GSI: analytics by tenant and type for filtered queries
+        gsi: DynamoDBIndex = DynamoDBIndex()
+        gsi.name = "gsi5"
+        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(
+            ("type", self.analytics_type), ("ts", self.created_utc_ts)
+        )
+        self.indexes.add_secondary(gsi)
+
+    @property
+    def route(self) -> str | None:
+        return self._route
+
+    @route.setter
+    def route(self, value: str | None):
+        self._route = value
+    
+    @property
+    def slug(self) -> str | None:
+        return self._slug
+
+    @slug.setter
+    def slug(self, value: str | None):
+        self._slug = value
+    
+    @property
+    def analytics_type(self) -> str:
+        return self._analytics_type
+
+    @analytics_type.setter
+    def analytics_type(self, value: str):
+        self._analytics_type = value
+    
+    @property
+    def data(self) -> Dict[str, Any]:
+        return self._data
+
+    @data.setter
+    def data(self, value: Dict[str, Any]):
+        self._data = value
+    
+    @property
+    def session_id(self) -> str | None:
+        return self._session_id
+
+    @session_id.setter
+    def session_id(self, value: str | None):
+        self._session_id = value
+    
+    @property
+    def user_agent(self) -> str | None:
+        return self._user_agent
+
+    @user_agent.setter
+    def user_agent(self, value: str | None):
+        self._user_agent = value
+    
+    @property
+    def ip_address(self) -> str | None:
+        return self._ip_address
+
+    @ip_address.setter
+    def ip_address(self, value: str | None):
+        self._ip_address = value
+    
+    @property
+    def referrer(self) -> str | None:
+        return self._referrer
+
+    @referrer.setter
+    def referrer(self, value: str | None):
+        self._referrer = value
+    
+    # Helper methods for different analytics types
+    def set_page_view(self, route: str, **kwargs):
+        """Set general page view analytics."""
+        self.route = route
+        self.analytics_type = "general"
+        self.data = {
+            "event": "page_view",
+            "duration_ms": kwargs.get("duration_ms"),
+            "scroll_depth": kwargs.get("scroll_depth"),
+            **kwargs
+        }
+    
+    def set_error(self, route: str, error_message: str, **kwargs):
+        """Set error analytics."""
+        self.route = route
+        self.analytics_type = "error"
+        self.data = {
+            "event": "error",
+            "error_message": error_message,
+            "error_type": kwargs.get("error_type"),
+            "stack_trace": kwargs.get("stack_trace"),
+            **kwargs
+        }
+    
+    def set_performance(self, route: str, **kwargs):
+        """Set performance analytics."""
+        self.route = route
+        self.analytics_type = "performance"
+        self.data = {
+            "event": "performance",
+            "load_time_ms": kwargs.get("load_time_ms"),
+            "ttfb_ms": kwargs.get("ttfb_ms"),  # Time to first byte
+            "fcp_ms": kwargs.get("fcp_ms"),  # First contentful paint
+            "lcp_ms": kwargs.get("lcp_ms"),  # Largest contentful paint
+            **kwargs
+        }
+    
+    def set_custom_event(self, route: str, event_name: str, **kwargs):
+        """Set custom event analytics."""
+        self.route = route
+        self.analytics_type = "custom"
+        self.data = {
+            "event": event_name,
+            **kwargs
+        }