import '../../domain/entities/friend.dart';
import '../../domain/entities/friend_request.dart';

/// Interface [FriendsRepository] définissant les méthodes pour gérer les amis.
/// Cette interface permet de séparer la logique métier des appels API et de la gestion des données.
/// Elle est implémentée par [FriendsRepositoryImpl], qui contient les détails d'implémentation.
abstract class FriendsRepository {

  /// Récupère la liste paginée des amis pour un utilisateur donné via l'API.
  ///
  /// [userId] : Identifiant unique de l'utilisateur pour lequel récupérer la liste d'amis.
  /// [currentPage] : Indique la page actuelle pour la pagination.
  /// [friendsPerPage] : Nombre d'amis à récupérer par page.
  ///
  /// Retourne une liste d'objets [Friend] correspondant aux amis de l'utilisateur.
  /// En cas d'échec, une liste vide peut être retournée par l'implémentation.
  Future<List<Friend>> fetchFriends(String userId, int currentPage, int friendsPerPage);

  /// Envoie une demande pour ajouter un nouvel ami via l'API.
  ///
  /// [userId] : Identifiant unique de l'utilisateur qui envoie la demande.
  /// [friendId] : Identifiant unique de l'ami à ajouter.
  ///
  /// Retourne un `Future<void>`. En cas d'erreur, l'implémentation peut lancer une exception.
  Future<void> addFriend(String userId, String friendId);

  /// Supprime un ami existant via l'API.
  ///
  /// [friendId] : Identifiant unique de l'ami à supprimer.
  ///
  /// Retourne un `Future<void>`. En cas d'erreur, l'implémentation peut lancer une exception.
  Future<void> removeFriend(String friendId);

  /// Récupère les détails d'un ami en utilisant son identifiant `friendId`.
  ///
  /// [userId] : Identifiant unique de l'utilisateur connecté (facultatif selon le contexte).
  /// [friendId] : Identifiant unique de l'ami pour lequel récupérer les détails.
  ///
  /// Retourne un `Future<Friend?>` contenant les informations de l'ami si trouvées,
  /// ou `null` si aucun ami correspondant n'est trouvé ou en cas d'échec.
  Future<Friend?> getFriendDetails(String friendId, String userId);

  /// Met à jour le statut d'un ami dans le système (par exemple, accepter, bloquer).
  ///
  /// [friendId] : Identifiant unique de l'ami.
  /// [status] : Nouveau statut de l'ami sous forme de chaîne de caractères.
  ///
  /// Retourne un `Future<void>`. En cas d'erreur, l'implémentation peut lancer une exception.
  Future<void> updateFriendStatus(String friendId, String status);

  /// Récupère les demandes d'amitié en attente pour un utilisateur.
  ///
  /// [userId] : Identifiant unique de l'utilisateur.
  /// [page] : Numéro de la page pour la pagination.
  /// [size] : Nombre d'éléments par page.
  ///
  /// Retourne une liste de demandes d'amitié en attente.
  Future<List<FriendRequest>> getPendingFriendRequests(String userId, int page, int size);

  /// Récupère les demandes d'amitié envoyées par un utilisateur.
  ///
  /// [userId] : Identifiant unique de l'utilisateur.
  /// [page] : Numéro de la page pour la pagination.
  /// [size] : Nombre d'éléments par page.
  ///
  /// Retourne une liste de demandes d'amitié envoyées.
  Future<List<FriendRequest>> getSentFriendRequests(String userId, int page, int size);

  /// Récupère les demandes d'amitié reçues par un utilisateur.
  ///
  /// [userId] : Identifiant unique de l'utilisateur.
  /// [page] : Numéro de la page pour la pagination.
  /// [size] : Nombre d'éléments par page.
  ///
  /// Retourne une liste de demandes d'amitié reçues.
  Future<List<FriendRequest>> getReceivedFriendRequests(String userId, int page, int size);

  /// Accepte une demande d'amitié.
  ///
  /// [friendshipId] : Identifiant unique de la relation d'amitié.
  ///
  /// Retourne un `Future<void>`. En cas d'erreur, l'implémentation peut lancer une exception.
  Future<void> acceptFriendRequest(String friendshipId);

  /// Rejette une demande d'amitié.
  ///
  /// [friendshipId] : Identifiant unique de la relation d'amitié.
  ///
  /// Retourne un `Future<void>`. En cas d'erreur, l'implémentation peut lancer une exception.
  Future<void> rejectFriendRequest(String friendshipId);

  /// Annule une demande d'amitié envoyée (supprime la relation).
  ///
  /// [friendshipId] : Identifiant unique de la relation d'amitié.
  ///
  /// Retourne un `Future<void>`. En cas d'erreur, l'implémentation peut lancer une exception.
  Future<void> cancelFriendRequest(String friendshipId);

  /// Récupère les suggestions d'amis pour un utilisateur.
  ///
  /// [userId] : Identifiant unique de l'utilisateur.
  /// [limit] : Nombre maximum de suggestions à retourner (par défaut 10).
  ///
  /// Retourne une liste de suggestions d'amis basées sur les amis en commun
  /// et d'autres critères de pertinence.
  Future<List<dynamic>> getFriendSuggestions(String userId, {int limit = 10});
}