posthog-ruby 3.3.3 → 3.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9a8d4402eef3a161a1c76c7e7e2349356741011cc6ead4acde7bd31ef437e568
-  data.tar.gz: b9ad05adb1b5e3aea9849bf0bbceceef0d22f9724561e8f3a4a3e39f4ed104e8
+  metadata.gz: 3d0dcf1963eb64bad7469885f038127408c5815a5cad8b5d338f220b2fac5263
+  data.tar.gz: 970b55467f0594423d57c36c9c546bb65ddcb68041ab11b4bea7ded9e25928bb
 SHA512:
-  metadata.gz: 055501a8e3ea62cfd321adee64297023338deb455ed59746632c0051179e3b3f6e733f1f7126eb612e5c381aa8bf8653b51ae2d15a1be938d80d05f8e0b06e3f
-  data.tar.gz: c4dd9ae85bafbec60209c8aff9329f79585b99deb8ffe1624397df73d930d54c40ab5fefaac2de9b75adee80c242f98d26428b61f4155206ce7632517303241b
+  metadata.gz: 5cfebda482c0b67e1c12fce9cae0081e182eb1d92577a7f07405ebff817635c31f70a780f4416b5de0d4bdecff7393852c9a8f8d44e34f5d8edf80f0db4434b3
+  data.tar.gz: 1ec51e9f018c98cdc8d00b86a0c11613f48544d6ebbeaebe5d98c5084861dcea0ba63be12f506d01a3493db87a9c9fe0f9c1c339d6ed286c7845f5da8bc4db26

data/lib/posthog/client.rb

@@ -279,38 +279,77 @@ module PostHog
       only_evaluate_locally: false,
       send_feature_flag_events: true
     )
-      person_properties, group_properties = add_local_person_and_group_properties(
+      result = get_feature_flag_result(
+        key,
         distinct_id,
-        groups,
-        person_properties,
-        group_properties
+        groups: groups,
+        person_properties: person_properties,
+        group_properties: group_properties,
+        only_evaluate_locally: only_evaluate_locally,
+        send_feature_flag_events: send_feature_flag_events
       )
-      feature_flag_response, flag_was_locally_evaluated, request_id = @feature_flags_poller.get_feature_flag(
-        key,
+      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,
         groups,
         person_properties,
-        group_properties,
-        only_evaluate_locally
+        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
+
         capture(
-          {
-            distinct_id: distinct_id,
-            event: '$feature_flag_called',
-            properties: {
-              '$feature_flag' => key,
-              '$feature_flag_response' => feature_flag_response,
-              'locally_evaluated' => flag_was_locally_evaluated
-            }.merge(request_id ? { '$feature_flag_request_id' => request_id } : {}),
-            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
@@ -336,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
@@ -385,7 +427,9 @@ module PostHog
         distinct_id, groups, person_properties, group_properties, only_evaluate_locally
       )
 
-      response.delete(:requestId) # remove internal information.
+      # Remove internal information
+      response.delete(:requestId)
+      response.delete(:evaluatedAt)
       response
     end
 

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

@@ -43,6 +43,7 @@ module PostHog
       @feature_flag_request_timeout_seconds = feature_flag_request_timeout_seconds
       @on_error = on_error || proc { |status, error| }
       @quota_limited = Concurrent::AtomicBoolean.new(false)
+      @flags_etag = Concurrent::AtomicReference.new(nil)
       @task =
         Concurrent::TimerTask.new(
           execution_interval: polling_interval
@@ -140,6 +141,7 @@ module PostHog
           [key, FeatureFlag.from_value_and_payload(key, value, flags_response[:featureFlagPayloads][key])]
         end
       end
+
       flags_response
     end
 
@@ -167,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}"
@@ -190,28 +187,50 @@ module PostHog
       flag_was_locally_evaluated = !response.nil?
 
       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]
+      [response, flag_was_locally_evaluated, request_id, evaluated_at, feature_flag_error, payload]
     end
 
     def get_all_flags(
@@ -252,6 +271,7 @@ module PostHog
       payloads = {}
       fallback_to_server = @feature_flags.empty?
       request_id = nil # Only for /flags requests
+      evaluated_at = nil # Only for /flags requests
 
       @feature_flags.each do |flag|
         match_value = _compute_flag_locally(flag, distinct_id, groups, person_properties, group_properties)
@@ -265,23 +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]
           end
         rescue StandardError => e
           @on_error.call(-1, "Error computing flag remotely: #{e}")
@@ -292,7 +321,11 @@ module PostHog
       {
         featureFlags: flags,
         featureFlagPayloads: payloads,
-        requestId: request_id
+        requestId: request_id,
+        evaluatedAt: evaluated_at,
+        errorsWhileComputingFlags: errors_while_computing,
+        quotaLimited: quota_limited,
+        status: status_code
       }
     end
 
@@ -834,12 +867,20 @@ module PostHog
 
     def _load_feature_flags
       begin
-        res = _request_feature_flag_definitions
+        res = _request_feature_flag_definitions(etag: @flags_etag.value)
       rescue StandardError => e
         @on_error.call(-1, e.to_s)
         return
       end
 
+      # Handle 304 Not Modified - flags haven't changed, skip processing
+      # Only update ETag if the 304 response includes one
+      if res[:not_modified]
+        @flags_etag.value = res[:etag] if res[:etag]
+        logger.debug '[FEATURE FLAGS] Flags not modified (304), using cached data'
+        return
+      end
+
       # Handle quota limits with 402 status
       if res.is_a?(Hash) && res[:status] == 402
         logger.warn(
@@ -856,6 +897,9 @@ module PostHog
       end
 
       if res.key?(:flags)
+        # Only update ETag on successful responses with flag data
+        @flags_etag.value = res[:etag]
+
         @feature_flags = res[:flags] || []
         @feature_flags_by_key = {}
         @feature_flags.each do |flag|
@@ -871,13 +915,14 @@ module PostHog
       end
     end
 
-    def _request_feature_flag_definitions
+    def _request_feature_flag_definitions(etag: nil)
       uri = URI("#{@host}/api/feature_flag/local_evaluation")
       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}"
+      req['If-None-Match'] = etag if etag
 
-      _request(uri, req)
+      _request(uri, req, nil, include_etag: true)
     end
 
     def _request_feature_flag_evaluation(data = {})
@@ -901,7 +946,7 @@ module PostHog
     end
 
     # rubocop:disable Lint/ShadowedException
-    def _request(uri, request_object, timeout = nil)
+    def _request(uri, request_object, timeout = nil, include_etag: false)
       request_object['User-Agent'] = "posthog-ruby#{PostHog::VERSION}"
       request_timeout = timeout || 10
 
@@ -913,16 +958,28 @@ module PostHog
           read_timeout: request_timeout
         ) do |http|
           res = http.request(request_object)
+          status_code = res.code.to_i
+          etag = include_etag ? res['ETag'] : nil
+
+          # Handle 304 Not Modified - return special response indicating no change
+          if status_code == 304
+            logger.debug("#{request_object.method} #{_mask_tokens_in_url(uri.to_s)} returned 304 Not Modified")
+            return { not_modified: true, etag: etag, status: status_code }
+          end
 
           # Parse response body to hash
           begin
             response = JSON.parse(res.body, { symbolize_names: true })
-            # Only add status if response is a hash
-            response = response.merge({ status: res.code.to_i }) if response.is_a?(Hash)
+            # Only add status (and etag if requested) if response is a hash
+            extra_fields = { status: status_code }
+            extra_fields[:etag] = etag if include_etag
+            response = response.merge(extra_fields) if response.is_a?(Hash)
             return response
           rescue JSON::ParserError
             # Handle case when response isn't valid JSON
-            return { error: 'Invalid JSON response', body: res.body, status: res.code.to_i }
+            error_response = { error: 'Invalid JSON response', body: res.body, status: status_code }
+            error_response[:etag] = etag if include_etag
+            return error_response
           end
         end
       rescue Timeout::Error,
@@ -939,5 +996,9 @@ module PostHog
       end
     end
     # rubocop:enable Lint/ShadowedException
+
+    def _mask_tokens_in_url(url)
+      url.gsub(/token=([^&]{10})[^&]*/, 'token=\1...')
+    end
   end
 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.3.3'
+  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.3.3
+  version: 3.5.0
 platform: ruby
 authors:
 - ''
 bindir: bin
 cert_chain: []
-date: 2025-10-22 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: []