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

geek_cafe_saas_sdk/lambda_handlers/README.md

@@ -0,0 +1,404 @@
+# Lambda Handler Reference Implementations
+
+## Overview
+
+This directory contains **reference Lambda handler implementations** for the file system services. These handlers are **templates** meant to be copied and customized by projects consuming this SDK.
+
+## Important: These Are Not Deployed
+
+**This SDK does not deploy Lambda functions to AWS.** These handlers serve as:
+
+- ✅ **Reference implementations** showing how to use the SDK services
+- ✅ **Starting templates** for your own Lambda functions  
+- ✅ **Best practice examples** for structuring handlers
+- ✅ **Integration patterns** with API Gateway
+
+## How to Use
+
+### 1. Install the SDK in Your Project
+
+```bash
+pip install geek-cafe-saas-sdk
+```
+
+### 2. Copy Handlers You Need
+
+Copy the handler files into your project:
+
+```bash
+# Copy specific handler
+cp lambda_handlers/files/upload/app.py my-project/handlers/file_upload.py
+
+# Or copy entire categories
+cp -r lambda_handlers/files my-project/handlers/
+```
+
+### 3. Customize for Your Needs
+
+All handlers follow this pattern:
+
+```python
+from geek_cafe_saas_sdk.domains.files.services.file_system_service import FileSystemService
+
+def lambda_handler(event, context):
+    # 1. Extract parameters from event
+    # 2. Initialize services from SDK
+    # 3. Call service methods
+    # 4. Return formatted response
+```
+
+Customize:
+- **Authentication**: Add Cognito, JWT, or custom auth
+- **Validation**: Add business-specific rules
+- **Error handling**: Match your error format
+- **Logging**: Integrate with your logging system
+- **Metrics**: Add custom CloudWatch metrics
+
+### 4. Deploy with Your Infrastructure
+
+Deploy using your preferred tool:
+
+**AWS SAM:**
+```yaml
+FileUploadFunction:
+  Type: AWS::Serverless::Function
+  Properties:
+    CodeUri: handlers/
+    Handler: file_upload.lambda_handler
+```
+
+**Serverless Framework:**
+```yaml
+functions:
+  fileUpload:
+    handler: handlers/file_upload.lambda_handler
+```
+
+**AWS CDK:**
+```python
+lambda_.Function(
+    self, "FileUpload",
+    handler="file_upload.lambda_handler",
+    code=lambda_.Code.from_asset("handlers")
+)
+```
+
+---
+
+## Handler Structure
+
+### File Operations
+
+| Handler | Path | Purpose |
+|---------|------|---------|
+| `files/upload/app.py` | `POST /files` | Upload new file |
+| `files/download/app.py` | `GET /files/{id}/download` | Download file |
+| `files/get/app.py` | `GET /files/{id}` | Get metadata |
+| `files/update/app.py` | `PUT /files/{id}` | Update metadata |
+| `files/delete/app.py` | `DELETE /files/{id}` | Delete file |
+| `files/list/app.py` | `GET /files` | List files |
+
+### Directory Operations
+
+| Handler | Path | Purpose |
+|---------|------|---------|
+| `directories/create/app.py` | `POST /directories` | Create directory |
+| `directories/get/app.py` | `GET /directories/{id}` | Get directory |
+| `directories/list/app.py` | `GET /directories` | List directories |
+| `directories/move/app.py` | `PUT /directories/{id}/move` | Move directory |
+| `directories/delete/app.py` | `DELETE /directories/{id}` | Delete directory |
+
+### Sharing Operations
+
+| Handler | Path | Purpose |
+|---------|------|---------|
+| `files/share/app.py` | `POST /files/share` | Share file |
+| `files/shares/list/app.py` | `GET /files/shares` | List shares |
+| `files/shares/revoke/app.py` | `DELETE /files/shares/{id}` | Revoke share |
+
+---
+
+## Common Customizations
+
+### Add Authentication
+
+```python
+def lambda_handler(event, context):
+    # Validate JWT token
+    token = event['headers'].get('Authorization')
+    user = validate_token(token)
+    
+    # Use validated user_id
+    result = file_service.create(
+        tenant_id=user.tenant_id,
+        user_id=user.user_id,
+        ...
+    )
+```
+
+### Add Request Validation
+
+```python
+def lambda_handler(event, context):
+    body = json.loads(event['body'])
+    
+    # Validate with your schema
+    errors = validate_upload_request(body)
+    if errors:
+        return {
+            'statusCode': 400,
+            'body': json.dumps({'errors': errors})
+        }
+```
+
+### Add Custom Error Handling
+
+```python
+def lambda_handler(event, context):
+    try:
+        result = file_service.create(...)
+        
+        if not result.success:
+            # Map SDK errors to your error codes
+            error_code = map_error_code(result.error_code)
+            return custom_error_response(error_code, result.message)
+    
+    except CustomException as e:
+        # Handle business exceptions
+        return business_error_response(e)
+```
+
+### Add Logging and Metrics
+
+```python
+import logging
+from aws_lambda_powertools import Logger, Metrics
+
+logger = Logger()
+metrics = Metrics()
+
+@logger.inject_lambda_context
+@metrics.log_metrics
+def lambda_handler(event, context):
+    logger.info("File upload requested", extra={
+        "tenant_id": tenant_id,
+        "file_name": file_name
+    })
+    
+    metrics.add_metric(name="FileUploads", unit="Count", value=1)
+    
+    result = file_service.create(...)
+    
+    if result.success:
+        metrics.add_metric(name="FileUploadSuccess", unit="Count", value=1)
+    else:
+        metrics.add_metric(name="FileUploadFailure", unit="Count", value=1)
+```
+
+---
+
+## Environment Variables
+
+All handlers expect these environment variables:
+
+```bash
+DYNAMODB_TABLE_NAME=your-table-name
+S3_BUCKET_NAME=your-bucket-name
+AWS_REGION=us-east-1
+```
+
+Set these in your infrastructure code:
+
+```yaml
+# SAM
+Environment:
+  Variables:
+    DYNAMODB_TABLE_NAME: !Ref FilesTable
+    S3_BUCKET_NAME: !Ref FilesBucket
+```
+
+---
+
+## Required Dependencies
+
+When deploying, include:
+
+```
+geek-cafe-saas-sdk
+boto3
+boto3-assist
+```
+
+Use Lambda Layers for dependencies:
+
+```bash
+# Create layer
+mkdir -p layer/python
+pip install -t layer/python geek-cafe-saas-sdk boto3-assist
+cd layer && zip -r ../dependencies.zip .
+```
+
+---
+
+## Testing Handlers Locally
+
+### With SAM CLI
+
+```bash
+# Create test event
+cat > test-event.json <<EOF
+{
+  "body": {
+    "tenant_id": "test",
+    "user_id": "user1",
+    "file_name": "test.txt",
+    "file_data": "SGVsbG8="
+  }
+}
+EOF
+
+# Invoke locally
+sam local invoke FileUploadFunction -e test-event.json
+```
+
+### With Python
+
+```python
+from your_handlers.file_upload import lambda_handler
+
+event = {
+    "body": {
+        "tenant_id": "test",
+        "user_id": "user1",
+        "file_name": "test.txt",
+        "file_data": "SGVsbG8="
+    }
+}
+
+response = lambda_handler(event, None)
+print(response)
+```
+
+---
+
+## Example: Complete Custom Handler
+
+Here's how to create a custom handler based on the SDK:
+
+```python
+"""
+Custom file upload handler for MyApp.
+"""
+
+import json
+import base64
+import os
+from typing import Dict, Any
+
+from geek_cafe_saas_sdk.domains.files.services.file_system_service import FileSystemService
+from geek_cafe_saas_sdk.domains.files.services.s3_file_service import S3FileService
+from boto3_assist.dynamodb.dynamodb import DynamoDB
+from boto3_assist.s3.s3_connection import S3Connection
+from boto3_assist.s3.s3_object import S3Object
+from boto3_assist.s3.s3_bucket import S3Bucket
+
+from myapp.auth import validate_jwt
+from myapp.validation import validate_file_upload
+from myapp.logging import get_logger
+
+logger = get_logger(__name__)
+
+
+def lambda_handler(event: Dict[str, Any], context: Any) -> Dict[str, Any]:
+    """Custom file upload handler with MyApp-specific logic."""
+    
+    # 1. Authenticate user
+    try:
+        user = validate_jwt(event['headers']['Authorization'])
+    except Exception as e:
+        return {
+            'statusCode': 401,
+            'body': json.dumps({'error': 'Unauthorized'})
+        }
+    
+    # 2. Parse and validate request
+    body = json.loads(event['body'])
+    errors = validate_file_upload(body, user)
+    if errors:
+        return {
+            'statusCode': 400,
+            'body': json.dumps({'errors': errors})
+        }
+    
+    # 3. Initialize SDK services
+    db = DynamoDB()
+    connection = S3Connection()
+    
+    s3_service = S3FileService(
+        s3_object=S3Object(connection=connection),
+        s3_bucket=S3Bucket(connection=connection),
+        default_bucket=os.environ['S3_BUCKET_NAME']
+    )
+    
+    file_service = FileSystemService(
+        dynamodb=db,
+        table_name=os.environ['DYNAMODB_TABLE_NAME'],
+        s3_service=s3_service,
+        default_bucket=os.environ['S3_BUCKET_NAME']
+    )
+    
+    # 4. Upload file using SDK
+    try:
+        result = file_service.create(
+            tenant_id=user.tenant_id,
+            user_id=user.user_id,
+            file_name=body['file_name'],
+            file_data=base64.b64decode(body['file_data']),
+            mime_type=body.get('mime_type', 'application/octet-stream'),
+            directory_id=body.get('directory_id'),
+            tags=body.get('tags', [])
+        )
+        
+        if result.success:
+            logger.info(f"File uploaded: {result.data.file_id}")
+            
+            # 5. Return MyApp-formatted response
+            return {
+                'statusCode': 201,
+                'body': json.dumps({
+                    'id': result.data.file_id,
+                    'name': result.data.file_name,
+                    'size': result.data.file_size,
+                    'created_at': result.data.created_utc_ts
+                })
+            }
+        else:
+            logger.error(f"Upload failed: {result.message}")
+            return {
+                'statusCode': 400,
+                'body': json.dumps({
+                    'error': result.message,
+                    'code': result.error_code
+                })
+            }
+    
+    except Exception as e:
+        logger.exception("Unexpected error during upload")
+        return {
+            'statusCode': 500,
+            'body': json.dumps({'error': 'Internal server error'})
+        }
+```
+
+---
+
+## Support
+
+- **Service Documentation**: See main SDK docs for service usage
+- **Usage Examples**: See `docs/FILE_SYSTEM_USAGE.md`
+- **API Reference**: See `docs/FILE_SYSTEM_API.md`
+- **Integration Tests**: See `tests/test_files_integration.py` for complete workflows
+
+---
+
+**Remember**: These handlers are starting points. Customize them to fit your application's needs!

geek_cafe_saas_sdk/lambda_handlers/__init__.py

@@ -0,0 +1,67 @@
+"""
+Lambda handler wrappers for reducing boilerplate in AWS Lambda functions.
+
+This module provides a flexible, composable system for creating Lambda handlers
+with built-in support for:
+- API key validation
+- API Gateway authorization (Cognito/Lambda authorizers)
+- Public endpoints (no auth)
+- Request/response transformation
+- Service initialization and pooling
+- Error handling and CORS
+- User context extraction
+
+Example Usage with Factory (Recommended):
+    from geek_cafe_saas_sdk.lambda_handlers import create_handler
+    from geek_cafe_saas_sdk.services.vote_service import VoteService
+    
+    # Factory automatically selects handler based on AUTH_TYPE env var
+    # Defaults to secure (API Gateway authorizer) if not set
+    handler = create_handler(
+        service_class=VoteService,
+        require_body=True,
+        convert_case=True
+    )
+    
+    def lambda_handler(event, context):
+        return handler.execute(event, context, business_logic)
+    
+    def business_logic(event, service, user_context):
+        payload = event["parsed_body"]
+        return service.create_vote(...)
+
+Environment Configuration:
+    AUTH_TYPE=secure    # API Gateway authorizer (default)
+    AUTH_TYPE=api_key   # x-api-key header validation
+    AUTH_TYPE=public    # No authentication
+    
+    AUTH_STRICT=true    # Strict validation (default)
+    AUTH_STRICT=false   # Permissive for local dev
+
+Direct Usage (if needed):
+    from geek_cafe_saas_sdk.lambda_handlers import SecureLambdaHandler
+    
+    handler = SecureLambdaHandler(
+        service_class=VoteService,
+        require_body=True
+    )
+"""
+
+from ._base.base_handler import BaseLambdaHandler
+from ._base.api_key_handler import ApiKeyLambdaHandler
+from ._base.public_handler import PublicLambdaHandler
+from ._base.secure_handler import SecureLambdaHandler
+from ._base.authorized_secure_handler import AuthorizedSecureLambdaHandler
+from ._base.service_pool import ServicePool
+from ._base.handler_factory import HandlerFactory, create_handler
+
+__all__ = [
+    "BaseLambdaHandler",
+    "ApiKeyLambdaHandler", 
+    "PublicLambdaHandler",
+    "SecureLambdaHandler",
+    "AuthorizedSecureLambdaHandler",
+    "ServicePool",
+    "HandlerFactory",
+    "create_handler",
+]

geek_cafe_saas_sdk/lambda_handlers/_base/__init__.py

@@ -0,0 +1,25 @@
+"""
+Base Lambda handler implementations.
+
+This module contains the core handler infrastructure that all Lambda handlers
+can build upon. These are internal/shared components.
+"""
+
+from .base_handler import BaseLambdaHandler
+from .api_key_handler import ApiKeyLambdaHandler
+from .public_handler import PublicLambdaHandler
+from .secure_handler import SecureLambdaHandler
+from .authorized_secure_handler import AuthorizedSecureLambdaHandler
+from .service_pool import ServicePool
+from .handler_factory import HandlerFactory, create_handler
+
+__all__ = [
+    'BaseLambdaHandler',
+    'ApiKeyLambdaHandler',
+    'PublicLambdaHandler',
+    'SecureLambdaHandler',
+    'AuthorizedSecureLambdaHandler',
+    'ServicePool',
+    'HandlerFactory',
+    'create_handler',
+]

geek_cafe_saas_sdk/lambda_handlers/_base/api_key_handler.py

@@ -0,0 +1,129 @@
+"""
+Lambda handler with API key validation.
+
+Implements the API key validation pattern used across the application.
+"""
+
+import os
+from typing import Dict, Any, Optional, Callable, TypeVar
+from aws_lambda_powertools import Logger
+
+from geek_cafe_saas_sdk.utilities.response import error_response
+from geek_cafe_saas_sdk.utilities.lambda_event_utility import LambdaEventUtility
+from .base_handler import BaseLambdaHandler
+
+logger = Logger()
+T = TypeVar('T')
+
+
+class ApiKeyLambdaHandler(BaseLambdaHandler):
+    """
+    Lambda handler with API key validation.
+    
+    Validates that requests include a valid API key in the x-api-key header.
+    The expected API key is read from the API_KEY environment variable.
+    
+    Example:
+        handler = ApiKeyLambdaHandler(
+            service_class=VoteService,
+            require_body=True
+        )
+        
+        def lambda_handler(event, context):
+            return handler.execute(event, context, process_vote)
+        
+        def process_vote(event, service, user_context):
+            payload = event["parsed_body"]
+            return service.create_vote(...)
+    """
+    
+    def __init__(
+        self,
+        api_key_env_var: str = "API_KEY",
+        api_key_header: str = "x-api-key",
+        **kwargs
+    ):
+        """
+        Initialize the API key handler.
+        
+        Args:
+            api_key_env_var: Environment variable name for API key
+            api_key_header: Header name to check for API key
+            **kwargs: Arguments passed to BaseLambdaHandler
+        """
+        # API key handlers don't require JWT auth - API key IS the auth
+        kwargs.setdefault('require_auth', False)
+        super().__init__(**kwargs)
+        self.api_key_env_var = api_key_env_var
+        self.api_key_header = api_key_header
+    
+    def _validate_security(self, event: Dict[str, Any]) -> Optional[Dict[str, Any]]:
+        """
+        Validate API key is present and correct at request time.
+
+        This method reads the API_KEY environment variable within the request
+        cycle, making it testable.
+
+        Returns:
+            Error response if validation fails, None if valid.
+        """
+        # 1. Get expected key from environment (at request time)
+        expected_api_key = os.getenv(self.api_key_env_var)
+
+        # 2. Check if the key is configured in the environment
+        if not expected_api_key:
+            logger.error(
+                f"API key not configured. Set '{self.api_key_env_var}' environment variable."
+            )
+            # This is a server-side configuration error
+            return error_response(
+                "This endpoint is not configured for API key access.",
+                "CONFIGURATION_ERROR",
+                500,
+            )
+
+        # 3. Get provided key from request headers
+        provided_api_key = LambdaEventUtility.get_value_from_header(
+            event, self.api_key_header
+        )
+
+        # 4. Check if a key was provided
+        if not provided_api_key:
+            logger.warning(f"No API key provided in '{self.api_key_header}' header.")
+            return error_response("API key is required.", "UNAUTHORIZED", 401)
+
+        # 5. Validate the key
+        if provided_api_key != expected_api_key:
+            logger.warning("Invalid API key provided.")
+            return error_response("Invalid API key.", "UNAUTHORIZED", 401)
+
+        # 6. Validation passed
+        logger.info("API key validation successful.")
+        return None
+
+    def execute(
+        self,
+        event: Dict[str, Any],
+        context: Any,
+        business_logic: Callable[[Dict[str, Any], Any, Dict[str, Any]], Any],
+        injected_service: Optional[T] = None
+    ) -> Dict[str, Any]:
+        """
+        Execute the Lambda handler with API key validation.
+        
+        Args:
+            event: Lambda event dictionary
+            context: Lambda context object
+            business_logic: Callable that implements the business logic
+            injected_service: Optional service instance for testing
+            
+        Returns:
+            Lambda response dictionary
+        """
+        # Validate API key first
+        validation_error = self._validate_security(event)
+        if validation_error:
+            return validation_error
+        
+        # If validation passed, execute parent's execute method
+        return super().execute(event, context, business_logic, injected_service)