"""Post repository interface.

This module extends the base repository interface with post-specific
query methods including slug lookup, author filtering, and search.
"""

from abc import abstractmethod

from app.domain.entities.post import Post
from app.domain.repositories.base import Repository


class PostRepository(Repository[Post]):
    """Repository interface for Blog Posts.

    Extends the generic repository with post-specific operations
    including slug-based lookup, author filtering, tag filtering,
    and full-text search capabilities.

    Example:
        >>> posts = await repo.get_by_author("user-123", limit=10)
        >>> exists = await repo.slug_exists("my-first-post")
    """

    @abstractmethod
    async def get_by_slug(self, slug: str) -> Post | None:
        """Get post by slug.

        Args:
            slug: URL-friendly slug identifier.

        Returns:
            Post instance if found, None otherwise.
        """
        ...

    @abstractmethod
    async def get_by_author(
        self,
        author_id: str,
        limit: int | None = None,
        offset: int | None = None,
    ) -> list[Post]:
        """Get all posts by author.

        Args:
            author_id: Identifier of the author.
            limit: Maximum number of posts to return.
            offset: Number of posts to skip.

        Returns:
            List of posts by the specified author.
        """
        ...

    @abstractmethod
    async def get_published(
        self,
        limit: int | None = None,
        offset: int | None = None,
    ) -> list[Post]:
        """Get all published posts.

        Args:
            limit: Maximum number of posts to return.
            offset: Number of posts to skip.

        Returns:
            List of published posts.
        """
        ...

    @abstractmethod
    async def get_by_tag(
        self,
        tag: str,
        limit: int | None = None,
        offset: int | None = None,
    ) -> list[Post]:
        """Get posts by tag.

        Args:
            tag: Tag to filter by.
            limit: Maximum number of posts to return.
            offset: Number of posts to skip.

        Returns:
            List of posts with the specified tag.
        """
        ...

    @abstractmethod
    async def slug_exists(self, slug: str) -> bool:
        """Check if slug already exists.

        Args:
            slug: Slug to check for existence.

        Returns:
            True if slug exists, False otherwise.
        """
        ...

    @abstractmethod
    async def search(
        self,
        query: str,
        limit: int | None = None,
        offset: int | None = None,
    ) -> list[Post]:
        """Search posts by query string.

        Args:
            query: Search query string.
            limit: Maximum number of posts to return.
            offset: Number of posts to skip.

        Returns:
            List of posts matching the search query.
        """
        ...