from __future__ import annotations

from typing import Any, Protocol, runtime_checkable


@runtime_checkable
class EmailNotificationPort(Protocol):
    """Domain Port Interface for sending transactional and operational emails."""

    async def send_email(
        self,
        recipient_email: str,
        subject: str,
        html_content: str,
        recipient_name: str = "DSCons User",
        sender_email: str | None = None,
        sender_name: str | None = None,
        attachments: list[dict[str, str]] | None = None,
    ) -> dict[str, Any]:
        """Send email via external notification provider."""
        ...