"""Repository protocol for ProjectMembership operations."""

from __future__ import annotations

from collections.abc import Sequence
from typing import TYPE_CHECKING, Protocol

if TYPE_CHECKING:
    from uuid import UUID

    from noteflow.domain.identity import ProjectMembership, ProjectRole


class ProjectMembershipRepository(Protocol):
    """Repository protocol for ProjectMembership operations."""

    async def get(
        self,
        project_id: UUID,
        user_id: UUID,
    ) -> ProjectMembership | None:
        """Get a user's membership in a project.

        Args:
            project_id: Project UUID.
            user_id: User UUID.

        Returns:
            Membership if user is a member, None otherwise.
        """
        ...

    async def add(
        self,
        project_id: UUID,
        user_id: UUID,
        role: ProjectRole,
    ) -> ProjectMembership:
        """Add a user to a project.

        Args:
            project_id: Project UUID.
            user_id: User UUID.
            role: Role to assign.

        Returns:
            Created membership.
        """
        ...

    async def update_role(
        self,
        project_id: UUID,
        user_id: UUID,
        role: ProjectRole,
    ) -> ProjectMembership | None:
        """Update a member's role in a project.

        Args:
            project_id: Project UUID.
            user_id: User UUID.
            role: New role.

        Returns:
            Updated membership if found, None otherwise.
        """
        ...

    async def remove(
        self,
        project_id: UUID,
        user_id: UUID,
    ) -> bool:
        """Remove a user from a project.

        Args:
            project_id: Project UUID.
            user_id: User UUID.

        Returns:
            True if removed, False if not found.
        """
        ...

    async def list_for_project(
        self,
        project_id: UUID,
        limit: int = 100,
        offset: int = 0,
    ) -> Sequence[ProjectMembership]:
        """List all members of a project.

        Args:
            project_id: Project UUID.
            limit: Maximum members to return.
            offset: Pagination offset.

        Returns:
            List of memberships.
        """
        ...

    async def list_for_user(
        self,
        user_id: UUID,
        workspace_id: UUID | None = None,
        limit: int = 100,
        offset: int = 0,
    ) -> Sequence[ProjectMembership]:
        """List all projects a user is a member of.

        Args:
            user_id: User UUID.
            workspace_id: Optional filter by workspace.
            limit: Maximum memberships to return.
            offset: Pagination offset.

        Returns:
            List of memberships.
        """
        ...

    async def bulk_add(
        self,
        project_id: UUID,
        memberships: Sequence[tuple[UUID, ProjectRole]],
    ) -> Sequence[ProjectMembership]:
        """Bulk add members to a project.

        Args:
            project_id: Project UUID.
            memberships: List of (user_id, role) tuples.

        Returns:
            Created memberships.
        """
        ...

    async def count_for_project(
        self,
        project_id: UUID,
    ) -> int:
        """Count members in a project.

        Args:
            project_id: Project UUID.

        Returns:
            Member count.
        """
        ...
