posthog-ruby 3.8.0 → 3.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a21b0cf7196c00dff9b6ad23c7ee12e54b9984b9e2e7639d0f4371f419de80c2
-  data.tar.gz: 643244ae98a7d9879e64c905133aafba69e0e5e710e49766bdd38db24f28032d
+  metadata.gz: 3f033107e265e546dca78bfbf8f6adb3552e5803ac7dec0bf822afb814e7658d
+  data.tar.gz: efe43054d73bfce034973fc12a01301f3b935cfacb1e7e86358332a9879f8911
 SHA512:
-  metadata.gz: f3e4329938912befad0b58c463dd5e82ff606e381c4f306e4a1d2e509963a613cff41acc5af853cd7a4f01033af283ee7a5f77324dd31e58c605b3f84a4d9d1b
-  data.tar.gz: e331c6d025c837c2c2764d4dcccbf61dd0c33e53f55dc9a5fbaf6a2628852c86f290dbf5c8c6c375e178d13ba839126e5c472e3bce1769e118d27b28f8410f17
+  metadata.gz: e1e3e4e0e5712ab73c8c0c11ce5a5869df0dc95f293b151f81d7fc715844e36867d3aeed393427494789bf8b35f2d96f42c703085d6be405fe1168feaa7daa82
+  data.tar.gz: 1347919dcaeda0b7ad237964ae00acc34d4b6e4b9273d3335ce6e4666f09471d8d8fefb53c13d51e345cf3b7c8e467b813b14cbbdad74062dbabbc12fbeadc26

data/lib/posthog/client.rb

@@ -14,6 +14,7 @@ require 'posthog/feature_flags'
 require 'posthog/feature_flag_evaluations'
 require 'posthog/send_feature_flags_options'
 require 'posthog/exception_capture'
+require 'posthog/internal/context'
 
 module PostHog
   class Client
@@ -185,9 +186,13 @@ module PostHog
     #                             events in PostHog are deduplicated by the
     #                             combination of teamId, timestamp date,
     #                             event name, distinct id, and UUID
+    # @note If `:distinct_id` is omitted, request/context distinct_id is used when
+    #   available; otherwise a UUID is generated and the event is marked personless
+    #   with `$process_person_profile: false`.
     # @macro common_attrs
     def capture(attrs)
       symbolize_keys! attrs
+      enrich_capture_attrs_with_context(attrs)
 
       # Precedence: an explicit `flags` snapshot always wins, regardless of
       # `send_feature_flags`. The snapshot guarantees the event carries the same
@@ -260,7 +265,8 @@ module PostHog
     # Captures an exception as an event
     #
     # @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 [String] distinct_id The ID for the user (optional, defaults to request/context distinct_id
+    #   or a generated UUID)
     # @param [Hash] additional_properties Additional properties to include with the exception event (optional)
     # @param [PostHog::FeatureFlagEvaluations] flags A snapshot returned by {#evaluate_flags}.
     #   Forwarded to the inner {#capture} call so the captured `$exception` event carries the
@@ -270,12 +276,8 @@ module PostHog
 
       return if exception_info.nil?
 
-      no_distinct_id_was_provided = distinct_id.nil?
-      distinct_id ||= SecureRandom.uuid
-
       properties = { '$exception_list' => [exception_info] }
       properties.merge!(additional_properties) if additional_properties && !additional_properties.empty?
-      properties['$process_person_profile'] = false if no_distinct_id_was_provided
 
       event_data = {
         distinct_id: distinct_id,
@@ -364,15 +366,15 @@ module PostHog
       !!response
     end
 
-    # @param [String] flag_key The unique flag key of the feature flag
+    # @param [String, Symbol] flag_key The unique flag key of the feature flag
     # @return [String] The decrypted value of the feature flag payload
     def get_remote_config_payload(flag_key)
-      @feature_flags_poller.get_remote_config_payload(flag_key)
+      @feature_flags_poller.get_remote_config_payload(flag_key.to_s)
     end
 
     # Returns whether the given feature flag is enabled for the given user or not
     #
-    # @param [String] key The key of the feature flag
+    # @param [String, Symbol] 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.
@@ -455,7 +457,7 @@ module PostHog
     # @param [Hash] group_properties
     # @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
+    # @param [Array<String, Symbol>] 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.
@@ -598,7 +600,7 @@ module PostHog
     # @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, Symbol] 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
     # @option [Hash] groups
@@ -623,6 +625,7 @@ module PostHog
         'instead — this consolidates flag evaluation into a single `/flags` request per ' \
         'incoming request.'
       )
+      key = key.to_s
       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,
@@ -684,6 +687,39 @@ module PostHog
 
     private
 
+    def enrich_capture_attrs_with_context(attrs)
+      context = Internal::Context.current
+      explicit_properties = attrs[:properties]
+      properties_are_hash = explicit_properties.nil? || explicit_properties.is_a?(Hash)
+      context_properties = context&.properties || {}
+      if properties_are_hash
+        attrs[:properties] = Internal::Context.merge_properties(context_properties, explicit_properties || {})
+      end
+
+      return if present_id?(attrs[:distinct_id])
+
+      if present_id?(context&.distinct_id)
+        attrs[:distinct_id] = context.distinct_id
+        return
+      end
+
+      attrs[:distinct_id] = SecureRandom.uuid
+      return unless properties_are_hash
+      return if property_key?(explicit_properties, '$process_person_profile')
+
+      attrs[:properties]['$process_person_profile'] = false
+    end
+
+    def present_id?(value)
+      !(value.nil? || (value.is_a?(String) && value.empty?))
+    end
+
+    def property_key?(properties, key)
+      return false unless properties.is_a?(Hash)
+
+      properties.key?(key) || properties.key?(key.to_sym)
+    end
+
     # 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.
@@ -725,6 +761,7 @@ module PostHog
       only_evaluate_locally: false,
       send_feature_flag_events: true
     )
+      key = key.to_s
       person_properties, group_properties = add_local_person_and_group_properties(
         distinct_id, groups, person_properties, group_properties
       )

data/lib/posthog/feature_flags.rb

@@ -125,6 +125,7 @@ module PostHog
 
     def get_flags(distinct_id, groups = {}, person_properties = {}, group_properties = {}, flag_keys = nil,
                   disable_geoip = nil)
+      flag_keys = flag_keys.map(&:to_s) if flag_keys.is_a?(Array)
       request_data = {
         distinct_id: distinct_id,
         groups: groups,
@@ -160,7 +161,7 @@ module PostHog
     end
 
     def get_remote_config_payload(flag_key)
-      _request_remote_config_payload(flag_key)
+      _request_remote_config_payload(flag_key.to_s)
     end
 
     def get_feature_flag(
@@ -171,6 +172,8 @@ module PostHog
       group_properties = {},
       only_evaluate_locally = false
     )
+      key = key.to_s
+
       # make sure they're loaded on first run
       load_feature_flags
 
@@ -363,6 +366,8 @@ module PostHog
       group_properties = {},
       only_evaluate_locally = false
     )
+      key = key.to_s
+
       if match_value.nil?
         match_value = get_feature_flag(
           key,
@@ -923,6 +928,7 @@ module PostHog
     def _compute_flag_payload_locally(key, match_value)
       return nil if @feature_flags_by_key.nil?
 
+      key = key.to_s
       response = nil
       if [true, false].include? match_value
         response = @feature_flags_by_key.dig(key, :filters, :payloads, match_value.to_s.to_sym)

data/lib/posthog/internal/context.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+module PostHog
+  module Internal
+    # Internal request/fiber-local context applied to capture calls.
+    # Uses Rails' isolated execution state when available, otherwise falls back
+    # to thread-local storage in the core SDK.
+    #
+    # This is intentionally not exposed as a public SDK API in Ruby yet. It exists
+    # to let framework integrations such as posthog-rails propagate request-scoped
+    # tracing headers to regular capture and exception events without making the
+    # server-side SDK globally stateful per user.
+    class Context
+      STORAGE_KEY = :posthog_context
+
+      attr_reader :distinct_id, :session_id, :properties
+
+      def initialize(distinct_id: nil, session_id: nil, properties: {})
+        @distinct_id = distinct_id
+        @session_id = session_id
+        @properties = properties ? properties.dup : {}
+        apply_session_property!
+      end
+
+      def self.current
+        if defined?(ActiveSupport::IsolatedExecutionState)
+          ActiveSupport::IsolatedExecutionState[STORAGE_KEY]
+        else
+          Thread.current[STORAGE_KEY]
+        end
+      end
+
+      def self.current=(context)
+        if defined?(ActiveSupport::IsolatedExecutionState)
+          ActiveSupport::IsolatedExecutionState[STORAGE_KEY] = context
+        else
+          Thread.current[STORAGE_KEY] = context
+        end
+      end
+
+      def self.with_context(data = nil, fresh: false, **kwargs)
+        previous_context = current
+        raise ArgumentError, 'with_context requires a block' unless block_given?
+
+        self.current = resolve(merge_data_and_kwargs(data, kwargs), previous_context, fresh: fresh)
+        yield
+      ensure
+        self.current = previous_context
+      end
+
+      def self.resolve(data, parent, fresh: false)
+        data = normalize_data(data)
+
+        parent_properties = fresh || parent.nil? ? {} : parent.properties
+        properties = merge_properties(parent_properties, data[:properties] || {})
+        if data[:session_id] && !session_property_key?(data[:properties])
+          properties.delete('$session_id')
+          properties.delete(:$session_id)
+        end
+
+        new(
+          distinct_id: data[:distinct_id] || (fresh || parent.nil? ? nil : parent.distinct_id),
+          session_id: data[:session_id] || (fresh || parent.nil? ? nil : parent.session_id),
+          properties: properties
+        )
+      end
+      private_class_method :resolve
+
+      def self.merge_data_and_kwargs(data, kwargs)
+        data ||= {}
+        raise ArgumentError, 'context data must be a Hash' unless data.is_a?(Hash)
+
+        data.merge(kwargs)
+      end
+      private_class_method :merge_data_and_kwargs
+
+      def self.merge_properties(base, overrides)
+        merged = (base || {}).dup
+        (overrides || {}).each do |key, value|
+          merged.delete(key.to_s) if key.is_a?(Symbol)
+          merged.delete(key.to_sym) if key.is_a?(String)
+          merged[key] = value
+        end
+        merged
+      end
+
+      def self.normalize_data(data)
+        data ||= {}
+        raise ArgumentError, 'context data must be a Hash' unless data.is_a?(Hash)
+
+        properties = data[:properties] || data['properties'] || {}
+        raise ArgumentError, 'context properties must be a Hash' unless properties.is_a?(Hash)
+
+        {
+          distinct_id: data[:distinct_id] || data['distinct_id'] || data[:distinctId] || data['distinctId'],
+          session_id: data[:session_id] || data['session_id'] || data[:sessionId] || data['sessionId'],
+          properties: properties
+        }
+      end
+      private_class_method :normalize_data
+
+      def self.session_property_key?(properties)
+        return false unless properties.is_a?(Hash)
+
+        properties.key?('$session_id') || properties.key?(:$session_id)
+      end
+      private_class_method :session_property_key?
+
+      def apply_session_property!
+        return if session_id.nil? || properties.key?('$session_id') || properties.key?(:$session_id)
+
+        properties['$session_id'] = session_id
+      end
+      private :apply_session_property!
+    end
+  end
+
+  private_constant :Internal
+end

data/lib/posthog/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: posthog-ruby
 version: !ruby/object:Gem::Version
-  version: 3.8.0
+  version: 3.9.0
 platform: ruby
 authors:
 - ''
@@ -46,6 +46,7 @@ files:
 - lib/posthog/feature_flags.rb
 - lib/posthog/field_parser.rb
 - lib/posthog/flag_definition_cache.rb
+- lib/posthog/internal/context.rb
 - lib/posthog/logging.rb
 - lib/posthog/message_batch.rb
 - lib/posthog/noop_worker.rb