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

geek_cafe_saas_sdk/__init__.py

@@ -1,9 +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 adds File System Service
 """
-__version__ = "0.6.0"
+__version__ = "0.7.1"
 
 # Import main modules for easier access
 from . import services

geek_cafe_saas_sdk/domains/files/handlers/README.md

@@ -0,0 +1,446 @@
+# File System Lambda Handlers
+
+Lambda handlers for the file system with lineage tracking support.
+
+---
+
+## Handler Structure
+
+```
+handlers/
+├── files/              # Basic file operations
+│   ├── create/         # Upload file
+│   ├── get/            # Get file metadata
+│   ├── download/       # Download file content
+│   └── list/           # List files
+│
+└── lineage/            # Lineage operations
+    ├── get_lineage/    # Get file lineage
+    ├── create_main/    # Create main file from original
+    ├── create_derived/ # Create derived file from main
+    ├── prepare_bundle/ # Prepare lineage bundle (metadata only)
+    └── download_bundle/# Download complete bundle (with content)
+```
+
+---
+
+## File Operations
+
+### POST /files - Upload File
+
+**Handler:** `files/create/app.py`
+
+**Body:**
+```json
+{
+  "fileName": "document.pdf",
+  "fileData": "base64_encoded_content",
+  "mimeType": "application/pdf",
+  "directoryId": "dir-123",
+  "versioningStrategy": "explicit",
+  "description": "Q1 Report",
+  "tags": ["report", "2024"],
+  
+  // Optional lineage fields:
+  "fileRole": "original",
+  "parentFileId": "file-parent",
+  "originalFileId": "file-original",
+  "transformationType": "convert",
+  "transformationOperation": "xls_to_csv",
+  "transformationMetadata": {
+    "source_format": "xls",
+    "target_format": "csv"
+  }
+}
+```
+
+**Response:** `201` with file metadata
+
+---
+
+### GET /files/{fileId} - Get File Metadata
+
+**Handler:** `files/get/app.py`
+
+**Path Parameters:**
+- `fileId` - File ID
+
+**Response:** `200` with file metadata including lineage fields
+
+---
+
+### GET /files/{fileId}/download - Download File
+
+**Handler:** `files/download/app.py`
+
+**Path Parameters:**
+- `fileId` - File ID
+
+**Response:** `200` with:
+```json
+{
+  "file_id": "file-123",
+  "file_name": "document.pdf",
+  "mime_type": "application/pdf",
+  "file_size": 12345,
+  "file_data": "base64_encoded_content",
+  "content_type": "application/pdf"
+}
+```
+
+---
+
+### GET /files - List Files
+
+**Handler:** `files/list/app.py`
+
+**Query Parameters:**
+- `directoryId` (optional) - Filter by directory
+- `ownerId` (optional) - Filter by owner (defaults to current user)
+- `limit` (optional) - Max results (default: 100)
+
+**Response:** `200` with array of file objects
+
+---
+
+## Lineage Operations
+
+### GET /files/{fileId}/lineage - Get File Lineage
+
+**Handler:** `lineage/get_lineage/app.py`
+
+**Path Parameters:**
+- `fileId` - File ID
+
+**Response:** `200` with:
+```json
+{
+  "selected": {file object},
+  "main": {file object or null},
+  "original": {file object or null},
+  "allDerived": [{file objects}]
+}
+```
+
+---
+
+### POST /files/lineage/main - Create Main File
+
+**Handler:** `lineage/create_main/app.py`
+
+Convert an original file to a main file (e.g., XLS → CSV).
+
+**Body:**
+```json
+{
+  "originalFileId": "file-123",
+  "fileName": "data.csv",
+  "fileData": "base64_encoded_content",
+  "mimeType": "text/csv",
+  "transformationOperation": "xls_to_csv",
+  "transformationMetadata": {
+    "source_format": "xls",
+    "target_format": "csv",
+    "converter_version": "1.0"
+  },
+  "directoryId": "dir-456"
+}
+```
+
+**Response:** `201` with main file metadata
+
+---
+
+### POST /files/lineage/derived - Create Derived File
+
+**Handler:** `lineage/create_derived/app.py`
+
+Create a derived file from a main file (e.g., data cleaning).
+
+**Body:**
+```json
+{
+  "mainFileId": "file-456",
+  "fileName": "data_clean_v1.csv",
+  "fileData": "base64_encoded_content",
+  "transformationOperation": "data_cleaning_v1",
+  "transformationMetadata": {
+    "cleaning_version": 1,
+    "operations": ["remove_nulls", "normalize_units"],
+    "rows_processed": 1000
+  },
+  "directoryId": "dir-789"
+}
+```
+
+**Response:** `201` with derived file metadata
+
+---
+
+### GET /files/{fileId}/bundle - Prepare Lineage Bundle
+
+**Handler:** `lineage/prepare_bundle/app.py`
+
+Get bundle metadata without file content (lightweight).
+
+**Path Parameters:**
+- `fileId` - File ID
+
+**Response:** `200` with:
+```json
+{
+  "selectedFile": {file object},
+  "mainFile": {file object},
+  "originalFile": {file object},
+  "metadata": {
+    "selectedFileId": "...",
+    "selectedFileName": "...",
+    "transformationChain": [
+      {"step": 1, "type": "original", "fileId": "...", "fileName": "..."},
+      {"step": 2, "type": "convert", "fileId": "...", "fileName": "...", "operation": "..."},
+      {"step": 3, "type": "clean", "fileId": "...", "fileName": "...", "operation": "..."}
+    ]
+  }
+}
+```
+
+---
+
+### GET /files/{fileId}/bundle/download - Download Lineage Bundle
+
+**Handler:** `lineage/download_bundle/app.py`
+
+Download complete bundle with file content (heavier).
+
+**Path Parameters:**
+- `fileId` - File ID
+
+**Response:** `200` with:
+```json
+{
+  "selected": {
+    "file": {file object},
+    "data": "base64_encoded_content"
+  },
+  "main": {
+    "file": {file object},
+    "data": "base64_encoded_content"
+  },
+  "original": {
+    "file": {file object},
+    "data": "base64_encoded_content"
+  },
+  "metadata": {transformation chain}
+}
+```
+
+---
+
+## API Gateway Configuration
+
+### Example SAM Template
+
+```yaml
+Resources:
+  # File Operations
+  FileUpload:
+    Type: AWS::Serverless::Function
+    Properties:
+      CodeUri: handlers/files/create/
+      Handler: app.handler
+      Events:
+        ApiEvent:
+          Type: Api
+          Properties:
+            Path: /files
+            Method: POST
+            Auth:
+              Authorizer: CognitoAuthorizer
+
+  FileGet:
+    Type: AWS::Serverless::Function
+    Properties:
+      CodeUri: handlers/files/get/
+      Handler: app.handler
+      Events:
+        ApiEvent:
+          Type: Api
+          Properties:
+            Path: /files/{fileId}
+            Method: GET
+            Auth:
+              Authorizer: CognitoAuthorizer
+
+  FileDownload:
+    Type: AWS::Serverless::Function
+    Properties:
+      CodeUri: handlers/files/download/
+      Handler: app.handler
+      Events:
+        ApiEvent:
+          Type: Api
+          Properties:
+            Path: /files/{fileId}/download
+            Method: GET
+            Auth:
+              Authorizer: CognitoAuthorizer
+
+  FileList:
+    Type: AWS::Serverless::Function
+    Properties:
+      CodeUri: handlers/files/list/
+      Handler: app.handler
+      Events:
+        ApiEvent:
+          Type: Api
+          Properties:
+            Path: /files
+            Method: GET
+            Auth:
+              Authorizer: CognitoAuthorizer
+
+  # Lineage Operations
+  GetLineage:
+    Type: AWS::Serverless::Function
+    Properties:
+      CodeUri: handlers/lineage/get_lineage/
+      Handler: app.handler
+      Events:
+        ApiEvent:
+          Type: Api
+          Properties:
+            Path: /files/{fileId}/lineage
+            Method: GET
+            Auth:
+              Authorizer: CognitoAuthorizer
+
+  CreateMain:
+    Type: AWS::Serverless::Function
+    Properties:
+      CodeUri: handlers/lineage/create_main/
+      Handler: app.handler
+      Events:
+        ApiEvent:
+          Type: Api
+          Properties:
+            Path: /files/lineage/main
+            Method: POST
+            Auth:
+              Authorizer: CognitoAuthorizer
+
+  CreateDerived:
+    Type: AWS::Serverless::Function
+    Properties:
+      CodeUri: handlers/lineage/create_derived/
+      Handler: app.handler
+      Events:
+        ApiEvent:
+          Type: Api
+          Properties:
+            Path: /files/lineage/derived
+            Method: POST
+            Auth:
+              Authorizer: CognitoAuthorizer
+
+  PrepareBundle:
+    Type: AWS::Serverless::Function
+    Properties:
+      CodeUri: handlers/lineage/prepare_bundle/
+      Handler: app.handler
+      Events:
+        ApiEvent:
+          Type: Api
+          Properties:
+            Path: /files/{fileId}/bundle
+            Method: GET
+            Auth:
+              Authorizer: CognitoAuthorizer
+
+  DownloadBundle:
+    Type: AWS::Serverless::Function
+    Properties:
+      CodeUri: handlers/lineage/download_bundle/
+      Handler: app.handler
+      Events:
+        ApiEvent:
+          Type: Api
+          Properties:
+            Path: /files/{fileId}/bundle/download
+            Method: GET
+            Auth:
+              Authorizer: CognitoAuthorizer
+```
+
+---
+
+## Authentication
+
+All handlers require secure authentication (Cognito JWT tokens).
+
+**Required User Context:**
+- `user_id` - User performing the action
+- `tenant_id` - Organization/tenant ID
+- `email` - User email (optional)
+
+---
+
+## Error Responses
+
+All handlers return standard error responses:
+
+```json
+{
+  "error": {
+    "code": "VALIDATION_ERROR",
+    "message": "file_name is required",
+    "details": {"field": "file_name"}
+  }
+}
+```
+
+**Common Error Codes:**
+- `VALIDATION_ERROR` - Invalid input
+- `NOT_FOUND` - File not found
+- `ACCESS_DENIED` - Insufficient permissions
+- `INVALID_FILE_ROLE` - Lineage role mismatch
+
+---
+
+## Testing
+
+Each handler can be tested independently:
+
+```python
+from handlers.files.create import app
+
+# Mock event
+event = {
+    "body": json.dumps({
+        "fileName": "test.txt",
+        "fileData": base64.b64encode(b"test").decode(),
+        "mimeType": "text/plain"
+    }),
+    "requestContext": {
+        "authorizer": {
+            "claims": {
+                "sub": "user-123",
+                "custom:tenant_id": "tenant-456"
+            }
+        }
+    }
+}
+
+# Test
+result = app.handler(event, None)
+print(result)
+```
+
+---
+
+## Next Steps
+
+1. Deploy handlers using SAM/CloudFormation
+2. Configure API Gateway routes
+3. Set up Cognito authorizer
+4. Test each endpoint
+5. Monitor CloudWatch logs

geek_cafe_saas_sdk/domains/files/handlers/__init__.py

@@ -0,0 +1,6 @@
+"""
+File handlers.
+
+Geek Cafe, LLC
+MIT License. See Project Root for the license information.
+"""

geek_cafe_saas_sdk/domains/files/handlers/files/create/app.py

@@ -0,0 +1,121 @@
+"""
+Lambda handler for creating/uploading files.
+
+Requires authentication (secure mode).
+"""
+
+from typing import Dict, Any
+from geek_cafe_saas_sdk.lambda_handlers import create_handler
+from geek_cafe_saas_sdk.domains.files.services import FileSystemService
+import base64
+
+
+# Factory creates handler (defaults to secure auth)
+handler_wrapper = create_handler(
+    service_class=FileSystemService,
+    require_body=True,
+    convert_case=True
+)
+
+
+def handler(event: Dict[str, Any], context: Any, injected_service=None) -> Dict[str, Any]:
+    """
+    Upload a new file.
+    
+    Args:
+        event: Lambda event from API Gateway
+        context: Lambda context
+        injected_service: Optional FileSystemService for testing
+    
+    Expected body (camelCase from frontend):
+    {
+        "fileName": "document.pdf",
+        "fileData": "base64_encoded_content",
+        "mimeType": "application/pdf",
+        "directoryId": "dir-123",  # Optional
+        "versioningStrategy": "explicit",  # Optional: "s3_native" or "explicit"
+        "description": "Q1 Report",  # Optional
+        "tags": ["report", "2024"],  # Optional
+        
+        # Optional lineage fields:
+        "fileRole": "original",  # "standalone", "original", "main", "derived"
+        "parentFileId": "file-parent",  # For lineage tracking
+        "originalFileId": "file-original",  # For lineage tracking
+        "transformationType": "convert",  # "convert", "clean", "process"
+        "transformationOperation": "xls_to_csv",  # Operation name
+        "transformationMetadata": {  # Operation details
+            "source_format": "xls",
+            "target_format": "csv"
+        }
+    }
+    
+    Returns 201 with created file metadata
+    """
+    return handler_wrapper.execute(event, context, upload_file, injected_service)
+
+
+def upload_file(
+    event: Dict[str, Any],
+    service: FileSystemService,
+    user_context: Dict[str, str]
+) -> Any:
+    """
+    Business logic for uploading files.
+    """
+    payload = event["parsed_body"]
+    
+    tenant_id = user_context.get("tenant_id")
+    user_id = user_context.get("user_id")
+    
+    # Extract required fields
+    file_name = payload.get("file_name")
+    file_data_b64 = payload.get("file_data")
+    mime_type = payload.get("mime_type")
+    
+    if not file_name:
+        raise ValueError("file_name is required")
+    if not file_data_b64:
+        raise ValueError("file_data is required")
+    if not mime_type:
+        raise ValueError("mime_type is required")
+    
+    # Decode base64 file data
+    try:
+        file_data = base64.b64decode(file_data_b64)
+    except Exception as e:
+        raise ValueError(f"Invalid base64 file_data: {str(e)}")
+    
+    # Extract optional fields
+    directory_id = payload.get("directory_id")
+    versioning_strategy = payload.get("versioning_strategy", "explicit")
+    description = payload.get("description")
+    tags = payload.get("tags", [])
+    
+    # Extract lineage fields
+    file_role = payload.get("file_role")
+    parent_file_id = payload.get("parent_file_id")
+    original_file_id = payload.get("original_file_id")
+    transformation_type = payload.get("transformation_type")
+    transformation_operation = payload.get("transformation_operation")
+    transformation_metadata = payload.get("transformation_metadata")
+    
+    # Upload file
+    result = service.create(
+        tenant_id=tenant_id,
+        user_id=user_id,
+        file_name=file_name,
+        file_data=file_data,
+        mime_type=mime_type,
+        directory_id=directory_id,
+        versioning_strategy=versioning_strategy,
+        description=description,
+        tags=tags,
+        file_role=file_role,
+        parent_file_id=parent_file_id,
+        original_file_id=original_file_id,
+        transformation_type=transformation_type,
+        transformation_operation=transformation_operation,
+        transformation_metadata=transformation_metadata
+    )
+    
+    return result

geek_cafe_saas_sdk/domains/files/handlers/files/download/app.py

@@ -0,0 +1,80 @@
+"""
+Lambda handler for downloading file content.
+
+Requires authentication (secure mode).
+"""
+
+from typing import Dict, Any
+from geek_cafe_saas_sdk.lambda_handlers import create_handler
+from geek_cafe_saas_sdk.domains.files.services import FileSystemService
+import base64
+
+
+# Factory creates handler (defaults to secure auth)
+handler_wrapper = create_handler(
+    service_class=FileSystemService,
+    require_body=False,
+    convert_case=True
+)
+
+
+def handler(event: Dict[str, Any], context: Any, injected_service=None) -> Dict[str, Any]:
+    """
+    Download file content.
+    
+    Args:
+        event: Lambda event from API Gateway
+        context: Lambda context
+        injected_service: Optional FileSystemService for testing
+    
+    Path parameters:
+        fileId: File ID
+    
+    Returns 200 with file content (base64 encoded for binary files)
+    """
+    return handler_wrapper.execute(event, context, download_file, injected_service)
+
+
+def download_file(
+    event: Dict[str, Any],
+    service: FileSystemService,
+    user_context: Dict[str, str]
+) -> Dict[str, Any]:
+    """
+    Business logic for downloading file content.
+    """
+    tenant_id = user_context.get("tenant_id")
+    user_id = user_context.get("user_id")
+    
+    # Get file ID from path parameters
+    path_params = event.get("pathParameters", {})
+    file_id = path_params.get("fileId") or path_params.get("id")
+    
+    if not file_id:
+        raise ValueError("fileId path parameter is required")
+    
+    # Download file
+    result = service.download_file(
+        tenant_id=tenant_id,
+        file_id=file_id,
+        user_id=user_id
+    )
+    
+    if result.success:
+        file_data = result.data['data']
+        file_info = result.data['file']
+        
+        # Encode binary data as base64 for JSON response
+        encoded_data = base64.b64encode(file_data).decode('utf-8')
+        
+        # Return with metadata
+        return {
+            'file_id': file_info.file_id,
+            'file_name': file_info.file_name,
+            'mime_type': file_info.mime_type,
+            'file_size': file_info.file_size,
+            'file_data': encoded_data,
+            'content_type': file_info.mime_type
+        }
+    
+    return result