feat: add evaluate_flags/2 API for single-call flag evaluation

[dmarticus]

Summary

• New PostHog.FeatureFlags.evaluate_flags/2 returns an Evaluations snapshot from a single /flags call.
• Snapshot exposes enabled?/2, get_flag/2, get_flag_payload/2, only/2, keys/1, event_properties/1. enabled?/2 and get_flag/2 fire $feature_flag_called with full metadata; get_flag_payload/2 doesn't.
• set_in_context/2 copies the snapshot's $feature/<key> and $active_feature_flags into the per-process context so subsequent PostHog.capture/3 calls pick them up — no new capture arity needed.
• %PostHog.FeatureFlags.Result{} now carries :id, :version, :reason, :request_id, and :evaluated_at. The existing check/3, check!/3, and get_feature_flag_result/4 paths attach the matching $feature_flag_* properties to $feature_flag_called events when the response provides them — needed for experiment exposure tracking.
• Pass flag_keys: [...] to evaluate_flags/2 to scope the underlying /flags request itself (forwarded as flag_keys_to_evaluate).

RFC: https://github.com/PostHog/requests-for-comments-internal/pull/1020. Reference implementations: posthog-python#539, posthog-js#3476.

Design decisions

• No capture(flags: snapshot) argument. Elixir's SDK already propagates $feature/* through the per-process context that check/3 writes to and capture/3 reads back. set_in_context/2 slots into that mechanism instead of fighting it.
• Snapshot is pure-functional, not Agent-backed. Mutable access tracking would require an Agent or threading a new snapshot through every query — both awkward in Elixir. only/2 (filter by explicit keys) is enough; only_accessed/1 from the cross-SDK API is dropped.
• Predicate is enabled?/2, not is_enabled/2. Idiomatic Elixir; is_* is reserved for guard-safe predicates and Credo flags it.
• Both paths share build_result/3 and log_feature_flag_usage/3. The existing single-flag path now emits the same rich metadata as the new snapshot path — single source of truth for $feature_flag_called properties.
• No dedup cache. The Elixir SDK has no per-distinct_id dedup for $feature_flag_called; both paths fire on every access. Adding the cache is a separate behavior change to existing call sites and lands in its own PR.
• No new config option. only/2 silently drops unknown keys (matching Map.take/2), so there's no warning to silence.

Phase 2 follow-ups

• Per-distinct_id dedup cache for $feature_flag_called events, applied to both paths.
• Local-evaluation poller, with locally_evaluated, $feature_flag_reason: "Evaluated locally", and $feature_flag_definitions_loaded_at plumbed through the snapshot.
• Runtime deprecation warnings on check/3, check!/3, get_feature_flag_result/4, get_feature_flag_result!/4 pointing at evaluate_flags/2.
• only_accessed/1 if users ask for it.

---

Created with PostHog Code

[github-actions]

posthog-elixir Compliance Report

Date: 2026-04-27 20:20:45 UTC
Duration: 207ms

⚠️ Some Tests Failed

0/1 tests passed, 1 failed

---

Feature_Flags Tests

⚠️ 0/1 tests passed, 1 failed

View Details

Test	Status	Duration
Request Payload.Request With Person Properties Device Id	❌	6ms

Failures

request_payload.request_with_person_properties_device_id

404, message='Not Found', url='http://sdk-adapter:8080/get_feature_flag'