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

geek_cafe_saas_sdk/domains/files/models/file.py

@@ -19,12 +19,16 @@ class File(BaseModel):
     Represents a file in the system with metadata, virtual path, and S3 location.
     Does not contain file data (stored in S3) - only metadata and references.
     
+    Multi-Tenancy:
+    - tenant_id: Organization/company (can have multiple users)
+    - owner_id: Specific user within the tenant who owns this file
+    
     Access Patterns (DynamoDB Keys):
     - pk: FILE#{tenant_id}#{file_id}
-    - sk: METADATA
-    - gsi1_pk: TENANT#{tenant_id}
-    - gsi1_sk: DIRECTORY#{directory_id}#{file_name}
-    - gsi2_pk: TENANT#{tenant_id}#USER#{owner_id}
+    - sk: metadata
+    - gsi1_pk: tenant#{tenant_id}
+    - gsi1_sk: directory#{directory_id}#{file_name}
+    - gsi2_pk: tenant#{tenant_id}#USER#{owner_id}
     - gsi2_sk: FILE#{created_utc_ts}
     
     Versioning Strategies:
@@ -35,11 +39,9 @@ class File(BaseModel):
     def __init__(self):
         super().__init__()
         
-        # File Identity
-        self._file_id: str | None = None  # Unique file ID (same as self.id)
-        
-        # Ownership (inherited tenant_id from BaseModel)
-        self._owner_id: str | None = None  # User who owns the file
+        # Identity (inherited from BaseModel: id, tenant_id)
+        # Note: tenant_id = organization/company, owner_id = specific user within tenant
+        self._owner_id: str | None = None  # User ID who owns this file
         
         # File Information
         self._file_name: str | None = None  # Display name (e.g., "report.pdf")
@@ -70,25 +72,72 @@ class File(BaseModel):
         self._status: str = "active"  # "active", "archived", "deleted"
         self._is_shared: bool = False  # Has active shares
         
+        # Lineage Tracking (for data processing pipelines)
+        self._file_role: str = "standalone"  # "standalone", "original", "main", "derived"
+        self._original_file_id: str | None = None  # Root file in lineage chain
+        self._parent_file_id: str | None = None  # Immediate parent file
+        
+        # Transformation Tracking
+        self._transformation_type: str | None = None  # "convert", "clean", "process"
+        self._transformation_operation: str | None = None  # "xls_to_csv", "data_cleaning_v2"
+        self._transformation_metadata: Dict[str, Any] | None = None  # Additional operation details
+        
+        # Relationship Counts
+        self._derived_file_count: int = 0  # Number of files derived from this one
+        
         # Timestamps (inherited from BaseModel)
         # created_utc_ts, updated_utc_ts, deleted_utc_ts
+        
+        # CRITICAL: Call _setup_indexes() as LAST line in __init__
+        self._setup_indexes()
     
-    # Properties - File Identity
+    def _setup_indexes(self):
+        """Setup DynamoDB indexes for file queries."""
+        
+        # Primary index: File by ID
+        primary = DynamoDBIndex()
+        primary.name = "primary"
+        primary.partition_key.attribute_name = "pk"
+        primary.partition_key.value = lambda: DynamoDBKey.build_key(("file", self.id))
+        primary.sort_key.attribute_name = "sk"
+        primary.sort_key.value = lambda: "metadata"
+        self.indexes.add_primary(primary)
+        
+        # GSI1: Files by directory
+        gsi = DynamoDBIndex()
+        gsi.name = "gsi1"
+        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"
+        if self.directory_id:
+            gsi.sort_key.value = lambda: DynamoDBKey.build_key(("directory", self.directory_id), ("file", self.file_name))
+        else:
+            gsi.sort_key.value = lambda: DynamoDBKey.build_key(("root", "file"), ("name", self.file_name))
+        self.indexes.add_secondary(gsi)
+        
+        # GSI2: Files by owner
+        gsi = DynamoDBIndex()
+        gsi.name = "gsi2"
+        gsi.partition_key.attribute_name = f"{gsi.name}_pk"
+        gsi.partition_key.value = lambda: DynamoDBKey.build_key(("tenant", self.tenant_id), ("user", self.owner_id))
+        gsi.sort_key.attribute_name = f"{gsi.name}_sk"
+        gsi.sort_key.value = lambda: DynamoDBKey.build_key(("file", self.created_utc_ts))
+        self.indexes.add_secondary(gsi)
+    
+    # Properties - File Identity (alias for BaseModel.id)
     @property
     def file_id(self) -> str | None:
-        """Unique file ID."""
-        return self._file_id or self.id
+        """Unique file ID (alias for id)."""
+        return self.id
     
     @file_id.setter
     def file_id(self, value: str | None):
-        self._file_id = value
-        if value:
-            self.id = value
+        self.id = value
     
     # Properties - Ownership
     @property
     def owner_id(self) -> str | None:
-        """User who owns the file."""
+        """User ID who owns the file (not tenant_id - that's the organization)."""
         return self._owner_id
     
     @owner_id.setter
@@ -258,6 +307,74 @@ class File(BaseModel):
     def is_shared(self, value: bool):
         self._is_shared = bool(value)
     
+    # Properties - Lineage Tracking
+    @property
+    def file_role(self) -> str:
+        """File role in lineage chain: 'standalone', 'original', 'main', 'derived'."""
+        return self._file_role
+    
+    @file_role.setter
+    def file_role(self, value: str | None):
+        valid_roles = ["standalone", "original", "main", "derived"]
+        if value in valid_roles:
+            self._file_role = value
+        else:
+            self._file_role = "standalone"
+    
+    @property
+    def original_file_id(self) -> str | None:
+        """Root file in lineage chain."""
+        return self._original_file_id
+    
+    @original_file_id.setter
+    def original_file_id(self, value: str | None):
+        self._original_file_id = value
+    
+    @property
+    def parent_file_id(self) -> str | None:
+        """Immediate parent file."""
+        return self._parent_file_id
+    
+    @parent_file_id.setter
+    def parent_file_id(self, value: str | None):
+        self._parent_file_id = value
+    
+    @property
+    def transformation_type(self) -> str | None:
+        """Type of transformation applied: 'convert', 'clean', 'process'."""
+        return self._transformation_type
+    
+    @transformation_type.setter
+    def transformation_type(self, value: str | None):
+        self._transformation_type = value
+    
+    @property
+    def transformation_operation(self) -> str | None:
+        """Specific operation performed (e.g., 'xls_to_csv', 'data_cleaning_v2')."""
+        return self._transformation_operation
+    
+    @transformation_operation.setter
+    def transformation_operation(self, value: str | None):
+        self._transformation_operation = value
+    
+    @property
+    def transformation_metadata(self) -> Dict[str, Any] | None:
+        """Additional transformation details."""
+        return self._transformation_metadata
+    
+    @transformation_metadata.setter
+    def transformation_metadata(self, value: Dict[str, Any] | None):
+        self._transformation_metadata = value if isinstance(value, dict) else None
+    
+    @property
+    def derived_file_count(self) -> int:
+        """Number of files derived from this one."""
+        return self._derived_file_count
+    
+    @derived_file_count.setter
+    def derived_file_count(self, value: int | None):
+        self._derived_file_count = value if isinstance(value, int) else 0
+    
     # Helper Methods
     def is_active(self) -> bool:
         """Check if file is active."""
@@ -310,3 +427,28 @@ class File(BaseModel):
         if self._s3_bucket and self._s3_key:
             return f"s3://{self._s3_bucket}/{self._s3_key}"
         return None
+    
+    # Lineage Helper Methods
+    def has_lineage(self) -> bool:
+        """Check if file participates in lineage tracking."""
+        return self._file_role != "standalone"
+    
+    def is_original(self) -> bool:
+        """Check if this is an original file."""
+        return self._file_role == "original"
+    
+    def is_main(self) -> bool:
+        """Check if this is a main file."""
+        return self._file_role == "main"
+    
+    def is_derived(self) -> bool:
+        """Check if this is a derived file."""
+        return self._file_role == "derived"
+    
+    def is_standalone(self) -> bool:
+        """Check if this is a standalone file (no lineage)."""
+        return self._file_role == "standalone"
+    
+    def increment_derived_count(self):
+        """Increment the derived file count."""
+        self._derived_file_count += 1

geek_cafe_saas_sdk/domains/files/models/file_share.py

@@ -63,6 +63,39 @@ class FileShare(BaseModel):
         
         # Timestamps (inherited from BaseModel)
         # created_utc_ts
+        
+        # CRITICAL: Call _setup_indexes() as LAST line in __init__
+        self._setup_indexes()
+    
+    def _setup_indexes(self):
+        """Setup DynamoDB indexes for file share queries."""
+        
+        # Primary index: Share by ID
+        primary = DynamoDBIndex()
+        primary.name = "primary"
+        primary.partition_key.attribute_name = "pk"
+        primary.partition_key.value = lambda: DynamoDBKey.build_key(("share", self.id))
+        primary.sort_key.attribute_name = "sk"
+        primary.sort_key.value = lambda: DynamoDBKey.build_key(("share", self.id))
+        self.indexes.add_primary(primary)
+        
+        # GSI1: Shares by file
+        gsi = DynamoDBIndex()
+        gsi.name = "gsi1"
+        gsi.partition_key.attribute_name = f"{gsi.name}_pk"
+        gsi.partition_key.value = lambda: DynamoDBKey.build_key(("file", self.file_id))
+        gsi.sort_key.attribute_name = f"{gsi.name}_sk"
+        gsi.sort_key.value = lambda: DynamoDBKey.build_key(("created", self.created_utc_ts))
+        self.indexes.add_secondary(gsi)
+        
+        # GSI2: Shares by shared_with_user
+        gsi = DynamoDBIndex()
+        gsi.name = "gsi2"
+        gsi.partition_key.attribute_name = f"{gsi.name}_pk"
+        gsi.partition_key.value = lambda: DynamoDBKey.build_key(("shared_with", self.shared_with_user_id))
+        gsi.sort_key.attribute_name = f"{gsi.name}_sk"
+        gsi.sort_key.value = lambda: DynamoDBKey.build_key(("created", self.created_utc_ts))
+        self.indexes.add_secondary(gsi)
     
     # Properties - Identity
     @property

geek_cafe_saas_sdk/domains/files/models/file_version.py

@@ -54,6 +54,30 @@ class FileVersion(BaseModel):
         
         # Timestamps (inherited from BaseModel)
         # created_utc_ts - when this version was created
+        
+        # CRITICAL: Call _setup_indexes() as LAST line in __init__
+        self._setup_indexes()
+    
+    def _setup_indexes(self):
+        """Setup DynamoDB indexes for file version queries."""
+        
+        # Primary index: Version by ID
+        primary = DynamoDBIndex()
+        primary.name = "primary"
+        primary.partition_key.attribute_name = "pk"
+        primary.partition_key.value = lambda: DynamoDBKey.build_key(("file_version", self.id))
+        primary.sort_key.attribute_name = "sk"
+        primary.sort_key.value = lambda: DynamoDBKey.build_key(("version", self.id))
+        self.indexes.add_primary(primary)
+        
+        # GSI1: Versions by file (ordered by version number)
+        gsi = DynamoDBIndex()
+        gsi.name = "gsi1"
+        gsi.partition_key.attribute_name = f"{gsi.name}_pk"
+        gsi.partition_key.value = lambda: DynamoDBKey.build_key(("file", self.file_id))
+        gsi.sort_key.attribute_name = f"{gsi.name}_sk"
+        gsi.sort_key.value = lambda: DynamoDBKey.build_key(("version", self.version_number))
+        self.indexes.add_secondary(gsi)
     
     # Properties - Identity
     @property

geek_cafe_saas_sdk/domains/files/services/__init__.py

@@ -0,0 +1,21 @@
+"""File services.
+
+Geek Cafe, LLC
+MIT License. See Project Root for the license information.
+"""
+
+from .file_system_service import FileSystemService
+from .directory_service import DirectoryService
+from .file_version_service import FileVersionService
+from .file_share_service import FileShareService
+from .s3_file_service import S3FileService
+from .file_lineage_service import FileLineageService
+
+__all__ = [
+    "FileSystemService",
+    "DirectoryService",
+    "FileVersionService",
+    "FileShareService",
+    "S3FileService",
+    "FileLineageService",
+]

geek_cafe_saas_sdk/domains/files/services/directory_service.py

@@ -113,28 +113,11 @@ class DirectoryService(DatabaseService[Directory]):
             directory.total_size = 0
             
             # Save to DynamoDB
-            pk = f"DIR#{tenant_id}#{directory.directory_id}"
-            sk = "METADATA"
-            
-            item = directory.to_dictionary()
-            item["pk"] = pk
-            item["sk"] = sk
-            
-            # GSI1: Directories by parent
-            item["gsi1_pk"] = f"TENANT#{tenant_id}"
-            if parent_id:
-                item["gsi1_sk"] = f"PARENT#{parent_id}#{directory_name}"
-            else:
-                item["gsi1_sk"] = f"PARENT#ROOT#{directory_name}"
+            directory.prep_for_save()
+            save_result = self._save_model(directory)
             
-            # GSI2: Directories by owner
-            item["gsi2_pk"] = f"TENANT#{tenant_id}#USER#{user_id}"
-            item["gsi2_sk"] = f"DIR#{directory.created_utc_ts}"
-            
-            self.dynamodb.save(
-                item=item,
-                table_name=self.table_name
-            )
+            if not save_result.success:
+                return save_result
             
             # Update parent's subdirectory count
             if parent_id:
@@ -172,22 +155,13 @@ class DirectoryService(DatabaseService[Directory]):
             ServiceResult with Directory model
         """
         try:
-            pk = f"DIR#{tenant_id}#{resource_id}"
-            sk = "METADATA"
-            
-            result = self.dynamodb.get(
-                table_name=self.table_name,
-                key={"pk": pk, "sk": sk}
-            )
+            # Use helper method with tenant check
+            directory = self._get_model_by_id_with_tenant_check(resource_id, Directory, tenant_id)
             
             # Check if directory exists
-            if not result or 'Item' not in result:
+            if not directory:
                 raise NotFoundError(f"Directory not found: {resource_id}")
             
-            # Convert to Directory model
-            directory = Directory()
-            directory.map(result['Item'])
-            
             # Access control: Check if user is owner
             if directory.owner_id != user_id:
                 # TODO: Check shared access
@@ -292,27 +266,8 @@ class DirectoryService(DatabaseService[Directory]):
             directory.updated_utc_ts = dt.datetime.now(dt.UTC).timestamp()
             
             # Save to DynamoDB
-            pk = f"DIR#{tenant_id}#{resource_id}"
-            sk = "METADATA"
-            
-            item = directory.to_dictionary()
-            item["pk"] = pk
-            item["sk"] = sk
-            
-            # Update GSI keys if name changed
-            if "directory_name" in updates:
-                item["gsi1_pk"] = f"TENANT#{tenant_id}"
-                if directory.parent_id:
-                    item["gsi1_sk"] = f"PARENT#{directory.parent_id}#{directory.directory_name}"
-                else:
-                    item["gsi1_sk"] = f"PARENT#ROOT#{directory.directory_name}"
-            
-            self.dynamodb.save(
-                item=item,
-                table_name=self.table_name
-            )
-            
-            return ServiceResult.success_result(directory)
+            directory.prep_for_save()
+            return self._save_model(directory)
             
         except (ValidationError, AccessDeniedError) as e:
             return ServiceResult.error_result(
@@ -369,17 +324,11 @@ class DirectoryService(DatabaseService[Directory]):
             directory.status = "deleted"
             directory.deleted_utc_ts = dt.datetime.now(dt.UTC).timestamp()
             
-            pk = f"DIR#{tenant_id}#{resource_id}"
-            sk = "METADATA"
+            directory.prep_for_save()
+            save_result = self._save_model(directory)
             
-            item = directory.to_dictionary()
-            item["pk"] = pk
-            item["sk"] = sk
-            
-            self.dynamodb.save(
-                item=item,
-                table_name=self.table_name
-            )
+            if not save_result.success:
+                return save_result
             
             # Update parent's subdirectory count
             if directory.parent_id:
@@ -419,30 +368,26 @@ class DirectoryService(DatabaseService[Directory]):
             ServiceResult with list of Directory models
         """
         try:
-            gsi1_pk = f"TENANT#{tenant_id}"
+            # Use GSI2 to query subdirectories by parent
+            temp_directory = Directory()
+            temp_directory.tenant_id = tenant_id
+            temp_directory.parent_id = parent_id  # None for root directories
             
-            if parent_id:
-                gsi1_sk_prefix = f"PARENT#{parent_id}#"
-            else:
-                gsi1_sk_prefix = "PARENT#ROOT#"
-            
-            # Query GSI1
-            results = self.dynamodb.query(
-                key=Key('gsi1_pk').eq(gsi1_pk) & Key('gsi1_sk').begins_with(gsi1_sk_prefix),
-                table_name=self.table_name,
-                index_name="gsi1",
-                limit=limit
-            )
+            # Query using helper method
+            query_result = self._query_by_index(temp_directory, "gsi2", limit=limit, ascending=True)
+            
+            if not query_result.success:
+                return query_result
             
+            # Filter results
             directories = []
-            for item in results.get('Items', []):
-                directory = Directory()
-                directory.map(item)
-                
-                # Filter out deleted directories
-                if directory.status != "deleted":
-                    # Basic access control: show only owned directories
-                    if directory.owner_id == user_id:
+            for directory in query_result.data:
+                # Debug: print what we're seeing
+                # print(f"Found dir: {directory.directory_name}, parent_id={directory.parent_id}, expected={parent_id}")
+                # Filter out deleted directories and apply access control
+                if directory.status != "deleted" and directory.owner_id == user_id:
+                    # Only include directories whose parent_id matches what we're looking for
+                    if directory.parent_id == parent_id:
                         directories.append(directory)
             
             return ServiceResult.success_result(directories)
@@ -570,24 +515,11 @@ class DirectoryService(DatabaseService[Directory]):
             directory.updated_utc_ts = dt.datetime.now(dt.UTC).timestamp()
             
             # Save to DynamoDB
-            pk = f"DIR#{tenant_id}#{directory_id}"
-            sk = "METADATA"
-            
-            item = directory.to_dictionary()
-            item["pk"] = pk
-            item["sk"] = sk
-            
-            # Update GSI1 for new parent
-            item["gsi1_pk"] = f"TENANT#{tenant_id}"
-            if new_parent_id:
-                item["gsi1_sk"] = f"PARENT#{new_parent_id}#{directory.directory_name}"
-            else:
-                item["gsi1_sk"] = f"PARENT#ROOT#{directory.directory_name}"
+            directory.prep_for_save()
+            save_result = self._save_model(directory)
             
-            self.dynamodb.save(
-                item=item,
-                table_name=self.table_name
-            )
+            if not save_result.success:
+                return save_result
             
             # Update parent counts
             if old_parent_id:
@@ -619,21 +551,23 @@ class DirectoryService(DatabaseService[Directory]):
     ) -> bool:
         """Check if directory name already exists in parent."""
         try:
-            gsi1_pk = f"TENANT#{tenant_id}"
-            if parent_id:
-                gsi1_sk = f"PARENT#{parent_id}#{directory_name}"
-            else:
-                gsi1_sk = f"PARENT#ROOT#{directory_name}"
+            # Use GSI2 to query subdirectories by parent
+            temp_directory = Directory()
+            temp_directory.tenant_id = tenant_id
+            temp_directory.parent_id = parent_id
+            temp_directory.directory_name = directory_name
             
-            results = self.dynamodb.query(
-                key=Key('gsi1_pk').eq(gsi1_pk) & Key('gsi1_sk').eq(gsi1_sk),
-                table_name=self.table_name,
-                index_name="gsi1",
-                limit=1
-            )
+            query_result = self._query_by_index(temp_directory, "gsi2", limit=1)
+            
+            if not query_result.success:
+                return False
             
-            items = results.get('Items', [])
-            return len(items) > 0
+            # Check if any non-deleted directories with this name exist
+            for directory in query_result.data:
+                if directory.directory_name == directory_name and directory.status != "deleted":
+                    return True
+            
+            return False
             
         except Exception:
             return False
@@ -646,29 +580,14 @@ class DirectoryService(DatabaseService[Directory]):
     ) -> None:
         """Increment or decrement subdirectory count."""
         try:
-            pk = f"DIR#{tenant_id}#{directory_id}"
-            sk = "METADATA"
+            # Get current directory using helper
+            directory = self._get_model_by_id_with_tenant_check(directory_id, Directory, tenant_id)
             
-            # Get current directory
-            result = self.dynamodb.get(
-                table_name=self.table_name,
-                key={"pk": pk, "sk": sk}
-            )
-            
-            if result and 'Item' in result:
-                directory = Directory()
-                directory.map(result['Item'])
-                
+            if directory:
                 directory.subdirectory_count = max(0, directory.subdirectory_count + delta)
                 
-                item = directory.to_dictionary()
-                item["pk"] = pk
-                item["sk"] = sk
-                
-                self.dynamodb.save(
-                    item=item,
-                    table_name=self.table_name
-                )
+                directory.prep_for_save()
+                self._save_model(directory)
         except Exception:
             # Silent fail - this is a best-effort update
             pass