Skip to content

StreamVault is a TV-first free IPTV player for Android TV built with Kotlin, Jetpack Compose, Room, Hilt, and Media3.

feat(catalog): define routes and integration ports

David Nashashed3f819bfaae
diff --git a/feature/catalog/src/main/java/com/streamvault/feature/catalog/api/CatalogFeatureContracts.kt b/feature/catalog/src/main/java/com/streamvault/feature/catalog/api/CatalogFeatureContracts.kt
new file mode 100644
index 00000000..c514cff5
--- /dev/null
+++ b/feature/catalog/src/main/java/com/streamvault/feature/catalog/api/CatalogFeatureContracts.kt
@@ -0,0 +1,28 @@
+package com.streamvault.feature.catalog.api
+
+import androidx.compose.foundation.layout.ColumnScope
+import androidx.compose.runtime.Composable
+import com.streamvault.core.navigation.AppDestination
+import com.streamvault.domain.model.AppHomeDashboardShelf
+
+enum class CatalogNavigationChrome {
+ Rail,
+ TopBar,
+}
+
+typealias CatalogScaffoldContent = @Composable (
+ currentDestination: AppDestination,
+ title: String,
+ subtitle: String?,
+ navigationChrome: CatalogNavigationChrome,
+ topBarVisible: Boolean,
+ compactHeader: Boolean,
+ showScreenHeader: Boolean,
+ content: @Composable ColumnScope.() -> Unit,
+) -> Unit
+
+typealias CatalogDashboardShelfCustomizationContent = @Composable (
+ currentShelves: List<AppHomeDashboardShelf>,
+ onDismiss: () -> Unit,
+ onSave: (List<AppHomeDashboardShelf>) -> Unit,
+) -> Unit
diff --git a/feature/catalog/src/main/java/com/streamvault/feature/catalog/api/CatalogPlatformPorts.kt b/feature/catalog/src/main/java/com/streamvault/feature/catalog/api/CatalogPlatformPorts.kt
new file mode 100644
index 00000000..68d6392f
--- /dev/null
+++ b/feature/catalog/src/main/java/com/streamvault/feature/catalog/api/CatalogPlatformPorts.kt
@@ -0,0 +1,90 @@
+package com.streamvault.feature.catalog.api
+
+import com.streamvault.core.navigation.AppDestination
+import com.streamvault.domain.model.Result
+import com.streamvault.domain.model.StreamInfo
+import kotlinx.coroutines.flow.Flow
+
+interface CatalogPlatformHost {
+ fun openCastRouteChooser()
+}
+
+interface CatalogStreamPreparer {
+ suspend fun prepare(streamInfo: StreamInfo): Result<StreamInfo>
+}
+
+interface CatalogDownloadStarter {
+ fun startDownload(downloadId: String)
+}
+
+data class CatalogChannelPlaybackContext(
+ val categoryId: Long?,
+ val providerId: Long,
+ val isVirtual: Boolean,
+ val combinedProfileId: Long?,
+ val returnDestination: AppDestination,
+)
+
+data class CatalogCastRequest(
+ val streamInfo: StreamInfo,
+ val title: String,
+ val subtitle: String?,
+ val artworkUrl: String?,
+ val startPositionMs: Long,
+)
+
+enum class CatalogMessage {
+ CastStarted,
+ CastUnavailable,
+ CastUnsupported,
+ CastItemUnavailable,
+ CastSessionFailed,
+ CastLoadFailed,
+ DownloadStarted,
+ DownloadFailed,
+ DownloadUrlUnavailable,
+}
+
+sealed interface CatalogCastStartResult {
+ data object Started : CatalogCastStartResult
+ data object RouteSelectionRequired : CatalogCastStartResult
+ data object Unavailable : CatalogCastStartResult
+ data class Unsupported(val message: CatalogMessage) : CatalogCastStartResult
+}
+
+sealed interface CatalogCastPlaybackEvent {
+ data object RouteSelectionCancelled : CatalogCastPlaybackEvent
+ data class Finished(
+ val succeeded: Boolean,
+ val message: CatalogMessage,
+ ) : CatalogCastPlaybackEvent
+}
+
+interface CatalogCastPort {
+ val playbackEvents: Flow<CatalogCastPlaybackEvent>
+ suspend fun startCasting(request: CatalogCastRequest): CatalogCastStartResult
+}
+
+sealed interface CatalogUiEvent {
+ data object OpenCastRouteChooser : CatalogUiEvent
+ data class ShowMessage(val message: CatalogMessage) : CatalogUiEvent
+}
+
+enum class CatalogUpdateAction {
+ None,
+ DownloadLatest,
+ Downloading,
+ InstallLatest,
+ InstallPermissionRequired,
+}
+
+data class CatalogUpdateNotice(
+ val latestVersionName: String,
+ val downloadSha256: String?,
+ val action: CatalogUpdateAction,
+)
+
+interface CatalogAppUpdatePort {
+ val notice: Flow<CatalogUpdateNotice?>
+ suspend fun installDownloadedUpdate(expectedSha256: String?): Result<Unit>
+}
diff --git a/feature/catalog/src/main/java/com/streamvault/feature/catalog/navigation/CatalogRoutePatterns.kt b/feature/catalog/src/main/java/com/streamvault/feature/catalog/navigation/CatalogRoutePatterns.kt
new file mode 100644
index 00000000..5478b606
--- /dev/null
+++ b/feature/catalog/src/main/java/com/streamvault/feature/catalog/navigation/CatalogRoutePatterns.kt
@@ -0,0 +1,14 @@
+package com.streamvault.feature.catalog.navigation
+
+object CatalogRoutePatterns {
+ const val HOME = "home"
+ const val MOVIES = "movies"
+ const val SERIES = "series"
+ const val VOD = "vod"
+ const val SEARCH = "search"
+ const val SEARCH_DESTINATION = "search?query={query}"
+ const val MOVIE_DETAIL = "movie_detail/{movieId}?returnRoute={returnRoute}"
+ const val SERIES_DETAIL = "series_detail/{seriesId}?returnRoute={returnRoute}"
+ const val MOVIE_DETAIL_PRESENTATION_HINT_KEY = "movie_detail_presentation_hint"
+ const val SERIES_DETAIL_PRESENTATION_HINT_KEY = "series_detail_presentation_hint"
+}
diff --git a/feature/catalog/src/test/java/com/streamvault/feature/catalog/api/CatalogFeatureContractsTest.kt b/feature/catalog/src/test/java/com/streamvault/feature/catalog/api/CatalogFeatureContractsTest.kt
new file mode 100644
index 00000000..0c29a929
--- /dev/null
+++ b/feature/catalog/src/test/java/com/streamvault/feature/catalog/api/CatalogFeatureContractsTest.kt
@@ -0,0 +1,127 @@
+package com.streamvault.feature.catalog.api
+
+import com.google.common.truth.Truth.assertThat
+import com.streamvault.core.navigation.AppDestination
+import com.streamvault.domain.model.Result
+import com.streamvault.domain.model.StreamInfo
+import kotlinx.coroutines.flow.Flow
+import kotlinx.coroutines.flow.MutableStateFlow
+import kotlinx.coroutines.flow.MutableSharedFlow
+import org.junit.Test
+
+class CatalogFeatureContractsTest {
+ @Test
+ fun `cast request preserves feature owned presentation inputs`() {
+ val streamInfo = StreamInfo(url = "https://example.test/movie.m3u8")
+ val request = CatalogCastRequest(
+ streamInfo = streamInfo,
+ title = "Title",
+ subtitle = "Subtitle",
+ artworkUrl = "art",
+ startPositionMs = 42_000L,
+ )
+
+ assertThat(request.streamInfo).isEqualTo(streamInfo)
+ assertThat(request.title).isEqualTo("Title")
+ assertThat(request.subtitle).isEqualTo("Subtitle")
+ assertThat(request.artworkUrl).isEqualTo("art")
+ assertThat(request.startPositionMs).isEqualTo(42_000L)
+ }
+
+ @Test
+ fun `catalog ports accept app independent fakes`() {
+ val platformHost = FakePlatformHost()
+ val streamPreparer = FakeStreamPreparer()
+ val downloadStarter = FakeDownloadStarter()
+ val castPort = FakeCastPort()
+ val updatePort = FakeUpdatePort()
+
+ platformHost.openCastRouteChooser()
+ downloadStarter.startDownload("download-1")
+
+ assertThat(platformHost.openedChooser).isTrue()
+ assertThat(downloadStarter.startedIds).containsExactly("download-1")
+ assertThat(streamPreparer).isInstanceOf(CatalogStreamPreparer::class.java)
+ assertThat(castPort).isInstanceOf(CatalogCastPort::class.java)
+ assertThat(updatePort).isInstanceOf(CatalogAppUpdatePort::class.java)
+ }
+
+ @Test
+ fun `catalog result and event models preserve exhaustive states`() {
+ val started: CatalogCastStartResult = CatalogCastStartResult.Started
+ val routeSelection: CatalogCastStartResult = CatalogCastStartResult.RouteSelectionRequired
+ val unavailable: CatalogCastStartResult = CatalogCastStartResult.Unavailable
+ val unsupported: CatalogCastStartResult =
+ CatalogCastStartResult.Unsupported(CatalogMessage.CastUnsupported)
+ val finished: CatalogCastPlaybackEvent =
+ CatalogCastPlaybackEvent.Finished(true, CatalogMessage.CastStarted)
+ val cancelled: CatalogCastPlaybackEvent = CatalogCastPlaybackEvent.RouteSelectionCancelled
+
+ assertThat(started).isEqualTo(CatalogCastStartResult.Started)
+ assertThat(routeSelection).isEqualTo(CatalogCastStartResult.RouteSelectionRequired)
+ assertThat(unavailable).isEqualTo(CatalogCastStartResult.Unavailable)
+ assertThat(unsupported).isEqualTo(
+ CatalogCastStartResult.Unsupported(CatalogMessage.CastUnsupported)
+ )
+ assertThat(finished).isEqualTo(
+ CatalogCastPlaybackEvent.Finished(true, CatalogMessage.CastStarted)
+ )
+ assertThat(cancelled).isEqualTo(CatalogCastPlaybackEvent.RouteSelectionCancelled)
+ assertThat(CatalogUiEvent.OpenCastRouteChooser)
+ .isEqualTo(CatalogUiEvent.OpenCastRouteChooser)
+ assertThat(CatalogUiEvent.ShowMessage(CatalogMessage.DownloadStarted).message)
+ .isEqualTo(CatalogMessage.DownloadStarted)
+ }
+
+ @Test
+ fun `channel playback context carries typed return destination`() {
+ val context = CatalogChannelPlaybackContext(
+ categoryId = 7L,
+ providerId = 11L,
+ isVirtual = true,
+ combinedProfileId = 13L,
+ returnDestination = AppDestination.Home,
+ )
+
+ assertThat(context.categoryId).isEqualTo(7L)
+ assertThat(context.providerId).isEqualTo(11L)
+ assertThat(context.isVirtual).isTrue()
+ assertThat(context.combinedProfileId).isEqualTo(13L)
+ assertThat(context.returnDestination).isEqualTo(AppDestination.Home)
+ }
+
+ private class FakePlatformHost : CatalogPlatformHost {
+ var openedChooser = false
+
+ override fun openCastRouteChooser() {
+ openedChooser = true
+ }
+ }
+
+ private class FakeStreamPreparer : CatalogStreamPreparer {
+ override suspend fun prepare(streamInfo: StreamInfo): Result<StreamInfo> =
+ Result.Success(streamInfo)
+ }
+
+ private class FakeDownloadStarter : CatalogDownloadStarter {
+ val startedIds = mutableListOf<String>()
+
+ override fun startDownload(downloadId: String) {
+ startedIds += downloadId
+ }
+ }
+
+ private class FakeCastPort : CatalogCastPort {
+ override val playbackEvents: Flow<CatalogCastPlaybackEvent> = MutableSharedFlow()
+
+ override suspend fun startCasting(request: CatalogCastRequest): CatalogCastStartResult =
+ CatalogCastStartResult.Started
+ }
+
+ private class FakeUpdatePort : CatalogAppUpdatePort {
+ override val notice: Flow<CatalogUpdateNotice?> = MutableStateFlow(null)
+
+ override suspend fun installDownloadedUpdate(expectedSha256: String?): Result<Unit> =
+ Result.Success(Unit)
+ }
+}
diff --git a/feature/catalog/src/test/java/com/streamvault/feature/catalog/navigation/CatalogRoutePatternsTest.kt b/feature/catalog/src/test/java/com/streamvault/feature/catalog/navigation/CatalogRoutePatternsTest.kt
new file mode 100644
index 00000000..1e4a5e19
--- /dev/null
+++ b/feature/catalog/src/test/java/com/streamvault/feature/catalog/navigation/CatalogRoutePatternsTest.kt
@@ -0,0 +1,27 @@
+package com.streamvault.feature.catalog.navigation
+
+import com.google.common.truth.Truth.assertThat
+import org.junit.Test
+
+class CatalogRoutePatternsTest {
+ @Test
+ fun `catalog route values preserve app compatibility`() {
+ assertThat(CatalogRoutePatterns.HOME).isEqualTo("home")
+ assertThat(CatalogRoutePatterns.MOVIES).isEqualTo("movies")
+ assertThat(CatalogRoutePatterns.SERIES).isEqualTo("series")
+ assertThat(CatalogRoutePatterns.VOD).isEqualTo("vod")
+ assertThat(CatalogRoutePatterns.SEARCH_DESTINATION).isEqualTo("search?query={query}")
+ assertThat(CatalogRoutePatterns.MOVIE_DETAIL)
+ .isEqualTo("movie_detail/{movieId}?returnRoute={returnRoute}")
+ assertThat(CatalogRoutePatterns.SERIES_DETAIL)
+ .isEqualTo("series_detail/{seriesId}?returnRoute={returnRoute}")
+ }
+
+ @Test
+ fun `presentation hint keys remain stable`() {
+ assertThat(CatalogRoutePatterns.MOVIE_DETAIL_PRESENTATION_HINT_KEY)
+ .isEqualTo("movie_detail_presentation_hint")
+ assertThat(CatalogRoutePatterns.SERIES_DETAIL_PRESENTATION_HINT_KEY)
+ .isEqualTo("series_detail_presentation_hint")
+ }
+}