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

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

Add Client#evaluate_flags(distinct_id, ...) returning a
FeatureFlagEvaluations snapshot, and a flags: option on capture so
a single /flags call can power both flag branching and event
enrichment per request.

The snapshot exposes is_enabled, get_flag, get_flag_payload, plus
only_accessed / only([keys]) filter helpers. flag_keys: scopes the
underlying /flags request itself. is_enabled and get_flag fire
$feature_flag_called events with full metadata (id, version, reason,
request_id), deduped through the existing per-distinct_id cache.
get_flag_payload does not record access or fire an event.

The dedup + capture in get_feature_flag_result is extracted into
_capture_feature_flag_called_if_needed and shared between the existing
path and the snapshot's access-recording.

Existing is_feature_enabled, get_feature_flag, get_feature_flag_result,
get_feature_flag_payload, and capture(send_feature_flags:) continue
to work unchanged.

Generated-By: PostHog Code
Task-Id: fe67a5bd-7d33-4568-9148-39d181660a5a

* feat: incorporate posthog-python#539 review feedback

Mirrors the changes that landed on the Python PR after review:

- only_accessed returns an empty snapshot when nothing has been
  accessed (drops the warn-and-fall-back-to-all-flags behavior — that
  was a misguided safety net that surprised callers in the
  early-pre-access pattern).
- capture(flags:, send_feature_flags:) now warns when both are passed,
  uses the snapshot, and ignores send_feature_flags. The snapshot
  guarantees the event carries the values branched on; the precedence
  was previously implicit.
- $feature_flag_called events now carry response-level errors
  (errors_while_computing_flags, quota_limited) combined with per-flag
  errors (flag_missing) as a comma-joined $feature_flag_error, matching
  the granularity of the legacy single-flag path.
- capture_exception now accepts a flags: kwarg and forwards it to the
  inner capture() so $exception events can carry the same flag context
  as other events.
- Phase 2 deprecation warnings ship alongside Phase 1: is_feature_enabled,
  get_feature_flag, get_feature_flag_result, get_feature_flag_payload,
  and capture(send_feature_flags:) emit Kernel.warn(..., category:
  :deprecated) pointing at evaluate_flags(). Public methods bypass
  each other internally (via a new private _get_feature_flag_result)
  so a single user-level call emits exactly one warning.

Generated-By: PostHog Code
Task-Id: fe67a5bd-7d33-4568-9148-39d181660a5a

* feat: address Dustin's review feedback on evaluate_flags PR

Snapshot:
- Rename is_enabled → enabled? for Ruby idiom (the legacy
  client-level is_feature_enabled keeps its name but is now deprecated).
- Canonicalize the recorded $feature_flag_response across
  enabled?/get_flag so a variant flag accessed both ways collapses to
  one $feature_flag_called event (with the variant value) instead of
  two with mismatched booleans. Same fix for missing flags: response
  is nil regardless of which method was called.

Client / poller:
- Drop the feature_flags_log_warnings config option in favor of
  standard log-level gating: warnings flow through logger.warn so
  callers silence them via their existing log config (mirrors the
  posthog-android feedback).
- Skip the remote /flags call when flag_keys are all locally
  resolved. Without flag_keys we still hit the server because we don't
  know about server-side-only flags.
- Forward disable_geoip to the /flags request body as geoip_disable.
- Use a Set for flag_keys lookup to keep the per-flag check O(1).
- Normalize remote and local-eval payloads via
  FeatureFlagResult.parse_payload (made public — same contract as
  FeatureFlagResult.from_value_and_payload uses internally).
- Guard capture(flags:) against non-snapshot values: log a warning
  and ignore instead of raising NoMethodError.
- Move _get_feature_flag_result into the private section.

Deprecation warnings:
- Drop the :deprecated category — Ruby suppresses those by default
  since 2.7.2 and most users wouldn't see them. Use Kernel.warn with
  a [posthog-ruby] DEPRECATION prefix; standard log-level / IO
  silencing still works.
- Emit each deprecation at most once per (method, client) pair via
  Concurrent::Set so high-volume callers don't pay a per-call cost.

Generated-By: PostHog Code
Task-Id: fe67a5bd-7d33-4568-9148-39d181660a5a

* chore: update changeset to match enabled? rename

The changeset was written before the is_enabled → enabled? rename
that came out of Dustin's review; align the example snippet and
description so the generated CHANGELOG entry uses the final API
naming. Also softens "DeprecationWarning" to "one-time deprecation
warning per method" since we dropped the :deprecated category in
favor of always-visible Kernel.warn.

Generated-By: PostHog Code
Task-Id: fe67a5bd-7d33-4568-9148-39d181660a5a

Author: dmarticus

.changeset/evaluate-flags-api.md

@@ -0,0 +1,14 @@
+---
+"posthog-ruby": minor
+---
+
+Add `evaluate_flags(distinct_id, …)` returning a `FeatureFlagEvaluations` snapshot, and a `flags:` option on `capture` so a single `/flags` call can power both flag branching and event enrichment per request.
+
+```ruby
+snapshot = posthog.evaluate_flags("user-1", flag_keys: ["checkout-redesign"])
+posthog.capture(distinct_id: "user-1", event: "checkout_started", flags: snapshot) if snapshot.enabled?("checkout-redesign")
+```
+
+The snapshot exposes `enabled?`, `get_flag`, `get_flag_payload`, plus `only_accessed` / `only([keys])` filter helpers. `flag_keys:` scopes the underlying `/flags` request itself. `enabled?` and `get_flag` fire `$feature_flag_called` events with full metadata (`$feature_flag_id`, `$feature_flag_version`, `$feature_flag_reason`, `$feature_flag_request_id`), deduped through the existing per-distinct_id cache. `get_flag_payload` does not record access or fire an event.
+
+Deprecates `is_feature_enabled`, `get_feature_flag`, `get_feature_flag_result`, `get_feature_flag_payload`, and `capture(send_feature_flags:)`. They continue to work unchanged but now emit a one-time deprecation warning per method pointing at `evaluate_flags()`. Removal is planned for the next major version.

lib/posthog.rb

@@ -12,4 +12,5 @@
 require 'posthog/exception_capture'
 require 'posthog/feature_flag_error'
 require 'posthog/feature_flag_result'
+require 'posthog/feature_flag_evaluations'
 require 'posthog/flag_definition_cache'

lib/posthog/client.rb

@@ -0,0 +1,177 @@
+# frozen_string_literal: true
+
+require 'set'
+
+module PostHog
+  # A snapshot of feature flag evaluations for one distinct_id, returned by
+  # PostHog::Client#evaluate_flags. Calls to {#is_enabled} / {#get_flag} fire the
+  # `$feature_flag_called` event (deduped through the existing per-distinct_id
+  # cache); {#get_flag_payload} does not. Pass the snapshot to `capture(flags:)`
+  # to attach `$feature/<key>` and `$active_feature_flags` without a second
+  # /flags request.
+  class FeatureFlagEvaluations
+    EVALUATED_LOCALLY_REASON = 'Evaluated locally'
+
+    EvaluatedFlagRecord = Struct.new(
+      :key, :enabled, :variant, :payload, :id, :version, :reason, :locally_evaluated,
+      keyword_init: true
+    )
+
+    Host = Struct.new(:capture_flag_called_event_if_needed, :log_warning, keyword_init: true)
+
+    attr_reader :distinct_id, :groups, :request_id, :evaluated_at, :flag_definitions_loaded_at
+
+    def initialize(
+      host: nil,
+      distinct_id: nil,
+      flags: {},
+      groups: nil,
+      disable_geoip: nil,
+      request_id: nil,
+      evaluated_at: nil,
+      flag_definitions_loaded_at: nil,
+      errors_while_computing: false,
+      quota_limited: false,
+      accessed: nil
+    )
+      @host = host
+      @distinct_id = distinct_id || ''
+      @flags = flags || {}
+      @groups = groups
+      @disable_geoip = disable_geoip
+      @request_id = request_id
+      @evaluated_at = evaluated_at
+      @flag_definitions_loaded_at = flag_definitions_loaded_at
+      @errors_while_computing = errors_while_computing
+      @quota_limited = quota_limited
+      @accessed = Set.new(accessed || [])
+    end
+
+    def keys
+      @flags.keys
+    end
+
+    def enabled?(key)
+      key = key.to_s
+      flag = @flags[key]
+      _record_access(key, flag)
+      flag&.enabled ? true : false
+    end
+
+    def get_flag(key)
+      key = key.to_s
+      flag = @flags[key]
+      _record_access(key, flag)
+      _flag_value(flag)
+    end
+
+    def get_flag_payload(key)
+      flag = @flags[key.to_s]
+      flag&.payload
+    end
+
+    # Order-dependent: if nothing has been accessed yet, the returned snapshot is
+    # empty. The method honors its name — pre-access flags before calling this if
+    # you want a populated result.
+    def only_accessed
+      _clone_with(@flags.slice(*@accessed))
+    end
+
+    def only(keys)
+      keys = Array(keys).map(&:to_s)
+      missing = keys.reject { |k| @flags.key?(k) }
+      unless missing.empty?
+        @host.log_warning.call(
+          'FeatureFlagEvaluations#only was called with flag keys that are not in the ' \
+          "evaluation set and will be dropped: #{missing.join(', ')}"
+        )
+      end
+      filtered = @flags.slice(*keys)
+      _clone_with(filtered)
+    end
+
+    # Builds the `$feature/<key>` and `$active_feature_flags` properties for a
+    # captured event. Called from PostHog::Client#capture when `flags:` is set.
+    def _get_event_properties
+      properties = {}
+      active = []
+      @flags.each do |key, flag|
+        properties["$feature/#{key}"] = flag.enabled ? (flag.variant || true) : false
+        active << key if flag.enabled
+      end
+      properties['$active_feature_flags'] = active.sort unless active.empty?
+      properties
+    end
+
+    private
+
+    # Canonical "stored" value for a flag — used for both the
+    # `$feature_flag_response` event property and the dedup cache key, so
+    # `enabled?` and `get_flag` collapse to a single exposure per flag.
+    # Variant string when present, else boolean enabled status; `nil` for
+    # unknown flags.
+    def _flag_value(flag)
+      return nil if flag.nil?
+      return flag.variant if flag.variant
+
+      flag.enabled ? true : false
+    end
+
+    def _record_access(key, flag)
+      @accessed.add(key)
+      return if @distinct_id.nil? || @distinct_id.to_s.empty?
+
+      response = _flag_value(flag)
+      properties = {
+        '$feature_flag' => key,
+        '$feature_flag_response' => response,
+        'locally_evaluated' => flag&.locally_evaluated ? true : false,
+        "$feature/#{key}" => response
+      }
+
+      if flag
+        properties['$feature_flag_payload'] = flag.payload unless flag.payload.nil?
+        properties['$feature_flag_id'] = flag.id if flag.id
+        properties['$feature_flag_version'] = flag.version if flag.version
+        properties['$feature_flag_reason'] = flag.reason if flag.reason
+        if flag.locally_evaluated && @flag_definitions_loaded_at
+          properties['$feature_flag_definitions_loaded_at'] = @flag_definitions_loaded_at
+        end
+      end
+
+      properties['$feature_flag_request_id'] = @request_id if @request_id
+      properties['$feature_flag_evaluated_at'] = @evaluated_at if @evaluated_at && !(flag && flag.locally_evaluated)
+
+      errors = []
+      errors << 'errors_while_computing_flags' if @errors_while_computing
+      errors << 'quota_limited' if @quota_limited
+      errors << 'flag_missing' if flag.nil?
+      properties['$feature_flag_error'] = errors.join(',') unless errors.empty?
+
+      @host.capture_flag_called_event_if_needed.call(
+        distinct_id: @distinct_id,
+        key: key,
+        response: response,
+        properties: properties,
+        groups: @groups,
+        disable_geoip: @disable_geoip
+      )
+    end
+
+    def _clone_with(flags)
+      self.class.new(
+        host: @host,
+        distinct_id: @distinct_id,
+        flags: flags,
+        groups: @groups,
+        disable_geoip: @disable_geoip,
+        request_id: @request_id,
+        evaluated_at: @evaluated_at,
+        flag_definitions_loaded_at: @flag_definitions_loaded_at,
+        errors_while_computing: @errors_while_computing,
+        quota_limited: @quota_limited,
+        accessed: @accessed.dup
+      )
+    end
+  end
+end

lib/posthog/feature_flag_evaluations.rb

@@ -39,6 +39,10 @@ def self.from_value_and_payload(key, value, payload)
       end
     end
 
+    # Deserialize a flag payload. Strings are JSON-parsed (with the raw string
+    # returned when the body is not valid JSON); already-deserialized values
+    # pass through. Public so {FeatureFlagEvaluations} can normalize payloads
+    # the same way {FeatureFlagResult} does.
     def self.parse_payload(payload)
       return nil if payload.nil?
       return payload unless payload.is_a?(String)
@@ -50,7 +54,5 @@ def self.parse_payload(payload)
         payload
       end
     end
-
-    private_class_method :parse_payload
   end
 end

lib/posthog/feature_flag_result.rb

@@ -46,6 +46,7 @@ def initialize(
       @on_error = on_error || proc { |status, error| }
       @quota_limited = Concurrent::AtomicBoolean.new(false)
       @flags_etag = Concurrent::AtomicReference.new(nil)
+      @flag_definitions_loaded_at = nil
 
       @flag_definition_cache_provider = flag_definition_cache_provider
       FlagDefinitionCacheProvider.validate!(@flag_definition_cache_provider) if @flag_definition_cache_provider
@@ -72,6 +73,8 @@ def load_feature_flags(force_reload = false)
       _load_feature_flags
     end
 
+    attr_reader :flag_definitions_loaded_at, :feature_flags_by_key
+
     def get_feature_variants(
       distinct_id,
       groups = {},
@@ -120,13 +123,16 @@ def get_feature_payloads(
       end
     end
 
-    def get_flags(distinct_id, groups = {}, person_properties = {}, group_properties = {})
+    def get_flags(distinct_id, groups = {}, person_properties = {}, group_properties = {}, flag_keys = nil,
+                  disable_geoip = nil)
       request_data = {
         distinct_id: distinct_id,
         groups: groups,
         person_properties: person_properties,
         group_properties: group_properties
       }
+      request_data[:flag_keys_to_evaluate] = flag_keys if flag_keys && !flag_keys.empty?
+      request_data[:geoip_disable] = true if disable_geoip
 
       flags_response = _request_feature_flag_evaluation(request_data)
 
@@ -1124,6 +1130,7 @@ def _apply_flag_definitions(data)
       @cohorts = Concurrent::Hash[deep_symbolize_keys(cohorts)]
 
       logger.debug "Loaded #{@feature_flags.length} feature flags and #{@cohorts.length} cohorts"
+      @flag_definitions_loaded_at = (Time.now.to_f * 1000).to_i
       @loaded_flags_successfully_once.make_true if @loaded_flags_successfully_once.false?
     end