feat: add EvaluateFlagsAsync() API for single-call flag evaluation

Directory.Build.props

@@ -1,6 +1,6 @@
 <Project>
     <PropertyGroup>
-        <Version>2.5.0</Version>
+        <Version>2.6.0</Version>
         <LangVersion>13.0</LangVersion>
         <Nullable>enable</Nullable>
         <ImplicitUsings>enable</ImplicitUsings>

samples/HogTied.Web/Filters/PostHogPageViewFilter.cs

@@ -1,3 +1,4 @@
+#pragma warning disable CS0618 // Tests/samples retain coverage of the deprecated single-flag API surface.
 using Microsoft.AspNetCore.Mvc.Filters;
 using Microsoft.Extensions.Options;
 using PostHog;

samples/HogTied.Web/Pages/Index.cshtml.cs

@@ -1,3 +1,4 @@
+#pragma warning disable CS0618 // Tests/samples retain coverage of the deprecated single-flag API surface.
 using System.ComponentModel.DataAnnotations;
 using System.Diagnostics;
 using System.Security.Claims;
@@ -295,4 +296,4 @@ public class CacheDemoData
     public double SecondCallMs { get; set; }
     public bool? FirstResult { get; set; }
     public bool? SecondResult { get; set; }
-}
+}

samples/PostHog.Example.Console/Program.cs

@@ -1,3 +1,4 @@
+#pragma warning disable CS0618 // Tests/samples retain coverage of the deprecated single-flag API surface.
 // PostHog .NET SDK Console Example
 //
 // This demonstrates basic PostHog SDK usage including:
@@ -379,4 +380,4 @@ static async Task RunAllExamples(PostHogClient posthog, bool hasPersonalApiKey)
     await RunIdentifyExamples(posthog);
     await RunFeatureFlagExamples(posthog);
     await RunLocalEvaluationExample(posthog, hasPersonalApiKey);
-}
+}

sdk_compliance_adapter/Program.cs

@@ -86,7 +86,7 @@
         request.Event,
         request.Properties,
         groups: null,
-        sendFeatureFlags: false,
+        flags: null,
         timestamp: timestamp
     );
 

src/PostHog.AI/PostHogOpenAIHandler.cs

@@ -476,7 +476,9 @@ out var streamBool
                     groups.Add(kvp.Key, kvp.Value?.ToString() ?? string.Empty);
                 }
             }
-            // Create captured event
+            // Create captured event.
+            // TODO: migrate to Capture(..., flags: null, ...) once tests are updated.
+#pragma warning disable CS0618
             _postHogClient.Capture(
                 distinctId,
                 eventName,
@@ -485,6 +487,7 @@ out var streamBool
                 false, // sendFeatureFlags
                 DateTimeOffset.UtcNow
             );
+#pragma warning restore CS0618
         }
 #pragma warning disable CA1031 // Do not catch general exception types
         catch (Exception ex)

src/PostHog.AspNetCore/FeatureManagement/PostHogVariantFeatureManager.cs

@@ -85,7 +85,10 @@ public async ValueTask<Variant> GetVariantAsync(
             ? (postHogTargetingContext.PersonProperties, GroupsAndProperties: postHogTargetingContext.GroupCollection)
             : (null, null);
 
-        // Call PostHog's API to check if the feature is enabled for this user
+        // Call PostHog's API to check if the feature is enabled for this user.
+        // TODO: migrate to EvaluateFlagsAsync + snapshot per request to align with the SDK's
+        // Phase 1 RFC; the feature manager API is per-flag so the change isn't trivial.
+#pragma warning disable CS0618
         return await posthog.GetFeatureFlagAsync(
             featureKey: feature,
             distinctId: context.UserId,
@@ -96,6 +99,7 @@ public async ValueTask<Variant> GetVariantAsync(
             },
             cancellationToken
         );
+#pragma warning restore CS0618
     }
 }
 

src/PostHog/Capture/CaptureExtensions.cs

@@ -25,7 +25,7 @@ public static bool Capture(
             eventName,
             properties: null,
             groups: null,
-            sendFeatureFlags: false);
+            flags: null);
 
     /// <summary>
     /// Captures an event.
@@ -35,17 +35,20 @@ public static bool Capture(
     /// <param name="eventName">Human friendly name of the event. Recommended format [object] [verb] such as "Project created" or "User signed up".</param>
     /// <param name="sendFeatureFlags">Default: <c>false</c>. If <c>true</c>, feature flags are sent with the captured event.</param>
     /// <returns><c>true</c> if the event was successfully enqueued. Otherwise <c>false</c>.</returns>
+    [Obsolete("Prefer Capture(..., flags: snapshot) using a FeatureFlagEvaluations snapshot from EvaluateFlagsAsync. This overload will be removed in a future major version.", error: false)]
     public static bool Capture(
         this IPostHogClient client,
         string distinctId,
         string eventName,
         bool sendFeatureFlags)
+#pragma warning disable CS0618
         => NotNull(client).Capture(
             distinctId,
             eventName,
             properties: null,
             groups: null,
             sendFeatureFlags: sendFeatureFlags);
+#pragma warning restore CS0618
 
     /// <summary>
     /// Captures an event with additional properties to add to the event.
@@ -65,7 +68,7 @@ public static bool Capture(
             eventName,
             properties,
             groups: null,
-            sendFeatureFlags: false);
+            flags: null);
 
     /// <summary>
     /// Captures an event with a custom timestamp.
@@ -85,7 +88,7 @@ public static bool Capture(
             eventName,
             properties: null,
             groups: null,
-            sendFeatureFlags: false,
+            flags: null,
             timestamp: timestamp);
 
     /// <summary>
@@ -108,7 +111,7 @@ public static bool Capture(
             eventName,
             properties: properties,
             groups: null,
-            sendFeatureFlags: false,
+            flags: null,
             timestamp: timestamp);
 
     /// <summary>
@@ -131,7 +134,7 @@ public static bool Capture(
             eventName,
             properties: null,
             groups: groups,
-            sendFeatureFlags: false,
+            flags: null,
             timestamp: timestamp);
 
     /// <summary>
@@ -156,7 +159,7 @@ public static bool Capture(
             eventName,
             properties: properties,
             groups: groups,
-            sendFeatureFlags: false,
+            flags: null,
             timestamp: timestamp);
 
     /// <summary>
@@ -168,19 +171,22 @@ public static bool Capture(
     /// <param name="timestamp">The timestamp when the event occurred.</param>
     /// <param name="sendFeatureFlags">If <c>true</c>, feature flags are sent with the captured event.</param>
     /// <returns><c>true</c> if the event was successfully enqueued. Otherwise <c>false</c>.</returns>
+    [Obsolete("Prefer Capture(..., flags: snapshot, timestamp: timestamp) using a FeatureFlagEvaluations snapshot from EvaluateFlagsAsync. This overload will be removed in a future major version.", error: false)]
     public static bool Capture(
         this IPostHogClient client,
         string distinctId,
         string eventName,
         DateTimeOffset timestamp,
         bool sendFeatureFlags)
+#pragma warning disable CS0618
         => NotNull(client).Capture(
             distinctId,
             eventName,
             properties: null,
             groups: null,
             sendFeatureFlags: sendFeatureFlags,
             timestamp: timestamp);
+#pragma warning restore CS0618
 
     /// <summary>
     /// Captures an event with a custom timestamp, properties, groups, and feature flags.
@@ -193,6 +199,7 @@ public static bool Capture(
     /// <param name="groups">Optional: Context of what groups are related to this event, example: { ["company"] = "id:5" }. Can be used to analyze companies instead of users.</param>
     /// <param name="sendFeatureFlags">Default: <c>false</c>. If <c>true</c>, feature flags are sent with the captured event.</param>
     /// <returns><c>true</c> if the event was successfully enqueued. Otherwise <c>false</c>.</returns>
+    [Obsolete("Prefer Capture(..., flags: snapshot, ...) using a FeatureFlagEvaluations snapshot from EvaluateFlagsAsync. This overload will be removed in a future major version.", error: false)]
     public static bool Capture(
         this IPostHogClient client,
         string distinctId,
@@ -201,13 +208,15 @@ public static bool Capture(
         Dictionary<string, object>? properties,
         GroupCollection? groups,
         bool sendFeatureFlags)
+#pragma warning disable CS0618
         => NotNull(client).Capture(
             distinctId,
             eventName,
             properties: properties,
             groups: groups,
             sendFeatureFlags: sendFeatureFlags,
             timestamp: timestamp);
+#pragma warning restore CS0618
 
     /// <summary>
     /// Captures an event with properties to set on the user.
@@ -263,7 +272,7 @@ public static bool Capture(
             eventName,
             properties,
             groups: null,
-            sendFeatureFlags: false);
+            flags: null);
     }
 
     /// <summary>
@@ -284,7 +293,7 @@ public static bool Capture(
             eventName,
             properties: null,
             groups: groups,
-            sendFeatureFlags: false);
+            flags: null);
 
     /// <summary>
     /// Captures a Page View ($pageview) event.
@@ -315,19 +324,22 @@ public static bool CapturePageView(
     /// <param name="properties">Additional context to save with the event.</param>
     /// <param name="sendFeatureFlags">Default: <c>false</c>. If <c>true</c>, feature flags are sent with the captured event.</param>
     /// <returns><c>true</c> if the event was successfully enqueued. Otherwise <c>false</c>.</returns>
+    [Obsolete("Prefer CapturePageView(distinctId, pagePath, properties) and forward a FeatureFlagEvaluations snapshot via Capture(..., flags: snapshot, ...) when needed. This overload will be removed in a future major version.", error: false)]
     public static bool CapturePageView(
         this IPostHogClient client,
         string distinctId,
         string pagePath,
         Dictionary<string, object>? properties,
         bool sendFeatureFlags)
+#pragma warning disable CS0618
         => NotNull(client).CaptureSpecialEvent(
             distinctId,
             eventName: "$pageview",
             eventPropertyName: "$current_url",
             eventPropertyValue: pagePath,
             properties,
             sendFeatureFlags);
+#pragma warning restore CS0618
 
     /// <summary>
     /// Captures a Page View ($pageview) event.
@@ -347,11 +359,15 @@ public static bool CapturePageView(
     /// <param name="distinctId">The identifier you use for the user.</param>
     /// <param name="pagePath">The URL or path of the page to capture.</param>
     /// <param name="sendFeatureFlags">Default: <c>false</c>. If <c>true</c>, feature flags are sent with the captured event.</param>
+    [Obsolete("Prefer CapturePageView(distinctId, pagePath) and forward a FeatureFlagEvaluations snapshot via Capture(..., flags: snapshot, ...) when needed. This overload will be removed in a future major version.", error: false)]
     public static bool CapturePageView(
         this IPostHogClient client,
         string distinctId,
         string pagePath,
-        bool sendFeatureFlags) => NotNull(client).CapturePageView(distinctId, pagePath, properties: null, sendFeatureFlags);
+        bool sendFeatureFlags)
+#pragma warning disable CS0618
+        => NotNull(client).CapturePageView(distinctId, pagePath, properties: null, sendFeatureFlags);
+#pragma warning restore CS0618
 
 
     /// <summary>
@@ -383,19 +399,22 @@ public static bool CaptureScreenView(
     /// <param name="properties">Additional context to save with the event.</param>
     /// <param name="sendFeatureFlags">Default: <c>false</c>. If <c>true</c>, feature flags are sent with the captured event.</param>
     /// <returns><c>true</c> if the event was successfully enqueued. Otherwise <c>false</c>.</returns>
+    [Obsolete("Prefer CaptureScreenView(distinctId, screenName, properties) and forward a FeatureFlagEvaluations snapshot via Capture(..., flags: snapshot, ...) when needed. This overload will be removed in a future major version.", error: false)]
     public static bool CaptureScreenView(
         this IPostHogClient client,
         string distinctId,
         string screenName,
         Dictionary<string, object>? properties,
         bool sendFeatureFlags)
+#pragma warning disable CS0618
         => NotNull(client).CaptureSpecialEvent(
             distinctId,
             eventName: "$screen",
             eventPropertyName: "$screen_name",
             eventPropertyValue: screenName,
             properties,
             sendFeatureFlags);
+#pragma warning restore CS0618
 
     /// <summary>
     /// Captures a Screen View ($screen) event.
@@ -459,7 +478,7 @@ public static bool CaptureSurveyResponses(
             properties[$"survey_response_{i}"] = surveyResponses[i];
         }
 
-        return NotNull(client).Capture(distinctId, "survey sent", properties, groups: null, sendFeatureFlags: false);
+        return NotNull(client).Capture(distinctId, "survey sent", properties, groups: null, flags: null);
     }
 
     /// <summary>
@@ -518,6 +537,12 @@ static bool CaptureSpecialEvent(
     {
         properties ??= new Dictionary<string, object>();
         properties[eventPropertyName] = eventPropertyValue;
+        if (!sendFeatureFlags)
+        {
+            return NotNull(client).Capture(distinctId, eventName, properties, groups: null, flags: null);
+        }
+#pragma warning disable CS0618
         return NotNull(client).Capture(distinctId, eventName, properties, null, sendFeatureFlags);
+#pragma warning restore CS0618
     }
 }

src/PostHog/Config/PostHogOptions.cs

@@ -88,6 +88,15 @@ public string? ProjectApiKey
     /// </summary>
     public TimeSpan FeatureFlagSentCacheSlidingExpiration { get; set; } = TimeSpan.FromMinutes(10);
 
+    /// <summary>
+    /// When <c>true</c> (default), the SDK emits warning logs from the
+    /// <see cref="Features.FeatureFlagEvaluations"/> snapshot helpers — specifically when
+    /// <see cref="Features.FeatureFlagEvaluations.OnlyAccessed"/> is called before any flags have been accessed,
+    /// or when <see cref="Features.FeatureFlagEvaluations.Only(System.Collections.Generic.IEnumerable{string})"/>
+    /// is given keys that are not present in the snapshot. Set to <c>false</c> to silence these warnings.
+    /// </summary>
+    public bool FeatureFlagsLogWarnings { get; set; } = true;
+
     /// <summary>
     /// The maximum number of messages to send in a batch. (Default: 100)
     /// </summary>