msaas-mailer 0.1.0__tar.gz

msaas_mailer-0.1.0/.gitignore

@@ -0,0 +1,23 @@
+node_modules/
+dist/
+.next/
+.turbo/
+*.pyc
+__pycache__/
+.venv/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+.env
+.env.*
+!.env.example
+!.env.*.example
+!.env.*.template
+.DS_Store
+coverage/
+
+# Runtime artifacts
+logs_llm/
+vectors.db
+vectors.db-shm
+vectors.db-wal

msaas_mailer-0.1.0/PKG-INFO

@@ -0,0 +1,13 @@
+Metadata-Version: 2.4
+Name: msaas-mailer
+Version: 0.1.0
+Summary: Transactional email module with Resend and pre-built templates
+Requires-Python: >=3.12
+Requires-Dist: jinja2>=3.1.0
+Requires-Dist: msaas-api-core
+Requires-Dist: msaas-errors
+Requires-Dist: pydantic>=2.0
+Requires-Dist: resend>=2.0.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'

msaas_mailer-0.1.0/pyproject.toml

@@ -0,0 +1,32 @@
+[project]
+name = "msaas-mailer"
+version = "0.1.0"
+description = "Transactional email module with Resend and pre-built templates"
+requires-python = ">=3.12"
+dependencies = [
+    "msaas-api-core",
+    "msaas-errors",
+    "resend>=2.0.0",
+    "pydantic>=2.0",
+    "jinja2>=3.1.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.23",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/mailer"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.uv.sources]
+msaas-api-core = { workspace = true }
+msaas-errors = { workspace = true }

msaas_mailer-0.1.0/src/mailer/__init__.py

@@ -0,0 +1,17 @@
+"""Willian Email — Transactional email module with Resend and pre-built templates."""
+
+from mailer.config import EmailConfig, init_email
+from mailer.sender import Recipient, SendResult, send_bulk, send_email
+from mailer.templates import EmailTemplate, register_template, render_template
+
+__all__ = [
+    "EmailConfig",
+    "EmailTemplate",
+    "Recipient",
+    "SendResult",
+    "init_email",
+    "register_template",
+    "render_template",
+    "send_bulk",
+    "send_email",
+]

msaas_mailer-0.1.0/src/mailer/config.py

@@ -0,0 +1,44 @@
+"""Email module configuration and initialization."""
+
+from __future__ import annotations
+
+from pydantic import BaseModel
+
+# Global config singleton — set via init_email()
+_config: EmailConfig | None = None
+
+
+class EmailConfig(BaseModel):
+    """Configuration for the email module."""
+
+    api_key: str
+    default_from: str
+    reply_to: str | None = None
+    product_name: str
+    product_url: str
+    logo_url: str | None = None
+    support_email: str | None = None
+
+
+def init_email(config: EmailConfig) -> None:
+    """Initialize the email module with the given configuration.
+
+    Must be called before send_email() or send_bulk(). Configures the Resend
+    SDK and stores settings used by templates (product name, logo, etc.).
+    """
+    import resend
+
+    global _config
+    _config = config
+    resend.api_key = config.api_key
+
+
+def get_config() -> EmailConfig:
+    """Return the current module configuration.
+
+    Raises:
+        RuntimeError: If init_email() has not been called.
+    """
+    if _config is None:
+        raise RuntimeError("Email module not initialized. Call init_email() first.")
+    return _config

msaas_mailer-0.1.0/src/mailer/sender.py

@@ -0,0 +1,121 @@
+"""Email sending via Resend SDK."""
+
+from __future__ import annotations
+
+import logging
+from typing import Literal
+
+import resend
+from pydantic import BaseModel
+
+from mailer.config import get_config
+from mailer.templates import render_template
+
+logger = logging.getLogger(__name__)
+
+
+class SendResult(BaseModel):
+    """Result of a single email send operation."""
+
+    id: str | None = None
+    status: Literal["sent", "failed"]
+    error: str | None = None
+
+
+class Recipient(BaseModel):
+    """A single recipient for bulk email operations."""
+
+    email: str
+    name: str | None = None
+    subject: str
+    data: dict = {}
+
+
+def send_email(
+    to: str | list[str],
+    subject: str,
+    template: str,
+    data: dict | None = None,
+    from_addr: str | None = None,
+) -> SendResult:
+    """Send a transactional email using a named template.
+
+    Args:
+        to: Recipient email address or list of addresses.
+        subject: Email subject line.
+        template: Template name (e.g. "welcome", "invoice").
+        data: Variables passed to the Jinja2 template.
+        from_addr: Override the default sender address.
+
+    Returns:
+        SendResult with delivery id and status.
+    """
+    config = get_config()
+    template_data = {**(data or {})}
+
+    # Inject global template variables from config
+    template_data.setdefault("product_name", config.product_name)
+    template_data.setdefault("product_url", config.product_url)
+    template_data.setdefault("logo_url", config.logo_url)
+    template_data.setdefault("support_email", config.support_email)
+
+    html = render_template(template, template_data)
+
+    params: resend.Emails.SendParams = {
+        "from_": from_addr or config.default_from,
+        "to": [to] if isinstance(to, str) else to,
+        "subject": subject,
+        "html": html,
+    }
+    if config.reply_to:
+        params["reply_to"] = config.reply_to
+
+    try:
+        response = resend.Emails.send(params)
+        email_id = (
+            response.get("id") if isinstance(response, dict) else getattr(response, "id", None)
+        )
+        logger.info("Email sent successfully", extra={"email_id": email_id, "to": to})
+        return SendResult(id=email_id, status="sent")
+    except Exception as exc:
+        logger.error("Failed to send email", extra={"error": str(exc), "to": to})
+        return SendResult(status="failed", error=str(exc))
+
+
+def send_bulk(
+    recipients: list[Recipient],
+    template: str,
+) -> list[SendResult]:
+    """Send the same template to multiple recipients with individual data.
+
+    Each recipient gets their own rendered email. This does NOT use Resend
+    batch API — it sends individually so each recipient can have unique
+    template data.
+
+    Args:
+        recipients: List of Recipient objects with email, subject, and data.
+        template: Template name to render for each recipient.
+
+    Returns:
+        List of SendResult objects, one per recipient (same order).
+    """
+    results: list[SendResult] = []
+    for recipient in recipients:
+        merged_data = {**recipient.data}
+        if recipient.name:
+            merged_data.setdefault("user_name", recipient.name)
+
+        result = send_email(
+            to=recipient.email,
+            subject=recipient.subject,
+            template=template,
+            data=merged_data,
+        )
+        results.append(result)
+
+    sent = sum(1 for r in results if r.status == "sent")
+    logger.info(
+        "Bulk send complete",
+        extra={"total": len(recipients), "sent": sent, "failed": len(recipients) - sent},
+    )
+    return results

msaas_mailer-0.1.0/src/mailer/templates/__init__.py

@@ -0,0 +1,100 @@
+"""Template rendering engine for email templates."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import NamedTuple
+
+from jinja2 import Environment, FileSystemLoader, select_autoescape
+
+# Directory containing built-in HTML templates
+_TEMPLATE_DIR = Path(__file__).parent
+
+# Custom templates registered at runtime
+_custom_templates: dict[str, str] = {}
+
+# Jinja2 environment — lazy-initialized
+_env: Environment | None = None
+
+
+class EmailTemplate(NamedTuple):
+    """Metadata about a registered template."""
+
+    name: str
+    source: str  # "builtin" or "custom"
+
+
+def _get_env() -> Environment:
+    """Return the Jinja2 environment, creating it on first use."""
+    global _env
+    if _env is None:
+        _env = Environment(
+            loader=FileSystemLoader(str(_TEMPLATE_DIR)),
+            autoescape=select_autoescape(["html"]),
+            trim_blocks=True,
+            lstrip_blocks=True,
+        )
+    return _env
+
+
+def render_template(template_name: str, data: dict) -> str:
+    """Render a named template with the given data.
+
+    Looks up custom templates first, then falls back to built-in
+    templates from the templates directory.
+
+    Args:
+        template_name: Name of the template (without .html extension).
+        data: Variables to pass to the Jinja2 template.
+
+    Returns:
+        Rendered HTML string.
+
+    Raises:
+        jinja2.TemplateNotFound: If no template with that name exists.
+    """
+    env = _get_env()
+
+    # Check custom templates first
+    if template_name in _custom_templates:
+        tmpl = env.from_string(_custom_templates[template_name])
+        return tmpl.render(**data)
+
+    # Fall back to file-based template
+    tmpl = env.get_template(f"{template_name}.html")
+    return tmpl.render(**data)
+
+
+def register_template(name: str, html: str) -> None:
+    """Register a custom template at runtime.
+
+    Custom templates take priority over built-in file-based templates
+    with the same name.
+
+    Args:
+        name: Template name (used when calling send_email).
+        html: Raw HTML/Jinja2 template string.
+    """
+    _custom_templates[name] = html
+
+
+def list_templates() -> list[EmailTemplate]:
+    """List all available templates (built-in and custom).
+
+    Returns:
+        List of EmailTemplate named tuples.
+    """
+    templates: list[EmailTemplate] = []
+
+    # Built-in templates from filesystem
+    for path in sorted(_TEMPLATE_DIR.glob("*.html")):
+        if path.name == "base.html":
+            continue
+        name = path.stem
+        templates.append(EmailTemplate(name=name, source="builtin"))
+
+    # Custom templates
+    for name in sorted(_custom_templates):
+        templates.append(EmailTemplate(name=name, source="custom"))
+
+    return templates

msaas_mailer-0.1.0/src/mailer/templates/alert.html

@@ -0,0 +1,83 @@
+{% extends "base.html" %}
+
+{% block preheader %}{{ severity | upper }}: {{ alert_title }}{% endblock %}
+
+{% block content %}
+<!-- Severity banner -->
+{% if severity == "error" %}
+{% set banner_bg = "#fef2f2" %}
+{% set banner_border = "#fca5a5" %}
+{% set banner_text = "#991b1b" %}
+{% set banner_icon = "!" %}
+{% elif severity == "warning" %}
+{% set banner_bg = "#fffbeb" %}
+{% set banner_border = "#fcd34d" %}
+{% set banner_text = "#92400e" %}
+{% set banner_icon = "!" %}
+{% else %}
+{% set banner_bg = "#eff6ff" %}
+{% set banner_border = "#93c5fd" %}
+{% set banner_text = "#1e40af" %}
+{% set banner_icon = "i" %}
+{% endif %}
+
+<table role="presentation" cellspacing="0" cellpadding="0" border="0" width="100%" style="margin: 0 0 28px 0;">
+  <tr>
+    <td style="background-color: {{ banner_bg }}; border-left: 4px solid {{ banner_border }}; border-radius: 0 8px 8px 0; padding: 16px 20px;">
+      <table role="presentation" cellspacing="0" cellpadding="0" border="0" width="100%">
+        <tr>
+          <td style="width: 32px; vertical-align: top; padding-right: 12px;">
+            <div style="width: 28px; height: 28px; border-radius: 50%; background-color: {{ banner_border }}; text-align: center; line-height: 28px; font-size: 14px; font-weight: 700; color: {{ banner_text }};">
+              {{ banner_icon }}
+            </div>
+          </td>
+          <td style="vertical-align: top;">
+            <p style="margin: 0 0 4px 0; font-size: 15px; font-weight: 700; color: {{ banner_text }}; text-transform: uppercase; letter-spacing: 0.3px;">
+              {{ severity | upper }}
+            </p>
+            <p style="margin: 0; font-size: 18px; font-weight: 700; color: {{ banner_text }}; line-height: 1.3;">
+              {{ alert_title }}
+            </p>
+          </td>
+        </tr>
+      </table>
+    </td>
+  </tr>
+</table>
+
+<!-- Greeting -->
+<p style="margin: 0 0 20px 0; font-size: 16px; line-height: 1.6; color: #4a4a5a;">
+  {% if user_name %}Hi {{ user_name }},{% else %}Hi there,{% endif %}
+</p>
+
+<!-- Alert message -->
+<p style="margin: 0 0 28px 0; font-size: 16px; line-height: 1.6; color: #4a4a5a;">
+  {{ alert_message }}
+</p>
+
+<!-- Optional action button -->
+{% if action_url and action_text %}
+<table role="presentation" cellspacing="0" cellpadding="0" border="0" align="center" width="100%">
+  <tr>
+    <td style="text-align: center; padding: 4px 0 16px 0;">
+      {% if severity == "error" %}
+      {% set btn_color = "#dc2626" %}
+      {% elif severity == "warning" %}
+      {% set btn_color = "#d97706" %}
+      {% else %}
+      {% set btn_color = "#6366f1" %}
+      {% endif %}
+      <a href="{{ action_url }}" style="display: inline-block; background-color: {{ btn_color }}; color: #ffffff; font-size: 16px; font-weight: 600; text-decoration: none; padding: 14px 36px; border-radius: 8px; mso-padding-alt: 0; text-align: center;">
+        <!--[if mso]><i style="letter-spacing: 36px; mso-font-width: -100%; mso-text-raise: 26pt;">&nbsp;</i><![endif]-->
+        <span style="mso-text-raise: 13pt;">{{ action_text }}</span>
+        <!--[if mso]><i style="letter-spacing: 36px; mso-font-width: -100%;">&nbsp;</i><![endif]-->
+      </a>
+    </td>
+  </tr>
+</table>
+{% endif %}
+
+<p style="margin: 16px 0 0 0; font-size: 14px; line-height: 1.5; color: #8c8c9a; text-align: center;">
+  This is an automated alert from {{ product_name }}. If you believe this was sent in error, please contact support.
+</p>
+{% endblock %}

msaas_mailer-0.1.0/src/mailer/templates/base.html

@@ -0,0 +1,116 @@
+<!DOCTYPE html>
+<html lang="en" xmlns="http://www.w3.org/1999/xhtml" xmlns:v="urn:schemas-microsoft-com:vml" xmlns:o="urn:schemas-microsoft-com:office:office">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <meta http-equiv="X-UA-Compatible" content="IE=edge">
+  <meta name="x-apple-disable-message-reformatting">
+  <title>{% block title %}{{ product_name }}{% endblock %}</title>
+  <!--[if mso]>
+  <noscript>
+    <xml>
+      <o:OfficeDocumentSettings>
+        <o:PixelsPerInch>96</o:PixelsPerInch>
+      </o:OfficeDocumentSettings>
+    </xml>
+  </noscript>
+  <![endif]-->
+  <style>
+    /* Reset */
+    body, table, td, a { -webkit-text-size-adjust: 100%; -ms-text-size-adjust: 100%; }
+    table, td { mso-table-lspace: 0pt; mso-table-rspace: 0pt; }
+    img { -ms-interpolation-mode: bicubic; border: 0; height: auto; line-height: 100%; outline: none; text-decoration: none; }
+    body { height: 100% !important; margin: 0 !important; padding: 0 !important; width: 100% !important; }
+    a[x-apple-data-detectors] { color: inherit !important; text-decoration: none !important; font-size: inherit !important; font-family: inherit !important; font-weight: inherit !important; line-height: inherit !important; }
+
+    /* Responsive */
+    @media only screen and (max-width: 620px) {
+      .email-container { width: 100% !important; max-width: 100% !important; }
+      .fluid { max-width: 100% !important; height: auto !important; margin-left: auto !important; margin-right: auto !important; }
+      .stack-column { display: block !important; width: 100% !important; max-width: 100% !important; }
+      .center-on-narrow { text-align: center !important; display: block !important; margin-left: auto !important; margin-right: auto !important; float: none !important; }
+      table.center-on-narrow { display: inline-block !important; }
+      .padding-mobile { padding-left: 20px !important; padding-right: 20px !important; }
+    }
+  </style>
+</head>
+<body style="margin: 0; padding: 0; background-color: #f4f5f7; font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif; color: #1a1a2e;">
+
+  <!-- Preheader (hidden text for email preview) -->
+  <div style="display: none; font-size: 1px; line-height: 1px; max-height: 0px; max-width: 0px; opacity: 0; overflow: hidden; mso-hide: all;">
+    {% block preheader %}{% endblock %}
+  </div>
+
+  <!-- Full-width wrapper -->
+  <table role="presentation" cellspacing="0" cellpadding="0" border="0" width="100%" style="background-color: #f4f5f7;">
+    <tr>
+      <td style="padding: 40px 10px;">
+
+        <!-- Email container (max 580px) -->
+        <table class="email-container" role="presentation" cellspacing="0" cellpadding="0" border="0" align="center" width="580" style="max-width: 580px; margin: 0 auto;">
+
+          <!-- Header -->
+          <tr>
+            <td style="padding: 0 0 24px 0; text-align: center;">
+              <table role="presentation" cellspacing="0" cellpadding="0" border="0" align="center">
+                <tr>
+                  {% if logo_url %}
+                  <td style="padding-right: 12px; vertical-align: middle;">
+                    <img src="{{ logo_url }}" alt="{{ product_name }}" width="36" height="36" style="width: 36px; height: 36px; border-radius: 8px;">
+                  </td>
+                  {% endif %}
+                  <td style="vertical-align: middle;">
+                    <a href="{{ product_url }}" style="font-size: 20px; font-weight: 700; color: #1a1a2e; text-decoration: none; letter-spacing: -0.3px;">{{ product_name }}</a>
+                  </td>
+                </tr>
+              </table>
+            </td>
+          </tr>
+
+          <!-- Body -->
+          <tr>
+            <td style="background-color: #ffffff; border-radius: 12px; box-shadow: 0 1px 3px rgba(0, 0, 0, 0.08);">
+              <table role="presentation" cellspacing="0" cellpadding="0" border="0" width="100%">
+                <tr>
+                  <td class="padding-mobile" style="padding: 40px 48px;">
+                    {% block content %}{% endblock %}
+                  </td>
+                </tr>
+              </table>
+            </td>
+          </tr>
+
+          <!-- Footer -->
+          <tr>
+            <td style="padding: 32px 20px 0 20px; text-align: center;">
+              <table role="presentation" cellspacing="0" cellpadding="0" border="0" align="center" width="100%">
+                <tr>
+                  <td style="font-size: 13px; line-height: 20px; color: #8c8c9a; text-align: center;">
+                    <p style="margin: 0 0 8px 0;">
+                      &copy; {{ product_name }}. All rights reserved.
+                    </p>
+                    {% if support_email %}
+                    <p style="margin: 0 0 8px 0;">
+                      Questions? Contact us at <a href="mailto:{{ support_email }}" style="color: #6366f1; text-decoration: none;">{{ support_email }}</a>
+                    </p>
+                    {% endif %}
+                    <p style="margin: 0;">
+                      <a href="{{ product_url }}/unsubscribe" style="color: #8c8c9a; text-decoration: underline;">Unsubscribe</a>
+                      &nbsp;&middot;&nbsp;
+                      <a href="{{ product_url }}/privacy" style="color: #8c8c9a; text-decoration: underline;">Privacy Policy</a>
+                    </p>
+                  </td>
+                </tr>
+              </table>
+            </td>
+          </tr>
+
+        </table>
+        <!-- /Email container -->
+
+      </td>
+    </tr>
+  </table>
+
+</body>
+</html>

msaas_mailer-0.1.0/src/mailer/templates/digest.html

@@ -0,0 +1,70 @@
+{% extends "base.html" %}
+
+{% block preheader %}Your {{ period }} digest from {{ product_name }} — {{ items | length }} updates{% endblock %}
+
+{% block content %}
+<!-- Heading -->
+<h1 style="margin: 0 0 8px 0; font-size: 26px; font-weight: 700; color: #1a1a2e; line-height: 1.3;">
+  Your {{ period }} digest
+</h1>
+
+<p style="margin: 0 0 28px 0; font-size: 16px; line-height: 1.6; color: #4a4a5a;">
+  {% if user_name %}Hi {{ user_name }},{% else %}Hi there,{% endif %}
+</p>
+
+<p style="margin: 0 0 28px 0; font-size: 16px; line-height: 1.6; color: #4a4a5a;">
+  {% if summary_text %}
+  {{ summary_text }}
+  {% else %}
+  Here's what happened since your last digest.
+  {% endif %}
+</p>
+
+<!-- Digest items -->
+{% if items %}
+<table role="presentation" cellspacing="0" cellpadding="0" border="0" width="100%" style="margin: 0 0 32px 0;">
+  {% for item in items %}
+  <tr>
+    <td style="padding: 0 0 {% if not loop.last %}20px{% else %}0{% endif %} 0; border-bottom: {% if not loop.last %}1px solid #f3f4f6{% else %}none{% endif %};">
+      <table role="presentation" cellspacing="0" cellpadding="0" border="0" width="100%">
+        <tr>
+          <td style="padding: 0 16px 0 0; vertical-align: top; width: 36px;">
+            <div style="width: 36px; height: 36px; border-radius: 8px; background-color: #eef2ff; text-align: center; line-height: 36px; font-size: 15px; font-weight: 600; color: #6366f1;">
+              {{ loop.index }}
+            </div>
+          </td>
+          <td style="vertical-align: top; padding: {% if not loop.last %}0 0 20px 0{% else %}0{% endif %};">
+            <p style="margin: 0 0 4px 0;">
+              <a href="{{ item.url }}" style="font-size: 16px; font-weight: 600; color: #1a1a2e; text-decoration: none; line-height: 1.4;">
+                {{ item.title }}
+              </a>
+            </p>
+            <p style="margin: 0; font-size: 14px; line-height: 1.5; color: #6b7280;">
+              {{ item.description }}
+            </p>
+          </td>
+        </tr>
+      </table>
+    </td>
+  </tr>
+  {% endfor %}
+</table>
+{% endif %}
+
+<!-- View all link -->
+<table role="presentation" cellspacing="0" cellpadding="0" border="0" align="center" width="100%">
+  <tr>
+    <td style="text-align: center; padding: 4px 0 16px 0;">
+      <a href="{{ product_url }}" style="display: inline-block; background-color: #6366f1; color: #ffffff; font-size: 16px; font-weight: 600; text-decoration: none; padding: 14px 36px; border-radius: 8px; mso-padding-alt: 0; text-align: center;">
+        <!--[if mso]><i style="letter-spacing: 36px; mso-font-width: -100%; mso-text-raise: 26pt;">&nbsp;</i><![endif]-->
+        <span style="mso-text-raise: 13pt;">View Dashboard</span>
+        <!--[if mso]><i style="letter-spacing: 36px; mso-font-width: -100%;">&nbsp;</i><![endif]-->
+      </a>
+    </td>
+  </tr>
+</table>
+
+<p style="margin: 16px 0 0 0; font-size: 14px; line-height: 1.5; color: #8c8c9a; text-align: center;">
+  You're receiving this because you're subscribed to {{ period }} digests.
+</p>
+{% endblock %}