Add tests and update KDoc

Author: aleksandar-apostolov

stream-android-core/src/main/java/io/getstream/android/core/api/StreamClient.kt

@@ -293,7 +293,7 @@ public fun StreamClient(
     cidWatcher: StreamCidWatcher = StreamCidWatcher(
         logProvider.taggedLogger("SCCidRewatcher"),
         streamRewatchSubscriptionManager = StreamSubscriptionManager(
-            logger = logProvider.taggedLogger("SCRewatchSubscritionManager")
+            logger = logProvider.taggedLogger("SCRewatchSubscriptionManager")
         ),
         streamClientSubscriptionManager = clientSubscriptionManager,
     )
@@ -354,7 +354,7 @@ public fun StreamClient(
 
     if (watchListener != null) {
         // Auto-subscribe the re-watch listener if any
-        cidWatcher.subscribe(watchListener)
+        cidWatcher.subscribe(watchListener).getOrThrow()
     }
 
     val mutableConnectionState = MutableStateFlow<StreamConnectionState>(StreamConnectionState.Idle)

stream-android-core/src/main/java/io/getstream/android/core/api/watcher/StreamCidRewatchListener.kt

@@ -3,8 +3,82 @@ package io.getstream.android.core.api.watcher
 import io.getstream.android.core.annotations.StreamInternalApi
 import io.getstream.android.core.api.model.StreamCid
 
+/**
+ * Callback interface invoked when watched resources need to be re-subscribed after a connection
+ * state change.
+ *
+ * This functional interface is used with [StreamCidWatcher] to receive notifications when the
+ * WebSocket connection state changes (especially during reconnections), allowing the product SDK
+ * to re-establish server-side watches for all actively monitored resources.
+ *
+ * ## When This Is Called
+ *
+ * The callback is triggered on every [StreamConnectionState.Connected] event when the watched
+ * CID registry is non-empty. This ensures that all active subscriptions are restored after:
+ * - Initial connection establishment
+ * - Network reconnection after temporary disconnection
+ * - WebSocket recovery after connection loss
+ *
+ * ## Threading
+ *
+ * - The callback is invoked asynchronously on an internal coroutine scope
+ * - Implementations should be thread-safe as concurrent invocations are possible
+ * - Long-running operations should be dispatched to an appropriate dispatcher
+ *
+ * ## Error Handling
+ *
+ * - Exceptions thrown by this callback are caught and logged by the watcher
+ * - Errors are also surfaced via [StreamClientListener.onError] for user-level handling
+ * - A failing callback will not prevent other listeners from being notified
+ *
+ * ## Example Usage
+ *
+ * ```kotlin
+ * val watcher = StreamCidWatcher(logger, rewatchManager, clientManager)
+ *
+ * // Register a rewatch listener
+ * watcher.subscribe(
+ *     listener = StreamCidRewatchListener { cids ->
+ *         logger.i { "Re-watching ${cids.size} channels" }
+ *         cids.forEach { cid ->
+ *             // Re-establish server-side watch for each CID
+ *             channelClient.watch(cid)
+ *         }
+ *     }
+ * )
+ *
+ * watcher.start()
+ * ```
+ *
+ * @see StreamCidWatcher Main component that manages the watch registry and triggers callbacks
+ * @see StreamCid Channel identifier in format "type:id" (e.g., "messaging:general")
+ */
 @StreamInternalApi
 public fun interface StreamCidRewatchListener {
 
+    /**
+     * Called when watched resources need to be re-subscribed.
+     *
+     * This method is invoked with the complete list of [StreamCid]s currently in the watch
+     * registry whenever the connection state changes to [StreamConnectionState.Connected] and
+     * the registry is non-empty.
+     *
+     * Implementations should iterate over the provided list and re-establish server-side watches
+     * for each CID to maintain active subscriptions across reconnection cycles.
+     *
+     * ## Contract
+     *
+     * - The list is never empty when this method is called
+     * - The list represents a snapshot of the watch registry at the time of invocation
+     * - Modifications to the list do not affect the internal registry
+     * - Multiple calls may occur for the same set of CIDs during reconnection scenarios
+     *
+     * ## Error Handling
+     *
+     * Exceptions thrown by this method are caught, logged, and surfaced via error callbacks.
+     * The failure of one listener does not prevent other listeners from being notified.
+     *
+     * @param list A non-empty list of [StreamCid]s that require re-watching
+     */
     public fun onRewatch(list: List<StreamCid>)
 }

stream-android-core/src/main/java/io/getstream/android/core/api/watcher/StreamCidWatcher.kt

@@ -23,10 +23,10 @@ import io.getstream.android.core.internal.watcher.StreamCidWatcherImpl
  *
  * 1. Product SDK watches a channel: `watcher.watch(StreamCid.parse("messaging:general"))`
  * 2. Watcher adds the CID to its internal registry
- * 3. Product SDK registers a rewatch callback: `watcher.onRewatch { cids -> resubscribe(cids) }`
+ * 3. Product SDK registers a rewatch listener: `watcher.subscribe(StreamCidRewatchListener { cids -> resubscribe(cids) })`
  * 4. Call `watcher.start()` to begin monitoring connection state changes
  * 5. Connection state changes (e.g., reconnection after network loss)
- * 6. Watcher invokes callback with all watched CIDs: `["messaging:general", "livestream:sports"]`
+ * 6. Watcher invokes listener with all watched CIDs: `["messaging:general", "livestream:sports"]`
  * 7. Product SDK re-establishes server-side watches for each CID
  *
  * ## Threading
@@ -97,8 +97,8 @@ public interface StreamCidWatcher : StreamObservable<StreamCidRewatchListener>,
     /**
      * Removes all entries from the watch registry.
      *
-     * After calling this method, the rewatch callback will be invoked with an empty list on
-     * subsequent connection state changes until new resources are watched.
+     * After calling this method, the rewatch callback will NOT be invoked on subsequent
+     * connection state changes (since the registry is empty) until new resources are watched.
      *
      * This method is typically called during cleanup or logout to ensure no stale watches remain.
      *