feat(flags): Add version info to $feature_flag_called request

[haacked]

This PR adds /decide?v=4 support to posthog-js. What we get with this support are the following:

A new getFeatureFlagDetails(key) method

This returns the full details of a feature flag. For example:

{
    "beta-feature-flag": {
    "key": "beta-feature-flag",
    "enabled": true,
    "variant": "variant-3",
    "reason": {
        "code": "condition_match",
        "condition_index": 0,
        "description": null
    },
    "metadata": {
        "id": 8,
        "payload": "{\"paylod\": \"3\"}",
        "version": 19,
        "description": ""
    }
}

This includes an evaluation reason (description is currently null, but will be populated in a future PR).
It also includes metadata such as the db id of the flag and its version.

There's also the corresponding getFlagsWithDetails() method to get all the flag details.

Updates to the $feature_flag_called event

When capturing the $feature_flag_called event, additional information are now captured:

1. $feature_flag_version: The version of the feature flag.
2. $feature_flag_id: The database id of the flag. A flag can be deleted and recreated with the same key, so this helps us determine if that's the case.
3. $feature_flag_reason: The reason the flag evaluated as it did. For now, it's just the evaluation code, but once [Flag reporting improvements] Add evaluation reason to decide response posthog#29445 is completed, this will include a human friendly description.
4. $feature_flag_original_response: This contains the original response in the situation that the client overrode the flag via a call to overrideFeatureFlags().
5. $feature_flag_original_payload: This contains the original payload in the situation that the client overrode the payload via a call to overrideFeatureFlags().

Sending the original values will help debug in the rare situation that a customer is confused by a flag result and forgot they were overriding it. 😆

Backwards compatibility:

The changes are all backwards compatible with /decide?v=3. Any requests for /decide?v=4 today will return a v=3 response. Once PostHog/posthog#29751 is deployed, then these new additions will "light up".

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Updated (UTC)
posthog-js	✅ Ready (Inspect)	Visit Preview	Mar 14, 2025 10:12pm

[github-actions]

Size Change: +24.3 kB (+0.68%)

Total Size: 3.6 MB

Filename	Size	Change
dist/array.full.es5.js	277 kB	+2.59 kB (+0.94%)
dist/array.full.js	380 kB	+2.42 kB (+0.64%)
dist/array.full.no-external.js	379 kB	+2.42 kB (+0.64%)
dist/array.js	188 kB	+2.41 kB (+1.3%)
dist/array.no-external.js	187 kB	+2.41 kB (+1.31%)
dist/main.js	189 kB	+2.41 kB (+1.29%)
dist/module.full.js	380 kB	+2.42 kB (+0.64%)
dist/module.full.no-external.js	379 kB	+2.42 kB (+0.64%)
dist/module.js	188 kB	+2.41 kB (+1.3%)
dist/module.no-external.js	187 kB	+2.41 kB (+1.31%)

ℹ️ View Unchanged

Filename	Size
dist/all-external-dependencies.js	220 kB
dist/customizations.full.js	14 kB
dist/dead-clicks-autocapture.js	14.5 kB
dist/exception-autocapture.js	9.94 kB
dist/external-scripts-loader.js	2.75 kB
dist/posthog-recorder.js	212 kB
dist/recorder-v2.js	115 kB
dist/recorder.js	115 kB
dist/surveys-preview.js	71.3 kB
dist/surveys.js	76 kB
dist/tracing-headers.js	1.76 kB
dist/web-vitals.js	10.4 kB

_{compressed-size-action}

[greptile-apps]

PR Summary

This PR adds support for /decide?v=4 endpoint in the PostHog JavaScript SDK, introducing significant enhancements to feature flag functionality. Here's a summary of the key changes:

• Added new getFeatureFlagDetails() method returning comprehensive flag information including evaluation reasons, metadata, and version info
• Enhanced $feature_flag_called event with additional fields like $feature_flag_version, $feature_flag_id, and $feature_flag_reason
• Added tracking of original flag values when overridden through overrideFeatureFlags() for debugging purposes
• Added proper handling of quota limiting scenarios for feature flag requests
• Updated all relevant tests and types while maintaining backwards compatibility with /decide?v=3

The changes appear well-structured with comprehensive test coverage and proper type definitions. The new functionality will help with debugging and provide more detailed insights into feature flag behavior.

_{7 file(s) reviewed, 1 comment(s)
Edit PR Review Bot Settings | Greptile}

[haacked]

Here's an example showing the additional information:

[haacked]

If you're wondering why I am excluding this, if we don't, it would get rendered like so:

Yikes! Useful info, but maybe too much and we'd need to figure out how to render it more nicely.

[haacked]

Made one last (hopefully) change to how we include the reason in the response:

I think the whole structure is useful. Later, when we implement a human friendly description, it can be included in there.

I need to dig into this, but by having structured data in there, I hope this'll make it possible to filter on $feature_flag_called events by reason.code so we can see all flags that matched a condition, etc.

Happy to roll that back if others don't like it and would rather it just be the human friendly description.