hawkapi-mail 0.1.0__py3-none-any.whl

hawkapi_mail/__init__.py

@@ -0,0 +1,95 @@
+"""hawkapi-mail — email plugin for HawkAPI.
+
+Backends: SMTP, AWS SES, SendGrid, Mailgun, Resend, in-memory.
+Extras: Jinja2 templates, persistent outbox + retry worker, webhook handlers.
+"""
+
+from __future__ import annotations
+
+from ._backends import (
+    Backend,
+    InMemoryBackend,
+    MailgunBackend,
+    MailgunConfig,
+    ResendBackend,
+    ResendConfig,
+    SendError,
+    SendGridBackend,
+    SendGridConfig,
+    SendResult,
+    SESBackend,
+    SESConfig,
+    SMTPBackend,
+    SMTPConfig,
+)
+from ._deps import get_mailer
+from ._mailer import Mailer, init_mail, resolve_mailer
+from ._message import Attachment, EmailMessage, format_address, new_message_id
+from ._outbox import (
+    MemoryOutbox,
+    Outbox,
+    OutboxEntry,
+    OutboxWorker,
+    RetryPolicy,
+    SQLiteOutbox,
+)
+from ._templates import TemplateRenderer
+from ._webhooks import (
+    EventKind,
+    SignatureError,
+    WebhookEvent,
+    confirm_ses_subscription,
+    parse_mailgun,
+    parse_resend,
+    parse_sendgrid,
+    parse_ses_sns,
+    verify_mailgun,
+    verify_resend,
+    verify_sendgrid,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Attachment",
+    "Backend",
+    "EmailMessage",
+    "EventKind",
+    "InMemoryBackend",
+    "Mailer",
+    "MailgunBackend",
+    "MailgunConfig",
+    "MemoryOutbox",
+    "Outbox",
+    "OutboxEntry",
+    "OutboxWorker",
+    "ResendBackend",
+    "ResendConfig",
+    "RetryPolicy",
+    "SESBackend",
+    "SESConfig",
+    "SMTPBackend",
+    "SMTPConfig",
+    "SQLiteOutbox",
+    "SendError",
+    "SendGridBackend",
+    "SendGridConfig",
+    "SendResult",
+    "SignatureError",
+    "TemplateRenderer",
+    "WebhookEvent",
+    "__version__",
+    "confirm_ses_subscription",
+    "format_address",
+    "get_mailer",
+    "init_mail",
+    "new_message_id",
+    "parse_mailgun",
+    "parse_resend",
+    "parse_sendgrid",
+    "parse_ses_sns",
+    "resolve_mailer",
+    "verify_mailgun",
+    "verify_resend",
+    "verify_sendgrid",
+]

hawkapi_mail/_backends.py

@@ -0,0 +1,419 @@
+"""Email backends — SMTP, SES, SendGrid, Mailgun, Resend, in-memory."""
+
+from __future__ import annotations
+
+import base64
+import ssl
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any, Protocol
+
+import aiosmtplib
+import httpx
+
+from ._message import EmailMessage
+
+if TYPE_CHECKING:  # pragma: no cover
+    pass
+
+
+class SendError(Exception):
+    """Raised when a backend cannot deliver a message."""
+
+
+@dataclass(slots=True)
+class SendResult:
+    message_id: str
+    provider: str
+    provider_message_id: str = ""
+    raw_response: Any = None
+
+
+class Backend(Protocol):
+    name: str
+
+    async def send(self, message: EmailMessage) -> SendResult: ...
+    async def close(self) -> None: ...
+
+
+# ---------------------------------------------------------------------------
+# SMTP
+# ---------------------------------------------------------------------------
+
+
+@dataclass(slots=True)
+class SMTPConfig:
+    host: str = "localhost"
+    port: int = 25
+    username: str = ""
+    password: str = ""
+    use_tls: bool = False  # implicit TLS / SMTPS (port 465)
+    start_tls: bool = False  # STARTTLS (port 587)
+    timeout: float = 30.0
+    validate_certs: bool = True
+
+
+@dataclass
+class SMTPBackend:
+    config: SMTPConfig
+    name: str = "smtp"
+
+    async def send(self, message: EmailMessage) -> SendResult:
+        if not message.sender:
+            raise SendError("sender required for SMTP")
+        ctx = ssl.create_default_context()
+        if not self.config.validate_certs:
+            ctx.check_hostname = False
+            ctx.verify_mode = ssl.CERT_NONE
+        try:
+            await aiosmtplib.send(
+                message.to_mime(),
+                sender=message.sender,
+                recipients=message.all_recipients(),
+                hostname=self.config.host,
+                port=self.config.port,
+                username=self.config.username or None,
+                password=self.config.password or None,
+                use_tls=self.config.use_tls,
+                start_tls=self.config.start_tls,
+                timeout=self.config.timeout,
+                tls_context=ctx,
+            )
+        except aiosmtplib.SMTPException as exc:
+            raise SendError(f"SMTP error: {exc}") from exc
+        return SendResult(message_id=message.message_id, provider="smtp")
+
+    async def close(self) -> None:
+        return None
+
+
+# ---------------------------------------------------------------------------
+# Shared HTTP helper
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class _HTTPMixin:
+    _client: httpx.AsyncClient | None = field(default=None, init=False)
+
+    def _get_client(self, timeout: float) -> httpx.AsyncClient:
+        if self._client is None:
+            self._client = httpx.AsyncClient(timeout=timeout)
+        return self._client
+
+    async def close(self) -> None:
+        if self._client is not None:
+            await self._client.aclose()
+            self._client = None
+
+
+# ---------------------------------------------------------------------------
+# AWS SES (raw send via boto3)
+# ---------------------------------------------------------------------------
+
+
+@dataclass(slots=True)
+class SESConfig:
+    region: str = "us-east-1"
+    aws_access_key_id: str = ""
+    aws_secret_access_key: str = ""
+    configuration_set: str = ""
+
+
+@dataclass
+class SESBackend:
+    config: SESConfig
+    name: str = "ses"
+    _client: Any = field(default=None, init=False)
+
+    def _get_client(self) -> Any:
+        if self._client is None:
+            try:
+                import boto3
+            except ImportError as exc:  # pragma: no cover
+                raise SendError("boto3 not installed; pip install 'hawkapi-mail[ses]'") from exc
+            kw: dict[str, Any] = {"region_name": self.config.region}
+            if self.config.aws_access_key_id:
+                kw["aws_access_key_id"] = self.config.aws_access_key_id
+            if self.config.aws_secret_access_key:
+                kw["aws_secret_access_key"] = self.config.aws_secret_access_key
+            self._client = boto3.client("ses", **kw)
+        return self._client
+
+    async def send(self, message: EmailMessage) -> SendResult:
+        client = self._get_client()
+        raw = message.to_mime()
+        kw: dict[str, Any] = {
+            "Source": message.sender,
+            "Destinations": message.all_recipients(),
+            "RawMessage": {"Data": raw},
+        }
+        if self.config.configuration_set:
+            kw["ConfigurationSetName"] = self.config.configuration_set
+        try:
+            resp = client.send_raw_email(**kw)
+        except Exception as exc:  # pragma: no cover - network
+            raise SendError(f"SES error: {exc}") from exc
+        return SendResult(
+            message_id=message.message_id,
+            provider="ses",
+            provider_message_id=resp.get("MessageId", ""),
+            raw_response=resp,
+        )
+
+    async def close(self) -> None:
+        self._client = None
+
+
+# ---------------------------------------------------------------------------
+# SendGrid (HTTP API v3)
+# ---------------------------------------------------------------------------
+
+
+@dataclass(slots=True)
+class SendGridConfig:
+    api_key: str
+    base_url: str = "https://api.sendgrid.com"
+    timeout: float = 30.0
+
+
+@dataclass
+class SendGridBackend(_HTTPMixin):
+    config: SendGridConfig = field(default_factory=lambda: SendGridConfig(api_key=""))
+    name: str = "sendgrid"
+
+    async def send(self, message: EmailMessage) -> SendResult:
+        payload = _sendgrid_payload(message)
+        client = self._get_client(self.config.timeout)
+        resp = await client.post(
+            f"{self.config.base_url}/v3/mail/send",
+            headers={"Authorization": f"Bearer {self.config.api_key}"},
+            json=payload,
+        )
+        if resp.status_code >= 300:
+            raise SendError(f"SendGrid {resp.status_code}: {resp.text}")
+        provider_id = resp.headers.get("x-message-id", "")
+        return SendResult(
+            message_id=message.message_id,
+            provider="sendgrid",
+            provider_message_id=provider_id,
+            raw_response={"status_code": resp.status_code, "headers": dict(resp.headers)},
+        )
+
+
+def _sendgrid_payload(message: EmailMessage) -> dict[str, Any]:
+    personalizations: dict[str, Any] = {"to": [{"email": e} for e in message.to]}
+    if message.cc:
+        personalizations["cc"] = [{"email": e} for e in message.cc]
+    if message.bcc:
+        personalizations["bcc"] = [{"email": e} for e in message.bcc]
+    content: list[dict[str, str]] = []
+    if message.text_body:
+        content.append({"type": "text/plain", "value": message.text_body})
+    if message.html_body:
+        content.append({"type": "text/html", "value": message.html_body})
+    if not content:
+        content.append({"type": "text/plain", "value": ""})
+    body: dict[str, Any] = {
+        "personalizations": [personalizations],
+        "from": {"email": message.sender},
+        "subject": message.subject,
+        "content": content,
+    }
+    if message.reply_to:
+        body["reply_to"] = {"email": message.reply_to[0]}
+    if message.attachments:
+        body["attachments"] = [
+            {
+                "content": base64.b64encode(a.content).decode("ascii"),
+                "filename": a.filename,
+                "type": a.mime_type,
+                "disposition": "inline" if a.inline else "attachment",
+                **({"content_id": a.content_id.strip("<>")} if a.inline and a.content_id else {}),
+            }
+            for a in message.attachments
+        ]
+    if message.tags:
+        body["categories"] = list(message.tags)
+    if message.metadata:
+        body["custom_args"] = dict(message.metadata)
+    if message.headers:
+        body["headers"] = dict(message.headers)
+    return body
+
+
+# ---------------------------------------------------------------------------
+# Mailgun (HTTP API v3)
+# ---------------------------------------------------------------------------
+
+
+@dataclass(slots=True)
+class MailgunConfig:
+    api_key: str
+    domain: str
+    base_url: str = "https://api.mailgun.net"
+    timeout: float = 30.0
+
+
+@dataclass
+class MailgunBackend(_HTTPMixin):
+    config: MailgunConfig = field(default_factory=lambda: MailgunConfig(api_key="", domain=""))
+    name: str = "mailgun"
+
+    async def send(self, message: EmailMessage) -> SendResult:
+        data: list[tuple[str, str]] = [
+            ("from", message.sender),
+            ("subject", message.subject),
+        ]
+        for r in message.to:
+            data.append(("to", r))
+        for r in message.cc:
+            data.append(("cc", r))
+        for r in message.bcc:
+            data.append(("bcc", r))
+        if message.text_body:
+            data.append(("text", message.text_body))
+        if message.html_body:
+            data.append(("html", message.html_body))
+        if message.reply_to:
+            data.append(("h:Reply-To", ", ".join(message.reply_to)))
+        for k, v in message.headers.items():
+            data.append((f"h:{k}", v))
+        for tag in message.tags:
+            data.append(("o:tag", tag))
+        for k, v in message.metadata.items():
+            data.append((f"v:{k}", v))
+        files: list[tuple[str, tuple[str, bytes, str]]] = []
+        for a in message.attachments:
+            field_name = "inline" if a.inline else "attachment"
+            files.append((field_name, (a.filename, a.content, a.mime_type)))
+        client = self._get_client(self.config.timeout)
+        if files:
+            resp = await client.post(
+                f"{self.config.base_url}/v3/{self.config.domain}/messages",
+                auth=("api", self.config.api_key),
+                data=data,  # type: ignore[arg-type]
+                files=files,
+            )
+        else:
+            from urllib.parse import urlencode
+
+            body = urlencode(data).encode("utf-8")
+            resp = await client.post(
+                f"{self.config.base_url}/v3/{self.config.domain}/messages",
+                auth=("api", self.config.api_key),
+                content=body,
+                headers={"Content-Type": "application/x-www-form-urlencoded"},
+            )
+        if resp.status_code >= 300:
+            raise SendError(f"Mailgun {resp.status_code}: {resp.text}")
+        body = resp.json()
+        return SendResult(
+            message_id=message.message_id,
+            provider="mailgun",
+            provider_message_id=body.get("id", ""),
+            raw_response=body,
+        )
+
+
+# ---------------------------------------------------------------------------
+# Resend (HTTP API)
+# ---------------------------------------------------------------------------
+
+
+@dataclass(slots=True)
+class ResendConfig:
+    api_key: str
+    base_url: str = "https://api.resend.com"
+    timeout: float = 30.0
+
+
+@dataclass
+class ResendBackend(_HTTPMixin):
+    config: ResendConfig = field(default_factory=lambda: ResendConfig(api_key=""))
+    name: str = "resend"
+
+    async def send(self, message: EmailMessage) -> SendResult:
+        body: dict[str, Any] = {
+            "from": message.sender,
+            "to": message.to,
+            "subject": message.subject,
+        }
+        if message.cc:
+            body["cc"] = message.cc
+        if message.bcc:
+            body["bcc"] = message.bcc
+        if message.reply_to:
+            body["reply_to"] = message.reply_to
+        if message.html_body:
+            body["html"] = message.html_body
+        if message.text_body:
+            body["text"] = message.text_body
+        if message.tags:
+            body["tags"] = [{"name": "tag", "value": t} for t in message.tags]
+        if message.headers:
+            body["headers"] = dict(message.headers)
+        if message.attachments:
+            body["attachments"] = [
+                {
+                    "filename": a.filename,
+                    "content": base64.b64encode(a.content).decode("ascii"),
+                    "content_type": a.mime_type,
+                }
+                for a in message.attachments
+            ]
+        client = self._get_client(self.config.timeout)
+        resp = await client.post(
+            f"{self.config.base_url}/emails",
+            headers={"Authorization": f"Bearer {self.config.api_key}"},
+            json=body,
+        )
+        if resp.status_code >= 300:
+            raise SendError(f"Resend {resp.status_code}: {resp.text}")
+        data = resp.json()
+        return SendResult(
+            message_id=message.message_id,
+            provider="resend",
+            provider_message_id=data.get("id", ""),
+            raw_response=data,
+        )
+
+
+# ---------------------------------------------------------------------------
+# In-memory (test outbox)
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class InMemoryBackend:
+    """Backend that captures messages instead of sending them — perfect for tests."""
+
+    name: str = "memory"
+    sent: list[EmailMessage] = field(default_factory=list)
+
+    async def send(self, message: EmailMessage) -> SendResult:
+        self.sent.append(message)
+        return SendResult(message_id=message.message_id, provider="memory")
+
+    async def close(self) -> None:
+        return None
+
+    def clear(self) -> None:
+        self.sent.clear()
+
+
+__all__ = [
+    "Backend",
+    "InMemoryBackend",
+    "MailgunBackend",
+    "MailgunConfig",
+    "ResendBackend",
+    "ResendConfig",
+    "SESBackend",
+    "SESConfig",
+    "SMTPBackend",
+    "SMTPConfig",
+    "SendError",
+    "SendGridBackend",
+    "SendGridConfig",
+    "SendResult",
+]

hawkapi_mail/_deps.py

@@ -0,0 +1,17 @@
+"""DI helpers for handlers."""
+
+from __future__ import annotations
+
+from hawkapi import HTTPException, Request
+
+from ._mailer import Mailer, resolve_mailer
+
+
+def get_mailer(request: Request) -> Mailer:
+    mailer = resolve_mailer(request.scope.get("app"))
+    if mailer is None:
+        raise HTTPException(500, detail="Mailer not configured — call init_mail(app, ...) first")
+    return mailer
+
+
+__all__ = ["get_mailer"]

hawkapi_mail/_mailer.py

@@ -0,0 +1,171 @@
+"""High-level Mailer + plugin entry point."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from ._backends import Backend, InMemoryBackend, SendResult
+from ._message import Attachment, EmailMessage
+from ._outbox import Outbox, OutboxWorker, RetryPolicy
+from ._templates import TemplateRenderer
+
+
+@dataclass
+class Mailer:
+    backend: Backend
+    default_sender: str = ""
+    templates: TemplateRenderer | None = None
+    outbox: Outbox | None = None
+    worker: OutboxWorker | None = None
+    retry: RetryPolicy = field(default_factory=RetryPolicy)
+
+    async def send(
+        self,
+        message: EmailMessage,
+        *,
+        deferred: bool = False,
+    ) -> SendResult | int:
+        """Send ``message``. When ``deferred`` is True and an outbox is attached,
+        enqueue the message instead and return the outbox entry id."""
+        if not message.sender and self.default_sender:
+            message.sender = self.default_sender
+        if deferred:
+            if self.outbox is None:
+                raise RuntimeError("deferred=True but no outbox configured")
+            return await self.outbox.enqueue(message)
+        return await self.backend.send(message)
+
+    async def send_template(
+        self,
+        template: str,
+        *,
+        context: dict[str, Any] | None = None,
+        subject: str,
+        sender: str = "",
+        to: str | Iterable[str] = (),
+        cc: str | Iterable[str] = (),
+        bcc: str | Iterable[str] = (),
+        reply_to: str | Iterable[str] = (),
+        text_template: str | None = None,
+        attachments: Iterable[Attachment] = (),
+        tags: Iterable[str] = (),
+        metadata: dict[str, str] | None = None,
+        headers: dict[str, str] | None = None,
+        deferred: bool = False,
+    ) -> SendResult | int:
+        if self.templates is None:
+            raise RuntimeError("send_template called but no TemplateRenderer is configured")
+        ctx = dict(context or {})
+        html = await self.templates.render_async(template, **ctx)
+        text = await self.templates.render_async(text_template, **ctx) if text_template else ""
+        msg = EmailMessage.build(
+            subject=subject,
+            sender=sender or self.default_sender,
+            to=to,
+            cc=cc,
+            bcc=bcc,
+            reply_to=reply_to,
+            text=text,
+            html=html,
+            attachments=attachments,
+            tags=tags,
+            metadata=metadata,
+            headers=headers,
+        )
+        return await self.send(msg, deferred=deferred)
+
+    async def attach_file(
+        self,
+        message: EmailMessage,
+        path: str | Path,
+        *,
+        filename: str | None = None,
+        mime_type: str | None = None,
+        inline: bool = False,
+    ) -> Attachment:
+        return message.add_attachment(path, filename=filename, mime_type=mime_type, inline=inline)
+
+    async def shutdown(self) -> None:
+        if self.worker is not None:
+            await self.worker.stop()
+        await self.backend.close()
+        if self.outbox is not None:
+            await self.outbox.close()
+
+
+# ---------------------------------------------------------------------------
+# Plugin registry + DI helpers
+# ---------------------------------------------------------------------------
+
+
+class _StateNamespace:
+    mail: Any
+
+
+_ACTIVE_MAILERS: dict[int, Mailer] = {}
+_LAST_MAILER: list[Mailer | None] = [None]
+
+
+def init_mail(
+    app: Any,
+    *,
+    backend: Backend | None = None,
+    default_sender: str = "",
+    templates: TemplateRenderer | None = None,
+    outbox: Outbox | None = None,
+    retry: RetryPolicy | None = None,
+    start_worker: bool = False,
+) -> Mailer:
+    """Attach a Mailer to ``app.state.mail`` and register it for DI lookup.
+
+    When ``outbox`` is provided and ``start_worker=True`` the OutboxWorker is
+    started during the HawkAPI startup phase via :pyfunc:`app.on_startup`.
+    """
+    if backend is None:
+        backend = InMemoryBackend()
+    mailer = Mailer(
+        backend=backend,
+        default_sender=default_sender,
+        templates=templates,
+        outbox=outbox,
+        retry=retry or RetryPolicy(),
+    )
+    if outbox is not None:
+        mailer.worker = OutboxWorker(outbox=outbox, backend=backend, retry=mailer.retry)
+    if getattr(app, "state", None) is None:
+        app.state = _StateNamespace()
+    app.state.mail = mailer
+    _ACTIVE_MAILERS[id(app)] = mailer
+    _LAST_MAILER[0] = mailer
+
+    if start_worker and mailer.worker is not None and hasattr(app, "on_startup"):
+        worker = mailer.worker
+
+        def _start() -> None:
+            worker.start()
+
+        async def _stop() -> None:
+            await worker.stop()
+
+        app.on_startup(_start)
+        if hasattr(app, "on_shutdown"):
+            app.on_shutdown(_stop)
+    return mailer
+
+
+def resolve_mailer(app: Any) -> Mailer | None:
+    if app is None:
+        return _LAST_MAILER[0]
+    mailer = _ACTIVE_MAILERS.get(id(app))
+    if mailer is not None:
+        return mailer
+    state = getattr(app, "state", None)
+    if state is not None and hasattr(state, "mail"):
+        return state.mail  # type: ignore[no-any-return]
+    return _LAST_MAILER[0]
+
+
+__all__ = ["Mailer", "init_mail", "resolve_mailer"]