"""
Abstract base class for notification providers.

All concrete providers (Gmail SMTP, Twilio SMS, SES, SNS) must implement
the interface defined here.
"""

from abc import ABC, abstractmethod
from typing import Any, Dict, Optional


class NotificationProvider(ABC):
    """
    Abstract notification provider.

    Implementations are responsible for:
      - Rendering the message body (substituting template variables)
      - Delivering the message to the recipient
      - Returning a success/failure indicator with optional error details
    """

    @abstractmethod
    async def send(
        self,
        recipient: str,
        subject: Optional[str],
        body_text: Optional[str],
        body_html: Optional[str],
        template_vars: Optional[Dict[str, Any]] = None,
    ) -> bool:
        """
        Send a notification message to the recipient.

        Args:
            recipient:     Delivery address — email for email channels, E.164
                           phone number for SMS channels.
            subject:       Email subject line (ignored for SMS channels).
            body_text:     Plain-text body.
            body_html:     HTML body (used by email providers; ignored by SMS).
            template_vars: Optional dict of extra variables for runtime rendering.

        Returns:
            True if the message was accepted by the downstream provider.
            False (or raises) on failure.
        """
        ...