From 0142c5a415de95389fdee987d209b024ef5b70bf Mon Sep 17 00:00:00 2001
From: Aleksandar Apostolov <apostolov.alexandar@gmail.com>
Date: Mon, 8 Jun 2026 14:12:49 +0200
Subject: [PATCH] chore(core): deprecate StreamVideo.logOut
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The KDoc claimed `logOut` clears internal user state, removes push
notification devices, and clears call state. The actual implementation
only writes null to the local DeviceTokenStorage — no `DELETE /devices`,
no socket disconnect, no in-memory clear.

The name and the historical doc invite a customer to ship broken
user-switching: anyone reading the API surface would reasonably assume a
clean slate. Surfaced while diagnosing a customer integration where push
delivery silently failed across user transitions.

Annotate the interface declaration and the StreamVideoClient override
with `@Deprecated`. Update the KDoc to describe current behavior
accurately. Point `ReplaceWith` at `StreamVideo.removeClient()`, which
triggers a real `cleanup()` and uninstalls the singleton. Customers who
need to remove the server-side device row should call `deleteDevice()`
before `removeClient()`.

No binary signature change — `@Deprecated` is annotation-only, so the
public `.api` file is unchanged.

AND-1217
---
 .../video/android/core/StreamVideo.kt         | 21 ++++++++++++++++++-
 .../video/android/core/StreamVideoClient.kt   |  8 +++++++
 2 files changed, 28 insertions(+), 1 deletion(-)

diff --git a/stream-video-android-core/src/main/kotlin/io/getstream/video/android/core/StreamVideo.kt b/stream-video-android-core/src/main/kotlin/io/getstream/video/android/core/StreamVideo.kt
index 257c7813732..cdf499cbb15 100644
--- a/stream-video-android-core/src/main/kotlin/io/getstream/video/android/core/StreamVideo.kt
+++ b/stream-video-android-core/src/main/kotlin/io/getstream/video/android/core/StreamVideo.kt
@@ -153,8 +153,27 @@ public interface StreamVideo : NotificationHandler {
     public suspend fun connect(): Result<Long>
 
     /**
-     * Clears the internal user state, removes push notification devices and clears the call state.
+     * Clears the locally stored push device token only. Does not call the
+     * server `DELETE /devices` endpoint, disconnect the coordinator socket, or
+     * clear any in-memory user / call state. The name and historical KDoc
+     * misrepresented this behavior; the method is kept for source compatibility
+     * but should not be used.
+     *
+     * For a full teardown, call [deleteDevice] (if a server-side device row
+     * should be removed) and then [StreamVideo.removeClient], which triggers
+     * [cleanup] and uninstalls the singleton.
      */
+    @Deprecated(
+        message = "logOut() only clears the local push device cache; it does not log the user " +
+            "out, remove the server-side device row, or disconnect the socket. Use " +
+            "StreamVideo.removeClient() for a full teardown (combine with deleteDevice() " +
+            "first if the server-side device row must be removed).",
+        replaceWith = ReplaceWith(
+            expression = "StreamVideo.removeClient()",
+            imports = ["io.getstream.video.android.core.StreamVideo"],
+        ),
+        level = DeprecationLevel.WARNING,
+    )
     public fun logOut()
 
     public companion object {
diff --git a/stream-video-android-core/src/main/kotlin/io/getstream/video/android/core/StreamVideoClient.kt b/stream-video-android-core/src/main/kotlin/io/getstream/video/android/core/StreamVideoClient.kt
index b2dad697f82..7fc05fb10be 100644
--- a/stream-video-android-core/src/main/kotlin/io/getstream/video/android/core/StreamVideoClient.kt
+++ b/stream-video-android-core/src/main/kotlin/io/getstream/video/android/core/StreamVideoClient.kt
@@ -1165,6 +1165,14 @@ internal class StreamVideoClient internal constructor(
     /**
      * @see StreamVideo.logOut
      */
+    @Deprecated(
+        message = "Kept for source compatibility; see StreamVideo.logOut for migration guidance.",
+        replaceWith = ReplaceWith(
+            expression = "StreamVideo.removeClient()",
+            imports = ["io.getstream.video.android.core.StreamVideo"],
+        ),
+        level = DeprecationLevel.WARNING,
+    )
     override fun logOut() {
         scope.launch(
             CoroutineName("logOut"),