"""MessagingProvider protocol -- interface for SMS/email messaging backends.

Core code depends on this protocol. Plugin implementations (zo_messaging,
twilio_messaging, sendgrid_messaging, etc.) implement it.

Provider-agnostic: Vastian's orchestrator calls send_sms/send_email without
knowing whether Zo, Twilio, or a local SMTP server handles delivery.
"""

from __future__ import annotations

from typing import Any, Protocol, runtime_checkable


@runtime_checkable
class MessagingProvider(Protocol):
    """Protocol for SMS and email messaging backends."""

    async def send_sms(self, body: str, to: str | None = None) -> dict[str, Any]:
        """Send an SMS message.

        Args:
            body: Message text.
            to: Recipient phone number (None = default user).

        Returns:
            Dict with at least {ok: bool, message_id: str}.
        """
        ...

    async def send_email(
        self,
        subject: str,
        body: str,
        to: str | None = None,
        attachments: list[str] | None = None,
    ) -> dict[str, Any]:
        """Send an email.

        Args:
            subject: Email subject line.
            body: Email body (markdown supported).
            to: Recipient email (None = default user).
            attachments: Optional list of file paths to attach.

        Returns:
            Dict with at least {ok: bool, message_id: str}.
        """
        ...

    async def pull_inbox(self) -> list[dict[str, Any]]:
        """Pull new messages from the messaging inbox.

        Returns:
            List of message dicts: {id, source, content, timestamp, type}.
            Type is 'sms' or 'email'.
        """
        ...

    async def get_contacts(self) -> list[dict[str, str]]:
        """Get available contacts.

        Returns:
            List of {name, phone, email} dicts.
        """
        ...
