feat!: Remove deprecated ProviderNotReady event (#239)

Signed-off-by: Max Pinheiro <max.pinheiro@fluxon.com>

Author: maxnrp

docs/multiprovider/README.md

@@ -3,13 +3,15 @@
 Combine multiple `FeatureProvider`s into a single provider with deterministic ordering, pluggable evaluation strategies, and unified status/event handling.
 
 ### Why use MultiProvider?
+
 - **Layer providers**: fall back from an in-memory or experiment provider to a remote provider.
 - **Migrate safely**: put the new provider first, retain the old as fallback.
 - **Handle errors predictably**: choose whether errors should short-circuit or be skipped.
 
 This implementation is adapted for Kotlin coroutines, flows, and OpenFeature error types.
 
 ### Quick start
+
 ```kotlin
 import dev.openfeature.kotlin.sdk.OpenFeatureAPI
 import dev.openfeature.kotlin.sdk.multiprovider.MultiProvider
@@ -35,6 +37,7 @@ val enabled = client.getBooleanValue("new-ui", defaultValue = false)
 ```
 
 ### How it works (at a glance)
+
 - The `MultiProvider` delegates each evaluation to its child providers in the order you supply.
 - A pluggable `Strategy` decides which child result to return.
 - Provider events are observed and converted into a single aggregate SDK status.
@@ -46,21 +49,23 @@ val enabled = client.getBooleanValue("new-ui", defaultValue = false)
   - Returns the first child result that is not "flag not found".
   - If a child returns an error other than `FLAG_NOT_FOUND`, that error is returned immediately.
   - If all children report `FLAG_NOT_FOUND`, the default value is returned with reason `DEFAULT`.
-
 - **FirstSuccessfulStrategy**
   - Skips over errors from children and continues to the next provider.
   - Returns the first successful evaluation (no error code).
   - If no provider succeeds, the default value is returned with `FLAG_NOT_FOUND`.
 
 Pick the strategy that best matches your failure-policy:
+
 - Prefer early, explicit error surfacing: use `FirstMatchStrategy`.
 - Prefer resilience and best-effort success: use `FirstSuccessfulStrategy`.
 
 ### Evaluation order matters
+
 Children are evaluated in the order provided. Put the most authoritative or fastest provider first. For example, place a small in-memory override provider before a remote provider to reduce latency.
 
 ### Events and status aggregation
-`MultiProvider` listens to child provider events and emits a single, aggregate status via `OpenFeatureAPI.statusFlow`. The highest-precedence status among children wins:
+
+`MultiProvider` listens to child provider events and emits a single, aggregate status via `OpenFeatureAPI.statusFlow`. Per the OpenFeature specification: a child stays `NOT_READY` until it emits `PROVIDER_READY`, `PROVIDER_ERROR`, or `PROVIDER_STALE` (or only `PROVIDER_CONFIGURATION_CHANGED`, which does not change readiness). The highest-precedence status among children wins:
 
 1. Fatal
 2. NotReady
@@ -71,27 +76,34 @@ Children are evaluated in the order provided. Put the most authoritative or fast
 `ProviderConfigurationChanged` is re-emitted as-is. When the aggregate status changes due to a child event, the original triggering event is also emitted.
 
 ### Context propagation
+
 When the evaluation context changes, `MultiProvider` calls `onContextSet` on all child providers concurrently. Aggregate status transitions to Reconciling and then back to Ready (or Error) in line with SDK behavior.
 
 ### Provider metadata
+
 `MultiProvider.metadata` exposes:
+
 - `name = "multiprovider"`
 - `originalMetadata`: a map of child-name → child `ProviderMetadata`
 
 Child names are derived from each provider’s `metadata.name`. If duplicates occur, stable suffixes are applied (e.g., `myProvider_1`, `myProvider_2`).
 
 Example: inspect provider metadata
+
 ```kotlin
 val meta = OpenFeatureAPI.getProviderMetadata()
 println(meta?.name) // "multiprovider"
 println(meta?.originalMetadata) // map of child names to their metadata
 ```
 
 ### Shutdown behavior
+
 `shutdown()` is invoked on all children. If any child fails to shut down, an aggregated error is thrown that includes all individual failures. Resources should be released in child providers even if peers fail.
 
 ### Custom strategies
+
 You can provide your own composition policy by implementing `MultiProvider.Strategy`:
+
 ```kotlin
 import dev.openfeature.kotlin.sdk.*
 import dev.openfeature.kotlin.sdk.multiprovider.MultiProvider
@@ -119,8 +131,7 @@ val multi = MultiProvider(listOf(experiments, remote), strategy = MyStrategy())
 ```
 
 ### Notes and limitations
+
 - Hooks on `MultiProvider` are currently not applied.
 - Ensure each child’s `metadata.name` is set for clearer diagnostics in `originalMetadata`.
 
-
-

kotlin-sdk/api/android/kotlin-sdk.api

@@ -719,28 +719,17 @@ public final class dev/openfeature/kotlin/sdk/events/OpenFeatureProviderEvents$P
 
 public final class dev/openfeature/kotlin/sdk/events/OpenFeatureProviderEvents$ProviderError : dev/openfeature/kotlin/sdk/events/OpenFeatureProviderEvents {
 	public fun <init> ()V
-	public fun <init> (Ldev/openfeature/kotlin/sdk/events/OpenFeatureProviderEvents$EventDetails;Ldev/openfeature/kotlin/sdk/exceptions/OpenFeatureError;)V
-	public synthetic fun <init> (Ldev/openfeature/kotlin/sdk/events/OpenFeatureProviderEvents$EventDetails;Ldev/openfeature/kotlin/sdk/exceptions/OpenFeatureError;ILkotlin/jvm/internal/DefaultConstructorMarker;)V
+	public fun <init> (Ldev/openfeature/kotlin/sdk/events/OpenFeatureProviderEvents$EventDetails;)V
+	public synthetic fun <init> (Ldev/openfeature/kotlin/sdk/events/OpenFeatureProviderEvents$EventDetails;ILkotlin/jvm/internal/DefaultConstructorMarker;)V
 	public final fun component1 ()Ldev/openfeature/kotlin/sdk/events/OpenFeatureProviderEvents$EventDetails;
-	public final fun component2 ()Ldev/openfeature/kotlin/sdk/exceptions/OpenFeatureError;
-	public final fun copy (Ldev/openfeature/kotlin/sdk/events/OpenFeatureProviderEvents$EventDetails;Ldev/openfeature/kotlin/sdk/exceptions/OpenFeatureError;)Ldev/openfeature/kotlin/sdk/events/OpenFeatureProviderEvents$ProviderError;
-	public static synthetic fun copy$default (Ldev/openfeature/kotlin/sdk/events/OpenFeatureProviderEvents$ProviderError;Ldev/openfeature/kotlin/sdk/events/OpenFeatureProviderEvents$EventDetails;Ldev/openfeature/kotlin/sdk/exceptions/OpenFeatureError;ILjava/lang/Object;)Ldev/openfeature/kotlin/sdk/events/OpenFeatureProviderEvents$ProviderError;
+	public final fun copy (Ldev/openfeature/kotlin/sdk/events/OpenFeatureProviderEvents$EventDetails;)Ldev/openfeature/kotlin/sdk/events/OpenFeatureProviderEvents$ProviderError;
+	public static synthetic fun copy$default (Ldev/openfeature/kotlin/sdk/events/OpenFeatureProviderEvents$ProviderError;Ldev/openfeature/kotlin/sdk/events/OpenFeatureProviderEvents$EventDetails;ILjava/lang/Object;)Ldev/openfeature/kotlin/sdk/events/OpenFeatureProviderEvents$ProviderError;
 	public fun equals (Ljava/lang/Object;)Z
-	public final fun getError ()Ldev/openfeature/kotlin/sdk/exceptions/OpenFeatureError;
 	public fun getEventDetails ()Ldev/openfeature/kotlin/sdk/events/OpenFeatureProviderEvents$EventDetails;
 	public fun hashCode ()I
 	public fun toString ()Ljava/lang/String;
 }
 
-public final class dev/openfeature/kotlin/sdk/events/OpenFeatureProviderEvents$ProviderNotReady : dev/openfeature/kotlin/sdk/events/OpenFeatureProviderEvents {
-	public static final field INSTANCE Ldev/openfeature/kotlin/sdk/events/OpenFeatureProviderEvents$ProviderNotReady;
-	public fun equals (Ljava/lang/Object;)Z
-	public synthetic fun getEventDetails ()Ldev/openfeature/kotlin/sdk/events/OpenFeatureProviderEvents$EventDetails;
-	public fun getEventDetails ()Ljava/lang/Void;
-	public fun hashCode ()I
-	public fun toString ()Ljava/lang/String;
-}
-
 public final class dev/openfeature/kotlin/sdk/events/OpenFeatureProviderEvents$ProviderReady : dev/openfeature/kotlin/sdk/events/OpenFeatureProviderEvents {
 	public fun <init> ()V
 	public fun <init> (Ldev/openfeature/kotlin/sdk/events/OpenFeatureProviderEvents$EventDetails;)V

kotlin-sdk/api/jvm/kotlin-sdk.api

@@ -719,28 +719,17 @@ public final class dev/openfeature/kotlin/sdk/events/OpenFeatureProviderEvents$P
 
 public final class dev/openfeature/kotlin/sdk/events/OpenFeatureProviderEvents$ProviderError : dev/openfeature/kotlin/sdk/events/OpenFeatureProviderEvents {
 	public fun <init> ()V
-	public fun <init> (Ldev/openfeature/kotlin/sdk/events/OpenFeatureProviderEvents$EventDetails;Ldev/openfeature/kotlin/sdk/exceptions/OpenFeatureError;)V
-	public synthetic fun <init> (Ldev/openfeature/kotlin/sdk/events/OpenFeatureProviderEvents$EventDetails;Ldev/openfeature/kotlin/sdk/exceptions/OpenFeatureError;ILkotlin/jvm/internal/DefaultConstructorMarker;)V
+	public fun <init> (Ldev/openfeature/kotlin/sdk/events/OpenFeatureProviderEvents$EventDetails;)V
+	public synthetic fun <init> (Ldev/openfeature/kotlin/sdk/events/OpenFeatureProviderEvents$EventDetails;ILkotlin/jvm/internal/DefaultConstructorMarker;)V
 	public final fun component1 ()Ldev/openfeature/kotlin/sdk/events/OpenFeatureProviderEvents$EventDetails;
-	public final fun component2 ()Ldev/openfeature/kotlin/sdk/exceptions/OpenFeatureError;
-	public final fun copy (Ldev/openfeature/kotlin/sdk/events/OpenFeatureProviderEvents$EventDetails;Ldev/openfeature/kotlin/sdk/exceptions/OpenFeatureError;)Ldev/openfeature/kotlin/sdk/events/OpenFeatureProviderEvents$ProviderError;
-	public static synthetic fun copy$default (Ldev/openfeature/kotlin/sdk/events/OpenFeatureProviderEvents$ProviderError;Ldev/openfeature/kotlin/sdk/events/OpenFeatureProviderEvents$EventDetails;Ldev/openfeature/kotlin/sdk/exceptions/OpenFeatureError;ILjava/lang/Object;)Ldev/openfeature/kotlin/sdk/events/OpenFeatureProviderEvents$ProviderError;
+	public final fun copy (Ldev/openfeature/kotlin/sdk/events/OpenFeatureProviderEvents$EventDetails;)Ldev/openfeature/kotlin/sdk/events/OpenFeatureProviderEvents$ProviderError;
+	public static synthetic fun copy$default (Ldev/openfeature/kotlin/sdk/events/OpenFeatureProviderEvents$ProviderError;Ldev/openfeature/kotlin/sdk/events/OpenFeatureProviderEvents$EventDetails;ILjava/lang/Object;)Ldev/openfeature/kotlin/sdk/events/OpenFeatureProviderEvents$ProviderError;
 	public fun equals (Ljava/lang/Object;)Z
-	public final fun getError ()Ldev/openfeature/kotlin/sdk/exceptions/OpenFeatureError;
 	public fun getEventDetails ()Ldev/openfeature/kotlin/sdk/events/OpenFeatureProviderEvents$EventDetails;
 	public fun hashCode ()I
 	public fun toString ()Ljava/lang/String;
 }
 
-public final class dev/openfeature/kotlin/sdk/events/OpenFeatureProviderEvents$ProviderNotReady : dev/openfeature/kotlin/sdk/events/OpenFeatureProviderEvents {
-	public static final field INSTANCE Ldev/openfeature/kotlin/sdk/events/OpenFeatureProviderEvents$ProviderNotReady;
-	public fun equals (Ljava/lang/Object;)Z
-	public synthetic fun getEventDetails ()Ldev/openfeature/kotlin/sdk/events/OpenFeatureProviderEvents$EventDetails;
-	public fun getEventDetails ()Ljava/lang/Void;
-	public fun hashCode ()I
-	public fun toString ()Ljava/lang/String;
-}
-
 public final class dev/openfeature/kotlin/sdk/events/OpenFeatureProviderEvents$ProviderReady : dev/openfeature/kotlin/sdk/events/OpenFeatureProviderEvents {
 	public fun <init> ()V
 	public fun <init> (Ldev/openfeature/kotlin/sdk/events/OpenFeatureProviderEvents$EventDetails;)V

kotlin-sdk/src/commonMain/kotlin/dev/openfeature/kotlin/sdk/events/OpenFeatureProviderEvents.kt

@@ -3,7 +3,6 @@ package dev.openfeature.kotlin.sdk.events
 import dev.openfeature.kotlin.sdk.OpenFeatureStatus
 import dev.openfeature.kotlin.sdk.exceptions.ErrorCode
 import dev.openfeature.kotlin.sdk.exceptions.OpenFeatureError
-import dev.openfeature.kotlin.sdk.exceptions.OpenFeatureError.ProviderFatalError
 
 sealed class OpenFeatureProviderEvents {
     data class EventDetails(
@@ -17,58 +16,48 @@ sealed class OpenFeatureProviderEvents {
 
     /**
      * The provider is ready to perform flag evaluations.
+     * [eventDetails] may supply [EventDetails.flagsChanged], [EventDetails.message], [EventDetails.errorCode], and [EventDetails.eventMetadata] as applicable.
      */
     data class ProviderReady(
         override val eventDetails: EventDetails? = null
     ) : OpenFeatureProviderEvents()
 
     /**
      * The provider signaled an error.
+     * [eventDetails] may supply [EventDetails.flagsChanged], [EventDetails.message], [EventDetails.errorCode], and [EventDetails.eventMetadata] as applicable.
      */
     data class ProviderError(
-        override val eventDetails: EventDetails? = null,
-        @Deprecated("Please use eventDetails instead.") val error: OpenFeatureError? = null
+        override val eventDetails: EventDetails? = null
     ) : OpenFeatureProviderEvents()
 
+    /**
+     * Configuration or flag definitions changed.
+     * [eventDetails] may supply [EventDetails.flagsChanged], [EventDetails.message], [EventDetails.errorCode], and [EventDetails.eventMetadata] as applicable.
+     */
     data class ProviderConfigurationChanged(
         override val eventDetails: EventDetails? = null
     ) : OpenFeatureProviderEvents()
 
     /**
      * The provider's cached state is no longer valid and may not be up-to-date with the source of truth.
+     * [eventDetails] may supply [EventDetails.flagsChanged], [EventDetails.message], [EventDetails.errorCode], and [EventDetails.eventMetadata] as applicable.
      */
     data class ProviderStale(
         override val eventDetails: EventDetails? = null
     ) : OpenFeatureProviderEvents()
-
-    @Deprecated("Use ProviderError instead", ReplaceWith("ProviderError"))
-    data object ProviderNotReady : OpenFeatureProviderEvents() {
-        override val eventDetails = null
-    }
 }
 
 internal fun OpenFeatureProviderEvents.ProviderError.toOpenFeatureStatusError(): OpenFeatureStatus {
-    return when {
-        eventDetails?.errorCode != null -> {
-            val openFeatureError = OpenFeatureError.fromMessageAndErrorCode(
-                errorMessage = eventDetails.message ?: "Provider did not supply an error message",
-                errorCode = eventDetails.errorCode
-            )
-            if (eventDetails.errorCode == ErrorCode.PROVIDER_FATAL) {
-                OpenFeatureStatus.Fatal(openFeatureError)
-            } else {
-                OpenFeatureStatus.Error(openFeatureError)
-            }
-        }
-
-        error != null -> { // Deprecated implementation
-            if (error is ProviderFatalError) {
-                OpenFeatureStatus.Fatal(error)
-            } else {
-                OpenFeatureStatus.Error(error)
-            }
-        }
-
-        else -> OpenFeatureStatus.Error(OpenFeatureError.GeneralError("Unspecified error"))
+    val code = eventDetails?.errorCode ?: return OpenFeatureStatus.Error(
+        OpenFeatureError.GeneralError(eventDetails?.message ?: "Unspecified error")
+    )
+    val openFeatureError = OpenFeatureError.fromMessageAndErrorCode(
+        errorMessage = eventDetails.message ?: "Provider did not supply an error message",
+        errorCode = code
+    )
+    return if (code == ErrorCode.PROVIDER_FATAL) {
+        OpenFeatureStatus.Fatal(openFeatureError)
+    } else {
+        OpenFeatureStatus.Error(openFeatureError)
     }
 }

kotlin-sdk/src/commonMain/kotlin/dev/openfeature/kotlin/sdk/exceptions/OpenFeatureError.kt

@@ -63,7 +63,7 @@ sealed class OpenFeatureError : Exception() {
     companion object {
         internal fun fromMessageAndErrorCode(errorMessage: String, errorCode: ErrorCode): OpenFeatureError {
             return when (errorCode) {
-                ErrorCode.PROVIDER_NOT_READY -> ProviderNotReadyError()
+                ErrorCode.PROVIDER_NOT_READY -> ProviderNotReadyError(errorMessage)
                 ErrorCode.FLAG_NOT_FOUND -> FlagNotFoundError(flagKey = null, errorMessage)
                 ErrorCode.PARSE_ERROR -> ParseError(errorMessage)
                 ErrorCode.TYPE_MISMATCH -> TypeMismatchError(errorMessage)

kotlin-sdk/src/commonMain/kotlin/dev/openfeature/kotlin/sdk/multiprovider/MultiProvider.kt

@@ -210,7 +210,6 @@ class MultiProvider(
             }
 
             is OpenFeatureProviderEvents.ProviderReady -> OpenFeatureStatus.Ready
-            is OpenFeatureProviderEvents.ProviderNotReady -> OpenFeatureStatus.NotReady
             is OpenFeatureProviderEvents.ProviderStale -> OpenFeatureStatus.Stale
             is OpenFeatureProviderEvents.ProviderError -> event.toOpenFeatureStatusError()
         }

kotlin-sdk/src/commonTest/kotlin/dev/openfeature/kotlin/sdk/EventDetailsTests.kt

@@ -41,35 +41,42 @@ class EventDetailsTests {
     }
 
     @Test
-    fun providerErrorMapToFatal() {
+    fun providerErrorEventDetailsMapToInvalidContextError() {
         val evt = OpenFeatureProviderEvents.ProviderError(
-            error = OpenFeatureError.ProviderFatalError("message")
+            OpenFeatureProviderEvents.EventDetails(
+                message = "message",
+                errorCode = ErrorCode.INVALID_CONTEXT
+            )
         )
 
         val status = evt.toOpenFeatureStatusError()
-        val fatal = assertIs<OpenFeatureStatus.Fatal>(status)
-        val err = assertIs<OpenFeatureError.ProviderFatalError>(fatal.error)
+        val errorStatus = assertIs<OpenFeatureStatus.Error>(status)
+        val err = assertIs<OpenFeatureError.InvalidContextError>(errorStatus.error)
         assertEquals("message", err.message)
     }
 
     @Test
-    fun providerErrorMapToError() {
-        val evt = OpenFeatureProviderEvents.ProviderError(
-            error = OpenFeatureError.InvalidContextError("message")
-        )
+    fun providerErrorMapToUnspecifiedError() {
+        val evt = OpenFeatureProviderEvents.ProviderError()
 
         val status = evt.toOpenFeatureStatusError()
-        val fatal = assertIs<OpenFeatureStatus.Error>(status)
-        val err = assertIs<OpenFeatureError.InvalidContextError>(fatal.error)
-        assertEquals("message", err.message)
+        val errorStatus = assertIs<OpenFeatureStatus.Error>(status)
+        val err = assertIs<OpenFeatureError.GeneralError>(errorStatus.error)
+        assertEquals("Unspecified error", err.message)
     }
 
     @Test
-    fun providerErrorMapToUnspecifiedError() {
-        val evt = OpenFeatureProviderEvents.ProviderError()
+    fun providerErrorEventDetailsWithMessageAndNullErrorCodeMapToGeneralError() {
+        val evt = OpenFeatureProviderEvents.ProviderError(
+            OpenFeatureProviderEvents.EventDetails(
+                message = "test",
+                errorCode = null
+            )
+        )
 
         val status = evt.toOpenFeatureStatusError()
-        val fatal = assertIs<OpenFeatureStatus.Error>(status)
-        assertIs<OpenFeatureError.GeneralError>(fatal.error)
+        val errorStatus = assertIs<OpenFeatureStatus.Error>(status)
+        val err = assertIs<OpenFeatureError.GeneralError>(errorStatus.error)
+        assertEquals("test", err.message)
     }
 }

kotlin-sdk/src/commonTest/kotlin/dev/openfeature/kotlin/sdk/ProviderEventingTests.kt

@@ -1,7 +1,7 @@
 package dev.openfeature.kotlin.sdk
 
 import dev.openfeature.kotlin.sdk.events.OpenFeatureProviderEvents
-import dev.openfeature.kotlin.sdk.exceptions.OpenFeatureError
+import dev.openfeature.kotlin.sdk.exceptions.ErrorCode
 import dev.openfeature.kotlin.sdk.helpers.DoSomethingProvider
 import dev.openfeature.kotlin.sdk.helpers.OverlyEmittingProvider
 import kotlinx.coroutines.ExperimentalCoroutinesApi
@@ -44,8 +44,9 @@ class ProviderEventingTests {
             ) {
                 flow.emit(
                     OpenFeatureProviderEvents.ProviderError(
-                        error = OpenFeatureError.ProviderNotReadyError(
-                            "test error"
+                        OpenFeatureProviderEvents.EventDetails(
+                            message = "test error",
+                            errorCode = ErrorCode.PROVIDER_NOT_READY
                         )
                     )
                 )

kotlin-sdk/src/commonTest/kotlin/dev/openfeature/kotlin/sdk/helpers/AutoHealingProvider.kt

@@ -7,6 +7,7 @@ import dev.openfeature.kotlin.sdk.ProviderEvaluation
 import dev.openfeature.kotlin.sdk.ProviderMetadata
 import dev.openfeature.kotlin.sdk.Value
 import dev.openfeature.kotlin.sdk.events.OpenFeatureProviderEvents
+import dev.openfeature.kotlin.sdk.exceptions.ErrorCode
 import dev.openfeature.kotlin.sdk.exceptions.OpenFeatureError
 import kotlinx.coroutines.delay
 import kotlinx.coroutines.flow.Flow
@@ -25,8 +26,9 @@ class AutoHealingProvider(
         ready = false
         _events.emit(
             OpenFeatureProviderEvents.ProviderError(
-                error = OpenFeatureError.ProviderNotReadyError(
-                    "AutoHealingProvider got an error. trying to heal"
+                OpenFeatureProviderEvents.EventDetails(
+                    message = "AutoHealingProvider got an error. trying to heal",
+                    errorCode = ErrorCode.PROVIDER_NOT_READY
                 )
             )
         )