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

geek_cafe_saas_sdk/domains/communities/models/community_member.py

@@ -0,0 +1,227 @@
+"""
+Geek Cafe, LLC
+MIT License.  See Project Root for the license information.
+
+CommunityMember model for scalable community membership using single-table design.
+"""
+
+from boto3_assist.dynamodb.dynamodb_index import DynamoDBIndex, DynamoDBKey
+import datetime as dt
+from typing import Optional
+from geek_cafe_saas_sdk.models.base_model import BaseModel
+
+
+class CommunityMember(BaseModel):
+    """
+    CommunityMember model for scalable membership tracking.
+    
+    Single-table design pattern:
+    - PK: community#<community_id>
+    - SK: member#<user_id>
+    - GSI1PK: user#<user_id> (for "what communities am I in?")
+    - GSI1SK: community#<community_id>#<joined_at>
+    
+    Benefits:
+    - Unlimited members per community
+    - Fast membership checks (single GetItem)
+    - Member metadata (role, status, join date)
+    - Efficient pagination
+    - Concurrent updates without contention
+    """
+
+    def __init__(self):
+        super().__init__()
+        # Note: Uses normal UUID id, but pk/sk create adjacent record pattern
+        self._community_id: str | None = None
+        self._user_id: str | None = None
+        
+        # Member metadata
+        self._status: str = "active"  # active, pending, banned, left
+        self._joined_at: float | None = None
+        self._invited_by_id: str | None = None
+        
+        # Dues tracking
+        self._dues_status: str = "current"  # current, overdue, exempt, pending
+        self._last_payment_at: float | None = None
+        self._next_payment_due: float | None = None
+        
+        # Activity tracking
+        self._last_active_at: float | None = None
+        self._event_attendance_count: int = 0
+        
+        # Setup DynamoDB indexes (adjacent record pattern)
+        self._setup_indexes()
+    
+    def _setup_indexes(self):
+        """Setup DynamoDB indexes for member queries."""
+        
+        # Primary index: Adjacent record pattern - members grouped by community
+        # Query: pk="community#<id>" AND sk BEGINS_WITH "member#" to get all members
+        primary: DynamoDBIndex = DynamoDBIndex()
+        primary.name = "primary"
+        primary.partition_key.attribute_name = "pk"
+        primary.partition_key.value = lambda: DynamoDBKey.build_key(("community", self.community_id))
+        primary.sort_key.attribute_name = "sk"
+        primary.sort_key.value = lambda: DynamoDBKey.build_key(("member", self.user_id))
+        self.indexes.add_primary(primary)
+        
+        # GSI1: User's communities - query communities by user
+        gsi: DynamoDBIndex = DynamoDBIndex()
+        gsi.name = "gsi1"
+        gsi.partition_key.attribute_name = f"{gsi.name}_pk"
+        gsi.partition_key.value = lambda: DynamoDBKey.build_key(("user", self.user_id))
+        gsi.sort_key.attribute_name = f"{gsi.name}_sk"
+        gsi.sort_key.value = lambda: DynamoDBKey.build_key(("community", self.community_id), ("ts", self.joined_at))
+        self.indexes.add_secondary(gsi)
+        
+        # GSI2: Members by status - query members by status within community
+        gsi: DynamoDBIndex = DynamoDBIndex()
+        gsi.name = "gsi2"
+        gsi.partition_key.attribute_name = f"{gsi.name}_pk"
+        gsi.partition_key.value = lambda: DynamoDBKey.build_key(("community", self.community_id), ("status", self.status))
+        gsi.sort_key.attribute_name = f"{gsi.name}_sk"
+        gsi.sort_key.value = lambda: DynamoDBKey.build_key(("member", self.user_id))
+        self.indexes.add_secondary(gsi)
+        
+        # GSI3: Members by dues status - query members with overdue dues
+        gsi: DynamoDBIndex = DynamoDBIndex()
+        gsi.name = "gsi3"
+        gsi.partition_key.attribute_name = f"{gsi.name}_pk"
+        gsi.partition_key.value = lambda: DynamoDBKey.build_key(("community", self.community_id), ("dues", self.dues_status))
+        gsi.sort_key.attribute_name = f"{gsi.name}_sk"
+        gsi.sort_key.value = lambda: DynamoDBKey.build_key(("due_date", self.next_payment_due or 0))
+        self.indexes.add_secondary(gsi)
+
+    @property
+    def model_version(self) -> str:
+        return "1.0"
+
+    def prep_for_save(self):
+        """
+        Prepare member record for save.
+        
+        Note: CommunityMember uses adjacent record pattern where:
+        - Normal UUID id (generated by parent)
+        - pk = "community#<community_id>" (groups by community)
+        - sk = "member#<user_id>" (enables begins_with queries)
+        """
+        # Validate required fields for adjacent record pattern
+        if not self.community_id:
+            raise ValueError("community_id is required for CommunityMember")
+        if not self.user_id:
+            raise ValueError("user_id is required for CommunityMember")
+        
+        # Set joined_at if not already set
+        if not self.joined_at:
+            self.joined_at = dt.datetime.now(dt.UTC).timestamp()
+        
+        # Call parent to generate normal UUID id and set timestamps
+        super().prep_for_save()
+
+    # Properties
+    @property
+    def community_id(self) -> str:
+        return self._community_id
+
+    @community_id.setter
+    def community_id(self, value: str | None):
+        self._community_id = value
+
+    @property
+    def user_id(self) -> str:
+        return self._user_id
+
+    @user_id.setter
+    def user_id(self, value: str | None):
+        self._user_id = value
+
+    @property
+    def status(self) -> str:
+        return self._status
+
+    @status.setter
+    def status(self, value: str | None):
+        valid_statuses = ["active", "pending", "banned", "left"]
+        self._status = value if value in valid_statuses else "active"
+
+    @property
+    def joined_at(self) -> float:
+        return self._joined_at
+
+    @joined_at.setter
+    def joined_at(self, value: float | None):
+        self._joined_at = value
+
+    @property
+    def invited_by_id(self) -> str:
+        return self._invited_by_id
+
+    @invited_by_id.setter
+    def invited_by_id(self, value: str | None):
+        self._invited_by_id = value
+
+    @property
+    def dues_status(self) -> str:
+        return self._dues_status
+
+    @dues_status.setter
+    def dues_status(self, value: str | None):
+        valid_statuses = ["current", "overdue", "exempt", "pending"]
+        self._dues_status = value if value in valid_statuses else "current"
+
+    @property
+    def last_payment_at(self) -> float:
+        return self._last_payment_at
+
+    @last_payment_at.setter
+    def last_payment_at(self, value: float | None):
+        self._last_payment_at = value
+
+    @property
+    def next_payment_due(self) -> float:
+        return self._next_payment_due
+
+    @next_payment_due.setter
+    def next_payment_due(self, value: float | None):
+        self._next_payment_due = value
+
+    @property
+    def last_active_at(self) -> float:
+        return self._last_active_at
+
+    @last_active_at.setter
+    def last_active_at(self, value: float | None):
+        self._last_active_at = value
+
+    @property
+    def event_attendance_count(self) -> int:
+        return self._event_attendance_count
+
+    @event_attendance_count.setter
+    def event_attendance_count(self, value: int | None):
+        self._event_attendance_count = value if isinstance(value, int) and value >= 0 else 0
+
+    # Helper methods
+    def is_active(self) -> bool:
+        """Check if member is active."""
+        return self.status == "active"
+
+    def is_pending(self) -> bool:
+        """Check if membership is pending approval."""
+        return self.status == "pending"
+
+    def is_banned(self) -> bool:
+        """Check if member is banned."""
+        return self.status == "banned"
+
+    def has_left(self) -> bool:
+        """Check if member has left the community."""
+        return self.status == "left"
+
+    def is_dues_current(self) -> bool:
+        """Check if member's dues are current."""
+        return self.dues_status == "current" or self.dues_status == "exempt"
+
+    def is_dues_overdue(self) -> bool:
+        """Check if member's dues are overdue."""
+        return self.dues_status == "overdue"

geek_cafe_saas_sdk/domains/communities/services/__init__.py

@@ -0,0 +1,6 @@
+# Communities Domain Services
+
+from .community_service import CommunityService
+from .community_member_service import CommunityMemberService
+
+__all__ = ["CommunityService", "CommunityMemberService"]

geek_cafe_saas_sdk/domains/communities/services/community_member_service.py

@@ -0,0 +1,412 @@
+# Community Member Service
+
+from typing import Dict, Any, List, Optional
+from boto3_assist.dynamodb.dynamodb import DynamoDB
+from geek_cafe_saas_sdk.services.database_service import DatabaseService
+from geek_cafe_saas_sdk.core.service_result import ServiceResult
+from geek_cafe_saas_sdk.core.service_errors import ValidationError, NotFoundError, AccessDeniedError
+from geek_cafe_saas_sdk.domains.communities.models import CommunityMember
+import datetime as dt
+
+
+class CommunityMemberService(DatabaseService[CommunityMember]):
+    """
+    Service for CommunityMember operations.
+    
+    Manages scalable membership using adjacent record pattern.
+    """
+
+    def __init__(self, *, dynamodb: DynamoDB = None, table_name: str = None):
+        super().__init__(dynamodb=dynamodb, table_name=table_name)
+    
+    # Required abstract methods from DatabaseService
+    def create(self, tenant_id: str, user_id: str, **kwargs) -> ServiceResult[CommunityMember]:
+        """Create method - delegates to add_member()."""
+        if 'community_id' not in kwargs:
+            return ServiceResult.error_result("community_id is required", "VALIDATION_ERROR")
+        
+        return self.add_member(
+            community_id=kwargs['community_id'],
+            user_id=user_id,
+            invited_by_id=kwargs.get('invited_by_id'),
+            status=kwargs.get('status', 'active')
+        )
+    
+    def get_by_id(self, resource_id: str, tenant_id: str, user_id: str) -> ServiceResult[CommunityMember]:
+        """Get method - resource_id should be in format 'community_id:user_id'."""
+        try:
+            if ':' in resource_id:
+                community_id, member_user_id = resource_id.split(':', 1)
+                return self.get_membership(community_id, member_user_id)
+            return ServiceResult.error_result("Invalid resource_id format. Expected 'community_id:user_id'")
+        except Exception as e:
+            return self._handle_service_exception(e, 'get_by_id', resource_id=resource_id)
+    
+    def update(self, resource_id: str, tenant_id: str, user_id: str, updates: Dict[str, Any]) -> ServiceResult[CommunityMember]:
+        """Update method - updates member record."""
+        try:
+            if ':' in resource_id:
+                community_id, member_user_id = resource_id.split(':', 1)
+                membership = self.get_membership(community_id, member_user_id)
+                
+                if not membership.success or not membership.data:
+                    return ServiceResult.error_result("Membership not found")
+                
+                # Apply updates
+                member = membership.data
+                if 'status' in updates:
+                    member.status = updates['status']
+                if 'dues_status' in updates:
+                    member.dues_status = updates['dues_status']
+                if 'last_payment_at' in updates:
+                    member.last_payment_at = updates['last_payment_at']
+                if 'next_payment_due' in updates:
+                    member.next_payment_due = updates['next_payment_due']
+                
+                member.prep_for_save()
+                return self._save_model(member)
+                
+            return ServiceResult.error_result("Invalid resource_id format. Expected 'community_id:user_id'")
+        except Exception as e:
+            return self._handle_service_exception(e, 'update', resource_id=resource_id)
+    
+    def delete(self, resource_id: str, tenant_id: str, user_id: str) -> ServiceResult[bool]:
+        """Delete method - soft deletes member."""
+        try:
+            if ':' in resource_id:
+                community_id, member_user_id = resource_id.split(':', 1)
+                return self.remove_member(community_id, member_user_id)
+            return ServiceResult.error_result("Invalid resource_id format. Expected 'community_id:user_id'")
+        except Exception as e:
+            return self._handle_service_exception(e, 'delete', resource_id=resource_id)
+
+    def add_member(self, community_id: str, user_id: str, invited_by_id: str = None, 
+                   status: str = "active") -> ServiceResult[CommunityMember]:
+        """
+        Add a member to a community.
+        
+        Args:
+            community_id: Community ID
+            user_id: User ID to add
+            invited_by_id: Optional ID of user who invited
+            status: Member status (active, pending, etc.)
+        """
+        try:
+            # Check if already a member
+            existing = self.get_membership(community_id, user_id)
+            if existing.success and existing.data:
+                if existing.data.status == "active":
+                    return ServiceResult.success_result(existing.data)
+                # Reactivate if previously left or banned
+                existing.data.status = status
+                existing.data.joined_at = dt.datetime.now(dt.UTC).timestamp()
+                existing.data.prep_for_save()
+                return self._save_model(existing.data)
+            
+            # Create new membership
+            member = CommunityMember()
+            member.community_id = community_id
+            member.user_id = user_id
+            member.status = status
+            member.invited_by_id = invited_by_id
+            member.joined_at = dt.datetime.now(dt.UTC).timestamp()
+            member.tenant_id = community_id  # For tenant isolation if needed
+            member.prep_for_save()
+            
+            return self._save_model(member)
+            
+        except Exception as e:
+            return self._handle_service_exception(
+                e, 'add_member', 
+                community_id=community_id, 
+                user_id=user_id
+            )
+
+    def remove_member(self, community_id: str, user_id: str) -> ServiceResult[bool]:
+        """
+        Remove a member from a community (soft delete by status change).
+        
+        Args:
+            community_id: Community ID
+            user_id: User ID to remove
+        """
+        try:
+            membership = self.get_membership(community_id, user_id)
+            
+            if not membership.success or not membership.data:
+                return ServiceResult.success_result(True)  # Already not a member
+            
+            # Mark as left instead of hard delete
+            membership.data.status = "left"
+            membership.data.prep_for_save()
+            
+            return self._save_model(membership.data).map(lambda _: True)
+            
+        except Exception as e:
+            return self._handle_service_exception(
+                e, 'remove_member',
+                community_id=community_id,
+                user_id=user_id
+            )
+
+    def get_membership(self, community_id: str, user_id: str) -> ServiceResult[CommunityMember]:
+        """
+        Get a specific membership record.
+        
+        Args:
+            community_id: Community ID
+            user_id: User ID
+        """
+        try:
+            # Create temp object to build the primary key
+            temp = CommunityMember()
+            temp.community_id = community_id
+            temp.user_id = user_id
+            
+            # Get by primary key (community + user)
+            result = self._get_by_primary_key(temp)
+            
+            if not result.success or not result.data:
+                raise NotFoundError("Membership not found")
+            
+            return result
+            
+        except Exception as e:
+            return self._handle_service_exception(
+                e, 'get_membership',
+                community_id=community_id,
+                user_id=user_id
+            )
+
+    def is_member(self, community_id: str, user_id: str, active_only: bool = True) -> bool:
+        """
+        Check if user is a member of community.
+        
+        Args:
+            community_id: Community ID
+            user_id: User ID
+            active_only: Only count active members (default True)
+        """
+        try:
+            result = self.get_membership(community_id, user_id)
+            
+            if not result.success or not result.data:
+                return False
+            
+            if active_only:
+                return result.data.is_active()
+            
+            return result.data.status in ["active", "pending"]
+            
+        except:
+            return False
+
+    def list_members(self, community_id: str, status: str = None, 
+                     limit: int = 50) -> ServiceResult[List[CommunityMember]]:
+        """
+        List members of a community.
+        
+        Args:
+            community_id: Community ID
+            status: Optional status filter (active, pending, etc.)
+            limit: Max results
+        """
+        try:
+            temp = CommunityMember()
+            temp.community_id = community_id
+            
+            if status:
+                # Query by status using GSI2
+                temp.status = status
+                result = self._query_by_index(temp, "gsi2", limit=limit, ascending=True)
+            else:
+                # Query all members using primary key begins_with
+                result = self._query_by_index(temp, "primary", limit=limit, ascending=True)
+            
+            if not result.success:
+                return result
+            
+            # Filter out deleted/left members if no status specified
+            if not status:
+                active_members = [m for m in result.data if m.status in ["active", "pending"]]
+                return ServiceResult.success_result(active_members)
+            
+            return result
+            
+        except Exception as e:
+            return self._handle_service_exception(
+                e, 'list_members',
+                community_id=community_id
+            )
+
+    def list_user_communities(self, user_id: str, status: str = "active",
+                             limit: int = 50) -> ServiceResult[List[CommunityMember]]:
+        """
+        List communities a user is a member of.
+        
+        Args:
+            user_id: User ID
+            status: Member status filter (default: active)
+            limit: Max results
+        """
+        try:
+            temp = CommunityMember()
+            temp.user_id = user_id
+            
+            # Query by user using GSI1
+            result = self._query_by_index(
+                temp, 
+                "gsi1", 
+                limit=limit,
+                ascending=False  # Most recently joined first
+            )
+            
+            if not result.success:
+                return result
+            
+            # Filter by status if specified
+            if status:
+                filtered = [m for m in result.data if m.status == status]
+                return ServiceResult.success_result(filtered)
+            
+            return result
+            
+        except Exception as e:
+            return self._handle_service_exception(
+                e, 'list_user_communities',
+                user_id=user_id
+            )
+
+    def get_member_count(self, community_id: str, status: str = "active") -> ServiceResult[int]:
+        """
+        Get count of members in a community.
+        
+        Args:
+            community_id: Community ID
+            status: Status filter (default: active)
+        """
+        try:
+            members_result = self.list_members(community_id, status=status, limit=1000)
+            
+            if not members_result.success:
+                return ServiceResult.error_result("Failed to count members")
+            
+            count = len(members_result.data)
+            return ServiceResult.success_result(count)
+            
+        except Exception as e:
+            return self._handle_service_exception(
+                e, 'get_member_count',
+                community_id=community_id
+            )
+
+    def update_member_status(self, community_id: str, user_id: str, 
+                            status: str) -> ServiceResult[CommunityMember]:
+        """
+        Update a member's status.
+        
+        Args:
+            community_id: Community ID
+            user_id: User ID
+            status: New status (active, pending, banned, left)
+        """
+        try:
+            membership = self.get_membership(community_id, user_id)
+            
+            if not membership.success or not membership.data:
+                raise NotFoundError("Membership not found")
+            
+            membership.data.status = status
+            membership.data.prep_for_save()
+            
+            return self._save_model(membership.data)
+            
+        except Exception as e:
+            return self._handle_service_exception(
+                e, 'update_member_status',
+                community_id=community_id,
+                user_id=user_id
+            )
+
+    def approve_pending_member(self, community_id: str, user_id: str) -> ServiceResult[CommunityMember]:
+        """
+        Approve a pending member.
+        
+        Args:
+            community_id: Community ID
+            user_id: User ID to approve
+        """
+        return self.update_member_status(community_id, user_id, "active")
+
+    def ban_member(self, community_id: str, user_id: str) -> ServiceResult[CommunityMember]:
+        """
+        Ban a member from the community.
+        
+        Args:
+            community_id: Community ID
+            user_id: User ID to ban
+        """
+        return self.update_member_status(community_id, user_id, "banned")
+
+    def update_dues_status(self, community_id: str, user_id: str,
+                          dues_status: str, next_payment_due: float = None) -> ServiceResult[CommunityMember]:
+        """
+        Update member's dues status.
+        
+        Args:
+            community_id: Community ID
+            user_id: User ID
+            dues_status: New dues status (current, overdue, exempt, pending)
+            next_payment_due: Optional next payment due date (timestamp)
+        """
+        try:
+            membership = self.get_membership(community_id, user_id)
+            
+            if not membership.success or not membership.data:
+                raise NotFoundError("Membership not found")
+            
+            membership.data.dues_status = dues_status
+            if dues_status == "current":
+                membership.data.last_payment_at = dt.datetime.now(dt.UTC).timestamp()
+            if next_payment_due:
+                membership.data.next_payment_due = next_payment_due
+                
+            membership.data.prep_for_save()
+            
+            return self._save_model(membership.data)
+            
+        except Exception as e:
+            return self._handle_service_exception(
+                e, 'update_dues_status',
+                community_id=community_id,
+                user_id=user_id
+            )
+
+    def list_members_with_overdue_dues(self, community_id: str, 
+                                       limit: int = 50) -> ServiceResult[List[CommunityMember]]:
+        """
+        List members with overdue dues using GSI3.
+        
+        Args:
+            community_id: Community ID
+            limit: Max results
+        """
+        try:
+            temp = CommunityMember()
+            temp.community_id = community_id
+            temp.dues_status = "overdue"
+            
+            result = self._query_by_index(
+                temp,
+                "gsi3",
+                limit=limit,
+                ascending=True  # Oldest overdue first
+            )
+            
+            return result
+            
+        except Exception as e:
+            return self._handle_service_exception(
+                e, 'list_members_with_overdue_dues',
+                community_id=community_id
+            )