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

ipulse_shared_core_ftredge/services/user/user_core_service.py

@@ -4,47 +4,32 @@ Enhanced UserCoreService - Comprehensive user management orchestration
 This service orchestrates all user-related operations by composing specialized
 operation classes for different concerns:
 - Firebase Auth User Management
-- User Account Management (UserProfile and UserStatus CRUD operations)
+- User Profile and Status Management
 - User Deletion Operations
 - Subscription Management
 - IAM Management
-- Default Values by UserType
+- Configuration by UserType
 
-Can be used by Firebase Cloud Functions, Core microservice APIs, admin tools, and tests.
+Can be used by Firebase Cloud Functions, admin tools, service APIs, admin tools, and tests.
 """
 import logging
-from typing import Any, Dict, List, Optional, Set, Tuple
+from typing import Any, Dict, List, Optional, Tuple, Union
+from datetime import datetime
 from google.cloud import firestore
-from pydantic import BaseModel
+from firebase_admin.auth import UserRecord
+from ipulse_shared_base_ftredge import ApprovalStatus, IAMUnit, IAMUserType
+from ...models import UserProfile, UserStatus, UserAuth, UserSubscription, UserType, SubscriptionPlan, UserPermission
 
-from ...models.user_profile import UserProfile
-from ...models.user_status import UserStatus, IAMUnitRefAssignment
-from ...models.user_auth import UserAuth
-from ...models.subscription import Subscription
-from ...exceptions import ServiceError, ResourceNotFoundError, UserCreationError
-from ..base import BaseFirestoreService
-from ipulse_shared_base_ftredge.enums.enums_iam import IAMUnitType
 
 # Import specialized operation classes
-from .user_account_operations import UserAccountOperations
-from .subscription_management_operations import SubscriptionManagementOperations, SubscriptionPlanDocument
-from .iam_management_operations import IAMManagementOperations
-from .user_auth_operations import UserAuthOperations
-from .user_holistic_operations import UserHolisticOperations
-
-
-# Model for user type defaults from Firestore
-class UserTypeDefaultsDocument(BaseModel):
-    """Model for user type defaults documents stored in Firestore"""
-    id: str
-    default_iam_domain_permissions: Optional[Dict[str, Dict[str, Dict[str, IAMUnitRefAssignment]]]] = None
-    default_subscription_based_insight_credits: Optional[int] = None
-    default_extra_insight_credits: Optional[int] = None
-    default_voting_credits: Optional[int] = None
-    default_subscription_plan_if_unpaid: Optional[str] = None
-    default_secondary_usertypes: Optional[List[str]] = None
-    default_organizations_uids: Optional[List[str]] = None
-    default_subscription_plan_id: Optional[str] = None
+from .userprofile_operations import UserprofileOperations
+from .userstatus_operations import UserstatusOperations
+from .user_subscription_operations import UsersubscriptionOperations
+from .user_permissions_operations import UserpermissionsOperations
+from .userauth_operations import UserauthOperations
+from .user_multistep_operations import UsermultistepOperations
+from ..catalog.catalog_usertype_service import CatalogUserTypeService
+from ..catalog.catalog_subscriptionplan_service import CatalogSubscriptionPlanService
 
 
 class UserCoreService:
@@ -62,9 +47,7 @@ class UserCoreService:
         logger: Optional[logging.Logger] = None,
         default_timeout: float = 10.0,
         profile_collection: Optional[str] = None,
-        status_collection: Optional[str] = None,
-        subscriptionplans_defaults_collection: str = "papp_core_configs_subscriptionplans_defaults",
-        users_defaults_collection: str = "papp_core_configs_users_defaults"
+        status_collection: Optional[str] = None
     ):
         """
         Initialize the Enhanced UserCoreService
@@ -75,8 +58,8 @@ class UserCoreService:
             default_timeout: Default timeout for Firestore operations
             profile_collection: Collection name for user profiles
             status_collection: Collection name for user statuses
-            subscriptionplans_defaults_collection: Collection name for subscription plans
-            users_defaults_collection: Collection name for user defaults
+            subscription_plans_collection: Collection name for subscription plans
+            user_types_collection: Collection name for user types
         """
         self.db = firestore_client
         self.logger = logger or logging.getLogger(__name__)
@@ -86,566 +69,609 @@ class UserCoreService:
         self.status_collection_name = status_collection or UserStatus.get_collection_name()
 
         # Initialize specialized operation classes in dependency order
-        self.user_auth_ops = UserAuthOperations(
+        self.userauth_ops = UserauthOperations(
             logger=self.logger
         )
 
-        self.user_account_ops = UserAccountOperations(
+        self.userprofile_ops = UserprofileOperations(
             firestore_client=self.db,
             logger=self.logger,
             timeout=self.timeout,
             profile_collection=self.profile_collection_name,
-            status_collection=self.status_collection_name
         )
 
-        self.subscription_ops = SubscriptionManagementOperations(
+        self.userstatus_ops = UserstatusOperations(
             firestore_client=self.db,
-            user_account_ops=self.user_account_ops,
             logger=self.logger,
             timeout=self.timeout,
-            subscription_plans_collection=subscriptionplans_defaults_collection
+            status_collection=self.status_collection_name,
         )
 
-        self.iam_ops = IAMManagementOperations(
-            user_account_ops=self.user_account_ops,
+        self.iam_ops = UserpermissionsOperations(
+            userstatus_ops=self.userstatus_ops,
             logger=self.logger
         )
 
-        # Initialize holistic operations last as it depends on other operations
-        self.user_holistic_ops = UserHolisticOperations(
-            user_account_ops=self.user_account_ops,
-            user_auth_ops=self.user_auth_ops,
-            subscription_ops=self.subscription_ops,
-            iam_ops=self.iam_ops,
+        self.subscription_ops = UsersubscriptionOperations(
+            firestore_client=self.db,
+            userstatus_ops=self.userstatus_ops,
+            permissions_ops=self.iam_ops,
+            logger=self.logger,
+            timeout=self.timeout
+        )
+
+        # Initialize catalog services
+        self.catalog_usertype_service = CatalogUserTypeService(
+            firestore_client=self.db,
             logger=self.logger
         )
 
-        # Initialize defaults values per usertype service
-        self.usertype_defaults_collection_name = users_defaults_collection
-        self._user_defaults_db_service = BaseFirestoreService[UserTypeDefaultsDocument](
-            db=self.db,
-            collection_name=self.usertype_defaults_collection_name,
-            resource_type="UserTypeDefault",
-            logger=self.logger,
-            timeout=self.timeout
+        self.catalog_subscriptionplan_service = CatalogSubscriptionPlanService(
+            firestore_client=self.db,
+            logger=self.logger
+        )
+
+        # Initialize multistep operations last as it depends on other operations
+        self.usermultistep_ops = UsermultistepOperations(
+            userprofile_ops=self.userprofile_ops,
+            userstatus_ops=self.userstatus_ops,
+            userauth_ops=self.userauth_ops,
+            usersubscription_ops=self.subscription_ops,
+            useriam_ops=self.iam_ops,
+            catalog_usertype_service=self.catalog_usertype_service,
+            catalog_subscriptionplan_service=self.catalog_subscriptionplan_service,
+            logger=self.logger
         )
 
 
     ######################################################################
-    ######################### UserAuth Operation #########################
+    ######################### Complete User Creation ####################
+    ######################################################################
 
+    async def create_user_from_models(
+        self,
+        userprofile: UserProfile,
+        userstatus: UserStatus,
+        userauth: Optional[UserAuth] = None,
+        validate_userauth_consistency: bool = False,
+        validate_userauth_exists: bool = False
+    ) -> Tuple[str, UserProfile, UserStatus]:
+        """
+        Create a complete user from ready UserAuth, UserProfile, and UserStatus models.
 
+        Delegates to UsermultistepOperations for the actual creation.
+        """
+        return await self.usermultistep_ops.create_user_from_models(
+            userprofile=userprofile,
+            userstatus=userstatus,
+            userauth=userauth,
+            validate_userauth_consistency=validate_userauth_consistency,
+            validate_userauth_exists=validate_userauth_exists
+        )
 
+    async def create_user_from_manual_usertype(
+        self,
+        userprofile: UserProfile,
+        usertype: UserType,
+        userauth: Optional[UserAuth] = None,
+        extra_insight_credits_override: Optional[int] = None,
+        voting_credits_override: Optional[int] = None,
+        subscriptionplan_id_override: Optional[str] = None,
+        created_by: Optional[str] = None,
+        apply_usertype_associated_subscriptionplan: bool = True,
+        validate_userauth_consistency: bool = False,
+        validate_userauth_exists: bool = False
+    ) -> Tuple[str, UserProfile, UserStatus]:
+        """
+        Create a complete user with manual UserType configuration.
 
+        Delegates to UsermultistepOperations for the actual creation.
+        """
+        return await self.usermultistep_ops.create_user_from_manual_usertype(
+            userprofile=userprofile,
+            usertype=usertype,
+            userauth=userauth,
+            extra_insight_credits_override=extra_insight_credits_override,
+            voting_credits_override=voting_credits_override,
+            subscriptionplan_id_override=subscriptionplan_id_override,
+            creator_uid=created_by,
+            apply_usertype_associated_subscriptionplan=apply_usertype_associated_subscriptionplan,
+            validate_userauth_consistency=validate_userauth_consistency,
+            validate_userauth_exists=validate_userauth_exists
+        )
 
-    def generate_firebase_custom_claims(
+    async def create_user_from_catalog_usertype(
         self,
-        primary_usertype: str,
-        secondary_usertypes: Optional[List[str]] = None,
-        organizations_uids: Optional[List[str]] = None,
-        user_approval_status: str = "pending"
-    ) -> Dict[str, Any]:
-        """Generate Firebase custom claims for a user"""
-        return self.user_auth_ops.generate_firebase_custom_claims(
-            primary_usertype=primary_usertype,
-            secondary_usertypes=secondary_usertypes,
-            organizations_uids=organizations_uids,
-            user_approval_status=user_approval_status
-        )
+        usertype_id: str,
+        userprofile: UserProfile,
+        userauth: Optional[UserAuth] = None,
+        extra_insight_credits_override: Optional[int] = None,
+        voting_credits_override: Optional[int] = None,
+        subscriptionplan_id_override: Optional[str] = None,
+        created_by: Optional[str] = None,
+        apply_usertype_associated_subscriptionplan: bool = True,
+        validate_userauth_consistency: bool = False,
+        validate_userauth_exists: bool = False
+    ) -> Tuple[str, UserProfile, UserStatus]:
+        """
+        Create a complete user based on UserType catalog configuration.
 
+        Delegates to UsermultistepOperations for the actual creation.
+        """
+        return await self.usermultistep_ops.create_user_from_catalog_usertype(
+            usertype_id=usertype_id,
+            userprofile=userprofile,
+            userauth=userauth,
+            extra_insight_credits_override=extra_insight_credits_override,
+            voting_credits_override=voting_credits_override,
+            subscriptionplan_id_override=subscriptionplan_id_override,
+            creator_uid=created_by,
+            apply_usertype_associated_subscriptionplan=apply_usertype_associated_subscriptionplan,
+            validate_userauth_consistency=validate_userauth_consistency,
+            validate_userauth_exists=validate_userauth_exists
+        )
 
+    ######################################################################
+    ######################### User Validation ############################
+    ######################################################################
 
-    ################################################################################################
-    ######################### Fetching Default User/Subscription Values   #########################
-
-    async def fetch_user_defaults(self, usertype_name: str) -> Optional[Dict[str, Any]]:
-        """Fetch user type defaults from Firestore"""
-        try:
-            user_defaults_data = await self._user_defaults_db_service.get_document(usertype_name)
-            if user_defaults_data:
-                self.logger.info(f"User defaults found for usertype: {usertype_name}")
-                # Convert UserTypeDefaultsDocument to dict for backward compatibility
-                if isinstance(user_defaults_data, UserTypeDefaultsDocument):
-                    return user_defaults_data.model_dump()
-                return user_defaults_data
-            else:
-                self.logger.warning(f"User defaults not found for usertype: {usertype_name}")
-                return None
-        except ResourceNotFoundError:
-            self.logger.warning(f"User defaults not found for usertype: {usertype_name}")
-            return None
-        except Exception as e:
-            self.logger.error(f"Error fetching user defaults for {usertype_name}: {e}", exc_info=True)
-            raise ServiceError(
-                operation="fetch_user_defaults",
-                resource_type="UserTypeDefault",
-                resource_id=usertype_name,
-                error=e
-            )
-
-    async def _fetch_subscription_plan_details(self, plan_id: str) -> Optional[SubscriptionPlanDocument]:
-        """Fetch subscription plan details (backward compatibility)"""
-        return await self.subscription_ops.fetch_subscription_plan_details(plan_id)
-
-    ###############################################################################
-    ############################## User Account Operation #########################
+    async def user_exists_fully(self, user_uid: str) -> Dict[str, bool]:
+        """Check if complete user exists (Auth, Profile, Status)"""
+        return await self.usermultistep_ops.user_exists_fully(user_uid=user_uid)
 
-    async def get_userprofile(self, user_uid: str) -> Optional[UserProfile]:
-        """Get a user profile by user UID"""
-        return await self.user_account_ops.get_userprofile(user_uid)
+    async def validate_user_fully_enabled(
+        self,
+        user_uid: str,
+        email_verified_must: bool = True,
+        approved_must: bool = True,
+        active_subscription_must: bool = True,
+        valid_permissions_must: bool = True
+    ) -> Dict[str, Any]:
+        """
+        Validate complete user integrity and operational readiness with configurable requirements.
 
-    async def get_userstatus(self, user_uid: str) -> Optional[UserStatus]:
-        """Get a user status by user UID"""
-        return await self.user_account_ops.get_userstatus(user_uid)
+        Delegates to UsermultistepOperations for comprehensive validation.
+        """
+        return await self.usermultistep_ops.validate_user_fully_enabled(
+            user_uid=user_uid,
+            email_verified_must=email_verified_must,
+            approved_must=approved_must,
+            active_subscription_must=active_subscription_must,
+            valid_permissions_must=valid_permissions_must
+        )
 
-    async def create_userprofile(self, user_profile: UserProfile) -> UserProfile:
-        """Create a new user profile"""
-        return await self.user_account_ops.create_userprofile(user_profile)
+    ######################################################################
+    ######################### User Deletion ##############################
+    ######################################################################
 
-    async def create_userstatus(
+    async def delete_user(
         self,
         user_uid: str,
-        primary_usertype: str,
-        organizations_uids: Optional[Set[str]] = None,
-        secondary_usertypes: Optional[List[str]] = None,
-        initial_subscription_plan_id: Optional[str] = None,
-        iam_domain_permissions: Optional[Dict[str, Dict[str, Dict[str, IAMUnitRefAssignment]]]] = None,
-        sbscrptn_based_insight_credits: int = 0,
-        extra_insight_credits: int = 0,
-        voting_credits: int = 0,
-        metadata: Optional[Dict[str, Any]] = None,
-        created_by: Optional[str] = None
-    ) -> UserStatus:
-        """Create a new user status with optional initial subscription"""
-        user_status = await self.user_account_ops.create_userstatus(
+        updater_uid: str,
+        delete_auth_user: bool = True,
+        delete_profile: bool = True,
+        delete_status: bool = True,
+        archive: bool = True
+    ) -> Dict[str, Any]:
+        """
+        Delete a user holistically, including their auth, profile, and status.
+
+        Delegates to UsermultistepOperations for the actual deletion.
+        """
+        return await self.usermultistep_ops.delete_user(
             user_uid=user_uid,
-            primary_usertype=primary_usertype,
-            organizations_uids=organizations_uids,
-            secondary_usertypes=secondary_usertypes,
-            iam_domain_permissions=iam_domain_permissions,
-            sbscrptn_based_insight_credits=sbscrptn_based_insight_credits,
-            extra_insight_credits=extra_insight_credits,
-            voting_credits=voting_credits,
-            metadata=metadata,
-            created_by=created_by
+            delete_auth_user=delete_auth_user,
+            delete_profile=delete_profile,
+            delete_status=delete_status,
+            updater_uid=updater_uid,
+            archive=archive
         )
 
-        # Apply initial subscription if provided
-        if initial_subscription_plan_id:
-            try:
-                await self.subscription_ops.apply_subscription_plan(
-                    user_uid=user_uid,
-                    plan_id=initial_subscription_plan_id,
-                    source=f"initial_setup_by_{created_by or 'system'}"
-                )
-                # Fetch updated status with subscription
-                updated_status = await self.get_userstatus(user_uid)
-                return updated_status or user_status
-            except Exception as e:
-                self.logger.error(f"Failed to apply initial subscription plan {initial_subscription_plan_id} for {user_uid}: {e}")
-                # Return the status without subscription rather than failing completely
-
-        return user_status
-
-    async def update_userprofile(self, user_uid: str, profile_data: Dict[str, Any], updater_uid: str) -> UserProfile:
-        """Update a user profile"""
-        return await self.user_account_ops.update_userprofile(user_uid, profile_data, updater_uid)
-
-    async def update_userstatus(self, user_uid: str, status_data: Dict[str, Any], updater_uid: str) -> UserStatus:
-        """Update a user status"""
-        return await self.user_account_ops.update_userstatus(user_uid, status_data, updater_uid)
-
-    ##########################################################################################
-    ################################ Hollistic User Creation #################################
-
-    async def create_user(
+    async def batch_delete_users(
         self,
-        email: str,
-        provider_id: str,
-        primary_usertype_name: str,
-        initial_subscription_plan_id: Optional[str] = None,
-        organizations_uids: Optional[Set[str]] = None,
-        secondary_usertype_names: Optional[List[str]] = None,
-        profile_custom_data: Optional[Dict[str, Any]] = None,
-        status_custom_data: Optional[Dict[str, Any]] = None,
-        created_by: Optional[str] = None,
-        use_firestore_defaults: bool = True,
-        password: Optional[str] = None,
-        email_verified: bool = False,
-        disabled: bool = False
-    ) -> Tuple[Optional[UserProfile], Optional[UserStatus], Optional[str]]:
+        user_uids: List[str],
+        updater_uid: str,
+        delete_auth_user: bool,
+        delete_profile: bool = True,
+        delete_status: bool = True,
+        archive: bool = True
+    ) -> Dict[str, Dict[str, Any]]:
         """
-        Create a complete user with Firebase Auth, UserProfile, and UserStatus
-
-        This method creates the complete user including Firebase Auth user with custom claims.
-        It delegates to UserHolisticOperations for coordinated user creation.
+        Batch delete multiple users holistically.
 
-        Returns:
-            Tuple of (UserProfile, UserStatus, error_message)
-            If successful, error_message is None
-            If failed, one or both models may be None with error_message describing the failure
+        Delegates to UsermultistepOperations for the actual deletion.
         """
-        self.logger.info(f"Starting complete user creation for Email: {email}, Type: {primary_usertype_name}")
-        effective_creator = created_by or f"UserCoreService.create_user:email_{email}"
-
-        # Fetch user type defaults if enabled
-        usertype_defaults: Dict[str, Any] = {}
-        if use_firestore_defaults:
-            fetched_defaults = await self.fetch_user_defaults(primary_usertype_name)
-            if fetched_defaults:
-                usertype_defaults = fetched_defaults
-            else:
-                #### TODO  : FIX HOW ERRORS ARE ACTUALLY REPORTED. SERVICEMON ?
-                self.logger.error(f"User defaults not found for '{primary_usertype_name}', proceeding with empty defaults")
-                raise UserCreationError(f"User defaults not found for '{primary_usertype_name}'")
-
-        # Prepare data with defaults
-        final_secondary_usertypes = secondary_usertype_names or usertype_defaults.get('default_secondary_usertypes', [])
-        final_organizations_uids = organizations_uids or set(usertype_defaults.get('default_organizations_uids', []))
-
-        # Extract custom data fields
-        iam_domain_permissions = (status_custom_data or {}).get('iam_domain_permissions')
-        if iam_domain_permissions is None and use_firestore_defaults:
-            iam_domain_permissions = usertype_defaults.get('default_iam_domain_permissions', {})
-
-        effective_initial_plan_id = initial_subscription_plan_id
-        if effective_initial_plan_id is None and use_firestore_defaults:
-            effective_initial_plan_id = usertype_defaults.get('default_subscription_plan_id')
-
-        # Credits from defaults or custom data
-        default_sbscrptn_credits = usertype_defaults.get('default_subscription_based_insight_credits', 0) if use_firestore_defaults else 0
-        default_extra_credits = usertype_defaults.get('default_extra_insight_credits', 0) if use_firestore_defaults else 0
-        default_voting_credits = usertype_defaults.get('default_voting_credits', 0) if use_firestore_defaults else 0
-
-        sbscrptn_based_insight_credits = (status_custom_data or {}).get('sbscrptn_based_insight_credits', default_sbscrptn_credits)
-        extra_insight_credits = (status_custom_data or {}).get('extra_insight_credits', default_extra_credits)
-        voting_credits = (status_custom_data or {}).get('voting_credits', default_voting_credits)
-        metadata = (status_custom_data or {}).get('metadata', {})
-
-        # Extract profile fields from profile_custom_data
-        first_name = (profile_custom_data or {}).get('first_name')
-        last_name = (profile_custom_data or {}).get('last_name')
-        username = (profile_custom_data or {}).get('username')
-        mobile = (profile_custom_data or {}).get('mobile')
-
-        try:
-            # Delegate to UserHolisticOperations for complete user creation
-            created_user_uid, created_profile, created_status = await self.user_holistic_ops.create_user(
-                email=email,
-                primary_usertype=primary_usertype_name,
-                password=password,
-                organizations_uids=final_organizations_uids,
-                secondary_usertypes=final_secondary_usertypes,
-                first_name=first_name,
-                last_name=last_name,
-                username=username,
-                mobile=mobile,
-                provider_id=provider_id,
-                email_verified=email_verified,
-                disabled=disabled,
-                initial_subscription_plan_id=effective_initial_plan_id,
-                iam_domain_permissions=iam_domain_permissions,
-                sbscrptn_based_insight_credits=sbscrptn_based_insight_credits,
-                extra_insight_credits=extra_insight_credits,
-                voting_credits=voting_credits,
-                metadata=metadata,
-                created_by=effective_creator,
-                set_custom_claims=True  # Always set custom claims for complete user creation
-            )
-
-            self.logger.info(f"Successfully created complete user {created_user_uid}")
-            return created_profile, created_status, None
-
-        except Exception as e:
-            error_msg = f"Failed to create complete user for email {email}: {str(e)}"
-            self.logger.error(error_msg, exc_info=True)
-            return None, None, error_msg
-
-
-    ##########################################################################################
-    ################################ Subscription Operations #################################
-
-    async def get_user_active_subscription(self, user_uid: str) -> Optional[Subscription]:
-        """Get the user's currently active subscription"""
-        return await self.subscription_ops.get_user_active_subscription(user_uid)
-
-    async def change_user_subscription(self, user_uid: str, new_plan_id: str, source: Optional[str] = None) -> Optional[Subscription]:
-        """Change a user's subscription to a new plan"""
-        return await self.subscription_ops.change_user_subscription(user_uid, new_plan_id, source)
-
-    async def cancel_user_subscription(self, user_uid: str, reason: Optional[str] = None, cancelled_by: Optional[str] = None) -> bool:
-        """Cancel a user's active subscription"""
-        return await self.subscription_ops.cancel_user_subscription(user_uid, reason, cancelled_by)
+        return await self.usermultistep_ops.batch_delete_users(
+            user_uids=user_uids,
+            delete_auth_user=delete_auth_user,
+            delete_profile=delete_profile,
+            delete_status=delete_status,
+            updater_uid=updater_uid,
+            archive=archive
+        )
 
+    ######################################################################
+    ######################### UserAuth Operations ########################
+    ######################################################################
 
-    async def _apply_subscription_plan(self, user_uid: str, plan_id: str, source: str = "system_default_config") -> Subscription:
-        """Apply subscription plan (backward compatibility)"""
-        return await self.subscription_ops.apply_subscription_plan(user_uid, plan_id, source)
+    async def create_userauth(self, userauth: UserAuth) -> str:
+        """Create a Firebase Auth user"""
+        return await self.userauth_ops.create_userauth(user_auth=userauth)
 
-    ##########################################################################################
-    ################################ IAM Operations Operations #################################
+    async def get_userauth(self, user_uid: str, get_model: bool = False) -> Union[UserRecord, UserAuth, None]:
+        """Get Firebase Auth user details"""
+        return await self.userauth_ops.get_userauth(user_uid=user_uid, get_model=get_model)
 
+    async def get_userauth_by_email(self, email: str, get_model: bool = False) -> Union[UserRecord, UserAuth, None]:
+        """Get Firebase Auth user by email"""
+        return await self.userauth_ops.get_userauth_by_email(email=email, get_model=get_model)
 
-    # Deletion Operations (delegated to UserHolisticOperations)
+    async def userauth_exists(self, user_uid: str) -> bool:
+        """Check if Firebase Auth user exists"""
+        return await self.userauth_ops.userauth_exists(user_uid=user_uid)
 
-    async def delete_user_account_docs(
+    async def update_userauth(
         self,
         user_uid: str,
-        deleted_by: str = "system_deletion"
-    ) -> Tuple[bool, bool, Optional[str]]:
-        """Delete user documents (profile and status)"""
-        # Use the new user_holistic_ops for coordinated deletion
-        result = await self.user_holistic_ops.delete_user(
+        email: Optional[str] = None,
+        display_name: Optional[str] = None,
+        password: Optional[str] = None,
+        email_verified: Optional[bool] = None,
+        disabled: Optional[bool] = None
+    ) -> UserRecord:
+        """Update Firebase Auth user"""
+        return await self.userauth_ops.update_userauth(
             user_uid=user_uid,
-            delete_auth_user=False,  # Only delete profile and status
-            delete_profile=True,
-            delete_status=True,
-            deleted_by=deleted_by
-        )
-        return (
-            result["profile_deleted_successfully"],
-            result["status_deleted_successfully"],
-            result["errors"][0] if result["errors"] else None
+            email=email,
+            display_name=display_name,
+            password=password,
+            email_verified=email_verified,
+            disabled=disabled
         )
 
-    async def delete_user_holistically_with_auth(
+    async def delete_userauth(self, user_uid: str, archive: bool = True) -> bool:
+        """Delete Firebase Auth user"""
+        return await self.userauth_ops.delete_userauth(user_uid=user_uid, archive=archive)
+
+    async def set_userauth_custom_claims(self, user_uid: str, custom_claims: Dict[str, Any]) -> bool:
+        """Set custom claims for Firebase Auth user"""
+        return await self.userauth_ops.set_userauth_custom_claims(user_uid=user_uid, custom_claims=custom_claims)
+
+    async def enable_userauth(self, user_uid: str, notes: str = "") -> bool:
+        """Enable Firebase Auth user"""
+        return await self.userauth_ops.enable_userauth(user_uid=user_uid, user_notes=notes)
+
+    async def disable_userauth(self, user_uid: str, notes: str = "") -> bool:
+        """Disable Firebase Auth user"""
+        return await self.userauth_ops.disable_userauth(user_uid=user_uid, user_notes=notes)
+
+    async def revoke_refresh_tokens(self, user_uid: str) -> bool:
+        """Revoke all refresh tokens for a user"""
+        return await self.userauth_ops.revoke_refresh_tokens(user_uid=user_uid)
+
+    async def set_user_approval_status(self, user_uid: str, status: ApprovalStatus, notes: str = "") -> bool:
+        """Set user approval status in custom claims"""
+        return await self.userauth_ops.set_user_approval_status(user_uid=user_uid, approval_status=status, updated_by=notes)
+
+    # Token and Security Operations
+
+    async def create_custom_token(
         self,
         user_uid: str,
-        delete_auth_user: bool = True,
-        deleted_by: str = "system_full_deletion"
+        additional_claims: Optional[Dict[str, Any]] = None
+    ) -> str:
+        """Creates a custom token for a user with optional additional claims"""
+        return await self.userauth_ops.create_custom_token(
+            user_uid=user_uid,
+            additional_claims=additional_claims
+        )
+
+    async def verify_id_token(
+        self,
+        token: str,
+        check_revoked: bool = False
     ) -> Dict[str, Any]:
-        """Complete user deletion including Firebase Auth deletion"""
-        return await self.user_holistic_ops.delete_user(user_uid, delete_auth_user, deleted_by=deleted_by)
+        """Verifies an ID token and returns the token claims"""
+        return await self.userauth_ops.verify_id_token(
+            token=token,
+            check_revoked=check_revoked
+        )
 
-    async def batch_delete_user_account_docs(
+    async def get_user_auth_token(
         self,
-        user_uids: List[str],
-        deleted_by: str = "system_batch_deletion"
-    ) -> Dict[str, Tuple[bool, bool, Optional[str]]]:
-        """Batch delete multiple users' documents"""
-        results_holistic = await self.user_holistic_ops.batch_delete_users(user_uids, delete_auth_user=False, deleted_by=deleted_by)
-
-        # Convert to expected format
-        converted_results = {}
-        for user_uid, result in results_holistic.items():
-            error_msg = result["errors"][0] if result["errors"] else None
-            converted_results[user_uid] = (
-                result["profile_deleted_successfully"],
-                result["status_deleted_successfully"],
-                error_msg
-            )
-
-        return converted_results
-
-    # Utility Methods
-
-    async def get_user_account_docs(self, user_uid: str) -> Tuple[Optional[UserProfile], Optional[UserStatus]]:
-        """Get both user profile and status"""
-        return await self.user_account_ops.get_user_core_docs(user_uid)
-
-    async def user_core_docs_exist(self, user_uid: str) -> Tuple[bool, bool]:
-        """Check if user profile and/or status exist"""
-        return await self.user_account_ops.user_core_docs_exist(user_uid)
-
-    async def validate_user_account_data(
+        email: str,
+        password: str,
+        api_key: str
+    ) -> Optional[str]:
+        """
+        Gets a user authentication token using the Firebase REST API.
+
+        Note: This method requires the Firebase Web API key and should be used
+        for testing or specific admin scenarios. For production authentication,
+        prefer using the Firebase client SDKs.
+        """
+        return await self.userauth_ops.get_user_auth_token(
+            email=email,
+            password=password,
+            api_key=api_key
+        )
+
+    async def generate_password_reset_link(
         self,
-        profile_data: Optional[Dict[str, Any]] = None,
-        status_data: Optional[Dict[str, Any]] = None
-    ) -> Tuple[bool, List[str]]:
-        """Validate user profile and status data without creating documents"""
-        return await self.user_account_ops.validate_user_core_data(profile_data, status_data)
+        email: str,
+        action_code_settings: Optional[Dict[str, Any]] = None
+    ) -> str:
+        """Generates a password reset link for a user"""
+        return await self.userauth_ops.generate_password_reset_link(
+            email=email,
+            action_code_settings=action_code_settings
+        )
 
-    # Enhanced Methods for Advanced Operations
+    async def generate_email_verification_link(
+        self,
+        email: str,
+        action_code_settings: Optional[Dict[str, Any]] = None
+    ) -> str:
+        """Generates an email verification link for a user"""
+        return await self.userauth_ops.generate_email_verification_link(
+            email=email,
+            action_code_settings=action_code_settings
+        )
+
+    ######################################################################
+    ######################### UserProfile Operations ####################
+    ######################################################################
+
+    async def create_userprofile(self, userprofile: UserProfile, creator_uid: Optional[str] = None) -> UserProfile:
+        """Create a UserProfile document"""
+        return await self.userprofile_ops.create_userprofile(userprofile=userprofile, creator_uid=creator_uid)
+
+    async def get_userprofile(self, user_uid: str) -> Optional[UserProfile]:
+        """Get a UserProfile by user UID"""
+        return await self.userprofile_ops.get_userprofile(user_uid=user_uid)
+
+    async def update_userprofile(self, user_uid: str, updates: Dict[str, Any], updater_uid: str) -> UserProfile:
+        """Update a UserProfile"""
+        return await self.userprofile_ops.update_userprofile(user_uid=user_uid, profile_data=updates, updater_uid=updater_uid)
+
+    async def delete_userprofile(self, user_uid: str, updater_uid: str, archive: bool = True) -> bool:
+        """Delete a UserProfile"""
+        return await self.userprofile_ops.delete_userprofile(user_uid=user_uid, updater_uid=updater_uid, archive=archive)
+
+    async def userprofile_exists(self, user_uid: str) -> bool:
+        """Check if a UserProfile exists"""
+        return await self.userprofile_ops.userprofile_exists(user_uid=user_uid)
 
-    async def get_users_by_usertype(
+    async def validate_userprofile_data(
         self,
-        primary_usertype: str,
-        limit: Optional[int] = None
-    ) -> List[UserProfile]:
-        """Get users by primary usertype (requires custom implementation)"""
-        # This would require a more advanced query system
-        # For now, we'll raise NotImplementedError to indicate this needs custom implementation
-        raise NotImplementedError("get_users_by_usertype requires custom query implementation")
-
-    async def get_users_by_organization(
+        profile_data: Optional[Dict[str, Any]] = None
+    ) -> tuple[bool, list[str]]:
+        """Validate UserProfile data"""
+        return await self.userprofile_ops.validate_userprofile_data(profile_data=profile_data)
+
+    ######################################################################
+    ######################### UserStatus Operations ######################
+    ######################################################################
+
+    async def create_userstatus(self, userstatus: UserStatus, creator_uid: Optional[str] = None) -> UserStatus:
+        """Create a UserStatus document"""
+        return await self.userstatus_ops.create_userstatus(userstatus=userstatus, creator_uid=creator_uid)
+
+    async def get_userstatus(self, user_uid: str) -> Optional[UserStatus]:
+        """Get a UserStatus by user UID"""
+        return await self.userstatus_ops.get_userstatus(user_uid=user_uid)
+
+    async def update_userstatus(self, user_uid: str, updates: Dict[str, Any], updater_uid: str) -> UserStatus:
+        """Update a UserStatus"""
+        return await self.userstatus_ops.update_userstatus(user_uid=user_uid, status_data=updates, updater_uid=updater_uid)
+
+    async def delete_userstatus(self, user_uid: str, updater_uid: str, archive: bool = True) -> bool:
+        """Delete a UserStatus"""
+        return await self.userstatus_ops.delete_userstatus(user_uid=user_uid, updater_uid=updater_uid, archive=archive)
+
+    async def userstatus_exists(self, user_uid: str) -> bool:
+        """Check if a UserStatus exists"""
+        return await self.userstatus_ops.userstatus_exists(user_uid=user_uid)
+
+    async def validate_userstatus_data(
         self,
-        organization_uid: str,
-        limit: Optional[int] = None
-    ) -> List[UserProfile]:
-        """Get users by organization (requires custom implementation)"""
-        # This would require a more advanced query system
-        raise NotImplementedError("get_users_by_organization requires custom query implementation")
-
-    async def bulk_update_user_permissions(
+        status_data: Optional[Dict[str, Any]] = None
+    ) -> tuple[bool, list[str]]:
+        """Validate UserStatus data"""
+        return await self.userstatus_ops.validate_userstatus_data(status_data=status_data)
+
+    async def validate_and_cleanup_user_permissions(
         self,
-        user_uids: List[str],
-        domain: str,
-        permissions_to_add: List[str],
-        permissions_to_remove: List[str],
+        user_uid: str,
         updater_uid: str
-    ) -> Dict[str, bool]:
-        """Bulk update permissions for multiple users"""
-        results = {}
-
-        for user_uid in user_uids:
-            try:
-                # Add permissions
-                for permission in permissions_to_add:
-                    await self.iam_ops.add_user_permission(
-                        user_uid=user_uid,
-                        domain=domain,
-                        permission_name=permission,
-                        iam_unit_type=IAMUnitType.GROUPS,  # Default to groups
-                        source=f"bulk_update_by_{updater_uid}",
-                        updater_uid=updater_uid
-                    )
-
-                # Remove permissions
-                for permission in permissions_to_remove:
-                    await self.iam_ops.remove_user_permission(
-                        user_uid=user_uid,
-                        domain=domain,
-                        permission_name=permission,
-                        iam_unit_type=IAMUnitType.GROUPS,  # Default to groups
-                        updater_uid=updater_uid
-                    )
-
-                results[user_uid] = True
-
-            except Exception as e:
-                self.logger.error(f"Failed to update permissions for user {user_uid}: {e}")
-                results[user_uid] = False
-
-        return results
-
-    # Statistics and Analytics Methods
-
-    async def get_user_statistics(self) -> Dict[str, int]:
-        """Get basic user statistics (requires custom implementation)"""
-        # This would require aggregation queries
-        raise NotImplementedError("get_user_statistics requires custom aggregation implementation")
-
-    async def get_subscription_statistics(self) -> Dict[str, int]:
-        """Get subscription statistics (requires custom implementation)"""
-        # This would require aggregation queries
-        raise NotImplementedError("get_subscription_statistics requires custom aggregation implementation")
-
-    # User 360 Operations (Complete User Lifecycle)
-
-    async def create_complete_user_with_auth(
-        self,
-        email: str,
-        primary_usertype: str,
-        password: Optional[str] = None,
-        organizations_uids: Optional[Set[str]] = None,
-        secondary_usertypes: Optional[List[str]] = None,
-        first_name: Optional[str] = None,
-        last_name: Optional[str] = None,
-        username: Optional[str] = None,
-        mobile: Optional[str] = None,
-        provider_id: str = "password",
-        email_verified: bool = False,
-        disabled: bool = False,
-        initial_subscription_plan_id: Optional[str] = None,
-        iam_domain_permissions: Optional[Dict[str, Dict[str, Dict[str, IAMUnitRefAssignment]]]] = None,
-        sbscrptn_based_insight_credits: int = 0,
-        extra_insight_credits: int = 0,
-        voting_credits: int = 0,
-        metadata: Optional[Dict[str, Any]] = None,
-        created_by: Optional[str] = None,
-        set_custom_claims: bool = True
-    ) -> Tuple[str, UserProfile, UserStatus]:
-        """
-        Create complete user with Firebase Auth, UserProfile, and UserStatus
+    ) -> int:
+        """Validate and cleanup expired permissions for a user"""
+        return await self.userstatus_ops.validate_and_cleanup_user_permissions(user_uid=user_uid, updater_uid=updater_uid)
 
-        This method directly delegates to UserHolisticOperations.create_user
-        """
-        return await self.user_holistic_ops.create_user(
-            email=email,
-            primary_usertype=primary_usertype,
-            password=password,
-            organizations_uids=organizations_uids,
-            secondary_usertypes=secondary_usertypes,
-            first_name=first_name,
-            last_name=last_name,
-            username=username,
-            mobile=mobile,
-            provider_id=provider_id,
-            email_verified=email_verified,
-            disabled=disabled,
-            initial_subscription_plan_id=initial_subscription_plan_id,
-            iam_domain_permissions=iam_domain_permissions,
-            sbscrptn_based_insight_credits=sbscrptn_based_insight_credits,
-            extra_insight_credits=extra_insight_credits,
-            voting_credits=voting_credits,
-            metadata=metadata,
-            created_by=created_by,
-            set_custom_claims=set_custom_claims
+    ######################################################################
+    ######################### Subscription Operations ###################
+    ######################################################################
+
+    async def fetch_subscriptionplan_and_apply_subscription_to_user(
+        self,
+        user_uid: str,
+        plan_id: str,
+        updater_uid: str,
+        source: str = "user_core_service",
+        granted_at: Optional[datetime] = None,
+        auto_renewal_end: Optional[datetime] = None
+    ) -> UserSubscription:
+        """Fetch a subscription plan from catalog and apply to user"""
+        return await self.subscription_ops.fetch_subscriptionplan_and_apply_subscription_to_user(
+            user_uid=user_uid,
+            plan_id=plan_id,
+            updater_uid=updater_uid,
+            source=source,
+            granted_at=granted_at,
+            auto_renewal_end=auto_renewal_end
         )
 
-    async def delete_complete_user(
+    async def apply_subscriptionplan_to_user(
         self,
         user_uid: str,
-        delete_auth_user: bool = True,
-        delete_profile: bool = True,
-        delete_status: bool = True,
-        deleted_by: str = "system_complete_deletion"
-    ) -> Dict[str, Any]:
-        """Delete complete user including Firebase Auth, UserProfile, and UserStatus"""
-        return await self.user_holistic_ops.delete_user(
+        subscriptionplan: SubscriptionPlan,
+        updater_uid: str,
+        source: str = "user_core_service",
+        granted_at: Optional[datetime] = None,
+        auto_renewal_end: Optional[datetime] = None
+    ) -> UserSubscription:
+        """Apply a subscription plan directly to user (plan already fetched)"""
+        return await self.subscription_ops.apply_subscriptionplan(
             user_uid=user_uid,
-            delete_auth_user=delete_auth_user,
-            delete_profile=delete_profile,
-            delete_status=delete_status,
-            deleted_by=deleted_by
+            subscriptionplan=subscriptionplan,
+            updater_uid=updater_uid,
+            source=source,
+            granted_at=granted_at,
+            auto_renewal_end=auto_renewal_end
         )
 
-    async def user_exists_complete(self, user_uid: str) -> Dict[str, bool]:
-        """Check if complete user exists (Auth, Profile, Status)"""
-        return await self.user_holistic_ops.user_exists_fully(user_uid)
+    async def cancel_user_subscription(self, user_uid: str, updater_uid: str) -> bool:
+        """Cancel a user's active subscription"""
+        return await self.subscription_ops.cancel_user_subscription(user_uid=user_uid, updater_uid=updater_uid)
 
-    async def validate_complete_user(self, user_uid: str) -> Dict[str, Any]:
-        """Validate complete user integrity"""
-        return await self.user_holistic_ops.validate_user_full_existance(user_uid)
+    async def get_user_active_subscription(self, user_uid: str) -> Optional[UserSubscription]:
+        """Get a user's active subscription"""
+        return await self.subscription_ops.get_user_active_subscription(user_uid=user_uid)
 
-    # User Auth Operations
+    async def update_user_subscription(
+        self,
+        user_uid: str,
+        subscription_data: Dict[str, Any],
+        updater_uid: str
+    ) -> Optional[UserSubscription]:
+        """Update a user's subscription"""
+        return await self.subscription_ops.update_user_subscription(user_uid=user_uid, subscription_updates=subscription_data, updater_uid=updater_uid)
 
-    async def create_userauth(
+    async def downgrade_user_subscription_to_fallback_subscriptionplan(
         self,
-        email: str,
-        password: Optional[str] = None,
-        email_verified: bool = False,
-        disabled: bool = False,
-        display_name: Optional[str] = None,
-        phone_number: Optional[str] = None,
-        custom_claims: Optional[Dict[str, Any]] = None
-    ) -> str:
-        """Create Firebase Auth user"""
-        user_auth = UserAuth(
-            email=email,
-            password=password,
-            email_verified=email_verified,
-            disabled=disabled,
-            phone_number=phone_number,
-            custom_claims=custom_claims
+        user_uid: str,
+        reason: str = "subscription_expired"
+    ) -> Optional[UserSubscription]:
+        """Downgrade user subscription to fallback plan"""
+        return await self.subscription_ops.downgrade_user_subscription_to_fallback_subscriptionplan(
+            user_uid=user_uid, reason=reason
         )
-        return await self.user_auth_ops.create_userauth(user_auth)
 
-    async def delete_userauth(self, user_uid: str) -> bool:
-        """Delete Firebase Auth user"""
-        return await self.user_auth_ops.delete_userauth(user_uid)
+    ######################################################################
+    ######################### IAM/Permissions Operations ################
+    ######################################################################
 
-    async def userauth_exists(self, user_uid: str) -> bool:
-        """Check if Firebase Auth user exists"""
-        return await self.user_auth_ops.userauth_exists(user_uid)
+    async def add_permission_to_user(
+        self,
+        user_uid: str,
+        permission: UserPermission,
+        updater_uid: str
+    ) -> bool:
+        """Add a permission to a user (returns success boolean)"""
+        return await self.iam_ops.add_permission_to_user(user_uid=user_uid, permission=permission, updater_uid=updater_uid)
+
+    async def get_permissions_of_user(self, user_uid: str) -> List[UserPermission]:
+        """Get a user's permissions"""
+        return await self.iam_ops.get_permissions_of_user(user_uid=user_uid)
 
-    # Custom Claims Operations (delegated to user_auth_ops)
+    async def remove_all_permissions_from_user(self, user_uid: str, updater_uid: str, source: Optional[str] = None) -> int:
+        """Remove all permissions from a user"""
+        return await self.iam_ops.remove_all_permissions_from_user(user_uid=user_uid, source=source, updater_uid=updater_uid)
 
-    async def set_userauth_custom_claims(
+    async def remove_permission_from_user(
         self,
         user_uid: str,
-        custom_claims: Dict[str, Any],
-        merge_with_existing: bool = False
+        domain: Optional[str] = None,
+        permission_type: Optional[IAMUnit] = None,
+        permission_name: Optional[str] = None,
+        source: Optional[str] = None,
+        updater_uid: Optional[str] = None
     ) -> bool:
-        """Set Firebase Auth custom claims for a user with optional merging"""
-        return await self.user_auth_ops.set_userauth_custom_claims(user_uid, custom_claims, merge_with_existing)
+        """Remove specific permission(s) from a user based on filter criteria"""
+        return await self.iam_ops.remove_permission_from_user(
+            user_uid=user_uid,
+            domain=domain,
+            permission_type=permission_type,
+            permission_name=permission_name,
+            source=source,
+            updater_uid=updater_uid
+        )
+
+    async def cleanup_expired_permissions_of_user(
+        self,
+        user_uid: str,
+        updater_uid: str,
+        iam_unit_type: Optional[IAMUnit] = None
+    ) -> int:
+        """Remove expired permissions from a user"""
+        return await self.iam_ops.cleanup_expired_permissions_of_user(user_uid=user_uid, iam_unit_type=iam_unit_type, updater_uid=updater_uid)
+
+    async def get_bulk_users_with_permission(
+        self,
+        domain: str,
+        iam_unit_type: IAMUnit,
+        permission_ref: str,
+        limit: int = 100,
+        valid_only: bool = True
+    ) -> List[str]:
+        """Get bulk users who have a specific permission"""
+        return await self.iam_ops.get_bulk_users_with_permission(
+            domain=domain,
+            iam_unit_type=iam_unit_type,
+            permission_ref=permission_ref,
+            limit=limit,
+            valid_only=valid_only
+        )
+
+    async def update_user_usertype(
+        self,
+        user_uid: str,
+        primary_usertype: Optional['IAMUserType'] = None,
+        secondary_usertypes: Optional[List['IAMUserType']] = None,
+        updater_uid: str = "system_usertype_update"
+    ) -> Tuple[UserProfile, Dict[str, Any]]:
+        """
+        Update user's primary and/or secondary usertypes efficiently across UserProfile and Firebase Auth.
+
+        Args:
+            user_uid: The UID of the user to update
+            primary_usertype: New primary usertype (optional, keeps existing if None)
+            secondary_usertypes: New secondary usertypes list (optional, keeps existing if None)
+            updater_uid: Who is performing this update
+
+        Returns:
+            Tuple of (updated_userprofile, updated_custom_claims)
+        """
+        return await self.usermultistep_ops.update_user_usertype(
+            user_uid=user_uid,
+            primary_usertype=primary_usertype,
+            secondary_usertypes=secondary_usertypes,
+            updater_uid=updater_uid
+        )
+
+    ######################################################################
+    ####################### User Subscription/Status Review #############
+    ######################################################################
+
+    async def review_and_clean_active_subscription_credits_and_permissions(
+        self,
+        user_uid: str,
+        updater_uid: str = "system_review",
+        review_auto_renewal: bool = True,
+        apply_fallback: bool = True,
+        clean_expired_permissions: bool = True,
+        review_credits: bool = True
+    ) -> Dict[str, Any]:
+        """
+        Orchestrate a comprehensive review and cleanup of a user's active subscription, credits, and permissions.
+        Delegates to UserstatusOperations for the actual logic.
+        """
+        return await self.userstatus_ops.review_and_clean_active_subscription_credits_and_permissions(
+            user_uid=user_uid,
+            updater_uid=updater_uid,
+            review_auto_renewal=review_auto_renewal,
+            apply_fallback=apply_fallback,
+            clean_expired_permissions=clean_expired_permissions,
+            review_credits=review_credits
+        )
+