Add generic PushProvider abstraction for notification delivery

Introduce a PushProvider interface that abstracts push notification
delivery, allowing the user to choose between available providers
(FCM, WebSocket) via a new "Push provider" setting under Notifications.

This lays the groundwork for additional providers (e.g. UnifiedPush)
without coupling the abstraction to any specific implementation.

- Add PushProvider interface with name, isAvailable, isActive, register,
  unregister, and requiresPersistentConnection
- Add PushProviderManager for provider selection and server registration
- Add FcmPushProvider (full flavor) and WebSocketPushProvider
- Add Dagger multibinding modules for both flavors
- Add "Push provider" ListPreference in Notifications settings
- Add WebsocketManager.restart() for instant provider switching
- Extend DeviceRegistration with pushUrl and pushEncrypt fields
- Add 28 unit tests for PushProvider and PushProviderManager

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: aaronstealth

app/src/full/kotlin/io/homeassistant/companion/android/push/FcmPushProvider.kt

@@ -0,0 +1,69 @@
+package io.homeassistant.companion.android.push
+
+import io.homeassistant.companion.android.common.push.PushProvider
+import io.homeassistant.companion.android.common.push.PushRegistrationResult
+import io.homeassistant.companion.android.common.util.MessagingTokenProvider
+import javax.inject.Inject
+import javax.inject.Singleton
+import timber.log.Timber
+
+/**
+ * Push provider implementation backed by Firebase Cloud Messaging.
+ *
+ * Only available in the "full" build flavor.
+ */
+@Singleton
+class FcmPushProvider @Inject constructor(
+    private val messagingTokenProvider: MessagingTokenProvider,
+) : PushProvider {
+
+    override val name: String = NAME
+
+    override suspend fun isAvailable(): Boolean {
+        return try {
+            val token = messagingTokenProvider()
+            !token.isBlank()
+        } catch (e: Exception) {
+            Timber.e(e, "FCM is not available")
+            false
+        }
+    }
+
+    override suspend fun isActive(): Boolean {
+        return try {
+            val token = messagingTokenProvider()
+            !token.isBlank()
+        } catch (e: Exception) {
+            false
+        }
+    }
+
+    override suspend fun register(): PushRegistrationResult? {
+        return try {
+            val token = messagingTokenProvider()
+            if (token.isBlank()) {
+                Timber.w("FCM token is blank")
+                null
+            } else {
+                PushRegistrationResult(
+                    pushToken = token.value,
+                    pushUrl = "", // Empty URL means use built-in push URL
+                    encrypt = false,
+                )
+            }
+        } catch (e: Exception) {
+            Timber.e(e, "Failed to register FCM")
+            null
+        }
+    }
+
+    override suspend fun unregister() {
+        // FCM doesn't need explicit unregistration in this context.
+        // Token invalidation is handled by Firebase automatically.
+        Timber.d("FCM unregister called (no-op)")
+    }
+
+    companion object {
+        const val NAME = "FCM"
+    }
+}

app/src/full/kotlin/io/homeassistant/companion/android/push/PushProviderModule.kt

@@ -0,0 +1,25 @@
+package io.homeassistant.companion.android.push
+
+import dagger.Binds
+import dagger.Module
+import dagger.hilt.InstallIn
+import dagger.hilt.components.SingletonComponent
+import dagger.multibindings.IntoSet
+import io.homeassistant.companion.android.common.push.PushProvider
+
+/**
+ * Dagger module that provides push provider implementations for the full flavor.
+ * Includes FCM and WebSocket providers.
+ */
+@Module
+@InstallIn(SingletonComponent::class)
+abstract class PushProviderModule {
+
+    @Binds
+    @IntoSet
+    abstract fun bindFcmPushProvider(provider: FcmPushProvider): PushProvider
+
+    @Binds
+    @IntoSet
+    abstract fun bindWebSocketPushProvider(provider: WebSocketPushProvider): PushProvider
+}

app/src/main/kotlin/io/homeassistant/companion/android/push/WebSocketPushProvider.kt

@@ -0,0 +1,57 @@
+package io.homeassistant.companion.android.push
+
+import android.content.Context
+import dagger.hilt.android.qualifiers.ApplicationContext
+import io.homeassistant.companion.android.common.data.servers.ServerManager
+import io.homeassistant.companion.android.common.push.PushProvider
+import io.homeassistant.companion.android.common.push.PushRegistrationResult
+import io.homeassistant.companion.android.database.settings.SettingsDao
+import io.homeassistant.companion.android.database.settings.WebsocketSetting
+import javax.inject.Inject
+import javax.inject.Singleton
+import timber.log.Timber
+
+/**
+ * Push provider implementation backed by a persistent WebSocket connection.
+ *
+ * This is always available and uses a persistent connection.
+ * Used by the minimal flavor when no other provider is selected.
+ */
+@Singleton
+class WebSocketPushProvider @Inject constructor(
+    @ApplicationContext private val context: Context,
+    private val serverManager: ServerManager,
+    private val settingsDao: SettingsDao,
+) : PushProvider {
+
+    override val name: String = NAME
+
+    override val requiresPersistentConnection: Boolean = true
+
+    override suspend fun isAvailable(): Boolean = true
+
+    override suspend fun isActive(): Boolean {
+        if (!serverManager.isRegistered()) return false
+        return serverManager.servers().any { server ->
+            val setting = settingsDao.get(server.id)?.websocketSetting
+            setting != null && setting != WebsocketSetting.NEVER
+        }
+    }
+
+    override suspend fun register(): PushRegistrationResult {
+        Timber.d("WebSocket push provider registered (persistent connection mode)")
+        return PushRegistrationResult(
+            pushToken = "",
+            pushUrl = null,
+            encrypt = false,
+        )
+    }
+
+    override suspend fun unregister() {
+        Timber.d("WebSocket push provider unregistered")
+    }
+
+    companion object {
+        const val NAME = "WebSocket"
+    }
+}

app/src/main/kotlin/io/homeassistant/companion/android/settings/SettingsFragment.kt

@@ -2,6 +2,7 @@ package io.homeassistant.companion.android.settings
 
 import android.app.UiModeManager
 import android.content.Intent
+import android.widget.Toast
 import android.content.pm.PackageManager
 import android.content.res.Configuration
 import android.os.Build
@@ -52,6 +53,7 @@ import io.homeassistant.companion.android.settings.wear.SettingsWearActivity
 import io.homeassistant.companion.android.settings.wear.SettingsWearDetection
 import io.homeassistant.companion.android.settings.widgets.ManageWidgetsSettingsFragment
 import io.homeassistant.companion.android.util.QuestUtil
+import io.homeassistant.companion.android.websocket.WebsocketManager
 import io.homeassistant.companion.android.util.applyBottomSafeDrawingInsets
 import io.homeassistant.companion.android.webview.WebViewActivity
 import java.time.Instant
@@ -61,6 +63,7 @@ import java.time.format.FormatStyle
 import kotlinx.coroutines.Dispatchers
 import kotlinx.coroutines.launch
 import kotlinx.coroutines.sync.Mutex
+import kotlinx.coroutines.withContext
 import kotlinx.coroutines.sync.withLock
 import timber.log.Timber
 
@@ -250,6 +253,7 @@ class SettingsFragment(
         }
 
         updateNotificationChannelPrefs()
+        updatePushProviderPrefs()
 
         if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
             findPreference<Preference>("notification_permission")?.let {
@@ -541,6 +545,46 @@ class SettingsFragment(
         }
     }
 
+    private fun updatePushProviderPrefs() {
+        findPreference<ListPreference>("notification_push_provider")?.let { pref ->
+            pref.preferenceDataStore = null
+            pref.setOnPreferenceChangeListener { _, newValue ->
+                val value = newValue as? String
+                lifecycleScope.launch(Dispatchers.IO) {
+                    presenter.handlePushProviderChange(value)
+                }
+                if (value == "WebSocket") {
+                    Toast.makeText(requireContext(), commonR.string.push_provider_websocket_enabled, Toast.LENGTH_SHORT).show()
+                    lifecycleScope.launch {
+                        WebsocketManager.restart(requireContext())
+                    }
+                }
+                true
+            }
+
+            lifecycleScope.launch(Dispatchers.IO) {
+                val entries = mutableListOf<String>()
+                val values = mutableListOf<String>()
+
+                val providers = presenter.getAvailablePushProviders()
+                for (provider in providers) {
+                    entries.add(provider.second)
+                    values.add(provider.first)
+                }
+
+                val activeValue = presenter.getActivePushProviderValue()
+
+                withContext(Dispatchers.Main) {
+                    pref.entries = entries.toTypedArray()
+                    pref.entryValues = values.toTypedArray()
+                    if (pref.value == null || pref.value !in values) {
+                        pref.value = activeValue
+                    }
+                }
+            }
+        }
+    }
+
     private fun onServerLockResult(result: Int): Boolean {
         if (result == Authenticator.SUCCESS && serverAuth != null) {
             (activity as? SettingsActivity)?.setAppActive(serverAuth, true)

app/src/main/kotlin/io/homeassistant/companion/android/settings/SettingsPresenter.kt

@@ -24,4 +24,7 @@ interface SettingsPresenter {
     suspend fun showChangeLog(context: Context)
     suspend fun isChangeLogPopupEnabled(): Boolean
     suspend fun setChangeLogPopupEnabled(enabled: Boolean)
+    fun getAvailablePushProviders(): List<Pair<String, String>>
+    fun getActivePushProviderValue(): String
+    fun handlePushProviderChange(value: String?)
 }

app/src/main/kotlin/io/homeassistant/companion/android/settings/SettingsPresenterImpl.kt

@@ -13,6 +13,7 @@ import io.homeassistant.companion.android.common.data.integration.impl.entities.
 import io.homeassistant.companion.android.common.data.prefs.NightModeTheme
 import io.homeassistant.companion.android.common.data.prefs.PrefsRepository
 import io.homeassistant.companion.android.common.data.servers.ServerManager
+import io.homeassistant.companion.android.common.push.PushProviderManager
 import io.homeassistant.companion.android.database.server.Server
 import io.homeassistant.companion.android.database.settings.SettingsDao
 import io.homeassistant.companion.android.settings.assist.DefaultAssistantManager
@@ -40,6 +41,7 @@ class SettingsPresenterImpl @Inject constructor(
     private val changeLog: ChangeLog,
     private val settingsDao: SettingsDao,
     private val defaultAssistantManager: DefaultAssistantManager,
+    private val pushProviderManager: PushProviderManager,
 ) : PreferenceDataStore(),
     SettingsPresenter {
 
@@ -58,6 +60,7 @@ class SettingsPresenterImpl @Inject constructor(
     )
 
     private var suggestionFlow = MutableStateFlow<SettingsHomeSuggestion?>(null)
+    private var selectedPushProvider: String? = null
 
     override fun getBoolean(key: String, defValue: Boolean): Boolean = runBlocking {
         return@runBlocking when (key) {
@@ -113,6 +116,7 @@ class SettingsPresenterImpl @Inject constructor(
             "languages" -> langsManager.getCurrentLang()
             "page_zoom" -> prefsRepository.getPageZoomLevel().toString()
             "screen_orientation" -> prefsRepository.getScreenOrientation()
+            "notification_push_provider" -> selectedPushProvider
             else -> throw IllegalArgumentException("No string found by this key: $key")
         }
     }
@@ -124,6 +128,7 @@ class SettingsPresenterImpl @Inject constructor(
                 "languages" -> langsManager.saveLang(value)
                 "page_zoom" -> prefsRepository.setPageZoomLevel(value?.toIntOrNull())
                 "screen_orientation" -> prefsRepository.saveScreenOrientation(value)
+                "notification_push_provider" -> handlePushProviderChange(value)
                 else -> throw IllegalArgumentException("No string found by this key: $key")
             }
         }
@@ -218,6 +223,27 @@ class SettingsPresenterImpl @Inject constructor(
         }
     }
 
+    override fun getAvailablePushProviders(): List<Pair<String, String>> {
+        return pushProviderManager.getAllProviders().map { provider ->
+            val label = when (provider.name) {
+                "FCM" -> "Firebase Cloud Messaging"
+                "WebSocket" -> "WebSocket"
+                else -> provider.name
+            }
+            provider.name to label
+        }
+    }
+
+    override fun getActivePushProviderValue(): String {
+        selectedPushProvider?.let { return it }
+        return "WebSocket"
+    }
+
+    override fun handlePushProviderChange(value: String?) {
+        if (value == null) return
+        selectedPushProvider = value
+    }
+
     private fun enableLauncherMode(enable: Boolean) {
         view.getPackageManager()?.setComponentEnabledSetting(
             launcherAliasComponent,

app/src/main/kotlin/io/homeassistant/companion/android/websocket/WebsocketManager.kt

@@ -62,6 +62,17 @@ class WebsocketManager(appContext: Context, workerParams: WorkerParameters) :
             WebsocketSetting.ALWAYS
         }
 
+        suspend fun restart(context: Context) {
+            val websocketNotifications =
+                PeriodicWorkRequestBuilder<WebsocketManager>(15, TimeUnit.MINUTES)
+                    .build()
+            WorkManager.getInstance(context).enqueueUniquePeriodicWork(
+                UNIQUE_WORK_NAME,
+                ExistingPeriodicWorkPolicy.CANCEL_AND_REENQUEUE,
+                websocketNotifications,
+            )
+        }
+
         suspend fun start(context: Context) {
             val websocketNotifications =
                 PeriodicWorkRequestBuilder<WebsocketManager>(15, TimeUnit.MINUTES)

app/src/main/res/xml/preferences.xml

@@ -131,6 +131,11 @@
             app:enableCopying="true"
             android:icon="@drawable/ic_notifications"
             android:summary="@string/rate_limit_summary"/>
+        <ListPreference
+            android:key="notification_push_provider"
+            android:title="@string/push_provider"
+            android:icon="@drawable/ic_notifications"
+            app:useSimpleSummaryProvider="true"/>
     </PreferenceCategory>
     <PreferenceCategory
         android:title="@string/assist"

app/src/minimal/kotlin/io/homeassistant/companion/android/push/PushProviderModule.kt

@@ -0,0 +1,21 @@
+package io.homeassistant.companion.android.push
+
+import dagger.Binds
+import dagger.Module
+import dagger.hilt.InstallIn
+import dagger.hilt.components.SingletonComponent
+import dagger.multibindings.IntoSet
+import io.homeassistant.companion.android.common.push.PushProvider
+
+/**
+ * Dagger module that provides push provider implementations for the minimal flavor.
+ * Includes WebSocket provider only (no FCM).
+ */
+@Module
+@InstallIn(SingletonComponent::class)
+abstract class PushProviderModule {
+
+    @Binds
+    @IntoSet
+    abstract fun bindWebSocketPushProvider(provider: WebSocketPushProvider): PushProvider
+}

common/src/main/kotlin/io/homeassistant/companion/android/common/data/integration/DeviceRegistration.kt

@@ -8,7 +8,9 @@ data class DeviceRegistration(
     val appVersion: AppVersion? = null,
     val deviceName: String? = null,
     var pushToken: MessagingToken? = null,
+    var pushUrl: String? = null,
     var pushWebsocket: Boolean = true,
+    var pushEncrypt: Boolean = false,
 )
 
 @Qualifier