mixpanel-ruby 3.1.0 → 3.2.0

data/Readme.rdoc

@@ -1,5 +1,7 @@
 = mixpanel-ruby: The official Mixpanel Ruby library
 
+##### _July 10, 2026_ - [v3.2.0](https://github.com/mixpanel/mixpanel-ruby/releases/tag/v3.2.0)
+
 mixpanel-ruby is a library for tracking events and sending \Mixpanel profile
 updates to \Mixpanel from your ruby applications.
 
@@ -27,6 +29,69 @@ The primary class you will use to track events is Mixpanel::Tracker. An instance
 Mixpanel::Tracker is enough to send events directly to \Mixpanel, and get you integrated
 right away.
 
+== Service Account Authentication
+
+Service accounts provide secure server-to-server authentication and are recommended over
+API keys for import operations and feature flags.
+
+=== Import with Service Account (Recommended)
+
+    require 'mixpanel-ruby'
+
+    # Create service account credentials
+    credentials = Mixpanel::ServiceAccountCredentials.new(
+        'your-service-account-username',
+        'your-service-account-secret',
+        'your-project-id'
+    )
+
+    # Pass credentials to tracker constructor
+    # Credentials are stored securely and never serialized to JSON
+    tracker = Mixpanel::Tracker.new(YOUR_MIXPANEL_TOKEN, credentials: credentials)
+
+    # Import historical events using import_events (recommended)
+    tracker.import_events('User1', 'Past Event', {
+        'time' => 1369353600,
+        'Source' => 'Import'
+    })
+
+    # Alternative: use import() with nil as first parameter
+    tracker.import(nil, 'User1', 'Past Event', {
+        'time' => 1369353600,
+        'Source' => 'Import'
+    })
+
+=== Import with API Key (Legacy)
+
+    # Legacy approach with API key string
+    tracker = Mixpanel::Tracker.new(YOUR_MIXPANEL_TOKEN)
+    tracker.import("API_KEY", 'User1', 'Past Event', {
+        'time' => 1369353600,
+        'Source' => 'Import'
+    })
+
+=== Feature Flags with Service Account
+
+    require 'mixpanel-ruby'
+
+    credentials = Mixpanel::ServiceAccountCredentials.new(
+        'your-service-account-username',
+        'your-service-account-secret',
+        'your-project-id'
+    )
+
+    # Pass credentials directly to the tracker
+    tracker = Mixpanel::Tracker.new(
+        YOUR_MIXPANEL_TOKEN,
+        nil,
+        credentials: credentials,
+        local_flags_config: {},
+        remote_flags_config: {}
+    )
+
+    # Use feature flags
+    is_enabled = tracker.remote_flags.is_enabled?('my-flag', { 'distinct_id' => 'User1' })
+
 == Additional Information
 
 For more information please visit:

data/lib/mixpanel-ruby/consumer.rb

@@ -40,6 +40,11 @@ module Mixpanel
   #        @kestrel.set(ANALYTICS_QUEUE, [type, message].to_json)
   #    end
   #
+  # IMPORTANT SECURITY NOTE: Always pass credentials to the Consumer or Tracker
+  # constructor (credentials: ...). Credentials are stored as instance variables
+  # and used only for HTTP Basic Auth headers - they never appear in message JSON,
+  # preventing accidental credential leakage in logs or queue storage.
+  #
   # You can also instantiate the library consumers yourself, and use
   # them wherever you would like. For example, the working that
   # consumes the above queue might work like this:
@@ -58,14 +63,19 @@ module Mixpanel
     # they will be used instead of the default Mixpanel endpoints.
     # This can be useful for proxying, debugging, or if you prefer
     # not to use SSL for your events.
+    #
+    # @param credentials [ServiceAccountCredentials, nil] Service account credentials for authentication.
+    #   Credentials are only used for the /import endpoint and feature flags.
     def initialize(events_endpoint=nil,
                    update_endpoint=nil,
                    groups_endpoint=nil,
-                   import_endpoint=nil)
+                   import_endpoint=nil,
+                   credentials: nil)
       @events_endpoint = events_endpoint || 'https://api.mixpanel.com/track'
       @update_endpoint = update_endpoint || 'https://api.mixpanel.com/engage'
       @groups_endpoint = groups_endpoint || 'https://api.mixpanel.com/groups'
       @import_endpoint = import_endpoint || 'https://api.mixpanel.com/import'
+      @credentials = credentials
     end
 
     # Send the given string message to Mixpanel. Type should be
@@ -85,13 +95,26 @@ module Mixpanel
 
       decoded_message = JSON.load(message)
       api_key = decoded_message["api_key"]
+
       data = Base64.encode64(decoded_message["data"].to_json).gsub("\n", '')
 
       form_data = {"data" => data, "verbose" => 1}
-      form_data.merge!("api_key" => api_key) if api_key
+
+      # Only add api_key to form data if using legacy API key (not service account credentials)
+      # Service account credentials use HTTP Basic Auth instead
+      if api_key && !@credentials
+        form_data.merge!("api_key" => api_key)
+      end
 
       begin
-        response_code, response_body = request(endpoint, form_data)
+        # Use keyword arguments for credentials to maintain backward compatibility
+        # with custom Consumer subclasses that override request(endpoint, form_data)
+        response_code, response_body =
+          if @credentials && type == :import
+            request(endpoint, form_data, credentials: @credentials, type: type)
+          else
+            request(endpoint, form_data)
+          end
       rescue => e
         raise ConnectionError.new("Could not connect to Mixpanel, with error \"#{e.message}\".")
       end
@@ -123,11 +146,32 @@ module Mixpanel
     #
     # as the result of the response. Response code should be nil if
     # the request never receives a response for some reason.
-    def request(endpoint, form_data)
+    #
+    # For service account authentication, pass credentials (ServiceAccountCredentials object)
+    # and type (:import) as keyword arguments.
+    # The positional parameters are preserved for backward compatibility with custom Consumer subclasses.
+    def request(endpoint, form_data, credentials: nil, type: nil)
       uri = URI(endpoint)
+
+      # Add project_id as query parameter for import endpoint with service account credentials
+      if credentials && type == :import
+        unless credentials.is_a?(ServiceAccountCredentials)
+          raise ArgumentError, "credentials must be ServiceAccountCredentials, got #{credentials.class}"
+        end
+
+        query_params = URI.decode_www_form(uri.query || '').to_h
+        query_params['project_id'] = credentials.project_id
+        uri.query = URI.encode_www_form(query_params)
+      end
+
       request = Net::HTTP::Post.new(uri.request_uri)
       request.set_form_data(form_data)
 
+      # Use Basic Auth with service account credentials for import endpoint
+      if credentials && type == :import
+        request.basic_auth(credentials.username, credentials.secret)
+      end
+
       client = Net::HTTP.new(uri.host, uri.port)
       client.use_ssl = true
       client.open_timeout = 10
@@ -182,17 +226,21 @@ module Mixpanel
     # to the Mixpanel::Tracker constructor. If a block is passed to
     # the constructor, the *_endpoint constructor arguments are
     # ignored.
-    def initialize(events_endpoint=nil, update_endpoint=nil, import_endpoint=nil, max_buffer_length=MAX_LENGTH, &block)
+    #
+    # @param credentials [ServiceAccountCredentials, nil] Service account credentials for authentication.
+    #   Credentials are only used for the /import endpoint and feature flags.
+    def initialize(events_endpoint=nil, update_endpoint=nil, import_endpoint=nil, max_buffer_length=MAX_LENGTH, credentials: nil, &block)
       @max_length = [max_buffer_length, MAX_LENGTH].min
       @buffers = {
         :event => [],
         :profile_update => [],
       }
+      @credentials = credentials
 
       if block
         @sink = block
       else
-        consumer = Consumer.new(events_endpoint, update_endpoint, import_endpoint)
+        consumer = Consumer.new(events_endpoint, update_endpoint, nil, import_endpoint, credentials: credentials)
         @sink = consumer.method(:send!)
       end
     end

data/lib/mixpanel-ruby/credentials.rb

@@ -0,0 +1,26 @@
+module Mixpanel
+  # Service account credentials for server-to-server authentication
+  # This is the recommended authentication method over API keys
+  class ServiceAccountCredentials
+    attr_reader :username, :secret, :project_id
+
+    # Create service account credentials
+    # @param username [String] Service account username
+    # @param secret [String] Service account secret
+    # @param project_id [String, Integer] Mixpanel project ID (accepts string or integer)
+    def initialize(username, secret, project_id)
+      raise ArgumentError, 'username is required' if username.nil? || username.empty?
+      raise ArgumentError, 'secret is required' if secret.nil? || secret.empty?
+      raise ArgumentError, 'project_id is required' if project_id.nil?
+
+      # Convert project_id to string if it's an integer (Mixpanel dashboard shows numeric IDs)
+      project_id = project_id.to_s if project_id.is_a?(Integer)
+      raise ArgumentError, 'project_id is required' if project_id.empty?
+
+      @username = username
+      @secret = secret
+      @project_id = project_id
+    end
+
+  end
+end

data/lib/mixpanel-ruby/events.rb

@@ -22,14 +22,19 @@ module Mixpanel
     #     # tracker has all of the methods of Mixpanel::Events
     #     tracker = Mixpanel::Tracker.new(YOUR_MIXPANEL_TOKEN)
     #
-    def initialize(token, error_handler=nil, &block)
+    def initialize(token, error_handler=nil, credentials: nil, &block)
       @token = token
       @error_handler = error_handler || ErrorHandler.new
+      @credentials = credentials
+
+      if block && credentials
+        warn '[WARNING] credentials passed to Events/Tracker are ignored when a custom sink block is provided. Pass credentials to your consumer directly.'
+      end
 
       if block
         @sink = block
       else
-        consumer = Consumer.new
+        consumer = Consumer.new(credentials: credentials)
         @sink = consumer.method(:send!)
       end
     end
@@ -87,19 +92,66 @@ module Mixpanel
     # we pass the time of the method call as the time the event occured, if you
     # wish to override this pass a timestamp in the properties hash.
     #
-    #     tracker = Mixpanel::Tracker.new(YOUR_MIXPANEL_TOKEN)
-    #
-    #     # Track that user "12345"'s credit card was declined
-    #     tracker.import("API_KEY", "12345", "Credit Card Declined")
-    #
-    #     # Properties describe the circumstances of the event,
-    #     # or aspects of the source or user associated with the event
-    #     tracker.import("API_KEY", "12345", "Welcome Email Sent", {
+    #     # Recommended: Use import_events() instead
+    #     credentials = Mixpanel::ServiceAccountCredentials.new(username, secret, project_id)
+    #     tracker = Mixpanel::Tracker.new(YOUR_MIXPANEL_TOKEN, credentials: credentials)
+    #     tracker.import_events("12345", "Welcome Email Sent", {
     #         'Email Template' => 'Pretty Pink Welcome',
     #         'User Sign-up Cohort' => 'July 2013',
     #         'time' => 1369353600,
     #     })
+    #
+    #     # Legacy: Pass API key as first parameter (deprecated)
+    #     tracker.import("API_KEY", "12345", "Credit Card Declined")
+    #
     def import(api_key, distinct_id, event, properties={}, ip=nil)
+      # Warn about deprecated API key usage
+      if api_key && !api_key.to_s.empty?
+        warn '[DEPRECATION] Passing api_key to import() is deprecated. Use ServiceAccountCredentials in the constructor instead. See https://docs.mixpanel.com/docs/tracking-methods/sdks/ruby#service-account-authentication'
+      end
+
+      # Warn when using import(nil, ...) - recommend import_events instead
+      if api_key.nil? && @credentials
+        warn '[DEPRECATION] Using import(nil, ...) is deprecated. Use import_events(...) instead for cleaner API.'
+      end
+
+      # Delegate to internal implementation
+      import_internal(api_key, distinct_id, event, properties, ip)
+    end
+
+    # Import an event using service account credentials from the constructor.
+    # This is the recommended method for importing historical events with service accounts.
+    #
+    # Credentials must be provided in the Tracker/Events constructor. This method is cleaner
+    # than import() as it doesn't require passing nil as the first parameter.
+    #
+    #     credentials = Mixpanel::ServiceAccountCredentials.new(username, secret, project_id)
+    #     tracker = Mixpanel::Tracker.new(YOUR_MIXPANEL_TOKEN, credentials: credentials)
+    #
+    #     tracker.import_events('user123', 'Past Event', {
+    #         'time' => 1369353600,
+    #         'Source' => 'Import'
+    #     })
+    #
+    def import_events(distinct_id, event, properties={}, ip=nil)
+      unless @credentials
+        raise ArgumentError, 'import_events requires credentials in constructor. Use: Tracker.new(token, credentials: credentials)'
+      end
+
+      # Delegate to internal implementation with nil api_key (uses constructor credentials)
+      import_internal(nil, distinct_id, event, properties, ip)
+    end
+
+    private
+
+    # Internal implementation for importing events.
+    # Called by both import() and import_events().
+    def import_internal(api_key, distinct_id, event, properties, ip)
+      # Validate that at least one authentication method is provided
+      if api_key.nil? && @credentials.nil?
+        raise ArgumentError, 'import requires authentication: provide either api_key parameter or credentials in constructor'
+      end
+
       properties = {
         'distinct_id' => distinct_id,
         'token' => @token,
@@ -116,9 +168,15 @@ module Mixpanel
 
       message = {
         'data' => data,
-        'api_key' => api_key,
       }
 
+      # Only include api_key in message if provided (legacy auth)
+      # When using service account credentials (recommended), pass nil for api_key
+      # and the Consumer will use credentials from its instance variable
+      if api_key
+        message['api_key'] = api_key
+      end
+
       ret = true
       begin
         @sink.call(:import, message.to_json)

data/lib/mixpanel-ruby/flags/flags_provider.rb

@@ -12,7 +12,7 @@ module Mixpanel
     # Base class for feature flags providers
     # Provides common HTTP handling and exposure event tracking
     class FlagsProvider
-      # @param provider_config [Hash] Configuration with :token, :api_host, :request_timeout_in_seconds
+      # @param provider_config [Hash] Configuration with :token, :api_host, :request_timeout_in_seconds, :credentials (optional)
       # @param endpoint [String] API endpoint path (e.g., '/flags' or '/flags/definitions')
       # @param tracker_callback [Proc] Function used to track events (bound tracker.track method)
       # @param evaluation_mode [String] The feature flag evaluation mode. This is either 'local' or 'remote'
@@ -23,6 +23,7 @@ module Mixpanel
         @tracker_callback = tracker_callback
         @evaluation_mode = evaluation_mode
         @error_handler = error_handler
+        @credentials = provider_config[:credentials]
       end
 
       # Make HTTP request to flags API endpoint
@@ -31,12 +32,20 @@ module Mixpanel
       # @raise [Mixpanel::ConnectionError] on network errors
       # @raise [Mixpanel::ServerError] on HTTP errors
       def call_flags_endpoint(additional_params = nil)
+        # Always use token in query params
         common_params = Utils.prepare_common_query_params(
           @provider_config[:token],
           Mixpanel::VERSION
         )
 
         params = common_params.merge(additional_params || {})
+
+        # Add project_id as query parameter when using service account credentials
+        # Note: project_id is required for service account auth but not used for token auth
+        if @credentials
+          params['project_id'] = @credentials.project_id
+        end
+
         query_string = URI.encode_www_form(params)
 
         uri = URI::HTTPS.build(
@@ -53,7 +62,12 @@ module Mixpanel
 
         request = Net::HTTP::Get.new(uri.request_uri)
 
-        request.basic_auth(@provider_config[:token], '')
+        # Use service account credentials for basic auth if provided, otherwise use token
+        if @credentials
+          request.basic_auth(@credentials.username, @credentials.secret)
+        else
+          request.basic_auth(@provider_config[:token], '')
+        end
 
         request['Content-Type'] = 'application/json'
         request['traceparent'] = Utils.generate_traceparent

data/lib/mixpanel-ruby/flags/local_flags_provider.rb

@@ -18,13 +18,26 @@ module Mixpanel
       # @param config [Hash] Local flags configuration
       # @param tracker_callback [Proc] Callback to track events
       # @param error_handler [Mixpanel::ErrorHandler] Error handler
-      def initialize(token, config, tracker_callback, error_handler)
-        @config = DEFAULT_CONFIG.merge(config || {})
+      # @param credentials [ServiceAccountCredentials, nil] Optional service account credentials
+      def initialize(token, config, tracker_callback, error_handler, credentials = nil)
+        # compact: an explicit nil from the caller (e.g.
+        # polling_interval_in_seconds: nil) must not override a sane default.
+        # Both the previous sleep(nil) and the current
+        # ConditionVariable#wait(mutex, nil) block indefinitely, which would
+        # silently disable polling — fall back to the default instead.
+        @config = DEFAULT_CONFIG.merge((config || {}).compact)
+
+        interval = @config[:polling_interval_in_seconds]
+        unless interval.is_a?(Numeric) && interval > 0
+          raise ArgumentError,
+                "polling_interval_in_seconds must be a positive number, got: #{interval.inspect}"
+        end
 
         provider_config = {
           token: token,
           api_host: @config[:api_host],
-          request_timeout_in_seconds: @config[:request_timeout_in_seconds]
+          request_timeout_in_seconds: @config[:request_timeout_in_seconds],
+          credentials: credentials
         }
 
         super(provider_config, '/flags/definitions', tracker_callback, 'local', error_handler)
@@ -32,36 +45,80 @@ module Mixpanel
         @flag_definitions = {}
         @polling_thread = nil
         @stop_polling = false
+        @polling_mutex = Mutex.new
+        @polling_condition = ConditionVariable.new
+        # Separate from @polling_mutex: serializes the full start/stop lifecycle
+        # (including the join inside stop) so a concurrent start can't observe a
+        # mid-stop state and spawn a new polling thread before the old one
+        # finishes exiting. We can't hold @polling_mutex across the join — the
+        # polling thread needs it to wake from the condition wait.
+        @lifecycle_mutex = Mutex.new
       end
 
       # Start polling for flag definitions
       # Fetches immediately, then at regular intervals if polling enabled
       def start_polling_for_definitions!
+        # Clear @stop_polling BEFORE the initial fetch so a concurrent
+        # stop_polling_for_definitions! arriving during the fetch can flip it
+        # back to true and signal "abandon start". Under @polling_mutex, writes
+        # to @stop_polling are linearized: whichever of {start's clear, stop's
+        # set} happened latest is what we observe under the lifecycle lock
+        # below — i.e. last-writer-wins semantics preserve stop's postcondition
+        # (polling is off when stop returns) even across the unguarded fetch.
+        @polling_mutex.synchronize { @stop_polling = false }
+
+        # Initial fetch is intentionally outside @lifecycle_mutex: it's a
+        # blocking HTTP call, and holding the lifecycle lock across it would
+        # block a concurrent stop_polling_for_definitions! for the full request
+        # timeout.
         fetch_flag_definitions
 
-        if @config[:enable_polling] && !@polling_thread
-          @stop_polling = false
-          @polling_thread = Thread.new do
-            loop do
-              sleep @config[:polling_interval_in_seconds]
-              break if @stop_polling
-
-              begin
-                fetch_flag_definitions
-              rescue StandardError => e
-                @error_handler.handle(e) if @error_handler
+        @lifecycle_mutex.synchronize do
+          # If a stop arrived during/after our @stop_polling clear above, abort
+          # — the user's stop "wins" because it's the most recent intent.
+          stop_requested = @polling_mutex.synchronize { @stop_polling }
+
+          # .alive? guards against a prior polling thread that died abnormally
+          # (e.g. error_handler itself raised); without it @polling_thread would
+          # be non-nil-but-dead and we'd silently refuse to restart polling.
+          if !stop_requested && @config[:enable_polling] &&
+             (@polling_thread.nil? || !@polling_thread.alive?)
+            @polling_thread = Thread.new do
+              loop do
+                # Check @stop_polling INSIDE the mutex (before and after wait)
+                # so a broadcast from stop_polling_for_definitions! can't be
+                # lost if it arrives while we're outside the synchronized region
+                # (e.g. during fetch_flag_definitions below).
+                stopped = @polling_mutex.synchronize do
+                  next true if @stop_polling
+
+                  @polling_condition.wait(@polling_mutex, @config[:polling_interval_in_seconds])
+                  @stop_polling
+                end
+                break if stopped
+
+                begin
+                  fetch_flag_definitions
+                rescue StandardError => e
+                  safe_handle_error(e)
+                end
               end
             end
           end
         end
       rescue StandardError => e
-        @error_handler.handle(e) if @error_handler
+        safe_handle_error(e)
       end
 
       def stop_polling_for_definitions!
-        @stop_polling = true
-        @polling_thread&.join
-        @polling_thread = nil
+        @lifecycle_mutex.synchronize do
+          @polling_mutex.synchronize do
+            @stop_polling = true
+            @polling_condition.broadcast
+          end
+          @polling_thread&.join
+          @polling_thread = nil
+        end
       end
 
       def shutdown
@@ -141,6 +198,16 @@ module Mixpanel
 
       private
 
+      # Wrap @error_handler.handle so a misbehaving handler can't kill the
+      # polling thread mid-loop — that would leave @polling_thread non-nil but
+      # dead, and (without the .alive? check in start) silently prevent restart.
+      def safe_handle_error(error)
+        @error_handler.handle(error) if @error_handler
+      rescue StandardError
+        # Swallow: keeping the polling loop alive is more important than
+        # propagating a broken handler's failure.
+      end
+
       def fetch_flag_definitions
         response = call_flags_endpoint
 

data/lib/mixpanel-ruby/flags/remote_flags_provider.rb

@@ -14,13 +14,15 @@ module Mixpanel
       # @param config [Hash] Remote flags configuration
       # @param tracker_callback [Proc] Callback to track events
       # @param error_handler [Mixpanel::ErrorHandler] Error handler
-      def initialize(token, config, tracker_callback, error_handler)
+      # @param credentials [ServiceAccountCredentials, nil] Optional service account credentials
+      def initialize(token, config, tracker_callback, error_handler, credentials = nil)
         merged_config = DEFAULT_CONFIG.merge(config || {})
 
         provider_config = {
           token: token,
           api_host: merged_config[:api_host],
-          request_timeout_in_seconds: merged_config[:request_timeout_in_seconds]
+          request_timeout_in_seconds: merged_config[:request_timeout_in_seconds],
+          credentials: credentials
         }
 
         super(provider_config, '/flags', tracker_callback, 'remote', error_handler)

data/lib/mixpanel-ruby/tracker.rb

@@ -62,9 +62,14 @@ module Mixpanel
     # If a block is provided, it is passed a type (one of :event or :profile_update)
     # and a string message. This same format is accepted by Mixpanel::Consumer#send!
     # and Mixpanel::BufferedConsumer#send!
-    def initialize(token, error_handler=nil, local_flags_config: nil, remote_flags_config: nil, &block)
-      super(token, error_handler, &block)
-      @token = token
+    #
+    # Optional parameters:
+    # - credentials: ServiceAccountCredentials for authentication (used for import and feature flags)
+    # - local_flags_config: Configuration hash for local feature flags
+    # - remote_flags_config: Configuration hash for remote feature flags
+    def initialize(token, error_handler=nil, credentials: nil, local_flags_config: nil, remote_flags_config: nil, &block)
+      super(token, error_handler, credentials: credentials, &block)
+
       @people = People.new(token, error_handler, &block)
       @groups = Groups.new(token, error_handler, &block)
 
@@ -74,7 +79,8 @@ module Mixpanel
           token,
           local_flags_config,
           method(:track),  # Pass bound method as callback
-          error_handler || ErrorHandler.new
+          error_handler || ErrorHandler.new,
+          credentials
         )
       end
 
@@ -84,7 +90,8 @@ module Mixpanel
           token,
           remote_flags_config,
           method(:track),  # Pass bound method as callback
-          error_handler || ErrorHandler.new
+          error_handler || ErrorHandler.new,
+          credentials
         )
       end
     end
@@ -122,14 +129,15 @@ module Mixpanel
     #
     #     tracker = Mixpanel::Tracker.new(YOUR_MIXPANEL_TOKEN)
     #
-    #     # Import event that user "12345"'s credit card was declined
+    #     # Using deprecated API key (still supported)
     #     tracker.import("API_KEY", "12345", "Credit Card Declined", {
     #       'time' => 1310111365
     #     })
     #
-    #     # Properties describe the circumstances of the event,
-    #     # or aspects of the source or user associated with the event
-    #     tracker.import("API_KEY", "12345", "Welcome Email Sent", {
+    #     # Using service account credentials (recommended)
+    #     credentials = Mixpanel::ServiceAccountCredentials.new(username, secret, project_id)
+    #     tracker = Mixpanel::Tracker.new(YOUR_MIXPANEL_TOKEN, credentials: credentials)
+    #     tracker.import(nil, "12345", "Welcome Email Sent", {
     #         'Email Template' => 'Pretty Pink Welcome',
     #         'User Sign-up Cohort' => 'July 2013',
     #         'time' => 1310111365
@@ -140,6 +148,28 @@ module Mixpanel
       super
     end
 
+    # Import an event using service account credentials from the constructor.
+    # This is the recommended method for importing historical events with service accounts.
+    #
+    # Service account credentials must be provided when creating the Tracker.
+    # This method provides a cleaner API than import() as it doesn't require
+    # passing nil as the first parameter.
+    #
+    #     credentials = Mixpanel::ServiceAccountCredentials.new(username, secret, project_id)
+    #     tracker = Mixpanel::Tracker.new(YOUR_MIXPANEL_TOKEN, credentials: credentials)
+    #
+    #     # Import a historical event
+    #     tracker.import_events('user123', 'Past Event', {
+    #         'Email Template' => 'Welcome Email',
+    #         'time' => 1369353600
+    #     })
+    #
+    def import_events(distinct_id, event, properties={}, ip=nil)
+      # This is here strictly to allow rdoc to include the relevant
+      # documentation
+      super
+    end
+
     # Creates a distinct_id alias. \Events and updates with an alias
     # will be considered by mixpanel to have the same source, and
     # refer to the same profile.

data/lib/mixpanel-ruby/version.rb

@@ -1,3 +1,3 @@
 module Mixpanel
-  VERSION = '3.1.0'
+  VERSION = '3.2.0'
 end

data/lib/mixpanel-ruby.rb

@@ -1,6 +1,7 @@
 require 'mixpanel-ruby/consumer.rb'
 require 'mixpanel-ruby/tracker.rb'
 require 'mixpanel-ruby/version.rb'
+require 'mixpanel-ruby/credentials.rb'
 require 'mixpanel-ruby/flags/utils.rb'
 require 'mixpanel-ruby/flags/types.rb'
 require 'mixpanel-ruby/flags/flags_provider.rb'

data/openfeature-provider/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## [openfeature/v0.1.0](https://github.com/mixpanel/mixpanel-ruby/tree/openfeature/v0.1.0) (2026-05-13)
+
+Initial release of the Mixpanel OpenFeature provider for Ruby.

data/openfeature-provider/README.md

@@ -1,5 +1,7 @@
 # mixpanel-ruby-openfeature
 
+##### _May 13, 2026_ - [openfeature/v0.1.0](https://github.com/mixpanel/mixpanel-ruby/releases/tag/openfeature/v0.1.0)
+
 [![Gem Version](https://img.shields.io/gem/v/mixpanel-ruby-openfeature.svg)](https://rubygems.org/gems/mixpanel-ruby-openfeature)
 [![OpenFeature](https://img.shields.io/badge/OpenFeature-compatible-green)](https://openfeature.dev/)
 [![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](https://github.com/mixpanel/mixpanel-ruby/blob/master/LICENSE)