/*
 * SPDX-License-Identifier: GPL-3.0-or-later
 */
package com.runicgateway.app.data.api

import com.runicgateway.app.data.api.dto.MeResponse
import com.runicgateway.app.data.api.dto.MobileLoginRequest
import com.runicgateway.app.data.api.dto.MobileLogoutRequest
import com.runicgateway.app.data.api.dto.MobileTokenResponse
import retrofit2.Response
import retrofit2.http.Body
import retrofit2.http.GET
import retrofit2.http.Header
import retrofit2.http.Headers
import retrofit2.http.POST

/**
 * The native bearer-auth surface (PLAN.md §4.1). Login and logout run on the main
 * OkHttp client; [com.runicgateway.app.core.net.AuthInterceptor] attaches the
 * access token to logout + `/auth/me`, and [com.runicgateway.app.core.net.TokenAuthenticator]
 * transparently refreshes on a `401`.
 *
 * Login is tagged [com.runicgateway.app.core.net.Http.NO_SESSION_HEADER] so it
 * carries no bearer and a credential `401` (bad password / `totpRequired`) is not
 * misread as an expired session. It returns a raw [Response] so the caller can
 * inspect the status and parse the `{ totpRequired }` error body.
 */
interface AuthApi {

    // Literal header value required by Retrofit @Headers; matches Http.NO_SESSION_HEADER.
    // [trustToken] rides the `X-Trust-Token` header (TRUSTED_DEVICES_MFA.md): a valid
    // token bound to this user lets the server skip the TOTP step. Retrofit omits the
    // header entirely when it is null, so an untrusted device sends nothing.
    @Headers("X-Runic-No-Session: 1")
    @POST("api/v1/auth/mobile/login")
    suspend fun login(
        @Body body: MobileLoginRequest,
        @Header("X-Trust-Token") trustToken: String? = null,
    ): Response<MobileTokenResponse>

    @POST("api/v1/auth/mobile/logout")
    suspend fun logout(@Body body: MobileLogoutRequest): Response<Unit>

    /** Current user — the app's authoritative role source, re-validated on resume (§4.3). */
    @GET("api/v1/auth/me")
    suspend fun me(): MeResponse
}
