"""Abstract base class for brokerage integrations.

All broker implementations must inherit from ``BaseBroker`` and provide
concrete implementations for order management, position tracking, and
account information retrieval.  This abstraction layer allows the trading
bot to swap brokerages (Alpaca, Interactive Brokers, Tradier, ...) without
changing strategy or execution logic.
"""

from abc import ABC, abstractmethod

from shared.schemas.trading import AccountInfo, OrderRequest, OrderResult, PositionInfo


class BaseBroker(ABC):
    """Interface that every brokerage adapter must implement."""

    @abstractmethod
    async def submit_order(self, order: OrderRequest) -> OrderResult:
        """Submit a new order to the brokerage.

        Parameters
        ----------
        order:
            The order details including ticker, side, quantity, and order type.

        Returns
        -------
        OrderResult
            Result containing the order ID, status, and fill information.
        """
        ...

    @abstractmethod
    async def cancel_order(self, order_id: str) -> bool:
        """Cancel an open order.

        Parameters
        ----------
        order_id:
            The brokerage-assigned order identifier.

        Returns
        -------
        bool
            ``True`` if the cancellation was accepted, ``False`` otherwise.
        """
        ...

    @abstractmethod
    async def get_positions(self) -> list[PositionInfo]:
        """Return all currently open positions.

        Returns
        -------
        list[PositionInfo]
            One entry per open position with quantity, average entry, current
            price, and unrealized P&L.
        """
        ...

    @abstractmethod
    async def get_account(self) -> AccountInfo:
        """Return account-level summary information.

        Returns
        -------
        AccountInfo
            Equity, cash, buying power, and total portfolio value.
        """
        ...

    @abstractmethod
    async def get_order_status(self, order_id: str) -> OrderResult:
        """Fetch the current status of an existing order.

        Parameters
        ----------
        order_id:
            The brokerage-assigned order identifier.

        Returns
        -------
        OrderResult
            Current state of the order including fill price if applicable.
        """
        ...