fix: always invoke reloadFeatureFlags callback

.changeset/reload-flags-callback-contract.md

@@ -0,0 +1,5 @@
+---
+"posthog": patch
+---
+
+`reloadFeatureFlags` now always invokes its completion callback, including when the SDK is disabled/opted-out or the distinct ID is blank. Previously these early-returns skipped the callback, which could leave callers that await it (e.g. the Flutter SDK's `reloadFeatureFlags`) hanging indefinitely.

posthog/src/main/java/com/posthog/PostHog.kt

@@ -1249,8 +1249,19 @@ public class PostHog private constructor(
         }
     }
 
+    // Invokes the feature flags callback, swallowing exceptions like runOnFeatureFlagsCallbacks.
+    private fun notifyFeatureFlagsCallback(onFeatureFlags: PostHogOnFeatureFlags?) {
+        try {
+            onFeatureFlags?.loaded()
+        } catch (e: Throwable) {
+            config?.logger?.log("Executing the feature flags callback failed: $e")
+        }
+    }
+
     public override fun reloadFeatureFlags(onFeatureFlags: PostHogOnFeatureFlags?) {
         if (!isEnabled()) {
+            // Still invoke the callback so awaiting callers aren't left hanging.
+            notifyFeatureFlagsCallback(onFeatureFlags)
             return
         }
         loadFeatureFlagsRequest(
@@ -1275,6 +1286,8 @@ public class PostHog private constructor(
 
         if (distinctId.isBlank()) {
             config?.logger?.log("Feature flags not loaded, distinctId is invalid: $distinctId")
+            // Still invoke the callback so awaiting callers aren't left hanging.
+            notifyFeatureFlagsCallback(onFeatureFlags)
             return
         }
 

posthog/src/test/java/com/posthog/PostHogFeatureFlagsTest.kt

@@ -14,6 +14,7 @@ import kotlin.test.AfterTest
 import kotlin.test.Test
 import kotlin.test.assertEquals
 import kotlin.test.assertNotEquals
+import kotlin.test.assertTrue
 
 internal class PostHogFeatureFlagsTest {
     @get:Rule
@@ -374,4 +375,19 @@ internal class PostHogFeatureFlagsTest {
         assertEquals("nonExistentFlag", theEvent.properties!!["\$feature_flag"])
         sut.close()
     }
+
+    @Test
+    fun `reloadFeatureFlags invokes callback when not enabled`() {
+        val http = mockHttp()
+        val url = http.url("/")
+        val sut = getSut(url.toString(), preloadFeatureFlags = false)
+        sut.close()
+
+        var called = false
+        sut.reloadFeatureFlags { called = true }
+
+        // isEnabled() is false after close(), so reloadFeatureFlags early-returns. The
+        // callback must still fire (synchronously) rather than leave awaiting callers hanging.
+        assertTrue(called)
+    }
 }