posthog-rails 3.9.0 → 3.9.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e9d0502771ef899181fbcf4acbbaf7b3c72000e5082ef69e98163bf43ae57002
-  data.tar.gz: 6002687536b139e97f4e4afc361f17ec519fc0fa54b16416bf888ba55e9b37f7
+  metadata.gz: 792f6e0ca6b259928ec0704d585e4887fbd4839837b7d49c08fc47b7eeeeeaaf
+  data.tar.gz: bc72fab471755cd32695bfdc919aa5cc99559c626504af061e89b80ad98dfd33
 SHA512:
-  metadata.gz: 339d21bdceb568ff493da11539db72fb0ca32d61cc50e18d12facc6a7920761554cc15a2cc85a45adf60a9b8fa324ad6129fb09ca176e180b3c7a4002f08e2ec
-  data.tar.gz: b6f2417f98317d42a5cdad3f15e7b2ae1d00254fd63571768a01956ffbb4cc0e398892409f65eb69167941a19392fc549c33406723b3cc36cef38b8f0f49017c
+  metadata.gz: f860543aeca28abfd50a110fa76fd2eed17a86e8c933cbbb0a0fdcdf4002d11bf400d2fb41d5680fa7587de749cad9514e71ad2a0855f1050827fb3da5d7a71b
+  data.tar.gz: afb7cb589db961516dea558424cdbe71ff9e20a004a0b944eba6f0aa54fdcb5a4be92acd0dfe6ce88abc84e35a63ca6567ecea4b5fd662018940b05b595aa27b

data/lib/posthog/rails/active_job.rb

@@ -13,7 +13,12 @@ module PostHog
       end
 
       module ClassMethods
-        # DSL for defining how to extract distinct_id from job arguments
+        # DSL for defining how to extract distinct_id from job arguments.
+        #
+        # @param proc [Proc, nil] Callable that receives the job's perform arguments.
+        # @yield The block receives the job's perform arguments.
+        # @return [Proc, nil] The configured extractor.
+        #
         # Example:
         #   class MyJob < ApplicationJob
         #     posthog_distinct_id ->(user, arg1, arg2) { user.id }
@@ -25,6 +30,7 @@ module PostHog
           @posthog_distinct_id_proc = proc || block
         end
 
+        # @return [Proc, nil] The configured distinct_id extractor.
         def posthog_distinct_id_proc
           @posthog_distinct_id_proc
         end

data/lib/posthog/rails/capture_exceptions.rb

@@ -4,14 +4,19 @@ require 'posthog/rails/parameter_filter'
 
 module PostHog
   module Rails
-    # Middleware that captures exceptions and sends them to PostHog
+    # Middleware that captures exceptions and sends them to PostHog.
+    #
+    # @api private
     class CaptureExceptions
       include ParameterFilter
 
+      # @param app [#call] Rack application.
       def initialize(app)
         @app = app
       end
 
+      # @param env [Hash] Rack environment.
+      # @return [Array] Rack response.
       def call(env)
         # Signal that we're in a web request context
         # ErrorSubscriber will skip capture for web requests to avoid duplicates

data/lib/posthog/rails/configuration.rb

@@ -3,31 +3,33 @@
 module PostHog
   module Rails
     class Configuration
-      # Whether to automatically capture exceptions from Rails
+      # @return [Boolean] Whether to automatically capture exceptions from Rails. Defaults to false.
       attr_accessor :auto_capture_exceptions
 
-      # Whether to capture exceptions that Rails rescues (e.g., with rescue_from)
+      # @return [Boolean] Whether to capture exceptions that Rails rescues (e.g., with rescue_from). Defaults to false.
       attr_accessor :report_rescued_exceptions
 
-      # Whether to automatically instrument ActiveJob
+      # @return [Boolean] Whether to automatically instrument ActiveJob. Defaults to false.
       attr_accessor :auto_instrument_active_job
 
-      # List of exception classes to ignore (in addition to default)
+      # @return [Array<String>] Exception class names to ignore in addition to the defaults.
       attr_accessor :excluded_exceptions
 
-      # Whether to use PostHog tracing headers for request-scoped identity/session context
+      # @return [Boolean] Whether to use PostHog tracing headers for request-scoped identity/session context.
+      #   Defaults to true.
       attr_accessor :use_tracing_headers
 
-      # Whether to capture the current user context in exceptions
+      # @return [Boolean] Whether to capture the current user context in exceptions. Defaults to true.
       attr_accessor :capture_user_context
 
-      # Method name to call on controller to get user ID (default: :current_user)
+      # @return [Symbol] Method name to call on controller to get the current user. Defaults to :current_user.
       attr_accessor :current_user_method
 
-      # Method name to call on user object to get distinct_id (default: auto-detect)
-      # When nil, tries: posthog_distinct_id, distinct_id, id, pk, uuid in order
+      # @return [Symbol, nil] Method name to call on the user object to get distinct_id. When nil, tries:
+      #   posthog_distinct_id, distinct_id, id, pk, uuid in order.
       attr_accessor :user_id_method
 
+      # @return [PostHog::Rails::Configuration]
       def initialize
         @auto_capture_exceptions = false
         @report_rescued_exceptions = false
@@ -39,7 +41,9 @@ module PostHog
         @user_id_method = nil
       end
 
-      # Default exceptions that Rails apps typically don't want to track
+      # Default exceptions that Rails apps typically don't want to track.
+      #
+      # @return [Array<String>]
       def default_excluded_exceptions
         [
           'AbstractController::ActionNotFound',
@@ -58,6 +62,8 @@ module PostHog
         ]
       end
 
+      # @param exception [Exception] The exception to check.
+      # @return [Boolean] Whether the exception should be captured.
       def should_capture_exception?(exception)
         exception_name = exception.class.name
         !all_excluded_exceptions.include?(exception_name)

data/lib/posthog/rails/error_subscriber.rb

@@ -4,11 +4,19 @@ require 'posthog/rails/parameter_filter'
 
 module PostHog
   module Rails
-    # Rails 7.0+ error reporter integration
-    # This integrates with Rails.error.handle and Rails.error.record
+    # Rails 7.0+ error reporter integration.
+    # This integrates with Rails.error.handle and Rails.error.record.
+    #
+    # @api private
     class ErrorSubscriber
       include ParameterFilter
 
+      # @param error [Exception] Error reported by Rails.
+      # @param handled [Boolean]
+      # @param severity [Symbol, String]
+      # @param context [Hash]
+      # @param source [String, nil]
+      # @return [void]
       def report(error, handled:, severity:, context:, source: nil)
         return unless PostHog::Rails.config&.auto_capture_exceptions
         return unless PostHog::Rails.config&.should_capture_exception?(error)

data/lib/posthog/rails/parameter_filter.rb

@@ -9,6 +9,8 @@ module PostHog
     # It automatically detects the correct Rails parameter filtering API based on
     # the Rails version.
     #
+    # @api private
+    #
     # @example Usage in a class
     #   class MyClass
     #     include PostHog::Rails::ParameterFilter
@@ -24,10 +26,12 @@ module PostHog
       MAX_DEPTH = 10
 
       if ::Rails.version.to_f >= 6.0
+        # @return [Class] Rails parameter filter backend.
         def self.backend
           ActiveSupport::ParameterFilter
         end
       else
+        # @return [Class] Rails parameter filter backend.
         def self.backend
           ActionDispatch::Http::ParameterFilter
         end

data/lib/posthog/rails/railtie.rb

@@ -21,7 +21,11 @@ module PostHog
               get_all_flags
             ].freeze
 
-            # Initialize PostHog client with a block configuration
+            # Initialize the singleton PostHog client used by Rails delegators.
+            #
+            # @param options [Hash] Core {PostHog::Client} options.
+            # @yieldparam config [PostHog::Rails::InitConfig] Block-based core SDK configuration.
+            # @return [PostHog::Client]
             def init(options = {})
               # If block given, yield to configuration
               if block_given?
@@ -42,11 +46,14 @@ module PostHog
               end
             end
 
+            # @return [Boolean] Whether {PostHog.init} has created a client.
             def initialized?
               !@client.nil?
             end
 
-            # Fallback for any client methods not explicitly defined
+            # Fallback for any client methods not explicitly defined.
+            #
+            # @api private
             # rubocop:disable Lint/RedundantSafeNavigation
             def method_missing(method_name, ...)
               if client&.respond_to?(method_name)
@@ -57,6 +64,7 @@ module PostHog
               end
             end
 
+            # @api private
             def respond_to_missing?(method_name, include_private = false)
               client&.respond_to?(method_name) || super
             end
@@ -118,6 +126,8 @@ module PostHog
         at_exit { PostHog.client&.shutdown if PostHog.initialized? }
       end
 
+      # @api private
+      # @return [void]
       def insert_middleware_after(app, target, middleware)
         # During initialization, app.config.middleware is a MiddlewareStackProxy
         # which only supports recording operations (insert_after, use, etc.)
@@ -125,6 +135,8 @@ module PostHog
         app.config.middleware.insert_after(target, middleware)
       end
 
+      # @api private
+      # @return [void]
       def insert_middleware_before(app, target, middleware)
         # During initialization, app.config.middleware is a MiddlewareStackProxy
         # which only supports recording operations (insert_before, use, etc.)
@@ -132,6 +144,8 @@ module PostHog
         app.config.middleware.insert_before(target, middleware)
       end
 
+      # @api private
+      # @return [void]
       def self.register_error_subscriber
         return unless PostHog::Rails.config&.auto_capture_exceptions
 
@@ -142,6 +156,8 @@ module PostHog
         PostHog::Logging.logger.warn("Backtrace: #{e.backtrace&.first(5)&.join("\n")}")
       end
 
+      # @api private
+      # @return [Boolean]
       def self.rails_version_above_7?
         ::Rails.version.to_f >= 7.0
       end
@@ -149,51 +165,74 @@ module PostHog
 
     # Configuration wrapper for the init block
     class InitConfig
+      # @param base_options [Hash] Initial core SDK options.
       def initialize(base_options = {})
         @base_options = base_options
       end
 
       # Core PostHog options
+      #
+      # @param value [String]
+      # @return [String]
       def api_key=(value)
         @base_options[:api_key] = value
       end
 
+      # @param value [String, nil]
+      # @return [String, nil]
       def personal_api_key=(value)
         @base_options[:personal_api_key] = value
       end
 
+      # @param value [String]
+      # @return [String]
       def host=(value)
         @base_options[:host] = value
       end
 
+      # @param value [Integer]
+      # @return [Integer]
       def max_queue_size=(value)
         @base_options[:max_queue_size] = value
       end
 
+      # @param value [Boolean]
+      # @return [Boolean]
       def test_mode=(value)
         @base_options[:test_mode] = value
       end
 
+      # @param value [Boolean]
+      # @return [Boolean]
       def sync_mode=(value)
         @base_options[:sync_mode] = value
       end
 
+      # @param value [Proc]
+      # @return [Proc]
       def on_error=(value)
         @base_options[:on_error] = value
       end
 
+      # @param value [Integer]
+      # @return [Integer]
       def feature_flags_polling_interval=(value)
         @base_options[:feature_flags_polling_interval] = value
       end
 
+      # @param value [Integer]
+      # @return [Integer]
       def feature_flag_request_timeout_seconds=(value)
         @base_options[:feature_flag_request_timeout_seconds] = value
       end
 
+      # @param value [Proc]
+      # @return [Proc]
       def before_send=(value)
         @base_options[:before_send] = value
       end
 
+      # @return [Hash] Core SDK options suitable for {PostHog::Client.new}.
       def to_client_options
         @base_options
       end

data/lib/posthog/rails/request_context.rb

@@ -7,11 +7,16 @@ require 'posthog/rails/request_metadata'
 module PostHog
   module Rails
     # Rack middleware that creates a request-local PostHog context from tracing headers.
+    #
+    # @api private
     class RequestContext
+      # @param app [#call] Rack application.
       def initialize(app)
         @app = app
       end
 
+      # @param env [Hash] Rack environment.
+      # @return [Array] Rack response.
       def call(env)
         request = build_request(env)
 

data/lib/posthog/rails/request_metadata.rb

@@ -5,9 +5,13 @@ require 'posthog/rails/tracing_headers'
 module PostHog
   module Rails
     # Internal helpers for extracting request metadata owned by RequestContext.
+    #
+    # @api private
     module RequestMetadata
       module_function
 
+      # @param request [Object] Rack or Rails request object.
+      # @return [Hash] Event properties extracted from the request.
       def extract(request)
         properties = {}
         add_property(properties, '$current_url', current_url(request))

data/lib/posthog/rails/rescued_exception_interceptor.rb

@@ -2,14 +2,19 @@
 
 module PostHog
   module Rails
-    # Middleware that intercepts exceptions that are rescued by Rails
+    # Middleware that intercepts exceptions that are rescued by Rails.
     # This middleware runs before ShowExceptions and captures the exception
-    # so we can report it even if Rails rescues it
+    # so we can report it even if Rails rescues it.
+    #
+    # @api private
     class RescuedExceptionInterceptor
+      # @param app [#call] Rack application.
       def initialize(app)
         @app = app
       end
 
+      # @param env [Hash] Rack environment.
+      # @return [Array] Rack response.
       def call(env)
         @app.call(env)
       rescue StandardError => e

data/lib/posthog/rails/tracing_headers.rb

@@ -3,12 +3,16 @@
 module PostHog
   module Rails
     # Helpers for extracting and sanitizing PostHog tracing headers from Rack/Rails requests.
+    #
+    # @api private
     module TracingHeaders
       MAX_HEADER_VALUE_LENGTH = 1000
       CONTROL_CHARACTERS = /[[:cntrl:]]/
 
       module_function
 
+      # @param value [Object]
+      # @return [String, nil]
       def sanitize_header_value(value)
         return nil unless value.is_a?(String)
 
@@ -18,6 +22,9 @@ module PostHog
         sanitized[0, MAX_HEADER_VALUE_LENGTH]
       end
 
+      # @param request_or_env [Object, Hash] Rack request, Rails request, or Rack env hash.
+      # @param header_name [String]
+      # @return [String, nil]
       def extract_header(request_or_env, header_name)
         candidates = header_candidates(header_name)
 

data/lib/posthog/rails.rb

@@ -18,29 +18,41 @@ module PostHog
     IN_WEB_REQUEST_KEY = :posthog_in_web_request
 
     class << self
+      # @return [PostHog::Rails::Configuration] Rails integration configuration.
       def config
         @config ||= Configuration.new
       end
 
+      # @param config [PostHog::Rails::Configuration] Rails integration configuration.
       attr_writer :config
 
+      # Configure Rails integration options.
+      #
+      # @yieldparam config [PostHog::Rails::Configuration]
+      # @return [void]
       def configure
         yield config if block_given?
       end
 
       # Mark that we're in a web request context
       # CaptureExceptions middleware will handle exception capture
+      # @api private
+      # @return [void]
       def enter_web_request
         Thread.current[IN_WEB_REQUEST_KEY] = true
       end
 
       # Clear web request context (called at end of request)
+      # @api private
+      # @return [void]
       def exit_web_request
         Thread.current[IN_WEB_REQUEST_KEY] = false
       end
 
       # Check if we're currently in a web request context
       # Used by ErrorSubscriber to avoid duplicate captures
+      # @api private
+      # @return [Boolean]
       def in_web_request?
         Thread.current[IN_WEB_REQUEST_KEY] == true
       end

metadata

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