swiftpy-framework 0.1.0__py3-none-any.whl

swiftpy/mail/transports/__init__.py

@@ -0,0 +1,21 @@
+from __future__ import annotations
+
+from swiftpy.mail.transports.api.base import ApiMailTransport
+from swiftpy.mail.transports.api.mailgun import MailgunTransport
+from swiftpy.mail.transports.api.resend import ResendTransport
+from swiftpy.mail.transports.api.sendgrid import SendGridTransport
+from swiftpy.mail.transports.base import MailTransport
+from swiftpy.mail.transports.console import ConsoleTransport
+from swiftpy.mail.transports.sendmail import SendmailTransport
+from swiftpy.mail.transports.smtp import SMTPTransport
+
+__all__ = [
+    "ApiMailTransport",
+    "ConsoleTransport",
+    "MailTransport",
+    "MailgunTransport",
+    "ResendTransport",
+    "SMTPTransport",
+    "SendGridTransport",
+    "SendmailTransport",
+]

swiftpy/mail/transports/api/__init__.py

@@ -0,0 +1,13 @@
+from __future__ import annotations
+
+from swiftpy.mail.transports.api.base import ApiMailTransport
+from swiftpy.mail.transports.api.mailgun import MailgunTransport
+from swiftpy.mail.transports.api.resend import ResendTransport
+from swiftpy.mail.transports.api.sendgrid import SendGridTransport
+
+__all__ = [
+    "ApiMailTransport",
+    "MailgunTransport",
+    "ResendTransport",
+    "SendGridTransport",
+]

swiftpy/mail/transports/api/base.py

@@ -0,0 +1,194 @@
+from __future__ import annotations
+
+import email.utils
+import html
+import re
+from datetime import UTC, datetime
+from typing import Any
+
+import httpx
+
+from swiftpy.mail.attachments import Attachment
+from swiftpy.mail.exceptions import (
+    AttachmentTooLargeError,
+    MailAuthenticationError,
+    MailConnectionError,
+    MailRateLimitError,
+    MailTimeoutError,
+    MailTransportError,
+    MailValidationError,
+)
+from swiftpy.mail.message import MailMessage
+from swiftpy.mail.transports.base import MailTransport
+
+_HTML_TAG_RE = re.compile(r"<[^>]+>")
+_SECRET_TOKEN_RE = re.compile(
+    r"(?i)(?:"
+    r"bearer\s+[A-Za-z0-9._\-]+"
+    r"|\b(?:sk|rk|pk)_(?:live|test)_[A-Za-z0-9_\-]{6,}"
+    r"|\bkey-[A-Za-z0-9_\-]{6,}"
+    r"|\bSG\.[A-Za-z0-9_.\-]{6,}"
+    r"|(?:api[_-]?key|token|secret|password)\s*[:=]\s*['\"]?[^\s'\";,]+"
+    r")"
+)
+
+
+def _sanitize_error_body(raw_text: str, *, max_len: int = 300) -> str:
+    """Strip HTML tags, redact credentials/tokens, and truncate upstream error bodies."""
+    plain = html.unescape(_HTML_TAG_RE.sub(" ", raw_text))
+    redacted = _SECRET_TOKEN_RE.sub("[REDACTED]", plain)
+    collapsed = re.sub(r"\s+", " ", redacted).strip()
+    if len(collapsed) > max_len:
+        return f"{collapsed[: max_len - 3]}..."
+    return collapsed
+
+
+def _parse_retry_after(raw_header: str | None) -> float | None:
+    """Parse numeric or HTTP-date Retry-After header into seconds."""
+    if not raw_header:
+        return None
+    stripped = raw_header.strip()
+    if not stripped:
+        return None
+    try:
+        return max(0.0, float(stripped))
+    except ValueError:
+        try:
+            parsed_dt = email.utils.parsedate_to_datetime(stripped)
+        except (TypeError, ValueError):
+            return None
+        if parsed_dt.tzinfo is None:
+            parsed_dt = parsed_dt.replace(tzinfo=UTC)
+        return max(0.0, (parsed_dt - datetime.now(UTC)).total_seconds())
+
+
+class ApiMailTransport(MailTransport):
+    """Base transport for HTTP API email service providers."""
+
+    def __init__(
+        self,
+        timeout: float = 30.0,
+        client: httpx.AsyncClient | None = None,
+        default_from: tuple[str, str | None] | None = None,
+        max_attachment_size_bytes: int | None = None,
+        max_message_size_bytes: int | None = None,
+    ) -> None:
+        self.timeout = timeout
+        self._client = client
+        self._owns_client: bool = client is None
+        self._closed: bool = False
+        self.default_from = default_from
+        self.max_attachment_size_bytes = max_attachment_size_bytes
+        self.max_message_size_bytes = max_message_size_bytes
+
+    @staticmethod
+    def _resolve_size_limit(
+        explicit: int | None, config: dict[str, Any], key: str
+    ) -> int | None:
+        if explicit is not None:
+            return explicit
+        raw = config.get(key)
+        return int(raw) if raw is not None else None
+
+    async def _read_attachments_with_limits(
+        self, message: MailMessage
+    ) -> list[tuple[Attachment, bytes]]:
+        """Read attachments and enforce configured per-attachment and total size limits."""
+        total_bytes = len((message.text_body or "").encode("utf-8")) + len(
+            (message.html_body or "").encode("utf-8")
+        )
+        loaded: list[tuple[Attachment, bytes]] = []
+        for att in message.attachments:
+            content = await att.read_bytes(max_size=self.max_attachment_size_bytes)
+            total_bytes += len(content)
+            if (
+                self.max_message_size_bytes is not None
+                and total_bytes > self.max_message_size_bytes
+            ):
+                raise AttachmentTooLargeError(
+                    f"Total email size ({total_bytes} bytes) exceeds limit ({self.max_message_size_bytes} bytes)"
+                )
+            loaded.append((att, content))
+
+        if (
+            self.max_message_size_bytes is not None
+            and total_bytes > self.max_message_size_bytes
+        ):
+            raise AttachmentTooLargeError(
+                f"Total email size ({total_bytes} bytes) exceeds limit ({self.max_message_size_bytes} bytes)"
+            )
+        return loaded
+
+    async def _get_client(self) -> httpx.AsyncClient:
+        if self._closed:
+            raise MailConnectionError("Transport has been closed")
+        if self._client is None or (self._owns_client and self._client.is_closed):
+            self._client = httpx.AsyncClient(timeout=self.timeout)
+            self._owns_client = True
+        elif not self._owns_client and self._client.is_closed:
+            raise MailConnectionError(
+                "External HTTP client provided to transport has been closed"
+            )
+        return self._client
+
+    def _resolve_from(
+        self,
+        from_address: str | None,
+        from_name: str | None,
+    ) -> tuple[str, str | None]:
+        if from_address:
+            return from_address, from_name
+        if self.default_from:
+            return self.default_from[0], from_name or self.default_from[1]
+        raise MailValidationError(
+            "Email message must specify a from_address or have a default configured"
+        )
+
+    def _handle_http_error(self, exc: Exception, provider_name: str) -> None:
+        if isinstance(exc, httpx.HTTPStatusError):
+            code = exc.response.status_code
+            text = _sanitize_error_body(exc.response.text)
+            if code in (401, 403):
+                raise MailAuthenticationError(
+                    f"{provider_name} API authentication failed ({code}): {text}"
+                ) from exc
+            if code in (400, 422):
+                raise MailValidationError(
+                    f"{provider_name} API validation error ({code}): {text}"
+                ) from exc
+            if code == 429:
+                retry_after_val = _parse_retry_after(
+                    exc.response.headers.get("Retry-After")
+                )
+                raise MailRateLimitError(
+                    f"{provider_name} API rate limit exceeded ({code}): {text}",
+                    retry_after=retry_after_val,
+                ) from exc
+            raise MailTransportError(
+                f"{provider_name} API HTTP error ({code}): {text}"
+            ) from exc
+        if isinstance(exc, httpx.TimeoutException):
+            raise MailTimeoutError(
+                f"{provider_name} API request timed out: {exc}"
+            ) from exc
+        if isinstance(exc, httpx.RequestError):
+            raise MailConnectionError(
+                f"{provider_name} API network connection error: {exc}"
+            ) from exc
+        raise MailTransportError(
+            f"Unexpected error communicating with {provider_name}: {exc}"
+        ) from exc
+
+    async def close(self) -> None:
+        """Close the underlying HTTP client if this transport created and owns it."""
+        self._closed = True
+        if (
+            self._owns_client
+            and self._client is not None
+            and not self._client.is_closed
+        ):
+            await self._client.aclose()
+            self._client = None
+
+
+__all__ = ["ApiMailTransport"]

swiftpy/mail/transports/api/mailgun.py

@@ -0,0 +1,158 @@
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+from swiftpy.mail.exceptions import MailConfigurationError, MailValidationError
+from swiftpy.mail.message import MailMessage, format_mail_address
+from swiftpy.mail.models import MailSendResult
+from swiftpy.mail.transports.api.base import ApiMailTransport
+
+type _MultipartFileValue = tuple[str | None, str] | tuple[str | None, bytes, str]
+
+
+class MailgunTransport(ApiMailTransport):
+    """
+    Email delivery transport using Mailgun REST API (https://mailgun.com).
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        domain: str,
+        timeout: float = 30.0,
+        endpoint: str = "https://api.mailgun.net/v3",
+        client: httpx.AsyncClient | None = None,
+        default_from: tuple[str, str | None] | None = None,
+        max_attachment_size_bytes: int | None = None,
+        max_message_size_bytes: int | None = None,
+    ) -> None:
+        super().__init__(
+            timeout=timeout,
+            client=client,
+            default_from=default_from,
+            max_attachment_size_bytes=max_attachment_size_bytes,
+            max_message_size_bytes=max_message_size_bytes,
+        )
+        self.api_key = api_key
+        self.domain = domain
+        self.endpoint = endpoint.rstrip("/")
+
+    @classmethod
+    def from_config(
+        cls,
+        config: dict[str, Any],
+        default_from: tuple[str, str | None] | None = None,
+        max_attachment_size_bytes: int | None = None,
+        max_message_size_bytes: int | None = None,
+    ) -> MailgunTransport:
+        api_key = str(config.get("api_key", ""))
+        domain = str(config.get("domain", ""))
+        timeout = float(config.get("timeout", 30.0))
+        endpoint = str(config.get("endpoint", "https://api.mailgun.net/v3"))
+        return cls(
+            api_key=api_key,
+            domain=domain,
+            timeout=timeout,
+            endpoint=endpoint,
+            default_from=default_from,
+            max_attachment_size_bytes=cls._resolve_size_limit(
+                max_attachment_size_bytes, config, "max_attachment_size_bytes"
+            ),
+            max_message_size_bytes=cls._resolve_size_limit(
+                max_message_size_bytes, config, "max_message_size_bytes"
+            ),
+        )
+
+    async def send(self, message: MailMessage) -> MailSendResult:
+        if not self.api_key:
+            raise MailConfigurationError("Mailgun API key is not configured")
+        if not self.domain:
+            raise MailConfigurationError("Mailgun domain is not configured")
+
+        if not message.to and not message.cc and not message.bcc:
+            raise MailValidationError(
+                "Email message must specify at least one recipient"
+            )
+
+        from_addr, from_name = self._resolve_from(
+            message.from_address, message.from_name
+        )
+        formatted_from = format_mail_address(from_addr, from_name, field_name="from")
+
+        multipart_fields: list[tuple[str, _MultipartFileValue]] = [
+            ("from", (None, formatted_from)),
+            ("subject", (None, message.subject)),
+        ]
+        for recipient in message.to:
+            multipart_fields.append(
+                ("to", (None, format_mail_address(recipient, field_name="to")))
+            )
+        for recipient in message.cc:
+            multipart_fields.append(
+                ("cc", (None, format_mail_address(recipient, field_name="cc")))
+            )
+        for recipient in message.bcc:
+            multipart_fields.append(
+                ("bcc", (None, format_mail_address(recipient, field_name="bcc")))
+            )
+
+        if message.reply_to:
+            multipart_fields.append(
+                (
+                    "h:Reply-To",
+                    (None, format_mail_address(message.reply_to, field_name="reply_to")),
+                )
+            )
+
+        if message.text_body:
+            multipart_fields.append(("text", (None, message.text_body)))
+        if message.html_body:
+            multipart_fields.append(("html", (None, message.html_body)))
+        if not message.text_body and not message.html_body:
+            multipart_fields.append(("text", (None, "")))
+
+        for k, v in message.headers.items():
+            multipart_fields.append((f"h:{k}", (None, str(v))))
+        for tag in message.tags:
+            multipart_fields.append(("o:tag", (None, str(tag))))
+        for k, v in message.metadata.items():
+            multipart_fields.append((f"v:{k}", (None, str(v))))
+
+        loaded_attachments = await self._read_attachments_with_limits(message)
+        for att, content in loaded_attachments:
+            field_name = "inline" if att.disposition == "inline" else "attachment"
+            multipart_fields.append(
+                (field_name, (att.filename, content, att.content_type))
+            )
+
+        url = f"{self.endpoint}/{self.domain}/messages"
+        client = await self._get_client()
+
+        try:
+            response = await client.post(
+                url,
+                files=multipart_fields,
+                auth=("api", self.api_key),
+            )
+            response.raise_for_status()
+            try:
+                res_data = response.json()
+            except (ValueError, KeyError, httpx.DecodingError):
+                res_data = {"raw": response.text}
+            msg_id = str(res_data.get("id", "")) if isinstance(res_data, dict) else ""
+            return MailSendResult(
+                success=True,
+                message_id=msg_id,
+                provider="mailgun",
+                accepted=message.all_recipient_addresses(),
+                rejected=[],
+                raw_response=res_data,
+            )
+        except Exception as exc:
+            self._handle_http_error(exc, "Mailgun")
+            raise  # pragma: no cover
+
+
+__all__ = ["MailgunTransport"]

swiftpy/mail/transports/api/resend.py

@@ -0,0 +1,156 @@
+from __future__ import annotations
+
+import base64
+from typing import Any
+
+import httpx
+
+from swiftpy.mail.exceptions import MailConfigurationError, MailValidationError
+from swiftpy.mail.message import MailMessage, format_mail_address
+from swiftpy.mail.models import MailSendResult
+from swiftpy.mail.transports.api.base import ApiMailTransport
+
+
+class ResendTransport(ApiMailTransport):
+    """
+    Email delivery transport using the Resend REST API (https://resend.com).
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        timeout: float = 30.0,
+        endpoint: str = "https://api.resend.com/emails",
+        client: httpx.AsyncClient | None = None,
+        default_from: tuple[str, str | None] | None = None,
+        max_attachment_size_bytes: int | None = None,
+        max_message_size_bytes: int | None = None,
+    ) -> None:
+        super().__init__(
+            timeout=timeout,
+            client=client,
+            default_from=default_from,
+            max_attachment_size_bytes=max_attachment_size_bytes,
+            max_message_size_bytes=max_message_size_bytes,
+        )
+        self.api_key = api_key
+        self.endpoint = endpoint
+
+    @classmethod
+    def from_config(
+        cls,
+        config: dict[str, Any],
+        default_from: tuple[str, str | None] | None = None,
+        max_attachment_size_bytes: int | None = None,
+        max_message_size_bytes: int | None = None,
+    ) -> ResendTransport:
+        api_key = str(config.get("api_key", ""))
+        timeout = float(config.get("timeout", 30.0))
+        endpoint = str(config.get("endpoint", "https://api.resend.com/emails"))
+        return cls(
+            api_key=api_key,
+            timeout=timeout,
+            endpoint=endpoint,
+            default_from=default_from,
+            max_attachment_size_bytes=cls._resolve_size_limit(
+                max_attachment_size_bytes, config, "max_attachment_size_bytes"
+            ),
+            max_message_size_bytes=cls._resolve_size_limit(
+                max_message_size_bytes, config, "max_message_size_bytes"
+            ),
+        )
+
+    async def send(self, message: MailMessage) -> MailSendResult:
+        if not self.api_key:
+            raise MailConfigurationError("Resend API key is not configured")
+
+        if not message.to and not message.cc and not message.bcc:
+            raise MailValidationError(
+                "Email message must specify at least one recipient"
+            )
+
+        from_addr, from_name = self._resolve_from(
+            message.from_address, message.from_name
+        )
+        formatted_from = format_mail_address(from_addr, from_name, field_name="from")
+
+        payload: dict[str, Any] = {
+            "from": formatted_from,
+            "to": [format_mail_address(r, field_name="to") for r in message.to],
+            "subject": message.subject,
+        }
+
+        if message.cc:
+            payload["cc"] = [
+                format_mail_address(r, field_name="cc") for r in message.cc
+            ]
+        if message.bcc:
+            payload["bcc"] = [
+                format_mail_address(r, field_name="bcc") for r in message.bcc
+            ]
+        if message.reply_to:
+            payload["reply_to"] = format_mail_address(
+                message.reply_to, field_name="reply_to"
+            )
+
+        if message.html_body:
+            payload["html"] = message.html_body
+        if message.text_body:
+            payload["text"] = message.text_body
+        if not message.html_body and not message.text_body:
+            payload["text"] = ""
+
+        if message.headers:
+            payload["headers"] = {str(k): str(v) for k, v in message.headers.items()}
+
+        loaded_attachments = await self._read_attachments_with_limits(message)
+        if loaded_attachments:
+            att_payload: list[dict[str, str]] = []
+            for att, data in loaded_attachments:
+                encoded = base64.b64encode(data).decode("ascii")
+                att_payload.append(
+                    {
+                        "filename": att.filename,
+                        "content": encoded,
+                    }
+                )
+            payload["attachments"] = att_payload
+
+        resend_tags: list[dict[str, str]] = [
+            {"name": tag, "value": "true"} for tag in message.tags
+        ]
+        for meta_key, meta_val in message.metadata.items():
+            resend_tags.append({"name": str(meta_key), "value": str(meta_val)})
+        if resend_tags:
+            payload["tags"] = resend_tags
+
+        headers = {
+            "Authorization": f"Bearer {self.api_key}",
+            "Content-Type": "application/json",
+            "User-Agent": "SwiftPY-Mail/1.0",
+        }
+
+        client = await self._get_client()
+
+        try:
+            response = await client.post(self.endpoint, json=payload, headers=headers)
+            response.raise_for_status()
+            try:
+                res_json = response.json()
+            except (ValueError, KeyError, httpx.DecodingError):
+                res_json = {"raw": response.text}
+            msg_id = str(res_json.get("id", "")) if isinstance(res_json, dict) else ""
+            return MailSendResult(
+                success=True,
+                message_id=msg_id,
+                provider="resend",
+                accepted=message.all_recipient_addresses(),
+                rejected=[],
+                raw_response=res_json,
+            )
+        except Exception as exc:
+            self._handle_http_error(exc, "Resend")
+            raise  # pragma: no cover
+
+
+__all__ = ["ResendTransport"]