package dev.stave.upnp

import dev.stave.domain.model.DidlItem

/**
 * Result of a Browse() or Search() call against a UPnP ContentDirectory service.
 *
 * [Success.totalMatches] is the server-reported total count — different from [Success.items]
 * size when pagination is in play. A search returning the first 25 matches out of 5000
 * has items.size == 25 and totalMatches == 5000. Random sampling uses this to pick a
 * valid offset without fetching the whole library.
 *
 * The default makes totalMatches == items.size for callers that don't care (Browse on
 * small containers where everything returns in one page).
 */
sealed interface BrowseResult {
    data class Success(
        val items: List<DidlItem>,
        val totalMatches: Long = items.size.toLong(),
    ) : BrowseResult

    data class Failure(val message: String) : BrowseResult
}