refactor: rename attach() to registerCallbacks(), deliver pending results on onResume, and make LogoutBuilder.startInternal private

Author: utkrishtsahu

EXAMPLES.md

@@ -327,17 +327,17 @@ WebAuthProvider.logout(account)
 
 ## Handling Configuration Changes During Authentication
 
-When the Activity is destroyed during authentication due to a configuration change (e.g. device rotation, locale change, dark mode toggle), the SDK caches the authentication result internally. Call `WebAuthProvider.attach()` in your `onResume()` to recover it. This single call handles both recovery scenarios:
+When the Activity is destroyed during authentication due to a configuration change (e.g. device rotation, locale change, dark mode toggle), the SDK caches the authentication result internally. Call `WebAuthProvider.registerCallbacks()` once in your `onCreate()` to recover it. This single call handles both recovery scenarios:
 
-- **Configuration change**: delivers any cached result immediately to the callback
+- **Configuration change**: delivers any cached result on the next `onResume` to the callback
 - **Process death**: registers `loginCallback` as a listener and auto-removes it when the Activity is destroyed
 
 ```kotlin
 class LoginActivity : AppCompatActivity() {
 
-    override fun onResume() {
-        super.onResume()
-        WebAuthProvider.attach(
+    override fun onCreate(savedInstanceState: Bundle?) {
+        super.onCreate(savedInstanceState)
+        WebAuthProvider.registerCallbacks(
             lifecycleOwner = this,
             loginCallback = object : Callback<Credentials, AuthenticationException> {
                 override fun onSuccess(result: Credentials) {
@@ -373,7 +373,7 @@ class LoginActivity : AppCompatActivity() {
 ```
 
 > [!NOTE]
-> If you use the `suspend fun await()` API from a ViewModel coroutine scope, the Activity is never captured in the callback chain, so you do not need `attach()` calls.
+> If you use the `suspend fun await()` API from a ViewModel coroutine scope, the Activity is never captured in the callback chain, so you do not need `registerCallbacks()` calls.
 
 ## Authentication API
 

V4_MIGRATION_GUIDE.md

@@ -308,15 +308,15 @@ the reference to the callback is immediately nulled out so the destroyed Activit
 in memory.
 
 If the authentication result arrives while the Activity is being recreated, it is cached internally.
-Use `WebAuthProvider.attach()` in your `onResume()` to recover it — this single call handles both
+Call `WebAuthProvider.registerCallbacks()` once in your `onCreate()` — this single call handles both
 recovery scenarios and manages the callback lifecycle automatically:
 
 ```kotlin
 class LoginActivity : AppCompatActivity() {
 
-    override fun onResume() {
-        super.onResume()
-        WebAuthProvider.attach(
+    override fun onCreate(savedInstanceState: Bundle?) {
+        super.onCreate(savedInstanceState)
+        WebAuthProvider.registerCallbacks(
             lifecycleOwner = this,
             loginCallback = object : Callback<Credentials, AuthenticationException> {
                 override fun onSuccess(result: Credentials) { /* handle credentials */ }
@@ -337,17 +337,17 @@ class LoginActivity : AppCompatActivity() {
 }
 ```
 
-`attach()` covers both scenarios in one call:
+`registerCallbacks()` covers both scenarios in one call:
 
 | Scenario | How it's handled |
 |----------|-----------------|
-| **Configuration change** (rotation, locale, dark mode) | Any result cached while the Activity was recreating is delivered immediately to the callback |
+| **Configuration change** (rotation, locale, dark mode) | Any result cached while the Activity was recreating is delivered on the next `onResume` |
 | **Process death** (system killed the app while browser was open) | `loginCallback` is registered as a listener and auto-removed when `lifecycleOwner` is destroyed — no manual `addCallback`/`removeCallback` calls needed |
 
 > **Note:** `logoutCallback` is optional — pass it only if your screen initiates logout flows.
 
 > **Note:** If you use the `suspend fun await()` API from a ViewModel coroutine scope, the
-> Activity is never captured in the callback chain, so you do not need `attach()` calls.
+> Activity is never captured in the callback chain, so you do not need `registerCallbacks()` calls.
 > See the sample app for a ViewModel-based example.
 
 ## Getting Help

auth0/src/main/java/com/auth0/android/provider/WebAuthProvider.kt

@@ -55,21 +55,21 @@ public object WebAuthProvider {
     internal val pendingLogoutResult = AtomicReference<PendingResult<Void?>?>(null)
 
     /**
-     * Attaches login (and optionally logout) callbacks for the duration of the given
-     * [lifecycleOwner]'s lifetime. Call this once in `onResume()` — it covers both recovery
+     * Registers login (and optionally logout) callbacks for the duration of the given
+     * [lifecycleOwner]'s lifetime. Call this once in `onCreate()` — it covers both recovery
      * scenarios automatically:
      *
-     * - **Configuration change** (rotation, locale, dark mode): if a login or logout result
-     *   arrived while the Activity was being recreated, it is delivered immediately.
-     * - **Process death**: [loginCallback] is registered as a listener so that if the process
+     * - **Process death**: [loginCallback] is registered immediately so that if the process
      *   was killed while the browser was open, the result is delivered when the Activity is
      *   restored. The callback is automatically unregistered when [lifecycleOwner] is destroyed,
      *   so there is no need to call [removeCallback] manually.
+     * - **Configuration change** (rotation, locale, dark mode): any login or logout result
+     *   that arrived while the Activity was being recreated is delivered on the next `onResume`.
      *
      * ```kotlin
-     * override fun onResume() {
-     *     super.onResume()
-     *     WebAuthProvider.attach(this, loginCallback = callback, logoutCallback = voidCallback)
+     * override fun onCreate(savedInstanceState: Bundle?) {
+     *     super.onCreate(savedInstanceState)
+     *     WebAuthProvider.registerCallbacks(this, loginCallback = callback, logoutCallback = voidCallback)
      * }
      * ```
      *
@@ -78,52 +78,53 @@ public object WebAuthProvider {
      * @param logoutCallback receives logout results recovered after a configuration change
      */
     @JvmStatic
-    public fun attach(
+    public fun registerCallbacks(
         lifecycleOwner: LifecycleOwner,
         loginCallback: Callback<Credentials, AuthenticationException>,
         logoutCallback: Callback<Void?, AuthenticationException>? = null,
     ) {
-        // Process-death recovery: register and auto-remove on destroy
+        // Process-death recovery: register immediately so result is routed here on restore
         callbacks += loginCallback
         lifecycleOwner.lifecycle.addObserver(object : DefaultLifecycleObserver {
+            override fun onResume(owner: LifecycleOwner) {
+                // Config-change recovery: deliver any result cached while Activity was recreating
+                pendingLoginResult.getAndSet(null)?.let { pending ->
+                    when (pending) {
+                        is PendingResult.Success -> loginCallback.onSuccess(pending.result)
+                        is PendingResult.Failure -> loginCallback.onFailure(pending.error)
+                    }
+                    resetManagerInstance()
+                }
+                logoutCallback?.let { cb ->
+                    pendingLogoutResult.getAndSet(null)?.let { pending ->
+                        when (pending) {
+                            is PendingResult.Success -> cb.onSuccess(pending.result)
+                            is PendingResult.Failure -> cb.onFailure(pending.error)
+                        }
+                        resetManagerInstance()
+                    }
+                }
+            }
+
             override fun onDestroy(owner: LifecycleOwner) {
                 callbacks -= loginCallback
                 owner.lifecycle.removeObserver(this)
             }
         })
-
-        // Config-change recovery: deliver any result cached while Activity was recreating
-        pendingLoginResult.getAndSet(null)?.let { pending ->
-            when (pending) {
-                is PendingResult.Success -> loginCallback.onSuccess(pending.result)
-                is PendingResult.Failure -> loginCallback.onFailure(pending.error)
-            }
-            resetManagerInstance()
-        }
-
-        logoutCallback?.let { cb ->
-            pendingLogoutResult.getAndSet(null)?.let { pending ->
-                when (pending) {
-                    is PendingResult.Success -> cb.onSuccess(pending.result)
-                    is PendingResult.Failure -> cb.onFailure(pending.error)
-                }
-                resetManagerInstance()
-            }
-        }
     }
 
     @Deprecated(
-        message = "Use attach() instead — it registers the callback and auto-removes it when the lifecycle owner is destroyed.",
-        replaceWith = ReplaceWith("attach(lifecycleOwner, loginCallback = callback)")
+        message = "Use registerCallbacks() instead — it registers the callback and auto-removes it when the lifecycle owner is destroyed.",
+        replaceWith = ReplaceWith("registerCallbacks(lifecycleOwner, loginCallback = callback)")
     )
     @JvmStatic
     public fun addCallback(callback: Callback<Credentials, AuthenticationException>) {
         callbacks += callback
     }
 
     @Deprecated(
-        message = "Use attach() instead — it auto-removes the callback when the lifecycle owner is destroyed.",
-        replaceWith = ReplaceWith("attach(lifecycleOwner, loginCallback = callback)")
+        message = "Use registerCallbacks() instead — it auto-removes the callback when the lifecycle owner is destroyed.",
+        replaceWith = ReplaceWith("registerCallbacks(lifecycleOwner, loginCallback = callback)")
     )
     @JvmStatic
     public fun removeCallback(callback: Callback<Credentials, AuthenticationException>) {
@@ -342,7 +343,7 @@ public object WebAuthProvider {
             startInternal(context, effectiveCallback)
         }
 
-        internal fun startInternal(context: Context, callback: Callback<Void?, AuthenticationException>) {
+        private fun startInternal(context: Context, callback: Callback<Void?, AuthenticationException>) {
             resetManagerInstance()
             if (!ctOptions.hasCompatibleBrowser(context.packageManager)) {
                 val ex = AuthenticationException(

auth0/src/test/java/com/auth0/android/provider/WebAuthProviderTest.kt

@@ -3300,84 +3300,101 @@ public class WebAuthProviderTest {
 
 
     @Test
-    public fun shouldDeliverPendingLoginResultOnAttach() {
+    public fun shouldDeliverPendingLoginResultOnResume() {
         val credentials = Mockito.mock(Credentials::class.java)
         WebAuthProvider.pendingLoginResult.set(WebAuthProvider.PendingResult.Success(credentials))
 
         val lifecycleOwner = Mockito.mock(LifecycleOwner::class.java)
         val lifecycle = Mockito.mock(Lifecycle::class.java)
         Mockito.`when`(lifecycleOwner.lifecycle).thenReturn(lifecycle)
 
-        WebAuthProvider.attach(lifecycleOwner, loginCallback = callback)
+        val observerCaptor = argumentCaptor<DefaultLifecycleObserver>()
+        WebAuthProvider.registerCallbacks(lifecycleOwner, loginCallback = callback)
+        verify(lifecycle).addObserver(observerCaptor.capture())
+
+        // Pending result is delivered on onResume, not immediately
+        verify(callback, Mockito.never()).onSuccess(any())
+        observerCaptor.firstValue.onResume(lifecycleOwner)
 
         verify(callback).onSuccess(credentials)
         Assert.assertNull(WebAuthProvider.pendingLoginResult.get())
     }
 
     @Test
-    public fun shouldDeliverPendingLoginFailureOnAttach() {
+    public fun shouldDeliverPendingLoginFailureOnResume() {
         val error = AuthenticationException("canceled", "User canceled")
         WebAuthProvider.pendingLoginResult.set(WebAuthProvider.PendingResult.Failure(error))
 
         val lifecycleOwner = Mockito.mock(LifecycleOwner::class.java)
         val lifecycle = Mockito.mock(Lifecycle::class.java)
         Mockito.`when`(lifecycleOwner.lifecycle).thenReturn(lifecycle)
 
-        WebAuthProvider.attach(lifecycleOwner, loginCallback = callback)
+        val observerCaptor = argumentCaptor<DefaultLifecycleObserver>()
+        WebAuthProvider.registerCallbacks(lifecycleOwner, loginCallback = callback)
+        verify(lifecycle).addObserver(observerCaptor.capture())
+
+        observerCaptor.firstValue.onResume(lifecycleOwner)
 
         verify(callback).onFailure(error)
         Assert.assertNull(WebAuthProvider.pendingLoginResult.get())
     }
 
     @Test
-    public fun shouldDeliverPendingLogoutResultOnAttach() {
+    public fun shouldDeliverPendingLogoutResultOnResume() {
         WebAuthProvider.pendingLogoutResult.set(WebAuthProvider.PendingResult.Success(null))
 
         val lifecycleOwner = Mockito.mock(LifecycleOwner::class.java)
         val lifecycle = Mockito.mock(Lifecycle::class.java)
         Mockito.`when`(lifecycleOwner.lifecycle).thenReturn(lifecycle)
 
-        WebAuthProvider.attach(lifecycleOwner, loginCallback = callback, logoutCallback = voidCallback)
+        val observerCaptor = argumentCaptor<DefaultLifecycleObserver>()
+        WebAuthProvider.registerCallbacks(lifecycleOwner, loginCallback = callback, logoutCallback = voidCallback)
+        verify(lifecycle).addObserver(observerCaptor.capture())
+
+        observerCaptor.firstValue.onResume(lifecycleOwner)
 
         verify(voidCallback).onSuccess(null)
         Assert.assertNull(WebAuthProvider.pendingLogoutResult.get())
     }
 
     @Test
-    public fun shouldDeliverPendingLogoutFailureOnAttach() {
+    public fun shouldDeliverPendingLogoutFailureOnResume() {
         val error = AuthenticationException("canceled", "User closed the browser")
         WebAuthProvider.pendingLogoutResult.set(WebAuthProvider.PendingResult.Failure(error))
 
         val lifecycleOwner = Mockito.mock(LifecycleOwner::class.java)
         val lifecycle = Mockito.mock(Lifecycle::class.java)
         Mockito.`when`(lifecycleOwner.lifecycle).thenReturn(lifecycle)
 
-        WebAuthProvider.attach(lifecycleOwner, loginCallback = callback, logoutCallback = voidCallback)
+        val observerCaptor = argumentCaptor<DefaultLifecycleObserver>()
+        WebAuthProvider.registerCallbacks(lifecycleOwner, loginCallback = callback, logoutCallback = voidCallback)
+        verify(lifecycle).addObserver(observerCaptor.capture())
+
+        observerCaptor.firstValue.onResume(lifecycleOwner)
 
         verify(voidCallback).onFailure(error)
         Assert.assertNull(WebAuthProvider.pendingLogoutResult.get())
     }
 
     @Test
-    public fun shouldRegisterLoginCallbackForProcessDeathOnAttach() {
+    public fun shouldRegisterLoginCallbackForProcessDeathOnRegisterCallbacks() {
         val lifecycleOwner = Mockito.mock(LifecycleOwner::class.java)
         val lifecycle = Mockito.mock(Lifecycle::class.java)
         Mockito.`when`(lifecycleOwner.lifecycle).thenReturn(lifecycle)
 
-        WebAuthProvider.attach(lifecycleOwner, loginCallback = callback)
+        WebAuthProvider.registerCallbacks(lifecycleOwner, loginCallback = callback)
 
         Assert.assertTrue(WebAuthProvider.callbacks.contains(callback))
     }
 
     @Test
-    public fun shouldAutoRemoveLoginCallbackOnDestroyAfterAttach() {
+    public fun shouldAutoRemoveLoginCallbackOnDestroyAfterRegisterCallbacks() {
         val lifecycleOwner = Mockito.mock(LifecycleOwner::class.java)
         val lifecycle = Mockito.mock(Lifecycle::class.java)
         Mockito.`when`(lifecycleOwner.lifecycle).thenReturn(lifecycle)
 
-        // Capture the observer registered by attach()
         val observerCaptor = argumentCaptor<DefaultLifecycleObserver>()
-        WebAuthProvider.attach(lifecycleOwner, loginCallback = callback)
+        WebAuthProvider.registerCallbacks(lifecycleOwner, loginCallback = callback)
         verify(lifecycle).addObserver(observerCaptor.capture())
 
         Assert.assertTrue(WebAuthProvider.callbacks.contains(callback))
@@ -3389,15 +3406,19 @@ public class WebAuthProviderTest {
     }
 
     @Test
-    public fun shouldNotDeliverLogoutResultWhenNoLogoutCallbackPassedToAttach() {
+    public fun shouldNotDeliverLogoutResultWhenNoLogoutCallbackPassedToRegisterCallbacks() {
         WebAuthProvider.pendingLogoutResult.set(WebAuthProvider.PendingResult.Success(null))
 
         val lifecycleOwner = Mockito.mock(LifecycleOwner::class.java)
         val lifecycle = Mockito.mock(Lifecycle::class.java)
         Mockito.`when`(lifecycleOwner.lifecycle).thenReturn(lifecycle)
 
-        // attach without logoutCallback — pending logout result should stay untouched
-        WebAuthProvider.attach(lifecycleOwner, loginCallback = callback)
+        val observerCaptor = argumentCaptor<DefaultLifecycleObserver>()
+        WebAuthProvider.registerCallbacks(lifecycleOwner, loginCallback = callback)
+        verify(lifecycle).addObserver(observerCaptor.capture())
+
+        // registerCallbacks without logoutCallback — pending logout result should stay untouched
+        observerCaptor.firstValue.onResume(lifecycleOwner)
 
         verify(voidCallback, Mockito.never()).onSuccess(any())
         Assert.assertNotNull(WebAuthProvider.pendingLogoutResult.get())