posthog-ruby 3.17.0 → 3.19.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 187ed0ab3a49d0137a8a5516792d00eb6baf5242ed6665df879563656a6541ac
-  data.tar.gz: cf463f7135031a7d6975bac3eb72ad48ead37729c577738f80fe03e83a6c8f9c
+  metadata.gz: b23e0da0723e7582825d0888d8c6ffd9b3ad0a77e5eec513a40ab3de1faaa306
+  data.tar.gz: 1fc203c912147dc865cb342213ef8ccd3604e4d84f0b0005932c559aa30c8017
 SHA512:
-  metadata.gz: 5f0906fded5049de9de8638ffee0345e7db4bee9a73387fcc602247a9e62193e011fa89358a1001d8818ec216116aec3750548e0c056a6488a7c3360784da038
-  data.tar.gz: 5d7c036bfccdb96b1343287a7349c5ab95ec7184b88db2189f9ba4d805756e050edc3f14533517b79a30377253649ceb1ccecf95a0f9950fdc28812cf18ec629
+  metadata.gz: 8409ba6d5fb0801643cbd6556a1dabf41441ff522b85d612601ac8547482c5eb139ac68f21250f2f240654f08c03b3ca6cdc0409f57f1c6af9cdd880c677805f
+  data.tar.gz: c7a146c293985480777e6f5139588ca0d897170b8fe15412e9d60561711cb57bec53e70225b8b209916a50835f249b9816bece364be754a56e6f1118454feb52

data/lib/posthog/client.rb

@@ -53,7 +53,11 @@ module PostHog
 
     # @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] :personal_api_key Your personal API key. Required for local feature flag evaluation.
+    # @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 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.
@@ -88,9 +92,18 @@ module PostHog
       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]
@@ -119,7 +132,8 @@ module PostHog
       end
       @worker_thread = nil
       @feature_flags_poller = nil
-      @personal_api_key = opts[:personal_api_key]
+      @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')
@@ -142,7 +156,7 @@ module PostHog
         @feature_flags_poller =
           FeatureFlagsPoller.new(
             opts[:feature_flags_polling_interval],
-            opts[:personal_api_key],
+            secret_key,
             @api_key,
             opts[:host],
             opts[:feature_flag_request_timeout_seconds] || Defaults::FeatureFlags::FLAG_REQUEST_TIMEOUT_SECONDS,
@@ -595,7 +609,8 @@ module PostHog
           id: definition[:id],
           version: nil,
           reason: FeatureFlagEvaluations::EVALUATED_LOCALLY_REASON,
-          locally_evaluated: true
+          locally_evaluated: true,
+          has_experiment: definition[:has_experiment]
         )
         locally_evaluated_keys << key.to_s
       end
@@ -635,7 +650,8 @@ module PostHog
               id: metadata ? metadata.id : nil,
               version: metadata ? metadata.version : nil,
               reason: reason ? (reason.description || reason.code) : nil,
-              locally_evaluated: false
+              locally_evaluated: false,
+              has_experiment: metadata&.has_experiment
             )
           end
         rescue StandardError => e
@@ -752,6 +768,7 @@ module PostHog
       # Remove internal information
       response.delete(:requestId)
       response.delete(:evaluatedAt)
+      response.delete(:flagDetails)
       response
     end
 
@@ -761,9 +778,9 @@ module PostHog
     def reload_feature_flags
       return if @disabled
 
-      unless @personal_api_key
+      unless @secret_key
         logger.error(
-          'You need to specify a personal_api_key to locally evaluate feature flags'
+          'You need to specify a secret_key to locally evaluate feature flags'
         )
         return
       end
@@ -907,7 +924,8 @@ module PostHog
       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 =
+      feature_flag_response, flag_was_locally_evaluated, request_id, evaluated_at, feature_flag_error, payload,
+        has_experiment =
         @feature_flags_poller.get_feature_flag(
           key, distinct_id, groups, person_properties, group_properties, only_evaluate_locally
         )
@@ -917,6 +935,7 @@ module PostHog
           '$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

data/lib/posthog/feature_flag.rb

@@ -68,7 +68,7 @@ module PostHog
   #
   # @api private
   class FeatureFlagMetadata
-    attr_reader :id, :version, :payload, :description
+    attr_reader :id, :version, :payload, :description, :has_experiment
 
     # @param json [Hash] Raw metadata returned by /flags.
     def initialize(json)
@@ -77,6 +77,9 @@ module PostHog
       @version = json['version']
       @payload = json['payload']
       @description = json['description']
+      # Whether the flag is linked to an experiment. nil when the server
+      # (an older deployment) does not report the field.
+      @has_experiment = json['has_experiment']
     end
   end
 end

data/lib/posthog/feature_flag_evaluations.rb

@@ -13,7 +13,7 @@ module PostHog
     EVALUATED_LOCALLY_REASON = 'Evaluated locally'
 
     EvaluatedFlagRecord = Struct.new(
-      :key, :enabled, :variant, :payload, :id, :version, :reason, :locally_evaluated,
+      :key, :enabled, :variant, :payload, :id, :version, :reason, :locally_evaluated, :has_experiment,
       keyword_init: true
     )
 
@@ -169,6 +169,7 @@ module PostHog
       }
 
       if flag
+        properties['$feature_flag_has_experiment'] = flag.has_experiment unless flag.has_experiment.nil?
         properties['$feature_flag_payload'] = flag.payload unless flag.payload.nil?
         properties['$feature_flag_id'] = flag.id if flag.id
         properties['$feature_flag_version'] = flag.version if flag.version

data/lib/posthog/feature_flags.rb

@@ -30,7 +30,8 @@ module PostHog
     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 secret_key [String, nil] Credential used to fetch local evaluation definitions. Accepts either a
+    #   Personal API Key (`phx_...`) or a Project Secret API Key (`phs_...`).
     # @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.
@@ -41,7 +42,7 @@ module PostHog
     #   Set to 0 to disable retrying.
     def initialize(
       polling_interval,
-      personal_api_key,
+      secret_key,
       project_api_key,
       host,
       feature_flag_request_timeout_seconds,
@@ -50,7 +51,7 @@ module PostHog
       feature_flag_request_max_retries: nil
     )
       @polling_interval = polling_interval || 30
-      @personal_api_key = personal_api_key
+      @secret_key = secret_key
       @project_api_key = project_api_key
       @host = host
       @feature_flags = Concurrent::Array.new
@@ -74,9 +75,9 @@ module PostHog
           execution_interval: polling_interval
         ) { _load_feature_flags }
 
-      # If no personal API key, disable local evaluation & thus polling for definitions
-      if @personal_api_key.nil?
-        logger.info 'No personal API key provided, disabling local evaluation'
+      # If no secret_key, disable local evaluation & thus polling for definitions
+      if @secret_key.nil?
+        logger.info 'No secret_key provided, disabling local evaluation'
         @loaded_flags_successfully_once.make_true
       else
         # load once before timer
@@ -220,6 +221,11 @@ module PostHog
       end
 
       flag_was_locally_evaluated = !response.nil?
+      # Whether the flag is linked to an experiment, as reported by the server.
+      # Locally-evaluated flags carry it in the stored definition; remotely
+      # evaluated flags carry it in the response metadata. nil when the server
+      # (an older deployment) does not report it.
+      has_experiment = feature_flag[:has_experiment] if flag_was_locally_evaluated
 
       request_id = nil
       evaluated_at = nil
@@ -252,6 +258,9 @@ module PostHog
           payload = payloads[key]
           feature_flag_error = errors.join(',') unless errors.empty?
 
+          flag_detail = flags_data[:flagDetails]&.[](key.to_sym)
+          has_experiment = flag_detail&.metadata&.has_experiment
+
           logger.debug "Successfully computed flag remotely: #{key} -> #{response}"
         rescue Timeout::Error => e
           @on_error.call(-1, "Timeout while fetching flags remotely: #{e}")
@@ -265,7 +274,7 @@ module PostHog
         end
       end
 
-      [response, flag_was_locally_evaluated, request_id, evaluated_at, feature_flag_error, payload]
+      [response, flag_was_locally_evaluated, request_id, evaluated_at, feature_flag_error, payload, has_experiment]
     end
 
     def get_all_flags(
@@ -323,10 +332,12 @@ module PostHog
       errors_while_computing = false
       quota_limited = nil
       status_code = nil
+      flag_details = nil
 
       if fallback_to_server && !only_evaluate_locally
         begin
           flags_and_payloads = get_flags(distinct_id, groups, person_properties, group_properties)
+          flag_details = flags_and_payloads[:flags]
           errors_while_computing = flags_and_payloads[:errorsWhileComputingFlags] || false
           quota_limited = flags_and_payloads[:quotaLimited]
           status_code = flags_and_payloads[:status]
@@ -367,6 +378,7 @@ module PostHog
       {
         featureFlags: flags,
         featureFlagPayloads: payloads,
+        flagDetails: flag_details,
         requestId: request_id,
         evaluatedAt: evaluated_at,
         errorsWhileComputingFlags: errors_while_computing,
@@ -1227,7 +1239,7 @@ module PostHog
       uri = URI("#{@host}/flags/definitions")
       uri.query = URI.encode_www_form([['token', @project_api_key], %w[send_cohorts true]])
       req = Net::HTTP::Get.new(uri)
-      req['Authorization'] = "Bearer #{@personal_api_key}"
+      req['Authorization'] = "Bearer #{@secret_key}"
       req['If-None-Match'] = etag if etag
 
       _request(uri, req, nil, include_etag: true)
@@ -1253,7 +1265,7 @@ module PostHog
       uri.query = URI.encode_www_form([['token', @project_api_key]])
       req = Net::HTTP::Get.new(uri)
       req['Content-Type'] = 'application/json'
-      req['Authorization'] = "Bearer #{@personal_api_key}"
+      req['Authorization'] = "Bearer #{@secret_key}"
 
       _request(uri, req, @feature_flag_request_timeout_seconds)
     end

data/lib/posthog/flag_definition_cache.rb

@@ -52,7 +52,7 @@ module PostHog
   #   cache = RedisFlagCache.new(redis, service_key: 'my-service')
   #   client = PostHog::Client.new(
   #     api_key: '<project_api_key>',
-  #     personal_api_key: '<personal_api_key>',
+  #     secret_key: '<secret_key>',
   #     flag_definition_cache_provider: cache
   #   )
   #

data/lib/posthog/version.rb

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

metadata

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