posthog-ruby 3.8.1 → 3.9.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4400cef0c43dd5e79c18f38712b6f0033271f798ad8f97362338516ab491185a
-  data.tar.gz: c789f72bcd04df210a74e79d9069e20a5a7f02b0b9b48eae344f58a33c348c8e
+  metadata.gz: 1388daa77d143c2822f15642b375b1e833a893d86677337d0d8bfc88875b364c
+  data.tar.gz: 2e71adb4fdc958bd8793515dbb3317652d9e811166678e7e38c57e57a85f3a08
 SHA512:
-  metadata.gz: fc6f2f8cfd188881c9aec1ab5867bf555ebfc8fdf12f87e2fb086884e75968e268df8346b1463a563bb48529f6f7c6326366718885c6e6584aa140ff5aa15f87
-  data.tar.gz: 7b6c516b339b0beaa8a0980d5e1d02027e826065f6bb28c85817344227cced2500b95e359bfe8955af952f553dc9b6cee958be8ffe2f52629d1bd1cf3df5e6f6
+  metadata.gz: a3ab6ee23fabf6375facb994ed3a16de3ec21ec53c88da0121fe3158d9b6552127d081124bb02870ca0b04d47bd2df4a79b7a95c45d8991095e2a4cbdfc63d09
+  data.tar.gz: ae04e209088f84ccb2760f0dc5fc3760cfb25e2ecd452201cf16b5432e4761acd63ef9471fc87cf88e21a1d16ce744191ea7ed6a445b2544fcf3e3a0f2f1040a

data/lib/posthog/backoff_policy.rb

@@ -3,10 +3,13 @@
 require 'posthog/defaults'
 
 module PostHog
+  # Retry backoff policy used by the SDK transport.
+  #
+  # @api private
   class BackoffPolicy
     include PostHog::Defaults::BackoffPolicy
 
-    # @param [Hash] opts
+    # @param opts [Hash]
     # @option opts [Numeric] :min_timeout_ms The minimum backoff timeout
     # @option opts [Numeric] :max_timeout_ms The maximum backoff timeout
     # @option opts [Numeric] :multiplier The value to multiply the current

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
@@ -49,29 +50,28 @@ module PostHog
       end
     end
 
-    # @param [Hash] opts
-    # @option opts [String] :api_key Your project's api_key
-    # @option opts [String] :personal_api_key Your personal API key
-    # @option opts [FixNum] :max_queue_size Maximum number of calls to be
-    #   remain queued. Defaults to 10_000.
-    # @option opts [Bool] :test_mode +true+ if messages should remain
-    #   queued for testing. Defaults to +false+.
-    # @option opts [Bool] :sync_mode +true+ to send events synchronously
-    #   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://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.
-    #   Measured in seconds, defaults to 3.
-    # @option opts [Proc] :before_send A block that receives the event hash and should return either a modified hash
-    #   to be sent to PostHog or nil to prevent the event from being sent. e.g. `before_send: ->(event) { event }`
-    # @option opts [Bool] :disable_singleton_warning +true+ to suppress the warning when multiple clients
-    #   share the same API key. Use only when you intentionally need multiple clients. Defaults to +false+.
-    # @option opts [Object] :flag_definition_cache_provider An object implementing the
-    #   {FlagDefinitionCacheProvider} interface for distributed flag definition caching.
-    #   EXPERIMENTAL: This API may change in future minor version bumps.
+    # @param opts [Hash] Client configuration.
+    # @option opts [String] :api_key Your project's API key. Required.
+    # @option opts [String, nil] :personal_api_key Your personal API key. Required for local feature flag evaluation.
+    # @option opts [String] :host Fully qualified hostname of the PostHog server. Defaults to `https://us.i.posthog.com`.
+    # @option opts [Integer] :max_queue_size Maximum number of calls to remain queued. Defaults to 10_000.
+    # @option opts [Integer] :batch_size Maximum number of events to send in one async batch.
+    # @option opts [Boolean] :test_mode +true+ if messages should remain queued for testing. Defaults to +false+.
+    # @option opts [Boolean] :sync_mode +true+ to send events synchronously on the calling thread. Useful in
+    #   forking environments like Sidekiq and Resque. Defaults to +false+.
+    # @option opts [Proc] :on_error Callback invoked as `on_error.call(status, error)` for API or serialization errors.
+    # @option opts [Integer] :feature_flags_polling_interval How often to poll for feature flag definition changes,
+    #   in seconds. Defaults to 30.
+    # @option opts [Integer] :feature_flag_request_timeout_seconds How long to wait for feature flag evaluation,
+    #   in seconds. Defaults to 3.
+    # @option opts [Proc] :before_send A callback that receives the event hash and should return either a modified
+    #   hash to be sent to PostHog or nil to prevent the event from being sent. e.g. `before_send: ->(event) { event }`.
+    # @option opts [Boolean] :disable_singleton_warning +true+ to suppress the warning when multiple clients share
+    #   the same API key. Use only when you intentionally need multiple clients. Defaults to +false+.
+    # @option opts [Boolean] :skip_ssl_verification +true+ to disable SSL certificate verification for requests.
+    #   Intended only for local development or custom deployments.
+    # @option opts [Object] :flag_definition_cache_provider An object implementing the {FlagDefinitionCacheProvider}
+    #   interface for distributed flag definition caching. EXPERIMENTAL: This API may change in future minor versions.
     def initialize(opts = {})
       symbolize_keys!(opts)
 
@@ -142,7 +142,9 @@ module PostHog
     # Synchronously waits until the worker has cleared the queue.
     #
     # Use only for scripts which are not long-running, and will specifically
-    # exit
+    # exit.
+    #
+    # @return [void]
     def flush
       if @sync_mode
         # Wait for any in-flight sync send to complete
@@ -158,7 +160,9 @@ module PostHog
 
     # Clears the queue without waiting.
     #
-    # Use only in test mode
+    # Use only in test mode.
+    #
+    # @return [void]
     def clear
       @queue.clear
     end
@@ -175,8 +179,10 @@ module PostHog
     #
     # @option attrs [String] :event Event name
     # @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 [Hash] :groups Group analytics mapping from group type to group key (optional)
+    # @option attrs [Boolean, Hash, SendFeatureFlagsOptions] :send_feature_flags
+    #   Deprecated. 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
@@ -185,9 +191,14 @@ 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`.
+    # @return [Boolean] Whether the event was queued or sent.
     # @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,22 +271,20 @@ 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}.
+    # @param flags [PostHog::FeatureFlagEvaluations, nil] 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.
+    # @return [Boolean, nil] Whether the exception event was queued or sent, or nil if the input could not be parsed.
     def capture_exception(exception, distinct_id = nil, additional_properties = {}, flags: nil)
       exception_info = ExceptionCapture.build_parsed_exception(exception)
 
       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,
@@ -293,6 +302,7 @@ module PostHog
     # @param [Hash] attrs
     #
     # @option attrs [Hash] :properties User properties (optional)
+    # @return [Boolean] Whether the identify event was queued or sent.
     # @macro common_attrs
     def identify(attrs)
       symbolize_keys! attrs
@@ -307,6 +317,7 @@ module PostHog
     # @option attrs [String] :group_key Group key
     # @option attrs [Hash] :properties Group properties (optional)
     # @option attrs [String] :distinct_id Distinct ID (optional)
+    # @return [Boolean] Whether the group identify event was queued or sent.
     # @macro common_attrs
     def group_identify(attrs)
       symbolize_keys! attrs
@@ -318,23 +329,32 @@ module PostHog
     # @param [Hash] attrs
     #
     # @option attrs [String] :alias The alias to give the distinct id
+    # @return [Boolean] Whether the alias event was queued or sent.
     # @macro common_attrs
     def alias(attrs)
       symbolize_keys! attrs
       enqueue(FieldParser.parse_for_alias(attrs))
     end
 
-    # @return [Hash] pops the last message from the queue
+    # @return [Hash] Pops the last message from the queue. Intended for test mode.
     def dequeue_last_message
       @queue.pop
     end
 
-    # @return [Fixnum] number of messages in the queue
+    # @return [Integer] Number of messages in the queue. Intended for test mode.
     def queued_messages
       @queue.length
     end
 
-    # @deprecated Use {#evaluate_flags} and {FeatureFlagEvaluations#is_enabled} instead.
+    # @deprecated Use {#evaluate_flags} and {FeatureFlagEvaluations#enabled?} instead.
+    # @param flag_key [String, Symbol] The unique key of the feature flag.
+    # @param distinct_id [String] The distinct id of the user.
+    # @param groups [Hash] Group analytics mapping from group type to group key.
+    # @param person_properties [Hash] Properties to use when evaluating the user locally or remotely.
+    # @param group_properties [Hash] Properties to use when evaluating groups locally or remotely.
+    # @param only_evaluate_locally [Boolean] Skip the remote /flags call.
+    # @param send_feature_flag_events [Boolean] Whether to capture `$feature_flag_called` for this access.
+    # @return [Boolean, nil] Whether the flag is enabled, or nil when the flag could not be evaluated.
     # TODO: In future version, rename to `feature_flag_enabled?`
     def is_feature_enabled( # rubocop:disable Naming/PredicateName
       flag_key,
@@ -364,8 +384,8 @@ module PostHog
       !!response
     end
 
-    # @param [String, Symbol] flag_key The unique flag key of the feature flag
-    # @return [String] The decrypted value of the feature flag payload
+    # @param flag_key [String, Symbol] The unique flag key of the remote config feature flag.
+    # @return [Hash] The parsed remote config payload response.
     def get_remote_config_payload(flag_key)
       @feature_flags_poller.get_remote_config_payload(flag_key.to_s)
     end
@@ -377,8 +397,10 @@ module PostHog
     # @param [Hash] groups
     # @param [Hash] person_properties key-value pairs of properties to associate with the user.
     # @param [Hash] group_properties
+    # @param only_evaluate_locally [Boolean] Skip the remote /flags call.
+    # @param send_feature_flag_events [Boolean] Whether to capture `$feature_flag_called` for this access.
     #
-    # @return [String, nil] The value of the feature flag
+    # @return [String, Boolean, nil] The value of the feature flag
     #
     # The provided properties are used to calculate feature flags locally, if possible.
     #
@@ -418,6 +440,14 @@ module PostHog
 
     # @deprecated Use {#evaluate_flags} and {FeatureFlagEvaluations#get_flag} /
     #   {FeatureFlagEvaluations#get_flag_payload} instead.
+    # @param key [String, Symbol] The unique key of the feature flag.
+    # @param distinct_id [String] The distinct id of the user.
+    # @param groups [Hash] Group analytics mapping from group type to group key.
+    # @param person_properties [Hash] Properties to use when evaluating the user locally or remotely.
+    # @param group_properties [Hash] Properties to use when evaluating groups locally or remotely.
+    # @param only_evaluate_locally [Boolean] Skip the remote /flags call.
+    # @param send_feature_flag_events [Boolean] Whether to capture `$feature_flag_called` for this access.
+    # @return [PostHog::FeatureFlagResult, nil]
     def get_feature_flag_result(
       key,
       distinct_id,
@@ -454,7 +484,8 @@ module PostHog
     # @param [Hash] person_properties key-value pairs of properties to associate with the user
     # @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 [Boolean, nil] disable_geoip When true, disables GeoIP lookup for remote evaluation and stamps captured
+    #   access events.
     # @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
@@ -578,6 +609,7 @@ module PostHog
     # @param [Hash] groups
     # @param [Hash] person_properties key-value pairs of properties to associate with the user.
     # @param [Hash] group_properties
+    # @param only_evaluate_locally [Boolean] Skip the remote /flags call.
     #
     # @return [Hash] String (not symbol) key value pairs of flag and their values
     def get_all_flags(
@@ -600,11 +632,12 @@ module PostHog
     #
     # @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
-    # @option [Hash] person_properties key-value pairs of properties to associate with the user.
-    # @option [Hash] group_properties
-    # @option [Boolean] only_evaluate_locally
+    # @param match_value [String, Boolean, nil] The value of the feature flag to be matched
+    # @param groups [Hash]
+    # @param person_properties [Hash] key-value pairs of properties to associate with the user.
+    # @param group_properties [Hash]
+    # @param only_evaluate_locally [Boolean]
+    # @return [Object, nil] The parsed payload for the matched flag value.
     #
     # @deprecated Use {#evaluate_flags} and {FeatureFlagEvaluations#get_flag_payload} instead.
     def get_feature_flag_payload(
@@ -637,10 +670,10 @@ module PostHog
     #   featureFlagPayloads: A hash of feature flag payloads
     #
     # @param [String] distinct_id The distinct id of the user
-    # @option [Hash] groups
-    # @option [Hash] person_properties key-value pairs of properties to associate with the user.
-    # @option [Hash] group_properties
-    # @option [Boolean] only_evaluate_locally
+    # @param groups [Hash]
+    # @param person_properties [Hash] key-value pairs of properties to associate with the user.
+    # @param group_properties [Hash]
+    # @param only_evaluate_locally [Boolean] Skip the remote /flags call.
     #
     def get_all_flags_and_payloads(
       distinct_id,
@@ -662,6 +695,9 @@ module PostHog
       response
     end
 
+    # Reload locally cached feature flag definitions.
+    #
+    # @return [void]
     def reload_feature_flags
       unless @personal_api_key
         logger.error(
@@ -672,6 +708,9 @@ module PostHog
       @feature_flags_poller.load_feature_flags(true)
     end
 
+    # Flush pending events and stop background resources.
+    #
+    # @return [void]
     def shutdown
       self.class._decrement_instance_count(@api_key) if @api_key
       @feature_flags_poller.shutdown_poller
@@ -685,6 +724,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.

data/lib/posthog/exception_capture.rb

@@ -11,6 +11,9 @@
 # 💖 open source (under MIT License)
 
 module PostHog
+  # Builds PostHog exception payloads from Ruby exception objects.
+  #
+  # @api private
   module ExceptionCapture
     RUBY_INPUT_FORMAT = /
         ^ \s* (?: [a-zA-Z]: | uri:classloader: )? ([^:]+ | <.*>):
@@ -18,6 +21,8 @@ module PostHog
         (?: :in\s('|`)(?:([\w:]+)\#)?([^']+)')?$
       /x
 
+    # @param value [Exception, String, Object] Exception input to parse.
+    # @return [Hash, nil] Parsed exception payload, or nil when the input is unsupported.
     def self.build_parsed_exception(value)
       title, message, backtrace = coerce_exception_input(value)
       return nil if title.nil?
@@ -25,6 +30,10 @@ module PostHog
       build_single_exception_from_data(title, message, backtrace)
     end
 
+    # @param title [String]
+    # @param message [String, nil]
+    # @param backtrace [Array<String>, nil]
+    # @return [Hash]
     def self.build_single_exception_from_data(title, message, backtrace)
       {
         'type' => title,
@@ -37,6 +46,8 @@ module PostHog
       }
     end
 
+    # @param backtrace [Array<String>, nil]
+    # @return [Hash, nil]
     def self.build_stacktrace(backtrace)
       return nil unless backtrace && !backtrace.empty?
 
@@ -50,6 +61,8 @@ module PostHog
       }
     end
 
+    # @param line [String]
+    # @return [Hash, nil]
     def self.parse_backtrace_line(line)
       match = line.match(RUBY_INPUT_FORMAT)
       return nil unless match
@@ -72,6 +85,8 @@ module PostHog
       frame
     end
 
+    # @param path [String]
+    # @return [Boolean]
     def self.gem_path?(path)
       path.include?('/gems/') ||
         path.include?('/ruby/') ||
@@ -79,6 +94,11 @@ module PostHog
         path.include?('/.rvm/')
     end
 
+    # @param frame [Hash]
+    # @param file_path [String]
+    # @param lineno [Integer]
+    # @param context_size [Integer]
+    # @return [void]
     def self.add_context_lines(frame, file_path, lineno, context_size = 5)
       lines = File.readlines(file_path)
       return if lines.empty?
@@ -97,6 +117,8 @@ module PostHog
       # Silently ignore file read errors
     end
 
+    # @param value [Exception, String, Object]
+    # @return [Array] Three-item array of title, message, and backtrace.
     def self.coerce_exception_input(value)
       if value.is_a?(String)
         title = 'Error'

data/lib/posthog/feature_flag.rb

@@ -1,10 +1,13 @@
 # frozen_string_literal: true
 
-# Represents a feature flag returned by /flags v2
 module PostHog
+  # Represents a feature flag returned by /flags v2.
+  #
+  # @api private
   class FeatureFlag
     attr_reader :key, :enabled, :variant, :reason, :metadata, :failed
 
+    # @param json [Hash] Raw feature flag data returned by /flags.
     def initialize(json)
       json.transform_keys!(&:to_s)
       @key = json['key']
@@ -15,15 +18,21 @@ module PostHog
       @failed = json['failed']
     end
 
+    # @return [String, Boolean] The variant value when present, otherwise the enabled status.
     # TODO: Rename to `value` in future version
     def get_value # rubocop:disable Naming/AccessorMethodName
       @variant || @enabled
     end
 
+    # @return [Object, nil] The flag payload from metadata.
     def payload
       @metadata&.payload
     end
 
+    # @param key [String, Symbol] The feature flag key.
+    # @param value [String, Boolean] The feature flag value.
+    # @param payload [Object, nil] The feature flag payload.
+    # @return [PostHog::FeatureFlag]
     def self.from_value_and_payload(key, value, payload)
       new({
             'key' => key,
@@ -40,10 +49,13 @@ module PostHog
     end
   end
 
-  # Represents the reason why a flag was enabled/disabled
+  # Represents the reason why a flag was enabled/disabled.
+  #
+  # @api private
   class EvaluationReason
     attr_reader :code, :description, :condition_index
 
+    # @param json [Hash] Raw reason data returned by /flags.
     def initialize(json)
       json.transform_keys!(&:to_s)
       @code = json['code']
@@ -52,10 +64,13 @@ module PostHog
     end
   end
 
-  # Represents metadata about a feature flag
+  # Represents metadata about a feature flag.
+  #
+  # @api private
   class FeatureFlagMetadata
     attr_reader :id, :version, :payload, :description
 
+    # @param json [Hash] Raw metadata returned by /flags.
     def initialize(json)
       json.transform_keys!(&:to_s)
       @id = json['id']

data/lib/posthog/feature_flag_error.rb

@@ -17,6 +17,7 @@ module PostHog
   #
   # For API errors with status codes, use the api_error() method which returns
   # a string like "api_error_500".
+  # @api private
   class FeatureFlagError
     ERRORS_WHILE_COMPUTING = 'errors_while_computing_flags'
     FLAG_MISSING = 'flag_missing'

data/lib/posthog/feature_flag_evaluations.rb

@@ -4,7 +4,7 @@ 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
+  # PostHog::Client#evaluate_flags. Calls to {#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
@@ -19,8 +19,32 @@ module PostHog
 
     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
+    # @return [String] The distinct id these evaluations belong to.
+    attr_reader :distinct_id
 
+    # @return [Hash, nil] Group analytics mapping used for evaluation.
+    attr_reader :groups
+
+    # @return [String, nil] Request id returned by the /flags endpoint.
+    attr_reader :request_id
+
+    # @return [String, nil] Evaluation timestamp returned by the /flags endpoint.
+    attr_reader :evaluated_at
+
+    # @return [Time, nil] When local flag definitions were loaded.
+    attr_reader :flag_definitions_loaded_at
+
+    # @param host [Host, nil] Internal host callbacks used to record flag access events.
+    # @param distinct_id [String, nil] The distinct id these evaluations belong to.
+    # @param flags [Hash] Evaluated flags keyed by flag key.
+    # @param groups [Hash, nil] Group analytics mapping from group type to group key.
+    # @param disable_geoip [Boolean, nil] Whether GeoIP was disabled during evaluation.
+    # @param request_id [String, nil] The request id returned by the /flags endpoint.
+    # @param evaluated_at [String, nil] The evaluation timestamp returned by the /flags endpoint.
+    # @param flag_definitions_loaded_at [Time, nil] When local flag definitions were loaded.
+    # @param errors_while_computing [Boolean] Whether the server reported errors while computing flags.
+    # @param quota_limited [Boolean] Whether feature flag evaluation was quota limited.
+    # @param accessed [Array<String>, Set<String>, nil] Flag keys already accessed by this snapshot.
     def initialize(
       host: nil,
       distinct_id: nil,
@@ -47,10 +71,13 @@ module PostHog
       @accessed = Set.new(accessed || [])
     end
 
+    # @return [Array<String>] The evaluated flag keys in this snapshot.
     def keys
       @flags.keys
     end
 
+    # @param key [String, Symbol] The feature flag key.
+    # @return [Boolean] true when the flag is enabled, false when disabled or missing.
     def enabled?(key)
       key = key.to_s
       flag = @flags[key]
@@ -58,6 +85,9 @@ module PostHog
       flag&.enabled ? true : false
     end
 
+    # @param key [String, Symbol] The feature flag key.
+    # @return [String, Boolean, nil] Variant string for multivariate flags, true/false for boolean flags,
+    #   or nil when the flag was not returned by the evaluation.
     def get_flag(key)
       key = key.to_s
       flag = @flags[key]
@@ -65,6 +95,8 @@ module PostHog
       _flag_value(flag)
     end
 
+    # @param key [String, Symbol] The feature flag key.
+    # @return [Object, nil] The parsed payload for the flag, if any.
     def get_flag_payload(key)
       flag = @flags[key.to_s]
       flag&.payload
@@ -73,10 +105,14 @@ module PostHog
     # 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.
+    # @return [PostHog::FeatureFlagEvaluations] A snapshot containing only flags already accessed with
+    #   {#enabled?} or {#get_flag}.
     def only_accessed
       _clone_with(@flags.slice(*@accessed))
     end
 
+    # @param keys [Array<String, Symbol>, String, Symbol] Flag keys to keep in the returned snapshot.
+    # @return [PostHog::FeatureFlagEvaluations] A snapshot containing only the requested keys that exist.
     def only(keys)
       keys = Array(keys).map(&:to_s)
       missing = keys.reject { |k| @flags.key?(k) }
@@ -92,6 +128,9 @@ module PostHog
 
     # Builds the `$feature/<key>` and `$active_feature_flags` properties for a
     # captured event. Called from PostHog::Client#capture when `flags:` is set.
+    #
+    # @api private
+    # @return [Hash]
     def _get_event_properties
       properties = {}
       active = []

data/lib/posthog/feature_flag_result.rb

@@ -6,8 +6,19 @@ module PostHog
   # Represents the result of a feature flag evaluation
   # containing both the flag value and payload
   class FeatureFlagResult
-    attr_reader :key, :variant, :payload
+    # @return [String, Symbol] The feature flag key.
+    attr_reader :key
 
+    # @return [String, nil] The variant key for multivariate flags.
+    attr_reader :variant
+
+    # @return [Object, nil] The parsed feature flag payload.
+    attr_reader :payload
+
+    # @param key [String, Symbol] The feature flag key.
+    # @param enabled [Boolean] Whether the feature flag is enabled.
+    # @param variant [String, nil] The variant key for multivariate flags.
+    # @param payload [Object, nil] The parsed feature flag payload.
     def initialize(key:, enabled:, variant: nil, payload: nil)
       @key = key
       @enabled = enabled
@@ -15,18 +26,27 @@ module PostHog
       @payload = payload
     end
 
-    # Returns the effective value of the feature flag
-    # variant if present, otherwise enabled status
+    # Returns the effective value of the feature flag: variant if present,
+    # otherwise enabled status.
+    #
+    # @return [String, Boolean]
     def value
       @variant || @enabled
     end
 
-    # Returns whether or not the feature flag evaluated as enabled
+    # Returns whether or not the feature flag evaluated as enabled.
+    #
+    # @return [Boolean]
     def enabled?
       @enabled
     end
 
-    # Factory method to create from flag value and payload
+    # Factory method to create from flag value and payload.
+    #
+    # @param key [String, Symbol] The feature flag key.
+    # @param value [String, Boolean, nil] The raw feature flag value.
+    # @param payload [Object, String, nil] The raw or JSON-encoded feature flag payload.
+    # @return [PostHog::FeatureFlagResult, nil]
     def self.from_value_and_payload(key, value, payload)
       return nil if value.nil?
 
@@ -43,6 +63,9 @@ module PostHog
     # returned when the body is not valid JSON); already-deserialized values
     # pass through. Public so {FeatureFlagEvaluations} can normalize payloads
     # the same way {FeatureFlagResult} does.
+    #
+    # @param payload [Object, String, nil] The raw payload value.
+    # @return [Object, nil] The parsed payload.
     def self.parse_payload(payload)
       return nil if payload.nil?
       return payload unless payload.is_a?(String)

data/lib/posthog/feature_flags.rb

@@ -20,10 +20,20 @@ module PostHog
   class RequiresServerEvaluation < StandardError
   end
 
+  # Polls and evaluates feature flag definitions for {PostHog::Client}.
+  #
+  # @api private
   class FeatureFlagsPoller
     include PostHog::Logging
     include PostHog::Utils
 
+    # @param polling_interval [Integer, nil] Seconds between local feature flag definition polls.
+    # @param personal_api_key [String, nil] Personal API key used to fetch local evaluation definitions.
+    # @param project_api_key [String] Project API key.
+    # @param host [String] PostHog API host URL.
+    # @param feature_flag_request_timeout_seconds [Integer] Timeout for feature flag requests.
+    # @param on_error [Proc, nil] Callback invoked as `on_error.call(status, error)`.
+    # @param flag_definition_cache_provider [Object, nil] Optional {FlagDefinitionCacheProvider} implementation.
     def initialize(
       polling_interval,
       personal_api_key,
@@ -446,6 +456,16 @@ module PostHog
       parsed_dt
     end
 
+    # Parse a single semver numeric identifier, rejecting empty, non-digit, or
+    # leading-zero values per semver 2.0.0 §2.
+    def self.parse_semver_numeric(part)
+      raise InconclusiveMatchError, 'Invalid semver format' if part.nil? || part.empty? || part !~ /^\d+$/
+      # Semver 2.0.0 §2: numeric identifiers MUST NOT include leading zeros.
+      raise InconclusiveMatchError, 'Invalid semver format' if part.length > 1 && part[0] == '0'
+
+      part.to_i
+    end
+
     # Parse a semver string into a comparable [major, minor, patch] integer array.
     # Handles v-prefix, whitespace, pre-release suffixes. Defaults missing components to 0.
     def self.parse_semver(value)
@@ -461,14 +481,9 @@ module PostHog
 
       raise InconclusiveMatchError, 'Invalid semver format' if parts.empty? || parts[0].to_s.empty?
 
-      # Check for leading dot or non-numeric parts
-      parts.each do |part|
-        raise InconclusiveMatchError, 'Invalid semver format' if part.empty? || part !~ /^\d+$/
-      end
-
-      major = parts[0].to_i
-      minor = parts.length > 1 ? parts[1].to_i : 0
-      patch = parts.length > 2 ? parts[2].to_i : 0
+      major = parse_semver_numeric(parts[0])
+      minor = parts.length > 1 ? parse_semver_numeric(parts[1]) : 0
+      patch = parts.length > 2 ? parse_semver_numeric(parts[2]) : 0
 
       [major, minor, patch]
     end
@@ -525,20 +540,22 @@ module PostHog
 
       raise InconclusiveMatchError, 'Invalid semver wildcard format' if parts.empty?
 
-      parts.each do |part|
-        raise InconclusiveMatchError, 'Invalid semver wildcard format' if part !~ /^\d+$/
+      numeric = parts.map do |part|
+        parse_semver_numeric(part)
+      rescue InconclusiveMatchError
+        raise InconclusiveMatchError, 'Invalid semver wildcard format'
       end
 
-      major = parts[0].to_i
-      case parts.length
+      major = numeric[0]
+      case numeric.length
       when 1
         [[major, 0, 0], [major + 1, 0, 0]]
       when 2
-        minor = parts[1].to_i
+        minor = numeric[1]
         [[major, minor, 0], [major, minor + 1, 0]]
       else
-        minor = parts[1].to_i
-        patch = parts[2].to_i
+        minor = numeric[1]
+        patch = numeric[2]
         [[major, minor, patch], [major, minor, patch + 1]]
       end
     end

data/lib/posthog/field_parser.rb

@@ -3,6 +3,9 @@
 require 'posthog/logging'
 
 module PostHog
+  # Converts public SDK method arguments into PostHog API event payloads.
+  #
+  # @api private
   class FieldParser
     class << self
       include PostHog::Utils
@@ -14,6 +17,8 @@ module PostHog
       # - "properties"
       # - "groups"
       # - "uuid"
+      # @param fields [Hash]
+      # @return [Hash]
       def parse_for_capture(fields)
         common = parse_common_fields(fields)
 
@@ -45,6 +50,8 @@ module PostHog
       # In addition to the common fields, identify accepts:
       #
       # - "properties"
+      # @param fields [Hash]
+      # @return [Hash]
       def parse_for_identify(fields)
         common = parse_common_fields(fields)
 
@@ -63,6 +70,8 @@ module PostHog
         )
       end
 
+      # @param fields [Hash]
+      # @return [Hash]
       def parse_for_group_identify(fields)
         properties = fields[:properties] || {}
         group_type = fields[:group_type]
@@ -92,6 +101,8 @@ module PostHog
       # In addition to the common fields, alias accepts:
       #
       # - "alias"
+      # @param fields [Hash]
+      # @return [Hash]
       def parse_for_alias(fields)
         common = parse_common_fields(fields)
 

data/lib/posthog/flag_definition_cache.rb

@@ -14,26 +14,31 @@ module PostHog
   #
   # == Required Methods
   #
-  # [+flag_definitions+]
+  # @!method flag_definitions
   #   Retrieve cached flag definitions. Return a Hash with +:flags+,
   #   +:group_type_mapping+, and +:cohorts+ keys, or +nil+ if the cache
   #   is empty. Returning +nil+ triggers an API fetch when no flags are
   #   loaded yet (emergency fallback).
+  #   @return [Hash, nil]
   #
-  # [+should_fetch_flag_definitions?+]
+  # @!method should_fetch_flag_definitions?
   #   Return +true+ if this instance should fetch new definitions from the
   #   API, +false+ to read from cache instead. Use for distributed lock
   #   coordination so only one worker fetches at a time.
+  #   @return [Boolean]
   #
-  # [+on_flag_definitions_received(data)+]
+  # @!method on_flag_definitions_received(data)
   #   Called after successfully fetching new definitions from the API.
   #   +data+ is a Hash with +:flags+, +:group_type_mapping+, and +:cohorts+
   #   keys (plain Ruby types, not Concurrent:: wrappers). Store it in your
   #   external cache.
+  #   @param data [Hash]
+  #   @return [void]
   #
-  # [+shutdown+]
+  # @!method shutdown
   #   Called when the PostHog client shuts down. Release any distributed
   #   locks and clean up resources.
+  #   @return [void]
   #
   # == Error Handling
   #
@@ -66,6 +71,7 @@ module PostHog
     #
     # @param provider [Object] the cache provider to validate
     # @raise [ArgumentError] if any required methods are missing
+    # @return [void]
     def self.validate!(provider)
       missing = REQUIRED_METHODS.reject { |m| provider.respond_to?(m) }
       return if missing.empty?

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/logging.rb

@@ -3,8 +3,12 @@
 require 'logger'
 
 module PostHog
-  # Wraps an existing logger and adds a prefix to all messages
+  # Wraps an existing logger and adds a prefix to all messages.
+  #
+  # @api private
   class PrefixedLogger
+    # @param logger [Logger, #debug, #info, #warn, #error]
+    # @param prefix [String]
     def initialize(logger, prefix)
       @logger = logger
       @prefix = prefix
@@ -37,6 +41,7 @@ module PostHog
 
   module Logging
     class << self
+      # @return [Logger, PostHog::PrefixedLogger] The logger used by the SDK.
       def logger
         return @logger if @logger
 
@@ -52,6 +57,7 @@ module PostHog
         @logger = PrefixedLogger.new(base_logger, '[posthog-ruby]')
       end
 
+      # @param logger [Logger, #debug, #info, #warn, #error] Custom logger used by the SDK.
       attr_writer :logger
     end
 
@@ -63,6 +69,7 @@ module PostHog
       end
     end
 
+    # @return [Logger, PostHog::PrefixedLogger] The logger used by the SDK.
     def logger
       Logging.logger
     end

data/lib/posthog/message_batch.rb

@@ -4,7 +4,9 @@ require 'forwardable'
 require 'posthog/logging'
 
 module PostHog
-  # A batch of `Message`s to be sent to the API
+  # A batch of messages to be sent to the API.
+  #
+  # @api private
   class MessageBatch
     class JSONGenerationError < StandardError
     end
@@ -13,12 +15,15 @@ module PostHog
     include PostHog::Logging
     include PostHog::Defaults::MessageBatch
 
+    # @param max_message_count [Integer] Maximum number of messages in the batch.
     def initialize(max_message_count)
       @messages = []
       @max_message_count = max_message_count
       @json_size = 0
     end
 
+    # @param message [Hash] Message to add to the batch.
+    # @return [Array<Hash>, nil]
     def <<(message)
       begin
         message_json = message.to_json
@@ -35,10 +40,12 @@ module PostHog
       end
     end
 
+    # @return [Boolean] Whether the batch is full.
     def full?
       item_count_exhausted? || size_exhausted?
     end
 
+    # @return [void]
     def clear
       @messages.clear
       @json_size = 0

data/lib/posthog/noop_worker.rb

@@ -1,21 +1,27 @@
 # frozen_string_literal: true
 
-# A worker that doesn't consume jobs
 module PostHog
+  # A worker that doesn't consume jobs.
+  #
+  # @api private
   class NoopWorker
+    # @param queue [Queue]
     def initialize(queue)
       @queue = queue
     end
 
+    # @return [void]
     def run
       # Does nothing
     end
 
+    # @return [Boolean]
     # TODO: Rename to `requesting?` in future version
     def is_requesting? # rubocop:disable Naming/PredicateName
       false
     end
 
+    # @return [void]
     def shutdown
       # Does nothing
     end

data/lib/posthog/response.rb

@@ -1,12 +1,14 @@
 # frozen_string_literal: true
 
 module PostHog
+  # API response wrapper returned by the SDK transport.
+  #
+  # @api private
   class Response
     attr_reader :status, :error
 
-    # public: Simple class to wrap responses from the API
-    #
-    #
+    # @param status [Integer] HTTP status code, or -1 for SDK/transport errors.
+    # @param error [String, nil] Error message returned by the API or SDK.
     def initialize(status = 200, error = nil)
       @status = status
       @error = error

data/lib/posthog/send_feature_flags_options.rb

@@ -3,16 +3,29 @@
 require 'posthog/utils'
 
 module PostHog
-  # Options for configuring feature flag behavior in capture calls
+  # Options for configuring deprecated feature flag behavior in capture calls.
+  #
+  # @deprecated Prefer passing a {PostHog::FeatureFlagEvaluations} snapshot to `capture(flags:)`.
   class SendFeatureFlagsOptions
-    attr_reader :only_evaluate_locally, :person_properties, :group_properties
+    # @return [Boolean, nil] Whether remote feature flag evaluation should be skipped.
+    attr_reader :only_evaluate_locally
 
+    # @return [Hash] Person properties to use for feature flag evaluation.
+    attr_reader :person_properties
+
+    # @return [Hash] Group properties to use for feature flag evaluation.
+    attr_reader :group_properties
+
+    # @param only_evaluate_locally [Boolean, nil] Skip remote feature flag evaluation.
+    # @param person_properties [Hash, nil] Person properties to use for feature flag evaluation.
+    # @param group_properties [Hash, nil] Group properties to use for feature flag evaluation.
     def initialize(only_evaluate_locally: nil, person_properties: nil, group_properties: nil)
       @only_evaluate_locally = only_evaluate_locally
       @person_properties = person_properties || {}
       @group_properties = group_properties || {}
     end
 
+    # @return [Hash] A hash representation suitable for `capture(send_feature_flags:)`.
     def to_h
       {
         only_evaluate_locally: @only_evaluate_locally,
@@ -21,6 +34,8 @@ module PostHog
       }
     end
 
+    # @param hash [Hash]
+    # @return [PostHog::SendFeatureFlagsOptions, nil]
     def self.from_hash(hash)
       return nil unless hash.is_a?(Hash)
 

data/lib/posthog/send_worker.rb

@@ -6,6 +6,9 @@ require 'posthog/transport'
 require 'posthog/utils'
 
 module PostHog
+  # Background worker that batches and sends queued events.
+  #
+  # @api private
   class SendWorker
     include PostHog::Utils
     include PostHog::Defaults
@@ -16,12 +19,13 @@ module PostHog
     # The worker continuously takes messages off the queue
     # and makes requests to the posthog.com api
     #
-    # queue   - Queue synchronized between client and worker
-    # api_key  - String of the project's API key
-    # options - Hash of worker options
-    #           batch_size - Fixnum of how many items to send in a batch
-    #           on_error   - Proc of what to do on an error
-    #
+    # @param queue [Queue] Queue synchronized between client and worker.
+    # @param api_key [String] Project API key.
+    # @param options [Hash] Worker options.
+    # @option options [Integer] :batch_size How many items to send in a batch.
+    # @option options [Proc] :on_error Callback invoked as `on_error.call(status, error)`.
+    # @option options [String] :host PostHog API host URL.
+    # @option options [Boolean] :skip_ssl_verification Disable SSL certificate verification.
     def initialize(queue, api_key, options = {})
       symbolize_keys! options
       @queue = queue
@@ -33,8 +37,9 @@ module PostHog
       @transport = Transport.new api_host: options[:host], skip_ssl_verification: options[:skip_ssl_verification]
     end
 
-    # public: Continuously runs the loop to check for new events
+    # Continuously runs the loop to check for new events.
     #
+    # @return [void]
     def run
       until Thread.current[:should_exit]
         return if @queue.empty?
@@ -54,12 +59,14 @@ module PostHog
       @transport.shutdown
     end
 
+    # @return [void]
     def shutdown
       @transport.shutdown
     end
 
     # public: Check whether we have outstanding requests.
     #
+    # @return [Boolean] Whether the worker has outstanding requests.
     # TODO: Rename to `requesting?` in future version
     def is_requesting? # rubocop:disable Naming/PredicateName
       @lock.synchronize { !@batch.empty? }

data/lib/posthog/transport.rb

@@ -10,11 +10,24 @@ require 'net/https'
 require 'json'
 
 module PostHog
+  # HTTP transport used by the SDK workers.
+  #
+  # @api private
   class Transport
     include PostHog::Defaults::Request
     include PostHog::Utils
     include PostHog::Logging
 
+    # @param options [Hash] Transport configuration.
+    # @option options [String] :api_host Full PostHog API host URL.
+    # @option options [String] :host Hostname to connect to.
+    # @option options [Integer] :port Port to connect to.
+    # @option options [Boolean] :ssl Whether to use HTTPS.
+    # @option options [Hash] :headers HTTP headers for batch requests.
+    # @option options [String] :path HTTP path for batch requests.
+    # @option options [Integer] :retries Number of retry attempts for retryable failures.
+    # @option options [PostHog::BackoffPolicy] :backoff_policy Backoff policy used between retries.
+    # @option options [Boolean] :skip_ssl_verification Disable SSL certificate verification.
     def initialize(options = {})
       if options[:api_host]
         uri = URI.parse(options[:api_host])
@@ -43,6 +56,8 @@ module PostHog
 
     # Sends a batch of messages to the API
     #
+    # @param api_key [String] Project API key.
+    # @param batch [PostHog::MessageBatch, Array<Hash>] Batch of messages to send.
     # @return [Response] API response
     def send(api_key, batch)
       logger.debug("Sending request for #{batch.length} items")
@@ -72,7 +87,9 @@ module PostHog
       end
     end
 
-    # Closes a persistent connection if it exists
+    # Closes a persistent connection if it exists.
+    #
+    # @return [void]
     def shutdown
       @http.finish if @http.started?
     end

data/lib/posthog/utils.rb

@@ -6,6 +6,9 @@ module PostHog
   class InconclusiveMatchError < StandardError
   end
 
+  # Utility helpers used internally by the SDK.
+  #
+  # @api private
   module Utils
     module_function
 
@@ -145,12 +148,19 @@ module PostHog
       end
     end
 
+    # Hash that clears itself when it reaches a maximum length.
+    #
+    # @api private
     class SizeLimitedHash < Hash
+      # @param max_length [Integer]
       def initialize(max_length, ...)
         super(...)
         @max_length = max_length
       end
 
+      # @param key [Object]
+      # @param value [Object]
+      # @return [Object]
       def []=(key, value)
         clear if length >= @max_length
         super

data/lib/posthog/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: posthog-ruby
 version: !ruby/object:Gem::Version
-  version: 3.8.1
+  version: 3.9.1
 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