# Copyright (c) 2025 CoReason, Inc.
#
# This software is proprietary and dual-licensed.
# Licensed under the Prosperity Public License 3.0 (the "License").
# A copy of the license is available at https://prosperitylicense.com/versions/3.0.0
# For details, see the LICENSE file.
# Commercial use beyond a 30-day trial requires a separate license.
#
# Source Code: https://github.com/CoReason-AI/coreason_navigator

from abc import ABC, abstractmethod
from typing import Literal

from coreason_identity.models import UserContext

from coreason_navigator.types import BrowserAction, BrowserState


class Navigator(ABC):
    """Abstract base class for the browser navigator."""

    @abstractmethod
    async def launch(self) -> None:
        """
        Starts the browser context.

        Raises:
            RuntimeError: If the browser fails to launch.
        """
        pass  # pragma: no cover

    @abstractmethod
    async def navigate(self, url: str, *, context: UserContext) -> BrowserState:
        """
        Navigates to the specified URL and returns the visual state.

        Args:
            url: The URL to navigate to.
            context: The identity context for the operation.

        Returns:
            BrowserState: The state of the browser after navigation.

        Raises:
            DomainNotAllowedError: If the URL is restricted by policy.
        """
        pass  # pragma: no cover

    @abstractmethod
    async def perform_action(self, action: BrowserAction, *, context: UserContext) -> BrowserState:
        """
        Executes a browser action (click, type, scroll, etc.) and returns the new state.

        Args:
            action: The BrowserAction to perform.
            context: The identity context for the operation.

        Returns:
            BrowserState: The updated state of the browser.
        """
        pass  # pragma: no cover

    @abstractmethod
    async def extract_content(self, format: Literal["markdown", "html"], *, context: UserContext) -> str:
        """
        Converts the page content to an LLM-readable format.

        Args:
            format: The desired output format ("markdown" or "html").
            context: The identity context for the operation.

        Returns:
            str: The extracted content.

        Raises:
            ValueError: If the format is not supported.
        """
        pass  # pragma: no cover

    @abstractmethod
    async def close(self) -> None:
        """
        Closes the browser resources.
        """
        pass  # pragma: no cover
