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

geek_cafe_saas_sdk/domains/notifications/models/notification_preference.py

@@ -0,0 +1,365 @@
+"""
+NotificationPreference Model - User notification channel preferences.
+
+Manages per-user settings for notification delivery including:
+- Channel enablement (email, SMS, push, in-app)
+- Quiet hours/Do Not Disturb
+- Notification type preferences
+- Frequency controls
+
+Geek Cafe, LLC
+MIT License. See Project Root for the license information.
+"""
+
+from typing import Dict, List, Any
+from geek_cafe_saas_sdk.models.base_model import BaseModel
+from boto3_assist.dynamodb.dynamodb_index import DynamoDBIndex, DynamoDBKey
+
+
+class NotificationPreference(BaseModel):
+    """
+    User notification preferences model.
+    
+    Controls how and when a user receives notifications across all channels.
+    Supports per-channel, per-type preferences with quiet hours.
+    """
+    
+    def __init__(self):
+        super().__init__()
+        
+        # User identification
+        self._user_id: str = ""  # Required
+        
+        # Global preferences
+        self._enabled: bool = True  # Master switch
+        self._do_not_disturb: bool = False  # Temporary DND
+        self._quiet_hours_enabled: bool = False
+        self._quiet_hours_start: str | None = None  # "22:00"
+        self._quiet_hours_end: str | None = None  # "08:00"
+        self._timezone: str = "UTC"
+        
+        # Channel preferences
+        self._email_enabled: bool = True
+        self._email_address: str | None = None  # Override default
+        self._email_frequency: str = "immediate"  # immediate, daily_digest, weekly_digest
+        
+        self._sms_enabled: bool = False  # Opt-in required
+        self._sms_phone: str | None = None
+        self._sms_frequency: str = "immediate"
+        
+        self._push_enabled: bool = True
+        self._push_device_tokens: List[str] = []  # Multiple devices
+        
+        self._in_app_enabled: bool = True
+        
+        self._webhook_enabled: bool = False
+        self._webhook_url: str | None = None
+        
+        # Type-specific preferences
+        # Key = notification_type, Value = {channel: enabled}
+        self._type_preferences: Dict[str, Dict[str, bool]] = {}
+        
+        # Digest settings
+        self._digest_time: str = "09:00"  # When to send daily digest
+        self._digest_day: str = "monday"  # For weekly digest
+        
+        # Metadata
+        self._language: str = "en"  # Preferred language
+        self._metadata: Dict[str, Any] = {}
+        
+        # CRITICAL: Call _setup_indexes() as LAST line in __init__
+        self._setup_indexes()
+    
+    def _setup_indexes(self):
+        """Setup DynamoDB indexes for notification preference queries."""
+        
+        # Primary index: Preference by user ID
+        primary: DynamoDBIndex = DynamoDBIndex()
+        primary.name = "primary"
+        primary.partition_key.attribute_name = "pk"
+        primary.partition_key.value = lambda: DynamoDBKey.build_key(("preferences", self.user_id))
+        primary.sort_key.attribute_name = "sk"
+        primary.sort_key.value = lambda: "metadata"
+        self.indexes.add_primary(primary)
+    
+    # Core Properties
+    @property
+    def user_id(self) -> str:
+        return self._user_id
+    
+    @user_id.setter
+    def user_id(self, value: str):
+        self._user_id = value
+    
+    @property
+    def enabled(self) -> bool:
+        return self._enabled
+    
+    @enabled.setter
+    def enabled(self, value: bool):
+        self._enabled = value
+    
+    @property
+    def do_not_disturb(self) -> bool:
+        return self._do_not_disturb
+    
+    @do_not_disturb.setter
+    def do_not_disturb(self, value: bool):
+        self._do_not_disturb = value
+    
+    @property
+    def quiet_hours_enabled(self) -> bool:
+        return self._quiet_hours_enabled
+    
+    @quiet_hours_enabled.setter
+    def quiet_hours_enabled(self, value: bool):
+        self._quiet_hours_enabled = value
+    
+    @property
+    def quiet_hours_start(self) -> str | None:
+        return self._quiet_hours_start
+    
+    @quiet_hours_start.setter
+    def quiet_hours_start(self, value: str | None):
+        self._quiet_hours_start = value
+    
+    @property
+    def quiet_hours_end(self) -> str | None:
+        return self._quiet_hours_end
+    
+    @quiet_hours_end.setter
+    def quiet_hours_end(self, value: str | None):
+        self._quiet_hours_end = value
+    
+    @property
+    def timezone(self) -> str:
+        return self._timezone
+    
+    @timezone.setter
+    def timezone(self, value: str):
+        self._timezone = value
+    
+    @property
+    def email_enabled(self) -> bool:
+        return self._email_enabled
+    
+    @email_enabled.setter
+    def email_enabled(self, value: bool):
+        self._email_enabled = value
+    
+    @property
+    def email_address(self) -> str | None:
+        return self._email_address
+    
+    @email_address.setter
+    def email_address(self, value: str | None):
+        self._email_address = value
+    
+    @property
+    def email_frequency(self) -> str:
+        return self._email_frequency
+    
+    @email_frequency.setter
+    def email_frequency(self, value: str):
+        self._email_frequency = value
+    
+    @property
+    def sms_enabled(self) -> bool:
+        return self._sms_enabled
+    
+    @sms_enabled.setter
+    def sms_enabled(self, value: bool):
+        self._sms_enabled = value
+    
+    @property
+    def sms_phone(self) -> str | None:
+        return self._sms_phone
+    
+    @sms_phone.setter
+    def sms_phone(self, value: str | None):
+        self._sms_phone = value
+    
+    @property
+    def sms_frequency(self) -> str:
+        return self._sms_frequency
+    
+    @sms_frequency.setter
+    def sms_frequency(self, value: str):
+        self._sms_frequency = value
+    
+    @property
+    def push_enabled(self) -> bool:
+        return self._push_enabled
+    
+    @push_enabled.setter
+    def push_enabled(self, value: bool):
+        self._push_enabled = value
+    
+    @property
+    def push_device_tokens(self) -> List[str]:
+        return self._push_device_tokens
+    
+    @push_device_tokens.setter
+    def push_device_tokens(self, value: List[str]):
+        self._push_device_tokens = value if value else []
+    
+    @property
+    def in_app_enabled(self) -> bool:
+        return self._in_app_enabled
+    
+    @in_app_enabled.setter
+    def in_app_enabled(self, value: bool):
+        self._in_app_enabled = value
+    
+    @property
+    def webhook_enabled(self) -> bool:
+        return self._webhook_enabled
+    
+    @webhook_enabled.setter
+    def webhook_enabled(self, value: bool):
+        self._webhook_enabled = value
+    
+    @property
+    def webhook_url(self) -> str | None:
+        return self._webhook_url
+    
+    @webhook_url.setter
+    def webhook_url(self, value: str | None):
+        self._webhook_url = value
+    
+    @property
+    def type_preferences(self) -> Dict[str, Dict[str, bool]]:
+        return self._type_preferences
+    
+    @type_preferences.setter
+    def type_preferences(self, value: Dict[str, Dict[str, bool]]):
+        self._type_preferences = value if value else {}
+    
+    @property
+    def digest_time(self) -> str:
+        return self._digest_time
+    
+    @digest_time.setter
+    def digest_time(self, value: str):
+        self._digest_time = value
+    
+    @property
+    def digest_day(self) -> str:
+        return self._digest_day
+    
+    @digest_day.setter
+    def digest_day(self, value: str):
+        self._digest_day = value
+    
+    @property
+    def language(self) -> str:
+        return self._language
+    
+    @language.setter
+    def language(self, value: str):
+        self._language = value
+    
+    @property
+    def metadata(self) -> Dict[str, Any]:
+        return self._metadata
+    
+    @metadata.setter
+    def metadata(self, value: Dict[str, Any]):
+        self._metadata = value if value else {}
+    
+    # Helper Methods
+    def is_channel_enabled(self, channel: str) -> bool:
+        """Check if a channel is globally enabled."""
+        if not self._enabled or self._do_not_disturb:
+            return False
+        
+        channel_map = {
+            "email": self._email_enabled,
+            "sms": self._sms_enabled,
+            "push": self._push_enabled,
+            "in_app": self._in_app_enabled,
+            "webhook": self._webhook_enabled
+        }
+        
+        return channel_map.get(channel, False)
+    
+    def is_type_enabled(self, notification_type: str, channel: str) -> bool:
+        """Check if a specific notification type is enabled for a channel."""
+        if not self.is_channel_enabled(channel):
+            return False
+        
+        if notification_type in self._type_preferences:
+            type_prefs = self._type_preferences[notification_type]
+            return type_prefs.get(channel, True)
+        
+        return True
+    
+    def set_type_preference(self, notification_type: str, channel: str, enabled: bool):
+        """Set preference for a notification type on a specific channel."""
+        if notification_type not in self._type_preferences:
+            self._type_preferences[notification_type] = {}
+        
+        self._type_preferences[notification_type][channel] = enabled
+    
+    def is_in_quiet_hours(self, current_time: str) -> bool:
+        """Check if current time is within quiet hours (HH:MM format)."""
+        if not self._quiet_hours_enabled:
+            return False
+        
+        if not self._quiet_hours_start or not self._quiet_hours_end:
+            return False
+        
+        try:
+            current = self._time_to_minutes(current_time)
+            start = self._time_to_minutes(self._quiet_hours_start)
+            end = self._time_to_minutes(self._quiet_hours_end)
+            
+            if start > end:  # Overnight hours
+                return current >= start or current <= end
+            else:
+                return start <= current <= end
+        except:
+            return False
+    
+    def _time_to_minutes(self, time_str: str) -> int:
+        """Convert HH:MM to minutes since midnight."""
+        hours, minutes = map(int, time_str.split(":"))
+        return hours * 60 + minutes
+    
+    def add_device_token(self, token: str):
+        """Add a push device token."""
+        if token and token not in self._push_device_tokens:
+            self._push_device_tokens.append(token)
+    
+    def remove_device_token(self, token: str):
+        """Remove a push device token."""
+        if token in self._push_device_tokens:
+            self._push_device_tokens.remove(token)
+    
+    def validate(self) -> tuple[bool, list[str]]:
+        """Validate preference data."""
+        errors = []
+        
+        if not self._user_id:
+            errors.append("user_id is required")
+        
+        # Validate quiet hours format
+        if self._quiet_hours_enabled:
+            if not self._quiet_hours_start or not self._quiet_hours_end:
+                errors.append("quiet_hours_start and quiet_hours_end required when enabled")
+            else:
+                try:
+                    self._time_to_minutes(self._quiet_hours_start)
+                    self._time_to_minutes(self._quiet_hours_end)
+                except:
+                    errors.append("Invalid quiet hours format (use HH:MM)")
+        
+        # Validate SMS phone if enabled
+        if self._sms_enabled and not self._sms_phone:
+            errors.append("sms_phone required when SMS is enabled")
+        
+        # Validate webhook URL if enabled
+        if self._webhook_enabled and not self._webhook_url:
+            errors.append("webhook_url required when webhook is enabled")
+        
+        return (len(errors) == 0, errors)

geek_cafe_saas_sdk/domains/notifications/models/webhook_subscription.py

@@ -0,0 +1,339 @@
+"""
+WebhookSubscription Model - Outbound webhook event subscriptions.
+
+Allows tenants to subscribe to platform events via webhooks for integrations.
+
+Geek Cafe, LLC
+MIT License. See Project Root for the license information.
+"""
+
+from typing import Dict, List, Any
+from geek_cafe_saas_sdk.models.base_model import BaseModel
+from boto3_assist.dynamodb.dynamodb_index import DynamoDBIndex, DynamoDBKey
+
+
+class WebhookSubscription(BaseModel):
+    """
+    Webhook subscription for outbound event notifications.
+    
+    Tenants can subscribe to platform events (payment completed, user created, etc.)
+    and receive HTTP POSTs to their endpoint.
+    """
+    
+    # Subscription status
+    STATUS_ACTIVE = "active"
+    STATUS_PAUSED = "paused"
+    STATUS_DISABLED = "disabled"
+    
+    def __init__(self):
+        super().__init__()
+        
+        # Core fields
+        self._tenant_id: str = ""  # Required
+        self._subscription_name: str = ""  # Display name
+        self._url: str = ""  # Webhook endpoint
+        self._status: str = self.STATUS_ACTIVE
+        
+        # Event subscription
+        self._event_types: List[str] = []  # Events to subscribe to
+        self._event_filters: Dict[str, Any] = {}  # Optional filters
+        
+        # Security
+        self._secret: str | None = None  # For HMAC signature
+        self._api_key: str | None = None  # Optional API key header
+        self._custom_headers: Dict[str, str] = {}  # Additional headers
+        
+        # Configuration
+        self._http_method: str = "POST"  # POST, PUT
+        self._content_type: str = "application/json"
+        self._timeout_seconds: int = 30
+        self._retry_enabled: bool = True
+        self._max_retries: int = 3
+        self._retry_delay_seconds: int = 60
+        
+        # Statistics
+        self._total_deliveries: int = 0
+        self._successful_deliveries: int = 0
+        self._failed_deliveries: int = 0
+        self._last_delivery_utc_ts: float | None = None
+        self._last_success_utc_ts: float | None = None
+        self._last_failure_utc_ts: float | None = None
+        self._last_error: str | None = None
+        
+        # Metadata
+        self._description: str | None = None
+        self._metadata: Dict[str, Any] = {}
+        
+        # CRITICAL: Call _setup_indexes() as LAST line in __init__
+        self._setup_indexes()
+    
+    def _setup_indexes(self):
+        """Setup DynamoDB indexes for webhook subscription queries."""
+        
+        # Primary index: Webhook subscription by ID
+        primary: DynamoDBIndex = DynamoDBIndex()
+        primary.name = "primary"
+        primary.partition_key.attribute_name = "pk"
+        primary.partition_key.value = lambda: DynamoDBKey.build_key(("webhook", self.id))
+        primary.sort_key.attribute_name = "sk"
+        primary.sort_key.value = lambda: "metadata"
+        self.indexes.add_primary(primary)
+        
+        # GSI1: Webhooks by tenant (for listing)
+        gsi: DynamoDBIndex = DynamoDBIndex()
+        gsi.name = "gsi1"
+        gsi.partition_key.attribute_name = f"{gsi.name}_pk"
+        gsi.partition_key.value = lambda: DynamoDBKey.build_key(("tenant", self.tenant_id))
+        gsi.sort_key.attribute_name = f"{gsi.name}_sk"
+        gsi.sort_key.value = lambda: DynamoDBKey.build_key(("webhook", self.created_utc_ts))
+        self.indexes.add_secondary(gsi)
+    
+    # Properties
+    @property
+    def tenant_id(self) -> str:
+        return self._tenant_id
+    
+    @tenant_id.setter
+    def tenant_id(self, value: str):
+        self._tenant_id = value
+    
+    @property
+    def subscription_name(self) -> str:
+        return self._subscription_name
+    
+    @subscription_name.setter
+    def subscription_name(self, value: str):
+        self._subscription_name = value
+    
+    @property
+    def url(self) -> str:
+        return self._url
+    
+    @url.setter
+    def url(self, value: str):
+        self._url = value
+    
+    @property
+    def status(self) -> str:
+        return self._status
+    
+    @status.setter
+    def status(self, value: str):
+        self._status = value
+    
+    @property
+    def event_types(self) -> List[str]:
+        return self._event_types
+    
+    @event_types.setter
+    def event_types(self, value: List[str]):
+        self._event_types = value if value else []
+    
+    @property
+    def event_filters(self) -> Dict[str, Any]:
+        return self._event_filters
+    
+    @event_filters.setter
+    def event_filters(self, value: Dict[str, Any]):
+        self._event_filters = value if value else {}
+    
+    @property
+    def secret(self) -> str | None:
+        return self._secret
+    
+    @secret.setter
+    def secret(self, value: str | None):
+        self._secret = value
+    
+    @property
+    def api_key(self) -> str | None:
+        return self._api_key
+    
+    @api_key.setter
+    def api_key(self, value: str | None):
+        self._api_key = value
+    
+    @property
+    def custom_headers(self) -> Dict[str, str]:
+        return self._custom_headers
+    
+    @custom_headers.setter
+    def custom_headers(self, value: Dict[str, str]):
+        self._custom_headers = value if value else {}
+    
+    @property
+    def http_method(self) -> str:
+        return self._http_method
+    
+    @http_method.setter
+    def http_method(self, value: str):
+        self._http_method = value
+    
+    @property
+    def content_type(self) -> str:
+        return self._content_type
+    
+    @content_type.setter
+    def content_type(self, value: str):
+        self._content_type = value
+    
+    @property
+    def timeout_seconds(self) -> int:
+        return self._timeout_seconds
+    
+    @timeout_seconds.setter
+    def timeout_seconds(self, value: int):
+        self._timeout_seconds = value
+    
+    @property
+    def retry_enabled(self) -> bool:
+        return self._retry_enabled
+    
+    @retry_enabled.setter
+    def retry_enabled(self, value: bool):
+        self._retry_enabled = value
+    
+    @property
+    def max_retries(self) -> int:
+        return self._max_retries
+    
+    @max_retries.setter
+    def max_retries(self, value: int):
+        self._max_retries = value
+    
+    @property
+    def retry_delay_seconds(self) -> int:
+        return self._retry_delay_seconds
+    
+    @retry_delay_seconds.setter
+    def retry_delay_seconds(self, value: int):
+        self._retry_delay_seconds = value
+    
+    @property
+    def total_deliveries(self) -> int:
+        return self._total_deliveries
+    
+    @total_deliveries.setter
+    def total_deliveries(self, value: int):
+        self._total_deliveries = value
+    
+    @property
+    def successful_deliveries(self) -> int:
+        return self._successful_deliveries
+    
+    @successful_deliveries.setter
+    def successful_deliveries(self, value: int):
+        self._successful_deliveries = value
+    
+    @property
+    def failed_deliveries(self) -> int:
+        return self._failed_deliveries
+    
+    @failed_deliveries.setter
+    def failed_deliveries(self, value: int):
+        self._failed_deliveries = value
+    
+    @property
+    def last_delivery_utc_ts(self) -> float | None:
+        return self._last_delivery_utc_ts
+    
+    @last_delivery_utc_ts.setter
+    def last_delivery_utc_ts(self, value: float | None):
+        self._last_delivery_utc_ts = value
+    
+    @property
+    def last_success_utc_ts(self) -> float | None:
+        return self._last_success_utc_ts
+    
+    @last_success_utc_ts.setter
+    def last_success_utc_ts(self, value: float | None):
+        self._last_success_utc_ts = value
+    
+    @property
+    def last_failure_utc_ts(self) -> float | None:
+        return self._last_failure_utc_ts
+    
+    @last_failure_utc_ts.setter
+    def last_failure_utc_ts(self, value: float | None):
+        self._last_failure_utc_ts = value
+    
+    @property
+    def last_error(self) -> str | None:
+        return self._last_error
+    
+    @last_error.setter
+    def last_error(self, value: str | None):
+        self._last_error = value
+    
+    @property
+    def description(self) -> str | None:
+        return self._description
+    
+    @description.setter
+    def description(self, value: str | None):
+        self._description = value
+    
+    @property
+    def metadata(self) -> Dict[str, Any]:
+        return self._metadata
+    
+    @metadata.setter
+    def metadata(self, value: Dict[str, Any]):
+        self._metadata = value if value else {}
+    
+    # Helper Methods
+    def is_active(self) -> bool:
+        """Check if subscription is active."""
+        return self._status == self.STATUS_ACTIVE
+    
+    def subscribes_to(self, event_type: str) -> bool:
+        """Check if subscription includes event type."""
+        return event_type in self._event_types or "*" in self._event_types
+    
+    def record_success(self, timestamp: float):
+        """Record successful delivery."""
+        self._total_deliveries += 1
+        self._successful_deliveries += 1
+        self._last_delivery_utc_ts = timestamp
+        self._last_success_utc_ts = timestamp
+        self._last_error = None
+    
+    def record_failure(self, timestamp: float, error: str):
+        """Record failed delivery."""
+        self._total_deliveries += 1
+        self._failed_deliveries += 1
+        self._last_delivery_utc_ts = timestamp
+        self._last_failure_utc_ts = timestamp
+        self._last_error = error
+    
+    def get_success_rate(self) -> float:
+        """Calculate success rate percentage."""
+        if self._total_deliveries == 0:
+            return 0.0
+        return (self._successful_deliveries / self._total_deliveries) * 100
+    
+    def validate(self) -> tuple[bool, list[str]]:
+        """Validate subscription data."""
+        errors = []
+        
+        if not self._tenant_id:
+            errors.append("tenant_id is required")
+        
+        if not self._subscription_name:
+            errors.append("subscription_name is required")
+        
+        if not self._url:
+            errors.append("url is required")
+        elif not self._url.startswith(("http://", "https://")):
+            errors.append("url must start with http:// or https://")
+        
+        if not self._event_types:
+            errors.append("event_types cannot be empty")
+        
+        if self._http_method not in ["POST", "PUT", "PATCH"]:
+            errors.append("http_method must be POST, PUT, or PATCH")
+        
+        if self._timeout_seconds < 1 or self._timeout_seconds > 300:
+            errors.append("timeout_seconds must be between 1 and 300")
+        
+        return (len(errors) == 0, errors)

geek_cafe_saas_sdk/domains/notifications/services/__init__.py

@@ -0,0 +1,10 @@
+"""
+Notifications Domain Services.
+
+Geek Cafe, LLC
+MIT License. See Project Root for the license information.
+"""
+
+from .notification_service import NotificationService
+
+__all__ = ["NotificationService"]