@bernierllc/email 1.0.0

package/packages/python/README.md

@@ -0,0 +1,106 @@
+# email-template-manager (Python SDK)
+
+A comprehensive Python SDK for email template management, providing both low-level components and high-level integrations for FastAPI, Django, and Flask applications.
+
+## Installation
+
+```bash
+# Basic installation
+pip install email-template-manager
+
+# With FastAPI support
+pip install email-template-manager[fastapi]
+
+# With Django support
+pip install email-template-manager[django]
+
+# With all providers
+pip install email-template-manager[sendgrid,ses,mailgun]
+```
+
+## Quick Start
+
+### Basic Usage
+
+```python
+from email_template_manager import EmailTemplateManager, SendGridProvider, EmailScheduler
+
+# Initialize components
+template_manager = EmailTemplateManager("postgresql://user:pass@localhost/db")
+email_provider = SendGridProvider({
+    "api_key": "your-sendgrid-key",
+    "from_email": "noreply@yourapp.com"
+})
+scheduler = EmailScheduler(template_manager, email_provider)
+
+# Create a template
+template = await template_manager.create_template({
+    "name": "Welcome Email",
+    "subject": "Welcome {{name}}!",
+    "html_body": "<h1>Welcome {{name}}</h1><p>Thanks for joining!</p>",
+    "text_body": "Welcome {{name}}!\n\nThanks for joining!",
+    "variables": [
+        {"name": "name", "type": "text", "required": True}
+    ]
+})
+
+# Schedule an email
+scheduled = await scheduler.schedule_email({
+    "template_id": template.id,
+    "recipient_email": "user@example.com",
+    "variables": {"name": "John Doe"},
+    "trigger_type": "immediate"
+})
+```
+
+### FastAPI Integration
+
+```python
+from fastapi import FastAPI
+from email_template_manager.integrations.fastapi import create_email_router
+
+app = FastAPI()
+
+# Add email management routes
+email_router = create_email_router(
+    database_url="postgresql://...",
+    email_provider_config={
+        "provider": "sendgrid",
+        "api_key": "your-key",
+        "from_email": "noreply@yourapp.com"
+    }
+)
+app.include_router(email_router, prefix="/api")
+```
+
+## Core Features
+
+- **Template Management** - Create, update, and manage email templates with variables
+- **Email Scheduling** - Schedule emails based on events or specific times
+- **Magic Links** - Generate secure, expiring links for authentication
+- **Multiple Providers** - Support for SendGrid, AWS SES, Mailgun, and more
+- **Framework Integration** - Ready-to-use integrations for FastAPI, Django, Flask
+- **Async Support** - Full async/await support throughout
+- **Type Safety** - Complete TypeScript-style type hints
+
+## Provider Support
+
+- SendGrid
+- AWS SES
+- Mailgun
+- Postmark
+- Generic SMTP
+
+## Framework Integrations
+
+- FastAPI (async routes and background tasks)
+- Django (views and admin integration)
+- Flask (blueprints and extensions)
+
+## Documentation
+
+Full documentation available at: https://email-template-manager.readthedocs.io
+
+## License
+
+MIT License - see LICENSE file for details.

package/packages/python/email_template_manager/__init__.py

@@ -0,0 +1,66 @@
+"""
+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 Manager - Universal email template management library
+"""
+
+__version__ = "1.0.0"
+
+# Configuration
+from .config import EmailManagerConfig
+from .core.magic_links import MagicLinkManager
+
+# Core classes
+from .core.manager import EmailTemplateManager
+from .core.scheduler import EmailScheduler
+
+# Exceptions
+from .exceptions import (
+    ConfigurationError,
+    DeliveryError,
+    EmailTemplateManagerError,
+    TemplateNotFoundError,
+    ValidationError,
+)
+from .models.magic_link import MagicLink
+from .models.scheduled import ScheduledEmail
+
+# Data models
+from .models.template import EmailTemplate, TemplateVariable
+from .providers.aws_ses import SESProvider
+
+# Email providers
+from .providers.base import EmailProvider
+from .providers.sendgrid import SendGridProvider
+from .providers.smtp import SMTPProvider
+
+__all__ = [
+    # Core classes
+    "EmailTemplateManager",
+    "EmailScheduler",
+    "MagicLinkManager",
+    # Models
+    "EmailTemplate",
+    "TemplateVariable",
+    "ScheduledEmail",
+    "MagicLink",
+    # Providers
+    "EmailProvider",
+    "SendGridProvider",
+    "SESProvider",
+    "SMTPProvider",
+    # Configuration
+    "EmailManagerConfig",
+    # Exceptions
+    "EmailTemplateManagerError",
+    "TemplateNotFoundError",
+    "ValidationError",
+    "DeliveryError",
+    "ConfigurationError",
+]

package/packages/python/email_template_manager/config.py

@@ -0,0 +1,98 @@
+"""
+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.
+"""
+
+"""
+Configuration models for email template manager
+"""
+
+from typing import Any, Dict, List, Literal, Optional
+
+from pydantic import BaseModel, Field
+
+
+class DatabaseConfig(BaseModel):
+    """Database configuration"""
+
+    url: str
+    echo: bool = False
+    pool_size: int = 5
+    max_overflow: int = 10
+    pool_timeout: int = 30
+
+
+class EmailProviderConfig(BaseModel):
+    """Email provider configuration"""
+
+    provider: Literal["sendgrid", "ses", "mailgun", "postmark", "smtp"]
+    api_key: Optional[str] = None
+    region: Optional[str] = None
+    endpoint: Optional[str] = None
+    from_email: str
+    from_name: Optional[str] = None
+    reply_to: Optional[str] = None
+    webhook_url: Optional[str] = None
+    webhook_secret: Optional[str] = None
+    sandbox: bool = False
+
+
+class TemplateConfig(BaseModel):
+    """Template configuration"""
+
+    default_from_email: str
+    default_from_name: Optional[str] = None
+    liquid_engine: Dict[str, Any] = Field(default_factory=dict)
+    cache_templates: bool = True
+    cache_ttl_seconds: int = 3600
+
+
+class SchedulingConfig(BaseModel):
+    """Scheduling configuration"""
+
+    batch_size: int = 50
+    default_max_retries: int = 3
+    retry_delay_minutes: List[int] = Field(default_factory=lambda: [5, 15, 60])
+    processing_interval_minutes: int = 5
+    max_concurrent_sends: int = 10
+
+
+class SecurityConfig(BaseModel):
+    """Security configuration"""
+
+    encryption_key: str
+    token_length: int = 32
+    default_expiry_hours: int = 24
+    hash_algorithm: str = "sha256"
+
+
+class LoggingConfig(BaseModel):
+    """Logging configuration"""
+
+    level: Literal["DEBUG", "INFO", "WARNING", "ERROR"] = "INFO"
+    format: str = "%(asctime)s - %(name)s - %(levelname)s - %(message)s"
+    include_payload: bool = False
+    log_to_file: bool = False
+    log_file_path: Optional[str] = None
+
+
+class EmailManagerConfig(BaseModel):
+    """Main email manager configuration"""
+
+    database: DatabaseConfig
+    email_provider: EmailProviderConfig
+    templates: TemplateConfig
+    scheduling: SchedulingConfig = Field(default_factory=SchedulingConfig)
+    security: SecurityConfig
+    logging: LoggingConfig = Field(default_factory=LoggingConfig)
+
+    # Optional feature flags
+    enable_webhooks: bool = True
+    enable_analytics: bool = False
+    enable_rate_limiting: bool = False
+
+    # Custom metadata
+    metadata: Dict[str, Any] = Field(default_factory=dict)

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

@@ -0,0 +1,245 @@
+"""
+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 manager implementation
+"""
+
+import logging
+import secrets
+import uuid
+from datetime import datetime, timedelta
+from typing import Any, Dict, Optional
+
+from cryptography.fernet import Fernet
+from sqlalchemy import JSON, Boolean, Column, DateTime, String
+
+from ..exceptions import EncryptionError
+from ..models.magic_link import MagicLink
+from .manager import Base, EmailTemplateManager
+
+logger = logging.getLogger(__name__)
+
+
+class MagicLinkModel(Base):
+    """SQLAlchemy model for magic links"""
+
+    __tablename__ = "magic_links"
+
+    id = Column(String, primary_key=True, default=lambda: str(uuid.uuid4()))
+    token = Column(String, unique=True, nullable=False)
+    email = Column(String, nullable=False)
+    type = Column(String, nullable=False)
+    payload = Column(JSON, default={})
+    expires_at = Column(DateTime, nullable=False)
+    used_at = Column(DateTime, nullable=True)
+    is_used = Column(Boolean, default=False)
+    link_metadata = Column(JSON, default={})
+    created_at = Column(DateTime, default=datetime.utcnow)
+
+
+class MagicLinkManager:
+    """Manages magic links for authentication and secure actions"""
+
+    def __init__(self, template_manager: EmailTemplateManager, encryption_key: str):
+        """
+        Initialize magic link manager
+
+        Args:
+            template_manager: Template manager instance
+            encryption_key: Key for encrypting/decrypting payloads
+        """
+        self.template_manager = template_manager
+        self.fernet = Fernet(
+            encryption_key.encode()
+            if isinstance(encryption_key, str)
+            else encryption_key
+        )
+
+        # Ensure tables are created
+        Base.metadata.create_all(self.template_manager.engine)
+
+    async def generate_magic_link(
+        self,
+        email: str,
+        link_type: str,
+        payload: Dict[str, Any],
+        expires_in_hours: int = 24,
+    ) -> MagicLink:
+        """Generate a new magic link"""
+        try:
+            # Generate secure token
+            token = secrets.token_urlsafe(32)
+
+            # Encrypt payload
+            encrypted_payload = self._encrypt_payload(payload)
+
+            # Calculate expiry
+            expires_at = datetime.utcnow() + timedelta(hours=expires_in_hours)
+
+            with self.template_manager.get_session() as session:
+                magic_link_model = MagicLinkModel(
+                    id=str(uuid.uuid4()),
+                    token=token,
+                    email=email,
+                    type=link_type,
+                    payload=encrypted_payload,
+                    expires_at=expires_at,
+                    is_used=False,
+                    link_metadata={},
+                )
+
+                session.add(magic_link_model)
+                session.commit()
+                session.refresh(magic_link_model)
+
+                return self._model_to_magic_link(magic_link_model)
+
+        except Exception as e:
+            logger.error(f"Failed to generate magic link: {str(e)}")
+            raise EncryptionError(f"Failed to generate magic link: {str(e)}")
+
+    async def validate_magic_link(self, token: str) -> Optional[MagicLink]:
+        """Validate a magic link token"""
+        try:
+            with self.template_manager.get_session() as session:
+                magic_link_model = (
+                    session.query(MagicLinkModel)
+                    .filter(MagicLinkModel.token == token)
+                    .first()
+                )
+
+                if not magic_link_model:
+                    return None
+
+                # Check if expired
+                if magic_link_model.expires_at < datetime.utcnow():
+                    return None
+
+                # Check if already used
+                if magic_link_model.is_used:
+                    return None
+
+                return self._model_to_magic_link(magic_link_model)
+
+        except Exception as e:
+            logger.error(f"Failed to validate magic link: {str(e)}")
+            return None
+
+    async def use_magic_link(self, token: str) -> Optional[MagicLink]:
+        """Use a magic link (marks it as used)"""
+        try:
+            magic_link = await self.validate_magic_link(token)
+            if not magic_link:
+                return None
+
+            with self.template_manager.get_session() as session:
+                magic_link_model = (
+                    session.query(MagicLinkModel)
+                    .filter(MagicLinkModel.token == token)
+                    .first()
+                )
+
+                if magic_link_model:
+                    magic_link_model.is_used = True  # type: ignore
+                    magic_link_model.used_at = datetime.utcnow()  # type: ignore
+                    session.commit()
+
+                    return self._model_to_magic_link(magic_link_model)
+
+            return None
+
+        except Exception as e:
+            logger.error(f"Failed to use magic link: {str(e)}")
+            return None
+
+    async def revoke_magic_link(self, token: str) -> bool:
+        """Revoke a magic link"""
+        try:
+            with self.template_manager.get_session() as session:
+                magic_link_model = (
+                    session.query(MagicLinkModel)
+                    .filter(MagicLinkModel.token == token)
+                    .first()
+                )
+
+                if magic_link_model:
+                    magic_link_model.is_used = True  # type: ignore
+                    magic_link_model.used_at = datetime.utcnow()  # type: ignore
+                    session.commit()
+                    return True
+
+                return False
+
+        except Exception as e:
+            logger.error(f"Failed to revoke magic link: {str(e)}")
+            return False
+
+    async def cleanup_expired_links(self) -> int:
+        """Remove expired magic links"""
+        try:
+            with self.template_manager.get_session() as session:
+                expired_count = (
+                    session.query(MagicLinkModel)
+                    .filter(MagicLinkModel.expires_at < datetime.utcnow())
+                    .count()
+                )
+
+                session.query(MagicLinkModel).filter(
+                    MagicLinkModel.expires_at < datetime.utcnow()
+                ).delete()
+
+                session.commit()
+                return expired_count
+
+        except Exception as e:
+            logger.error(f"Failed to cleanup expired links: {str(e)}")
+            return 0
+
+    def _encrypt_payload(self, payload: Dict[str, Any]) -> Dict[str, Any]:
+        """Encrypt sensitive payload data"""
+        try:
+            import json
+
+            payload_json = json.dumps(payload)
+            encrypted_data = self.fernet.encrypt(payload_json.encode())
+            return {"encrypted": encrypted_data.decode()}
+        except Exception as e:
+            raise EncryptionError(f"Failed to encrypt payload: {str(e)}")
+
+    def _decrypt_payload(self, encrypted_payload: Dict[str, Any]) -> Dict[str, Any]:
+        """Decrypt payload data"""
+        try:
+            import json
+
+            encrypted_data = encrypted_payload.get("encrypted", "")
+            decrypted_data = self.fernet.decrypt(encrypted_data.encode())
+            return json.loads(decrypted_data.decode())
+        except Exception as e:
+            raise EncryptionError(f"Failed to decrypt payload: {str(e)}")
+
+    def _model_to_magic_link(self, model: MagicLinkModel) -> MagicLink:
+        """Convert SQLAlchemy model to Pydantic model"""
+        # Decrypt payload
+        try:
+            decrypted_payload = self._decrypt_payload(model.payload)  # type: ignore
+        except Exception:
+            decrypted_payload = {}
+
+        return MagicLink(
+            id=model.id,  # type: ignore
+            token=model.token,  # type: ignore
+            email=model.email,  # type: ignore
+            type=model.type,  # type: ignore
+            payload=decrypted_payload,
+            expires_at=model.expires_at,  # type: ignore
+            used_at=model.used_at,  # type: ignore
+            is_used=model.is_used,  # type: ignore
+            metadata=model.link_metadata,  # type: ignore
+            created_at=model.created_at,  # type: ignore
+        )