@spec accept_invite(Ecto.UUID.t(), Ecto.UUID.t()) ::
  {:ok, Gamend.Groups.GroupMember.t()} | {:error, atom()}

Accept a pending group invite by invite_id. The user must be the recipient of the invite. Works for all group types (public, private, hidden).

@spec cancel_invite(Ecto.UUID.t(), Ecto.UUID.t()) :: :ok | {:error, atom()}

Cancel (delete) a group invitation that the current user sent. Only the sender can cancel their own invitation.

@spec count_invitations(Ecto.UUID.t()) :: non_neg_integer()

Count pending invitations for a user.

@spec count_sent_invitations(Ecto.UUID.t()) :: non_neg_integer()

Count group invitations sent by a user.

@spec decline_invite(Ecto.UUID.t(), Ecto.UUID.t()) :: :ok | {:error, atom()}

Decline a pending group invite by invite_id. Only the recipient can decline. The invite is marked as "declined" (not deleted) so the sender can see the outcome.

@spec invite_to_group(Ecto.UUID.t(), Ecto.UUID.t(), Ecto.UUID.t()) ::
  {:ok, Gamend.Groups.GroupInvite.t()}
  | {:ok, :request_approved}
  | {:error, atom()}

Invite a user to a group. Creates a GroupInvite record and sends an informational notification. The invite record is independent of the notification — deleting notifications does not affect pending invites.

If the target user already has a pending join request for this group, the request is automatically approved instead of creating an invite. In that case, returns {:ok, :request_approved}.

The admin must already be connected to the target — a friendship, or a group they are both already in. Without that an admin could put any user id at all into a group with them, which made a group invite a weaker control than a party invite, where Parties.check_leader_connected_to_target/2 has always required a connection. On a service children can reach, being addable to a stranger's group is the contact path that matters, so the two now agree. Returns {:error, :not_connected}.

@spec list_invitations(
  Ecto.UUID.t(),
  keyword()
) :: [map()]

List pending group invitations for a user.

@spec list_sent_invitations(
  Ecto.UUID.t(),
  keyword()
) :: [map()]

List group invitations sent by a user.