"""Abstract persistence API for generated HTML pages and favorites."""

from __future__ import annotations

from abc import ABC, abstractmethod
from typing import Any


class HtmlPageStore(ABC):
    # --- Generated pages ---

    @abstractmethod
    async def create_page(self, data: dict[str, Any]) -> dict[str, Any]:
        raise NotImplementedError

    @abstractmethod
    async def get_page(self, page_id: str) -> dict[str, Any] | None:
        """Return a page by id without restricting by owner."""
        raise NotImplementedError

    @abstractmethod
    async def get_page_by_run(self, run_id: str) -> dict[str, Any] | None:
        """Return the page produced by a given run, if any."""
        raise NotImplementedError

    @abstractmethod
    async def latest_page_for_task(self, task_id: str) -> dict[str, Any] | None:
        """Return the most recently created page for a task, if any."""
        raise NotImplementedError

    # --- Favorites ---

    @abstractmethod
    async def create_favorite(self, data: dict[str, Any]) -> dict[str, Any]:
        raise NotImplementedError

    @abstractmethod
    async def list_favorites(self, user_id: str, *, limit: int = 100) -> list[dict[str, Any]]:
        raise NotImplementedError

    @abstractmethod
    async def get_favorite(self, favorite_id: str) -> dict[str, Any] | None:
        """Return a favorite by id without restricting by owner."""
        raise NotImplementedError

    @abstractmethod
    async def get_favorite_by_page(self, user_id: str, page_id: str) -> dict[str, Any] | None:
        """Return the user's existing favorite for a page, if any (dedup check)."""
        raise NotImplementedError

    @abstractmethod
    async def delete_favorite(self, favorite_id: str, user_id: str) -> bool:
        raise NotImplementedError