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

[dmarticus]

Summary

• Adds Client#evaluate_flags(distinct_id, …) returning a FeatureFlagEvaluations snapshot — one /flags round-trip powers both branching and event enrichment.
• Snapshot exposes is_enabled / get_flag / get_flag_payload for branching, plus only_accessed / only([keys]) to narrow what gets attached to a captured event.
• Adds flags: option on capture and capture_exception — when present, attaches $feature/<key> and $active_feature_flags from the snapshot without any extra /flags call.
• flag_keys: on evaluate_flags scopes the underlying /flags request itself (sent as flag_keys_to_evaluate).
• Deprecates is_feature_enabled, get_feature_flag, get_feature_flag_result, get_feature_flag_payload, and capture(send_feature_flags:) — they keep working but now emit a DeprecationWarning pointing at evaluate_flags(). Removal is planned for the next major.
• Adds a feature_flags_log_warnings: client option (default true) to silence the snapshot's filter-helper warnings.

References

RFC: https://github.com/PostHog/requests-for-comments-internal/pull/1020 · mirrors posthog-python#539 and posthog-js#3476.

Design decisions

• is_enabled returns false for unknown flags, get_flag returns nil — matches the legacy single-flag methods so existing branching code is structurally interchangeable.
• get_flag_payload deliberately does not record access or fire $feature_flag_called — payload-only reads shouldn't count as an exposure.
• only_accessed() returns an empty snapshot when nothing has been accessed (it honors its name) — pre-access flags first if you want a populated result.
• Filtered snapshot clones get a copy of the parent's accessed set, so calls on a clone don't back-propagate exposures into the parent.
• A small Host struct (two lambdas: capture_flag_called_event_if_needed, log_warning) is passed to the snapshot instead of a back-reference to the full Client — keeps the snapshot decoupled and testable.
• Locally-evaluated flags are tagged with locally_evaluated: true, reason "Evaluated locally", and $feature_flag_definitions_loaded_at on emitted events, matching the existing single-flag local path.
• Response-level errors (errorsWhileComputingFlags, quotaLimited) and per-flag errors (flag_missing) are combined into a comma-joined $feature_flag_error so each event keeps the granular error code(s).
• Passing both flags: and send_feature_flags: to capture uses the snapshot and warns — the snapshot guarantees the event carries the same values your code branched on.
• Deprecated methods bypass each other internally (is_feature_enabled and get_feature_flag call a private _get_feature_flag_result directly) so a single user-level call emits exactly one warning, not a cascade.

Phase 2 follow-ups

• Update docs at https://posthog.com/docs/libraries/ruby and the feature-flags pages so the wizard / new-app instrumentation points at evaluate_flags().
• Consider stashing the active flags snapshot on a request-scoped context so auto-captured exceptions inherit the same flag context as manual captures.

All tests + lint pass on Ruby 3.2 / 3.3 / 3.4 (380 examples).

---

Created with PostHog Code