posthog-ruby 3.6.4 → 3.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b48a174a03d0e38137942c28829ea24f7ff4ef88827dea2319b5f03b39a7401d
-  data.tar.gz: ce8c7d2446f5356ba578d4b30dfbde67239cf36a634d36662fad21ec9c949045
+  metadata.gz: afcf66d4afc793e15c83b53e455ef605218def4581460279d45721b82c1f73f2
+  data.tar.gz: 96f13bf72ddc840302d71c21072db26bdd098b73fd862455dc65b745357dc7d2
 SHA512:
-  metadata.gz: '02590918cb8cd087c997a866eafeb0174b52bb611e38fc541d5a31de58b6e16a52d4d49e8120a48862d28afd9e8a13f7fca108947417d96a0b4f837e55d1cf1c'
-  data.tar.gz: ae2697f0031883102ec584629c1452d8b712096ccf0d0ebe6b0b1a518984b09751de82c981e90525c141e21e1923907186af8a89586e58632af08b308dc24613
+  metadata.gz: 8b3e3871c5be034db9928b012cc0a3417121dc6f1ab4e7c5ece24e1c637dc04959ef50e4f551de598e11c4922d4f54048a9438bb03c86eb1e0eac67eabefdf7d
+  data.tar.gz: 3bf3128f6333b9678aa9c3a616494fcbff369ece30a0b0c422468cdab8856902a4184a560da84d6dbadb3dc935555b7402fe63d9158ea1da62589115247e7357

data/lib/posthog/client.rb

@@ -11,6 +11,7 @@ require 'posthog/noop_worker'
 require 'posthog/message_batch'
 require 'posthog/transport'
 require 'posthog/feature_flags'
+require 'posthog/feature_flag_evaluations'
 require 'posthog/send_feature_flags_options'
 require 'posthog/exception_capture'
 
@@ -59,7 +60,7 @@ module PostHog
     #   on the calling thread. Useful in forking environments like Sidekiq
     #   and Resque. Defaults to +false+.
     # @option opts [Proc] :on_error Handles error calls from the API.
-    # @option opts [String] :host Fully qualified hostname of the PostHog server. Defaults to `https://app.posthog.com`
+    # @option opts [String] :host Fully qualified hostname of the PostHog server. Defaults to `https://us.i.posthog.com`
     # @option opts [Integer] :feature_flags_polling_interval How often to poll for feature flag definition changes.
     #   Measured in seconds, defaults to 30.
     # @option opts [Integer] :feature_flag_request_timeout_seconds How long to wait for feature flag evaluation.
@@ -74,7 +75,9 @@ module PostHog
     def initialize(opts = {})
       symbolize_keys!(opts)
 
-      opts[:host] ||= 'https://app.posthog.com'
+      opts[:api_key] = normalize_string_option(opts[:api_key])
+      opts[:personal_api_key] = normalize_string_option(opts[:personal_api_key], blank_as_nil: true)
+      opts[:host] = normalize_host_option(opts[:host])
 
       @queue = Queue.new
       @api_key = opts[:api_key]
@@ -102,6 +105,7 @@ module PostHog
       @personal_api_key = opts[:personal_api_key]
 
       check_api_key!
+      logger.error('api_key is empty after trimming whitespace; check your project API key') if @api_key == ''
 
       # Warn when multiple clients are created with the same API key (can cause dropped events)
       unless opts[:test_mode] || opts[:disable_singleton_warning]
@@ -132,6 +136,7 @@ module PostHog
       end
 
       @before_send = opts[:before_send]
+      @deprecation_emitted_for = Concurrent::Set.new
     end
 
     # Synchronously waits until the worker has cleared the queue.
@@ -172,6 +177,10 @@ module PostHog
     # @option attrs [Hash] :properties Event properties (optional)
     # @option attrs [Bool, Hash, SendFeatureFlagsOptions] :send_feature_flags
     #   Whether to send feature flags with this event, or configuration for feature flag evaluation (optional)
+    # @option attrs [PostHog::FeatureFlagEvaluations] :flags A snapshot returned by
+    #   {#evaluate_flags}. When present, `$feature/<key>` and `$active_feature_flags` are
+    #   attached from the snapshot without making an additional /flags request, and this
+    #   takes precedence over `:send_feature_flags`.
     # @option attrs [String] :uuid ID that uniquely identifies an event;
     #                             events in PostHog are deduplicated by the
     #                             combination of teamId, timestamp date,
@@ -180,8 +189,39 @@ module PostHog
     def capture(attrs)
       symbolize_keys! attrs
 
+      # Precedence: an explicit `flags` snapshot always wins, regardless of
+      # `send_feature_flags`. The snapshot guarantees the event carries the same
+      # values the developer branched on with no additional network call.
+      if attrs[:flags]
+        if attrs[:flags].is_a?(FeatureFlagEvaluations)
+          if attrs[:send_feature_flags]
+            logger.warn(
+              '[FEATURE FLAGS] Both `flags` and `send_feature_flags` were passed to ' \
+              'capture(); using `flags` and ignoring `send_feature_flags`.'
+            )
+          end
+          snapshot_props = attrs[:flags]._get_event_properties
+          attrs[:properties] = snapshot_props.merge(attrs[:properties] || {})
+          attrs.delete(:flags)
+          attrs.delete(:send_feature_flags)
+        else
+          logger.warn(
+            '[FEATURE FLAGS] capture(flags:) expects a PostHog::FeatureFlagEvaluations snapshot ' \
+            "from `client.evaluate_flags(...)`; got #{attrs[:flags].class}. Ignoring."
+          )
+          attrs.delete(:flags)
+        end
+      end
+
       send_feature_flags_param = attrs[:send_feature_flags]
       if send_feature_flags_param
+        _emit_deprecation(
+          :capture_send_feature_flags,
+          '`send_feature_flags` on `capture` is deprecated and will be removed in a future major ' \
+          'version. Pass a `flags` snapshot from `client.evaluate_flags(...)` instead — it ' \
+          'avoids a second `/flags` request per capture and guarantees the event carries the ' \
+          'exact flag values your code branched on.'
+        )
         # Handle different types of send_feature_flags parameter
         case send_feature_flags_param
         when true
@@ -222,7 +262,10 @@ module PostHog
     # @param [Exception, String, Object] exception The exception to capture, a string message, or exception-like object
     # @param [String] distinct_id The ID for the user (optional, defaults to a generated UUID)
     # @param [Hash] additional_properties Additional properties to include with the exception event (optional)
-    def capture_exception(exception, distinct_id = nil, additional_properties = {})
+    # @param [PostHog::FeatureFlagEvaluations] flags A snapshot returned by {#evaluate_flags}.
+    #   Forwarded to the inner {#capture} call so the captured `$exception` event carries the
+    #   same `$feature/<key>` and `$active_feature_flags` properties as the snapshot.
+    def capture_exception(exception, distinct_id = nil, additional_properties = {}, flags: nil)
       exception_info = ExceptionCapture.build_parsed_exception(exception)
 
       return if exception_info.nil?
@@ -240,6 +283,7 @@ module PostHog
         properties: properties,
         timestamp: Time.now
       }
+      event_data[:flags] = flags if flags
 
       capture(event_data)
     end
@@ -290,6 +334,7 @@ module PostHog
       @queue.length
     end
 
+    # @deprecated Use {#evaluate_flags} and {FeatureFlagEvaluations#is_enabled} instead.
     # TODO: In future version, rename to `feature_flag_enabled?`
     def is_feature_enabled( # rubocop:disable Naming/PredicateName
       flag_key,
@@ -300,15 +345,20 @@ module PostHog
       only_evaluate_locally: false,
       send_feature_flag_events: true
     )
-      response = get_feature_flag(
-        flag_key,
-        distinct_id,
-        groups: groups,
-        person_properties: person_properties,
-        group_properties: group_properties,
-        only_evaluate_locally: only_evaluate_locally,
-        send_feature_flag_events: send_feature_flag_events
+      _emit_deprecation(
+        :is_feature_enabled,
+        '`is_feature_enabled` is deprecated and will be removed in a future major version. ' \
+        'Use `client.evaluate_flags(distinct_id, ...)` and call `flags.enabled?(key)` instead — ' \
+        'this consolidates flag evaluation into a single `/flags` request per incoming request.'
+      )
+      # Bypass the public `get_feature_flag` so the user only sees a single deprecation
+      # warning per call, not a cascade.
+      result = _get_feature_flag_result(
+        flag_key, distinct_id,
+        groups: groups, person_properties: person_properties, group_properties: group_properties,
+        only_evaluate_locally: only_evaluate_locally, send_feature_flag_events: send_feature_flag_events
       )
+      response = result&.value
       return nil if response.nil?
 
       !!response
@@ -341,6 +391,7 @@ module PostHog
     # ```ruby
     #     group_properties: {"organization": {"name": "PostHog", "employees": 11}}
     # ```
+    # @deprecated Use {#evaluate_flags} and {FeatureFlagEvaluations#get_flag} instead.
     def get_feature_flag(
       key,
       distinct_id,
@@ -350,77 +401,175 @@ module PostHog
       only_evaluate_locally: false,
       send_feature_flag_events: true
     )
-      result = get_feature_flag_result(
-        key,
-        distinct_id,
-        groups: groups,
-        person_properties: person_properties,
-        group_properties: group_properties,
-        only_evaluate_locally: only_evaluate_locally,
-        send_feature_flag_events: send_feature_flag_events
+      _emit_deprecation(
+        :get_feature_flag,
+        '`get_feature_flag` is deprecated and will be removed in a future major version. ' \
+        'Use `client.evaluate_flags(distinct_id, ...)` and call `flags.get_flag(key)` instead — ' \
+        'this consolidates flag evaluation into a single `/flags` request per incoming request.'
+      )
+      # Bypass the public `get_feature_flag_result` so the user only sees one deprecation warning.
+      result = _get_feature_flag_result(
+        key, distinct_id,
+        groups: groups, person_properties: person_properties, group_properties: group_properties,
+        only_evaluate_locally: only_evaluate_locally, send_feature_flag_events: send_feature_flag_events
       )
       result&.value
     end
 
-    # Returns both the feature flag value and payload in a single call.
-    # This method raises the $feature_flag_called event with the payload included.
+    # @deprecated Use {#evaluate_flags} and {FeatureFlagEvaluations#get_flag} /
+    #   {FeatureFlagEvaluations#get_flag_payload} instead.
+    def get_feature_flag_result(
+      key,
+      distinct_id,
+      groups: {},
+      person_properties: {},
+      group_properties: {},
+      only_evaluate_locally: false,
+      send_feature_flag_events: true
+    )
+      _emit_deprecation(
+        :get_feature_flag_result,
+        '`get_feature_flag_result` is deprecated and will be removed in a future major version. ' \
+        'Use `client.evaluate_flags(distinct_id, ...)` and call `flags.get_flag(key)` / ' \
+        '`flags.get_flag_payload(key)` instead — this consolidates flag evaluation into a single ' \
+        '`/flags` request per incoming request.'
+      )
+      _get_feature_flag_result(
+        key, distinct_id,
+        groups: groups, person_properties: person_properties, group_properties: group_properties,
+        only_evaluate_locally: only_evaluate_locally, send_feature_flag_events: send_feature_flag_events
+      )
+    end
+
+    # Evaluate feature flags for a distinct id and return a snapshot.
+    #
+    # The returned {PostHog::FeatureFlagEvaluations} can be queried with
+    # `is_enabled` / `get_flag` / `get_flag_payload`, narrowed with
+    # `only_accessed` / `only`, and passed to {#capture} via the `flags:` option
+    # to attach `$feature/<key>` and `$active_feature_flags` without an extra
+    # /flags request.
     #
-    # @param [String] key The key of the feature flag
     # @param [String] distinct_id The distinct id of the user
     # @param [Hash] groups
-    # @param [Hash] person_properties key-value pairs of properties to associate with the user.
+    # @param [Hash] person_properties key-value pairs of properties to associate with the user
     # @param [Hash] group_properties
-    # @param [Boolean] only_evaluate_locally
-    # @param [Boolean] send_feature_flag_events
-    #
-    # @return [FeatureFlagResult, nil] A FeatureFlagResult object containing the flag value and payload,
-    #   or nil if the flag evaluation returned nil
-    def get_feature_flag_result(
-      key,
+    # @param [Boolean] only_evaluate_locally Skip the remote /flags call entirely
+    # @param [Boolean] disable_geoip Stamped on captured access events
+    # @param [Array<String>] flag_keys When set, scopes the underlying /flags
+    #   request to only these flag keys (sent as `flag_keys_to_evaluate`).
+    #   Distinct from {FeatureFlagEvaluations#only}, which filters the
+    #   already-fetched snapshot in memory.
+    # @return [PostHog::FeatureFlagEvaluations]
+    def evaluate_flags(
       distinct_id,
       groups: {},
       person_properties: {},
       group_properties: {},
       only_evaluate_locally: false,
-      send_feature_flag_events: true
+      disable_geoip: nil,
+      flag_keys: nil
     )
+      host = _feature_flag_evaluations_host
+
+      if distinct_id.nil? || distinct_id.to_s.empty?
+        return FeatureFlagEvaluations.new(host: host, distinct_id: '', flags: {})
+      end
+
       person_properties, group_properties = add_local_person_and_group_properties(
-        distinct_id,
-        groups,
-        person_properties,
-        group_properties
+        distinct_id, groups, person_properties, group_properties
       )
-      feature_flag_response, flag_was_locally_evaluated, request_id, evaluated_at, feature_flag_error, payload =
-        @feature_flags_poller.get_feature_flag(
-          key,
-          distinct_id,
-          groups,
-          person_properties,
-          group_properties,
-          only_evaluate_locally
-        )
-      feature_flag_reported_key = "#{key}_#{feature_flag_response}"
 
-      if !@distinct_id_has_sent_flag_calls[distinct_id].include?(feature_flag_reported_key) && send_feature_flag_events
-        properties = {
-          '$feature_flag' => key,
-          '$feature_flag_response' => feature_flag_response,
-          'locally_evaluated' => flag_was_locally_evaluated
-        }
-        properties['$feature_flag_request_id'] = request_id if request_id
-        properties['$feature_flag_evaluated_at'] = evaluated_at if evaluated_at
-        properties['$feature_flag_error'] = feature_flag_error if feature_flag_error
+      records = {}
+      locally_evaluated_keys = Set.new
+      flag_keys_set = flag_keys&.to_set(&:to_s)
 
-        capture(
-          distinct_id: distinct_id,
-          event: '$feature_flag_called',
-          properties: properties,
-          groups: groups
+      @feature_flags_poller.load_feature_flags
+      poller_flags_by_key = @feature_flags_poller.feature_flags_by_key || {}
+
+      poller_flags_by_key.each do |key, definition|
+        next if flag_keys_set && !flag_keys_set.include?(key.to_s)
+
+        begin
+          match = @feature_flags_poller.send(
+            :_compute_flag_locally,
+            definition, distinct_id, groups, person_properties, group_properties
+          )
+        rescue PostHog::RequiresServerEvaluation, PostHog::InconclusiveMatchError, StandardError
+          next
+        end
+
+        next if match.nil?
+
+        records[key.to_s] = FeatureFlagEvaluations::EvaluatedFlagRecord.new(
+          key: key.to_s,
+          enabled: match.is_a?(String) || (match ? true : false),
+          variant: match.is_a?(String) ? match : nil,
+          payload: FeatureFlagResult.parse_payload(
+            @feature_flags_poller.send(:_compute_flag_payload_locally, key, match)
+          ),
+          id: definition[:id],
+          version: nil,
+          reason: FeatureFlagEvaluations::EVALUATED_LOCALLY_REASON,
+          locally_evaluated: true
         )
-        @distinct_id_has_sent_flag_calls[distinct_id] << feature_flag_reported_key
+        locally_evaluated_keys << key.to_s
       end
 
-      FeatureFlagResult.from_value_and_payload(key, feature_flag_response, payload)
+      request_id = nil
+      evaluated_at = nil
+      errors_while_computing = false
+      quota_limited = false
+
+      # Skip the remote `/flags` round-trip when the caller scoped the request
+      # to a fixed set of `flag_keys` and we've already resolved every one of
+      # them locally. Without `flag_keys` set, we can't know whether the server
+      # has flags we don't have definitions for, so we still hit `/flags`.
+      all_requested_flags_resolved_locally = flag_keys_set && (flag_keys_set - locally_evaluated_keys).empty?
+
+      if !only_evaluate_locally && !all_requested_flags_resolved_locally
+        begin
+          flags_response = @feature_flags_poller.get_flags(
+            distinct_id, groups, person_properties, group_properties, flag_keys, disable_geoip
+          )
+          request_id = flags_response[:requestId]
+          evaluated_at = flags_response[:evaluatedAt]
+          errors_while_computing = flags_response[:errorsWhileComputingFlags] == true
+          quota_limited = (flags_response[:quotaLimited] || []).include?('feature_flags')
+          remote_flags = flags_response[:flags] || {}
+          remote_flags.each do |key, ff|
+            key_str = key.to_s
+            next if locally_evaluated_keys.include?(key_str)
+
+            metadata = ff.metadata
+            reason = ff.reason
+            records[key_str] = FeatureFlagEvaluations::EvaluatedFlagRecord.new(
+              key: key_str,
+              enabled: ff.enabled ? true : false,
+              variant: ff.variant,
+              payload: FeatureFlagResult.parse_payload(ff.payload),
+              id: metadata ? metadata.id : nil,
+              version: metadata ? metadata.version : nil,
+              reason: reason ? (reason.description || reason.code) : nil,
+              locally_evaluated: false
+            )
+          end
+        rescue StandardError => e
+          @on_error&.call(-1, "Error evaluating flags remotely: #{e}")
+        end
+      end
+
+      FeatureFlagEvaluations.new(
+        host: host,
+        distinct_id: distinct_id,
+        flags: records,
+        groups: groups,
+        disable_geoip: disable_geoip,
+        request_id: request_id,
+        evaluated_at: evaluated_at,
+        flag_definitions_loaded_at: @feature_flags_poller.flag_definitions_loaded_at,
+        errors_while_computing: errors_while_computing,
+        quota_limited: quota_limited
+      )
     end
 
     # Returns all flags for a given user
@@ -457,6 +606,7 @@ module PostHog
     # @option [Hash] group_properties
     # @option [Boolean] only_evaluate_locally
     #
+    # @deprecated Use {#evaluate_flags} and {FeatureFlagEvaluations#get_flag_payload} instead.
     def get_feature_flag_payload(
       key,
       distinct_id,
@@ -466,6 +616,13 @@ module PostHog
       group_properties: {},
       only_evaluate_locally: false
     )
+      _emit_deprecation(
+        :get_feature_flag_payload,
+        '`get_feature_flag_payload` is deprecated and will be removed in a future major version. ' \
+        'Use `client.evaluate_flags(distinct_id, ...)` and call `flags.get_flag_payload(key)` ' \
+        'instead — this consolidates flag evaluation into a single `/flags` request per ' \
+        'incoming request.'
+      )
       person_properties, group_properties = add_local_person_and_group_properties(distinct_id, groups,
                                                                                   person_properties, group_properties)
       @feature_flags_poller.get_feature_flag_payload(key, distinct_id, match_value, groups, person_properties,
@@ -527,6 +684,84 @@ module PostHog
 
     private
 
+    # Shared by the legacy single-flag path ({#get_feature_flag_result}) and the
+    # snapshot's access-recording. Owns dedup-key construction, the
+    # per-distinct_id sent-flags cache, and the `$feature_flag_called` capture call.
+    def _capture_feature_flag_called_if_needed(
+      distinct_id: nil, key: nil, response: nil, properties: nil,
+      groups: nil, disable_geoip: nil
+    )
+      reported_key = "#{key}_#{response.nil? ? '::null::' : response}"
+      return if @distinct_id_has_sent_flag_calls[distinct_id].include?(reported_key)
+
+      msg = {
+        distinct_id: distinct_id,
+        event: '$feature_flag_called',
+        properties: properties
+      }
+      msg[:groups] = groups if groups
+      msg[:disable_geoip] = disable_geoip unless disable_geoip.nil?
+
+      capture(msg)
+      @distinct_id_has_sent_flag_calls[distinct_id] << reported_key
+    end
+
+    def _feature_flag_evaluations_host
+      @feature_flag_evaluations_host ||= FeatureFlagEvaluations::Host.new(
+        capture_flag_called_event_if_needed: method(:_capture_feature_flag_called_if_needed),
+        log_warning: ->(message) { logger.warn(message) }
+      )
+    end
+
+    # Implementation of {#get_feature_flag_result}, called by both the public
+    # method and the legacy `is_feature_enabled` / `get_feature_flag` paths so
+    # a single user-level call emits exactly one deprecation warning.
+    def _get_feature_flag_result(
+      key,
+      distinct_id,
+      groups: {},
+      person_properties: {},
+      group_properties: {},
+      only_evaluate_locally: false,
+      send_feature_flag_events: true
+    )
+      person_properties, group_properties = add_local_person_and_group_properties(
+        distinct_id, groups, person_properties, group_properties
+      )
+      feature_flag_response, flag_was_locally_evaluated, request_id, evaluated_at, feature_flag_error, payload =
+        @feature_flags_poller.get_feature_flag(
+          key, distinct_id, groups, person_properties, group_properties, only_evaluate_locally
+        )
+      if send_feature_flag_events
+        properties = {
+          '$feature_flag' => key,
+          '$feature_flag_response' => feature_flag_response,
+          'locally_evaluated' => flag_was_locally_evaluated
+        }
+        properties['$feature_flag_request_id'] = request_id if request_id
+        properties['$feature_flag_evaluated_at'] = evaluated_at if evaluated_at
+        properties['$feature_flag_error'] = feature_flag_error if feature_flag_error
+
+        _capture_feature_flag_called_if_needed(
+          distinct_id: distinct_id, key: key, response: feature_flag_response,
+          properties: properties, groups: groups
+        )
+      end
+
+      FeatureFlagResult.from_value_and_payload(key, feature_flag_response, payload)
+    end
+
+    # Emits a deprecation warning at most once per `(method_name, process)` pair.
+    # Ruby's `Kernel.warn(..., category: :deprecated)` is suppressed by default
+    # since 2.7.2; we emit without the category so messages reach users on a
+    # default Ruby setup. Standard logger configuration / `$VERBOSE = nil` / IO
+    # redirection still silences as expected.
+    def _emit_deprecation(method_name, message)
+      return unless @deprecation_emitted_for.add?(method_name)
+
+      Kernel.warn("[posthog-ruby] DEPRECATION: #{message}", uplevel: 2)
+    end
+
     # before_send should run immediately before the event is sent to the queue.
     # @param [Object] action The event to be sent to PostHog
     # @return [null, Object, nil] The processed event or nil if the event should not be sent
@@ -585,6 +820,22 @@ module PostHog
       raise ArgumentError, 'API key must be initialized' if @api_key.nil?
     end
 
+    def normalize_string_option(value, blank_as_nil: false)
+      return value unless value.is_a?(String)
+
+      normalized = value.strip
+      return nil if blank_as_nil && normalized.empty?
+
+      normalized
+    end
+
+    def normalize_host_option(host)
+      normalized = normalize_string_option(host)
+      return 'https://us.i.posthog.com' if normalized.nil? || normalized.empty?
+
+      normalized
+    end
+
     def ensure_worker_running
       return if worker_running?
 

data/lib/posthog/defaults.rb

@@ -5,7 +5,7 @@ module PostHog
     MAX_HASH_SIZE = 50_000
 
     module Request
-      HOST = 'app.posthog.com'
+      HOST = 'us.i.posthog.com'
       PORT = 443
       PATH = '/batch/'
       SSL = true

data/lib/posthog/feature_flag_evaluations.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

data/lib/posthog/feature_flag_result.rb

@@ -39,6 +39,10 @@ module PostHog
       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 @@ module PostHog
         payload
       end
     end
-
-    private_class_method :parse_payload
   end
 end

data/lib/posthog/feature_flags.rb

@@ -46,6 +46,7 @@ module PostHog
       @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 @@ module PostHog
       _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 @@ module PostHog
       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,11 +1130,12 @@ module PostHog
       @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
 
     def _request_feature_flag_definitions(etag: nil)
-      uri = URI("#{@host}/api/feature_flag/local_evaluation")
+      uri = URI("#{@host}/flags/definitions")
       uri.query = URI.encode_www_form([['token', @project_api_key], %w[send_cohorts true]])
       req = Net::HTTP::Get.new(uri)
       req['Authorization'] = "Bearer #{@personal_api_key}"

data/lib/posthog/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module PostHog
-  VERSION = '3.6.4'
+  VERSION = '3.7.0'
 end

data/lib/posthog.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: posthog-ruby
 version: !ruby/object:Gem::Version
-  version: 3.6.4
+  version: 3.7.0
 platform: ruby
 authors:
 - ''
@@ -41,6 +41,7 @@ files:
 - lib/posthog/exception_capture.rb
 - lib/posthog/feature_flag.rb
 - lib/posthog/feature_flag_error.rb
+- lib/posthog/feature_flag_evaluations.rb
 - lib/posthog/feature_flag_result.rb
 - lib/posthog/feature_flags.rb
 - lib/posthog/field_parser.rb