package com.fabledsword.minstrel.api.endpoints

import retrofit2.http.Body
import retrofit2.http.POST

/**
 * Retrofit interface for `POST /api/playback-errors`. Reports a
 * client-detected playback failure (zero-duration, decode error, ...)
 * so the admin inbox surfaces it.
 *
 * Failures during dispatch are reported via the MutationQueue path
 * for offline replay (see [com.fabledsword.minstrel.cache.mutations.MutationQueue.enqueuePlaybackErrorReport]).
 */
interface PlaybackErrorsApi {
    @POST("api/playback-errors")
    suspend fun report(@Body body: PlaybackErrorReportRequest)
}

/**
 * POST body for `/api/playback-errors`. `kind` is one of
 * "zero_duration" / "load_failed" / "stalled"; server validates against
 * the CHECK constraint enum. `detail` is optional free-text (Media3
 * error message, etc.). `clientId` reuses the existing playback
 * client identifier the device already sends with `/api/plays/...`
 * so support can correlate reports across surfaces.
 */
@kotlinx.serialization.Serializable
data class PlaybackErrorReportRequest(
    @kotlinx.serialization.SerialName("track_id") val trackId: String,
    val kind: String,
    val detail: String? = null,
    @kotlinx.serialization.SerialName("client_id") val clientId: String,
)
