feat: Clean up builder patterns and remove unnecessary convenience methods

Remove problematic convenience methods and enforce consistent builder usage:

- Remove EventDetails.fromProviderEventDetails() static methods
- Remove HookContext.from() static method
- Remove FlagEvaluationDetails.from() static method
- Update all usages to use .builder() pattern consistently
- Add required imports for Optional and ImmutableMetadata

Benefits:
✅ Consistent API - single builder() method per class
✅ No confusion between convenience methods and builders
✅ More explicit and discoverable API surface
✅ Better IDE autocompletion and IntelliSense
✅ Easier to maintain and understand

Breaking change: Convenience methods removed in favor of builder pattern

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <[email protected]>

Author: aepfli

openfeature-api/src/main/java/dev/openfeature/api/EventDetails.java

@@ -209,32 +209,4 @@ public EventDetails build() {
         }
     }
 
-    /**
-     * Create EventDetails from ProviderEventDetails with provider name.
-     *
-     * @param providerEventDetails the provider event details
-     * @param providerName the name of the provider
-     * @return EventDetails instance
-     */
-    public static EventDetails fromProviderEventDetails(
-            ProviderEventDetails providerEventDetails, String providerName) {
-        return fromProviderEventDetails(providerEventDetails, providerName, null);
-    }
-
-    /**
-     * Create EventDetails from ProviderEventDetails with provider name and domain.
-     *
-     * @param providerEventDetails the provider event details
-     * @param providerName the name of the provider
-     * @param domain the domain associated with the event
-     * @return EventDetails instance
-     */
-    public static EventDetails fromProviderEventDetails(
-            ProviderEventDetails providerEventDetails, String providerName, String domain) {
-        return builder()
-                .providerName(providerName)
-                .domain(domain)
-                .providerEventDetails(providerEventDetails)
-                .build();
-    }
 }

openfeature-api/src/main/java/dev/openfeature/api/FlagEvaluationDetails.java

@@ -202,24 +202,4 @@ public FlagEvaluationDetails<T> build() {
         }
     }
 
-    /**
-     * Generate detail payload from the provider response.
-     *
-     * @param providerEval provider response
-     * @param flagKey      key for the flag being evaluated
-     * @param <T>          type of flag being returned
-     * @return detail payload
-     */
-    public static <T> FlagEvaluationDetails<T> from(ProviderEvaluation<T> providerEval, String flagKey) {
-        return FlagEvaluationDetails.<T>builder()
-                .flagKey(flagKey)
-                .value(providerEval.getValue())
-                .variant(providerEval.getVariant())
-                .reason(providerEval.getReason())
-                .errorMessage(providerEval.getErrorMessage())
-                .errorCode(providerEval.getErrorCode())
-                .flagMetadata(Optional.ofNullable(providerEval.getFlagMetadata())
-                        .orElse(ImmutableMetadata.builder().build()))
-                .build();
-    }
 }

openfeature-api/src/main/java/dev/openfeature/api/HookContext.java

@@ -52,34 +52,6 @@ public static <T> Builder<T> builder() {
         return new Builder<>();
     }
 
-    /**
-     * Builds a {@link HookContext} instances from request data.
-     *
-     * @param key              feature flag key
-     * @param type             flag value type
-     * @param clientMetadata   info on which client is calling
-     * @param providerMetadata info on the provider
-     * @param ctx              Evaluation Context for the request
-     * @param defaultValue     Fallback value
-     * @param <T>              type that the flag is evaluating against
-     * @return resulting context for hook
-     */
-    public static <T> HookContext<T> from(
-            String key,
-            FlagValueType type,
-            ClientMetadata clientMetadata,
-            Metadata providerMetadata,
-            EvaluationContext ctx,
-            T defaultValue) {
-        return HookContext.<T>builder()
-                .flagKey(key)
-                .type(type)
-                .clientMetadata(clientMetadata)
-                .providerMetadata(providerMetadata)
-                .ctx(ctx)
-                .defaultValue(defaultValue)
-                .build();
-    }
 
     @Override
     public boolean equals(Object o) {

openfeature-sdk/src/main/java/dev/openfeature/sdk/DefaultOpenFeatureAPI.java

@@ -473,19 +473,30 @@ private void runHandlersForProvider(FeatureProvider provider, ProviderEvent even
                     .orElse("unknown");
 
             // run the global handlers
-            eventSupport.runGlobalHandlers(event, EventDetails.fromProviderEventDetails(details, providerName));
+            eventSupport.runGlobalHandlers(event, EventDetails.builder()
+                    .providerName(providerName)
+                    .providerEventDetails(details)
+                    .build());
 
             // run the handlers associated with domains for this provider
             domainsForProvider.forEach(domain -> eventSupport.runClientHandlers(
-                    domain, event, EventDetails.fromProviderEventDetails(details, providerName, domain)));
+                    domain, event, EventDetails.builder()
+                            .providerName(providerName)
+                            .domain(domain)
+                            .providerEventDetails(details)
+                            .build()));
 
             if (providerRepository.isDefaultProvider(provider)) {
                 // run handlers for clients that have no bound providers (since this is the default)
                 Set<String> allDomainNames = eventSupport.getAllDomainNames();
                 Set<String> boundDomains = providerRepository.getAllBoundDomains();
                 allDomainNames.removeAll(boundDomains);
                 allDomainNames.forEach(domain -> eventSupport.runClientHandlers(
-                        domain, event, EventDetails.fromProviderEventDetails(details, providerName, domain)));
+                        domain, event, EventDetails.builder()
+                                .providerName(providerName)
+                                .domain(domain)
+                                .providerEventDetails(details)
+                                .build()));
             }
         }
     }

openfeature-sdk/src/main/java/dev/openfeature/sdk/OpenFeatureClient.java

@@ -12,6 +12,7 @@
 import dev.openfeature.api.Hook;
 import dev.openfeature.api.HookContext;
 import dev.openfeature.api.ImmutableContext;
+import dev.openfeature.api.ImmutableMetadata;
 import dev.openfeature.api.ImmutableStructure;
 import dev.openfeature.api.ProviderEvaluation;
 import dev.openfeature.api.ProviderEvent;
@@ -33,6 +34,7 @@
 import java.util.List;
 import java.util.Map;
 import java.util.Objects;
+import java.util.Optional;
 import java.util.concurrent.ConcurrentLinkedQueue;
 import java.util.concurrent.atomic.AtomicReference;
 import java.util.function.Consumer;
@@ -201,18 +203,25 @@ private <T> FlagEvaluationDetails<T> evaluateFlag(
 
             var mergedCtx = hookSupport.beforeHooks(
                     type,
-                    HookContext.from(
-                            key,
-                            type,
-                            this.getMetadata(),
-                            provider.getMetadata(),
-                            mergeEvaluationContext(ctx),
-                            defaultValue),
+                    HookContext.<T>builder()
+                            .flagKey(key)
+                            .type(type)
+                            .clientMetadata(this.getMetadata())
+                            .providerMetadata(provider.getMetadata())
+                            .ctx(mergeEvaluationContext(ctx))
+                            .defaultValue(defaultValue)
+                            .build(),
                     mergedHooks,
                     hints);
 
-            afterHookContext =
-                    HookContext.from(key, type, this.getMetadata(), provider.getMetadata(), mergedCtx, defaultValue);
+            afterHookContext = HookContext.<T>builder()
+                    .flagKey(key)
+                    .type(type)
+                    .clientMetadata(this.getMetadata())
+                    .providerMetadata(provider.getMetadata())
+                    .ctx(mergedCtx)
+                    .defaultValue(defaultValue)
+                    .build();
 
             // "short circuit" if the provider is in NOT_READY or FATAL state
             if (ProviderState.NOT_READY.equals(state)) {
@@ -225,7 +234,16 @@ private <T> FlagEvaluationDetails<T> evaluateFlag(
             var providerEval =
                     (ProviderEvaluation<T>) createProviderEvaluation(type, key, defaultValue, provider, mergedCtx);
 
-            details = FlagEvaluationDetails.from(providerEval, key);
+            details = FlagEvaluationDetails.<T>builder()
+                    .flagKey(key)
+                    .value(providerEval.getValue())
+                    .variant(providerEval.getVariant())
+                    .reason(providerEval.getReason())
+                    .errorMessage(providerEval.getErrorMessage())
+                    .errorCode(providerEval.getErrorCode())
+                    .flagMetadata(Optional.ofNullable(providerEval.getFlagMetadata())
+                            .orElse(ImmutableMetadata.builder().build()))
+                    .build();
             if (details.getErrorCode() != null) {
                 var error =
                         ExceptionUtils.instantiateErrorByErrorCode(details.getErrorCode(), details.getErrorMessage());

openfeature-sdk/src/test/java/dev/openfeature/sdk/HookContextTest.java

@@ -21,8 +21,14 @@ class HookContextTest {
     void metadata_field_is_type_metadata() {
         ClientMetadata clientMetadata = mock(ClientMetadata.class);
         Metadata meta = mock(Metadata.class);
-        HookContext<Object> hc =
-                HookContext.from("key", FlagValueType.BOOLEAN, clientMetadata, meta, new ImmutableContext(), false);
+        HookContext<Boolean> hc = HookContext.<Boolean>builder()
+                .flagKey("key")
+                .type(FlagValueType.BOOLEAN)
+                .clientMetadata(clientMetadata)
+                .providerMetadata(meta)
+                .ctx(new ImmutableContext())
+                .defaultValue(false)
+                .build();
 
         assertTrue(ClientMetadata.class.isAssignableFrom(hc.getClientMetadata().getClass()));
         assertTrue(Metadata.class.isAssignableFrom(hc.getProviderMetadata().getClass()));