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

ipulse_shared_core_ftredge/services/base/base_firestore_service.py

@@ -7,7 +7,7 @@ This provides the foundation for all Firestore-based services.
 
 import json
 import logging
-from datetime import datetime, timezone
+from datetime import datetime, timezone, date
 from typing import Any, AsyncGenerator, Dict, Generic, List, Optional, TypeVar, Type, Union
 
 from google.cloud import firestore
@@ -20,6 +20,32 @@ from ...exceptions import ResourceNotFoundError, ServiceError, ValidationError a
 T = TypeVar('T', bound=BaseModel)
 
 
+def _sanitize_firestore_data(data: Any) -> Any:
+    """
+    Recursively sanitize data before sending to Firestore.
+    Converts datetime.date objects to datetime.datetime objects since Firestore
+    only supports datetime.datetime, not datetime.date.
+    """
+    if isinstance(data, date) and not isinstance(data, datetime):
+        # Convert date to datetime (start of day in UTC)
+        return datetime.combine(data, datetime.min.time()).replace(tzinfo=timezone.utc)
+
+    if isinstance(data, BaseModel):
+        # Convert Pydantic model to dict and sanitize recursively
+        return _sanitize_firestore_data(data.model_dump())
+
+    if isinstance(data, dict):
+        # Recurse into dictionaries
+        return {k: _sanitize_firestore_data(v) for k, v in data.items()}
+
+    if isinstance(data, list):
+        # Recurse into lists
+        return [_sanitize_firestore_data(item) for item in data]
+
+    # Return everything else as-is (str, int, float, bool, datetime, etc.)
+    return data
+
+
 class BaseFirestoreService(Generic[T]):
     """
     Base service class for Firestore operations using Pydantic models
@@ -95,7 +121,7 @@ class BaseFirestoreService(Generic[T]):
                 additional_info={"validation_errors": e.errors()}
             )
 
-    async def get_document(self, doc_id: str, convert_to_model: bool = True) -> Union[Dict[str, Any], None]:
+    async def get_document(self, doc_id: str, convert_to_model: bool = True) -> Union[T, Dict[str, Any]]:
         """
         Get a document by ID
 
@@ -104,7 +130,7 @@ class BaseFirestoreService(Generic[T]):
             convert_to_model: Whether to convert to Pydantic model
 
         Returns:
-            Document as dict, or None if not found
+            Document as a model instance or dict.
 
         Raises:
             ResourceNotFoundError: If document doesn't exist
@@ -121,7 +147,21 @@ class BaseFirestoreService(Generic[T]):
                 )
 
             doc_dict = doc.to_dict()
-            return doc_dict
+            if not doc_dict:
+                # This case should ideally not be reached if doc.exists is true,
+                # but as a safeguard:
+                raise ServiceError(
+                    operation="get_document",
+                    error=ValueError("Document exists but data is empty."),
+                    resource_type=self.resource_type,
+                    resource_id=doc_id
+                )
+
+            if convert_to_model and self.model_class:
+                return self._convert_to_model(doc_dict, doc_id)
+            else:
+                doc_dict['id'] = doc_id
+                return doc_dict
 
         except ResourceNotFoundError:
             raise
@@ -162,6 +202,9 @@ class BaseFirestoreService(Generic[T]):
             else:
                 doc_dict = data.copy()
 
+            # Sanitize data for Firestore (convert date objects to datetime)
+            doc_dict = _sanitize_firestore_data(doc_dict)
+
             # Ensure ID is set correctly
             doc_dict['id'] = doc_id
 
@@ -234,6 +277,10 @@ class BaseFirestoreService(Generic[T]):
 
             # Add update timestamp and user
             updates = update_data.copy()
+
+            # Sanitize data for Firestore (convert date objects to datetime)
+            updates = _sanitize_firestore_data(updates)
+
             updates['updated_at'] = datetime.now(timezone.utc)
             updates['updated_by'] = updater_uid
 
@@ -310,7 +357,7 @@ class BaseFirestoreService(Generic[T]):
         """
         try:
             doc_ref = self._get_collection().document(doc_id)
-            doc = await doc_ref.get()
+            doc = doc_ref.get()  # Remove await - this is synchronous
             return doc.exists
         except Exception as e:
             raise ServiceError(
@@ -325,8 +372,10 @@ class BaseFirestoreService(Generic[T]):
         limit: Optional[int] = None,
         start_after: Optional[str] = None,
         order_by: Optional[str] = None,
-        filters: Optional[List[FieldFilter]] = None
-    ) -> List[T]:
+        order_direction: str = firestore.Query.ASCENDING,
+        filters: Optional[List[tuple]] = None,
+        as_models: bool = True
+    ) -> Union[List[T], List[Dict[str, Any]]]:
         """
         List documents with optional filtering and pagination
 
@@ -334,10 +383,12 @@ 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:
-            List of documents as model instances
+            List of documents as model instances or dicts
 
         Raises:
             ServiceError: If an error occurs during listing
@@ -348,11 +399,12 @@ class BaseFirestoreService(Generic[T]):
             # Apply filters
             if filters:
                 for filter_condition in filters:
-                    query = query.where(filter=filter_condition)
+                    field, operator, value = filter_condition
+                    query = query.where(field, operator, value)
 
             # 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:
@@ -373,7 +425,7 @@ class BaseFirestoreService(Generic[T]):
                 if doc_dict is None:
                     continue  # Skip documents that don't exist
 
-                if self.model_class:
+                if as_models and self.model_class:
                     model_instance = self._convert_to_model(doc_dict, doc.id)
                     results.append(model_instance)
                 else:
@@ -412,20 +464,27 @@ class BaseFirestoreService(Generic[T]):
             ServiceError: If an error occurs during archival
         """
         try:
+            # Generate unique archive document ID to handle duplicates
+            archive_timestamp = datetime.now(timezone.utc)
+            timestamp_str = archive_timestamp.strftime("%Y%m%d_%H%M%S_%f")[:-3]  # microseconds to milliseconds
+            unique_archive_doc_id = f"{doc_id}_{timestamp_str}"
+
             # Add archival metadata
             archive_data = document_data.copy()
             archive_data.update({
-                "archived_at": datetime.now(timezone.utc),
+                "archived_at": archive_timestamp,
                 "archived_by": archived_by,
+                "updated_at": archive_timestamp,
+                "updated_by": archived_by,
                 "original_collection": self.collection_name,
                 "original_doc_id": doc_id
             })
 
-            # Store in archive collection
-            archive_ref = self.db.collection(archive_collection).document(doc_id)
+            # Store in archive collection with unique ID
+            archive_ref = self.db.collection(archive_collection).document(unique_archive_doc_id)
             archive_ref.set(archive_data, timeout=self.timeout)
 
-            self.logger.info(f"Successfully archived {self.resource_type} {doc_id} to {archive_collection}")
+            self.logger.info(f"Successfully archived {self.resource_type} {doc_id} to {archive_collection} as {unique_archive_doc_id}")
             return True
 
         except Exception as e:
@@ -518,3 +577,5 @@ class BaseFirestoreService(Generic[T]):
                 resource_type=self.resource_type,
                 resource_id=doc_id
             )
+
+

ipulse_shared_core_ftredge/services/{cache_aware_firestore_service.py → base/cache_aware_firestore_service.py}

@@ -1,11 +1,11 @@
 """Cache-aware Firestore service base class."""
 import time
-from typing import TypeVar, Generic, Dict, Any, List, Optional
+from typing import TypeVar, Generic, Dict, Any, List, Optional, Union, Type
 from google.cloud import firestore
-from .base import BaseFirestoreService
-from ..exceptions import ResourceNotFoundError, ServiceError
-from ..cache.shared_cache import SharedCache
-from ..models import BaseDataModel
+from . import BaseFirestoreService
+from ...exceptions import ResourceNotFoundError, ServiceError
+from ...cache.shared_cache import SharedCache
+from ...models import BaseDataModel
 
 T = TypeVar('T', bound=BaseDataModel)
 
@@ -20,12 +20,13 @@ class CacheAwareFirestoreService(BaseFirestoreService[T], Generic[T]):
         db: firestore.Client,
         collection_name: str,
         resource_type: str,
-        logger,
+        model_class: Optional[Type[T]] = None,
+        logger=None,
         document_cache: Optional[SharedCache] = None,
         collection_cache: Optional[SharedCache] = None,
         timeout: float = 30.0
     ):
-        super().__init__(db, collection_name, resource_type, logger)
+        super().__init__(db, collection_name, resource_type, model_class, logger, timeout)
         self.document_cache = document_cache
         self.collection_cache = collection_cache
         self.timeout = timeout
@@ -36,15 +37,16 @@ class CacheAwareFirestoreService(BaseFirestoreService[T], Generic[T]):
         if self.collection_cache:
             self.logger.info(f"Collection cache enabled for {resource_type}: {self.collection_cache.name}")
 
-    async def get_document(self, doc_id: str) -> Dict[str, Any]:
+    async def get_document(self, doc_id: str, convert_to_model: bool = True) -> Union[T, Dict[str, Any]]:
         """
         Get a document with caching support.
 
         Args:
             doc_id: Document ID to fetch
+            convert_to_model: Whether to convert to Pydantic model
 
         Returns:
-            Document data as dictionary
+            Document as model instance or dictionary
 
         Raises:
             ResourceNotFoundError: If document doesn't exist
@@ -57,35 +59,29 @@ class CacheAwareFirestoreService(BaseFirestoreService[T], Generic[T]):
 
             if cached_doc is not None:
                 self.logger.debug(f"Cache HIT for document {doc_id} in {cache_check_time:.2f}ms")
-                return cached_doc
+                if convert_to_model and self.model_class:
+                    return self._convert_to_model(cached_doc, doc_id)
+                else:
+                    cached_doc['id'] = doc_id
+                    return cached_doc
             else:
                 self.logger.debug(f"Cache MISS for document {doc_id} - checking Firestore")
 
-        # Fetch from Firestore
-        start_time = time.time()
-        doc_ref = self.db.collection(self.collection_name).document(doc_id)
-        doc = doc_ref.get(timeout=self.timeout)
-        firestore_time = (time.time() - start_time) * 1000
-
-        if not doc.exists:
-            self.logger.info(f"Document {doc_id} not found in Firestore after {firestore_time:.2f}ms")
-            raise ResourceNotFoundError(self.resource_type, doc_id)
-
-        doc_data = doc.to_dict()
-        self.logger.debug(f"Fetched document {doc_id} from Firestore in {firestore_time:.2f}ms")
-
-        # Cache the result
-        if self.document_cache and doc_data:
-            self.document_cache.set(doc_id, doc_data)
-            self.logger.debug(f"Cached document {doc_id}")
+        # Fetch from Firestore using parent method
+        return await super().get_document(doc_id, convert_to_model)
 
-        return doc_data
-
-    async def get_all_documents(self, cache_key: Optional[str] = None) -> List[Dict[str, Any]]:
+    async def get_all_documents(self, cache_key: Optional[str] = None, as_models: bool = True) -> Union[List[T], List[Dict[str, Any]]]:
         """
         Retrieves all documents from the collection.
         Uses collection_cache if cache_key is provided and cache is available.
         Also populates document_cache for each retrieved document.
+
+        Args:
+            cache_key: Optional cache key for collection-level caching
+            as_models: Whether to convert documents to Pydantic models
+
+        Returns:
+            List of documents as model instances or dicts
         """
         if cache_key and self.collection_cache:
             cached_collection_data = self.collection_cache.get(cache_key)
@@ -96,6 +92,15 @@ class CacheAwareFirestoreService(BaseFirestoreService[T], Generic[T]):
                     for doc_data in cached_collection_data:
                         if "id" in doc_data and not self.document_cache.get(doc_data["id"]):
                             self._cache_document_data(doc_data["id"], doc_data)
+
+                # Convert to models if requested
+                if as_models and self.model_class:
+                    results = []
+                    for doc_data in cached_collection_data:
+                        if "id" in doc_data:
+                            model_instance = self._convert_to_model(doc_data, doc_data["id"])
+                            results.append(model_instance)
+                    return results
                 return cached_collection_data
             else:
                 self.logger.debug(f"Cache MISS for collection key '{cache_key}' in {self.collection_cache.name} - checking Firestore")
@@ -127,6 +132,15 @@ class CacheAwareFirestoreService(BaseFirestoreService[T], Generic[T]):
                     # _cache_document_data expects 'id' to be in doc_data for keying
                     self._cache_document_data(doc_data["id"], doc_data)
 
+            # Convert to models if requested
+            if as_models and self.model_class:
+                results = []
+                for doc_data in docs_data_list:
+                    if "id" in doc_data:
+                        model_instance = self._convert_to_model(doc_data, doc_data["id"])
+                        results.append(model_instance)
+                return results
+
             return docs_data_list
 
         except Exception as e:
@@ -139,9 +153,9 @@ class CacheAwareFirestoreService(BaseFirestoreService[T], Generic[T]):
             self.document_cache.set(doc_id, data)
             self.logger.debug(f"Cached item {doc_id} in {self.document_cache.name}")
 
-    async def create_document(self, doc_id: str, data: T, creator_uid: str) -> Dict[str, Any]:
+    async def create_document(self, doc_id: str, data: Union[T, Dict[str, Any]], creator_uid: str, merge: bool = False) -> Dict[str, Any]:
         """Create document and invalidate cache."""
-        result = await super().create_document(doc_id, data, creator_uid)
+        result = await super().create_document(doc_id, data, creator_uid, merge)
         self._invalidate_document_cache(doc_id)
         self._invalidate_all_collection_caches()
         return result

ipulse_shared_core_ftredge/services/catalog/__init__.py

@@ -0,0 +1,14 @@
+"""
+Catalog Services Module
+
+This module provides services for managing catalog data including subscription plans
+and user type templates stored in Firestore.
+"""
+
+from .catalog_subscriptionplan_service import CatalogSubscriptionPlanService
+from .catalog_usertype_service import CatalogUserTypeService
+
+__all__ = [
+    "CatalogSubscriptionPlanService",
+    "CatalogUserTypeService",
+]

ipulse_shared_core_ftredge/services/catalog/catalog_subscriptionplan_service.py

@@ -0,0 +1,277 @@
+"""
+Subscription Plan Catalog Service
+
+This service manages subscription plan templates stored in Firestore.
+These templates are used to configure and create user subscriptions consistently.
+"""
+
+import logging
+from typing import Dict, List, Optional, Any
+from google.cloud import firestore
+from google.cloud.firestore import Client
+from ipulse_shared_base_ftredge import SubscriptionPlanName
+from ipulse_shared_base_ftredge.enums.enums_status import ObjectOverallStatus
+from ipulse_shared_core_ftredge.models.catalog.subscriptionplan import SubscriptionPlan
+from ipulse_shared_core_ftredge.services.base.base_firestore_service import BaseFirestoreService
+from ipulse_shared_core_ftredge.exceptions import ServiceError
+
+
+class CatalogSubscriptionPlanService(BaseFirestoreService[SubscriptionPlan]):
+    """
+    Service for managing subscription plan catalog configurations.
+
+    This service provides CRUD operations for subscription plan templates that define
+    the structure and defaults for user subscriptions.
+    """
+
+    def __init__(
+        self,
+        firestore_client: Client,
+        logger: Optional[logging.Logger] = None
+    ):
+        """
+        Initialize the Subscription Plan Catalog Service.
+
+        Args:
+            firestore_client: Firestore client instance
+            logger: Logger instance (optional)
+        """
+        super().__init__(
+            db=firestore_client,
+            collection_name="papp_core_catalog_subscriptionplans",
+            resource_type="subscriptionplan",
+            model_class=SubscriptionPlan,
+            logger=logger or logging.getLogger(__name__)
+        )
+        self.archive_collection_name = "~archive_papp_core_catalog_subscriptionplans"
+
+    async def create_subscriptionplan(
+        self,
+        subscriptionplan_id: str,
+        subscription_plan: SubscriptionPlan,
+        creator_uid: str
+    ) -> SubscriptionPlan:
+        """
+        Create a new subscription plan.
+
+        Args:
+            subscriptionplan_id: Unique identifier for the plan
+            subscription_plan: Subscription plan data
+            creator_uid: UID of the user creating the plan
+
+        Returns:
+            Created subscription plan
+
+        Raises:
+            ServiceError: If creation fails
+            ValidationError: If plan data is invalid
+        """
+        self.logger.info(f"Creating subscription plan: {subscriptionplan_id}")
+
+        # Create the document
+        created_doc = await self.create_document(
+            doc_id=subscriptionplan_id,
+            data=subscription_plan,
+            creator_uid=creator_uid
+        )
+
+        # Convert back to model
+        result = SubscriptionPlan.model_validate(created_doc)
+        self.logger.info(f"Successfully created subscription plan: {subscriptionplan_id}")
+        return result
+
+    async def get_subscriptionplan(self, subscriptionplan_id: str) -> Optional[SubscriptionPlan]:
+        """
+        Retrieve a subscription plan by ID.
+
+        Args:
+            subscriptionplan_id: Unique identifier for the plan
+
+        Returns:
+            Subscription plan if found, None otherwise
+
+        Raises:
+            ServiceError: If retrieval fails
+        """
+        self.logger.debug(f"Retrieving subscription plan: {subscriptionplan_id}")
+        doc_data = await self.get_document(subscriptionplan_id)
+        if doc_data is None:
+            return None
+        return SubscriptionPlan.model_validate(doc_data) if isinstance(doc_data, dict) else doc_data
+
+    async def update_subscriptionplan(
+        self,
+        subscriptionplan_id: str,
+        updates: Dict[str, Any],
+        updater_uid: str
+    ) -> SubscriptionPlan:
+        """
+        Update a subscription plan.
+
+        Args:
+            subscriptionplan_id: Unique identifier for the plan
+            updates: Fields to update
+            updater_uid: UID of the user updating the plan
+
+        Returns:
+            Updated subscription plan
+
+        Raises:
+            ServiceError: If update fails
+            ResourceNotFoundError: If plan not found
+            ValidationError: If update data is invalid
+        """
+        self.logger.info(f"Updating subscription plan: {subscriptionplan_id}")
+
+        updated_doc = await self.update_document(
+            doc_id=subscriptionplan_id,
+            update_data=updates,
+            updater_uid=updater_uid
+        )
+
+        result = SubscriptionPlan.model_validate(updated_doc)
+        self.logger.info(f"Successfully updated subscription plan: {subscriptionplan_id}")
+        return result
+
+    async def delete_subscriptionplan(
+        self,
+        subscriptionplan_id: str,
+        archive: bool = True
+    ) -> bool:
+        """
+        Delete a subscription plan.
+
+        Args:
+            subscriptionplan_id: Unique identifier for the plan
+            archive: Whether to archive the plan before deletion
+
+        Returns:
+            True if deletion was successful
+
+        Raises:
+            ServiceError: If deletion fails
+            ResourceNotFoundError: If plan not found
+        """
+        self.logger.info(f"Deleting subscription plan: {subscriptionplan_id}")
+
+        if archive:
+            # Get the plan data before deletion for archiving
+            template = await self.get_subscriptionplan(subscriptionplan_id)
+            if template:
+                await self.archive_document(
+                    document_data=template.model_dump(),
+                    doc_id=subscriptionplan_id,
+                    archive_collection=self.archive_collection_name,
+                    archived_by="system"
+                )
+
+        result = await self.delete_document(subscriptionplan_id)
+        self.logger.info(f"Successfully deleted subscription plan: {subscriptionplan_id}")
+        return result
+
+    async def list_subscriptionplans(
+        self,
+        plan_name: Optional[SubscriptionPlanName] = None,
+        pulse_status: Optional[ObjectOverallStatus] = None,
+        latest_version_only: bool = False,
+        limit: Optional[int] = None,
+        version_ordering: str = "DESCENDING"
+    ) -> List[SubscriptionPlan]:
+        """
+        List subscription plans with optional filtering.
+
+        Args:
+            plan_name: Filter by specific plan name (FREE, BASE, PREMIUM)
+            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
+
+        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}, version_ordering: {version_ordering}")
+
+        # Build query filters
+        filters = []
+        if plan_name:
+            filters.append(("plan_name", "==", plan_name.value))
+        if pulse_status:
+            filters.append(("pulse_status", "==", pulse_status.value))
+
+        # 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,
+            order_direction=order_direction,
+            limit=query_limit
+        )
+
+        # Convert to SubscriptionPlan models
+        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.")
+
+            plan_groups = {}
+            for plan in plans:
+                key = plan.plan_name.value
+                if key not in plan_groups:
+                    plan_groups[key] = plan  # First one is the latest due to sorting
+
+            return list(plan_groups.values())
+
+        return plans
+
+
+    def _get_collection(self):
+        """Get the Firestore collection reference."""
+        return self.db.collection(self.collection_name)
+
+    async def subscriptionplan_exists(self, subscriptionplan_id: str) -> bool:
+        """
+        Check if a subscription plan exists.
+
+        Args:
+            subscriptionplan_id: Unique identifier for the plan
+
+        Returns:
+            True if plan exists, False otherwise
+
+        Raises:
+            ServiceError: If check fails
+        """
+        return await self.document_exists(subscriptionplan_id)
+
+    async def validate_subscriptionplan_data(self, subscriptionplan_data: Dict[str, Any]) -> tuple[bool, List[str]]:
+        """
+        Validate subscription plan data.
+
+        Args:
+            subscriptionplan_data: Plan data to validate
+
+        Returns:
+            Tuple of (is_valid, list_of_errors)
+        """
+        try:
+            SubscriptionPlan.model_validate(subscriptionplan_data)
+            return True, []
+        except Exception as e:
+            return False, [str(e)]