from __future__ import annotations

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

from armorer.messaging.models import MessagingEvent, UserMapping


class MessagingGateway(ABC):
    """Base abstraction for messaging providers (Telegram, Signal, etc.)."""

    provider: str

    @abstractmethod
    def send_message(self, channel_id: str, text: str, reply_to: Optional[str] = None) -> dict[str, Any]:
        """Send a message to a provider channel/chat."""

    def receive_webhook(self, payload: Mapping[str, Any]) -> Optional[MessagingEvent]:
        """Provider entrypoint for inbound webhooks."""
        return self.normalize_event(payload)

    @abstractmethod
    def normalize_event(self, payload: Mapping[str, Any]) -> Optional[MessagingEvent]:
        """Convert provider-specific webhook payload into a neutral event."""

    @abstractmethod
    def map_user(self, event: MessagingEvent) -> UserMapping:
        """Map provider identity fields into a neutral user mapping."""

