posthog-ruby 3.4.0 → 3.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9e99287bd9fe6eb8969c2481c0380c2a6eba12709de5f5189a053cb9ba5ca255
-  data.tar.gz: 78b496c5feb9c8cb222393ababa36d0f6fd81c18e603469b0633ac3fcdbfd639
+  metadata.gz: 3d0dcf1963eb64bad7469885f038127408c5815a5cad8b5d338f220b2fac5263
+  data.tar.gz: 970b55467f0594423d57c36c9c546bb65ddcb68041ab11b4bea7ded9e25928bb
 SHA512:
-  metadata.gz: dc1c52ff0243af441d895c05199067347931f0bf50a21ba897a3fb75640cb954ec66c79dddb29fb92338479014f3a7f42543a1ef651ebdcbd7fe6845ff9e9002
-  data.tar.gz: e46932963b504e54fe4590db73e1956611190b2ab16a1f04ffff5877c01b1e71a2dafc5f9c373361b69bb5f63532d1400c244580ac3c229ced006b350880eef5
+  metadata.gz: 5cfebda482c0b67e1c12fce9cae0081e182eb1d92577a7f07405ebff817635c31f70a780f4416b5de0d4bdecff7393852c9a8f8d44e34f5d8edf80f0db4434b3
+  data.tar.gz: 1ec51e9f018c98cdc8d00b86a0c11613f48544d6ebbeaebe5d98c5084861dcea0ba63be12f506d01a3493db87a9c9fe0f9c1c339d6ed286c7845f5da8bc4db26

data/lib/posthog/client.rb

@@ -278,6 +278,40 @@ module PostHog
       group_properties: {},
       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
+      )
+      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.
+    #
+    # @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] 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,
+      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,
@@ -285,7 +319,7 @@ module PostHog
         person_properties,
         group_properties
       )
-      feature_flag_response, flag_was_locally_evaluated, request_id, evaluated_at =
+      feature_flag_response, flag_was_locally_evaluated, request_id, evaluated_at, feature_flag_error, payload =
         @feature_flags_poller.get_feature_flag(
           key,
           distinct_id,
@@ -294,8 +328,8 @@ module PostHog
           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,
@@ -304,18 +338,18 @@ module PostHog
         }
         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(
-          {
-            distinct_id: distinct_id,
-            event: '$feature_flag_called',
-            properties: properties,
-            groups: groups
-          }
+          distinct_id: distinct_id,
+          event: '$feature_flag_called',
+          properties: properties,
+          groups: groups
         )
         @distinct_id_has_sent_flag_calls[distinct_id] << feature_flag_reported_key
       end
-      feature_flag_response
+
+      FeatureFlagResult.from_value_and_payload(key, feature_flag_response, payload)
     end
 
     # Returns all flags for a given user
@@ -341,6 +375,9 @@ module PostHog
 
     # Returns payload for a given feature flag
     #
+    # @deprecated Use {#get_feature_flag_result} instead, which returns both the flag value and payload
+    #   and properly raises the $feature_flag_called event.
+    #
     # @param [String] key The key of the feature flag
     # @param [String] distinct_id The distinct id of the user
     # @option [String or boolean] match_value The value of the feature flag to be matched

data/lib/posthog/feature_flag_error.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module PostHog
+  # Error type constants for the $feature_flag_error property.
+  #
+  # These values are sent in analytics events to track flag evaluation failures.
+  # They should not be changed without considering impact on existing dashboards
+  # and queries that filter on these values.
+  #
+  # Error values:
+  #   ERRORS_WHILE_COMPUTING: Server returned errorsWhileComputingFlags=true
+  #   FLAG_MISSING: Requested flag not in API response
+  #   QUOTA_LIMITED: Rate/quota limit exceeded
+  #   TIMEOUT: Request timed out
+  #   CONNECTION_ERROR: Network connectivity issue
+  #   UNKNOWN_ERROR: Unexpected exceptions
+  #
+  # For API errors with status codes, use the api_error() method which returns
+  # a string like "api_error_500".
+  class FeatureFlagError
+    ERRORS_WHILE_COMPUTING = 'errors_while_computing_flags'
+    FLAG_MISSING = 'flag_missing'
+    QUOTA_LIMITED = 'quota_limited'
+    TIMEOUT = 'timeout'
+    CONNECTION_ERROR = 'connection_error'
+    UNKNOWN_ERROR = 'unknown_error'
+
+    # Generate API error string with status code.
+    #
+    # @param status [Integer, String] The HTTP status code
+    # @return [String] Error string in format "api_error_STATUS"
+    def self.api_error(status)
+      "api_error_#{status.to_s.downcase}"
+    end
+  end
+end

data/lib/posthog/feature_flag_result.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module PostHog
+  # Represents the result of a feature flag evaluation
+  # containing both the flag value and payload
+  class FeatureFlagResult
+    attr_reader :key, :variant, :payload
+
+    def initialize(key:, enabled:, variant: nil, payload: nil)
+      @key = key
+      @enabled = enabled
+      @variant = variant
+      @payload = payload
+    end
+
+    # Returns the effective value of the feature flag
+    # variant if present, otherwise enabled status
+    def value
+      @variant || @enabled
+    end
+
+    # Returns whether or not the feature flag evaluated as enabled
+    def enabled?
+      @enabled
+    end
+
+    # Factory method to create from flag value and payload
+    def self.from_value_and_payload(key, value, payload)
+      return nil if value.nil?
+
+      parsed_payload = parse_payload(payload)
+
+      if value.is_a?(String)
+        new(key: key, enabled: true, variant: value, payload: parsed_payload)
+      else
+        new(key: key, enabled: value, payload: parsed_payload)
+      end
+    end
+
+    def self.parse_payload(payload)
+      return nil if payload.nil?
+      return payload unless payload.is_a?(String)
+      return nil if payload.empty?
+
+      begin
+        JSON.parse(payload)
+      rescue JSON::ParserError
+        payload
+      end
+    end
+
+    private_class_method :parse_payload
+  end
+end

data/lib/posthog/feature_flags.rb

@@ -169,18 +169,13 @@ module PostHog
       end
 
       response = nil
-      feature_flag = nil
-
-      @feature_flags.each do |flag|
-        if key == flag[:key]
-          feature_flag = flag
-          break
-        end
-      end
+      payload = nil
+      feature_flag = @feature_flags_by_key&.[](key)
 
       unless feature_flag.nil?
         begin
           response = _compute_flag_locally(feature_flag, distinct_id, groups, person_properties, group_properties)
+          payload = _compute_flag_payload_locally(key, response) unless response.nil?
           logger.debug "Successfully computed flag locally: #{key} -> #{response}"
         rescue RequiresServerEvaluation, InconclusiveMatchError => e
           logger.debug "Failed to compute flag #{key} locally: #{e}"
@@ -193,29 +188,49 @@ module PostHog
 
       request_id = nil
       evaluated_at = nil
+      feature_flag_error = nil
 
       if !flag_was_locally_evaluated && !only_evaluate_locally
         begin
+          errors = []
           flags_data = get_all_flags_and_payloads(distinct_id, groups, person_properties, group_properties,
                                                   only_evaluate_locally, true)
           if flags_data.key?(:featureFlags)
             flags = stringify_keys(flags_data[:featureFlags] || {})
+            payloads = stringify_keys(flags_data[:featureFlagPayloads] || {})
             request_id = flags_data[:requestId]
             evaluated_at = flags_data[:evaluatedAt]
           else
             logger.debug "Missing feature flags key: #{flags_data.to_json}"
             flags = {}
+            payloads = {}
           end
 
+          status = flags_data[:status]
+          errors << FeatureFlagError.api_error(status) if status && status >= 400
+          errors << FeatureFlagError::ERRORS_WHILE_COMPUTING if flags_data[:errorsWhileComputingFlags]
+          errors << FeatureFlagError::QUOTA_LIMITED if flags_data[:quotaLimited]&.include?('feature_flags')
+          errors << FeatureFlagError::FLAG_MISSING unless flags.key?(key.to_s)
+
           response = flags[key]
           response = false if response.nil?
+          payload = payloads[key]
+          feature_flag_error = errors.join(',') unless errors.empty?
+
           logger.debug "Successfully computed flag remotely: #{key} -> #{response}"
+        rescue Timeout::Error => e
+          @on_error.call(-1, "Timeout while fetching flags remotely: #{e}")
+          feature_flag_error = FeatureFlagError::TIMEOUT
+        rescue Errno::ECONNRESET, Errno::ECONNREFUSED, EOFError, SocketError => e
+          @on_error.call(-1, "Connection error while fetching flags remotely: #{e}")
+          feature_flag_error = FeatureFlagError::CONNECTION_ERROR
         rescue StandardError => e
           @on_error.call(-1, "Error computing flag remotely: #{e}. #{e.backtrace.join("\n")}")
+          feature_flag_error = FeatureFlagError::UNKNOWN_ERROR
         end
       end
 
-      [response, flag_was_locally_evaluated, request_id, evaluated_at]
+      [response, flag_was_locally_evaluated, request_id, evaluated_at, feature_flag_error, payload]
     end
 
     def get_all_flags(
@@ -270,24 +285,32 @@ module PostHog
         fallback_to_server = true
       end
 
+      errors_while_computing = false
+      quota_limited = nil
+      status_code = nil
+
       if fallback_to_server && !only_evaluate_locally
         begin
           flags_and_payloads = get_flags(distinct_id, groups, person_properties, group_properties)
+          errors_while_computing = flags_and_payloads[:errorsWhileComputingFlags] || false
+          quota_limited = flags_and_payloads[:quotaLimited]
+          status_code = flags_and_payloads[:status]
 
           unless flags_and_payloads.key?(:featureFlags)
             raise StandardError, "Error flags response: #{flags_and_payloads}"
           end
 
+          request_id = flags_and_payloads[:requestId]
+          evaluated_at = flags_and_payloads[:evaluatedAt]
+
           # Check if feature_flags are quota limited
-          if flags_and_payloads[:quotaLimited]&.include?('feature_flags')
+          if quota_limited&.include?('feature_flags')
             logger.warn '[FEATURE FLAGS] Quota limited for feature flags'
             flags = {}
             payloads = {}
           else
             flags = stringify_keys(flags_and_payloads[:featureFlags] || {})
             payloads = stringify_keys(flags_and_payloads[:featureFlagPayloads] || {})
-            request_id = flags_and_payloads[:requestId]
-            evaluated_at = flags_and_payloads[:evaluatedAt]
           end
         rescue StandardError => e
           @on_error.call(-1, "Error computing flag remotely: #{e}")
@@ -299,7 +322,10 @@ module PostHog
         featureFlags: flags,
         featureFlagPayloads: payloads,
         requestId: request_id,
-        evaluatedAt: evaluated_at
+        evaluatedAt: evaluated_at,
+        errorsWhileComputingFlags: errors_while_computing,
+        quotaLimited: quota_limited,
+        status: status_code
       }
     end
 

data/lib/posthog/logging.rb

@@ -41,8 +41,8 @@ module PostHog
         return @logger if @logger
 
         base_logger =
-          if defined?(Rails)
-            Rails.logger
+          if defined?(::Rails)
+            ::Rails.logger
           else
             logger = Logger.new $stdout
             logger.progname = 'PostHog'

data/lib/posthog/version.rb

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

data/lib/posthog.rb

@@ -10,3 +10,5 @@ require 'posthog/transport'
 require 'posthog/response'
 require 'posthog/logging'
 require 'posthog/exception_capture'
+require 'posthog/feature_flag_error'
+require 'posthog/feature_flag_result'

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: posthog-ruby
 version: !ruby/object:Gem::Version
-  version: 3.4.0
+  version: 3.5.0
 platform: ruby
 authors:
 - ''
 bindir: bin
 cert_chain: []
-date: 2025-12-04 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: concurrent-ruby
@@ -40,6 +40,8 @@ files:
 - lib/posthog/defaults.rb
 - lib/posthog/exception_capture.rb
 - lib/posthog/feature_flag.rb
+- lib/posthog/feature_flag_error.rb
+- lib/posthog/feature_flag_result.rb
 - lib/posthog/feature_flags.rb
 - lib/posthog/field_parser.rb
 - lib/posthog/logging.rb
@@ -70,7 +72,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.6
+rubygems_version: 4.0.3
 specification_version: 4
 summary: PostHog library
 test_files: []