kstlib 0.0.1a0__py3-none-any.whl → 1.0.0__py3-none-any.whl

kstlib/mail/transports/gmail.py

@@ -0,0 +1,268 @@
+"""Gmail API transport for async email delivery via OAuth2.
+
+Send emails through the Gmail API using OAuth2 authentication. This transport
+integrates with the kstlib.auth module for token management.
+
+Requirements:
+    pip install httpx
+
+OAuth2 Scopes:
+    https://www.googleapis.com/auth/gmail.send
+
+API Documentation:
+    https://developers.google.com/gmail/api/reference/rest/v1/users.messages/send
+
+Examples:
+    Using a Token directly::
+
+        from kstlib.auth import Token
+        from kstlib.mail.transports import GmailTransport
+
+        token = Token(access_token="ya29.xxx", scope=["gmail.send"])
+        transport = GmailTransport(token=token)
+        await transport.send(message)
+
+    Using TokenStorage from kstlib.auth::
+
+        from kstlib.auth import OIDCProvider, AuthSession
+        from kstlib.mail.transports import GmailTransport
+
+        provider = OIDCProvider.from_config("google")
+        with AuthSession(provider) as session:
+            token = provider.get_token()
+            transport = GmailTransport(token=token)
+            await transport.send(message)
+"""
+
+from __future__ import annotations
+
+import base64
+import logging
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from kstlib.logging import TRACE_LEVEL
+from kstlib.mail.exceptions import MailConfigurationError, MailTransportError
+from kstlib.mail.transport import AsyncMailTransport, handle_http_error_response
+from kstlib.utils.http_trace import create_trace_event_hooks
+
+if TYPE_CHECKING:
+    from email.message import EmailMessage
+
+    import httpx
+
+    from kstlib.auth import Token
+
+__all__ = ["GmailTransport"]
+
+log = logging.getLogger(__name__)
+
+GMAIL_API_URL = "https://gmail.googleapis.com/gmail/v1/users/me/messages/send"
+
+
+@dataclass(frozen=True, slots=True)
+class GmailResponse:
+    """Response from Gmail API after sending an email.
+
+    Attributes:
+        id: The immutable ID of the sent message.
+        thread_id: The ID of the thread the message belongs to.
+        label_ids: List of label IDs applied to this message.
+    """
+
+    id: str
+    thread_id: str
+    label_ids: list[str]
+
+
+class GmailTransport(AsyncMailTransport):
+    """Async transport for sending emails via Gmail API.
+
+    Uses OAuth2 Bearer token authentication. The token must have the
+    'https://www.googleapis.com/auth/gmail.send' scope.
+
+    Args:
+        token: OAuth2 token from kstlib.auth module.
+        base_url: API endpoint URL (default: Gmail send endpoint).
+        timeout: Request timeout in seconds (default: 30.0).
+
+    Raises:
+        MailConfigurationError: If token is missing or invalid.
+
+    Examples:
+        Basic send::
+
+            from kstlib.auth import Token
+            from kstlib.mail.transports import GmailTransport
+
+            token = Token(access_token="ya29.xxx")
+            transport = GmailTransport(token=token)
+
+            message = EmailMessage()
+            message["From"] = "sender@gmail.com"
+            message["To"] = "recipient@example.com"
+            message["Subject"] = "Hello"
+            message.set_content("Email body")
+
+            await transport.send(message)
+
+        With token refresh callback::
+
+            async def refresh_token() -> Token:
+                # Refresh logic using kstlib.auth
+                return new_token
+
+            transport = GmailTransport(
+                token=token,
+                on_token_refresh=refresh_token,
+            )
+    """
+
+    def __init__(
+        self,
+        token: Token,
+        *,
+        base_url: str = GMAIL_API_URL,
+        timeout: float = 30.0,
+    ) -> None:
+        """Initialize the Gmail transport.
+
+        Args:
+            token: OAuth2 token with gmail.send scope.
+            base_url: API endpoint URL.
+            timeout: Request timeout in seconds.
+
+        Raises:
+            MailConfigurationError: If token is None or has no access_token.
+        """
+        if token is None:
+            raise MailConfigurationError("OAuth2 token is required for GmailTransport")
+
+        if not token.access_token:
+            raise MailConfigurationError("Token must have an access_token")
+
+        self._token = token
+        self._base_url = base_url
+        self._timeout = timeout
+        self._last_response: GmailResponse | None = None
+
+    @property
+    def token(self) -> Token:
+        """Return the current OAuth2 token."""
+        return self._token
+
+    @property
+    def last_response(self) -> GmailResponse | None:
+        """Return the response from the last successful send."""
+        return self._last_response
+
+    def update_token(self, token: Token) -> None:
+        """Update the OAuth2 token (e.g., after refresh).
+
+        Args:
+            token: New OAuth2 token.
+        """
+        self._token = token
+
+    async def send(self, message: EmailMessage) -> None:
+        """Send an email via the Gmail API.
+
+        Encodes the EmailMessage in base64url format and posts it to the
+        Gmail API. The sender must match the authenticated user's email
+        address (or an alias).
+
+        When TRACE logging is enabled, detailed HTTP request/response
+        information is logged including headers and body.
+
+        Args:
+            message: The email message to send.
+
+        Raises:
+            MailTransportError: If the API request fails.
+            MailConfigurationError: If httpx is not installed.
+        """
+        try:
+            import httpx
+        except ImportError as e:
+            raise MailConfigurationError("httpx is required for GmailTransport. Install with: pip install httpx") from e
+
+        # Check token expiration
+        if self._token.is_expired:
+            log.warning("OAuth2 token is expired, request may fail")
+
+        # Encode message as base64url
+        raw_message = self._encode_message(message)
+        payload = {"raw": raw_message}
+
+        headers = {
+            "Authorization": f"Bearer {self._token.access_token}",
+            "Content-Type": "application/json",
+        }
+
+        # Setup trace logging if enabled
+        event_hooks, trace_enabled = create_trace_event_hooks(log, TRACE_LEVEL)
+        if trace_enabled:
+            log.log(TRACE_LEVEL, "[Gmail] Sending email via Gmail API")
+            log.log(TRACE_LEVEL, "[Gmail] From: %s, To: %s", message.get("From"), message.get("To"))
+
+        try:
+            async with httpx.AsyncClient(timeout=self._timeout, event_hooks=event_hooks) as client:
+                response = await client.post(
+                    self._base_url,
+                    json=payload,
+                    headers=headers,
+                )
+
+                if response.status_code == 401:
+                    raise MailTransportError("Gmail API authentication failed. Token may be expired or revoked.")
+
+                if response.status_code >= 400:
+                    self._handle_error_response(response)
+
+                data = response.json()
+                self._last_response = GmailResponse(
+                    id=data.get("id", ""),
+                    thread_id=data.get("threadId", ""),
+                    label_ids=data.get("labelIds", []),
+                )
+                log.debug("Email sent via Gmail API: %s", self._last_response.id)
+                if trace_enabled:
+                    log.log(TRACE_LEVEL, "[Gmail] Message sent successfully, id=%s", self._last_response.id)
+
+        except httpx.TimeoutException as e:
+            if trace_enabled:
+                log.log(TRACE_LEVEL, "[Gmail] Timeout error: %s", e)
+            raise MailTransportError(f"Gmail API timeout: {e}") from e
+        except httpx.RequestError as e:
+            if trace_enabled:
+                log.log(TRACE_LEVEL, "[Gmail] Request error: %s", e)
+            raise MailTransportError(f"Gmail API request failed: {e}") from e
+
+    def _encode_message(self, message: EmailMessage) -> str:
+        """Encode EmailMessage to base64url string.
+
+        Gmail API expects the raw RFC 2822 message encoded in base64url
+        (URL-safe base64 without padding).
+
+        Args:
+            message: The email message.
+
+        Returns:
+            Base64url encoded message string.
+        """
+        raw_bytes = message.as_bytes()
+        # base64url encoding (URL-safe, no padding)
+        encoded = base64.urlsafe_b64encode(raw_bytes).decode("ascii")
+        # Remove padding (Gmail API expects no padding)
+        return encoded.rstrip("=")
+
+    def _handle_error_response(self, response: httpx.Response) -> None:
+        """Handle error response from Gmail API.
+
+        Args:
+            response: The HTTP response.
+
+        Raises:
+            MailTransportError: Always raises with error details.
+        """
+        handle_http_error_response(response, "Gmail", log, extract_code=True)

kstlib/mail/transports/resend.py

@@ -0,0 +1,324 @@
+"""Resend.com API transport for async email delivery.
+
+Resend is a modern email API for developers. This transport sends emails
+via the Resend REST API using async HTTP requests.
+
+Requirements:
+    pip install httpx
+
+API Documentation:
+    https://resend.com/docs/api-reference/emails/send-email
+
+Examples:
+    Basic usage with API key::
+
+        from kstlib.mail.transports import ResendTransport
+
+        transport = ResendTransport(api_key="re_123456789")
+
+        # Use with MailBuilder
+        mail = MailBuilder(transport=transport)
+        await mail.sender("you@example.com").to("user@example.com").send_async()
+
+    With environment variable::
+
+        import os
+        transport = ResendTransport(api_key=os.environ["RESEND_API_KEY"])
+"""
+
+from __future__ import annotations
+
+import base64
+import logging
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any
+
+from kstlib.logging import TRACE_LEVEL
+from kstlib.mail.exceptions import MailConfigurationError, MailTransportError
+from kstlib.mail.transport import AsyncMailTransport, handle_http_error_response
+from kstlib.utils.http_trace import create_trace_event_hooks
+
+if TYPE_CHECKING:
+    from email.message import EmailMessage
+
+    import httpx
+
+__all__ = ["ResendTransport"]
+
+log = logging.getLogger(__name__)
+
+RESEND_API_URL = "https://api.resend.com/emails"
+
+
+@dataclass(frozen=True, slots=True)
+class ResendResponse:
+    """Response from Resend API after sending an email.
+
+    Attributes:
+        id: The unique ID assigned to the sent email.
+    """
+
+    id: str
+
+
+class ResendTransport(AsyncMailTransport):
+    """Async transport for sending emails via Resend.com API.
+
+    Resend provides a simple REST API for sending transactional emails.
+    This transport converts EmailMessage objects to Resend's JSON format
+    and sends them asynchronously using httpx.
+
+    Args:
+        api_key: Resend API key (starts with 're_').
+        base_url: API base URL (default: https://api.resend.com/emails).
+        timeout: Request timeout in seconds (default: 30.0).
+
+    Examples:
+        Basic send::
+
+            transport = ResendTransport(api_key="re_123456789")
+
+            message = EmailMessage()
+            message["From"] = "sender@example.com"
+            message["To"] = "recipient@example.com"
+            message["Subject"] = "Hello"
+            message.set_content("Plain text body")
+
+            await transport.send(message)
+
+        With HTML content::
+
+            message = EmailMessage()
+            message["From"] = "sender@example.com"
+            message["To"] = "recipient@example.com"
+            message["Subject"] = "Welcome"
+            message.set_content("Plain text fallback")
+            message.add_alternative("<h1>Welcome!</h1>", subtype="html")
+
+            await transport.send(message)
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str = RESEND_API_URL,
+        timeout: float = 30.0,
+    ) -> None:
+        """Initialize the Resend transport.
+
+        Args:
+            api_key: Resend API key.
+            base_url: API endpoint URL.
+            timeout: Request timeout in seconds.
+
+        Raises:
+            MailConfigurationError: If api_key is empty.
+        """
+        if not api_key:
+            raise MailConfigurationError("Resend API key is required")
+
+        self._api_key = api_key
+        self._base_url = base_url
+        self._timeout = timeout
+        self._last_response: ResendResponse | None = None
+
+    @property
+    def last_response(self) -> ResendResponse | None:
+        """Return the response from the last successful send."""
+        return self._last_response
+
+    async def send(self, message: EmailMessage) -> None:
+        """Send an email via the Resend API.
+
+        Converts the EmailMessage to Resend's JSON format and posts it
+        to the API. Supports plain text, HTML, and attachments.
+
+        When TRACE logging is enabled, detailed HTTP request/response
+        information is logged including headers and body.
+
+        Args:
+            message: The email message to send.
+
+        Raises:
+            MailTransportError: If the API request fails.
+            MailConfigurationError: If required fields are missing.
+        """
+        try:
+            import httpx
+        except ImportError as e:
+            raise MailConfigurationError(
+                "httpx is required for ResendTransport. Install with: pip install httpx"
+            ) from e
+
+        payload = self._build_payload(message)
+
+        headers = {
+            "Authorization": f"Bearer {self._api_key}",
+            "Content-Type": "application/json",
+        }
+
+        # Setup trace logging if enabled
+        event_hooks, trace_enabled = create_trace_event_hooks(log, TRACE_LEVEL)
+        if trace_enabled:
+            log.log(TRACE_LEVEL, "[Resend] Sending email via Resend API")
+            log.log(TRACE_LEVEL, "[Resend] From: %s, To: %s", message.get("From"), message.get("To"))
+
+        try:
+            async with httpx.AsyncClient(timeout=self._timeout, event_hooks=event_hooks) as client:
+                response = await client.post(
+                    self._base_url,
+                    json=payload,
+                    headers=headers,
+                )
+
+                if response.status_code >= 400:
+                    self._handle_error_response(response)
+
+                data = response.json()
+                self._last_response = ResendResponse(id=data.get("id", ""))
+                log.debug("Email sent via Resend: %s", self._last_response.id)
+                if trace_enabled:
+                    log.log(TRACE_LEVEL, "[Resend] Message sent successfully, id=%s", self._last_response.id)
+
+        except httpx.TimeoutException as e:
+            if trace_enabled:
+                log.log(TRACE_LEVEL, "[Resend] Timeout error: %s", e)
+            raise MailTransportError(f"Resend API timeout: {e}") from e
+        except httpx.RequestError as e:
+            if trace_enabled:
+                log.log(TRACE_LEVEL, "[Resend] Request error: %s", e)
+            raise MailTransportError(f"Resend API request failed: {e}") from e
+
+    def _build_payload(self, message: EmailMessage) -> dict[str, Any]:
+        """Convert EmailMessage to Resend API payload.
+
+        Args:
+            message: The email message.
+
+        Returns:
+            Dict suitable for JSON serialization.
+
+        Raises:
+            MailConfigurationError: If required fields are missing.
+        """
+        from_addr = message.get("From")
+        if not from_addr:
+            raise MailConfigurationError("Email must have a From address")
+
+        to_addrs = self._parse_recipients(message.get("To", ""))
+        if not to_addrs:
+            raise MailConfigurationError("Email must have at least one To address")
+
+        payload: dict[str, Any] = {
+            "from": from_addr,
+            "to": to_addrs,
+            "subject": message.get("Subject", ""),
+        }
+
+        # Add CC and BCC if present
+        cc_addrs = self._parse_recipients(message.get("Cc", ""))
+        if cc_addrs:
+            payload["cc"] = cc_addrs
+
+        bcc_addrs = self._parse_recipients(message.get("Bcc", ""))
+        if bcc_addrs:
+            payload["bcc"] = bcc_addrs
+
+        # Add Reply-To if present
+        reply_to = message.get("Reply-To")
+        if reply_to:
+            payload["reply_to"] = reply_to
+
+        # Extract body content
+        self._add_body_content(message, payload)
+
+        # Extract attachments
+        attachments = self._extract_attachments(message)
+        if attachments:
+            payload["attachments"] = attachments
+
+        return payload
+
+    def _parse_recipients(self, header_value: str) -> list[str]:
+        """Parse comma-separated email addresses.
+
+        Args:
+            header_value: The header value (e.g., "a@x.com, b@x.com").
+
+        Returns:
+            List of email addresses.
+        """
+        if not header_value:
+            return []
+        return [addr.strip() for addr in header_value.split(",") if addr.strip()]
+
+    def _add_body_content(self, message: EmailMessage, payload: dict[str, Any]) -> None:
+        """Extract and add body content to payload.
+
+        Args:
+            message: The email message.
+            payload: The API payload to update.
+        """
+        # Get the message body - handle multipart
+        # Note: get_content() adds trailing newline, so we strip it
+        if message.is_multipart():
+            for part in message.walk():
+                content_type = part.get_content_type()
+                if content_type == "text/plain" and "text" not in payload:
+                    content = part.get_content()
+                    if isinstance(content, str):
+                        payload["text"] = content.rstrip("\n")
+                elif content_type == "text/html" and "html" not in payload:
+                    content = part.get_content()
+                    if isinstance(content, str):
+                        payload["html"] = content.rstrip("\n")
+        else:
+            # Simple message
+            content = message.get_content()
+            if isinstance(content, str):
+                text = content.rstrip("\n")
+                if message.get_content_type() == "text/html":
+                    payload["html"] = text
+                else:
+                    payload["text"] = text
+
+    def _extract_attachments(self, message: EmailMessage) -> list[dict[str, str]]:
+        """Extract attachments from the email message.
+
+        Args:
+            message: The email message.
+
+        Returns:
+            List of attachment dicts with filename and base64 content.
+        """
+        attachments: list[dict[str, str]] = []
+
+        if not message.is_multipart():
+            return attachments
+
+        for part in message.walk():
+            content_disposition = part.get("Content-Disposition", "")
+            if "attachment" in content_disposition:
+                filename = part.get_filename() or "attachment"
+                content = part.get_payload(decode=True)
+                if isinstance(content, bytes):
+                    attachments.append(
+                        {
+                            "filename": filename,
+                            "content": base64.b64encode(content).decode("ascii"),
+                        }
+                    )
+
+        return attachments
+
+    def _handle_error_response(self, response: httpx.Response) -> None:
+        """Handle error response from Resend API.
+
+        Args:
+            response: The HTTP response.
+
+        Raises:
+            MailTransportError: Always raises with error details.
+        """
+        handle_http_error_response(response, "Resend", log)