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

geek_cafe_saas_sdk/__init__.py

@@ -0,0 +1,9 @@
+"""
+Geek Cafe Services - Base Reusable Services for SaaS
+
+Version 0.2.0 adds Lambda Handler Wrappers for reducing boilerplate code.
+"""
+__version__ = "0.6.0"
+
+# Import main modules for easier access
+from . import services

geek_cafe_saas_sdk/core/__init__.py

@@ -0,0 +1,11 @@
+# Core module for foundational classes and utilities
+
+from .service_errors import ValidationError, AccessDeniedError, NotFoundError
+from .service_result import ServiceResult
+
+__all__ = [
+    'ValidationError',
+    'AccessDeniedError',
+    'NotFoundError',
+    'ServiceResult',
+]

geek_cafe_saas_sdk/core/audit_mixin.py

@@ -0,0 +1,33 @@
+from typing import Optional, Dict
+from datetime import datetime
+import logging
+
+
+class AuditMixin:
+    """Mixin for services that need audit logging."""
+    
+    def _log_activity(self, action: str, resource_type: str, resource_id: str,
+                     tenant_id: str, user_id: str, metadata: Optional[Dict] = None) -> None:
+        """Log activity for audit purposes."""
+        logger = logging.getLogger(f"{__name__}.audit")
+        
+        audit_data = {
+            'action': action,
+            'resource_type': resource_type,
+            'resource_id': resource_id,
+            'tenant_id': tenant_id,
+            'user_id': user_id,
+            'timestamp': datetime.now().isoformat(),
+            'metadata': metadata or {}
+        }
+        
+        logger.info(
+            f"AUDIT: {action} on {resource_type} {resource_id} by user {user_id}",
+            extra=audit_data
+        )
+        
+        # Also print for console visibility
+        print(f"📋 AUDIT: {action} on {resource_type} {resource_id} by user {user_id}")
+        
+    # TODO: Implement activity logging to database such as dynamodb or put into a queue
+        

geek_cafe_saas_sdk/core/error_codes.py

@@ -0,0 +1,132 @@
+"""
+Geek Cafe, LLC
+MIT License. See Project Root for the license information.
+
+Standardized error codes for all services.
+"""
+
+from enum import Enum
+
+
+class ErrorCode(str, Enum):
+    """
+    Standardized error codes for all services.
+    
+    Error codes are organized by category and map to HTTP status code equivalents.
+    Using an enum ensures type safety and consistency across all services.
+    """
+    
+    # Input/Validation Errors (4xx equivalent)
+    VALIDATION_ERROR = "VALIDATION_ERROR"              # Invalid input data
+    MISSING_REQUIRED_FIELD = "MISSING_REQUIRED_FIELD"  # Specific validation failure
+    INVALID_FORMAT = "INVALID_FORMAT"                  # Data format issues
+    INVALID_PARAMETER = "INVALID_PARAMETER"            # Parameter value issues
+    
+    # Authorization Errors (403 equivalent)
+    ACCESS_DENIED = "ACCESS_DENIED"                    # User lacks permission
+    INSUFFICIENT_PERMISSIONS = "INSUFFICIENT_PERMISSIONS"  # Role-based denial
+    AUTHENTICATION_REQUIRED = "AUTHENTICATION_REQUIRED"  # No auth token provided
+    
+    # Resource Errors (404 equivalent)
+    NOT_FOUND = "NOT_FOUND"                            # Resource doesn't exist
+    RESOURCE_DELETED = "RESOURCE_DELETED"              # Resource was soft-deleted
+    
+    # Conflict Errors (409 equivalent)
+    ALREADY_EXISTS = "ALREADY_EXISTS"                  # Duplicate resource
+    CONCURRENT_MODIFICATION = "CONCURRENT_MODIFICATION"  # Optimistic lock failure
+    RESOURCE_CONFLICT = "RESOURCE_CONFLICT"            # General conflict
+    
+    # Database Errors (500 equivalent)
+    DATABASE_ERROR = "DATABASE_ERROR"                  # Generic DB error
+    DATABASE_SAVE_FAILED = "DATABASE_SAVE_FAILED"      # Save operation failed
+    DATABASE_DELETE_FAILED = "DATABASE_DELETE_FAILED"  # Delete operation failed
+    DATABASE_QUERY_FAILED = "DATABASE_QUERY_FAILED"    # Query operation failed
+    DATABASE_CONNECTION_ERROR = "DATABASE_CONNECTION_ERROR"  # Connection issues
+    
+    # Service/Business Logic Errors (500 equivalent)
+    INTERNAL_ERROR = "INTERNAL_ERROR"                  # Unexpected error
+    SERVICE_UNAVAILABLE = "SERVICE_UNAVAILABLE"        # Dependency failure
+    OPERATION_FAILED = "OPERATION_FAILED"              # Business logic failure
+    
+    # Batch/Bulk Operation Errors
+    PARTIAL_FAILURE = "PARTIAL_FAILURE"                # Some items in batch failed
+    BATCH_OPERATION_FAILED = "BATCH_OPERATION_FAILED"  # Entire batch failed
+    
+    # Rate Limiting / Throttling (429 equivalent)
+    RATE_LIMIT_EXCEEDED = "RATE_LIMIT_EXCEEDED"        # Too many requests
+    QUOTA_EXCEEDED = "QUOTA_EXCEEDED"                  # Usage quota exceeded
+    
+    def __str__(self) -> str:
+        """Return the error code value as string."""
+        return self.value
+    
+    @classmethod
+    def is_client_error(cls, code: 'ErrorCode') -> bool:
+        """
+        Check if error code represents a client error (4xx equivalent).
+        
+        Args:
+            code: Error code to check
+            
+        Returns:
+            True if client error, False otherwise
+        """
+        client_errors = {
+            cls.VALIDATION_ERROR,
+            cls.MISSING_REQUIRED_FIELD,
+            cls.INVALID_FORMAT,
+            cls.INVALID_PARAMETER,
+            cls.ACCESS_DENIED,
+            cls.INSUFFICIENT_PERMISSIONS,
+            cls.AUTHENTICATION_REQUIRED,
+            cls.NOT_FOUND,
+            cls.RESOURCE_DELETED,
+            cls.ALREADY_EXISTS,
+            cls.CONCURRENT_MODIFICATION,
+            cls.RESOURCE_CONFLICT,
+            cls.RATE_LIMIT_EXCEEDED,
+            cls.QUOTA_EXCEEDED,
+        }
+        return code in client_errors
+    
+    @classmethod
+    def is_server_error(cls, code: 'ErrorCode') -> bool:
+        """
+        Check if error code represents a server error (5xx equivalent).
+        
+        Args:
+            code: Error code to check
+            
+        Returns:
+            True if server error, False otherwise
+        """
+        return not cls.is_client_error(code)
+    
+    @classmethod
+    def get_http_status(cls, code: 'ErrorCode') -> int:
+        """
+        Get suggested HTTP status code for error code.
+        
+        Args:
+            code: Error code
+            
+        Returns:
+            HTTP status code (e.g., 400, 404, 500)
+        """
+        status_map = {
+            cls.VALIDATION_ERROR: 400,
+            cls.MISSING_REQUIRED_FIELD: 400,
+            cls.INVALID_FORMAT: 400,
+            cls.INVALID_PARAMETER: 400,
+            cls.AUTHENTICATION_REQUIRED: 401,
+            cls.ACCESS_DENIED: 403,
+            cls.INSUFFICIENT_PERMISSIONS: 403,
+            cls.NOT_FOUND: 404,
+            cls.RESOURCE_DELETED: 410,  # Gone
+            cls.ALREADY_EXISTS: 409,
+            cls.CONCURRENT_MODIFICATION: 409,
+            cls.RESOURCE_CONFLICT: 409,
+            cls.RATE_LIMIT_EXCEEDED: 429,
+            cls.QUOTA_EXCEEDED: 429,
+        }
+        return status_map.get(code, 500)  # Default to 500 for server errors

geek_cafe_saas_sdk/core/service_errors.py

@@ -0,0 +1,19 @@
+# Service Errors
+from typing import Optional, Union, List
+
+class ValidationError(Exception):
+    """Validation error for service operations."""
+    
+    def __init__(self, message: str, field: Optional[Union[str, List[str]]] = None):
+        super().__init__(message)
+        self.field = field
+
+
+class AccessDeniedError(Exception):
+    """Access denied error for service operations."""
+    pass
+
+
+class NotFoundError(Exception):
+    """Resource not found error."""
+    pass

geek_cafe_saas_sdk/core/service_result.py

@@ -0,0 +1,121 @@
+"""Base service classes for collaborative property operations."""
+
+
+import traceback
+from typing import Any, Dict, List, Optional, TypeVar, Generic
+from datetime import datetime
+
+from aws_lambda_powertools import Logger
+
+logger = Logger()
+
+
+T = TypeVar('T')
+
+
+class ServiceResult(Generic[T]):
+    """Standard service operation result with enhanced error handling."""
+    
+    def __init__(self, success: bool, data: Optional[T] = None, 
+                 message: Optional[str] = None, error_code: Optional[str] = None,
+                 error_details: Optional[Dict[str, Any]] = None,
+                 stack_trace: Optional[str] = None):
+        self.success = success
+        self.data = data
+        self.message = message
+        self.error_code = error_code
+        self.error_details = error_details or {}
+        self.stack_trace = stack_trace
+        self.timestamp = datetime.now()
+    
+    @classmethod
+    def success_result(cls, data: T) -> 'ServiceResult[T]':
+        """Create a successful result."""
+        return cls(success=True, data=data)
+    
+    @classmethod
+    def error_result(cls, message: str, error_code: Optional[str] = None, 
+                    error_details: Optional[Dict[str, Any]] = None) -> 'ServiceResult[T]':
+        """Create an error result with basic error information."""
+        return cls(success=False, message=message, error_code=error_code, error_details=error_details)
+    
+    @classmethod
+    def exception_result(cls, exception: Exception, error_code: Optional[str] = None,
+                        context: Optional[str] = None) -> 'ServiceResult[T]':
+        """Create an error result from an exception with full stack trace logging."""
+        
+        # Get the full stack trace
+        stack_trace = traceback.format_exc()
+        
+        # Create detailed error message
+        error_message = f"{type(exception).__name__}: {str(exception)}"
+        if context:
+            error_message = f"{context} - {error_message}"
+        
+        # Prepare error details
+        error_details = {
+            'exception_type': type(exception).__name__,
+            'exception_message': str(exception),
+            'context': context,
+            'timestamp': datetime.now().isoformat()
+        }
+        
+        # Log the full error with stack trace to CloudWatch
+        logger.error(
+            f"Service operation failed: {error_message}\n"
+            f"Context: {context or 'None'}\n"
+            f"Exception Type: {type(exception).__name__}\n"
+            f"Exception Message: {str(exception)}\n"
+            f"Stack Trace:\n{stack_trace}",
+            extra={
+                'error_code': error_code,
+                'exception_type': type(exception).__name__,
+                'context': context,
+                'stack_trace': stack_trace
+            }
+        )
+        
+        # Also print to console for immediate visibility
+        print(f"\n🚨 SERVICE ERROR: {error_message}")
+        print(f"📍 Context: {context or 'None'}")
+        print(f"🔍 Exception Type: {type(exception).__name__}")
+        print(f"📝 Stack Trace:")
+        print(stack_trace)
+        print("" + "="*80 + "")
+        
+        return cls(
+            success=False, 
+            message=error_message, 
+            error_code=error_code or 'INTERNAL_ERROR',
+            error_details=error_details,
+            stack_trace=stack_trace
+        )
+    
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert result to dictionary for API responses."""
+        result = {
+            'success': self.success,
+            'timestamp': self.timestamp.isoformat()
+        }
+        
+        if self.success:
+            result['data'] = self.data
+        else:
+            result['error'] = {
+                'message': self.message,
+                'code': self.error_code,
+                'details': self.error_details
+            }
+            # Only include stack trace in development/debug mode
+            # You might want to add a flag to control this
+            if self.stack_trace:
+                result['error']['stack_trace'] = self.stack_trace
+        
+        return result
+
+
+
+
+
+
+

geek_cafe_saas_sdk/decorators/__init__.py

@@ -0,0 +1,64 @@
+"""
+Lambda handler decorators for cross-cutting concerns.
+
+This module provides composable decorators for Lambda handlers following
+industry best practices (AWS Lambda Powertools, Flask, FastAPI patterns).
+
+Usage:
+    from geek_cafe_saas_sdk.decorators import (
+        handle_errors,
+        add_cors,
+        parse_request_body,
+        inject_service
+    )
+    
+    @handle_errors
+    @add_cors
+    @parse_request_body(convert_case=True)
+    @inject_service(MessageService)
+    def handler(event, context, service):
+        return service.get_by_id(event['pathParameters']['id'])
+
+Design Principles:
+    - Explicit > Implicit: See all behaviors in handler signature
+    - Composable: Stack decorators as needed
+    - Single Responsibility: Each decorator has one job
+    - Testable: Test handlers and decorators independently
+    - Industry Standard: Follows AWS Lambda Powertools patterns
+"""
+
+from .core import (
+    handle_errors,
+    add_cors,
+    parse_request_body,
+    inject_service,
+    log_execution,
+    validate_path_params,
+    extract_user_context_decorator
+)
+
+from .auth import (
+    require_authorization,
+    require_admin,
+    require_tenant_admin,
+    require_platform_admin,
+    public
+)
+
+__all__ = [
+    # Core decorators
+    "handle_errors",
+    "add_cors",
+    "parse_request_body",
+    "inject_service",
+    "log_execution",
+    "validate_path_params",
+    "extract_user_context_decorator",
+    
+    # Auth decorators
+    "require_authorization",
+    "require_admin",
+    "require_tenant_admin",
+    "require_platform_admin",
+    "public",
+]