mixpanel-ruby 3.1.0 → 3.3.0

data/spec/mixpanel-ruby/flags/local_flags_spec.rb

@@ -1,6 +1,8 @@
 require 'json'
+require 'timeout'
 require 'mixpanel-ruby/flags/local_flags_provider'
 require 'mixpanel-ruby/flags/types'
+require 'mixpanel-ruby/credentials'
 require 'webmock/rspec'
 
 describe Mixpanel::Flags::LocalFlagsProvider do
@@ -16,7 +18,8 @@ describe Mixpanel::Flags::LocalFlagsProvider do
       test_token,
       config,
       mock_tracker,
-      mock_error_handler
+      mock_error_handler,
+      nil  # credentials
     )
   end
 
@@ -100,6 +103,34 @@ describe Mixpanel::Flags::LocalFlagsProvider do
     }
   end
 
+  describe '#initialize' do
+    it 'raises ArgumentError when polling_interval_in_seconds is not a positive number' do
+      [0, -1, 'sixty', :foo].each do |bad_value|
+        expect do
+          Mixpanel::Flags::LocalFlagsProvider.new(
+            test_token,
+            { polling_interval_in_seconds: bad_value },
+            mock_tracker,
+            mock_error_handler
+          )
+        end.to raise_error(ArgumentError, /polling_interval_in_seconds/)
+      end
+    end
+
+    it 'falls back to the default polling_interval_in_seconds when caller passes nil' do
+      # nil must not silently override the default — CV#wait(mutex, nil) blocks
+      # indefinitely, which would silently disable polling.
+      expect do
+        Mixpanel::Flags::LocalFlagsProvider.new(
+          test_token,
+          { polling_interval_in_seconds: nil },
+          mock_tracker,
+          mock_error_handler
+        )
+      end.not_to raise_error
+    end
+  end
+
   describe '#get_variant_value' do
     it 'returns fallback when no flag definitions' do
       stub_flag_definitions([])
@@ -718,6 +749,179 @@ describe Mixpanel::Flags::LocalFlagsProvider do
 
       provider.send(:track_exposure_event, 'test_flag', variant, test_context)
     end
+
+    it 'runs the tracker inline by default (no executor configured)' do
+      flag = create_test_flag
+      stub_flag_definitions([flag])
+      provider.start_polling_for_definitions!
+
+      variant = Mixpanel::Flags::SelectedVariant.new(
+        variant_key: 'treatment', variant_value: 'treatment'
+      )
+
+      calling_thread = Thread.current
+      tracker_thread = nil
+      allow(mock_tracker).to receive(:call) { tracker_thread = Thread.current }
+
+      provider.send(:track_exposure_event, 'test_flag', variant, test_context)
+      expect(tracker_thread).to be(calling_thread)
+    end
+
+    it 'dispatches the tracker via :exposure_executor when configured' do
+      executor = Object.new
+      def executor.post(&block)
+        Thread.new(&block)
+      end
+
+      tracker_thread = nil
+      tracker_ran = Queue.new
+      tracker = ->(_distinct_id, _event, _properties) {
+        tracker_thread = Thread.current
+        tracker_ran << :done
+      }
+
+      provider = Mixpanel::Flags::LocalFlagsProvider.new(
+        test_token,
+        { enable_polling: false, exposure_executor: executor },
+        tracker,
+        mock_error_handler
+      )
+
+      variant = Mixpanel::Flags::SelectedVariant.new(
+        variant_key: 'treatment', variant_value: 'treatment'
+      )
+      provider.send(:track_exposure_event, 'test_flag', variant, test_context)
+
+      # Bounded wait — a bare Queue#pop would hang CI forever if the
+      # tracker block raised before pushing :done.
+      Timeout.timeout(2) { tracker_ran.pop }
+      expect(tracker_thread).not_to be(Thread.current)
+    end
+
+    it 'reports non-MixpanelError exceptions from the async tracker to error_handler' do
+      handler_called = Queue.new
+      handler = double('error_handler')
+      allow(handler).to receive(:handle) { |e| handler_called << e }
+
+      executor = Object.new
+      def executor.post(&block)
+        Thread.new(&block)
+      end
+
+      tracker = ->(_distinct_id, _event, _properties) { raise NoMethodError, 'boom' }
+
+      provider = Mixpanel::Flags::LocalFlagsProvider.new(
+        test_token,
+        { enable_polling: false, exposure_executor: executor },
+        tracker,
+        handler
+      )
+
+      variant = Mixpanel::Flags::SelectedVariant.new(
+        variant_key: 'treatment', variant_value: 'treatment'
+      )
+      provider.send(:track_exposure_event, 'test_flag', variant, test_context)
+
+      err = Timeout.timeout(2) { handler_called.pop }
+      expect(err).to be_a(Mixpanel::MixpanelError)
+      expect(err.message).to include('NoMethodError')
+      expect(err.message).to include('boom')
+    end
+
+    # Inline path preserves the pre-executor behavior: non-MixpanelError
+    # from the tracker propagates to the flag evaluator's caller instead
+    # of being silently reported. Only the async path wraps everything,
+    # because on the executor thread propagation would just kill the
+    # background thread with no visibility.
+    it 'lets non-MixpanelError exceptions propagate on the inline path' do
+      tracker = ->(_distinct_id, _event, _properties) { raise NoMethodError, 'boom' }
+
+      inline_provider = Mixpanel::Flags::LocalFlagsProvider.new(
+        test_token,
+        { enable_polling: false },
+        tracker,
+        mock_error_handler
+      )
+
+      variant = Mixpanel::Flags::SelectedVariant.new(
+        variant_key: 'treatment', variant_value: 'treatment'
+      )
+
+      expect(mock_error_handler).not_to receive(:handle)
+      expect {
+        inline_provider.send(:track_exposure_event, 'test_flag', variant, test_context)
+      }.to raise_error(NoMethodError, 'boom')
+    end
+
+    # SDK-84: when local eval succeeds via a non-distinct_id Variant Assignment
+    # Key but the context lacks distinct_id, the exposure can't fire. Surface
+    # via error_handler instead of silently returning.
+    it 'reports through error_handler when distinct_id is missing' do
+      variant = Mixpanel::Flags::SelectedVariant.new(
+        variant_key: 'treatment', variant_value: 'treatment'
+      )
+
+      expect(mock_tracker).not_to receive(:call)
+      expect(mock_error_handler).to receive(:handle) do |err|
+        expect(err).to be_a(Mixpanel::MixpanelError)
+        expect(err.message).to include('test_flag')
+        expect(err.message).to include('distinct_id')
+      end
+
+      provider.send(
+        :track_exposure_event,
+        'test_flag',
+        variant,
+        { 'device_id' => 'abc-123' }
+      )
+    end
+  end
+
+  describe '#get_variant variant_source / fallback_reason tagging' do
+    let(:fallback) { Mixpanel::Flags::SelectedVariant.new(variant_value: 'fb') }
+
+    it 'tags matched variants as LOCAL with no fallback_reason' do
+      flag = create_test_flag(rollout_percentage: 100.0)
+      stub_flag_definitions([flag])
+      provider.start_polling_for_definitions!
+
+      result = provider.get_variant('test_flag', fallback, test_context)
+      expect(result.variant_source).to eq(Mixpanel::Flags::VariantSource::LOCAL)
+      expect(result.fallback_reason).to be_nil
+      expect(result.variant_key).not_to be_nil
+    end
+
+    it 'tags missing flag as FALLBACK / flag_not_found' do
+      stub_flag_definitions([])
+      provider.start_polling_for_definitions!
+
+      result = provider.get_variant('missing', fallback, test_context)
+      expect(result.variant_source).to eq(Mixpanel::Flags::VariantSource::FALLBACK)
+      expect(result.fallback_reason.kind).to eq(:flag_not_found)
+      expect(result.fallback_reason.message).to be_nil
+      expect(result.variant_value).to eq('fb')
+    end
+
+    it 'tags missing context as FALLBACK / missing_context_key with the missing attribute' do
+      flag = create_test_flag(context: 'distinct_id')
+      stub_flag_definitions([flag])
+      provider.start_polling_for_definitions!
+
+      result = provider.get_variant('test_flag', fallback, {})
+      expect(result.variant_source).to eq(Mixpanel::Flags::VariantSource::FALLBACK)
+      expect(result.fallback_reason.kind).to eq(:missing_context_key)
+      expect(result.fallback_reason.message).to eq('distinct_id')
+    end
+
+    it 'tags no-rollout-match as FALLBACK / no_rollout_match' do
+      flag = create_test_flag(rollout_percentage: 0.0)
+      stub_flag_definitions([flag])
+      provider.start_polling_for_definitions!
+
+      result = provider.get_variant('test_flag', fallback, test_context)
+      expect(result.variant_source).to eq(Mixpanel::Flags::VariantSource::FALLBACK)
+      expect(result.fallback_reason.kind).to eq(:no_rollout_match)
+    end
   end
 
   describe 'polling' do
@@ -741,7 +945,8 @@ describe Mixpanel::Flags::LocalFlagsProvider do
         test_token,
         { enable_polling: true, polling_interval_in_seconds: 0.1 },
         mock_tracker,
-        mock_error_handler
+        mock_error_handler,
+        nil  # credentials
       )
 
       begin
@@ -755,5 +960,228 @@ describe Mixpanel::Flags::LocalFlagsProvider do
         polling_provider.stop_polling_for_definitions!
       end
     end
+
+    it 'shuts down promptly while the polling thread is waiting on the interval' do
+      flag = create_test_flag
+      stub_flag_definitions([flag])
+
+      polling_provider = Mixpanel::Flags::LocalFlagsProvider.new(
+        test_token,
+        # A long interval ensures the polling thread is parked on the wait when
+        # shutdown is requested — pre-fix, the join would have to ride out the
+        # full interval before the thread checked @stop_polling.
+        { enable_polling: true, polling_interval_in_seconds: 30 },
+        mock_tracker,
+        mock_error_handler
+      )
+
+      polling_provider.start_polling_for_definitions!
+      begin
+        # Wait until the polling thread is parked on the condition variable
+        # (status 'sleep') so the spec deterministically exercises the CV-wakeup
+        # path.
+        polling_thread = polling_provider.instance_variable_get(:@polling_thread)
+        Timeout.timeout(2) { sleep 0.01 until polling_thread.status == 'sleep' }
+
+        t0 = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        polling_provider.stop_polling_for_definitions!
+        elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - t0
+        expect(elapsed).to be < 1.0
+      ensure
+        polling_provider.stop_polling_for_definitions!
+      end
+    end
+
+    it 'shuts down promptly when stop races an in-flight fetch' do
+      flag = create_test_flag
+      fetch_count = 0
+      fetch_count_mutex = Mutex.new
+      second_fetch_started = Queue.new
+      second_fetch_release = Queue.new
+
+      stub_request(:get, endpoint_url_regex)
+        .to_return do |_request|
+          this_call = fetch_count_mutex.synchronize { fetch_count += 1 }
+          if this_call == 2
+            second_fetch_started << true
+            second_fetch_release.pop
+          end
+          {
+            status: 200,
+            body: { code: 200, flags: [flag] }.to_json,
+            headers: { 'Content-Type' => 'application/json' }
+          }
+        end
+
+      polling_provider = Mixpanel::Flags::LocalFlagsProvider.new(
+        test_token,
+        # 1 s interval — large enough that the lost-wakeup race (if reintroduced)
+        # would be detectable as ~1 s of extra teardown after the fetch finishes,
+        # but small enough that the second polling-thread fetch starts quickly.
+        { enable_polling: true, polling_interval_in_seconds: 1.0 },
+        mock_tracker,
+        mock_error_handler
+      )
+
+      polling_provider.start_polling_for_definitions!
+      begin
+        # Bounded wait: if a regression keeps the polling thread from reaching
+        # the second fetch, fail fast rather than hanging the suite.
+        Timeout.timeout(5) { second_fetch_started.pop }
+
+        # Trigger shutdown while the polling thread is mid-fetch (NOT on the
+        # CV), so the broadcast goes to no waiter. Run it in a thread so we can
+        # release the fetch afterwards.
+        stopper = Thread.new { polling_provider.stop_polling_for_definitions! }
+        # Wait until the stopper has set @stop_polling and broadcast, so
+        # releasing the fetch deterministically lands in the lost-wakeup window
+        # this spec targets.
+        Timeout.timeout(2) { sleep 0.01 until polling_provider.instance_variable_get(:@stop_polling) }
+
+        t0 = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        second_fetch_release << true
+        stopper.join
+        elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - t0
+
+        # With the predicate-inside-mutex check, the polling thread re-enters
+        # the mutex after fetch, sees @stop_polling = true, skips the wait, and
+        # breaks immediately. Without it, the thread would call wait(1.0 s),
+        # ride out the full interval, and only then break — elapsed would be
+        # ~1 s.
+        expect(elapsed).to be < 0.5
+      ensure
+        # Unblock any in-flight stub fetch in case we raised before releasing
+        # it normally — otherwise the polling thread stays blocked at
+        # second_fetch_release.pop and stop_polling_for_definitions!'s join
+        # would hang the suite.
+        second_fetch_release << true
+        polling_provider.stop_polling_for_definitions!
+      end
+    end
+
+    it 'stop arriving during the initial fetch wins; start does not spawn a thread' do
+      fetch_in_progress = Queue.new
+      fetch_release = Queue.new
+
+      stub_request(:get, endpoint_url_regex).to_return do |_req|
+        fetch_in_progress << true
+        fetch_release.pop
+        {
+          status: 200,
+          body: { code: 200, flags: [] }.to_json,
+          headers: { 'Content-Type' => 'application/json' }
+        }
+      end
+
+      polling_provider = Mixpanel::Flags::LocalFlagsProvider.new(
+        test_token,
+        { enable_polling: true, polling_interval_in_seconds: 30 },
+        mock_tracker,
+        mock_error_handler
+      )
+
+      starter = Thread.new { polling_provider.start_polling_for_definitions! }
+      begin
+        # Wait until start is blocked inside the initial fetch.
+        Timeout.timeout(5) { fetch_in_progress.pop }
+
+        # Stop arrives while start is mid-fetch (start has already cleared
+        # @stop_polling, so this is the bad case where stop's set must "win"
+        # despite happening between start's clear and start's spawn-decision).
+        polling_provider.stop_polling_for_definitions!
+
+        # Let start finish its fetch and reach the lifecycle check.
+        fetch_release << true
+        starter.join
+
+        # No polling thread should have been spawned — stop's postcondition
+        # (polling is off when stop returns) must hold even when start was
+        # mid-fetch at the time of the stop call.
+        expect(polling_provider.instance_variable_get(:@polling_thread)).to be_nil
+      ensure
+        fetch_release << true
+        starter&.join
+        polling_provider.stop_polling_for_definitions!
+      end
+    end
+
+    # SDK-78: safe_handle_error previously dispatched only to @error_handler,
+    # whose default Mixpanel::ErrorHandler#handle is a no-op — schema drift
+    # (NoMethodError, JSON::ParserError, etc.) looped forever undetected.
+    # Warn to stderr unconditionally so failures are visible without an
+    # error_handler being configured.
+    it 'warns to stderr when fetch raises and no error_handler is configured' do
+      stub_request(:get, endpoint_url_regex).to_return(status: 500, body: 'server down')
+
+      polling_provider = Mixpanel::Flags::LocalFlagsProvider.new(
+        test_token,
+        { enable_polling: false },
+        mock_tracker,
+        nil
+      )
+
+      expect { polling_provider.start_polling_for_definitions! }
+        .to output(/\[Mixpanel\] Failed to fetch flag definitions: Mixpanel::ServerError/).to_stderr
+    end
+
+    # Regression: previously the outer rescue on start_polling_for_definitions!
+    # caught an initial-fetch failure and returned before the @lifecycle_mutex
+    # block ever spawned the poller thread. A single startup blip (transient
+    # 500 / network timeout) left the SDK permanently without a poller until
+    # the caller retried — the whole point of polling.
+    it 'still spawns the polling thread when the initial fetch fails' do
+      stub_request(:get, endpoint_url_regex).to_return(status: 500, body: 'transient')
+
+      polling_provider = Mixpanel::Flags::LocalFlagsProvider.new(
+        test_token,
+        { enable_polling: true, polling_interval_in_seconds: 30 },
+        mock_tracker,
+        nil
+      )
+
+      begin
+        # Warning is expected because the initial fetch fails; capture stderr
+        # so it doesn't pollute test output.
+        expect { polling_provider.start_polling_for_definitions! }
+          .to output(/\[Mixpanel\] Failed to fetch flag definitions/).to_stderr
+
+        polling_thread = polling_provider.instance_variable_get(:@polling_thread)
+        expect(polling_thread).not_to be_nil
+        expect(polling_thread).to be_alive
+      ensure
+        polling_provider.stop_polling_for_definitions!
+      end
+    end
+  end
+
+  describe 'service account credentials' do
+    it 'uses service account credentials for authentication' do
+      credentials = Mixpanel::ServiceAccountCredentials.new('test-user', 'test-secret', 'test-project')
+      flag = create_test_flag
+
+      stub_request(:get, endpoint_url_regex)
+        .with(
+          basic_auth: ['test-user', 'test-secret']
+        )
+        .to_return(
+          status: 200,
+          body: { code: 200, flags: [flag] }.to_json,
+          headers: { 'Content-Type' => 'application/json' }
+        )
+
+      credentials_provider = Mixpanel::Flags::LocalFlagsProvider.new(
+        test_token,
+        config,
+        mock_tracker,
+        mock_error_handler,
+        credentials
+      )
+
+      credentials_provider.start_polling_for_definitions!
+      result = credentials_provider.get_variant_value('test_flag', 'fallback', test_context, report_exposure: false)
+
+      expect(result).not_to eq('fallback')
+      credentials_provider.stop_polling_for_definitions!
+    end
   end
 end

data/spec/mixpanel-ruby/flags/remote_flags_spec.rb

@@ -1,6 +1,8 @@
 require 'json'
+require 'timeout'
 require 'mixpanel-ruby/flags/remote_flags_provider'
 require 'mixpanel-ruby/flags/types'
+require 'mixpanel-ruby/credentials'
 require 'webmock/rspec'
 
 describe Mixpanel::Flags::RemoteFlagsProvider do
@@ -17,6 +19,7 @@ describe Mixpanel::Flags::RemoteFlagsProvider do
       config,
       mock_tracker,
       mock_error_handler
+      # credentials defaults to nil
     )
   end
 
@@ -116,6 +119,61 @@ describe Mixpanel::Flags::RemoteFlagsProvider do
       provider.get_variant_value('test_flag', 'control', test_context)
     end
 
+    it 'runs the tracker inline by default (no executor configured)' do
+      response = create_success_response({
+        'test_flag' => {
+          'variant_key' => 'treatment',
+          'variant_value' => 'treatment'
+        }
+      })
+      stub_flags_request(response)
+
+      calling_thread = Thread.current
+      tracker_thread = nil
+      allow(mock_tracker).to receive(:call) { tracker_thread = Thread.current }
+
+      provider.get_variant_value('test_flag', 'control', test_context)
+      expect(tracker_thread).to be(calling_thread)
+    end
+
+    it 'dispatches the tracker via the configured exposure_executor off the calling thread' do
+      response = create_success_response({
+        'test_flag' => {
+          'variant_key' => 'treatment',
+          'variant_value' => 'treatment'
+        }
+      })
+      stub_flags_request(response)
+
+      calling_thread = Thread.current
+      tracker_thread = nil
+      tracker_ran = Queue.new
+      tracker = ->(_distinct_id, _event, _properties) {
+        tracker_thread = Thread.current
+        tracker_ran << :done
+      }
+
+      # Minimal duck-typed executor: spawn a thread per call.
+      executor = Object.new
+      def executor.post(&block)
+        Thread.new(&block)
+      end
+
+      provider = Mixpanel::Flags::RemoteFlagsProvider.new(
+        test_token,
+        { exposure_executor: executor },
+        tracker,
+        mock_error_handler
+      )
+
+      provider.get_variant_value('test_flag', 'control', test_context)
+
+      # Bounded wait — a bare Queue#pop would hang CI forever if the
+      # tracker block raised before pushing :done.
+      Timeout.timeout(2) { tracker_ran.pop }
+      expect(tracker_thread).not_to be(calling_thread)
+    end
+
     it 'does not track exposure event when report_exposure is false' do
       response = create_success_response({
         'test_flag' => {
@@ -257,6 +315,18 @@ describe Mixpanel::Flags::RemoteFlagsProvider do
 
       provider.get_variant('any-flag', fallback_variant, test_context)
     end
+
+    it 'tags the fallback as BACKEND_ERROR with the response body on HTTP error (SDK-83)' do
+      stub_request(:get, %r{https://api\.mixpanel\.com/flags})
+        .to_return(status: 400, body: 'distinct_id must be provided in evalContext as a string')
+
+      fallback_variant = Mixpanel::Flags::SelectedVariant.new(variant_value: 'fb')
+      result = provider.get_variant('any-flag', fallback_variant, test_context, report_exposure: false)
+
+      expect(result.variant_source).to eq(Mixpanel::Flags::VariantSource::FALLBACK)
+      expect(result.fallback_reason.kind).to eq(:backend_error)
+      expect(result.fallback_reason.message).to include('distinct_id must be provided')
+    end
   end
 
   describe '#is_enabled' do
@@ -438,4 +508,38 @@ describe Mixpanel::Flags::RemoteFlagsProvider do
       provider.send(:track_exposure_event, 'test_flag', variant, test_context)
     end
   end
+
+  describe 'service account credentials' do
+    it 'uses service account credentials for authentication' do
+      credentials = Mixpanel::ServiceAccountCredentials.new('test-user', 'test-secret', 'test-project')
+
+      response = create_success_response({
+        'test_flag' => {
+          'variant_key' => 'treatment',
+          'variant_value' => 'treatment'
+        }
+      })
+
+      stub_request(:get, endpoint_url_regex)
+        .with(
+          basic_auth: ['test-user', 'test-secret']
+        )
+        .to_return(
+          status: 200,
+          body: response.to_json,
+          headers: { 'Content-Type' => 'application/json' }
+        )
+
+      credentials_provider = Mixpanel::Flags::RemoteFlagsProvider.new(
+        test_token,
+        config,
+        mock_tracker,
+        mock_error_handler,
+        credentials
+      )
+
+      result = credentials_provider.get_variant_value('test_flag', 'fallback', test_context, report_exposure: false)
+      expect(result).to eq('treatment')
+    end
+  end
 end

data/spec/mixpanel-ruby/flags/types_spec.rb

@@ -0,0 +1,55 @@
+require 'json'
+require 'mixpanel-ruby/flags/types'
+
+describe Mixpanel::Flags::SelectedVariant do
+  describe '#to_h' do
+    it 'returns a plain hash for a matched variant' do
+      variant = described_class.new(
+        variant_key: 'treatment',
+        variant_value: 'v1',
+        experiment_id: 'exp-1',
+        is_experiment_active: true,
+        variant_source: Mixpanel::Flags::VariantSource::LOCAL
+      )
+
+      expect(variant.to_h).to eq(
+        variant_key: 'treatment',
+        variant_value: 'v1',
+        experiment_id: 'exp-1',
+        is_experiment_active: true,
+        variant_source: 'local'
+      )
+    end
+
+    # SDK-125: previously to_h returned the raw FallbackReason object under
+    # :fallback_reason, so downstream serializers (e.g. .to_json,
+    # structured logging) got an object representation instead of the
+    # {kind:, message:} hash FallbackReason itself defines.
+    it 'recurses into FallbackReason so the result is fully hash-y' do
+      variant = described_class.new(
+        variant_value: 'fallback-value',
+        variant_source: Mixpanel::Flags::VariantSource::FALLBACK,
+        fallback_reason: Mixpanel::Flags::FallbackReason.backend_error('boom')
+      )
+
+      expect(variant.to_h[:fallback_reason]).to eq(kind: :backend_error, message: 'boom')
+    end
+
+    it 'round-trips through JSON without leaking a FallbackReason object' do
+      variant = described_class.new(
+        variant_value: 'fallback-value',
+        variant_source: Mixpanel::Flags::VariantSource::FALLBACK,
+        fallback_reason: Mixpanel::Flags::FallbackReason.missing_context_key('distinct_id')
+      )
+
+      parsed = JSON.parse(variant.to_h.to_json, symbolize_names: true)
+
+      expect(parsed[:fallback_reason]).to eq(kind: 'missing_context_key', message: 'distinct_id')
+    end
+
+    it 'compacts fallback_reason when absent' do
+      variant = described_class.new(variant_value: 'x', variant_source: 'local')
+      expect(variant.to_h).not_to have_key(:fallback_reason)
+    end
+  end
+end

data/spec/mixpanel-ruby/tracker_spec.rb

@@ -131,4 +131,22 @@ describe Mixpanel::Tracker do
       expect(expect).to eq(found)
     end
   end
+
+  describe 'service account credentials' do
+    it 'should pass credentials to flags providers when passed directly' do
+      credentials = Mixpanel::ServiceAccountCredentials.new('user', 'secret', 'project123')
+
+      tracker = Mixpanel::Tracker.new(
+        'TEST TOKEN',
+        nil,
+        credentials: credentials,
+        local_flags_config: {},
+        remote_flags_config: {}
+      )
+
+      # Verify credentials were passed to providers by checking internal state
+      expect(tracker.local_flags.instance_variable_get(:@credentials)).to eq(credentials)
+      expect(tracker.remote_flags.instance_variable_get(:@credentials)).to eq(credentials)
+    end
+  end
 end