From 9ab5006eb8c9945c68959efcd1722da2a2b522db Mon Sep 17 00:00:00 2001
From: Fabrizio Demaria <fabrizio.f.demaria@gmail.com>
Date: Mon, 15 Jan 2024 17:51:32 +0100
Subject: [PATCH] docs: Update Events docs and signature (#90)

Signed-off-by: Fabrizio Demaria <fdema@spotify.com>
Signed-off-by: Fabrizio Demaria <fabrizio.f.demaria@gmail.com>
Co-authored-by: Nicklas Lundin <nicklasl@spotify.com>
---
 README.md                                     | 40 +++++++++++++++----
 .../dev/openfeature/sdk/async/Extensions.kt   |  4 +-
 .../sdk/DeveloperExperienceTests.kt           |  5 ++-
 3 files changed, 37 insertions(+), 12 deletions(-)

diff --git a/README.md b/README.md
index 81fb4d2..6e4f558 100644
--- a/README.md
+++ b/README.md
@@ -55,12 +55,12 @@ dependencies {
 ### Usage
 
 ```kotlin
-// configure a provider and get client
 coroutineScope.launch(Dispatchers.IO) {
+  // configure a provider, wait for it to complete its initialization tasks
   OpenFeatureAPI.setProviderAndWait(customProvider)
   val client = OpenFeatureAPI.getClient()
 
-// get a bool flag value
+  // get a bool flag value
   client.getBooleanValue("boolFlag", default = false)
 }
 ```
@@ -74,7 +74,7 @@ coroutineScope.launch(Dispatchers.IO) {
 | ✅      | [Hooks](#hooks)                 | Add functionality to various stages of the flag evaluation life-cycle.                                                             |
 | ❌      | Logging                         | Integrate with popular logging packages.                                                                                           |
 | ❌      | Named clients                   | Utilize multiple providers in a single application.                                                                                |
-| ⚠️      | [Eventing](#eventing)           | React to state changes in the provider or flag management system.                                                                  |
+| ✅️      | [Eventing](#eventing)           | React to state changes in the provider or flag management system.                                                                  |
 | ✅      | [Shutdown](#shutdown)           | Gracefully clean up a provider during application shutdown.                                                                        |
 | ⚠️      | [Extending](#extending)         | Extend OpenFeature with custom providers and hooks.                                                                                |
 
@@ -89,9 +89,11 @@ If the provider you're looking for hasn't been created yet, see the [develop a p
 Once you've added a provider as a dependency, it can be registered with OpenFeature like this:
 
 ```kotlin
-OpenFeatureAPI.setProvider(MyProvider())
+OpenFeatureAPI.setProviderAndWait(MyProvider())
 ```
 
+_(Asynchronous API that doesn't wait is also available)_
+
 
 ### Targeting
 
@@ -137,13 +139,28 @@ Some providers support additional events, such as `PROVIDER_CONFIGURATION_CHANGE
 
 Please refer to the documentation of the provider you're using to see what events are supported.
 
+Example usage:
 ```kotlin
-OpenFeatureAPI.observeEvents<OpenFeatureEvents.ProviderReady>()
-    ?.collect {
-        // do something once the provider is ready
-    }
+viewModelScope.launch {
+  OpenFeatureAPI.observe<OpenFeatureEvents.ProviderReady>().collect {
+    println(">> ProviderReady event received")
+  }
+}
+
+viewModelScope.launch {
+  OpenFeatureAPI.setProviderAndWait(
+    ConfidenceFeatureProvider.create(
+      applicationContext,
+      clientSecret
+    ),
+    Dispatchers.IO,
+    myEvaluationContext
+  )
+}
 ```
 
+<!-- (It's only possible to observe events from the global `OpenFeatureAPI`, until multiple providers are supported) -->
+
 ### Shutdown
 
 The OpenFeature API provides a close function to perform a cleanup of the registered provider.
@@ -210,6 +227,13 @@ class NewProvider(override val hooks: List<Hook<*>>, override val metadata: Meta
         // add necessary changes on context change
     }
 
+    override fun observe(): Flow<OpenFeatureEvents> {
+        // return a `Flow` of the Events
+    }
+
+    override fun getProviderStatus(): OpenFeatureEvents {
+        // return the event representative of the current Provider Status
+    }
 }
 ```
 
diff --git a/android/src/main/java/dev/openfeature/sdk/async/Extensions.kt b/android/src/main/java/dev/openfeature/sdk/async/Extensions.kt
index e36d711..39b96e5 100644
--- a/android/src/main/java/dev/openfeature/sdk/async/Extensions.kt
+++ b/android/src/main/java/dev/openfeature/sdk/async/Extensions.kt
@@ -48,9 +48,9 @@ internal fun FeatureProvider.observeProviderReady() = observe<OpenFeatureEvents.
 Observe events from currently configured Provider.
  */
 @OptIn(ExperimentalCoroutinesApi::class)
-fun OpenFeatureAPI.observeEvents(): Flow<OpenFeatureEvents> {
+internal inline fun <reified T : OpenFeatureEvents> OpenFeatureAPI.observe(): Flow<T> {
     return sharedProvidersFlow.flatMapLatest { provider ->
-        provider.observe()
+        provider.observe<T>()
     }
 }
 
diff --git a/android/src/test/java/dev/openfeature/sdk/DeveloperExperienceTests.kt b/android/src/test/java/dev/openfeature/sdk/DeveloperExperienceTests.kt
index 862f258..5acd88a 100644
--- a/android/src/test/java/dev/openfeature/sdk/DeveloperExperienceTests.kt
+++ b/android/src/test/java/dev/openfeature/sdk/DeveloperExperienceTests.kt
@@ -1,7 +1,8 @@
 package dev.openfeature.sdk
 
-import dev.openfeature.sdk.async.observeEvents
+import dev.openfeature.sdk.async.observe
 import dev.openfeature.sdk.async.setProviderAndWait
+import dev.openfeature.sdk.events.OpenFeatureEvents
 import dev.openfeature.sdk.exceptions.ErrorCode
 import dev.openfeature.sdk.helpers.AlwaysBrokenProvider
 import dev.openfeature.sdk.helpers.DoSomethingProvider
@@ -95,7 +96,7 @@ class DeveloperExperienceTests {
         val dispatcher = StandardTestDispatcher(testScheduler)
         var eventCount = 0
         CoroutineScope(dispatcher).launch {
-            OpenFeatureAPI.observeEvents().collect {
+            OpenFeatureAPI.observe<OpenFeatureEvents.ProviderReady>().collect {
                 eventCount++
             }
         }