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

ipulse_shared_core_ftredge/models/base_data_model.py

@@ -1,7 +1,6 @@
 from datetime import datetime, timezone
 from typing import Any
 from typing import ClassVar
-from typing import Optional, Dict
 from pydantic import BaseModel, Field, ConfigDict, field_validator
 import dateutil.parser
 
@@ -21,9 +20,9 @@ class BaseDataModel(BaseModel):
         frozen=True  # Keep schema version frozen for data integrity
     )
 
-    # Audit fields - now mutable for updates
-    created_at: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
-    created_by: str = Field(...)
+    # Audit fields - created fields are frozen after creation, updated fields are mutable
+    created_at: datetime = Field(default_factory=lambda: datetime.now(timezone.utc), frozen=True)
+    created_by: str = Field(..., frozen=True)
     updated_at: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
     updated_by: str = Field(...)
 
@@ -35,22 +34,21 @@ class BaseDataModel(BaseModel):
     @field_validator('created_at', 'updated_at', mode='before')
     @classmethod
     def parse_datetime(cls, v: Any) -> datetime:
-        if isinstance(v, datetime): # If Firestore already gave a datetime object
-            return v # Just use it, no parsing needed
-        if isinstance(v, str): # If it's a string (e.g. from an API request, not Firestore direct)
+        """
+        Ensures that datetime fields are properly parsed into datetime objects.
+        Handles both datetime objects (from Firestore) and ISO format strings (from APIs).
+        """
+        if isinstance(v, datetime):
+            # If it's already a datetime object (including Firestore's DatetimeWithNanoseconds),
+            # return it directly.
+            return v
+
+        if isinstance(v, str):
+            # If it's a string, parse it into a datetime object.
             try:
                 return dateutil.parser.isoparse(v)
             except (TypeError, ValueError) as e:
                 raise ValueError(f"Invalid datetime string format: {v} - {e}")
-        # Firestore might send google.api_core.datetime_helpers.DatetimeWithNanoseconds
-        # which is a subclass of datetime.datetime, so isinstance(v, datetime) should catch it.
-        # If for some reason it's a different type not caught by isinstance(v, datetime)
-        # but has isoformat(), perhaps try that, but it's unlikely with current Firestore client.
-        # For example, if v is some custom timestamp object from an older library:
-        if hasattr(v, 'isoformat'): # Fallback for unknown datetime-like objects
-             try:
-                 return dateutil.parser.isoparse(v.isoformat())
-             except Exception as e:
-                 raise ValueError(f"Could not parse datetime-like object: {v} - {e}")
-
-        raise ValueError(f"Unsupported type for datetime parsing: {type(v)} value: {v}")
+
+        # If the type is not a datetime or a string, it's an unsupported format.
+        raise ValueError(f"Unsupported type for datetime parsing: {type(v)}")

ipulse_shared_core_ftredge/models/catalog/__init__.py

@@ -0,0 +1,10 @@
+"""
+Models for default configurations
+"""
+
+from .subscriptionplan import SubscriptionPlan, ProrationMethod, PlanUpgradePath
+from .usertype import UserType
+__all__ = [
+    "UserType",
+    "SubscriptionPlan"
+]

ipulse_shared_core_ftredge/models/catalog/subscriptionplan.py

@@ -0,0 +1,274 @@
+"""
+Subscription Plan Defaults Model
+
+This module defines the configuration templates for subscription plans that are stored in Firestore.
+These templates are used to create actual user subscriptions with consistent settings.
+"""
+
+from typing import Dict, Any, Optional, ClassVar, List
+from enum import StrEnum
+from datetime import datetime, timezone, timedelta
+from pydantic import Field, ConfigDict, field_validator,model_validator, BaseModel
+from ipulse_shared_base_ftredge import (Layer, Module, list_enums_as_lower_strings,
+                                        Subject, SubscriptionPlanName,ObjectOverallStatus,
+                                        SubscriptionStatus, TimeUnit)
+from ..base_data_model import BaseDataModel
+from ..user.user_permissions import UserPermission
+
+
+class ProrationMethod(StrEnum):
+    """Methods for handling proration when upgrading plans."""
+    IMMEDIATE = "immediate"
+    PRORATED = "prorated"
+    END_OF_CYCLE = "end_of_cycle"
+
+
+class Proration(BaseModel):
+    """Defines the proration behavior for subscription changes."""
+    pro_rata_billing: bool = Field(
+        default=True,
+        description="If true, charge a pro-rated amount for the remaining time in the current billing cycle."
+    )
+    proration_date: Optional[int] = Field(
+        default=None,
+        description="The specific date to use for proration calculations, if applicable."
+    )
+
+
+class PlanUpgradePath(BaseModel):
+    """Represents an upgrade path from a source plan to the plan where this path is defined."""
+
+    price_usd: float = Field(
+        ...,
+        ge=0,
+        description="Price for upgrading to this plan in USD"
+    )
+
+    proration_method: ProrationMethod = Field(
+        ...,
+        description="How to handle proration when upgrading"
+    )
+
+
+############################################ !!!!! ALWAYS UPDATE SCHEMA VERSION IF SCHEMA IS BEING MODIFIED !!! ############################################
+class SubscriptionPlan(BaseDataModel):
+    """
+    Configuration template for subscription plans stored in Firestore.
+    These templates define the default settings applied when creating user subscriptions.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    VERSION: ClassVar[float] = 1.0
+    DOMAIN: ClassVar[str] = "_".join(list_enums_as_lower_strings(Layer.PULSE_APP, Module.CORE, Subject.CATALOG))
+    OBJ_REF: ClassVar[str] = "subscriptionplan"
+
+    # System-managed fields
+    schema_version: float = Field(
+        default=VERSION,
+        description="Version of this Class == version of DB Schema",
+        frozen=True
+    )
+
+    id: Optional[str] = Field(
+        default=None,
+        description="Unique identifier for this plan template (e.g., 'free_subscription_1'). Auto-generated if not provided.",
+        frozen=True
+    )
+
+    plan_name: SubscriptionPlanName = Field(
+        ...,
+        description="Subscription plan type (FREE, BASE, PREMIUM)",
+        frozen=True
+    )
+
+    plan_version: int = Field(
+        ...,
+        ge=1,
+        description="Version of this plan template",
+        frozen=True
+    )
+
+    pulse_status: ObjectOverallStatus = Field(
+        default=ObjectOverallStatus.ACTIVE,
+        description="Overall status of this subscription plan configuration"
+    )
+
+    # Display information
+    display_name: str = Field(
+        ...,
+        min_length=1,
+        description="Human-readable plan name",
+        frozen=True
+    )
+
+    description: str = Field(
+        ...,
+        min_length=1,
+        description="Description of what this plan includes",
+        frozen=True
+    )
+
+    granted_iam_permissions: List[UserPermission] = Field(
+        default_factory=list,
+        description="List of all IAM permission granted by this plan",
+        frozen=True
+    )
+
+    # Credit configuration
+    subscription_based_insight_credits_per_update: int = Field(
+        ...,
+        ge=0,
+        description="Number of insight credits added per update cycle",
+        frozen=True
+    )
+
+    subscription_based_insight_credits_update_freq_h: int = Field(
+        ...,
+        gt=0,
+        description="How often insight credits are updated (in hours)",
+        frozen=True
+    )
+
+    extra_insight_credits_per_cycle: int = Field(
+        ...,
+        ge=0,
+        description="Bonus insight credits granted per subscription cycle",
+        frozen=True
+    )
+
+    voting_credits_per_update: int = Field(
+        ...,
+        ge=0,
+        description="Number of voting credits added per update cycle",
+        frozen=True
+    )
+
+    voting_credits_update_freq_h: int = Field(
+        ...,
+        gt=0,
+        description="How often voting credits are updated (in hours)",
+        frozen=True
+    )
+
+    # Plan cycle configuration
+    plan_validity_cycle_length: int = Field(
+        ...,
+        gt=0,
+        description="Length of each subscription cycle (e.g., 1, 3, 12)",
+        frozen=True
+    )
+
+    plan_validity_cycle_unit: TimeUnit = Field(
+        ...,
+        description="Unit for the cycle length (month, year, etc.)",
+        frozen=True
+    )
+
+    # Pricing
+    plan_per_cycle_price_usd: float = Field(
+        ...,
+        ge=0,
+        description="Price per subscription cycle in USD",
+        frozen=True
+    )
+
+    # Features and customization
+    plan_extra_features: Dict[str, Any] = Field(
+        default_factory=dict,
+        description="Additional features enabled by this plan",
+        frozen=True
+    )
+
+    # Upgrade paths
+    plan_upgrade_paths: Dict[str, PlanUpgradePath] = Field(
+        default_factory=dict,
+        description="Defines valid upgrade paths TO this plan FROM other plans (source_plan_id -> upgrade_details)",
+        frozen=True
+    )
+
+    # Default settings
+    plan_default_auto_renewal_end: Optional[datetime] = Field(
+        default=None,
+        description="Default auto-renewal setting for new subscriptions",
+        frozen=True
+    )
+
+    plan_default_status: SubscriptionStatus = Field(
+        ...,
+        description="Default status for new subscriptions with this plan",
+        frozen=True
+    )
+
+    # Fallback configuration
+    fallback_plan_id_if_current_plan_expired: Optional[str] = Field(
+        None,
+        description="Plan to fall back to when this plan expires (None for no fallback)",
+        frozen=True
+    )
+
+    @model_validator(mode='before')
+    @classmethod
+    def set_id_if_not_provided(cls, data: Any) -> Any:
+        """Generate an ID from plan_name and plan_version if not provided."""
+        if isinstance(data, dict):
+            plan_name = data.get('plan_name')
+            plan_version = data.get('plan_version')
+            provided_id = data.get('id')
+
+            if plan_name and plan_version is not None:
+                plan_name_str = str(plan_name)
+                expected_id = f"{plan_name_str}_{plan_version}"
+
+                if provided_id is None:
+                    # Auto-generate ID
+                    data['id'] = expected_id
+                else:
+                    # Validate provided ID matches expected format
+                    if provided_id != expected_id:
+                        raise ValueError(
+                            f"Invalid ID format. Expected '{expected_id}' based on "
+                            f"plan_name='{plan_name_str}' and plan_version={plan_version}, "
+                            f"but got '{provided_id}'. ID must follow format: {{plan_name}}_{{plan_version}}"
+                        )
+        return data
+
+
+    @field_validator('granted_iam_permissions')
+    @classmethod
+    def validate_iam_permissions(cls, v: List[UserPermission]) -> List[UserPermission]:
+        """Validate IAM permissions structure."""
+        if not isinstance(v, list):
+            raise ValueError("granted_iam_permissions must be a list")
+
+        for i, permission in enumerate(v):
+            if not isinstance(permission, UserPermission):
+                raise ValueError(f"Permission at index {i} must be a UserPermission instance")
+
+        return v
+
+    @field_validator('plan_upgrade_paths')
+    @classmethod
+    def validate_upgrade_paths(cls, v: Dict[str, PlanUpgradePath]) -> Dict[str, PlanUpgradePath]:
+        """Validate upgrade paths."""
+        for source_plan_id, upgrade_path in v.items():
+            if not isinstance(source_plan_id, str) or not source_plan_id.strip():
+                raise ValueError(f"Source plan ID must be a non-empty string, got: {source_plan_id}")
+
+            if not isinstance(upgrade_path, PlanUpgradePath):
+                raise ValueError(f"Upgrade path for '{source_plan_id}' must be a PlanUpgradePath instance")
+
+        return v
+
+    def get_cycle_duration_hours(self) -> int:
+        """Calculate the total duration of one cycle in hours."""
+        unit_to_hours = {
+            TimeUnit.MINUTE: 1/60,
+            TimeUnit.HOUR: 1,
+            TimeUnit.DAY: 24,
+            TimeUnit.WEEK: 24 * 7,
+            TimeUnit.MONTH: 24 * 30,  # Approximate
+            TimeUnit.YEAR: 24 * 365,  # Approximate
+        }
+        multiplier = unit_to_hours.get(self.plan_validity_cycle_unit, 24 * 30)
+        return int(self.plan_validity_cycle_length * multiplier)

ipulse_shared_core_ftredge/models/catalog/usertype.py

@@ -0,0 +1,177 @@
+"""
+User Defaults Model
+
+This module defines the configuration templates for user type defaults that are stored in Firestore.
+These templates are used to create user profiles and statuses with consistent default settings
+based on their user type (superadmin, admin, internal, authenticated, anonymous).
+"""
+
+from typing import Dict, Any, Optional, ClassVar, List
+from datetime import datetime
+from pydantic import Field, ConfigDict, field_validator, model_validator
+from ipulse_shared_base_ftredge import Layer, Module, list_enums_as_lower_strings, Subject, ObjectOverallStatus
+from ipulse_shared_base_ftredge.enums.enums_iam import IAMUserType
+from ipulse_shared_core_ftredge.models.base_data_model import BaseDataModel
+from ipulse_shared_core_ftredge.models.user.user_permissions import UserPermission
+
+# ORIGINAL AUTHOR ="russlan.ramdowar;russlan@ftredge.com"
+# CLASS_ORIGIN_DATE="2025-06-27"
+
+
+############################################ !!!!! ALWAYS UPDATE SCHEMA VERSION IF SCHEMA IS BEING MODIFIED !!! ############################################
+class UserType(BaseDataModel):
+    """
+    Configuration template for user type defaults stored in Firestore.
+    These templates define the default settings applied when creating users of specific types.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    VERSION: ClassVar[float] = 1.0
+    DOMAIN: ClassVar[str] = "_".join(list_enums_as_lower_strings(Layer.PULSE_APP, Module.CORE.name, Subject.CATALOG.name))
+    OBJ_REF: ClassVar[str] = "usertype"
+
+    # System-managed fields
+    schema_version: float = Field(
+        default=VERSION,
+        description="Version of this Class == version of DB Schema",
+        frozen=True
+    )
+
+    id: Optional[str] = Field(
+        default=None,
+        description="Unique identifier for this user type template (e.g., 'superadmin_1', 'authenticated_1'). Auto-generated if not provided.",
+        frozen=True
+    )
+
+    version: int = Field(
+        ...,
+        ge=1,
+        description="Version of this user type template",
+        frozen=True
+    )
+
+    pulse_status: ObjectOverallStatus = Field(
+        default=ObjectOverallStatus.ACTIVE,
+        description="Overall status of this user type configuration"
+    )
+
+    # User type configuration
+    primary_usertype: IAMUserType = Field(
+        ...,
+        description="Primary user type for this configuration template",
+        frozen=True
+    )
+
+    secondary_usertypes: List[IAMUserType] = Field(
+        default_factory=list,
+        description="Secondary user types automatically assigned to users of this primary type",
+        frozen=True
+    )
+
+    # Organization defaults
+    default_organizations: List[str] = Field(
+        default_factory=list,
+        description="Default organization UIDs for users of this type",
+        frozen=True
+    )
+
+    # IAM permissions structure - simplified flattened list
+    granted_iam_permissions: List[UserPermission] = Field(
+        default_factory=list,
+        description="Default IAM permissions granted to users of this type.",
+        frozen=True
+    )
+
+    default_extra_insight_credits: int = Field(
+        default=0,
+        ge=0,
+        description="Default extra insight credits for users of this type",
+        frozen=True
+    )
+
+    default_voting_credits: int = Field(
+        default=0,
+        ge=0,
+        description="Default voting credits for users of this type",
+        frozen=True
+    )
+
+    # Subscription defaults
+    default_subscriptionplan_if_unpaid: Optional[str] = Field(
+        default=None,
+        description="Default subscription plan ID to assign if user has no active subscription",
+        frozen=True
+    )
+
+    default_subscriptionplan_auto_renewal_end: Optional[datetime] = Field(
+        default=None,
+        description="Default auto-renewal end date to apply when assigning default_subscriptionplan_if_unpaid",
+        frozen=True
+    )
+
+    # Additional metadata
+    metadata: Dict[str, Any] = Field(
+        default_factory=dict,
+        description="Additional metadata for this user type configuration",
+        frozen=True
+    )
+
+    @model_validator(mode='before')
+    @classmethod
+    def set_id_if_not_provided(cls, data: Any) -> Any:
+        """Generate an ID from primary_usertype and version if not provided."""
+        if isinstance(data, dict):
+            primary_usertype = data.get('primary_usertype')
+            version = data.get('version')
+            provided_id = data.get('id')
+
+            if primary_usertype and version is not None:
+                primary_usertype_str = str(primary_usertype)
+                expected_id = f"{primary_usertype_str}_{version}"
+
+                if provided_id is None:
+                    # Auto-generate ID
+                    data['id'] = expected_id
+                else:
+                    # Validate provided ID matches expected format
+                    if provided_id != expected_id:
+                        raise ValueError(
+                            f"Invalid ID format. Expected '{expected_id}' based on "
+                            f"primary_usertype='{primary_usertype_str}' and version={version}, "
+                            f"but got '{provided_id}'. ID must follow format: {{primary_usertype}}_{{version}}"
+                        )
+        return data
+
+    @property
+    def usertype_id(self) -> str:
+        """Get the ID as a non-optional string. ID is always set after validation."""
+        if self.id is None:
+            raise ValueError("UserType ID is not set - this should not happen after model validation")
+        return self.id
+
+    @field_validator('granted_iam_permissions')
+    @classmethod
+    def validate_iam_permissions(cls, v: List[UserPermission]) -> List[UserPermission]:
+        """Validate IAM permissions structure."""
+        if not isinstance(v, list):
+            raise ValueError("granted_iam_permissions must be a list")
+
+        for i, permission in enumerate(v):
+            if not isinstance(permission, UserPermission):
+                raise ValueError(f"Permission at index {i} must be a UserPermission instance")
+
+        return v
+
+    @field_validator('secondary_usertypes')
+    @classmethod
+    def validate_secondary_usertypes(cls, v: List[IAMUserType]) -> List[IAMUserType]:
+        """Validate secondary user types list."""
+        # Remove duplicates while preserving order
+        seen = set()
+        unique_list = []
+        for user_type in v:
+            if user_type not in seen:
+                seen.add(user_type)
+                unique_list.append(user_type)
+        return unique_list

ipulse_shared_core_ftredge/models/user/__init__.py

@@ -0,0 +1,5 @@
+from .userprofile import UserProfile
+from .user_subscription import UserSubscription
+from .user_permissions import UserPermission
+from .userstatus import UserStatus
+from .userauth import UserAuth

ipulse_shared_core_ftredge/models/user/user_permissions.py

@@ -0,0 +1,66 @@
+
+""" User IAM model for tracking user permissions and access rights. """
+from datetime import datetime, timezone
+from typing import Dict, Optional, Any
+from pydantic import BaseModel, Field, ConfigDict
+from ipulse_shared_base_ftredge.enums.enums_iam import IAMUnit
+
+class UserPermission(BaseModel):
+    """
+    A single permission assignment with full context.
+    Flattened structure for easier management and querying.
+    """
+    model_config = ConfigDict(frozen=False)
+
+    domain: str = Field(
+        ...,
+        description="The domain for this permission (e.g., 'papp', 'papp/oracle')"
+    )
+    iam_unit_type: IAMUnit = Field(
+        ...,
+        description="Type of IAM assignment (GROUP, ROLE, etc.)"
+    )
+    permission_ref: str = Field(
+        ...,
+        description="The permission reference/name (e.g., 'sysadmin_group', 'analyst')"
+    )
+    source: str = Field(
+        ...,
+        description="Source of this assignment (e.g., subscription plan ID, 'manual_grant')"
+    )
+    expires_at: Optional[datetime] = Field(
+        default=None,
+        description="When this assignment expires (None for permanent)"
+    )
+    granted_at: datetime = Field(
+        default_factory=lambda: datetime.now(timezone.utc),
+        description="When this permission was granted"
+    )
+    granted_by: Optional[str] = Field(
+        default=None,
+        description="Who granted this permission (user ID or system identifier)"
+    )
+    metadata: Dict[str, Any] = Field(
+        default_factory=dict,
+        description="Additional metadata for this permission assignment"
+    )
+
+    def is_valid(self) -> bool:
+        """Check if the permission is currently valid (not expired)."""
+        if self.expires_at is None:
+            return True
+
+        # Ensure both datetimes are timezone-aware for comparison
+        current_time = datetime.now(timezone.utc)
+        expires_time = self.expires_at
+
+        # If expires_at is timezone-naive, assume it's UTC
+        if expires_time.tzinfo is None:
+            expires_time = expires_time.replace(tzinfo=timezone.utc)
+
+        return current_time <= expires_time
+
+    def __str__(self) -> str:
+        """Human-readable representation of the permission."""
+        expiry = f" (expires: {self.expires_at})" if self.expires_at else " (permanent)"
+        return f"{self.domain}/{self.iam_unit_type}/{self.permission_ref} from {self.source}{expiry}"