posthog-ruby 3.9.0 → 3.9.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3f033107e265e546dca78bfbf8f6adb3552e5803ac7dec0bf822afb814e7658d
-  data.tar.gz: efe43054d73bfce034973fc12a01301f3b935cfacb1e7e86358332a9879f8911
+  metadata.gz: 44b91bbae760e03c60cedc5e14bebc275a4e0fd112ba20bed4c2539016cc8241
+  data.tar.gz: 15cfdaa8da6474bd7f6854339aa4123a02991eac0eac8bd3b4d78da3f4d131e9
 SHA512:
-  metadata.gz: e1e3e4e0e5712ab73c8c0c11ce5a5869df0dc95f293b151f81d7fc715844e36867d3aeed393427494789bf8b35f2d96f42c703085d6be405fe1168feaa7daa82
-  data.tar.gz: 1347919dcaeda0b7ad237964ae00acc34d4b6e4b9273d3335ce6e4666f09471d8d8fefb53c13d51e345cf3b7c8e467b813b14cbbdad74062dbabbc12fbeadc26
+  metadata.gz: 3dc592f13f48e806ae7ac7f5985ce4466f7dff80f6965e8a5e0f5df774f4f7529e83023c0cde3a7ad2686d18a4aebab38e8538467576c8b17145c373648382e7
+  data.tar.gz: 3fa007054bb09b32ae6df99570683dc568a35365f44f46375f50a9b0a8338640d281dcb37dc6bc6041013093df0f64cb44a42b44c30e8a6e5ee49b0a8291e880

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

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'time'
+require 'json'
 require 'securerandom'
 
 require 'posthog/defaults'
@@ -50,29 +51,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)
 
@@ -143,7 +143,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
@@ -159,7 +161,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
@@ -176,8 +180,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
@@ -189,6 +195,7 @@ module PostHog
     # @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
@@ -268,9 +275,10 @@ module PostHog
     # @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)
 
@@ -295,6 +303,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
@@ -309,6 +318,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
@@ -320,23 +330,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,
@@ -366,8 +385,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
@@ -379,8 +398,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.
     #
@@ -420,6 +441,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,
@@ -456,7 +485,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
@@ -580,6 +610,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(
@@ -602,11 +633,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(
@@ -639,10 +671,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,
@@ -664,6 +696,9 @@ module PostHog
       response
     end
 
+    # Reload locally cached feature flag definitions.
+    #
+    # @return [void]
     def reload_feature_flags
       unless @personal_api_key
         logger.error(
@@ -674,6 +709,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
@@ -723,11 +761,22 @@ module PostHog
     # 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.
+    # Group context is included in the dedup key so group-scoped flags fire a
+    # separate event for each group a user is evaluated under.
     def _capture_feature_flag_called_if_needed(
       distinct_id: nil, key: nil, response: nil, properties: nil,
       groups: nil, disable_geoip: nil
     )
-      reported_key = "#{key}_#{response.nil? ? '::null::' : response}"
+      response_repr = response.nil? ? '::null::' : response
+      groups_repr =
+        if groups && !groups.empty?
+          # Canonicalize so two equal hashes with keys inserted in a different
+          # order produce the same dedup key.
+          "_#{groups.sort.to_json}"
+        else
+          ''
+        end
+      reported_key = "#{key}_#{response_repr}#{groups_repr}"
       return if @distinct_id_has_sent_flag_calls[distinct_id].include?(reported_key)
 
       msg = {

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/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.9.0'
+  VERSION = '3.9.2'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: posthog-ruby
 version: !ruby/object:Gem::Version
-  version: 3.9.0
+  version: 3.9.2
 platform: ruby
 authors:
 - ''