Skip to content

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

feat: add typed navigation contracts

David Nashash3eefa17ddd43
diff --git a/core/navigation/src/main/kotlin/com/streamvault/core/navigation/AppDestination.kt b/core/navigation/src/main/kotlin/com/streamvault/core/navigation/AppDestination.kt
new file mode 100644
index 00000000..7303cc79
--- /dev/null
+++ b/core/navigation/src/main/kotlin/com/streamvault/core/navigation/AppDestination.kt
@@ -0,0 +1,48 @@
+package com.streamvault.core.navigation
+
+import java.io.Serializable
+
+sealed interface AppDestination : Serializable {
+ data object Welcome : AppDestination
+ data object Home : AppDestination
+ data class LiveTv(val categoryId: Long? = null) : AppDestination
+ data object Movies : AppDestination
+ data object Series : AppDestination
+ data object Vod : AppDestination
+ data object Downloads : AppDestination
+ data class Guide(
+ val categoryId: Long? = null,
+ val anchorTimeMs: Long? = null,
+ val favoritesOnly: Boolean = false
+ ) : AppDestination
+ data class Settings(val backupUri: String? = null) : AppDestination
+ data object Plugins : AppDestination
+ data class Search(val query: String? = null) : AppDestination
+ data class ProviderSetup(
+ val providerId: Long? = null,
+ val importUri: String? = null
+ ) : AppDestination
+ data class MovieDetail(
+ val movieId: Long,
+ val returnDestination: AppDestination? = null
+ ) : AppDestination {
+ init {
+ require(movieId > 0L) { "movieId must be positive" }
+ }
+ }
+ data class SeriesDetail(
+ val seriesId: Long,
+ val returnDestination: AppDestination? = null
+ ) : AppDestination {
+ init {
+ require(seriesId > 0L) { "seriesId must be positive" }
+ }
+ }
+ data class ParentalControlGroups(val providerId: Long) : AppDestination {
+ init {
+ require(providerId > 0L) { "providerId must be positive" }
+ }
+ }
+ data object Player : AppDestination
+ data object MultiView : AppDestination
+}
diff --git a/core/navigation/src/main/kotlin/com/streamvault/core/navigation/NavigationActions.kt b/core/navigation/src/main/kotlin/com/streamvault/core/navigation/NavigationActions.kt
new file mode 100644
index 00000000..95155f86
--- /dev/null
+++ b/core/navigation/src/main/kotlin/com/streamvault/core/navigation/NavigationActions.kt
@@ -0,0 +1,14 @@
+package com.streamvault.core.navigation
+
+interface NavigationActions {
+ fun navigate(
+ destination: AppDestination,
+ options: NavigationOptions = NavigationOptions()
+ )
+
+ fun openPlayer(request: PlayerNavigationRequest)
+
+ fun back(): Boolean
+
+ fun returnTo(destination: AppDestination?): Boolean
+}
diff --git a/core/navigation/src/main/kotlin/com/streamvault/core/navigation/NavigationRequest.kt b/core/navigation/src/main/kotlin/com/streamvault/core/navigation/NavigationRequest.kt
new file mode 100644
index 00000000..afd9ecdc
--- /dev/null
+++ b/core/navigation/src/main/kotlin/com/streamvault/core/navigation/NavigationRequest.kt
@@ -0,0 +1,32 @@
+package com.streamvault.core.navigation
+
+import java.io.Serializable
+
+sealed interface ExternalNavigationRequest : Serializable {
+ data class Search(val query: String) : ExternalNavigationRequest
+ data class Player(val request: PlayerNavigationRequest) : ExternalNavigationRequest
+ data class Destination(val destination: AppDestination) : ExternalNavigationRequest
+ data class ImportM3u(val uri: String) : ExternalNavigationRequest
+ data class ImportBackup(val uri: String) : ExternalNavigationRequest
+}
+
+data class NavigationOptions(
+ val launchSingleTop: Boolean = false,
+ val restoreState: Boolean = false,
+ val saveState: Boolean = false,
+ val popUpTo: AppDestination? = null,
+ val inclusive: Boolean = false
+) : Serializable
+
+sealed interface NavigationCommand : Serializable {
+ data class Navigate(
+ val destination: AppDestination,
+ val options: NavigationOptions = NavigationOptions()
+ ) : NavigationCommand
+
+ data class OpenPlayer(val request: PlayerNavigationRequest) : NavigationCommand
+
+ data object Back : NavigationCommand
+
+ data class ReturnTo(val destination: AppDestination?) : NavigationCommand
+}
diff --git a/core/navigation/src/main/kotlin/com/streamvault/core/navigation/PlayerNavigationRequest.kt b/core/navigation/src/main/kotlin/com/streamvault/core/navigation/PlayerNavigationRequest.kt
new file mode 100644
index 00000000..91d45a16
--- /dev/null
+++ b/core/navigation/src/main/kotlin/com/streamvault/core/navigation/PlayerNavigationRequest.kt
@@ -0,0 +1,25 @@
+package com.streamvault.core.navigation
+
+import java.io.Serializable
+
+data class PlayerNavigationRequest(
+ val streamUrl: String,
+ val title: String,
+ val channelId: String? = null,
+ val internalId: Long = -1L,
+ val categoryId: Long? = null,
+ val providerId: Long? = null,
+ val isVirtual: Boolean = false,
+ val combinedProfileId: Long? = null,
+ val combinedSourceFilterProviderId: Long? = null,
+ val contentType: String = "LIVE",
+ val artworkUrl: String? = null,
+ val archiveStartMs: Long? = null,
+ val archiveEndMs: Long? = null,
+ val archiveTitle: String? = null,
+ val returnDestination: AppDestination? = null,
+ val seriesId: Long? = null,
+ val seasonNumber: Int? = null,
+ val episodeNumber: Int? = null,
+ val episodeId: Long? = null
+) : Serializable
diff --git a/core/navigation/src/test/kotlin/com/streamvault/core/navigation/AppDestinationTest.kt b/core/navigation/src/test/kotlin/com/streamvault/core/navigation/AppDestinationTest.kt
new file mode 100644
index 00000000..b8fcbf6c
--- /dev/null
+++ b/core/navigation/src/test/kotlin/com/streamvault/core/navigation/AppDestinationTest.kt
@@ -0,0 +1,29 @@
+package com.streamvault.core.navigation
+
+import com.google.common.truth.Truth.assertThat
+import org.junit.Test
+
+class AppDestinationTest {
+ @Test
+ fun detailDestinationKeepsTypedReturnTarget() {
+ val destination = AppDestination.MovieDetail(
+ movieId = 42L,
+ returnDestination = AppDestination.Search("night")
+ )
+
+ assertThat(destination.movieId).isEqualTo(42L)
+ assertThat(destination.returnDestination)
+ .isEqualTo(AppDestination.Search("night"))
+ }
+
+ @Test
+ fun destinationsRejectInvalidIdentityValues() {
+ val invalidMovie = runCatching { AppDestination.MovieDetail(0L) }
+ val invalidSeries = runCatching { AppDestination.SeriesDetail(-1L) }
+ val invalidParentalGroups = runCatching { AppDestination.ParentalControlGroups(0L) }
+
+ assertThat(invalidMovie.isFailure).isTrue()
+ assertThat(invalidSeries.isFailure).isTrue()
+ assertThat(invalidParentalGroups.isFailure).isTrue()
+ }
+}
diff --git a/core/navigation/src/test/kotlin/com/streamvault/core/navigation/NavigationRequestTest.kt b/core/navigation/src/test/kotlin/com/streamvault/core/navigation/NavigationRequestTest.kt
new file mode 100644
index 00000000..dac9e2e3
--- /dev/null
+++ b/core/navigation/src/test/kotlin/com/streamvault/core/navigation/NavigationRequestTest.kt
@@ -0,0 +1,55 @@
+package com.streamvault.core.navigation
+
+import com.google.common.truth.Truth.assertThat
+import org.junit.Test
+
+class NavigationRequestTest {
+ @Test
+ fun externalAndInternalRequestsRemainTyped() {
+ assertThat(ExternalNavigationRequest.Search("sports"))
+ .isNotEqualTo(ExternalNavigationRequest.Destination(AppDestination.Home))
+ assertThat(NavigationCommand.OpenPlayer(PlayerNavigationRequest("https://x", "X")))
+ .isInstanceOf(NavigationCommand.OpenPlayer::class.java)
+ }
+
+ @Test
+ fun navigationActionsFakeRecordsTypedCommandsWithoutController() {
+ val actions = RecordingNavigationActions()
+ val destination = AppDestination.Search("news")
+ val request = PlayerNavigationRequest("https://example.com/live.m3u8", "News")
+
+ actions.navigate(destination, NavigationOptions(launchSingleTop = true))
+ actions.openPlayer(request)
+ actions.returnTo(AppDestination.Home)
+
+ assertThat(actions.navigations).containsExactly(
+ NavigationCommand.Navigate(
+ destination,
+ NavigationOptions(launchSingleTop = true)
+ )
+ )
+ assertThat(actions.players).containsExactly(request)
+ assertThat(actions.returns).containsExactly(AppDestination.Home)
+ }
+
+ private class RecordingNavigationActions : NavigationActions {
+ val navigations = mutableListOf<NavigationCommand.Navigate>()
+ val players = mutableListOf<PlayerNavigationRequest>()
+ val returns = mutableListOf<AppDestination?>()
+
+ override fun navigate(destination: AppDestination, options: NavigationOptions) {
+ navigations += NavigationCommand.Navigate(destination, options)
+ }
+
+ override fun openPlayer(request: PlayerNavigationRequest) {
+ players += request
+ }
+
+ override fun back(): Boolean = true
+
+ override fun returnTo(destination: AppDestination?): Boolean {
+ returns += destination
+ return true
+ }
+ }
+}
diff --git a/core/navigation/src/test/kotlin/com/streamvault/core/navigation/PlayerNavigationRequestTest.kt b/core/navigation/src/test/kotlin/com/streamvault/core/navigation/PlayerNavigationRequestTest.kt
new file mode 100644
index 00000000..9230a11c
--- /dev/null
+++ b/core/navigation/src/test/kotlin/com/streamvault/core/navigation/PlayerNavigationRequestTest.kt
@@ -0,0 +1,60 @@
+package com.streamvault.core.navigation
+
+import com.google.common.truth.Truth.assertThat
+import java.io.ByteArrayInputStream
+import java.io.ByteArrayOutputStream
+import java.io.ObjectInputStream
+import java.io.ObjectOutputStream
+import org.junit.Test
+
+class PlayerNavigationRequestTest {
+ @Test
+ fun serializableRoundTripPreservesEpisodeAndReturnIdentity() {
+ val request = PlayerNavigationRequest(
+ streamUrl = "https://example.com/e.m3u8",
+ title = "Episode",
+ providerId = 9L,
+ contentType = "SERIES_EPISODE",
+ returnDestination = AppDestination.SeriesDetail(12L),
+ seriesId = 12L,
+ seasonNumber = 3,
+ episodeNumber = 4,
+ episodeId = 77L
+ )
+
+ val bytes = ByteArrayOutputStream()
+ ObjectOutputStream(bytes).use { it.writeObject(request) }
+ val restored = ObjectInputStream(ByteArrayInputStream(bytes.toByteArray()))
+ .use { it.readObject() as PlayerNavigationRequest }
+
+ assertThat(restored).isEqualTo(request)
+ }
+
+ @Test
+ fun requestPreservesArchiveAndCombinedSourceFields() {
+ val request = PlayerNavigationRequest(
+ streamUrl = "https://example.com/archive.m3u8",
+ title = "Morning News",
+ channelId = "news.hd",
+ internalId = 42L,
+ categoryId = -4L,
+ providerId = 7L,
+ isVirtual = true,
+ combinedProfileId = 11L,
+ combinedSourceFilterProviderId = 8L,
+ contentType = "LIVE",
+ artworkUrl = "https://example.com/news.png",
+ archiveStartMs = 1_700_000_000_000L,
+ archiveEndMs = 1_700_000_360_000L,
+ archiveTitle = "Morning News: 08:00",
+ returnDestination = AppDestination.LiveTv(-4L)
+ )
+
+ assertThat(request.archiveStartMs).isEqualTo(1_700_000_000_000L)
+ assertThat(request.archiveEndMs).isEqualTo(1_700_000_360_000L)
+ assertThat(request.archiveTitle).isEqualTo("Morning News: 08:00")
+ assertThat(request.combinedProfileId).isEqualTo(11L)
+ assertThat(request.combinedSourceFilterProviderId).isEqualTo(8L)
+ assertThat(request.returnDestination).isEqualTo(AppDestination.LiveTv(-4L))
+ }
+}