@bernierllc/email 1.0.0

package/packages/python/specification.md

@@ -0,0 +1,930 @@
+# email-template-manager (Python) - Python SDK Specification
+
+## Overview
+
+A comprehensive Python SDK for email template management, providing both low-level components and high-level integrations for FastAPI, Django, and Flask applications. Built with modern Python patterns, async support, and comprehensive type hints.
+
+## Core Models
+
+### Pydantic Models
+
+```python
+from pydantic import BaseModel, EmailStr, Field
+from typing import List, Optional, Dict, Any, Literal
+from datetime import datetime
+from enum import Enum
+
+class TemplateVariable(BaseModel):
+    name: str
+    type: Literal['text', 'number', 'date', 'boolean', 'url']
+    description: Optional[str] = None
+    default_value: Optional[Any] = None
+    required: bool = True
+
+class EmailTemplate(BaseModel):
+    id: Optional[str] = None
+    name: str
+    subject: str
+    html_body: str
+    text_body: str
+    variables: List[TemplateVariable] = []
+    category_id: Optional[str] = None
+    tags: List[str] = []
+    is_active: bool = True
+    version: int = 1
+    created_at: Optional[datetime] = None
+    updated_at: Optional[datetime] = None
+    created_by: Optional[str] = None
+
+class ScheduledEmail(BaseModel):
+    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] = {}
+    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] = {}
+
+class MagicLink(BaseModel):
+    id: Optional[str] = None
+    token: str
+    email: EmailStr
+    type: str
+    payload: Dict[str, Any] = {}
+    expires_at: datetime
+    used_at: Optional[datetime] = None
+    is_used: bool = False
+    metadata: Dict[str, Any] = {}
+```
+
+### SQLAlchemy Models
+
+```python
+from sqlalchemy import Column, String, Text, DateTime, Boolean, Integer, JSON
+from sqlalchemy.ext.declarative import declarative_base
+from sqlalchemy.sql import func
+
+Base = declarative_base()
+
+class EmailTemplateModel(Base):
+    __tablename__ = "email_templates"
+
+    id = Column(String, primary_key=True)
+    name = Column(String, nullable=False)
+    subject = Column(String, nullable=False)
+    html_body = Column(Text, nullable=False)
+    text_body = Column(Text, nullable=False)
+    variables = Column(JSON, default=[])
+    category_id = Column(String, nullable=True)
+    tags = Column(JSON, default=[])
+    is_active = Column(Boolean, default=True)
+    version = Column(Integer, default=1)
+    created_at = Column(DateTime, server_default=func.now())
+    updated_at = Column(DateTime, server_default=func.now(), onupdate=func.now())
+    created_by = Column(String, nullable=True)
+
+class ScheduledEmailModel(Base):
+    __tablename__ = "scheduled_emails"
+
+    id = Column(String, primary_key=True)
+    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)
+    metadata = Column(JSON, default={})
+
+class MagicLinkModel(Base):
+    __tablename__ = "magic_links"
+
+    id = Column(String, primary_key=True)
+    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)
+    metadata = Column(JSON, default={})
+```
+
+## Core Classes
+
+### EmailTemplateManager
+
+```python
+from typing import Optional, List, Dict, Any
+from sqlalchemy.orm import Session
+from sqlalchemy import create_engine
+
+class EmailTemplateManager:
+    def __init__(self, database_url: str, echo: bool = False):
+        self.engine = create_engine(database_url, echo=echo)
+        Base.metadata.create_all(self.engine)
+
+    def get_session(self) -> Session:
+        from sqlalchemy.orm import sessionmaker
+        SessionLocal = sessionmaker(bind=self.engine)
+        return SessionLocal()
+
+    async def create_template(self, template: EmailTemplate) -> EmailTemplate:
+        """Create a new email template"""
+        # Implementation
+        pass
+
+    async def get_template(self, template_id: str) -> Optional[EmailTemplate]:
+        """Get template by ID"""
+        pass
+
+    async def update_template(self, template_id: str, updates: Dict[str, Any]) -> EmailTemplate:
+        """Update existing template"""
+        pass
+
+    async def delete_template(self, template_id: str) -> bool:
+        """Delete template"""
+        pass
+
+    async def list_templates(
+        self,
+        skip: int = 0,
+        limit: int = 100,
+        filters: Optional[Dict[str, Any]] = None
+    ) -> List[EmailTemplate]:
+        """List templates with pagination and filtering"""
+        pass
+
+    async def render_template(
+        self,
+        template_id: str,
+        variables: Dict[str, Any]
+    ) -> Dict[str, str]:
+        """Render template with variables"""
+        pass
+
+    def validate_template_variables(
+        self,
+        template: EmailTemplate,
+        variables: Dict[str, Any]
+    ) -> Dict[str, Any]:
+        """Validate template variables"""
+        pass
+```
+
+### EmailScheduler
+
+```python
+import asyncio
+from datetime import datetime, timedelta
+from typing import List, Optional, Dict, Any
+
+class EmailScheduler:
+    def __init__(
+        self,
+        template_manager: EmailTemplateManager,
+        email_provider: 'EmailProvider',
+        max_retries: int = 3,
+        batch_size: int = 100
+    ):
+        self.template_manager = template_manager
+        self.email_provider = email_provider
+        self.max_retries = max_retries
+        self.batch_size = batch_size
+
+    async def schedule_email(self, email: ScheduledEmail) -> ScheduledEmail:
+        """Schedule a single email"""
+        pass
+
+    async def schedule_batch(self, emails: List[ScheduledEmail]) -> List[ScheduledEmail]:
+        """Schedule multiple emails"""
+        pass
+
+    async def cancel_scheduled_email(self, email_id: str) -> bool:
+        """Cancel a scheduled email"""
+        pass
+
+    async def pause_scheduled_email(self, email_id: str) -> bool:
+        """Pause a scheduled email"""
+        pass
+
+    async def resume_scheduled_email(self, email_id: str) -> bool:
+        """Resume a paused email"""
+        pass
+
+    async def process_pending_emails(self) -> Dict[str, Any]:
+        """Process all pending emails"""
+        pass
+
+    async def retry_failed_emails(self) -> Dict[str, Any]:
+        """Retry failed emails"""
+        pass
+
+    async def get_scheduled_email(self, email_id: str) -> Optional[ScheduledEmail]:
+        """Get scheduled email by ID"""
+        pass
+
+    async def list_scheduled_emails(
+        self,
+        skip: int = 0,
+        limit: int = 100,
+        filters: Optional[Dict[str, Any]] = None
+    ) -> List[ScheduledEmail]:
+        """List scheduled emails"""
+        pass
+```
+
+### MagicLinkManager
+
+```python
+import secrets
+import hashlib
+from datetime import datetime, timedelta
+from typing import Optional, Dict, Any
+
+class MagicLinkManager:
+    def __init__(
+        self,
+        database_manager: EmailTemplateManager,
+        encryption_key: str,
+        default_expiry_hours: int = 24
+    ):
+        self.db = database_manager
+        self.encryption_key = encryption_key
+        self.default_expiry_hours = default_expiry_hours
+
+    async def generate_magic_link(
+        self,
+        email: str,
+        link_type: str,
+        payload: Dict[str, Any],
+        expires_in_hours: Optional[int] = None
+    ) -> MagicLink:
+        """Generate a new magic link"""
+        pass
+
+    async def validate_magic_link(self, token: str) -> Optional[MagicLink]:
+        """Validate magic link token"""
+        pass
+
+    async def use_magic_link(self, token: str) -> MagicLink:
+        """Mark magic link as used and return it"""
+        pass
+
+    async def revoke_magic_link(self, token: str) -> bool:
+        """Revoke a magic link"""
+        pass
+
+    async def cleanup_expired_links(self) -> int:
+        """Clean up expired magic links"""
+        pass
+
+    def _generate_token(self, length: int = 32) -> str:
+        """Generate secure random token"""
+        return secrets.token_urlsafe(length)
+
+    def _hash_token(self, token: str) -> str:
+        """Hash token for storage"""
+        return hashlib.sha256(f"{token}{self.encryption_key}".encode()).hexdigest()
+```
+
+## Email Providers
+
+### Abstract Base Provider
+
+```python
+from abc import ABC, abstractmethod
+from typing import List, Dict, Any, Optional
+
+class EmailProvider(ABC):
+    def __init__(self, config: Dict[str, Any]):
+        self.config = config
+
+    @abstractmethod
+    async def send_email(
+        self,
+        to_email: str,
+        subject: str,
+        html_body: str,
+        text_body: str,
+        from_email: Optional[str] = None,
+        from_name: Optional[str] = None,
+        reply_to: Optional[str] = None,
+        metadata: Optional[Dict[str, Any]] = None
+    ) -> Dict[str, Any]:
+        """Send a single email"""
+        pass
+
+    @abstractmethod
+    async def send_batch(self, emails: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
+        """Send multiple emails"""
+        pass
+
+    @abstractmethod
+    async def get_delivery_status(self, message_id: str) -> Dict[str, Any]:
+        """Get delivery status for a message"""
+        pass
+
+    @abstractmethod
+    async def process_webhook(self, payload: Dict[str, Any], signature: str) -> List[Dict[str, Any]]:
+        """Process webhook from email provider"""
+        pass
+```
+
+### SendGrid Provider
+
+```python
+import sendgrid
+from sendgrid.helpers.mail import Mail, Email, To, Content
+
+class SendGridProvider(EmailProvider):
+    def __init__(self, config: Dict[str, Any]):
+        super().__init__(config)
+        self.client = sendgrid.SendGridAPIClient(api_key=config['api_key'])
+        self.from_email = config['from_email']
+        self.from_name = config.get('from_name', '')
+
+    async def send_email(
+        self,
+        to_email: str,
+        subject: str,
+        html_body: str,
+        text_body: str,
+        from_email: Optional[str] = None,
+        from_name: Optional[str] = None,
+        reply_to: Optional[str] = None,
+        metadata: Optional[Dict[str, Any]] = None
+    ) -> Dict[str, Any]:
+        """Send email using SendGrid"""
+        # Implementation
+        pass
+
+    async def send_batch(self, emails: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
+        """Send batch emails using SendGrid"""
+        pass
+
+    async def get_delivery_status(self, message_id: str) -> Dict[str, Any]:
+        """Get delivery status from SendGrid"""
+        pass
+
+    async def process_webhook(self, payload: Dict[str, Any], signature: str) -> List[Dict[str, Any]]:
+        """Process SendGrid webhook"""
+        pass
+```
+
+### AWS SES Provider
+
+```python
+import boto3
+from botocore.exceptions import ClientError
+
+class SESProvider(EmailProvider):
+    def __init__(self, config: Dict[str, Any]):
+        super().__init__(config)
+        self.client = boto3.client(
+            'ses',
+            region_name=config.get('region', 'us-east-1'),
+            aws_access_key_id=config.get('access_key_id'),
+            aws_secret_access_key=config.get('secret_access_key')
+        )
+        self.from_email = config['from_email']
+
+    async def send_email(self, **kwargs) -> Dict[str, Any]:
+        """Send email using AWS SES"""
+        # Implementation
+        pass
+
+    # ... other methods
+```
+
+## Framework Integrations
+
+### FastAPI Integration
+
+```python
+from fastapi import FastAPI, Depends, HTTPException, BackgroundTasks
+from fastapi.responses import JSONResponse
+from typing import List, Optional
+
+def create_email_router(
+    template_manager: EmailTemplateManager,
+    scheduler: EmailScheduler,
+    magic_link_manager: MagicLinkManager
+):
+    from fastapi import APIRouter
+    router = APIRouter(prefix="/email", tags=["email"])
+
+    @router.post("/templates/", response_model=EmailTemplate)
+    async def create_template(template: EmailTemplate):
+        """Create a new email template"""
+        return await template_manager.create_template(template)
+
+    @router.get("/templates/", response_model=List[EmailTemplate])
+    async def list_templates(
+        skip: int = 0,
+        limit: int = 100,
+        category: Optional[str] = None
+    ):
+        """List email templates"""
+        filters = {"category_id": category} if category else None
+        return await template_manager.list_templates(skip, limit, filters)
+
+    @router.get("/templates/{template_id}", response_model=EmailTemplate)
+    async def get_template(template_id: str):
+        """Get template by ID"""
+        template = await template_manager.get_template(template_id)
+        if not template:
+            raise HTTPException(status_code=404, detail="Template not found")
+        return template
+
+    @router.put("/templates/{template_id}", response_model=EmailTemplate)
+    async def update_template(template_id: str, updates: Dict[str, Any]):
+        """Update template"""
+        return await template_manager.update_template(template_id, updates)
+
+    @router.delete("/templates/{template_id}")
+    async def delete_template(template_id: str):
+        """Delete template"""
+        success = await template_manager.delete_template(template_id)
+        if not success:
+            raise HTTPException(status_code=404, detail="Template not found")
+        return {"success": True}
+
+    @router.post("/schedule/", response_model=ScheduledEmail)
+    async def schedule_email(email: ScheduledEmail, background_tasks: BackgroundTasks):
+        """Schedule an email"""
+        scheduled = await scheduler.schedule_email(email)
+        if email.trigger_type == 'immediate':
+            background_tasks.add_task(scheduler.process_pending_emails)
+        return scheduled
+
+    @router.post("/schedule/batch/", response_model=List[ScheduledEmail])
+    async def schedule_batch(emails: List[ScheduledEmail]):
+        """Schedule multiple emails"""
+        return await scheduler.schedule_batch(emails)
+
+    @router.post("/magic-links/generate/", response_model=MagicLink)
+    async def generate_magic_link(
+        email: str,
+        link_type: str,
+        payload: Dict[str, Any],
+        expires_in_hours: Optional[int] = None
+    ):
+        """Generate magic link"""
+        return await magic_link_manager.generate_magic_link(
+            email, link_type, payload, expires_in_hours
+        )
+
+    @router.post("/magic-links/validate/")
+    async def validate_magic_link(token: str):
+        """Validate magic link"""
+        link = await magic_link_manager.validate_magic_link(token)
+        if not link:
+            raise HTTPException(status_code=404, detail="Invalid or expired token")
+        return link
+
+    @router.post("/magic-links/use/")
+    async def use_magic_link(token: str):
+        """Use magic link"""
+        try:
+            link = await magic_link_manager.use_magic_link(token)
+            return link
+        except Exception as e:
+            raise HTTPException(status_code=400, detail=str(e))
+
+    return router
+
+# Usage example
+def create_app():
+    app = FastAPI(title="Email Template Manager")
+
+    # Initialize managers
+    template_manager = EmailTemplateManager("postgresql://...")
+    email_provider = SendGridProvider({"api_key": "...", "from_email": "..."})
+    scheduler = EmailScheduler(template_manager, email_provider)
+    magic_link_manager = MagicLinkManager(template_manager, "encryption_key")
+
+    # Include router
+    email_router = create_email_router(template_manager, scheduler, magic_link_manager)
+    app.include_router(email_router)
+
+    return app
+```
+
+### Django Integration
+
+```python
+from django.conf import settings
+from django.http import JsonResponse
+from django.views.decorators.http import require_http_methods
+from django.views.decorators.csrf import csrf_exempt
+from django.utils.decorators import method_decorator
+from django.views import View
+import json
+
+class EmailTemplateView(View):
+    def __init__(self):
+        self.template_manager = EmailTemplateManager(settings.DATABASE_URL)
+        self.scheduler = EmailScheduler(self.template_manager, self.get_email_provider())
+
+    def get_email_provider(self):
+        provider_config = settings.EMAIL_PROVIDER_CONFIG
+        if provider_config['provider'] == 'sendgrid':
+            return SendGridProvider(provider_config)
+        # ... other providers
+
+    @method_decorator(csrf_exempt)
+    def dispatch(self, request, *args, **kwargs):
+        return super().dispatch(request, *args, **kwargs)
+
+    async def post(self, request):
+        """Create email template"""
+        data = json.loads(request.body)
+        template = EmailTemplate(**data)
+        created_template = await self.template_manager.create_template(template)
+        return JsonResponse(created_template.dict())
+
+    async def get(self, request):
+        """List email templates"""
+        templates = await self.template_manager.list_templates()
+        return JsonResponse([t.dict() for t in templates], safe=False)
+
+# Django settings configuration
+EMAIL_TEMPLATE_MANAGER = {
+    'DATABASE_URL': 'postgresql://...',
+    'EMAIL_PROVIDER_CONFIG': {
+        'provider': 'sendgrid',
+        'api_key': 'your-sendgrid-api-key',
+        'from_email': 'your-email@domain.com',
+        'from_name': 'Your App'
+    },
+    'MAGIC_LINK_CONFIG': {
+        'encryption_key': 'your-encryption-key',
+        'default_expiry_hours': 24
+    }
+}
+```
+
+### Flask Integration
+
+```python
+from flask import Flask, request, jsonify, Blueprint
+from typing import Dict, Any
+
+def create_email_blueprint(
+    template_manager: EmailTemplateManager,
+    scheduler: EmailScheduler,
+    magic_link_manager: MagicLinkManager
+) -> Blueprint:
+    bp = Blueprint('email', __name__, url_prefix='/email')
+
+    @bp.route('/templates/', methods=['POST'])
+    async def create_template():
+        data = request.get_json()
+        template = EmailTemplate(**data)
+        created_template = await template_manager.create_template(template)
+        return jsonify(created_template.dict())
+
+    @bp.route('/templates/', methods=['GET'])
+    async def list_templates():
+        skip = request.args.get('skip', 0, type=int)
+        limit = request.args.get('limit', 100, type=int)
+        templates = await template_manager.list_templates(skip, limit)
+        return jsonify([t.dict() for t in templates])
+
+    @bp.route('/schedule/', methods=['POST'])
+    async def schedule_email():
+        data = request.get_json()
+        scheduled_email = ScheduledEmail(**data)
+        result = await scheduler.schedule_email(scheduled_email)
+        return jsonify(result.dict())
+
+    return bp
+
+# Usage
+def create_app():
+    app = Flask(__name__)
+
+    # Initialize managers
+    template_manager = EmailTemplateManager("postgresql://...")
+    email_provider = SendGridProvider({"api_key": "...", "from_email": "..."})
+    scheduler = EmailScheduler(template_manager, email_provider)
+    magic_link_manager = MagicLinkManager(template_manager, "encryption_key")
+
+    # Register blueprint
+    email_bp = create_email_blueprint(template_manager, scheduler, magic_link_manager)
+    app.register_blueprint(email_bp)
+
+    return app
+```
+
+## Utilities and Helpers
+
+### Template Rendering
+
+```python
+from jinja2 import Environment, BaseLoader
+import re
+from typing import Dict, Any
+
+class LiquidTemplateRenderer:
+    def __init__(self):
+        self.env = Environment(loader=BaseLoader())
+
+    def render(self, template_content: str, variables: Dict[str, Any]) -> str:
+        """Render liquid template with variables"""
+        template = self.env.from_string(template_content)
+        return template.render(**variables)
+
+    def validate_template(self, template_content: str) -> Dict[str, Any]:
+        """Validate template syntax"""
+        try:
+            self.env.from_string(template_content)
+            return {"valid": True, "errors": []}
+        except Exception as e:
+            return {"valid": False, "errors": [str(e)]}
+
+    def extract_variables(self, template_content: str) -> List[str]:
+        """Extract variable names from template"""
+        pattern = r'\{\{\s*(\w+)\s*\}\}'
+        return list(set(re.findall(pattern, template_content)))
+```
+
+### Validation Utilities
+
+```python
+import re
+from typing import Dict, Any, List
+from email_validator import validate_email, EmailNotValidError
+
+class ValidationUtils:
+    @staticmethod
+    def validate_email_address(email: str) -> bool:
+        """Validate email address format"""
+        try:
+            validate_email(email)
+            return True
+        except EmailNotValidError:
+            return False
+
+    @staticmethod
+    def validate_template_variables(
+        template: EmailTemplate,
+        variables: Dict[str, Any]
+    ) -> Dict[str, Any]:
+        """Validate template variables against schema"""
+        errors = []
+        warnings = []
+
+        for var_def in template.variables:
+            if var_def.required and var_def.name not in variables:
+                errors.append(f"Required variable '{var_def.name}' is missing")
+            elif var_def.name in variables:
+                value = variables[var_def.name]
+                if not ValidationUtils._validate_variable_type(value, var_def.type):
+                    errors.append(f"Variable '{var_def.name}' has invalid type")
+
+        return {
+            "valid": len(errors) == 0,
+            "errors": errors,
+            "warnings": warnings
+        }
+
+    @staticmethod
+    def _validate_variable_type(value: Any, expected_type: str) -> bool:
+        """Validate individual variable type"""
+        type_validators = {
+            'text': lambda v: isinstance(v, str),
+            'number': lambda v: isinstance(v, (int, float)),
+            'date': lambda v: isinstance(v, str) and ValidationUtils._is_valid_date(v),
+            'boolean': lambda v: isinstance(v, bool),
+            'url': lambda v: isinstance(v, str) and ValidationUtils._is_valid_url(v)
+        }
+
+        validator = type_validators.get(expected_type)
+        return validator(value) if validator else True
+
+    @staticmethod
+    def _is_valid_date(date_str: str) -> bool:
+        """Check if string is valid date"""
+        try:
+            from datetime import datetime
+            datetime.fromisoformat(date_str.replace('Z', '+00:00'))
+            return True
+        except ValueError:
+            return False
+
+    @staticmethod
+    def _is_valid_url(url: str) -> bool:
+        """Check if string is valid URL"""
+        url_pattern = re.compile(
+            r'^https?://'  # http:// or https://
+            r'(?:(?:[A-Z0-9](?:[A-Z0-9-]{0,61}[A-Z0-9])?\.)+[A-Z]{2,6}\.?|'  # domain...
+            r'localhost|'  # localhost...
+            r'\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})'  # ...or ip
+            r'(?::\d+)?'  # optional port
+            r'(?:/?|[/?]\S+)$', re.IGNORECASE)
+        return url_pattern.match(url) is not None
+```
+
+## CLI Tools
+
+### Command Line Interface
+
+```python
+import click
+import asyncio
+from typing import Optional
+
+@click.group()
+def cli():
+    """Email Template Manager CLI"""
+    pass
+
+@cli.command()
+@click.option('--database-url', required=True, help='Database connection URL')
+@click.option('--name', required=True, help='Template name')
+@click.option('--subject', required=True, help='Email subject')
+@click.option('--html-file', required=True, help='HTML template file')
+@click.option('--text-file', help='Text template file')
+def create_template(database_url: str, name: str, subject: str, html_file: str, text_file: Optional[str]):
+    """Create a new email template"""
+    async def _create():
+        manager = EmailTemplateManager(database_url)
+
+        with open(html_file, 'r') as f:
+            html_body = f.read()
+
+        text_body = ""
+        if text_file:
+            with open(text_file, 'r') as f:
+                text_body = f.read()
+
+        template = EmailTemplate(
+            name=name,
+            subject=subject,
+            html_body=html_body,
+            text_body=text_body
+        )
+
+        result = await manager.create_template(template)
+        click.echo(f"Created template: {result.id}")
+
+    asyncio.run(_create())
+
+@cli.command()
+@click.option('--database-url', required=True)
+def process_emails(database_url: str):
+    """Process pending scheduled emails"""
+    async def _process():
+        manager = EmailTemplateManager(database_url)
+        # Initialize email provider from config
+        provider = SendGridProvider({"api_key": "...", "from_email": "..."})
+        scheduler = EmailScheduler(manager, provider)
+
+        result = await scheduler.process_pending_emails()
+        click.echo(f"Processed {result['processed']} emails")
+
+    asyncio.run(_process())
+
+if __name__ == '__main__':
+    cli()
+```
+
+## Testing Framework
+
+### Test Utilities
+
+```python
+import pytest
+from unittest.mock import AsyncMock, MagicMock
+from typing import Dict, Any, Optional
+
+class MockEmailProvider(EmailProvider):
+    def __init__(self):
+        self.sent_emails = []
+        self.delivery_statuses = {}
+
+    async def send_email(self, **kwargs) -> Dict[str, Any]:
+        email_data = kwargs.copy()
+        message_id = f"mock_{len(self.sent_emails)}"
+        email_data['message_id'] = message_id
+        self.sent_emails.append(email_data)
+        return {"message_id": message_id, "status": "sent"}
+
+    async def send_batch(self, emails: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
+        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) -> Dict[str, Any]:
+        return self.delivery_statuses.get(message_id, {"status": "delivered"})
+
+    async def process_webhook(self, payload: Dict[str, Any], signature: str) -> List[Dict[str, Any]]:
+        return [payload]
+
+@pytest.fixture
+def mock_email_provider():
+    return MockEmailProvider()
+
+@pytest.fixture
+def template_manager():
+    # Use in-memory SQLite for testing
+    return EmailTemplateManager("sqlite:///:memory:")
+
+@pytest.fixture
+def sample_template():
+    return EmailTemplate(
+        name="Test Template",
+        subject="Hello {{name}}",
+        html_body="<h1>Hello {{name}}</h1><p>{{message}}</p>",
+        text_body="Hello {{name}}\n\n{{message}}",
+        variables=[
+            TemplateVariable(name="name", type="text", required=True),
+            TemplateVariable(name="message", type="text", required=True)
+        ]
+    )
+
+# Example test
+@pytest.mark.asyncio
+async def test_create_template(template_manager, sample_template):
+    created = await template_manager.create_template(sample_template)
+    assert created.id is not None
+    assert created.name == sample_template.name
+    assert created.subject == sample_template.subject
+```
+
+## Package Configuration
+
+### setup.py
+
+```python
+from setuptools import setup, find_packages
+
+setup(
+    name="email-template-manager",
+    version="1.0.0",
+    description="Universal email template management library",
+    author="Your Name",
+    author_email="your.email@example.com",
+    url="https://github.com/your-org/email-template-manager",
+    packages=find_packages(),
+    install_requires=[
+        "pydantic>=1.8.0",
+        "sqlalchemy>=1.4.0",
+        "alembic>=1.7.0",
+        "jinja2>=3.0.0",
+        "email-validator>=1.1.0",
+        "cryptography>=3.4.0",
+        "click>=8.0.0",
+    ],
+    extras_require={
+        "fastapi": ["fastapi>=0.68.0", "uvicorn>=0.15.0"],
+        "django": ["django>=3.2.0"],
+        "flask": ["flask>=2.0.0"],
+        "sendgrid": ["sendgrid>=6.8.0"],
+        "ses": ["boto3>=1.18.0"],
+        "mailgun": ["requests>=2.26.0"],
+        "postmark": ["postmarker>=0.15.0"],
+        "test": [
+            "pytest>=6.2.0",
+            "pytest-asyncio>=0.15.0",
+            "pytest-cov>=2.12.0",
+        ]
+    },
+    entry_points={
+        "console_scripts": [
+            "email-template-manager=email_template_manager.cli:cli",
+        ],
+    },
+    classifiers=[
+        "Development Status :: 4 - Beta",
+        "Intended Audience :: Developers",
+        "License :: OSI Approved :: MIT License",
+        "Programming Language :: Python :: 3",
+        "Programming Language :: Python :: 3.8",
+        "Programming Language :: Python :: 3.9",
+        "Programming Language :: Python :: 3.10",
+        "Programming Language :: Python :: 3.11",
+    ],
+    python_requires=">=3.8",
+)
+```
+
+This Python SDK provides comprehensive email template management capabilities with support for major Python web frameworks and email providers.