ipulse-shared-core-ftredge 22.1.1__py3-none-any.whl → 23.1.1__py3-none-any.whl

ipulse_shared_core_ftredge/models/user/user_subscription.py

@@ -3,7 +3,7 @@ from dateutil.relativedelta import relativedelta
 import uuid
 from typing import Optional, ClassVar, Dict, Any, List
 from pydantic import Field, ConfigDict, model_validator
-from ipulse_shared_base_ftredge import Layer, Module, list_enums_as_lower_strings, Subject, SubscriptionPlanName, SubscriptionStatus
+from ipulse_shared_base_ftredge import Layer, Module, list_enums_as_lower_strings, Subject, SubscriptionPlanName, SubscriptionStatus, TimeUnit
 from ..base_data_model import BaseDataModel
 from .user_permissions import UserPermission
 # ORIGINAL AUTHOR ="russlan.ramdowar;russlan@ftredge.com"
@@ -62,9 +62,9 @@ class UserSubscription(BaseDataModel):
     )
 
     # Direct field instead of computed - will be auto-calculated
-    cycle_end_date: Optional[datetime] = Field(
-        default=None,
-        description="Subscription Cycle End Date (auto-calculated if not provided)"
+    cycle_end_datetime: Optional[datetime] = Field(
+        default=None,  # Optional during creation, auto-calculated by validator
+        description="Subscription Cycle End Date (auto-calculated if not provided during creation)"
     )
 
     # Fields for cycle calculation
@@ -79,9 +79,9 @@ class UserSubscription(BaseDataModel):
     )
 
     # Renewal and status fields
-    auto_renew: bool = Field(
-        ...,  # Required field, no default
-        description="Auto-renewal status"
+    auto_renew_end_datetime: Optional[datetime] = Field(
+        default=None,
+        description="End datetime for auto-renewal period. If None, no auto-renewal. If set, auto-renewal is active until this time."
     )
 
     status: SubscriptionStatus = Field(
@@ -163,25 +163,62 @@ class UserSubscription(BaseDataModel):
     @classmethod
     def auto_calculate_cycle_end_date(cls, data: Dict[str, Any]) -> Dict[str, Any]:
         """
-        Auto-calculate cycle_end_date if not provided, based on cycle_start_date,
+        Auto-calculate cycle_end_datetime if not provided, based on cycle_start_date,
         validity_time_length, and validity_time_unit.
         """
         if not isinstance(data, dict):
             return data
 
-        # Only calculate if cycle_end_date is not already provided
-        if 'cycle_end_date' not in data or data['cycle_end_date'] is None:
+        # Only calculate if cycle_end_datetime is not already provided or is the default
+        if ('cycle_end_datetime' not in data or
+            data['cycle_end_datetime'] is None or
+            # Check if it's the default factory value (close to now)
+            (isinstance(data.get('cycle_end_datetime'), datetime) and
+             abs((data['cycle_end_datetime'] - datetime.now(timezone.utc)).total_seconds()) < 5)):
+
             cycle_start_date = data.get('cycle_start_date')
             validity_time_length = data.get('validity_time_length')
             validity_time_unit = data.get('validity_time_unit')
 
             if cycle_start_date and validity_time_length and validity_time_unit:
-                data['cycle_end_date'] = cls.calculate_cycle_end_date(
+                data['cycle_end_datetime'] = cls.calculate_cycle_end_date(
                     cycle_start_date, validity_time_length, validity_time_unit
                 )
+            else:
+                raise ValueError(
+                    "Cannot create subscription without cycle_end_datetime. "
+                    "Either provide cycle_end_datetime directly or provide "
+                    "cycle_start_date, validity_time_length, and validity_time_unit for auto-calculation."
+                )
 
         return data
 
+    @model_validator(mode='after')
+    def validate_cycle_end_date_required(self) -> 'UserSubscription':
+        """
+        Ensures cycle_end_datetime is NEVER None after all processing.
+        This is a business rule validation that must always pass.
+        """
+        if self.cycle_end_datetime is None:
+            raise ValueError(
+                "cycle_end_datetime is required and cannot be None. "
+                "This is a critical business rule violation."
+            )
+        return self
+
+    @property
+    def cycle_end_datetime_safe(self) -> datetime:
+        """
+        Get cycle_end_datetime with guaranteed non-None value.
+        This property enforces the business rule that cycle_end_datetime is never None after validation.
+        """
+        if self.cycle_end_datetime is None:
+            raise ValueError(
+                "cycle_end_datetime is None - this violates the business rule. "
+                "Subscription model validation should have prevented this."
+            )
+        return self.cycle_end_datetime
+
     # Helper method to calculate cycle end date
     @classmethod
     def calculate_cycle_end_date(cls, start_date: datetime, validity_length: int, validity_unit: str) -> datetime:
@@ -202,35 +239,110 @@ class UserSubscription(BaseDataModel):
     # Methods for subscription management
     def is_active(self) -> bool:
         """Check if the subscription is currently active."""
-        if not self.cycle_end_date:
-            return False
         now = datetime.now(timezone.utc)
         return (
             self.status == SubscriptionStatus.ACTIVE and
-            self.cycle_start_date <= now <= self.cycle_end_date
+            self.cycle_start_date <= now <= self.cycle_end_datetime_safe
         )
 
     def is_expired(self) -> bool:
         """Check if the subscription has expired."""
-        if not self.cycle_end_date:
-            return True
         now = datetime.now(timezone.utc)
-        return now > self.cycle_end_date
+        return now > self.cycle_end_datetime_safe
+
+    def subscription_time_remaining(self, unit: TimeUnit = TimeUnit.SECOND, with_auto_renew: bool = False) -> float:
+        """
+        Calculate time remaining in the subscription.
+
+        Args:
+            unit: Time unit to return (using TimeUnit enum)
+            with_auto_renew: Whether to consider auto-renewal cycles until auto_renew_end_datetime
 
-    def days_remaining(self) -> int:
-        """Calculate the number of days remaining in the subscription."""
-        if not self.cycle_end_date:
-            return 0
+        Returns:
+            Time remaining in the specified unit as float
+        """
         now = datetime.now(timezone.utc)
-        if now > self.cycle_end_date:
-            return 0
 
-        # Get time difference
-        time_diff = self.cycle_end_date - now
+        if with_auto_renew and self.auto_renew_end_datetime:
+            # Calculate with auto-renewal logic
+            # If auto-renewal ends before/at current cycle end, only current cycle matters
+            if self.auto_renew_end_datetime <= self.cycle_end_datetime_safe:
+                if now >= self.cycle_end_datetime_safe:
+                    return 0.0
+                time_diff = self.cycle_end_datetime_safe - now
+            else:
+                # If we're past the auto-renewal end date, no time remaining
+                if now >= self.auto_renew_end_datetime:
+                    return 0.0
+
+                # Calculate the last cycle end date that falls within auto_renew_end_datetime
+                last_cycle_end = self._calculate_last_cycle_end_within_auto_renew()
+
+                # Calculate time from now until that last cycle end
+                if now >= last_cycle_end:
+                    return 0.0
+
+                time_diff = last_cycle_end - now
+        else:
+            # Basic time calculation without auto-renewal
+            if now >= self.cycle_end_datetime_safe:
+                return 0.0
+            time_diff = self.cycle_end_datetime_safe - now
+
+        # Convert to the requested unit
+        return self._convert_time_to_unit(time_diff.total_seconds(), unit.value)
+
+    def _calculate_last_cycle_end_within_auto_renew(self) -> datetime:
+        """
+        Calculate the last cycle end date that falls within the auto_renew_end_datetime period.
+
+        Returns:
+            The last cycle end date before auto_renew_end_datetime expires
+        """
+        if not self.auto_renew_end_datetime:
+            return self.cycle_end_datetime_safe
+
+        # Start with current cycle end
+        current_cycle_end = self.cycle_end_datetime_safe
+
+        # Keep adding cycle lengths until we pass auto_renew_end_datetime
+        while current_cycle_end < self.auto_renew_end_datetime:
+            # Calculate next cycle end by adding the cycle length
+            next_cycle_end = self.calculate_cycle_end_date(
+                start_date=current_cycle_end,
+                validity_length=self.validity_time_length,
+                validity_unit=self.validity_time_unit
+            )
+
+            # If the next cycle would end after auto_renew_end_datetime, we stop
+            if next_cycle_end > self.auto_renew_end_datetime:
+                break
 
-        # If there's any time remaining but less than a day, return 1
-        if time_diff.days == 0 and time_diff.seconds > 0:
-            return 1
+            current_cycle_end = next_cycle_end
+
+        return current_cycle_end
+
+    def _convert_time_to_unit(self, total_seconds: float, unit: str) -> float:
+        """
+        Convert seconds to the specified time unit.
+
+        Args:
+            total_seconds: Total seconds to convert
+            unit: Target unit (string value from TimeUnit enum)
+
+        Returns:
+            Time in the specified unit as float
+        """
+        conversions = {
+            'second': 1.0,
+            'minute': 60.0,
+            'hour': 3600.0,
+            'day': 3600.0 * 24.0,
+            'week': 3600.0 * 24.0 * 7.0,
+            'month': 3600.0 * 24.0 * 30.0,  # Approximate 30 days per month
+            'year': 3600.0 * 24.0 * 365.0,  # Approximate 365 days per year
+        }
+
+        divisor = conversions.get(unit.lower(), 1.0)
+        return total_seconds / divisor
 
-        # Otherwise return the number of complete days
-        return time_diff.days

ipulse_shared_core_ftredge/models/user/userstatus.py

@@ -1,8 +1,8 @@
 """ User Status model for tracking user subscription and access rights. """
-from datetime import datetime, timezone
+from datetime import datetime, timezone, timedelta
 from typing import Set, Optional, Dict, List, ClassVar, Any
 from pydantic import Field, ConfigDict, model_validator, field_validator
-from ipulse_shared_base_ftredge import Layer, Module, list_enums_as_lower_strings, Subject
+from ipulse_shared_base_ftredge import Layer, Module, list_enums_as_lower_strings, Subject, TimeUnit
 from ipulse_shared_base_ftredge.enums.enums_iam import IAMUnit
 from .user_subscription import UserSubscription
 from ..base_data_model import BaseDataModel
@@ -19,7 +19,7 @@ class UserStatus(BaseDataModel):
     model_config = ConfigDict(frozen=False, extra="forbid")
 
     # Class constants
-    VERSION: ClassVar[float] = 6.0  # Major version bump for flattened IAM permissions structure
+    VERSION: ClassVar[float] = 7.0  # Major version bump for flattened IAM permissions structure
     DOMAIN: ClassVar[str] = "_".join(list_enums_as_lower_strings(Layer.PULSE_APP, Module.CORE, Subject.USER))
     OBJ_REF: ClassVar[str] = "userstatus"
 
@@ -329,7 +329,7 @@ class UserStatus(BaseDataModel):
                 iam_unit_type=permission.iam_unit_type,
                 permission_ref=permission.permission_ref,
                 source=source,
-                expires_at=subscription.cycle_end_date,
+                expires_at=subscription.cycle_end_datetime,
                 granted_by=granted_by
             )
             added_count += 1
@@ -343,14 +343,8 @@ class UserStatus(BaseDataModel):
             return self.active_subscription.is_active()
         return False
 
-    # Method instead of computed field
-    def subscription_expires_in_days(self) -> Optional[int]:
-        """Get days until subscription expiration."""
-        if self.active_subscription and self.active_subscription.is_active():
-            return self.active_subscription.days_remaining()
-        return None
 
-    def apply_subscription(self, subscription: UserSubscription, add_associated_permissions: bool = True, remove_existing_subscription_permissions: bool = True, granted_by: Optional[str] = None) -> int:
+    def apply_subscription(self, subscription: UserSubscription, add_associated_permissions: bool = True, remove_previous_subscription_permissions: bool = True, granted_by: Optional[str] = None) -> int:
         """
         Apply a subscription's benefits to the user status.
         This updates credits, permissions, and sets the active subscription.
@@ -358,7 +352,7 @@ class UserStatus(BaseDataModel):
         Args:
             subscription: The subscription to apply
             add_associated_permissions: If True, adds IAM permissions from the subscription
-            remove_existing_subscription_permissions: If True, removes IAM permissions from any existing subscription
+            remove_previous_subscription_permissions: If True, removes IAM permissions from any existing subscription
             granted_by: Who granted this permission (user ID, system process, etc.)
 
         Returns:
@@ -370,7 +364,7 @@ class UserStatus(BaseDataModel):
         permissions_added = 0
 
         # Remove existing subscription permissions if requested
-        if remove_existing_subscription_permissions and self.active_subscription:
+        if remove_previous_subscription_permissions and self.active_subscription:
             # Use the subscription plan_id as the source (which already contains "subscription" and version)
             source = self.active_subscription.plan_id
             removed_permissions = self.remove_all_permissions(source=source)
@@ -427,4 +421,59 @@ class UserStatus(BaseDataModel):
         self.sbscrptn_based_insight_credits_updtd_on = datetime.now(timezone.utc)
         self.active_subscription = None
 
-        return permissions_removed
+        return permissions_removed
+
+    ########################################################################
+    ############ #########   Credit Management  ######### #############
+    ########################################################################
+
+    def should_update_subscription_credits(self) -> bool:
+        """
+        Check if subscription-based credits should be updated based on the cycle timing.
+
+        Credits should be updated if:
+        1. User has an active subscription
+        2. The last update was before the current cycle period started
+
+        Returns:
+            True if credits should be updated, False otherwise
+        """
+        if not self.active_subscription or not self.active_subscription.is_active():
+            return False
+
+        now = datetime.now(timezone.utc)
+        cycle_start = self.active_subscription.cycle_start_date
+        update_frequency_hours = self.active_subscription.subscription_based_insight_credits_update_freq_h
+
+        # Calculate when the next credit update should happen based on cycle start
+        # We need to find the most recent cycle boundary that has passed
+        hours_since_cycle_start = (now - cycle_start).total_seconds() / 3600
+        completed_periods = int(hours_since_cycle_start // update_frequency_hours)
+
+        if completed_periods == 0:
+            # We haven't completed even one period yet
+            return False
+
+        # Calculate when the last period should have ended
+        last_period_end = cycle_start + timedelta(hours=completed_periods * update_frequency_hours)
+
+        # Check if our last update was before this period ended
+        return self.sbscrptn_based_insight_credits_updtd_on < last_period_end
+
+    def update_subscription_credits(self) -> int:
+        """
+        Update subscription-based credits if needed.
+
+        Returns:
+            Amount of credits added (0 if no update needed)
+        """
+        if not self.should_update_subscription_credits() or not self.active_subscription:
+            return 0
+
+        final_credits = self.active_subscription.subscription_based_insight_credits_per_update
+
+        if final_credits > 0:
+            self.sbscrptn_based_insight_credits = final_credits
+            self.sbscrptn_based_insight_credits_updtd_on = datetime.now(timezone.utc)
+
+        return final_credits

ipulse_shared_core_ftredge/services/base/base_firestore_service.py

@@ -372,7 +372,8 @@ class BaseFirestoreService(Generic[T]):
         limit: Optional[int] = None,
         start_after: Optional[str] = None,
         order_by: Optional[str] = None,
-        filters: Optional[List[FieldFilter]] = None,
+        order_direction: str = firestore.Query.ASCENDING,
+        filters: Optional[List[tuple]] = None,
         as_models: bool = True
     ) -> Union[List[T], List[Dict[str, Any]]]:
         """
@@ -382,7 +383,8 @@ class BaseFirestoreService(Generic[T]):
             limit: Maximum number of documents to return
             start_after: Document ID to start after for pagination
             order_by: Field to order by
-            filters: List of field filters
+            order_direction: Direction to order by (e.g., "ASCENDING", "DESCENDING")
+            filters: List of field filters as tuples (field, operator, value)
             as_models: Whether to convert documents to Pydantic models
 
         Returns:
@@ -402,7 +404,7 @@ class BaseFirestoreService(Generic[T]):
 
             # Apply ordering
             if order_by:
-                query = query.order_by(order_by)
+                query = query.order_by(order_by, direction=order_direction)
 
             # Apply pagination
             if start_after:

ipulse_shared_core_ftredge/services/catalog/catalog_subscriptionplan_service.py

@@ -174,7 +174,8 @@ class CatalogSubscriptionPlanService(BaseFirestoreService[SubscriptionPlan]):
         plan_name: Optional[SubscriptionPlanName] = None,
         pulse_status: Optional[ObjectOverallStatus] = None,
         latest_version_only: bool = False,
-        limit: Optional[int] = None
+        limit: Optional[int] = None,
+        version_ordering: str = "DESCENDING"
     ) -> List[SubscriptionPlan]:
         """
         List subscription plans with optional filtering.
@@ -184,6 +185,7 @@ class CatalogSubscriptionPlanService(BaseFirestoreService[SubscriptionPlan]):
             pulse_status: Filter by specific pulse status
             latest_version_only: Only return the latest version per plan
             limit: Maximum number of plans to return
+            version_ordering: Order direction for version ('ASCENDING' or 'DESCENDING')
 
         Returns:
             List of subscription plans
@@ -191,7 +193,7 @@ class CatalogSubscriptionPlanService(BaseFirestoreService[SubscriptionPlan]):
         Raises:
             ServiceError: If listing fails
         """
-        self.logger.debug(f"Listing subscription plans - plan_name: {plan_name}, pulse_status: {pulse_status}, latest_version_only: {latest_version_only}")
+        self.logger.debug(f"Listing subscription plans - plan_name: {plan_name}, pulse_status: {pulse_status}, latest_version_only: {latest_version_only}, version_ordering: {version_ordering}")
 
         # Build query filters
         filters = []
@@ -200,39 +202,41 @@ class CatalogSubscriptionPlanService(BaseFirestoreService[SubscriptionPlan]):
         if pulse_status:
             filters.append(("pulse_status", "==", pulse_status.value))
 
-        # If latest_version_only is requested, order by version descending
-        order_by = None
-        if latest_version_only:
-            order_by = "plan_version"  # Use plan_version field name
+        # Set ordering
+        order_by = "plan_version"
+        order_direction = firestore.Query.DESCENDING if version_ordering == "DESCENDING" else firestore.Query.ASCENDING
+
+        # Optimize query if only the latest version of a specific plan is needed
+        query_limit = limit
+        if latest_version_only and plan_name:
+            query_limit = 1
+            # Ensure descending order to get the latest
+            order_direction = firestore.Query.DESCENDING
 
         docs = await self.list_documents(
             filters=filters,
             order_by=order_by,
-            limit=limit
+            order_direction=order_direction,
+            limit=query_limit
         )
 
         # Convert to SubscriptionPlan models
-        plans = [SubscriptionPlan.model_validate(doc) if isinstance(doc, dict) else doc for doc in docs]
+        plans = [SubscriptionPlan.model_validate(doc) for doc in docs]
+
+        # If we need the latest of all plans, we fetch all sorted by version
+        # and then pick the first one for each plan_name in Python.
+        if latest_version_only and not plan_name:
+            # This assumes the list is sorted by version descending.
+            if order_direction != firestore.Query.DESCENDING:
+                self.logger.warning("latest_version_only is True but version_ordering is not DESCENDING. Results may not be the latest.")
 
-        # If latest_version_only is requested, group by plan_name and get highest version
-        if latest_version_only:
-            # Group by plan_name
             plan_groups = {}
             for plan in plans:
                 key = plan.plan_name.value
                 if key not in plan_groups:
-                    plan_groups[key] = []
-                plan_groups[key].append(plan)
-
-            # Get the latest version for each group
-            latest_plans = []
-            for group in plan_groups.values():
-                if group:
-                    # Sort by plan_version descending and take the first
-                    latest = max(group, key=lambda x: x.plan_version)
-                    latest_plans.append(latest)
-
-            return latest_plans
+                    plan_groups[key] = plan  # First one is the latest due to sorting
+
+            return list(plan_groups.values())
 
         return plans
 

ipulse_shared_core_ftredge/services/catalog/catalog_usertype_service.py

@@ -7,7 +7,7 @@ These templates are used to configure default settings for user profiles and sta
 
 import logging
 from typing import Dict, List, Optional, Any
-from google.cloud.firestore import Client
+from google.cloud.firestore import Client , Query
 from ipulse_shared_base_ftredge import IAMUserType
 from ipulse_shared_base_ftredge.enums.enums_status import ObjectOverallStatus
 from ipulse_shared_core_ftredge.models.catalog.usertype import UserType
@@ -171,7 +171,8 @@ class CatalogUserTypeService(BaseFirestoreService[UserType]):
         primary_usertype: Optional[IAMUserType] = None,
         pulse_status: Optional[ObjectOverallStatus] = None,
         latest_version_only: bool = False,
-        limit: Optional[int] = None
+        limit: Optional[int] = None,
+        version_ordering: str = "DESCENDING"
     ) -> List[UserType]:
         """
         List usertypes with optional filtering.
@@ -181,6 +182,7 @@ class CatalogUserTypeService(BaseFirestoreService[UserType]):
             pulse_status: Filter by specific pulse status
             latest_version_only: Only return the latest version per usertype
             limit: Maximum number of usertypes to return
+            version_ordering: Order direction for version ('ASCENDING' or 'DESCENDING')
 
         Returns:
             List of usertypes
@@ -188,7 +190,7 @@ class CatalogUserTypeService(BaseFirestoreService[UserType]):
         Raises:
             ServiceError: If listing fails
         """
-        self.logger.debug(f"Listing usertypes - primary_usertype: {primary_usertype}, pulse_status: {pulse_status}, latest_version_only: {latest_version_only}")
+        self.logger.debug(f"Listing usertypes - primary_usertype: {primary_usertype}, pulse_status: {pulse_status}, latest_version_only: {latest_version_only}, version_ordering: {version_ordering}")
 
         # Build query filters
         filters = []
@@ -197,41 +199,41 @@ class CatalogUserTypeService(BaseFirestoreService[UserType]):
         if pulse_status:
             filters.append(("pulse_status", "==", pulse_status.value))
 
-        # If latest_version_only is requested, order by version descending
-        order_by = None
-        if latest_version_only:
-            order_by = "version"
-            # We'll need to group by primary_usertype and take the first from each group
-            # This is more complex, so let's handle it differently
+        # Set ordering
+        order_by = "version"
+        order_direction = Query.DESCENDING if version_ordering == "DESCENDING" else Query.ASCENDING
+
+        # Optimize query if only the latest version of a specific usertype is needed
+        query_limit = limit
+        if latest_version_only and primary_usertype:
+            query_limit = 1
+            # Ensure descending order to get the latest
+            order_direction = Query.DESCENDING
 
         docs = await self.list_documents(
             filters=filters,
             order_by=order_by,
-            limit=limit
+            order_direction=order_direction,
+            limit=query_limit
         )
 
         # Convert to UserType models
-        usertypes = [UserType.model_validate(doc) if isinstance(doc, dict) else doc for doc in docs]
+        usertypes = [UserType.model_validate(doc) for doc in docs]
+
+        # If we need the latest of all usertypes, we fetch all sorted by version
+        # and then pick the first one for each primary_usertype in Python.
+        if latest_version_only and not primary_usertype:
+            # This assumes the list is sorted by version descending.
+            if order_direction != Query.DESCENDING:
+                self.logger.warning("latest_version_only is True but version_ordering is not DESCENDING. Results may not be the latest.")
 
-        # If latest_version_only is requested, group by primary_usertype and get highest version
-        if latest_version_only:
-            # Group by primary_usertype
             usertype_groups = {}
             for usertype in usertypes:
                 key = usertype.primary_usertype.value
                 if key not in usertype_groups:
-                    usertype_groups[key] = []
-                usertype_groups[key].append(usertype)
-
-            # Get the latest version for each group
-            latest_usertypes = []
-            for group in usertype_groups.values():
-                if group:
-                    # Sort by version descending and take the first
-                    latest = max(group, key=lambda x: x.version)
-                    latest_usertypes.append(latest)
+                    usertype_groups[key] = usertype  # First one is the latest due to sorting
 
-            return latest_usertypes
+            return list(usertype_groups.values())
 
         return usertypes
 
@@ -305,3 +307,70 @@ class CatalogUserTypeService(BaseFirestoreService[UserType]):
             "extra_insight_credits": usertype.default_extra_insight_credits,
             "voting_credits": usertype.default_voting_credits
         }
+
+    async def fetch_catalog_usertype_based_on_email(
+        self,
+        email: str,
+        superadmins: Optional[List[str]] = None,
+        admins: Optional[List[str]] = None,
+        internal_domains: Optional[List[str]] = None
+    ) -> UserType:
+        """
+        Fetch the actual usertype from catalog based on email domain classification.
+
+        Args:
+            email: User's email address
+            superadmins: List of superadmin emails
+            admins: List of admin emails
+            internal_domains: List of internal domains
+
+        Returns:
+            UserType object from the catalog
+
+        Raises:
+            ServiceError: If no active usertype found for the determined primary_usertype
+        """
+        if not email:
+            primary_usertype = IAMUserType.CUSTOMER
+        else:
+            superadmins = superadmins or []
+            admins = admins or []
+            internal_domains = internal_domains or []
+
+            email_lower = email.lower()
+
+            if email_lower in [admin.lower() for admin in superadmins]:
+                primary_usertype = IAMUserType.SUPERADMIN
+            elif email_lower in [admin.lower() for admin in admins]:
+                primary_usertype = IAMUserType.ADMIN
+            else:
+                domain = email_lower.split('@')[-1] if '@' in email_lower else ''
+                if domain in internal_domains:
+                    primary_usertype = IAMUserType.INTERNAL
+                else:
+                    primary_usertype = IAMUserType.CUSTOMER
+
+        # Get the actual usertype from the catalog
+        usertypes = await self.list_usertypes(
+            primary_usertype=primary_usertype,
+            pulse_status=ObjectOverallStatus.ACTIVE,
+            latest_version_only=True,
+            limit=1
+        )
+
+        if not usertypes:
+            from ipulse_shared_core_ftredge.exceptions import ServiceError
+            raise ServiceError(
+                error=f"No active usertype found in catalog for primary_usertype '{primary_usertype.value}'",
+                resource_type="usertype",
+                operation="fetch_catalog_usertype_based_on_email",
+                additional_info={
+                    "email": email,
+                    "primary_usertype": primary_usertype.value,
+                    "domain": email.split('@')[-1] if '@' in email else ''
+                }
+            )
+
+        usertype = usertypes[0]
+        self.logger.info(f"Found usertype '{usertype.id}' for email '{email}' with primary_usertype '{primary_usertype.value}'")
+        return usertype