package legion.muyue.best2048.network;

import legion.muyue.best2048.data.GameInfo;
import legion.muyue.best2048.data.GameStateResponse;
import legion.muyue.best2048.data.MoveRequest;
import legion.muyue.best2048.data.PlayerIdRequest;
import retrofit2.Call;
import retrofit2.http.Body;
import retrofit2.http.GET;
import retrofit2.http.POST;
import retrofit2.http.Path;

/**
 * Définit les points de terminaison (endpoints) de l'API REST pour le jeu Best2048.
 * Cette interface est utilisée par Retrofit pour générer une implémentation
 * capable d'effectuer des appels réseau vers le serveur du jeu.
 *
 * Les appels retournent des objets {@link Call} qui permettent une exécution
 * asynchrone (ou synchrone) des requêtes HTTP.
 *
 * @see ApiClient#getApiService() pour obtenir une instance implémentant cette interface.
 */
public interface ApiService {

    /**
     * Crée une nouvelle partie ou rejoint une partie existante en attente pour le joueur spécifié.
     * Effectue une requête POST vers {@code /api/games}.
     * Le corps de la requête contient l'identifiant du joueur.
     *
     * @param playerIdRequest Un objet {@link PlayerIdRequest} contenant l'identifiant unique
     * du joueur qui souhaite créer ou rejoindre une partie.
     * @return Un objet {@link Call} qui, en cas de succès, encapsule les informations
     * de la partie créée ou rejointe ({@link GameInfo}).
     */
    @POST("games")
    Call<GameInfo> createOrJoinGame(@Body PlayerIdRequest playerIdRequest);

    /**
     * Récupère l'état actuel complet d'une partie spécifique.
     * Effectue une requête GET vers {@code /api/games/{gameId}}.
     *
     * @param gameId L'identifiant unique de la partie dont l'état doit être récupéré.
     * Ce paramètre est inséré dans le chemin de l'URL.
     * @return Un objet {@link Call} qui, en cas de succès, encapsule l'état complet
     * de la partie demandée ({@link GameStateResponse}).
     */
    @GET("games/{gameId}")
    Call<GameStateResponse> getGameState(@Path("gameId") String gameId);

    /**
     * Soumet un mouvement effectué par un joueur dans une partie spécifique.
     * Effectue une requête POST vers {@code /api/games/{gameId}/moves}.
     * Le corps de la requête contient les détails du mouvement (direction et identifiant du joueur).
     *
     * @param gameId      L'identifiant unique de la partie dans laquelle le mouvement est effectué.
     * Ce paramètre est inséré dans le chemin de l'URL.
     * @param moveRequest Un objet {@link MoveRequest} contenant la direction du mouvement
     * et l'identifiant du joueur effectuant le mouvement.
     * @return Un objet {@link Call} qui, en cas de succès, encapsule le nouvel état
     * de la partie après l'application du mouvement ({@link GameStateResponse}).
     * La réponse peut indiquer si le mouvement était valide, l'état mis à jour du plateau,
     * les scores, etc.
     */
    @POST("games/{gameId}/moves")
    Call<GameStateResponse> makeMove(@Path("gameId") String gameId, @Body MoveRequest moveRequest);

}