@bernierllc/email 1.0.0

package/packages/python/email_template_manager/core/scheduler.py

@@ -0,0 +1,473 @@
+"""
+Copyright (c) 2025 Bernier LLC
+
+This file is licensed to the client under a limited-use license.
+The client may use and modify this code *only within the scope of the project it was delivered for*.
+Redistribution or use in other products or commercial offerings is not permitted without written consent from Bernier LLC.
+"""
+
+"""
+Email scheduling and batch processing
+"""
+
+import asyncio
+import logging
+import uuid
+from datetime import datetime, timedelta
+from typing import List, Optional
+
+from sqlalchemy import JSON, Column, DateTime, Integer, String, Text
+
+from ..exceptions import SchedulingError, TemplateNotFoundError
+from ..models.scheduled import (
+    ProcessingResult,
+    ScheduledEmail,
+    SchedulingFilters,
+)
+from ..providers.base import EmailMessage, EmailProvider
+from .manager import Base, EmailTemplateManager
+
+logger = logging.getLogger(__name__)
+
+
+class ScheduledEmailModel(Base):
+    """SQLAlchemy model for scheduled emails"""
+
+    __tablename__ = "scheduled_emails"
+
+    id = Column(String, primary_key=True, default=lambda: str(uuid.uuid4()))
+    template_id = Column(String, nullable=False)
+    recipient_email = Column(String, nullable=False)
+    recipient_name = Column(String, nullable=True)
+    scheduled_for = Column(DateTime, nullable=False)
+    trigger_type = Column(String, nullable=False)
+    trigger_offset = Column(Integer, nullable=True)
+    reference_date = Column(DateTime, nullable=True)
+    variables = Column(JSON, default={})
+    status = Column(String, default="pending")
+    sent_at = Column(DateTime, nullable=True)
+    error_message = Column(Text, nullable=True)
+    retry_count = Column(Integer, default=0)
+    max_retries = Column(Integer, default=3)
+    email_metadata = Column(JSON, default={})
+    created_at = Column(DateTime, default=datetime.utcnow)
+    updated_at = Column(DateTime, default=datetime.utcnow, onupdate=datetime.utcnow)
+
+
+class EmailScheduler:
+    """Manages email scheduling and delivery"""
+
+    def __init__(
+        self,
+        template_manager: EmailTemplateManager,
+        email_provider: EmailProvider,
+        batch_size: int = 50,
+        retry_delays: List[int] = None,
+    ):
+        """
+        Initialize email scheduler
+
+        Args:
+            template_manager: Template manager instance
+            email_provider: Email provider instance
+            batch_size: Number of emails to process in each batch
+            retry_delays: Retry delays in minutes [5, 15, 60] by default
+        """
+        self.template_manager = template_manager
+        self.email_provider = email_provider
+        self.batch_size = batch_size
+        self.retry_delays = retry_delays or [5, 15, 60]
+
+        # Ensure tables are created
+        Base.metadata.create_all(self.template_manager.engine)
+
+    async def schedule_email(self, email: ScheduledEmail) -> ScheduledEmail:
+        """Schedule a single email"""
+        try:
+            # Validate template exists
+            template = await self.template_manager.get_template(email.template_id)
+            if not template:
+                raise TemplateNotFoundError(f"Template {email.template_id} not found")
+
+            # Calculate scheduled time based on trigger type
+            scheduled_for = self._calculate_scheduled_time(
+                email.trigger_type, email.trigger_offset, email.reference_date
+            )
+
+            with self.template_manager.get_session() as session:
+                scheduled_email_model = ScheduledEmailModel(
+                    id=email.id or str(uuid.uuid4()),
+                    template_id=email.template_id,
+                    recipient_email=str(email.recipient_email),
+                    recipient_name=email.recipient_name,
+                    scheduled_for=scheduled_for,
+                    trigger_type=email.trigger_type,
+                    trigger_offset=email.trigger_offset,
+                    reference_date=email.reference_date,
+                    variables=email.variables,
+                    status=email.status,
+                    retry_count=email.retry_count,
+                    max_retries=email.max_retries,
+                    email_metadata=email.metadata,
+                )
+
+                session.add(scheduled_email_model)
+                session.commit()
+                session.refresh(scheduled_email_model)
+
+                return self._model_to_scheduled_email(scheduled_email_model)
+
+        except Exception as e:
+            logger.error(f"Failed to schedule email: {str(e)}")
+            raise SchedulingError(f"Failed to schedule email: {str(e)}")
+
+    async def schedule_batch(
+        self, emails: List[ScheduledEmail]
+    ) -> List[ScheduledEmail]:
+        """Schedule multiple emails"""
+        results = []
+        for email in emails:
+            try:
+                result = await self.schedule_email(email)
+                results.append(result)
+            except Exception as e:
+                logger.error(f"Failed to schedule email in batch: {str(e)}")
+                # Create a failed scheduled email record
+                failed_email = email.copy()
+                failed_email.status = "failed"
+                failed_email.error_message = str(e)
+                results.append(failed_email)
+
+        return results
+
+    async def cancel_scheduled_email(self, email_id: str) -> bool:
+        """Cancel a scheduled email"""
+        try:
+            with self.template_manager.get_session() as session:
+                scheduled_email = (
+                    session.query(ScheduledEmailModel)
+                    .filter(ScheduledEmailModel.id == email_id)
+                    .first()
+                )
+
+                if not scheduled_email:
+                    return False
+
+                if scheduled_email.status in ["sent", "failed"]:
+                    return False
+
+                scheduled_email.status = "cancelled"
+                scheduled_email.updated_at = datetime.utcnow()
+                session.commit()
+
+                return True
+
+        except Exception as e:
+            logger.error(f"Failed to cancel scheduled email {email_id}: {str(e)}")
+            raise SchedulingError(f"Failed to cancel email: {str(e)}")
+
+    async def pause_scheduled_email(self, email_id: str) -> bool:
+        """Pause a scheduled email"""
+        return await self._update_email_status(email_id, "paused")
+
+    async def resume_scheduled_email(self, email_id: str) -> bool:
+        """Resume a paused email"""
+        return await self._update_email_status(email_id, "pending")
+
+    async def process_pending_emails(self) -> ProcessingResult:
+        """Process pending emails that are ready to be sent"""
+        start_time = datetime.utcnow()
+        processed_count = 0
+        success_count = 0
+        failed_count = 0
+        errors = []
+
+        try:
+            # Get pending emails ready to be sent
+            pending_emails = await self._get_pending_emails()
+
+            for scheduled_email in pending_emails:
+                try:
+                    # Render and send the email
+                    success = await self._send_scheduled_email(scheduled_email)
+                    processed_count += 1
+
+                    if success:
+                        success_count += 1
+                    else:
+                        failed_count += 1
+
+                except Exception as e:
+                    failed_count += 1
+                    error_msg = f"Email {scheduled_email.id}: {str(e)}"
+                    errors.append({"email_id": scheduled_email.id, "error": error_msg})
+                    logger.error(error_msg)
+
+                # Process in batches to avoid overwhelming the system
+                if processed_count % self.batch_size == 0:
+                    await asyncio.sleep(0.1)  # Brief pause between batches
+
+            processing_time = (datetime.utcnow() - start_time).total_seconds()
+
+            return ProcessingResult(
+                processed_count=processed_count,
+                success_count=success_count,
+                failed_count=failed_count,
+                errors=errors,
+                processing_time_seconds=processing_time,
+            )
+
+        except Exception as e:
+            logger.error(f"Failed to process pending emails: {str(e)}")
+            raise SchedulingError(f"Failed to process emails: {str(e)}")
+
+    async def retry_failed_emails(self) -> ProcessingResult:
+        """Retry failed emails that haven't exceeded max retries"""
+        try:
+            with self.template_manager.get_session() as session:
+                # Get failed emails that can be retried
+                failed_emails = (
+                    session.query(ScheduledEmailModel)
+                    .filter(
+                        ScheduledEmailModel.status == "failed",
+                        ScheduledEmailModel.retry_count
+                        < ScheduledEmailModel.max_retries,
+                    )
+                    .all()
+                )
+
+                for email_model in failed_emails:
+                    # Calculate next retry time based on retry count
+                    if email_model.retry_count < len(self.retry_delays):
+                        delay_minutes = self.retry_delays[email_model.retry_count]
+                    else:
+                        delay_minutes = self.retry_delays[-1]
+
+                    next_retry = datetime.utcnow() + timedelta(minutes=delay_minutes)
+
+                    # Update email for retry
+                    email_model.status = "pending"
+                    email_model.scheduled_for = next_retry
+                    email_model.retry_count += 1
+                    email_model.error_message = None
+                    email_model.updated_at = datetime.utcnow()
+
+                session.commit()
+
+                # Process the retries
+                return await self.process_pending_emails()
+
+        except Exception as e:
+            logger.error(f"Failed to retry failed emails: {str(e)}")
+            raise SchedulingError(f"Failed to retry emails: {str(e)}")
+
+    async def get_scheduled_email(self, email_id: str) -> Optional[ScheduledEmail]:
+        """Get scheduled email by ID"""
+        try:
+            with self.template_manager.get_session() as session:
+                email_model = (
+                    session.query(ScheduledEmailModel)
+                    .filter(ScheduledEmailModel.id == email_id)
+                    .first()
+                )
+
+                if not email_model:
+                    return None
+
+                return self._model_to_scheduled_email(email_model)
+
+        except Exception as e:
+            logger.error(f"Failed to get scheduled email {email_id}: {str(e)}")
+            return None
+
+    async def list_scheduled_emails(
+        self, filters: Optional[SchedulingFilters] = None
+    ) -> List[ScheduledEmail]:
+        """List scheduled emails with optional filtering"""
+        try:
+            with self.template_manager.get_session() as session:
+                query = session.query(ScheduledEmailModel)
+
+                # Apply filters
+                if filters:
+                    if filters.template_id:
+                        query = query.filter(
+                            ScheduledEmailModel.template_id == filters.template_id
+                        )
+                    if filters.recipient_email:
+                        query = query.filter(
+                            ScheduledEmailModel.recipient_email
+                            == filters.recipient_email
+                        )
+                    if filters.status:
+                        query = query.filter(
+                            ScheduledEmailModel.status == filters.status
+                        )
+                    if filters.scheduled_after:
+                        query = query.filter(
+                            ScheduledEmailModel.scheduled_for >= filters.scheduled_after
+                        )
+                    if filters.scheduled_before:
+                        query = query.filter(
+                            ScheduledEmailModel.scheduled_for
+                            <= filters.scheduled_before
+                        )
+
+                # Apply pagination
+                if filters and filters.offset:
+                    query = query.offset(filters.offset)
+                if filters and filters.limit:
+                    query = query.limit(filters.limit)
+                else:
+                    query = query.limit(100)  # Default limit
+
+                email_models = query.all()
+                return [self._model_to_scheduled_email(model) for model in email_models]
+
+        except Exception as e:
+            logger.error(f"Failed to list scheduled emails: {str(e)}")
+            return []
+
+    def _calculate_scheduled_time(
+        self,
+        trigger_type: str,
+        trigger_offset: Optional[int],
+        reference_date: Optional[datetime],
+    ) -> datetime:
+        """Calculate when the email should be sent"""
+        if trigger_type == "immediate":
+            return datetime.utcnow()
+        elif (
+            trigger_type == "relative" and reference_date and trigger_offset is not None
+        ):
+            return reference_date + timedelta(days=trigger_offset)
+        elif trigger_type == "absolute" and reference_date:
+            return reference_date
+        else:
+            # Default to immediate if invalid configuration
+            return datetime.utcnow()
+
+    async def _get_pending_emails(self) -> List[ScheduledEmailModel]:
+        """Get emails that are ready to be sent"""
+        with self.template_manager.get_session() as session:
+            return (
+                session.query(ScheduledEmailModel)
+                .filter(
+                    ScheduledEmailModel.status == "pending",
+                    ScheduledEmailModel.scheduled_for <= datetime.utcnow(),
+                )
+                .limit(self.batch_size)
+                .all()
+            )
+
+    async def _send_scheduled_email(self, scheduled_email: ScheduledEmailModel) -> bool:
+        """Send a single scheduled email"""
+        try:
+            # Render the template
+            rendered = await self.template_manager.render_template(
+                scheduled_email.template_id, scheduled_email.variables
+            )
+
+            # Create email message
+            email_message = EmailMessage(
+                to_email=scheduled_email.recipient_email,
+                to_name=scheduled_email.recipient_name,
+                subject=rendered.subject,
+                html_content=rendered.html_content,
+                text_content=rendered.text_content,
+                metadata={
+                    "scheduled_email_id": scheduled_email.id,
+                    "template_id": scheduled_email.template_id,
+                    **scheduled_email.metadata,
+                },
+            )
+
+            # Send the email
+            result = await self.email_provider.send_email(email_message)
+
+            # Update scheduled email status
+            with self.template_manager.get_session() as session:
+                email_model = (
+                    session.query(ScheduledEmailModel)
+                    .filter(ScheduledEmailModel.id == scheduled_email.id)
+                    .first()
+                )
+
+                if email_model:
+                    if result.success:
+                        email_model.status = "sent"
+                        email_model.sent_at = datetime.utcnow()
+                        email_model.error_message = None
+                    else:
+                        email_model.status = "failed"
+                        email_model.error_message = result.error_message
+
+                    email_model.updated_at = datetime.utcnow()
+                    session.commit()
+
+            return result.success
+
+        except Exception as e:
+            # Update scheduled email with error
+            with self.template_manager.get_session() as session:
+                email_model = (
+                    session.query(ScheduledEmailModel)
+                    .filter(ScheduledEmailModel.id == scheduled_email.id)
+                    .first()
+                )
+
+                if email_model:
+                    email_model.status = "failed"
+                    email_model.error_message = str(e)
+                    email_model.updated_at = datetime.utcnow()
+                    session.commit()
+
+            logger.error(
+                f"Failed to send scheduled email {scheduled_email.id}: {str(e)}"
+            )
+            return False
+
+    async def _update_email_status(self, email_id: str, status: str) -> bool:
+        """Update email status"""
+        try:
+            with self.template_manager.get_session() as session:
+                email_model = (
+                    session.query(ScheduledEmailModel)
+                    .filter(ScheduledEmailModel.id == email_id)
+                    .first()
+                )
+
+                if not email_model:
+                    return False
+
+                email_model.status = status
+                email_model.updated_at = datetime.utcnow()
+                session.commit()
+
+                return True
+
+        except Exception as e:
+            logger.error(f"Failed to update email status: {str(e)}")
+            return False
+
+    def _model_to_scheduled_email(self, model: ScheduledEmailModel) -> ScheduledEmail:
+        """Convert SQLAlchemy model to Pydantic model"""
+        return ScheduledEmail(
+            id=model.id,
+            template_id=model.template_id,
+            recipient_email=model.recipient_email,
+            recipient_name=model.recipient_name,
+            scheduled_for=model.scheduled_for,
+            trigger_type=model.trigger_type,
+            trigger_offset=model.trigger_offset,
+            reference_date=model.reference_date,
+            variables=model.variables,
+            status=model.status,
+            sent_at=model.sent_at,
+            error_message=model.error_message,
+            retry_count=model.retry_count,
+            max_retries=model.max_retries,
+            metadata=model.email_metadata,
+            created_at=model.created_at,
+            updated_at=model.updated_at,
+        )

package/packages/python/email_template_manager/exceptions.py

@@ -0,0 +1,67 @@
+"""
+Copyright (c) 2025 Bernier LLC
+
+This file is licensed to the client under a limited-use license.
+The client may use and modify this code *only within the scope of the project it was delivered for*.
+Redistribution or use in other products or commercial offerings is not permitted without written consent from Bernier LLC.
+"""
+
+"""
+Core exceptions for email template manager
+"""
+
+
+class EmailTemplateManagerError(Exception):
+    """Base exception for all email template manager errors"""
+
+    pass
+
+
+class TemplateNotFoundError(EmailTemplateManagerError):
+    """Raised when a template is not found"""
+
+    pass
+
+
+class ValidationError(EmailTemplateManagerError):
+    """Raised when validation fails"""
+
+    def __init__(self, message: str, errors: list = None):
+        super().__init__(message)
+        self.errors = errors or []
+
+
+class DeliveryError(EmailTemplateManagerError):
+    """Raised when email delivery fails"""
+
+    pass
+
+
+class ConfigurationError(EmailTemplateManagerError):
+    """Raised when configuration is invalid"""
+
+    pass
+
+
+class SchedulingError(EmailTemplateManagerError):
+    """Raised when email scheduling fails"""
+
+    pass
+
+
+class ProviderError(EmailTemplateManagerError):
+    """Raised when email provider operations fail"""
+
+    pass
+
+
+class EncryptionError(EmailTemplateManagerError):
+    """Raised when encryption/decryption operations fail"""
+
+    pass
+
+
+class DatabaseError(EmailTemplateManagerError):
+    """Raised when database operations fail"""
+
+    pass

package/packages/python/email_template_manager/models/magic_link.py

@@ -0,0 +1,59 @@
+"""
+Copyright (c) 2025 Bernier LLC
+
+This file is licensed to the client under a limited-use license.
+The client may use and modify this code *only within the scope of the project it was delivered for*.
+Redistribution or use in other products or commercial offerings is not permitted without written consent from Bernier LLC.
+"""
+
+"""
+Magic link data models
+"""
+
+from datetime import datetime
+from typing import Any, Dict, Optional
+
+from pydantic import BaseModel, EmailStr, Field
+
+
+class MagicLink(BaseModel):
+    """Magic link model"""
+
+    id: Optional[str] = None
+    token: str
+    email: EmailStr
+    type: str
+    payload: Dict[str, Any] = Field(default_factory=dict)
+    expires_at: datetime
+    used_at: Optional[datetime] = None
+    is_used: bool = False
+    metadata: Dict[str, Any] = Field(default_factory=dict)
+    created_at: Optional[datetime] = None
+
+    class Config:
+        from_attributes = True
+        json_encoders = {datetime: lambda v: v.isoformat() if v else None}
+
+
+class MagicLinkConfig(BaseModel):
+    """Magic link configuration"""
+
+    default_expiry_hours: int = 24
+    token_length: int = 32
+    allow_reuse: bool = False
+    max_uses: int = 1
+    cleanup_expired_links: bool = True
+
+
+class MagicLinkFilters(BaseModel):
+    """Magic link filters for querying"""
+
+    email: Optional[str] = None
+    type: Optional[str] = None
+    is_used: Optional[bool] = None
+    expires_after: Optional[datetime] = None
+    expires_before: Optional[datetime] = None
+    created_after: Optional[datetime] = None
+    created_before: Optional[datetime] = None
+    limit: Optional[int] = None
+    offset: Optional[int] = None

package/packages/python/email_template_manager/models/scheduled.py

@@ -0,0 +1,78 @@
+"""
+Copyright (c) 2025 Bernier LLC
+
+This file is licensed to the client under a limited-use license.
+The client may use and modify this code *only within the scope of the project it was delivered for*.
+Redistribution or use in other products or commercial offerings is not permitted without written consent from Bernier LLC.
+"""
+
+"""
+Scheduled email data models
+"""
+
+from datetime import datetime
+from typing import Any, Dict, Literal, Optional
+
+from pydantic import BaseModel, EmailStr, Field
+
+
+class ScheduledEmail(BaseModel):
+    """Scheduled email model"""
+
+    id: Optional[str] = None
+    template_id: str
+    recipient_email: EmailStr
+    recipient_name: Optional[str] = None
+    scheduled_for: datetime
+    trigger_type: Literal["immediate", "relative", "absolute"]
+    trigger_offset: Optional[int] = None  # days before/after reference date
+    reference_date: Optional[datetime] = None
+    variables: Dict[str, Any] = Field(default_factory=dict)
+    status: Literal["pending", "sent", "failed", "cancelled", "paused"] = "pending"
+    sent_at: Optional[datetime] = None
+    error_message: Optional[str] = None
+    retry_count: int = 0
+    max_retries: int = 3
+    metadata: Dict[str, Any] = Field(default_factory=dict)
+    created_at: Optional[datetime] = None
+    updated_at: Optional[datetime] = None
+
+    class Config:
+        from_attributes = True
+        json_encoders = {datetime: lambda v: v.isoformat() if v else None}
+
+
+class SchedulingFilters(BaseModel):
+    """Scheduling filters for querying scheduled emails"""
+
+    template_id: Optional[str] = None
+    recipient_email: Optional[str] = None
+    status: Optional[Literal["pending", "sent", "failed", "cancelled", "paused"]] = None
+    scheduled_after: Optional[datetime] = None
+    scheduled_before: Optional[datetime] = None
+    created_after: Optional[datetime] = None
+    created_before: Optional[datetime] = None
+    limit: Optional[int] = None
+    offset: Optional[int] = None
+
+
+class ProcessingResult(BaseModel):
+    """Result of email processing operation"""
+
+    processed_count: int
+    success_count: int
+    failed_count: int
+    errors: list[Dict[str, Any]] = Field(default_factory=list)
+    processing_time_seconds: float
+
+
+class EmailBatch(BaseModel):
+    """Batch of emails to be scheduled"""
+
+    template_id: str
+    recipients: list[Dict[str, Any]]  # List of recipient data with variables
+    scheduled_for: Optional[datetime] = None
+    trigger_type: Literal["immediate", "relative", "absolute"] = "immediate"
+    trigger_offset: Optional[int] = None
+    reference_date: Optional[datetime] = None
+    metadata: Dict[str, Any] = Field(default_factory=dict)