mixpanel-ruby 3.2.0 → 3.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6e8271da642afa8ee7d980b2508db17f84f342f33405bde9dd6d0a15b8a10df0
-  data.tar.gz: 2d2da06b34ee942c35286b155bc5942a3ee56d8f17727063ebec16e5eb8d2149
+  metadata.gz: 1be60e96a1c17bd58aa1e6a1b9c17228a2b4934966c95bd893efa66d6a4a4f54
+  data.tar.gz: 8081213f4003791117e588c7afa479d249dd79ec219e16f109dda5ef26a0224c
 SHA512:
-  metadata.gz: 0f8236551ad44db0c9b3afdcefa17083bbca02ff00b6b9a236123857eaf38595070b258c923671b0f0672c76aa6baadefc7d169e02f27ec33cb475b4b9eabb70
-  data.tar.gz: 469d8373977e082acc887a8e11d8eeb973190a3488f40d5bb6fa66f4be7cd5c6e83772923e3ee291641f7aa25d8b0dd6d6123541f2e2ed90677c3b34f0e48bba
+  metadata.gz: f11a900846a56ab4d2ff879c23af112a086bee115e0b12aae4f5fb65ba9f37f6bb65959554e48da90d632e2e5a24070ed4e1867ef213db970d990caa2adc25c5
+  data.tar.gz: c7f2e19753de2dc9d55dcf93a798074ff1dc4cc82a5b2b33ce78dd765a33e98f6fc357d994580b38ac1ea2a92a9b942287f92ed3b34a4262f9bc75f476adc496

data/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## [v3.3.0](https://github.com/mixpanel/mixpanel-ruby/tree/v3.3.0) (2026-07-24)
+
+### Fixes
+- allow capability to offload reportExposure to async thread (SDK-80) ([#157](https://github.com/mixpanel/mixpanel-ruby/pull/157))
+- surface dropped exposure when distinct_id missing from context ([#154](https://github.com/mixpanel/mixpanel-ruby/pull/154))
+- distinguish fallback reasons + forward backend error message (SDK-79, SDK-83) ([#153](https://github.com/mixpanel/mixpanel-ruby/pull/153))
+
+[Full Changelog](https://github.com/mixpanel/mixpanel-ruby/compare/v3.2.0...v3.3.0)
+
 ## [v3.2.0](https://github.com/mixpanel/mixpanel-ruby/tree/v3.2.0) (2026-07-10)
 
 ### Features

data/Readme.rdoc

@@ -1,6 +1,6 @@
 = mixpanel-ruby: The official Mixpanel Ruby library
 
-##### _July 10, 2026_ - [v3.2.0](https://github.com/mixpanel/mixpanel-ruby/releases/tag/v3.2.0)
+##### _July 24, 2026_ - [v3.3.0](https://github.com/mixpanel/mixpanel-ruby/releases/tag/v3.3.0)
 
 mixpanel-ruby is a library for tracking events and sending \Mixpanel profile
 updates to \Mixpanel from your ruby applications.

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, :credentials (optional)
+      # @param provider_config [Hash] Configuration with :token, :api_host, :request_timeout_in_seconds, :exposure_executor, :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
+        @exposure_executor = provider_config[:exposure_executor]
         @credentials = provider_config[:credentials]
       end
 
@@ -102,6 +103,14 @@ module Mixpanel
         distinct_id = context['distinct_id'] || context[:distinct_id]
 
         unless distinct_id
+          # Local eval succeeds when the flag's Variant Assignment Key is
+          # something other than distinct_id (e.g., device_id), but the
+          # exposure event still needs distinct_id to attribute the user.
+          # Surface the drop instead of silently returning so callers can
+          # see they need to include distinct_id in the context.
+          @error_handler&.handle(MixpanelError.new(
+            "Cannot track exposure event for flag '#{flag_key}' without a distinct_id in the context"
+          ))
           return
         end
 
@@ -118,12 +127,40 @@ module Mixpanel
         properties['$is_experiment_active'] = selected_variant.is_experiment_active unless selected_variant.is_experiment_active.nil?
         properties['$is_qa_tester'] = selected_variant.is_qa_tester unless selected_variant.is_qa_tester.nil?
 
-        begin
-          @tracker_callback.call(distinct_id, Utils::EXPOSURE_EVENT, properties)
-        rescue MixpanelError => e
-          @error_handler.handle(e)
+        dispatch_exposure(distinct_id, properties)
+      end
+
+      private
+
+      # Dispatch the tracker call inline or via the configured executor.
+      # The executor is duck-typed — anything that responds to #post(&block)
+      # works (Concurrent::ExecutorService, or a Thread.new wrapper).
+      #
+      # Async path only: catch any non-MixpanelError from the tracker so it
+      # doesn't terminate the executor thread silently. Inline path
+      # preserves the original behavior — non-MixpanelError propagates to
+      # the flag evaluator's caller unchanged.
+      def dispatch_exposure(distinct_id, properties)
+        if @exposure_executor
+          begin
+            @exposure_executor.post do
+              invoke_tracker(distinct_id, properties)
+            rescue StandardError => e
+              @error_handler.handle(MixpanelError.new("Exposure event failed: #{e.class}: #{e.message}")) if @error_handler
+            end
+          rescue StandardError => e
+            @error_handler.handle(MixpanelError.new("Exposure event dropped — executor refused to accept task: #{e.message}")) if @error_handler
+          end
+        else
+          invoke_tracker(distinct_id, properties)
         end
       end
+
+      def invoke_tracker(distinct_id, properties)
+        @tracker_callback.call(distinct_id, Utils::EXPOSURE_EVENT, properties)
+      rescue MixpanelError => e
+        @error_handler.handle(e) if @error_handler
+      end
     end
   end
 end

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

@@ -11,7 +11,8 @@ module Mixpanel
         api_host: 'api.mixpanel.com',
         request_timeout_in_seconds: 10,
         enable_polling: true,
-        polling_interval_in_seconds: 60
+        polling_interval_in_seconds: 60,
+        exposure_executor: nil
       }.freeze
 
       # @param token [String] Mixpanel project token
@@ -37,6 +38,7 @@ module Mixpanel
           token: token,
           api_host: @config[:api_host],
           request_timeout_in_seconds: @config[:request_timeout_in_seconds],
+          exposure_executor: @config[:exposure_executor],
           credentials: credentials
         }
 
@@ -71,7 +73,17 @@ module Mixpanel
         # 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
+        #
+        # A transient failure here (network blip, HTTP 500) should NOT prevent
+        # the polling thread from spawning — the loop retries on the configured
+        # interval. Without this inner rescue, the outer rescue below would
+        # catch and return, leaving the SDK permanently without polling until
+        # the caller manually retried.
+        begin
+          fetch_flag_definitions
+        rescue StandardError => e
+          safe_handle_error(e)
+        end
 
         @lifecycle_mutex.synchronize do
           # If a stop arrived during/after our @stop_polling clear above, abort
@@ -159,11 +171,11 @@ module Mixpanel
       def get_variant(flag_key, fallback_variant, context, report_exposure: true)
         flag = @flag_definitions[flag_key]
 
-        return fallback_variant unless flag
+        return fallback_variant.as_fallback(FallbackReason.flag_not_found) unless flag
 
         context_key = flag['context']
         unless context.key?(context_key) || context.key?(context_key.to_sym)
-          return fallback_variant
+          return fallback_variant.as_fallback(FallbackReason.missing_context_key(context_key))
         end
 
         context_value = context[context_key] || context[context_key.to_sym]
@@ -175,10 +187,10 @@ module Mixpanel
           selected_variant = get_assigned_variant(flag, context_value, flag_key, rollout) if rollout
         end
 
-        return fallback_variant unless selected_variant
+        return fallback_variant.as_fallback(FallbackReason.no_rollout_match) unless selected_variant
 
         track_exposure_event(flag_key, selected_variant, context) if report_exposure
-        selected_variant
+        selected_variant.with_source(VariantSource::LOCAL)
       end
 
       # Get all variants for user context
@@ -187,10 +199,11 @@ module Mixpanel
       # @return [Hash] Map of flag_key => SelectedVariant
       def get_all_variants(context)
         variants = {}
+        fallback = SelectedVariant.new(variant_value: nil)
 
         @flag_definitions.each_key do |flag_key|
-          variant = get_variant(flag_key, nil, context, report_exposure: false)
-          variants[flag_key] = variant if variant
+          variant = get_variant(flag_key, fallback, context, report_exposure: false)
+          variants[flag_key] = variant if variant.variant_source == VariantSource::LOCAL
         end
 
         variants
@@ -201,11 +214,19 @@ module Mixpanel
       # 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.
+      #
+      # Always warn to stderr as well. The default Mixpanel::ErrorHandler#handle
+      # is a no-op, so dispatching only via @error_handler swallows schema drift
+      # (NoMethodError, JSON::ParserError, etc.) — the loop runs forever
+      # undetected. Matches the convention in mixpanel-python / mixpanel-java /
+      # mixpanel-go / mixpanel-node, all of which log unconditionally and keep
+      # polling.
       def safe_handle_error(error)
+        warn "[Mixpanel] Failed to fetch flag definitions: #{error.class}: #{error.message}"
         @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.
+        # Swallow handler failures: keeping the polling loop alive is more
+        # important than propagating a broken handler's failure.
       end
 
       def fetch_flag_definitions

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

@@ -7,7 +7,8 @@ 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
@@ -22,6 +23,7 @@ module Mixpanel
           token: token,
           api_host: merged_config[:api_host],
           request_timeout_in_seconds: merged_config[:request_timeout_in_seconds],
+          exposure_executor: merged_config[:exposure_executor],
           credentials: credentials
         }
 
@@ -61,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
@@ -75,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)
@@ -106,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/version.rb

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

data/openfeature-provider/README.md

@@ -201,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/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/flags/local_flags_spec.rb

@@ -749,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
@@ -931,6 +1104,54 @@ describe Mixpanel::Flags::LocalFlagsProvider do
         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

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

@@ -1,4 +1,5 @@
 require 'json'
+require 'timeout'
 require 'mixpanel-ruby/flags/remote_flags_provider'
 require 'mixpanel-ruby/flags/types'
 require 'mixpanel-ruby/credentials'
@@ -118,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' => {
@@ -259,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

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: mixpanel-ruby
 version: !ruby/object:Gem::Version
-  version: 3.2.0
+  version: 3.3.0
 platform: ruby
 authors:
 - Mixpanel
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-07-10 00:00:00.000000000 Z
+date: 2026-07-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: mutex_m
@@ -221,6 +221,7 @@ files:
 - spec/mixpanel-ruby/events_spec.rb
 - spec/mixpanel-ruby/flags/local_flags_spec.rb
 - spec/mixpanel-ruby/flags/remote_flags_spec.rb
+- spec/mixpanel-ruby/flags/types_spec.rb
 - spec/mixpanel-ruby/flags/utils_spec.rb
 - spec/mixpanel-ruby/groups_spec.rb
 - spec/mixpanel-ruby/people_spec.rb