posthog-ruby 3.9.1 → 3.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1388daa77d143c2822f15642b375b1e833a893d86677337d0d8bfc88875b364c
-  data.tar.gz: 2e71adb4fdc958bd8793515dbb3317652d9e811166678e7e38c57e57a85f3a08
+  metadata.gz: caf866cb91c9fb07b894b6af005decf79644ddc3c2a7c2f84dc3dd59ac9350b1
+  data.tar.gz: 6aace1e7809b8f2c6f8529086aaaf8cceb44d5f47b515222d0eeb0e757a66617
 SHA512:
-  metadata.gz: a3ab6ee23fabf6375facb994ed3a16de3ec21ec53c88da0121fe3158d9b6552127d081124bb02870ca0b04d47bd2df4a79b7a95c45d8991095e2a4cbdfc63d09
-  data.tar.gz: ae04e209088f84ccb2760f0dc5fc3760cfb25e2ecd452201cf16b5432e4761acd63ef9471fc87cf88e21a1d16ce744191ea7ed6a445b2544fcf3e3a0f2f1040a
+  metadata.gz: ec98d033a36bd7069b001e957fd5a395d54225f505717c45322faa8ce157d00a8fdb1275b5ac4f098e3c51e78a8b2b13a11a94d76be7d50be9b87ab469da3285
+  data.tar.gz: c0122abe71ac22a9075236b167c4a136c156f8af6853252f0caf18e4c7f41f8ccdd4b2132481d1138a6ec44793efef8d14ed35c3b7aa5769f45b20babd1ebae9

data/lib/posthog/client.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'time'
+require 'json'
 require 'securerandom'
 
 require 'posthog/defaults'
@@ -51,7 +52,7 @@ module PostHog
     end
 
     # @param opts [Hash] Client configuration.
-    # @option opts [String] :api_key Your project's API key. Required.
+    # @option opts [String, nil] :api_key Your project's API key. Missing or blank values disable the client.
     # @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.
@@ -71,7 +72,10 @@ module PostHog
     # @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.
+    #   interface for distributed flag definition caching.
+    # @option opts [Boolean] :is_server +true+ to stamp captured events with `$is_server => true` so PostHog
+    #   attributes them as server-side. Defaults to +true+. Set to +false+ when running posthog-ruby as a
+    #   client/CLI so the device OS is attributed normally and `$is_server` is omitted.
     def initialize(opts = {})
       symbolize_keys!(opts)
 
@@ -81,11 +85,12 @@ module PostHog
 
       @queue = Queue.new
       @api_key = opts[:api_key]
+      @disabled = @api_key.nil? || @api_key.empty?
       @max_queue_size = opts[:max_queue_size] || Defaults::Queue::MAX_SIZE
       @worker_mutex = Mutex.new
-      @sync_mode = opts[:sync_mode] == true && !opts[:test_mode]
+      @sync_mode = opts[:sync_mode] == true && !opts[:test_mode] && !@disabled
       @on_error = opts[:on_error] || proc { |status, error| }
-      @worker = if opts[:test_mode]
+      @worker = if opts[:test_mode] || @disabled
                   NoopWorker.new(@queue)
                 elsif @sync_mode
                   nil
@@ -104,11 +109,12 @@ module PostHog
       @feature_flags_poller = nil
       @personal_api_key = opts[:personal_api_key]
 
-      check_api_key!
-      logger.error('api_key is empty after trimming whitespace; check your project API key') if @api_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 opts[:test_mode] || opts[:disable_singleton_warning]
+      unless @disabled || opts[:test_mode] || opts[:disable_singleton_warning]
         previous_count = self.class._increment_instance_count(@api_key)
         if previous_count >= 1
           logger.warn(
@@ -120,22 +126,25 @@ module PostHog
         end
       end
 
-      @feature_flags_poller =
-        FeatureFlagsPoller.new(
-          opts[:feature_flags_polling_interval],
-          opts[:personal_api_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]
-        )
+      unless @disabled
+        @feature_flags_poller =
+          FeatureFlagsPoller.new(
+            opts[:feature_flags_polling_interval],
+            opts[:personal_api_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]
+          )
+      end
 
       @distinct_id_has_sent_flag_calls = SizeLimitedHash.new(Defaults::MAX_HASH_SIZE) do |hash, key|
         hash[key] = []
       end
 
       @before_send = opts[:before_send]
+      @is_server = opts.fetch(:is_server, true) != false
       @deprecation_emitted_for = Concurrent::Set.new
     end
 
@@ -197,6 +206,8 @@ module PostHog
     # @return [Boolean] Whether the event was queued or sent.
     # @macro common_attrs
     def capture(attrs)
+      return false if @disabled
+
       symbolize_keys! attrs
       enrich_capture_attrs_with_context(attrs)
 
@@ -225,7 +236,7 @@ module PostHog
       end
 
       send_feature_flags_param = attrs[:send_feature_flags]
-      if send_feature_flags_param
+      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 ' \
@@ -265,6 +276,7 @@ module PostHog
         attrs[:feature_variants] = feature_variants if feature_variants
       end
 
+      attrs[:is_server] = @is_server
       enqueue(FieldParser.parse_for_capture(attrs))
     end
 
@@ -279,6 +291,8 @@ module PostHog
     #   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)
+      return false if @disabled
+
       exception_info = ExceptionCapture.build_parsed_exception(exception)
 
       return if exception_info.nil?
@@ -305,7 +319,10 @@ module PostHog
     # @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
       enqueue(FieldParser.parse_for_identify(attrs))
     end
 
@@ -320,7 +337,10 @@ module PostHog
     # @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
       enqueue(FieldParser.parse_for_group_identify(attrs))
     end
 
@@ -332,7 +352,10 @@ module PostHog
     # @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
       enqueue(FieldParser.parse_for_alias(attrs))
     end
 
@@ -387,6 +410,8 @@ module PostHog
     # @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
 
@@ -464,6 +489,8 @@ module PostHog
         '`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,
@@ -506,6 +533,8 @@ module PostHog
         return FeatureFlagEvaluations.new(host: host, distinct_id: '', flags: {})
       end
 
+      return FeatureFlagEvaluations.new(host: host, distinct_id: distinct_id, flags: {}, groups: groups) if @disabled
+
       person_properties, group_properties = add_local_person_and_group_properties(
         distinct_id, groups, person_properties, group_properties
       )
@@ -619,6 +648,8 @@ module PostHog
       group_properties: {},
       only_evaluate_locally: false
     )
+      return {} if @disabled
+
       person_properties, group_properties = add_local_person_and_group_properties(distinct_id, groups,
                                                                                   person_properties, group_properties)
       @feature_flags_poller.get_all_flags(distinct_id, groups, person_properties, group_properties,
@@ -656,6 +687,8 @@ module PostHog
         '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(distinct_id, groups,
                                                                                   person_properties, group_properties)
@@ -682,6 +715,8 @@ module PostHog
       group_properties: {},
       only_evaluate_locally: false
     )
+      return { featureFlags: {}, featureFlagPayloads: {} } if @disabled
+
       person_properties, group_properties = add_local_person_and_group_properties(
         distinct_id, groups, person_properties, group_properties
       )
@@ -699,6 +734,8 @@ module PostHog
     #
     # @return [void]
     def reload_feature_flags
+      return if @disabled
+
       unless @personal_api_key
         logger.error(
           'You need to specify a personal_api_key to locally evaluate feature flags'
@@ -712,8 +749,8 @@ module PostHog
     #
     # @return [void]
     def shutdown
-      self.class._decrement_instance_count(@api_key) if @api_key
-      @feature_flags_poller.shutdown_poller
+      self.class._decrement_instance_count(@api_key) unless @disabled
+      @feature_flags_poller&.shutdown_poller
       flush
       if @sync_mode
         @sync_lock.synchronize { @transport&.shutdown }
@@ -760,11 +797,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 = {
@@ -798,6 +846,8 @@ module PostHog
       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(
         distinct_id, groups, person_properties, group_properties
@@ -863,6 +913,8 @@ module PostHog
     #
     # returns Boolean of whether the item was added to the queue.
     def enqueue(action)
+      return false if @disabled
+
       action = process_before_send(action)
       return false if action.nil? || action.empty?
 
@@ -889,11 +941,6 @@ module PostHog
       end
     end
 
-    # private: Checks that the api_key is properly initialized
-    def check_api_key!
-      raise ArgumentError, 'API key must be initialized' if @api_key.nil?
-    end
-
     def normalize_string_option(value, blank_as_nil: false)
       return value unless value.is_a?(String)
 

data/lib/posthog/field_parser.rb

@@ -89,11 +89,11 @@ module PostHog
         common.merge(
           {
             event: '$groupidentify',
-            properties: {
+            properties: (common[:properties] || {}).merge(
               '$group_type': group_type,
               '$group_key': group_key,
-              '$group_set': properties.merge(common[:properties] || {})
-            }
+              '$group_set': properties
+            )
           }
         )
       end
@@ -141,16 +141,21 @@ module PostHog
         check_timestamp! timestamp
         check_presence! distinct_id, 'distinct_id'
 
+        is_server = fields.fetch(:is_server, true) != false
+
+        properties = {
+          '$lib' => 'posthog-ruby',
+          '$lib_version' => PostHog::VERSION.to_s
+        }
+        properties['$is_server'] = true if is_server
+
         parsed = {
           timestamp: datetime_in_iso8601(timestamp),
           library: 'posthog-ruby',
           library_version: PostHog::VERSION.to_s,
           messageId: message_id,
           distinct_id: distinct_id,
-          properties: {
-            '$lib' => 'posthog-ruby',
-            '$lib_version' => PostHog::VERSION.to_s
-          }
+          properties: properties
         }
 
         if send_feature_flags && fields[:feature_variants]

data/lib/posthog/flag_definition_cache.rb

@@ -3,8 +3,6 @@
 module PostHog
   # Interface for external caching of feature flag definitions.
   #
-  # EXPERIMENTAL: This API may change in future minor version bumps.
-  #
   # Enables multi-worker environments (Kubernetes, load-balanced servers,
   # serverless functions) to share flag definitions via an external cache,
   # reducing redundant API calls.

data/lib/posthog/version.rb

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

metadata

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