txlemetry-ruby 4.0.0

data/lib/txlemetry/client.rb

@@ -0,0 +1,1266 @@
+# frozen_string_literal: true
+
+require 'time'
+require 'json'
+require 'securerandom'
+
+require 'txlemetry/defaults'
+require 'txlemetry/logging'
+require 'txlemetry/utils'
+require 'txlemetry/send_worker'
+require 'txlemetry/noop_worker'
+require 'txlemetry/message_batch'
+require 'txlemetry/transport'
+require 'txlemetry/feature_flags'
+require 'txlemetry/feature_flag_evaluations'
+require 'txlemetry/send_feature_flags_options'
+require 'txlemetry/exception_capture'
+require 'txlemetry/internal/context'
+
+module Txlemetry
+  class Client
+    include Txlemetry::Utils
+    include Txlemetry::Logging
+
+    # Strict allowlist of properties kept on minimal `$feature_flag_called`
+    # events (server-gated, non-experiment flags only). Everything else —
+    # context properties, `$feature/<key>`, payloads, system metadata — is
+    # stripped. Includes symbol forms so allowlisted properties supplied
+    # through context with symbol keys survive.
+    MINIMAL_FLAG_CALLED_EVENT_PROPERTIES = %w[
+      $feature_flag
+      $feature_flag_response
+      $feature_flag_has_experiment
+      $feature_flag_id
+      $feature_flag_version
+      $feature_flag_reason
+      $feature_flag_request_id
+      $feature_flag_evaluated_at
+      $feature_flag_error
+      locally_evaluated
+      $groups
+      $process_person_profile
+      $session_id
+      $is_server
+      $lib
+      $lib_version
+      $release_id
+    ].flat_map { |key| [key, key.to_sym] }.freeze
+    private_constant :MINIMAL_FLAG_CALLED_EVENT_PROPERTIES
+
+    # Holds the id that `txlemetry-cli release resolve` prints. Error tracking
+    # links an exception to its release by this id, because a Ruby app has no
+    # build step that could inject it.
+    RELEASE_ID_ENV_VAR = 'TXLEMETRY_RELEASE_ID'
+    private_constant :RELEASE_ID_ENV_VAR
+
+    # Thread-safe tracking of client instances per API key for singleton warnings
+    @instances_by_api_key = {}
+    @instances_mutex = Mutex.new
+
+    class << self
+      # Resets instance tracking. Used primarily for testing.
+      # In production, instance counts persist for the lifetime of the process.
+      def reset_instance_tracking!
+        @instances_mutex.synchronize do
+          @instances_by_api_key = {}
+        end
+      end
+
+      def _increment_instance_count(api_key)
+        @instances_mutex.synchronize do
+          count = @instances_by_api_key[api_key] || 0
+          @instances_by_api_key[api_key] = count + 1
+          count
+        end
+      end
+
+      def _decrement_instance_count(api_key)
+        @instances_mutex.synchronize do
+          count = (@instances_by_api_key[api_key] || 1) - 1
+          @instances_by_api_key[api_key] = [count, 0].max
+        end
+      end
+    end
+
+    # @param opts [Hash] Client configuration.
+    # @option opts [String, nil] :api_key Your project's API key. Missing or blank values disable the client.
+    # @option opts [String, nil] :secret_key The credential used for local feature flag evaluation and remote
+    #   config. Accepts either a Personal API Key (`phx_...`) or a Project Secret API Key (`phs_...`). Required
+    #   for local feature flag evaluation.
+    # @option opts [String, nil] :personal_api_key
+    #   @deprecated Use +:secret_key+ instead. Retained as an alias; when both are supplied, +:secret_key+ wins.
+    # @option opts [String] :host Fully qualified hostname of the Txlemetry server. Defaults to `https://app.txlemetry.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 [Numeric] :flush_interval_seconds Maximum seconds to wait for an async batch to fill before sending.
+    #   Defaults to 5.
+    # @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 [Integer] :max_retries How many times to retry batch uploads after the first send attempt.
+    #   Defaults to the transport default. Set to 0 to disable retrying.
+    # @option opts [Integer] :feature_flag_request_max_retries How many times to retry a flag request after a
+    #   transient network error. Each retry sleeps on the calling thread before retrying, so this adds to
+    #   worst-case latency. Defaults to 1. Set to 0 to disable retrying.
+    # @option opts [Boolean] :feature_flags_async_load +true+ to fetch feature flag definitions for local
+    #   evaluation only on the poller's background thread instead of the calling thread. The constructor
+    #   returns without waiting for definitions: the poller fetches immediately on boot and, if that fails,
+    #   keeps retrying on its regular polling interval until a load succeeds. Until then local evaluation
+    #   treats definitions as absent (check {#feature_flags_loaded?}), so evaluations return nil with
+    #   +only_evaluate_locally: true+, or fall back to the remote flags endpoint (which still runs on the
+    #   calling thread) without it. Defaults to +false+.
+    # @option opts [Proc] :before_send A callback that receives the event hash and should return either a modified
+    #   hash to be sent to Txlemetry 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 [Boolean] :compress_request Set to +false+ to disable gzip compression for batch uploads.
+    # @option opts [Object] :flag_definition_cache_provider An object implementing the {FlagDefinitionCacheProvider}
+    #   interface for distributed flag definition caching.
+    # @option opts [Boolean] :is_server +true+ to stamp captured events with `$is_server => true` so Txlemetry
+    #   attributes them as server-side. Defaults to +true+. Set to +false+ when running txlemetry-ruby as a
+    #   client/CLI so the device OS is attributed normally and `$is_server` is omitted.
+    def initialize(opts = {})
+      symbolize_keys!(opts)
+
+      opts[:api_key] = normalize_string_option(opts[:api_key])
+      opts[:secret_key] = normalize_string_option(opts[:secret_key], blank_as_nil: true)
+      opts[:personal_api_key] = normalize_string_option(opts[:personal_api_key], blank_as_nil: true)
+      opts[:host] = normalize_host_option(opts[:host])
+
+      if opts[:secret_key].nil? && !opts[:personal_api_key].nil?
+        logger.warn(
+          'The :personal_api_key option is deprecated; use :secret_key instead. It accepts either a ' \
+          'Personal API Key (phx_...) or a Project Secret API Key (phs_...).'
+        )
+      end
+      secret_key = opts[:secret_key] || opts[:personal_api_key]
+
+      @queue = Queue.new
+      @queue_mutex = Mutex.new
+      @api_key = opts[:api_key]
+      @disabled = @api_key.nil? || @api_key.empty?
+      @max_queue_size = opts[:max_queue_size] || Defaults::Queue::MAX_SIZE
+      @lib = opts[:_lib] || 'txlemetry-ruby'
+      @lib_version = (opts[:_lib_version] || Txlemetry::VERSION).to_s
+      @headers = Defaults::Request::HEADERS.merge('User-Agent' => "#{@lib}/#{@lib_version}")
+      @worker_mutex = Mutex.new
+      @shutdown_mutex = Mutex.new
+      @shutdown_condition = ConditionVariable.new
+      @shutdown = false
+      @shutdown_complete = false
+      @shutdown_result = false
+      @sync_mode = opts[:sync_mode] == true && !opts[:test_mode] && !@disabled
+      @on_error = opts[:on_error] || proc { |status, error| }
+      @worker = if opts[:test_mode] || @disabled
+                  NoopWorker.new(@queue)
+                elsif @sync_mode
+                  nil
+                else
+                  SendWorker.new(@queue, @api_key, opts.merge(headers: @headers))
+                end
+      if @sync_mode
+        @transport = Transport.new(
+          api_host: opts[:host],
+          headers: @headers,
+          skip_ssl_verification: opts[:skip_ssl_verification],
+          retries: opts.key?(:max_retries) ? opts[:max_retries].to_i + 1 : 3,
+          compress_request: opts[:compress_request]
+        )
+        @sync_lock = Mutex.new
+      end
+      @worker_thread = nil
+      @feature_flags_poller = nil
+      @secret_key = secret_key
+      @personal_api_key = secret_key
+
+      if @disabled && !opts[:silence_disabled_client_error]
+        logger.error('api_key is missing or empty after trimming whitespace; check your project API key')
+      end
+
+      # Warn when multiple clients are created with the same API key (can cause dropped events)
+      unless @disabled || opts[:test_mode] || opts[:disable_singleton_warning]
+        previous_count = Txlemetry::Client._increment_instance_count(@api_key)
+        @instance_registered = true
+        if previous_count >= 1
+          logger.warn(
+            'Multiple Txlemetry client instances detected for the same API key. ' \
+            'This can cause dropped events and inconsistent behavior. ' \
+            'Use a singleton pattern: instantiate once and reuse the client. ' \
+            'See https://txlemetry.com/docs/libraries/ruby'
+          )
+        end
+      end
+
+      # Initialize tracking before the poller can load definitions (including async loads).
+      @distinct_id_has_sent_flag_calls_mutex = Mutex.new
+      @distinct_id_has_sent_flag_calls = SizeLimitedHash.new(Defaults::MAX_HASH_SIZE) do |hash, key|
+        hash[key] = SizeLimitedArray.new(Defaults::MAX_HASH_SIZE)
+      end
+
+      unless @disabled
+        @feature_flags_poller =
+          FeatureFlagsPoller.new(
+            opts[:feature_flags_polling_interval],
+            secret_key,
+            @api_key,
+            opts[:host],
+            opts[:feature_flag_request_timeout_seconds] || Defaults::FeatureFlags::FLAG_REQUEST_TIMEOUT_SECONDS,
+            opts[:on_error],
+            flag_definition_cache_provider: opts[:flag_definition_cache_provider],
+            feature_flag_request_max_retries: opts[:feature_flag_request_max_retries],
+            async_load: opts[:feature_flags_async_load] == true,
+            user_agent: @headers['User-Agent'],
+            flag_definitions_update_mutex: @distinct_id_has_sent_flag_calls_mutex,
+            on_flag_definitions_updated: -> { @distinct_id_has_sent_flag_calls.clear }
+          )
+      end
+
+      @before_send = opts[:before_send]
+      @is_server = opts.fetch(:is_server, true) != false
+      @release_id = normalize_string_option(ENV.fetch(RELEASE_ID_ENV_VAR) { ENV['POSTHOG_RELEASE_ID'] }, blank_as_nil: true)
+      @deprecation_emitted_for = Concurrent::Set.new
+    end
+
+    # When sync_mode is enabled, blocks until in-flight requests are complete
+    # and returns true. Timeout parameter has no effect.
+    #
+    # Otherwise, waits until the worker has cleared the queue or timeout is hit.
+    # Note: The asynchronous wait polls and can be starved if another thread is
+    # actively continuing to enqueue new events.
+    #
+    # @param timeout [Numeric, nil] Maximum seconds to wait for pending events
+    #   to be sent, or +nil+ to wait indefinitely.
+    # @return [Boolean] +true+ if all pending events were sent, +false+ if the
+    #   timeout elapsed first.
+    def flush(timeout: nil)
+      if @sync_mode
+        # Wait for any in-flight sync send to complete
+        @sync_lock.synchronize {} # rubocop:disable Lint/EmptyBlock
+        return true
+      end
+
+      if @worker.is_a?(NoopWorker)
+        clear
+        return true
+      end
+
+      deadline = timeout && (monotonic_time + timeout)
+
+      while !@queue.empty? || @worker.is_requesting?
+        ensure_worker_running
+        @worker.request_flush
+        remaining = deadline && (deadline - monotonic_time)
+        return false if remaining && remaining <= 0
+
+        sleep(remaining ? remaining.clamp(0, 0.1) : 0.1)
+      end
+      true
+    end
+
+    # Clears the queue without waiting.
+    #
+    # Use only in test mode.
+    #
+    # @return [void]
+    def clear
+      @queue_mutex.synchronize { @queue.clear }
+    end
+
+    # @!macro common_attrs
+    #   @option attrs [String] :message_id Deprecated. Use `:uuid` instead. If `:uuid` is absent or
+    #     invalid and `:message_id` is a valid UUID, it is sent as `uuid` for backwards compatibility.
+    #     If neither value is valid, the SDK generates a `uuid`. SDK metadata is sent as `$lib` and
+    #     `$lib_version` properties.
+    #   @option attrs [Time] :timestamp When the event occurred (optional). UTC is preferred;
+    #     non-UTC values are converted to the equivalent UTC instant before serialization.
+    #   @option attrs [String] :distinct_id The ID for this user in your database
+
+    # Captures an event
+    #
+    # @param [Hash] attrs
+    #
+    # @option attrs [String] :event Event name
+    # @option attrs [Hash] :properties Event properties (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 [Txlemetry::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
+    #   takes precedence over `:send_feature_flags`.
+    # @option attrs [String] :uuid ID that uniquely identifies an event;
+    #                             events in Txlemetry 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)
+      return false if @disabled
+
+      symbolize_keys! attrs
+      minimal_flag_called_event = attrs.delete(:_minimal_flag_called_event) == true
+      # Integrations that ride on a host application's client (e.g. Txlemetry::MCP)
+      # may relabel a single event's `$lib`/`$lib_version` without relabeling the
+      # client or its User-Agent.
+      lib_override = attrs.delete(:_lib)
+      lib_version_override = attrs.delete(:_lib_version)
+      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
+      # values the developer branched on with no additional network call.
+      if attrs[:flags]
+        if attrs[:flags].is_a?(FeatureFlagEvaluations)
+          if attrs[:send_feature_flags]
+            logger.warn(
+              '[FEATURE FLAGS] Both `flags` and `send_feature_flags` were passed to ' \
+              'capture(); using `flags` and ignoring `send_feature_flags`.'
+            )
+          end
+          snapshot_props = attrs[:flags]._get_event_properties
+          attrs[:properties] = snapshot_props.merge(attrs[:properties] || {})
+          attrs.delete(:flags)
+          attrs.delete(:send_feature_flags)
+        else
+          logger.warn(
+            '[FEATURE FLAGS] capture(flags:) expects a Txlemetry::FeatureFlagEvaluations snapshot ' \
+            "from `client.evaluate_flags(...)`; got #{attrs[:flags].class}. Ignoring."
+          )
+          attrs.delete(:flags)
+        end
+      end
+
+      send_feature_flags_param = attrs[:send_feature_flags]
+      if send_feature_flags_param && !@disabled
+        _emit_deprecation(
+          :capture_send_feature_flags,
+          '`send_feature_flags` on `capture` is deprecated and will be removed in a future major ' \
+          'version. Pass a `flags` snapshot from `client.evaluate_flags(...)` instead — it ' \
+          'avoids a second `/flags` request per capture and guarantees the event carries the ' \
+          'exact flag values your code branched on.'
+        )
+        # Handle different types of send_feature_flags parameter
+        case send_feature_flags_param
+        when true
+          # Backward compatibility: simple boolean
+          feature_variants = @feature_flags_poller.get_feature_variants(attrs[:distinct_id], attrs[:groups] || {})
+        when Hash
+          # Hash with options
+          options = SendFeatureFlagsOptions.from_hash(send_feature_flags_param)
+          feature_variants = @feature_flags_poller.get_feature_variants(
+            attrs[:distinct_id],
+            attrs[:groups] || {},
+            options ? options.person_properties : {},
+            options ? options.group_properties : {},
+            options ? options.only_evaluate_locally : false
+          )
+        when SendFeatureFlagsOptions
+          # SendFeatureFlagsOptions object
+          feature_variants = @feature_flags_poller.get_feature_variants(
+            attrs[:distinct_id],
+            attrs[:groups] || {},
+            send_feature_flags_param.person_properties,
+            send_feature_flags_param.group_properties,
+            send_feature_flags_param.only_evaluate_locally || false
+          )
+        else
+          # Invalid type, treat as false
+          feature_variants = nil
+        end
+
+        attrs[:feature_variants] = feature_variants if feature_variants
+      end
+
+      attrs[:is_server] = @is_server
+      attrs[:lib] = lib_override || @lib
+      attrs[:lib_version] = (lib_version_override || @lib_version).to_s
+      message = FieldParser.parse_for_capture(attrs)
+      # Minimal events are built from the allowlist after full assembly so
+      # context properties and parser-added metadata can never leak in.
+      if minimal_flag_called_event
+        message[:properties] = message[:properties].slice(*MINIMAL_FLAG_CALLED_EVENT_PROPERTIES)
+      end
+      enqueue(message)
+    end
+
+    # 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 request/context distinct_id
+    #   or a generated UUID)
+    # @param [Hash] additional_properties Additional properties to include with the exception event (optional)
+    # @param flags [Txlemetry::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.
+    # @param mechanism [Hash, nil] How the exception was captured, e.g.
+    #   `{ 'type' => 'rails', 'handled' => false }` for automatic integrations.
+    #   Defaults to `{ 'type' => 'generic', 'handled' => true }` for manual captures.
+    # @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, mechanism: nil)
+      return false if @disabled
+
+      exception_list = ExceptionCapture.build_exception_list(exception, mechanism: mechanism)
+
+      return if exception_list.nil?
+
+      properties = { '$exception_list' => exception_list }
+      properties.merge!(additional_properties) if additional_properties && !additional_properties.empty?
+
+      event_data = {
+        distinct_id: distinct_id,
+        event: '$exception',
+        properties: properties,
+        timestamp: Time.now
+      }
+      event_data[:flags] = flags if flags
+
+      capture(event_data)
+    end
+
+    # Identifies a user
+    #
+    # @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)
+      return false if @disabled
+
+      symbolize_keys! attrs
+      attrs[:is_server] = @is_server
+      attrs[:lib] = @lib
+      attrs[:lib_version] = @lib_version
+      enqueue(FieldParser.parse_for_identify(attrs))
+    end
+
+    # Identifies a group
+    #
+    # @param [Hash] attrs
+    #
+    # @option attrs [String] :group_type Group type
+    # @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)
+      return false if @disabled
+
+      symbolize_keys! attrs
+      attrs[:is_server] = @is_server
+      attrs[:lib] = @lib
+      attrs[:lib_version] = @lib_version
+      enqueue(FieldParser.parse_for_group_identify(attrs))
+    end
+
+    # Aliases a user from one id to another
+    #
+    # @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)
+      return false if @disabled
+
+      symbolize_keys! attrs
+      attrs[:is_server] = @is_server
+      attrs[:lib] = @lib
+      attrs[:lib_version] = @lib_version
+      enqueue(FieldParser.parse_for_alias(attrs))
+    end
+
+    # @return [Hash] Pops the last message from the queue. Intended for test mode.
+    def dequeue_last_message
+      @queue.pop
+    end
+
+    # @return [Integer] Number of messages in the queue. Intended for test mode.
+    def queued_messages
+      @queue.length
+    end
+
+    # @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/PredicatePrefix
+      flag_key,
+      distinct_id,
+      groups: {},
+      person_properties: {},
+      group_properties: {},
+      only_evaluate_locally: false,
+      send_feature_flag_events: true
+    )
+      _emit_deprecation(
+        :is_feature_enabled,
+        '`is_feature_enabled` is deprecated and will be removed in a future major version. ' \
+        'Use `client.evaluate_flags(distinct_id, ...)` and call `flags.enabled?(key)` instead — ' \
+        'this consolidates flag evaluation into a single `/flags` request per incoming request.'
+      )
+      # Bypass the public `get_feature_flag` so the user only sees a single deprecation
+      # warning per call, not a cascade.
+      result = _get_feature_flag_result(
+        flag_key, distinct_id,
+        groups: groups, person_properties: person_properties, group_properties: group_properties,
+        only_evaluate_locally: only_evaluate_locally, send_feature_flag_events: send_feature_flag_events
+      )
+      response = result&.value
+      return nil if response.nil?
+
+      !!response
+    end
+
+    # @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)
+      return nil if @disabled
+
+      @feature_flags_poller.get_remote_config_payload(flag_key.to_s)
+    end
+
+    # Returns whether the given feature flag is enabled for the given user or not
+    #
+    # @param [String, Symbol] key The key of the feature flag
+    # @param [String] distinct_id The distinct id of the user
+    # @param [Hash] groups
+    # @param [Hash] person_properties key-value pairs of properties to associate with the user.
+    # @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, Boolean, nil] The value of the feature flag
+    #
+    # The provided properties are used to calculate feature flags locally, if possible.
+    #
+    # `groups` are a mapping from group type to group key. So, if you have a group type of "organization"
+    # and a group key of "5",
+    # you would pass groups={"organization": "5"}.
+    # `group_properties` take the format: { group_type_name: { group_properties } }
+    # So, for example, if you have the group type "organization" and the group key "5", with the properties name,
+    # and employee count, you'll send these as:
+    # ```ruby
+    #     group_properties: {"organization": {"name": "Txlemetry", "employees": 11}}
+    # ```
+    # @deprecated Use {#evaluate_flags} and {FeatureFlagEvaluations#get_flag} instead.
+    def get_feature_flag(
+      key,
+      distinct_id,
+      groups: {},
+      person_properties: {},
+      group_properties: {},
+      only_evaluate_locally: false,
+      send_feature_flag_events: true
+    )
+      _emit_deprecation(
+        :get_feature_flag,
+        '`get_feature_flag` is deprecated and will be removed in a future major version. ' \
+        'Use `client.evaluate_flags(distinct_id, ...)` and call `flags.get_flag(key)` instead — ' \
+        'this consolidates flag evaluation into a single `/flags` request per incoming request.'
+      )
+      # Bypass the public `get_feature_flag_result` so the user only sees one deprecation warning.
+      result = _get_feature_flag_result(
+        key, distinct_id,
+        groups: groups, person_properties: person_properties, group_properties: group_properties,
+        only_evaluate_locally: only_evaluate_locally, send_feature_flag_events: send_feature_flag_events
+      )
+      result&.value
+    end
+
+    # @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 [Txlemetry::FeatureFlagResult, nil]
+    def get_feature_flag_result(
+      key,
+      distinct_id,
+      groups: {},
+      person_properties: {},
+      group_properties: {},
+      only_evaluate_locally: false,
+      send_feature_flag_events: true
+    )
+      _emit_deprecation(
+        :get_feature_flag_result,
+        '`get_feature_flag_result` is deprecated and will be removed in a future major version. ' \
+        'Use `client.evaluate_flags(distinct_id, ...)` and call `flags.get_flag(key)` / ' \
+        '`flags.get_flag_payload(key)` instead — this consolidates flag evaluation into a single ' \
+        '`/flags` request per incoming request.'
+      )
+      return nil if @disabled
+
+      _get_feature_flag_result(
+        key, distinct_id,
+        groups: groups, person_properties: person_properties, group_properties: group_properties,
+        only_evaluate_locally: only_evaluate_locally, send_feature_flag_events: send_feature_flag_events
+      )
+    end
+
+    # Evaluate feature flags for a distinct id and return a snapshot.
+    #
+    # The returned {Txlemetry::FeatureFlagEvaluations} can be queried with
+    # `is_enabled` / `get_flag` / `get_flag_payload`, narrowed with
+    # `only_accessed` / `only`, and passed to {#capture} via the `flags:` option
+    # to attach `$feature/<key>` and `$active_feature_flags` without an extra
+    # /flags request.
+    #
+    # @param [String] distinct_id The distinct id of the user
+    # @param [Hash] groups
+    # @param [Hash] person_properties key-value pairs of properties to associate with the user
+    # @param [Hash] group_properties
+    # @param [Boolean] only_evaluate_locally Skip the remote /flags call entirely
+    # @param [Boolean, nil] disable_geoip When true, disables GeoIP lookup for remote evaluation and stamps captured
+    #   access events.
+    # @param [Array<String, Symbol>, nil] flag_keys When set, scopes evaluation to only these flag keys.
+    #   An empty array returns an empty snapshot without evaluating flags; +nil+ evaluates all flags.
+    #   Distinct from {FeatureFlagEvaluations#only}, which filters the already-fetched snapshot in memory.
+    # @return [Txlemetry::FeatureFlagEvaluations]
+    def evaluate_flags(
+      distinct_id,
+      groups: {},
+      person_properties: {},
+      group_properties: {},
+      only_evaluate_locally: false,
+      disable_geoip: nil,
+      flag_keys: nil
+    )
+      host = _feature_flag_evaluations_host
+
+      if distinct_id.nil? || distinct_id.to_s.empty?
+        return FeatureFlagEvaluations.new(host: host, distinct_id: '', flags: {})
+      end
+
+      return FeatureFlagEvaluations.new(host: host, distinct_id: distinct_id, flags: {}, groups: groups) if @disabled
+
+      if flag_keys && flag_keys.empty?
+        return FeatureFlagEvaluations.new(
+          host: host, distinct_id: distinct_id, flags: {}, groups: groups, disable_geoip: disable_geoip
+        )
+      end
+
+      person_properties, group_properties = add_local_person_and_group_properties(
+        groups, person_properties, group_properties
+      )
+
+      records = {}
+      locally_evaluated_keys = Set.new
+      flag_keys_set = flag_keys&.to_set(&:to_s)
+
+      @feature_flags_poller.load_feature_flags
+      definition_snapshot = @feature_flags_poller._evaluation_snapshot
+      poller_flags_by_key = definition_snapshot[:flags_by_key] || {}
+
+      poller_flags_by_key.each do |key, definition|
+        next if flag_keys_set && !flag_keys_set.include?(key.to_s)
+
+        begin
+          match = @feature_flags_poller.send(
+            :_compute_flag_locally,
+            definition, distinct_id, groups, person_properties, group_properties, snapshot: definition_snapshot
+          )
+        rescue Txlemetry::RequiresServerEvaluation, Txlemetry::InconclusiveMatchError, StandardError
+          next
+        end
+
+        next if match.nil?
+
+        records[key.to_s] = FeatureFlagEvaluations::EvaluatedFlagRecord.new(
+          key: key.to_s,
+          enabled: match.is_a?(String) || (match ? true : false),
+          variant: match.is_a?(String) ? match : nil,
+          payload: FeatureFlagResult.parse_payload(
+            @feature_flags_poller.send(:_compute_flag_payload_locally, key, match, snapshot: definition_snapshot)
+          ),
+          id: definition[:id],
+          version: nil,
+          reason: FeatureFlagEvaluations::EVALUATED_LOCALLY_REASON,
+          locally_evaluated: true,
+          has_experiment: definition[:has_experiment]
+        )
+        locally_evaluated_keys << key.to_s
+      end
+
+      request_id = nil
+      evaluated_at = nil
+      errors_while_computing = false
+      quota_limited = false
+      # Server-controlled gate for minimal `$feature_flag_called` events. When
+      # the snapshot uses a remote /flags response, the response's top-level
+      # `minimalFlagCalledEvents` field governs; a local-only snapshot reads
+      # the gate polled with the flag definitions.
+      minimal_flag_called_events = definition_snapshot[:minimal_flag_called_events]
+
+      # Skip the remote `/flags` round-trip when the caller scoped the request
+      # to a fixed set of `flag_keys` and we've already resolved every one of
+      # them locally. Without `flag_keys` set, we can't know whether the server
+      # has flags we don't have definitions for, so we still hit `/flags`.
+      all_requested_flags_resolved_locally = flag_keys_set && (flag_keys_set - locally_evaluated_keys).empty?
+
+      if !only_evaluate_locally && !all_requested_flags_resolved_locally
+        # The gate is team-level, so the /flags response gate supersedes the
+        # poller gate for mixed snapshots — both signals come from the same
+        # server and agree in steady state. When the response omits the gate,
+        # the whole snapshot fails safe to full events.
+        minimal_flag_called_events = false
+        begin
+          flags_response = @feature_flags_poller.get_flags(
+            distinct_id, groups, person_properties, group_properties, flag_keys, disable_geoip
+          )
+          minimal_flag_called_events = flags_response[:minimalFlagCalledEvents] == true
+          request_id = flags_response[:requestId]
+          evaluated_at = flags_response[:evaluatedAt]
+          errors_while_computing = flags_response[:errorsWhileComputingFlags] == true
+          quota_limited = (flags_response[:quotaLimited] || []).include?('feature_flags')
+          remote_flags = flags_response[:flags] || {}
+          remote_flags.each do |key, ff|
+            key_str = key.to_s
+            next if locally_evaluated_keys.include?(key_str)
+
+            metadata = ff.metadata
+            reason = ff.reason
+            records[key_str] = FeatureFlagEvaluations::EvaluatedFlagRecord.new(
+              key: key_str,
+              enabled: ff.enabled ? true : false,
+              variant: ff.variant,
+              payload: FeatureFlagResult.parse_payload(ff.payload),
+              id: metadata&.id,
+              version: metadata&.version,
+              reason: reason ? (reason.description || reason.code) : nil,
+              locally_evaluated: false,
+              has_experiment: metadata&.has_experiment
+            )
+          end
+        rescue StandardError => e
+          @on_error&.call(-1, "Error evaluating flags remotely: #{e}")
+        end
+      end
+
+      FeatureFlagEvaluations.new(
+        host: host,
+        distinct_id: distinct_id,
+        flags: records,
+        groups: groups,
+        disable_geoip: disable_geoip,
+        request_id: request_id,
+        evaluated_at: evaluated_at,
+        flag_definitions_loaded_at: @feature_flags_poller.flag_definitions_loaded_at,
+        errors_while_computing: errors_while_computing,
+        quota_limited: quota_limited,
+        minimal_flag_called_events: minimal_flag_called_events
+      )
+    end
+
+    # Returns all flags for a given user
+    #
+    # @param [String] distinct_id The distinct id of the user
+    # @param [Hash] groups
+    # @param [Hash] person_properties key-value pairs of properties to associate with the user.
+    # @param [Hash] group_properties
+    # @param 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(
+      distinct_id,
+      groups: {},
+      person_properties: {},
+      group_properties: {},
+      only_evaluate_locally: false
+    )
+      return {} if @disabled
+
+      person_properties, group_properties = add_local_person_and_group_properties(groups, person_properties,
+                                                                                  group_properties)
+      @feature_flags_poller.get_all_flags(distinct_id, groups, person_properties, group_properties,
+                                          only_evaluate_locally)
+    end
+
+    # Returns payload for a given feature flag
+    #
+    # @deprecated Use {#get_feature_flag_result} instead, which returns both the flag value and payload
+    #   and properly raises the $feature_flag_called event.
+    #
+    # @param [String, Symbol] key The key of the feature flag
+    # @param [String] distinct_id The distinct id of the user
+    # @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(
+      key,
+      distinct_id,
+      match_value: nil,
+      groups: {},
+      person_properties: {},
+      group_properties: {},
+      only_evaluate_locally: false
+    )
+      _emit_deprecation(
+        :get_feature_flag_payload,
+        '`get_feature_flag_payload` is deprecated and will be removed in a future major version. ' \
+        'Use `client.evaluate_flags(distinct_id, ...)` and call `flags.get_flag_payload(key)` ' \
+        'instead — this consolidates flag evaluation into a single `/flags` request per ' \
+        'incoming request.'
+      )
+      return nil if @disabled
+
+      key = key.to_s
+      person_properties, group_properties = add_local_person_and_group_properties(groups, person_properties,
+                                                                                  group_properties)
+      @feature_flags_poller.get_feature_flag_payload(key, distinct_id, match_value, groups, person_properties,
+                                                     group_properties, only_evaluate_locally)
+    end
+
+    # Returns all flags and payloads for a given user
+    #
+    # @return [Hash] A hash with the following keys:
+    #   featureFlags: A hash of feature flags
+    #   featureFlagPayloads: A hash of feature flag payloads
+    #
+    # @param [String] distinct_id The distinct id of the user
+    # @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,
+      groups: {},
+      person_properties: {},
+      group_properties: {},
+      only_evaluate_locally: false
+    )
+      return { featureFlags: {}, featureFlagPayloads: {} } if @disabled
+
+      person_properties, group_properties = add_local_person_and_group_properties(
+        groups, person_properties, group_properties
+      )
+      response = @feature_flags_poller.get_all_flags_and_payloads(
+        distinct_id, groups, person_properties, group_properties, only_evaluate_locally
+      )
+
+      # Remove internal information
+      response.delete(:requestId)
+      response.delete(:evaluatedAt)
+      response.delete(:flagDetails)
+      response.delete(:minimalFlagCalledEvents)
+      response
+    end
+
+    # Reload locally cached feature flag definitions synchronously on the
+    # calling thread.
+    #
+    # @return [void]
+    def reload_feature_flags
+      return if @disabled
+
+      unless @secret_key
+        logger.error(
+          'You need to specify a secret_key to locally evaluate feature flags'
+        )
+        return
+      end
+      @feature_flags_poller.load_feature_flags(true)
+    end
+
+    # Whether feature flag definitions for local evaluation are currently loaded.
+    # False until the first successful load, and false again if a quota-limited
+    # (402) response discards the definitions.
+    #
+    # @return [Boolean]
+    def feature_flags_loaded?
+      return false if @disabled
+
+      @feature_flags_poller.definitions_loaded?
+    end
+
+    # Whether the client will actually send events. It is disabled when the
+    # api_key is missing or blank, in which case every capture call no-ops.
+    #
+    # @return [Boolean]
+    def enabled?
+      !@disabled
+    end
+
+    # Flush pending events and stop background resources.
+    #
+    # When sync_mode is not set, this method calls the flush method; see flush
+    # method documentation for timeout semantics. Unlike flush, this method
+    # stops the worker. So any events still queued after the timeout will not be
+    # sent. After the timeout, this method may wait up to one additional second
+    # for worker and transport cleanup, which may continue after it returns.
+    #
+    # @param timeout [Numeric, nil] Maximum seconds to wait for pending events
+    #   to be sent, or +nil+ to wait indefinitely. Has no effect when sync_mode
+    #   is true.
+    # @return [Boolean] +true+ if all pending events were sent, +false+ if the
+    #   timeout elapsed first.
+    def shutdown(timeout: nil)
+      deadline = timeout && (monotonic_time + timeout)
+      shutdown_result = @shutdown_mutex.synchronize do
+        if @shutdown
+          until @shutdown_complete
+            # Avoid deadlocking when an in-flight send's on_error callback
+            # re-enters shutdown while the original caller is waiting for it.
+            break if Thread.current == @worker_thread || (@sync_mode && @sync_lock.owned?)
+
+            remaining = deadline && (deadline - monotonic_time)
+            break if remaining && remaining <= 0
+
+            @shutdown_condition.wait(@shutdown_mutex, remaining)
+          end
+          @shutdown_complete ? @shutdown_result : false
+        else
+          @shutdown = true
+          nil
+        end
+      end
+      return shutdown_result unless shutdown_result.nil?
+
+      flushed = false
+      begin
+        Txlemetry::Client._decrement_instance_count(@api_key) if @instance_registered
+        @feature_flags_poller&.shutdown_poller
+        flushed =
+          if @sync_mode
+            # Waiting for @sync_lock lets any in-flight sync send finish before
+            # the connection is closed.
+            @sync_lock.synchronize { @transport&.shutdown }
+            true
+          else
+            drained = flush(timeout: timeout)
+            @worker&.shutdown
+            @worker_thread&.join(1)
+            drained
+          end
+        @distinct_id_has_sent_flag_calls_mutex.synchronize do
+          @distinct_id_has_sent_flag_calls.clear
+        end
+        flushed
+      ensure
+        @shutdown_mutex.synchronize do
+          @shutdown_result = flushed
+          @shutdown_complete = true
+          @shutdown_condition.broadcast
+        end
+      end
+    end
+
+    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.
+    # 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, minimal: false
+    )
+      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}"
+      should_capture = @distinct_id_has_sent_flag_calls_mutex.synchronize do
+        sent_keys = @distinct_id_has_sent_flag_calls[distinct_id]
+        if sent_keys.include?(reported_key)
+          false
+        else
+          sent_keys << reported_key
+          true
+        end
+      end
+      return unless should_capture
+
+      msg = {
+        distinct_id: distinct_id,
+        event: '$feature_flag_called',
+        properties: properties
+      }
+      msg[:groups] = groups if groups
+      msg[:disable_geoip] = disable_geoip unless disable_geoip.nil?
+      msg[:_minimal_flag_called_event] = true if minimal
+
+      capture(msg)
+    end
+
+    def _feature_flag_evaluations_host
+      @feature_flag_evaluations_host ||= FeatureFlagEvaluations::Host.new(
+        capture_flag_called_event_if_needed: method(:_capture_feature_flag_called_if_needed),
+        log_warning: ->(message) { logger.warn(message) }
+      )
+    end
+
+    # Implementation of {#get_feature_flag_result}, called by both the public
+    # method and the legacy `is_feature_enabled` / `get_feature_flag` paths so
+    # a single user-level call emits exactly one deprecation warning.
+    def _get_feature_flag_result(
+      key,
+      distinct_id,
+      groups: {},
+      person_properties: {},
+      group_properties: {},
+      only_evaluate_locally: false,
+      send_feature_flag_events: true
+    )
+      return nil if @disabled
+
+      key = key.to_s
+      person_properties, group_properties = add_local_person_and_group_properties(
+        groups, person_properties, group_properties
+      )
+      feature_flag_response, flag_was_locally_evaluated, request_id, evaluated_at, feature_flag_error, payload,
+        has_experiment, minimal_flag_called_events =
+        @feature_flags_poller.get_feature_flag(
+          key, distinct_id, groups, person_properties, group_properties, only_evaluate_locally
+        )
+      if send_feature_flag_events
+        properties = {
+          '$feature_flag' => key,
+          '$feature_flag_response' => feature_flag_response,
+          'locally_evaluated' => flag_was_locally_evaluated
+        }
+        properties['$feature_flag_has_experiment'] = has_experiment unless has_experiment.nil?
+        properties['$feature_flag_request_id'] = request_id if request_id
+        properties['$feature_flag_evaluated_at'] = evaluated_at if evaluated_at
+        properties['$feature_flag_error'] = feature_flag_error if feature_flag_error
+
+        # Emit a minimal event only when the server gate is on and the flag is
+        # known to have no linked experiment. Any missing signal fails safe to
+        # the full event.
+        minimal = minimal_flag_called_events == true && has_experiment == false
+        _capture_feature_flag_called_if_needed(
+          distinct_id: distinct_id, key: key, response: feature_flag_response,
+          properties: properties, groups: groups, minimal: minimal
+        )
+      end
+
+      FeatureFlagResult.from_value_and_payload(key, feature_flag_response, payload)
+    end
+
+    # Emits a deprecation warning at most once per `(method_name, process)` pair.
+    # Ruby's `Kernel.warn(..., category: :deprecated)` is suppressed by default
+    # since 2.7.2; we emit without the category so messages reach users on a
+    # default Ruby setup. Standard logger configuration / `$VERBOSE = nil` / IO
+    # redirection still silences as expected.
+    def _emit_deprecation(method_name, message)
+      return unless @deprecation_emitted_for.add?(method_name)
+
+      Kernel.warn("[txlemetry-ruby] DEPRECATION: #{message}", uplevel: 2)
+    end
+
+    # before_send should run immediately before the event is sent to the queue.
+    # @param [Object] action The event to be sent to Txlemetry
+    # @return [null, Object, nil] The processed event or nil if the event should not be sent
+    def process_before_send(action)
+      return action if action.nil? || action.empty?
+      return action unless @before_send
+
+      begin
+        processed_action = @before_send.call(action)
+
+        if processed_action.nil?
+          logger.warn("Event #{action[:event]} was rejected in beforeSend function")
+        elsif processed_action.empty?
+          logger.warn("Event #{action[:event]} has no properties after beforeSend function, this is likely an error")
+        end
+
+        processed_action
+      rescue StandardError => e
+        logger.error("Error in beforeSend function - dropping event: #{e.message}")
+        nil
+      end
+    end
+
+    # private: Enqueues the action.
+    #
+    # returns Boolean of whether the item was added to the queue.
+    def enqueue(action)
+      return false if @disabled || shutdown?
+
+      # Every event type passes through here, and before_send still sees the id.
+      action = add_release_id(action)
+      action = process_before_send(action)
+      return false if action.nil? || action.empty?
+
+      if @sync_mode
+        send_sync(action)
+        return true
+      end
+
+      queued = @queue_mutex.synchronize do
+        if @queue.length < @max_queue_size
+          @queue << action
+          true
+        else
+          false
+        end
+      end
+
+      if queued
+        ensure_worker_running
+        @worker.notify
+        true
+      else
+        logger.warn(
+          'Queue is full, dropping events. The :max_queue_size ' \
+          'configuration parameter can be increased to prevent this from ' \
+          'happening.'
+        )
+        false
+      end
+    end
+
+    # A `$release_id` the caller or the request context already set wins.
+    def add_release_id(action)
+      return action if @release_id.nil?
+
+      properties = action[:properties]
+      return action unless properties.is_a?(Hash)
+      return action if properties.key?('$release_id') || properties.key?(:$release_id)
+
+      action.merge(properties: properties.merge('$release_id' => @release_id))
+    end
+
+    def normalize_string_option(value, blank_as_nil: false)
+      return value unless value.is_a?(String)
+
+      normalized = value.strip
+      return nil if blank_as_nil && normalized.empty?
+
+      normalized
+    end
+
+    def normalize_host_option(host)
+      normalized = normalize_string_option(host)
+      return 'https://app.txlemetry.com' if normalized.nil? || normalized.empty?
+
+      normalized
+    end
+
+    def ensure_worker_running
+      return if worker_running?
+
+      @worker_mutex.synchronize do
+        return if worker_running?
+
+        @worker_thread = Thread.new { @worker.run }
+      end
+    end
+
+    def send_sync(action)
+      batch = MessageBatch.new(1)
+      begin
+        batch << action
+      rescue MessageBatch::JSONGenerationError => e
+        @on_error.call(-1, e.to_s)
+        return
+      end
+      return if batch.empty?
+
+      @sync_lock.synchronize do
+        res = @transport.send(@api_key, batch)
+        @on_error.call(res.status, res.error) unless res.status.between?(200, 299)
+      end
+    end
+
+    def worker_running?
+      @worker_thread&.alive?
+    end
+
+    def shutdown?
+      @shutdown_mutex.synchronize { @shutdown }
+    end
+
+    def add_local_person_and_group_properties(groups, person_properties, group_properties)
+      groups ||= {}
+      person_properties ||= {}
+      group_properties ||= {}
+
+      symbolize_keys! groups
+      symbolize_keys! person_properties
+      symbolize_keys! group_properties
+
+      group_properties.each_value do |value|
+        symbolize_keys! value
+      end
+
+      all_group_properties = {}
+      groups&.each do |group_name, group_key|
+        all_group_properties[group_name] = {
+          '$group_key': group_key
+        }.merge((group_properties && group_properties[group_name]) || {})
+      end
+
+      [person_properties, all_group_properties]
+    end
+  end
+end