fix(feature-management): enumerate flags via /flags when no PersonalApiKey

Without a PersonalApiKey the local evaluator is null, which left
PostHogVariantFeatureManager.GetFeatureNamesAsync and
PostHogFeatureDefinitionProvider.GetAllFeatureDefinitionsAsync returning
nothing — breaking the MSFT Feature Management definition-driven path
for SDK consumers who use the remote /flags evaluation path only.

Fall back to a single /flags poll using a stable sentinel distinct_id
($feature_enumeration_sentinel) and use the returned flag keys. The
sentinel stays constant so the existing in-memory /flags cache (keyed
by distinct_id) reuses the response and PostHog does not spawn a new
phantom person per poll. Per-flag values for the sentinel are
discarded — only the key set is consumed. GetAllFeatureFlagsAsync does
not emit $feature_flag_called events, so no analytics noise.

Local evaluation behavior is unchanged when a PersonalApiKey exists.

Refs #64.

Author: jojosenthusiast

src/PostHog.AspNetCore/FeatureManagement/FeatureEnumerationFallback.cs

@@ -0,0 +1,38 @@
+namespace PostHog.FeatureManagement;
+
+/// <summary>
+/// Shared fallback used by <see cref="PostHogFeatureDefinitionProvider"/> and
+/// <see cref="PostHogVariantFeatureManager"/> to enumerate flag keys when no
+/// <see cref="Config.PostHogOptions.PersonalApiKey"/> is configured (no local evaluation source).
+/// </summary>
+/// <remarks>
+/// <para>
+/// Polls <c>/flags</c> with a stable sentinel <c>distinct_id</c> and returns the keys from the
+/// response. Per-flag values for the sentinel are discarded — only the set of keys is consumed.
+/// </para>
+/// <para>
+/// The sentinel id is intentionally stable: a random id would spawn a phantom person on every poll
+/// and defeat the in-memory <c>/flags</c> cache. See PostHog/posthog-dotnet#64 for the rationale.
+/// </para>
+/// </remarks>
+internal static class FeatureEnumerationFallback
+{
+    /// <summary>
+    /// Stable sentinel <c>distinct_id</c> used by the enumeration fallback. Stays constant so the
+    /// SDK's in-memory <c>/flags</c> cache (keyed by distinct_id) reuses the response and PostHog
+    /// doesn't create a new phantom person per poll.
+    /// </summary>
+    internal const string SentinelDistinctId = "$feature_enumeration_sentinel";
+
+    public static async Task<IReadOnlyCollection<string>> GetFeatureKeysAsync(
+        IPostHogClient posthog,
+        CancellationToken cancellationToken)
+    {
+        var flags = await posthog.GetAllFeatureFlagsAsync(
+            distinctId: SentinelDistinctId,
+            options: null,
+            cancellationToken);
+        // Order is not guaranteed by /flags; callers (Microsoft Feature Management) don't rely on it.
+        return flags.Keys.ToList();
+    }
+}

src/PostHog.AspNetCore/FeatureManagement/PostHogFeatureDefinitionProvider.cs

@@ -31,16 +31,25 @@ public async IAsyncEnumerable<FeatureDefinition> GetAllFeatureDefinitionsAsync()
         {
             foreach (var flag in localEvaluator.LocalEvaluationApiResult.Flags)
             {
-                yield return CreateFeatureDefinition(flag);
+                yield return CreateFeatureDefinition(flag.Key);
             }
+            yield break;
+        }
+
+        // Fallback: no PersonalApiKey means no local-evaluation flag list. Poll /flags with a stable
+        // sentinel distinct_id and use the returned keys as the enumeration source. We only care about
+        // keys; the values for the sentinel are discarded. See PostHog/posthog-dotnet#64.
+        foreach (var key in await FeatureEnumerationFallback.GetFeatureKeysAsync(posthog, CancellationToken.None))
+        {
+            yield return CreateFeatureDefinition(key);
         }
     }
 
-    static FeatureDefinition CreateFeatureDefinition(LocalFeatureFlag flag)
+    static FeatureDefinition CreateFeatureDefinition(string key)
     {
         return new FeatureDefinition
         {
-            Name = flag.Key,
+            Name = key,
             EnabledFor = [new FeatureFilterConfiguration { Name = "PostHog" }],
             RequirementType = RequirementType.Any
         };

src/PostHog.AspNetCore/FeatureManagement/PostHogVariantFeatureManager.cs

@@ -23,13 +23,20 @@ public async IAsyncEnumerable<string> GetFeatureNamesAsync(
         [EnumeratorCancellation] CancellationToken cancellationToken = new())
     {
         var localEvaluator = await posthog.GetLocalEvaluatorAsync(cancellationToken);
-        if (localEvaluator is null)
+        if (localEvaluator is not null)
         {
+            foreach (var flag in localEvaluator.LocalEvaluationApiResult.Flags)
+            {
+                yield return flag.Key;
+            }
             yield break;
         }
-        foreach (var flag in localEvaluator.LocalEvaluationApiResult.Flags)
+
+        // Fallback: no PersonalApiKey means no local-evaluation flag list. Poll /flags with a stable
+        // sentinel distinct_id and yield the returned keys. See PostHog/posthog-dotnet#64.
+        foreach (var key in await FeatureEnumerationFallback.GetFeatureKeysAsync(posthog, cancellationToken))
         {
-            yield return flag.Key;
+            yield return key;
         }
     }
 

tests/UnitTests.AspNetCore/FeatureManagement/PostHogFeatureDefinitionProviderTests.cs

@@ -67,6 +67,46 @@ public async Task ReturnsAllActiveFeatures()
     }
 }
 
+public class TheGetAllFeatureDefinitionsAsyncMethodFallback
+{
+    // Stable sentinel distinct_id used by the enumeration fallback to /flags when no PersonalApiKey
+    // is configured. Must stay stable so that PostHog doesn't spawn a phantom person on every poll
+    // and so the /flags response is cacheable. See PostHog/posthog-dotnet#64.
+    const string EnumerationSentinelDistinctId = "$feature_enumeration_sentinel";
+
+    [Fact]
+    public async Task ReturnsFlagsFromFlagsEndpointWhenNoPersonalApiKey()
+    {
+        var container = new TestContainer(sp =>
+        {
+            var builder = new PostHogConfigurationBuilder(sp);
+            builder.UseFeatureManagement<FakePostHogFeatureFlagContextProvider>();
+            // No PersonalApiKey configured.
+        });
+        container.FakeHttpMessageHandler.AddFlagsResponse(
+            requestPredicate: body =>
+                body.TryGetValue("distinct_id", out var id)
+                && id is System.Text.Json.JsonElement el
+                && el.GetString() == EnumerationSentinelDistinctId,
+            responseBody: """
+            {
+              "featureFlags": {
+                "beta-feature": true,
+                "alpha-feature": false
+              }
+            }
+            """
+        );
+        var provider = container.Activate<PostHogFeatureDefinitionProvider>();
+
+        var features = await provider.GetAllFeatureDefinitionsAsync().ToListAsync();
+
+        Assert.Equal(
+            new[] { "beta-feature", "alpha-feature" },
+            features.Select(f => f.Name).OrderByDescending(n => n));
+    }
+}
+
 public class TheGetFeatureDefinitionAsyncMethod
 {
     [Fact]

tests/UnitTests.AspNetCore/FeatureManagement/PostHogVariantFeatureManagerTests.cs

@@ -63,6 +63,45 @@ public async Task ReturnsAllActiveFeatures()
     }
 }
 
+public class TheGetFeatureNamesAsyncMethodFallback
+{
+    // Stable sentinel distinct_id used by the enumeration fallback to /flags when no PersonalApiKey
+    // is configured. See PostHog/posthog-dotnet#64.
+    const string EnumerationSentinelDistinctId = "$feature_enumeration_sentinel";
+
+    [Fact]
+    public async Task ReturnsFlagsFromFlagsEndpointWhenNoPersonalApiKey()
+    {
+        var container = new TestContainer(sp =>
+        {
+            var builder = new PostHogConfigurationBuilder(sp);
+            builder.UseFeatureManagement<FakePostHogFeatureFlagContextProvider>();
+            // No PersonalApiKey configured.
+        });
+        container.FakeHttpMessageHandler.AddFlagsResponse(
+            requestPredicate: body =>
+                body.TryGetValue("distinct_id", out var id)
+                && id is System.Text.Json.JsonElement el
+                && el.GetString() == EnumerationSentinelDistinctId,
+            responseBody: """
+            {
+              "featureFlags": {
+                "beta-feature": true,
+                "alpha-feature": false
+              }
+            }
+            """
+        );
+        var featureManager = container.Activate<PostHogVariantFeatureManager>();
+
+        var featureNames = await featureManager.GetFeatureNamesAsync().ToListAsync();
+
+        Assert.Equal(
+            new[] { "beta-feature", "alpha-feature" },
+            featureNames.OrderByDescending(n => n));
+    }
+}
+
 public class TheIsEnabledAsyncMethod
 {
     [Fact]