@bernierllc/email 1.0.0

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

@@ -0,0 +1,90 @@
+"""
+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 template data models
+"""
+
+from datetime import datetime
+from typing import Any, Dict, List, Literal, Optional
+
+from pydantic import BaseModel, Field
+
+
+class TemplateVariable(BaseModel):
+    """Template variable definition"""
+
+    name: str
+    type: Literal["text", "number", "date", "boolean", "url", "email"]
+    description: Optional[str] = None
+    default_value: Optional[Any] = None
+    required: bool = True
+    validation: Optional[Dict[str, Any]] = None
+
+
+class EmailTemplate(BaseModel):
+    """Email template model"""
+
+    id: Optional[str] = None
+    name: str
+    subject: str
+    html_body: str
+    text_body: str
+    variables: List[TemplateVariable] = Field(default_factory=list)
+    category_id: Optional[str] = None
+    tags: List[str] = Field(default_factory=list)
+    is_active: bool = True
+    version: int = 1
+    created_at: Optional[datetime] = None
+    updated_at: Optional[datetime] = None
+    created_by: Optional[str] = None
+    metadata: Dict[str, Any] = Field(default_factory=dict)
+
+    class Config:
+        from_attributes = True
+        json_encoders = {datetime: lambda v: v.isoformat() if v else None}
+
+
+class TemplateCategory(BaseModel):
+    """Template category model"""
+
+    id: str
+    name: str
+    description: Optional[str] = None
+    color: Optional[str] = None
+    is_active: bool = True
+
+
+class RenderedTemplate(BaseModel):
+    """Rendered template result"""
+
+    subject: str
+    html_content: str
+    text_content: str
+    variables: Dict[str, Any]
+    template_id: str
+
+
+class TemplateFilters(BaseModel):
+    """Template filtering options"""
+
+    category_id: Optional[str] = None
+    tags: List[str] = Field(default_factory=list)
+    is_active: Optional[bool] = None
+    search: Optional[str] = None
+    created_by: Optional[str] = None
+    created_after: Optional[datetime] = None
+    created_before: Optional[datetime] = None
+
+
+class ValidationResult(BaseModel):
+    """Template validation result"""
+
+    is_valid: bool
+    errors: List[Dict[str, Any]] = Field(default_factory=list)
+    warnings: List[Dict[str, Any]] = Field(default_factory=list)

package/packages/python/email_template_manager/providers/aws_ses.py

@@ -0,0 +1,44 @@
+"""
+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.
+"""
+
+"""
+AWS SES email provider implementation
+"""
+
+from typing import Any, Dict, List, Optional
+
+from .base import DeliveryStatus, EmailMessage, EmailProvider, SendResult
+
+
+class SESProvider(EmailProvider):
+    """AWS SES email provider"""
+
+    def __init__(self, config: Dict[str, Any]):
+        super().__init__(config)
+        # TODO: Initialize boto3 SES client
+
+    async def send_email(self, email: EmailMessage) -> SendResult:
+        """Send a single email via AWS SES"""
+        # TODO: Implement SES email sending
+        return SendResult(
+            success=False, error_message="SES provider not yet implemented"
+        )
+
+    async def send_batch(self, emails: List[EmailMessage]) -> List[SendResult]:
+        """Send multiple emails via AWS SES"""
+        return [await self.send_email(email) for email in emails]
+
+    async def get_delivery_status(self, message_id: str) -> Optional[DeliveryStatus]:
+        """Get delivery status from AWS SES"""
+        return None
+
+    async def process_webhook(
+        self, payload: Any, signature: str
+    ) -> List[Dict[str, Any]]:
+        """Process AWS SES webhook events"""
+        return []

package/packages/python/email_template_manager/providers/base.py

@@ -0,0 +1,94 @@
+"""
+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.
+"""
+
+"""
+Base email provider abstract class
+"""
+
+from abc import ABC, abstractmethod
+from datetime import datetime
+from typing import Any, Dict, List, Optional
+
+from pydantic import BaseModel, EmailStr
+
+
+class EmailMessage(BaseModel):
+    """Email message model"""
+
+    to_email: EmailStr
+    to_name: Optional[str] = None
+    from_email: Optional[EmailStr] = None
+    from_name: Optional[str] = None
+    subject: str
+    html_content: Optional[str] = None
+    text_content: Optional[str] = None
+    reply_to: Optional[EmailStr] = None
+    headers: Optional[Dict[str, str]] = None
+    attachments: Optional[List[Dict[str, Any]]] = None
+    metadata: Optional[Dict[str, Any]] = None
+
+
+class SendResult(BaseModel):
+    """Email sending result"""
+
+    success: bool
+    message_id: Optional[str] = None
+    error_message: Optional[str] = None
+    provider_response: Optional[Any] = None
+    metadata: Optional[Dict[str, Any]] = None
+
+
+class DeliveryStatus(BaseModel):
+    """Email delivery status"""
+
+    message_id: str
+    status: str  # delivered, bounced, failed, pending, etc.
+    delivered_at: Optional[datetime] = None
+    opened_at: Optional[datetime] = None
+    clicked_at: Optional[datetime] = None
+    bounced_at: Optional[datetime] = None
+    reason: Optional[str] = None
+    metadata: Optional[Dict[str, Any]] = None
+
+
+class EmailProvider(ABC):
+    """Abstract base class for email providers"""
+
+    def __init__(self, config: Dict[str, Any]):
+        """Initialize the email provider with configuration"""
+        self.config = config
+
+    @abstractmethod
+    async def send_email(self, email: EmailMessage) -> SendResult:
+        """Send a single email"""
+        pass
+
+    @abstractmethod
+    async def send_batch(self, emails: List[EmailMessage]) -> List[SendResult]:
+        """Send multiple emails"""
+        pass
+
+    @abstractmethod
+    async def get_delivery_status(self, message_id: str) -> Optional[DeliveryStatus]:
+        """Get delivery status for a message"""
+        pass
+
+    @abstractmethod
+    async def process_webhook(
+        self, payload: Any, signature: str
+    ) -> List[Dict[str, Any]]:
+        """Process webhook events from the provider"""
+        pass
+
+    def validate_configuration(self) -> bool:
+        """Validate provider configuration"""
+        return True
+
+    def get_provider_name(self) -> str:
+        """Get the provider name"""
+        return self.__class__.__name__.replace("Provider", "").lower()

package/packages/python/email_template_manager/providers/sendgrid.py

@@ -0,0 +1,325 @@
+"""
+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.
+"""
+
+"""
+SendGrid email provider implementation
+"""
+
+import logging
+from datetime import datetime
+from typing import Any, Dict, List, Optional
+
+from sendgrid import SendGridAPIClient
+from sendgrid.helpers.mail import (
+    Attachment,
+    Disposition,
+    FileContent,
+    FileName,
+    FileType,
+    From,
+    HtmlContent,
+    Mail,
+    PlainTextContent,
+    Subject,
+    To,
+)
+
+from ..exceptions import ConfigurationError, DeliveryError
+from .base import DeliveryStatus, EmailMessage, EmailProvider, SendResult
+
+logger = logging.getLogger(__name__)
+
+
+class SendGridProvider(EmailProvider):
+    """SendGrid email provider with full API support"""
+
+    def __init__(self, config: Dict[str, Any]):
+        """
+        Initialize SendGrid provider
+
+        Args:
+            config: Configuration dictionary with keys:
+                - api_key: SendGrid API key
+                - from_email: Default from email
+                - from_name: Default from name (optional)
+                - webhook_url: Webhook URL for delivery tracking (optional)
+                - webhook_secret: Webhook secret for verification (optional)
+        """
+        super().__init__(config)
+
+        if not config.get("api_key"):
+            raise ConfigurationError("SendGrid API key is required")
+
+        self.client = SendGridAPIClient(api_key=config["api_key"])
+        self.from_email = config["from_email"]
+        self.from_name = config.get("from_name", "")
+        self.webhook_url = config.get("webhook_url")
+        self.webhook_secret = config.get("webhook_secret")
+
+    async def send_email(self, email: EmailMessage) -> SendResult:
+        """Send a single email via SendGrid"""
+        try:
+            # Create the email
+            mail = Mail()
+
+            # Set sender
+            mail.from_email = From(
+                email=email.from_email or self.from_email,
+                name=email.from_name or self.from_name,
+            )
+
+            # Set recipient
+            mail.to = To(email=email.to_email, name=email.to_name)
+
+            # Set subject
+            mail.subject = Subject(email.subject)
+
+            # Set content
+            if email.html_content:
+                mail.content = HtmlContent(email.html_content)
+
+            if email.text_content:
+                if mail.content:
+                    # Add plain text as alternative
+                    mail.add_content(PlainTextContent(email.text_content))
+                else:
+                    mail.content = PlainTextContent(email.text_content)
+
+            # Add reply-to if specified
+            if email.reply_to:
+                mail.reply_to = email.reply_to
+
+            # Add custom headers
+            if email.headers:
+                for key, value in email.headers.items():
+                    mail.header = {key: value}
+
+            # Add attachments
+            if email.attachments:
+                for attachment_data in email.attachments:
+                    attachment = Attachment(
+                        file_content=FileContent(attachment_data["content"]),
+                        file_name=FileName(attachment_data["filename"]),
+                        file_type=FileType(
+                            attachment_data.get(
+                                "content_type", "application/octet-stream"
+                            )
+                        ),
+                        disposition=Disposition("attachment"),
+                    )
+                    mail.attachment = attachment
+
+            # Add custom tracking parameters
+            if email.metadata:
+                mail.custom_args = email.metadata
+
+            # Send the email
+            response = self.client.send(mail)
+
+            # Parse response
+            message_id = None
+            if hasattr(response, "headers") and "X-Message-Id" in response.headers:
+                message_id = response.headers["X-Message-Id"]
+
+            logger.info(
+                f"Email sent successfully via SendGrid. Status: {response.status_code}"
+            )
+
+            return SendResult(
+                success=True,
+                message_id=message_id,
+                provider_response=response.body,
+                metadata={"status_code": response.status_code, "provider": "sendgrid"},
+            )
+
+        except Exception as e:
+            logger.error(f"Failed to send email via SendGrid: {str(e)}")
+            return SendResult(
+                success=False, error_message=str(e), metadata={"provider": "sendgrid"}
+            )
+
+    async def send_batch(self, emails: List[EmailMessage]) -> List[SendResult]:
+        """Send multiple emails (SendGrid sends individually)"""
+        results = []
+
+        for email in emails:
+            result = await self.send_email(email)
+            results.append(result)
+
+        return results
+
+    async def get_delivery_status(self, message_id: str) -> Optional[DeliveryStatus]:
+        """Get delivery status for a message using SendGrid's Event API"""
+        try:
+            # Use SendGrid's Event API to get delivery status
+            # Note: This requires the Events API to be enabled
+            params = {"msg_id": message_id, "limit": 1}
+
+            # Make the API call (response not used in this simplified implementation)
+            self.client.client.suppression.unsubscribes.get(
+                query_params=params
+            )
+
+            # This is a simplified implementation
+            # In practice, you'd need to parse the events and determine status
+            return DeliveryStatus(
+                message_id=message_id,
+                status="unknown",  # Would be determined from events
+                delivered_at=None,
+                metadata={},
+            )
+
+        except Exception as e:
+            logger.error(f"Failed to get delivery status from SendGrid: {str(e)}")
+            return None
+
+    async def process_webhook(
+        self, payload: Any, signature: str
+    ) -> List[Dict[str, Any]]:
+        """Process SendGrid webhook events"""
+        try:
+            # Verify webhook signature if secret is configured
+            if self.webhook_secret:
+                # Implement signature verification here
+                # SendGrid uses a different signature method than others
+                pass
+
+            # Parse SendGrid webhook payload
+            events = []
+
+            if isinstance(payload, list):
+                # SendGrid sends events as an array
+                for event_data in payload:
+                    event = {
+                        "message_id": event_data.get("sg_message_id"),
+                        "event_type": event_data.get("event"),
+                        "timestamp": datetime.fromtimestamp(
+                            event_data.get("timestamp", 0)
+                        ),
+                        "email": event_data.get("email"),
+                        "reason": event_data.get("reason"),
+                        "response": event_data.get("response"),
+                        "provider": "sendgrid",
+                        "raw_data": event_data,
+                    }
+                    events.append(event)
+
+            return events
+
+        except Exception as e:
+            logger.error(f"Failed to process SendGrid webhook: {str(e)}")
+            return []
+
+    def validate_configuration(self) -> bool:
+        """Validate SendGrid configuration"""
+        try:
+            # Test API key by making a simple API call
+            response = self.client.client.user.profile.get()
+            return response.status_code == 200
+        except Exception as e:
+            logger.error(f"SendGrid configuration validation failed: {str(e)}")
+            return False
+
+    async def create_template(self, template_data: Dict[str, Any]) -> str:
+        """Create a template in SendGrid (Dynamic Templates)"""
+        try:
+            data = {"name": template_data["name"], "generation": "dynamic"}
+
+            response = self.client.client.templates.post(request_body=data)
+
+            if response.status_code == 201:
+                template_id = response.body.get("id")
+
+                # Create a version for the template
+                version_data = {
+                    "subject": template_data["subject"],
+                    "html_content": template_data["html_content"],
+                    "plain_content": template_data.get("text_content", ""),
+                    "active": 1,
+                }
+
+                version_response = self.client.client.templates._(
+                    template_id
+                ).versions.post(request_body=version_data)
+
+                if version_response.status_code == 201:
+                    return template_id
+
+            raise DeliveryError(f"Failed to create SendGrid template: {response.body}")
+
+        except Exception as e:
+            logger.error(f"Failed to create SendGrid template: {str(e)}")
+            raise DeliveryError(f"Template creation failed: {str(e)}")
+
+    async def send_template_email(
+        self,
+        template_id: str,
+        to_email: str,
+        template_data: Dict[str, Any],
+        to_name: Optional[str] = None,
+    ) -> SendResult:
+        """Send an email using a SendGrid Dynamic Template"""
+        try:
+            mail = Mail()
+
+            # Set sender
+            mail.from_email = From(email=self.from_email, name=self.from_name)
+
+            # Set recipient
+            mail.to = To(email=to_email, name=to_name)
+
+            # Set template ID
+            mail.template_id = template_id
+
+            # Set dynamic template data
+            mail.dynamic_template_data = template_data
+
+            # Send the email
+            response = self.client.send(mail)
+
+            message_id = None
+            if hasattr(response, "headers") and "X-Message-Id" in response.headers:
+                message_id = response.headers["X-Message-Id"]
+
+            return SendResult(
+                success=True,
+                message_id=message_id,
+                provider_response=response.body,
+                metadata={
+                    "status_code": response.status_code,
+                    "provider": "sendgrid",
+                    "template_id": template_id,
+                },
+            )
+
+        except Exception as e:
+            logger.error(f"Failed to send template email via SendGrid: {str(e)}")
+            return SendResult(
+                success=False,
+                error_message=str(e),
+                metadata={"provider": "sendgrid", "template_id": template_id},
+            )
+
+    async def get_webhook_data(
+        self, webhook_data: List[Dict[str, Any]]
+    ) -> List[Dict[str, Any]]:
+        """Process SendGrid webhook data"""
+        events = []
+
+        for event in webhook_data:
+            processed_event = {
+                "message_id": event.get("sg_message_id"),
+                "event_type": event.get("event"),
+                "timestamp": event.get("timestamp"),
+                "email": event.get("email"),
+                "reason": event.get("reason"),
+                "bounce_classification": event.get("bounce_classification"),
+            }
+            events.append(processed_event)
+
+        return events

package/packages/python/email_template_manager/providers/smtp.py

@@ -0,0 +1,44 @@
+"""
+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.
+"""
+
+"""
+SMTP email provider implementation
+"""
+
+from typing import Any, Dict, List, Optional
+
+from .base import DeliveryStatus, EmailMessage, EmailProvider, SendResult
+
+
+class SMTPProvider(EmailProvider):
+    """SMTP email provider"""
+
+    def __init__(self, config: Dict[str, Any]):
+        super().__init__(config)
+        # TODO: Initialize SMTP connection
+
+    async def send_email(self, email: EmailMessage) -> SendResult:
+        """Send a single email via SMTP"""
+        # TODO: Implement SMTP email sending
+        return SendResult(
+            success=False, error_message="SMTP provider not yet implemented"
+        )
+
+    async def send_batch(self, emails: List[EmailMessage]) -> List[SendResult]:
+        """Send multiple emails via SMTP"""
+        return [await self.send_email(email) for email in emails]
+
+    async def get_delivery_status(self, message_id: str) -> Optional[DeliveryStatus]:
+        """Get delivery status - not supported by basic SMTP"""
+        return None
+
+    async def process_webhook(
+        self, payload: Any, signature: str
+    ) -> List[Dict[str, Any]]:
+        """Process webhook events - not supported by basic SMTP"""
+        return []