Player SDK on Android

data class DeviceValues(val unionInfo: String, val drmKek: String)

interface PlayerSdk {
    /** Read only after the SDK has started and its licence check succeeded. Throws instead of returning null:
     *  never send "(null)", "null" or an empty string to your backend. */
    fun deviceValues(): DeviceValues
    fun play(vid: String, playAuthToken: String, startAtMs: Long)
    fun preload(vid: String, playAuthToken: String)
    fun addSubtitles(subtitles: List<Subtitle>)
    val currentPositionMs: Long
    /** A playback error, including an expired ticket. Do not branch on SDK error codes. */
    var onError: ((Throwable) -> Unit)?
}

@Serializable
data class Subtitle(val lang: String, val url: String, val format: String)

@Serializable
data class Ticket(
    val vid: String,
    @SerialName("play_auth_token") val playAuthToken: String, // memory only: never log, never persist
    @SerialName("expires_at") val expiresAt: String,
    val subtitles: List<Subtitle> = emptyList(),
) {
    /** Wandura's clock decides; allow a minute for a device clock that runs slow. */
    fun isFresh(now: Instant = Instant.now()): Boolean = Instant.parse(expiresAt).isAfter(now.plusSeconds(60))
}

@Serializable
data class NextTicket(@SerialName("episode_no") val episodeNo: Int, val ticket: Ticket)

/** The shape the example backends (Node, Python) return from YOUR `POST /v1/play`. */
@Serializable
data class PlayResponse(
    val ok: Boolean,
    val current: Ticket? = null,
    val next: List<NextTicket> = emptyList(),
    val outcome: String? = null, // locked | unavailable | not_ready | busy | broken — unknown = broken
)

/** Your backend. Implement with your HTTP client (OkHttp, Retrofit, Ktor) and a 15-second timeout: your backend may
 *  retry Wandura for a few seconds. Send YOUR viewer session, never a Wandura key. */
interface Backend {
    suspend fun play(filmId: String, episodeNo: Int, device: DeviceValues): PlayResponse
}

sealed interface ScreenState {
    data object Loading : ScreenState
    data object Playing : ScreenState
    data object Paywall : ScreenState
    data class Message(val text: String, val canRetry: Boolean) : ScreenState
}

class PlaybackController(
    private val sdk: PlayerSdk,
    private val backend: Backend,
    private val scope: CoroutineScope,
    private val onState: (ScreenState) -> Unit,
) {
    private val prefetched = mutableMapOf<Int, Ticket>() // episode number → ticket for THIS device only
    private var current: Triple<String, Int, Ticket>? = null
    private var refreshedAfterError = false

    init {
        sdk.onError = { scope.launch { recoverFromPlayerError() } }
    }

    /** The viewer tapped an episode. */
    suspend fun start(filmId: String, episodeNo: Int) {
        onState(ScreenState.Loading)
        refreshedAfterError = false
        val device = runCatching { sdk.deviceValues() }.getOrElse {
            return onState(ScreenState.Message("Couldn't load this episode", canRetry = false)) // SDK setup bug
        }
        // A prefetched ticket starts the episode at once. The play request is still sent: it records the view.
        prefetched.remove(episodeNo)?.takeIf { it.isFresh() }?.let { begin(filmId, episodeNo, it, 0) }
        val r = runCatching { backend.play(filmId, episodeNo, device) }.getOrNull()
        when {
            r?.ok == true && r.current != null -> {
                if (current?.second != episodeNo) begin(filmId, episodeNo, r.current, 0)
                r.next.forEach { n -> // a prefetch missing from `next` is not an error
                    prefetched[n.episodeNo] = n.ticket
                    sdk.preload(n.ticket.vid, n.ticket.playAuthToken)
                }
            }
            current?.second == episodeNo -> Unit // already playing from the prefetched ticket
            r == null -> onState(ScreenState.Message("Taking longer than usual", canRetry = true))
            else -> show(r.outcome)
        }
    }

    /** Expired ticket or any SDK error: ONE fresh ticket, resume at the same position. Never a loop. */
    private suspend fun recoverFromPlayerError() {
        val c = current
        val device = runCatching { sdk.deviceValues() }.getOrNull()
        if (c == null || refreshedAfterError || device == null) {
            return onState(ScreenState.Message("Couldn't load this episode", canRetry = true))
        }
        refreshedAfterError = true
        val position = sdk.currentPositionMs
        val r = runCatching { backend.play(c.first, c.second, device) }.getOrNull()
        val ticket = r?.current
        if (r?.ok != true || ticket == null) return onState(ScreenState.Message("Couldn't load this episode", canRetry = true))
        begin(c.first, c.second, ticket, position)
    }

    /** Back from the background: a ticket with less than a minute left is replaced before resuming. */
    suspend fun onResume() {
        val c = current ?: return
        if (c.third.isFresh()) return
        refreshedAfterError = false
        recoverFromPlayerError()
    }

    private fun begin(filmId: String, episodeNo: Int, ticket: Ticket, atMs: Long) {
        current = Triple(filmId, episodeNo, ticket)
        sdk.play(ticket.vid, ticket.playAuthToken, atMs)
        sdk.addSubtitles(ticket.subtitles) // empty list = no subtitles yet, not an error
        onState(ScreenState.Playing)
    }

    private fun show(outcome: String?) = onState(
        when (outcome) {
            "locked" -> ScreenState.Paywall
            "unavailable" -> ScreenState.Message("This title is no longer available", canRetry = false)
            "not_ready" -> ScreenState.Message("Not available yet", canRetry = false)
            "busy" -> ScreenState.Message("Busy, try again in a moment", canRetry = true)
            else -> ScreenState.Message("Couldn't load this episode", canRetry = true)
        },
    )
}