# -*- coding: utf-8 -*-
# hub/ticket/services/hardware_gateway.py

"""Публичный контракт аппаратного шлюза Ticket."""

from __future__ import annotations

from typing import Any, Mapping, Protocol

from domain import TicketHardwareStatus


class TicketHardwareObserver(Protocol):
    """Получатель событий от аппаратного или mock-шлюза."""

    def on_task_action(self, raw_action: Mapping[str, Any]) -> None:
        """Принять внешнее действие по задаче."""

    def on_gateway_status(self, status: TicketHardwareStatus) -> None:
        """Принять обновление статуса подключения и инициализации."""

    def on_gateway_error(self, message: str) -> None:
        """Принять сообщение об ошибке шлюза."""


class TicketHardwareGateway(Protocol):
    """Минимальный публичный API сервиса ввода событий Ticket."""

    def start(self) -> None:
        """Запустить внешний источник событий."""

    def stop(self) -> None:
        """Остановить внешний источник событий."""

    def get_status(self) -> TicketHardwareStatus:
        """Вернуть текущий статус шлюза."""

    def set_observer(self, observer: TicketHardwareObserver | None) -> None:
        """Назначить получателя событий приложения."""

    def set_button_state(self, button_id: int, state_code: int) -> None:
        """Синхронизировать каноническое состояние кнопки для аппаратного шлюза."""

    def remove_button_state(self, button_id: int) -> None:
        """Удалить известное состояние кнопки из шлюза."""

    def reset_button_states(self) -> None:
        """Сбросить все известные состояния кнопок при смене контекста."""