@spec accept_friend_request(integer(), GameServer.Accounts.User.t()) ::
  {:ok, GameServer.Friends.Friendship.t()} | {:error, term()}

Accept a friend request (only the target may accept). Returns {:ok, friendship}.

@spec block_friend_request(integer(), GameServer.Accounts.User.t()) ::
  {:ok, GameServer.Friends.Friendship.t()} | {:error, term()}

Block an incoming request (only the target may block). Returns {:ok, friendship} with status "blocked".

@spec cancel_request(integer(), GameServer.Accounts.User.t()) ::
  {:ok, :cancelled} | {:error, :not_found | :not_authorized | term()}

Cancel an outgoing friend request (only the requester may cancel).

@spec count_blocked_for_user(user_id() | GameServer.Accounts.User.t()) ::
  non_neg_integer()

Count blocked friendships for a user (number of blocked rows where user is target).

@spec count_friends_for_user(user_id() | GameServer.Accounts.User.t()) ::
  non_neg_integer()

Count accepted friends for a given user (distinct other user ids).

@spec count_incoming_requests(user_id() | GameServer.Accounts.User.t()) ::
  non_neg_integer()

Count incoming pending friend requests for a user.

@spec count_outgoing_requests(user_id() | GameServer.Accounts.User.t()) ::
  non_neg_integer()

Count outgoing pending friend requests for a user.

@spec create_request(GameServer.Accounts.User.t() | user_id(), user_id()) ::
  {:ok, GameServer.Friends.Friendship.t()}
  | {:error,
     :cannot_friend_self
     | :blocked
     | :already_friends
     | :already_requested
     | term()}

Create a friend request from requester -> target. If a reverse pending request exists (target -> requester) it will be accepted instead. Returns {:ok, friendship} on success or {:error, reason}.

@spec get_by_pair(user_id(), user_id()) :: GameServer.Friends.Friendship.t() | nil

Get friendship between two users (ordered requester->target) if exists

@spec get_friendship(integer()) :: GameServer.Friends.Friendship.t() | nil

Get friendship by id (returns nil when not found)

@spec get_friendship!(integer()) :: GameServer.Friends.Friendship.t()

Get friendship by id

@spec list_blocked_for_user(
  user_id() | GameServer.Accounts.User.t(),
  GameServer.Types.pagination_opts()
) :: [GameServer.Friends.Friendship.t()]

List blocked friendships for a user (Friendship structs where the user is the blocker / target).

@spec list_friends_for_user(
  integer() | GameServer.Accounts.User.t(),
  GameServer.Types.pagination_opts()
) :: [GameServer.Accounts.User.t()]

List accepted friends for a given user id - returns list of User structs.

Options

See GameServer.Types.pagination_opts/0 for available options.

@spec list_friends_with_friendship(
  integer() | GameServer.Accounts.User.t(),
  GameServer.Types.pagination_opts()
) :: [%{friendship_id: integer(), user: GameServer.Accounts.User.t()}]

List accepted friendships for a user along with the other user and friendship id.

Returns a list of maps: %{friendship_id: integer(), user: %User{}}

@spec list_incoming_requests(
  integer() | GameServer.Accounts.User.t(),
  GameServer.Types.pagination_opts()
) :: [GameServer.Friends.Friendship.t()]

List incoming pending friend requests for a user (Friendship structs).

Options

See GameServer.Types.pagination_opts/0 for available options.

@spec list_outgoing_requests(
  integer() | GameServer.Accounts.User.t(),
  GameServer.Types.pagination_opts()
) :: [GameServer.Friends.Friendship.t()]

List outgoing pending friend requests for a user (Friendship structs).

Options

See GameServer.Types.pagination_opts/0 for available options.

@spec reject_friend_request(integer(), GameServer.Accounts.User.t()) ::
  {:ok, GameServer.Friends.Friendship.t()} | {:error, term()}

Reject a friend request (only the target may reject). Returns {:ok, friendship}.

@spec remove_friend(integer(), integer()) ::
  {:ok, GameServer.Friends.Friendship.t()} | {:error, term()}

Remove a friendship (either direction) - only participating users may call this.

@spec unblock_friendship(integer(), GameServer.Accounts.User.t()) ::
  {:ok, :unblocked} | {:error, term()}

Unblock a previously-blocked friendship (only the user who blocked may unblock). Returns {:ok, :unblocked} on success.