mixpanel-ruby 3.2.0 → 3.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6e8271da642afa8ee7d980b2508db17f84f342f33405bde9dd6d0a15b8a10df0
-  data.tar.gz: 2d2da06b34ee942c35286b155bc5942a3ee56d8f17727063ebec16e5eb8d2149
+  metadata.gz: c087578749eaaa76591b16c382aef85e38e276501c39c8a82e5ff155e2572747
+  data.tar.gz: edc867253e2a32dafa92dc32cc318d6aab740de9a776955715eef42972810b90
 SHA512:
-  metadata.gz: 0f8236551ad44db0c9b3afdcefa17083bbca02ff00b6b9a236123857eaf38595070b258c923671b0f0672c76aa6baadefc7d169e02f27ec33cb475b4b9eabb70
-  data.tar.gz: 469d8373977e082acc887a8e11d8eeb973190a3488f40d5bb6fa66f4be7cd5c6e83772923e3ee291641f7aa25d8b0dd6d6123541f2e2ed90677c3b34f0e48bba
+  metadata.gz: a635485dfad21d6c20c7beafb831bd27af2333ca59b2cf3e04e3be6fd09dbc506c4ac67b160415a6d70646e9068290ffdcd6160453dee0b88ff4a1ec799e7253
+  data.tar.gz: 173b6b1e59c299c5ddbf3c36f02ef64893388d55ea94671fb4da15a8e636e7bc2c943cf4b5f9c81a941f20a73e3c97cd508fd681d21dca85b25b94b3f612514f

data/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## [v3.4.0](https://github.com/mixpanel/mixpanel-ruby/tree/v3.4.0) (2026-09-01)
+
+### Features
+- Implement semver and date custom ops for flags runtime props ([#171](https://github.com/mixpanel/mixpanel-ruby/pull/171))
+
+[Full Changelog](https://github.com/mixpanel/mixpanel-ruby/compare/v3.3.0...v3.4.0)
+
+## [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)
+##### _September 01, 2026_ - [v3.4.0](https://github.com/mixpanel/mixpanel-ruby/releases/tag/v3.4.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/custom_operators.rb

@@ -0,0 +1,207 @@
+require 'date'
+require 'time'
+require 'json_logic'
+
+module Mixpanel
+  module Flags
+    module CustomOperators
+      # Using the official semantic versioning 2.0.0 regular expression to handle cross-platform validation
+      # differences on other SDK's. For example, some platforms allow leading zeros even though it is not valid
+      # as part of the Semver 2.0.0 spec. See https://semver.org/
+      SEMVER_STRICT = /\A(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?\z/
+
+      # Strict RFC3339 guard for datetime strings. The date and hour fields are captured so the
+      # calendar can be validated separately; the pattern only constrains their shape.
+      RFC3339_STRICT = /\A(\d{4})-(\d{2})-(\d{2})[Tt](\d{2}):\d{2}:\d{2}(\.\d+)?([Zz]|[+-]\d{2}:\d{2})\z/
+
+      # SemVer 2.0.0 requires major.minor.patch; partial versions are zero-padded to this.
+      SEMVER_PARTS = 3
+
+      # Longest operand the semver regex is allowed to see. A real version never approaches this; the
+      # bound matches MAX_LENGTH in node-semver, and keeps an arbitrarily long property value off the
+      # regex regardless of how the engine schedules backtracking.
+      MAX_SEMVER_LENGTH = 256
+
+      # Epoch milliseconds are compared as int64 elsewhere, so anything at or beyond this is out of range.
+      MAX_EPOCH_MS = 2**63
+
+      module_function
+
+      # Implements a custom operation for semantic versioning comparison that conforms to the
+      # semver 2.0.0 standard. Prior to comparison, any leading version prefix is stripped.
+      def semver_compare(values)
+        unpacked = operands(values)
+        return false unless unpacked
+
+        actual, symbol, target = unpacked
+        return false unless actual.is_a?(String) && target.is_a?(String)
+        return false if actual.length > MAX_SEMVER_LENGTH || target.length > MAX_SEMVER_LENGTH
+
+        actual_version = normalize_semver(actual)
+        target_version = normalize_semver(target)
+        return false unless actual_version.match?(SEMVER_STRICT) && target_version.match?(SEMVER_STRICT)
+
+        cmp = compare_semver(actual_version, target_version)
+        comparator_matches?(cmp, symbol)
+      end
+
+      # Strip optional build metadata and separate the core version from pre-release identifiers
+      def split_semver(version)
+        plus = version.index('+')
+        version = version[0, plus] if plus
+        dash = version.index('-')
+        return [version.split('.'), []] unless dash
+
+        [version[0, dash].split('.'), version[(dash + 1)..-1].split('.')]
+      end
+
+      def numeric_identifier?(identifier)
+        identifier.match?(/\A[0-9]+\z/)
+      end
+
+      # Numeric identifiers carry no leading zeros, so the longer run of digits is the larger number.
+      # Comparing them as digits rather than parsing to a fixed-width integer keeps versions that
+      # overflow a 64-bit integer ordered correctly.
+      def compare_numeric(a, b)
+        return a.length <=> b.length unless a.length == b.length
+
+        a <=> b
+      end
+
+      # SemVer 2.0.0 section 11.4: digits compare numerically, a numeric identifier ranks below an
+      # alphanumeric one, and anything else compares by ASCII order.
+      def compare_prerelease_identifier(a, b)
+        a_numeric = numeric_identifier?(a)
+        b_numeric = numeric_identifier?(b)
+        return compare_numeric(a, b) if a_numeric && b_numeric
+        return -1 if a_numeric
+        return 1 if b_numeric
+
+        a <=> b
+      end
+
+      # Ordering per SemVer 2.0.0 section 11. Both operands have already been normalized and matched
+      # against the official regex, so the core holds exactly three numeric identifiers and every
+      # prerelease field is well-formed; the split needs no error path.
+      def compare_semver(actual, target)
+        actual_core, actual_prerelease = split_semver(actual)
+        target_core, target_prerelease = split_semver(target)
+
+        actual_core.each_with_index do |part, index|
+          result = compare_numeric(part, target_core[index])
+          return result unless result.zero?
+        end
+
+        # A prerelease ranks below the release it belongs to (section 11.3).
+        return 0 if actual_prerelease.empty? && target_prerelease.empty?
+        return 1 if actual_prerelease.empty?
+        return -1 if target_prerelease.empty?
+
+        [actual_prerelease.length, target_prerelease.length].min.times do |index|
+          result = compare_prerelease_identifier(actual_prerelease[index], target_prerelease[index])
+          return result unless result.zero?
+        end
+        # Every field so far is equal, so the longer list wins (section 11.4.4).
+        actual_prerelease.length <=> target_prerelease.length
+      end
+
+      # Implements a custom operation for datetime comparison. The target value stored on the
+      # feature flag is the millisecond epoch, whereas the actual value provided at evaluation
+      # time must be RFC-3339 formatted.
+      def datetime_compare(values)
+        unpacked = operands(values)
+        return false unless unpacked
+
+        actual, symbol, target = unpacked
+        actual_sec = convert_rfc3339_to_unix_seconds(actual)
+        target_sec = convert_unix_milliseconds_to_seconds(target)
+        return false unless actual_sec && target_sec
+
+        cmp = actual_sec - target_sec
+        comparator_matches?(cmp, symbol)
+      end
+
+      def operands(values)
+        return nil unless values.length == 3
+
+        actual, symbol, target = values
+        return nil unless symbol.is_a?(String)
+
+        [actual, symbol, target]
+      end
+
+      def comparator_matches?(cmp, symbol)
+        case symbol
+        when '===' then cmp.zero?
+        when '!==' then !cmp.zero?
+        when '<' then cmp < 0
+        when '<=' then cmp <= 0
+        when '>' then cmp > 0
+        when '>=' then cmp >= 0
+        else false
+        end
+      end
+
+      def normalize_semver(str)
+        stripped = str.strip
+        stripped = stripped[1..] if stripped =~ /\Av/i
+
+        suffix_start = stripped.length
+        ['-', '+'].each do |separator|
+          index = stripped.index(separator)
+          suffix_start = index if index && index < suffix_start
+        end
+
+        core = stripped[0, suffix_start]
+        suffix = stripped[suffix_start..] || ''
+
+        # split(-1) keeps trailing empty fields, so "1." and "1.2.3." stay malformed instead of
+        # silently padding to a valid version. Returning the input unchanged lets the validator reject it.
+        segments = core.split('.', -1)
+        return stripped unless segments.length.between?(1, SEMVER_PARTS) && segments.all? { |seg| seg.match?(/\A\d+\z/) }
+
+        segments += ['0'] * (SEMVER_PARTS - segments.length)
+        segments.join('.') + suffix
+      end
+
+      # The pattern constrains each field to two digits, which still admits a date that cannot exist,
+      # such as 2026-02-30 or 29 February in a common year. Time.iso8601 rolls those forward into a
+      # real instant instead of raising, and hour 24 likewise becomes the following midnight, so the
+      # calendar is checked here. RFC 3339 section 5.6 allows hours 00 through 23.
+      def real_calendar_date?(year, month, day, hour)
+        hour <= 23 && Date.valid_date?(year, month, day)
+      end
+
+      def convert_rfc3339_to_unix_seconds(value)
+        return nil unless value.is_a?(String)
+
+        normalized = value.strip.upcase
+        fields = RFC3339_STRICT.match(normalized)
+        return nil unless fields
+        return nil unless real_calendar_date?(fields[1].to_i, fields[2].to_i, fields[3].to_i, fields[4].to_i)
+
+        parsed = Time.iso8601(normalized)
+        parsed.to_i
+      rescue ArgumentError
+        nil
+      end
+
+      def convert_unix_milliseconds_to_seconds(value)
+        return nil unless value.is_a?(Numeric)
+        # A value int64 cannot represent is not a real timestamp; treating one as a bound would let a
+        # nonsense target define a rollout window. NaN fails this comparison too.
+        return nil unless value.abs < MAX_EPOCH_MS
+
+        value.to_i.fdiv(1000).truncate
+      end
+    end
+  end
+end
+
+JsonLogic.add_operation('semver_compare') do |values, _data|
+  Mixpanel::Flags::CustomOperators.semver_compare(values)
+end
+
+JsonLogic.add_operation('datetime_compare') do |values, _data|
+  Mixpanel::Flags::CustomOperators.datetime_compare(values)
+end

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

@@ -1,6 +1,7 @@
 require 'thread'
 require 'json_logic'
 require 'mixpanel-ruby/flags/flags_provider'
+require 'mixpanel-ruby/flags/custom_operators'
 
 module Mixpanel
   module Flags
@@ -11,7 +12,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 +39,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 +74,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 +172,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 +188,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 +200,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 +215,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
@@ -356,7 +378,10 @@ module Mixpanel
         begin
           rule = lowercase_only_leaf_nodes(runtime_rule)
           result = JsonLogic.apply(rule, parameters)
-          !!result
+          # A well-formed runtime rule evaluates to a boolean. Anything else —
+          # notably an unrecognized operator, which the engine echoes back as a
+          # (truthy) hash rather than raising — fails closed.
+          result == true
         rescue StandardError => e
           @error_handler.handle(e) if @error_handler
           false

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.4.0'
 end

data/mixpanel-ruby.gemspec

@@ -15,7 +15,7 @@ spec = Gem::Specification.new do |spec|
   spec.required_ruby_version = '>= 3.0.0'
   spec.add_runtime_dependency 'mutex_m'
   spec.add_runtime_dependency "base64"
-  spec.add_runtime_dependency 'json-logic-rb', '~> 0.1.5'
+  spec.add_runtime_dependency 'json-logic-rb', '~> 0.2'
 
   spec.add_development_dependency 'activesupport', '~> 4.0'
   spec.add_development_dependency 'rake', '~> 13'

data/openfeature-provider/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## [openfeature/v0.2.0](https://github.com/mixpanel/mixpanel-ruby/tree/openfeature/v0.2.0) (2026-07-28)
+
+### Features
+- add service account support ([#152](https://github.com/mixpanel/mixpanel-ruby/pull/152))
+
+### Chores
+- pin mixpanel-ruby ~> 3.3 for fallback_reason (SDK-126) ([#166](https://github.com/mixpanel/mixpanel-ruby/pull/166))
+
+[Full Changelog](https://github.com/mixpanel/mixpanel-ruby/compare/openfeature/v0.1.0...openfeature/v0.2.0)
+
 ## [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.