mixpanel-ruby 3.1.0 → 3.3.0

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

@@ -7,20 +7,24 @@ module Mixpanel
     class RemoteFlagsProvider < FlagsProvider
       DEFAULT_CONFIG = {
         api_host: 'api.mixpanel.com',
-        request_timeout_in_seconds: 10
+        request_timeout_in_seconds: 10,
+        exposure_executor: nil
       }.freeze
 
       # @param token [String] Mixpanel project token
       # @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],
+          exposure_executor: merged_config[:exposure_executor],
+          credentials: credentials
         }
 
         super(provider_config, '/flags', tracker_callback, 'remote', error_handler)
@@ -59,13 +63,18 @@ module Mixpanel
         flags = response['flags'] || {}
         selected_variant_data = flags[flag_key]
 
-        return fallback_variant unless selected_variant_data
+        # The /flags endpoint only returns variants the user is enrolled in,
+        # so a missing key could mean the flag doesn't exist OR the user
+        # isn't in any rollout. The remote SDK can't tell them apart without
+        # server-side help — surface as FLAG_NOT_FOUND for now.
+        return fallback_variant.as_fallback(FallbackReason.flag_not_found) unless selected_variant_data
 
         selected_variant = SelectedVariant.new(
           variant_key: selected_variant_data['variant_key'],
           variant_value: selected_variant_data['variant_value'],
           experiment_id: selected_variant_data['experiment_id'],
-          is_experiment_active: selected_variant_data['is_experiment_active']
+          is_experiment_active: selected_variant_data['is_experiment_active'],
+          variant_source: VariantSource::REMOTE
         )
 
         track_exposure_event(flag_key, selected_variant, context, latency_ms) if report_exposure
@@ -73,7 +82,12 @@ module Mixpanel
         return selected_variant
       rescue MixpanelError => e
         @error_handler.handle(e)
-        return fallback_variant
+        # Attach the backend's message so the OpenFeature wrapper can forward
+        # it into ResolutionDetails#error_message — without this the caller
+        # sees a bare GENERAL error and has to dig through logs to find out
+        # the backend rejected the request (e.g. "distinct_id must be
+        # provided in evalContext as a string"). SDK-83.
+        return fallback_variant.as_fallback(FallbackReason.backend_error(e.message))
       end
 
       # Check if flag is enabled (for boolean flags)
@@ -104,7 +118,8 @@ module Mixpanel
             variant_key: variant_data['variant_key'],
             variant_value: variant_data['variant_value'],
             experiment_id: variant_data['experiment_id'],
-            is_experiment_active: variant_data['is_experiment_active']
+            is_experiment_active: variant_data['is_experiment_active'],
+            variant_source: VariantSource::REMOTE
           )
         end
 

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

@@ -1,35 +1,114 @@
 module Mixpanel
   module Flags
+    # Where a SelectedVariant came from. Set by the providers on every returned
+    # variant — coarse-grained (local / remote / fallback). For the specific
+    # reason behind a fallback, see {FallbackReason}.
+    module VariantSource
+      LOCAL    = 'local'.freeze
+      REMOTE   = 'remote'.freeze
+      FALLBACK = 'fallback'.freeze
+    end
+
+    # Why the SDK returned the developer fallback. Only meaningful when
+    # SelectedVariant#variant_source == VariantSource::FALLBACK.
+    #
+    # `kind` is the discriminator (matches the PHP constant set). `message`
+    # is set on the reasons that carry useful detail (BACKEND_ERROR with the
+    # backend's response, MISSING_CONTEXT_KEY with the missing attribute);
+    # nil otherwise. The OpenFeature wrapper dispatches on kind and forwards
+    # message into ResolutionDetails#error_message.
+    class FallbackReason
+      KINDS = %i[flag_not_found missing_context_key no_rollout_match backend_error].freeze
+
+      attr_reader :kind, :message
+
+      def initialize(kind, message: nil)
+        raise ArgumentError, "Unknown FallbackReason kind: #{kind.inspect}" unless KINDS.include?(kind)
+
+        @kind = kind
+        @message = message
+        freeze
+      end
+
+      def ==(other)
+        other.is_a?(FallbackReason) && other.kind == @kind && other.message == @message
+      end
+      alias_method :eql?, :==
+
+      def hash
+        [self.class, @kind, @message].hash
+      end
+
+      def to_h
+        { kind: @kind, message: @message }.compact
+      end
+
+      # Factory methods. Reasons without meaningful detail return a frozen
+      # singleton; reasons with detail allocate per call.
+      def self.flag_not_found;      FLAG_NOT_FOUND;   end
+      def self.no_rollout_match;    NO_ROLLOUT_MATCH; end
+      def self.missing_context_key(key = nil); new(:missing_context_key, message: key); end
+      def self.backend_error(message); new(:backend_error, message: message); end
+
+      FLAG_NOT_FOUND   = new(:flag_not_found)
+      NO_ROLLOUT_MATCH = new(:no_rollout_match)
+    end
+
     # Selected variant returned from flag evaluation
     class SelectedVariant
       attr_accessor :variant_key, :variant_value, :experiment_id,
-                    :is_experiment_active, :is_qa_tester
+                    :is_experiment_active, :is_qa_tester,
+                    :variant_source, :fallback_reason
 
-      # @param variant_key [String, nil] The variant key
-      # @param variant_value [Object] The variant value (any type)
-      # @param experiment_id [String, nil] Associated experiment ID
-      # @param is_experiment_active [Boolean, nil] Whether experiment is active
-      # @param is_qa_tester [Boolean, nil] Whether user is a QA tester
       def initialize(variant_key: nil, variant_value: nil, experiment_id: nil,
-                     is_experiment_active: nil, is_qa_tester: nil)
+                     is_experiment_active: nil, is_qa_tester: nil,
+                     variant_source: nil, fallback_reason: nil)
         @variant_key = variant_key
         @variant_value = variant_value
         @experiment_id = experiment_id
         @is_experiment_active = is_experiment_active
         @is_qa_tester = is_qa_tester
+        @variant_source = variant_source
+        @fallback_reason = fallback_reason
+      end
+
+      # Return a copy of this variant tagged with the given source. Clears
+      # fallback_reason — use {#as_fallback} when returning a fallback.
+      def with_source(source)
+        copy_with(variant_source: source, fallback_reason: nil)
+      end
+
+      # Return a copy tagged as a fallback with the given reason.
+      def as_fallback(reason)
+        copy_with(variant_source: VariantSource::FALLBACK, fallback_reason: reason)
       end
 
       # Convert to hash representation
-      # @return [Hash]
       def to_h
         {
           variant_key: @variant_key,
           variant_value: @variant_value,
           experiment_id: @experiment_id,
           is_experiment_active: @is_experiment_active,
-          is_qa_tester: @is_qa_tester
+          is_qa_tester: @is_qa_tester,
+          variant_source: @variant_source,
+          fallback_reason: @fallback_reason&.to_h
         }.compact
       end
+
+      private
+
+      def copy_with(variant_source: @variant_source, fallback_reason: @fallback_reason)
+        SelectedVariant.new(
+          variant_key: @variant_key,
+          variant_value: @variant_value,
+          experiment_id: @experiment_id,
+          is_experiment_active: @is_experiment_active,
+          is_qa_tester: @is_qa_tester,
+          variant_source: variant_source,
+          fallback_reason: fallback_reason
+        )
+      end
     end
   end
 end

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.3.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)
@@ -199,6 +201,34 @@ When you are done using the provider, shut it down to stop any background pollin
 provider.shutdown
 ```
 
+## Async Exposure Tracking
+
+By default, every flag evaluation tracks an exposure event inline — the `/track` HTTP round trip happens on the calling thread before `fetch_*_value` returns. For latency-sensitive code paths, pass an `:exposure_executor` so exposure tracking runs off-thread. The executor is duck-typed — anything that responds to `#post(&block)` works:
+
+```ruby
+# With concurrent-ruby (recommended)
+require 'concurrent'
+exposure_executor = Concurrent::FixedThreadPool.new(1)
+
+provider = Mixpanel::OpenFeature::Provider.from_local(
+  'YOUR_PROJECT_TOKEN',
+  { exposure_executor: exposure_executor },
+)
+
+# Without concurrent-ruby (minimal wrapper)
+class ThreadPerCall
+  def post(&block) = Thread.new(&block)
+end
+provider = Mixpanel::OpenFeature::Provider.from_local(
+  'YOUR_PROJECT_TOKEN',
+  { exposure_executor: ThreadPerCall.new },
+)
+```
+
+Available on both local and remote flag configs. Defaults to `nil` (inline behavior); existing setups are unaffected.
+
+> **Executor lifecycle:** `provider.shutdown` stops the flags provider's own resources (polling) but does NOT shut down a user-supplied executor. Own the executor's lifecycle explicitly — e.g. `at_exit { exposure_executor.shutdown; exposure_executor.wait_for_termination(5) }` for `Concurrent::FixedThreadPool`. Skipping this can leave background threads alive at process exit and delay shutdown.
+
 ## Error Handling
 
 The provider uses OpenFeature's standard error codes to indicate issues during flag evaluation:

data/openfeature-provider/lib/mixpanel/openfeature/provider.rb

@@ -69,16 +69,41 @@ module Mixpanel
 
         begin
           result = @flags_provider.get_variant(flag_key, fallback, context, report_exposure: true)
-        rescue StandardError
-          return error_result(default_value, ::OpenFeature::SDK::Provider::ErrorCode::GENERAL)
+        rescue StandardError => e
+          return error_result(default_value, ::OpenFeature::SDK::Provider::ErrorCode::GENERAL, e.message)
         end
 
-        if result.equal?(fallback)
+        # variant_source distinguishes local / remote / fallback. When fallback,
+        # fallback_reason carries the specific reason (PHP-aligned constants)
+        # so we can map each to the spec-correct OpenFeature response instead
+        # of collapsing every fallback to FLAG_NOT_FOUND. SDK-83: BACKEND_ERROR
+        # also carries the backend message, forwarded as error_message.
+        case result.fallback_reason&.kind
+        when :flag_not_found
           return ::OpenFeature::SDK::Provider::ResolutionDetails.new(
             value: default_value,
             error_code: ::OpenFeature::SDK::Provider::ErrorCode::FLAG_NOT_FOUND,
             reason: ::OpenFeature::SDK::Provider::Reason::DEFAULT
           )
+        when :missing_context_key
+          return error_result(
+            default_value,
+            ::OpenFeature::SDK::Provider::ErrorCode::TARGETING_KEY_MISSING,
+            result.fallback_reason.message
+          )
+        when :no_rollout_match
+          # Flag exists, user just didn't match any rollout — per the
+          # OpenFeature spec this is `reason: DEFAULT` with no error.
+          return ::OpenFeature::SDK::Provider::ResolutionDetails.new(
+            value: default_value,
+            reason: ::OpenFeature::SDK::Provider::Reason::DEFAULT
+          )
+        when :backend_error
+          return error_result(
+            default_value,
+            ::OpenFeature::SDK::Provider::ErrorCode::GENERAL,
+            result.fallback_reason.message
+          )
         end
 
         value = result.variant_value
@@ -158,10 +183,11 @@ module Mixpanel
         end
       end
 
-      def error_result(default_value, error_code)
+      def error_result(default_value, error_code, error_message = nil)
         ::OpenFeature::SDK::Provider::ResolutionDetails.new(
           value: default_value,
           error_code: error_code,
+          error_message: error_message,
           reason: ::OpenFeature::SDK::Provider::Reason::ERROR
         )
       end

data/openfeature-provider/lib/mixpanel/openfeature/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Mixpanel
+  module OpenFeature
+    VERSION = '0.1.0'
+  end
+end

data/openfeature-provider/lib/mixpanel/openfeature.rb

@@ -1,3 +1,4 @@
 # frozen_string_literal: true
 
+require_relative 'openfeature/version'
 require_relative 'openfeature/provider'

data/openfeature-provider/mixpanel-ruby-openfeature.gemspec

@@ -1,8 +1,10 @@
 # frozen_string_literal: true
 
+require File.join(File.dirname(__FILE__), 'lib/mixpanel/openfeature/version.rb')
+
 Gem::Specification.new do |spec|
   spec.name = 'mixpanel-ruby-openfeature'
-  spec.version = '0.1.0'
+  spec.version = Mixpanel::OpenFeature::VERSION
   spec.authors = ['Mixpanel']
   spec.email = 'support@mixpanel.com'
   spec.summary = 'OpenFeature provider for Mixpanel feature flags'

data/openfeature-provider/spec/mixpanel_openfeature_provider_spec.rb

@@ -75,15 +75,25 @@ RSpec.describe Mixpanel::OpenFeature::Provider do
   def setup_flag(flag_key, value, variant_key: 'variant-key')
     allow(mock_flags).to receive(:get_variant) do |key, fallback, _ctx, **_kwargs|
       if key == flag_key
-        Mixpanel::Flags::SelectedVariant.new(variant_key: variant_key, variant_value: value)
+        Mixpanel::Flags::SelectedVariant.new(
+          variant_key: variant_key,
+          variant_value: value,
+          variant_source: Mixpanel::Flags::VariantSource::LOCAL
+        )
       else
-        fallback
+        fallback.as_fallback(Mixpanel::Flags::FallbackReason.flag_not_found)
       end
     end
   end
 
+  def setup_fallback(reason)
+    allow(mock_flags).to receive(:get_variant) do |_key, fallback, _ctx, **_kwargs|
+      fallback.as_fallback(reason)
+    end
+  end
+
   def setup_flag_not_found
-    allow(mock_flags).to receive(:get_variant) { |_key, fallback, _ctx, **_kwargs| fallback }
+    setup_fallback(Mixpanel::Flags::FallbackReason.flag_not_found)
   end
 
   # --- Metadata ---
@@ -305,6 +315,67 @@ RSpec.describe Mixpanel::OpenFeature::Provider do
     end
   end
 
+  # --- NO_ROLLOUT_MATCH (flag exists, no rollout matched) ---
+
+  describe 'no rollout match' do
+    before { setup_fallback(Mixpanel::Flags::FallbackReason.no_rollout_match) }
+
+    it 'returns DEFAULT reason without an error code' do
+      result = provider.fetch_boolean_value(flag_key: 'flag', default_value: true)
+      expect(result.value).to be true
+      expect(result.reason).to eq('DEFAULT')
+      expect(result.error_code).to be_nil
+    end
+
+    it 'works for strings' do
+      result = provider.fetch_string_value(flag_key: 'flag', default_value: 'default')
+      expect(result.value).to eq('default')
+      expect(result.reason).to eq('DEFAULT')
+      expect(result.error_code).to be_nil
+    end
+  end
+
+  # --- MISSING_CONTEXT_KEY ---
+
+  describe 'missing context key' do
+    before { setup_fallback(Mixpanel::Flags::FallbackReason.missing_context_key('distinct_id')) }
+
+    it 'returns TARGETING_KEY_MISSING for boolean' do
+      result = provider.fetch_boolean_value(flag_key: 'flag', default_value: false)
+      expect(result.value).to be false
+      expect(result.error_code).to eq('TARGETING_KEY_MISSING')
+      expect(result.reason).to eq('ERROR')
+    end
+
+    it 'returns TARGETING_KEY_MISSING for string and forwards the missing key as error_message' do
+      result = provider.fetch_string_value(flag_key: 'flag', default_value: 'default')
+      expect(result.value).to eq('default')
+      expect(result.error_code).to eq('TARGETING_KEY_MISSING')
+      expect(result.error_message).to eq('distinct_id')
+      expect(result.reason).to eq('ERROR')
+    end
+  end
+
+  # --- BACKEND_ERROR (SDK-83: forwards the backend's response message) ---
+
+  describe 'backend error' do
+    before do
+      setup_fallback(
+        Mixpanel::Flags::FallbackReason.backend_error(
+          'HTTP 400: distinct_id must be provided in evalContext as a string'
+        )
+      )
+    end
+
+    it 'maps to GENERAL and forwards the backend message as error_message' do
+      result = provider.fetch_string_value(flag_key: 'flag', default_value: 'default')
+      expect(result.value).to eq('default')
+      expect(result.error_code).to eq('GENERAL')
+      expect(result.reason).to eq('ERROR')
+      expect(result.error_message).to include('distinct_id must be provided')
+    end
+  end
+
   # --- PROVIDER_NOT_READY ---
 
   describe 'provider not ready' do

data/spec/mixpanel-ruby/consumer_spec.rb

@@ -3,6 +3,7 @@ require 'spec_helper'
 require 'webmock'
 
 require 'mixpanel-ruby/consumer'
+require 'mixpanel-ruby/credentials'
 
 describe Mixpanel::Consumer do
   before { WebMock.reset! }
@@ -95,6 +96,56 @@ describe Mixpanel::Consumer do
     it_behaves_like 'consumer'
   end
 
+  context 'service account credentials' do
+    it 'should send a request to api.mixpanel.com/import with service account credentials' do
+      stub_request(:any, 'https://api.mixpanel.com/import?project_id=test-project-123').to_return({:body => '{"status": 1, "error": null}'})
+      credentials = Mixpanel::ServiceAccountCredentials.new('test-user', 'test-secret', 'test-project-123')
+      consumer = Mixpanel::Consumer.new(nil, nil, nil, nil, credentials: credentials)
+
+      consumer.send!(:import, {'data' => 'TEST EVENT MESSAGE'}.to_json)
+
+      # Should use Basic Auth header with username:secret
+      # Should add project_id as query parameter
+      # Should NOT include credentials in POST body or message
+      expect(WebMock).to have_requested(:post, 'https://api.mixpanel.com/import?project_id=test-project-123').
+        with(
+          :body => {
+            'data' => 'IlRFU1QgRVZFTlQgTUVTU0FHRSI=',
+            'verbose' => '1'
+          },
+          :headers => {
+            'Authorization' => 'Basic ' + Base64.strict_encode64('test-user:test-secret')
+          }
+        )
+    end
+
+    it 'should raise ArgumentError when credentials is not ServiceAccountCredentials' do
+      consumer = Mixpanel::Consumer.new
+
+      expect {
+        consumer.request('https://api.mixpanel.com/import', {'data' => 'test', 'verbose' => '1'}, credentials: 'invalid', type: :import)
+      }.to raise_error(ArgumentError, /credentials must be ServiceAccountCredentials, got String/)
+    end
+
+    it 'should not include api_key when credentials are present' do
+      stub_request(:any, 'https://api.mixpanel.com/import?project_id=test-project').to_return({:body => '{"status": 1, "error": null}'})
+      credentials = Mixpanel::ServiceAccountCredentials.new('user', 'secret', 'test-project')
+      consumer = Mixpanel::Consumer.new(nil, nil, nil, nil, credentials: credentials)
+
+      # Message includes api_key but it should be ignored when credentials are present
+      consumer.send!(:import, {'data' => 'TEST EVENT MESSAGE', 'api_key' => 'SHOULD_BE_IGNORED'}.to_json)
+
+      # api_key should NOT be in the request body (only data and verbose)
+      expect(WebMock).to have_requested(:post, 'https://api.mixpanel.com/import?project_id=test-project').
+        with(
+          :body => {
+            'data' => 'IlRFU1QgRVZFTlQgTUVTU0FHRSI=',
+            'verbose' => '1'
+          }
+        )
+    end
+  end
+
 end
 
 describe Mixpanel::BufferedConsumer do
@@ -205,4 +256,34 @@ describe Mixpanel::BufferedConsumer do
     end
   end
 
+  context 'with service account credentials' do
+    it 'should pass credentials to consumer when using BufferedConsumer' do
+      stub_request(:any, 'https://api.mixpanel.com/import?project_id=buffered-project').to_return({:body => '{"status": 1, "error": null}'})
+      credentials = Mixpanel::ServiceAccountCredentials.new('buffered-user', 'buffered-secret', 'buffered-project')
+      consumer = Mixpanel::BufferedConsumer.new(nil, nil, nil, 2, credentials: credentials)
+
+      # Import messages are not buffered - they're sent immediately
+      consumer.send!(:import, {'data' => 'EVENT 1'}.to_json)
+
+      # Verify credentials were used in the request
+      expect(WebMock).to have_requested(:post, 'https://api.mixpanel.com/import?project_id=buffered-project').
+        with(
+          :headers => {
+            'Authorization' => 'Basic ' + Base64.strict_encode64('buffered-user:buffered-secret')
+          }
+        ).once
+    end
+  end
+
+end
+
+describe 'Connection error handling' do
+  it 'should raise ConnectionError when network error occurs' do
+    stub_request(:any, 'https://api.mixpanel.com/track').to_raise(StandardError.new('Network timeout'))
+    consumer = Mixpanel::Consumer.new
+
+    expect {
+      consumer.send!(:event, {'data' => 'TEST EVENT MESSAGE'}.to_json)
+    }.to raise_error(Mixpanel::ConnectionError, /Could not connect to Mixpanel, with error "Network timeout"/)
+  end
 end