mixpanel-ruby 2.3.0 → 3.1.0

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

@@ -0,0 +1,134 @@
+require 'mixpanel-ruby/flags/flags_provider'
+
+module Mixpanel
+  module Flags
+    # Remote feature flags provider
+    # Evaluates flags on the server-side via HTTP API calls
+    class RemoteFlagsProvider < FlagsProvider
+      DEFAULT_CONFIG = {
+        api_host: 'api.mixpanel.com',
+        request_timeout_in_seconds: 10
+      }.freeze
+
+      # @param token [String] Mixpanel project token
+      # @param config [Hash] Remote flags configuration
+      # @param tracker_callback [Proc] Callback to track events
+      # @param error_handler [Mixpanel::ErrorHandler] Error handler
+      def initialize(token, config, tracker_callback, error_handler)
+        merged_config = DEFAULT_CONFIG.merge(config || {})
+
+        provider_config = {
+          token: token,
+          api_host: merged_config[:api_host],
+          request_timeout_in_seconds: merged_config[:request_timeout_in_seconds]
+        }
+
+        super(provider_config, '/flags', tracker_callback, 'remote', error_handler)
+      end
+
+      # Get variant value for a flag
+      # @param flag_key [String] Feature flag key
+      # @param fallback_value [Object] Fallback value
+      # @param context [Hash] Evaluation context
+      # @param report_exposure [Boolean] Whether to track exposure
+      # @return [Object] Variant value
+      def get_variant_value(flag_key, fallback_value, context, report_exposure: true)
+        selected_variant = get_variant(
+          flag_key,
+          SelectedVariant.new(variant_value: fallback_value),
+          context,
+          report_exposure: report_exposure
+        )
+        selected_variant.variant_value
+      rescue MixpanelError => e
+        @error_handler.handle(e)
+        fallback_value
+      end
+
+      # Get complete variant information
+      # @param flag_key [String] Feature flag key
+      # @param fallback_variant [SelectedVariant] Fallback variant
+      # @param context [Hash] Evaluation context
+      # @param report_exposure [Boolean] Whether to track exposure
+      # @return [SelectedVariant]
+      def get_variant(flag_key, fallback_variant, context, report_exposure: true)
+        start_time = Time.now
+        response = fetch_flags(context, flag_key)
+        latency_ms = ((Time.now - start_time) * 1000).to_i
+
+        flags = response['flags'] || {}
+        selected_variant_data = flags[flag_key]
+
+        return fallback_variant 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']
+        )
+
+        track_exposure_event(flag_key, selected_variant, context, latency_ms) if report_exposure
+
+        return selected_variant
+      rescue MixpanelError => e
+        @error_handler.handle(e)
+        return fallback_variant
+      end
+
+      # Check if flag is enabled (for boolean flags)
+      # This method is intended only for flags defined as Mixpanel Feature Gates (boolean flags)
+      # This checks that the variant value of a selected variant is concretely the boolean 'true'
+      # It does not coerce other truthy values.
+      # @param flag_key [String] Feature flag key
+      # @param context [Hash] Evaluation context
+      # @return [Boolean]
+      def is_enabled?(flag_key, context)
+        value = get_variant_value(flag_key, false, context)
+        value == true
+      rescue MixpanelError => e
+        @error_handler.handle(e)
+        false
+      end
+
+      # Get all variants for user context
+      # Exposure events NOT tracked automatically
+      # @param context [Hash] Evaluation context
+      # @return [Hash, nil] Map of flag_key => SelectedVariant, or nil on error
+      def get_all_variants(context)
+        response = fetch_flags(context)
+
+        variants = {}
+        (response['flags'] || {}).each do |flag_key, variant_data|
+          variants[flag_key] = SelectedVariant.new(
+            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']
+          )
+        end
+
+        variants
+      rescue MixpanelError => e
+        @error_handler.handle(e)
+        nil
+      end
+
+      private
+
+      # Fetch flags from remote API
+      # @param context [Hash] Evaluation context
+      # @param flag_key [String, nil] Optional specific flag key
+      # @return [Hash] API response
+      def fetch_flags(context, flag_key = nil)
+        additional_params = {
+          'context' => JSON.generate(context)
+        }
+
+        additional_params['flag_key'] = flag_key if flag_key
+
+        call_flags_endpoint(additional_params)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,35 @@
+module Mixpanel
+  module Flags
+    # Selected variant returned from flag evaluation
+    class SelectedVariant
+      attr_accessor :variant_key, :variant_value, :experiment_id,
+                    :is_experiment_active, :is_qa_tester
+
+      # @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)
+        @variant_key = variant_key
+        @variant_value = variant_value
+        @experiment_id = experiment_id
+        @is_experiment_active = is_experiment_active
+        @is_qa_tester = is_qa_tester
+      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
+        }.compact
+      end
+    end
+  end
+end

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

@@ -0,0 +1,65 @@
+require 'securerandom'
+
+module Mixpanel
+  module Flags
+    module Utils
+      EXPOSURE_EVENT = '$experiment_started'.freeze
+
+      # FNV-1a 64-bit hash implementation
+      # Used for consistent variant assignment
+      #
+      # @param data [String] Data to hash
+      # @return [Integer] 64-bit hash value
+      def self.fnv1a_64(data)
+        fnv_prime = 0x100000001b3
+        hash_value = 0xcbf29ce484222325
+
+        data.bytes.each do |byte|
+          hash_value ^= byte
+          hash_value *= fnv_prime
+          hash_value &= 0xffffffffffffffff  # Keep 64-bit
+        end
+
+        hash_value
+      end
+
+      # Normalized hash for variant assignment
+      # Returns a float in the range [0.0, 1.0) for rollout percentage matching
+      #
+      # @param key [String] Key to hash (typically distinct_id)
+      # @param salt [String] Salt value (flag-specific)
+      # @return [Float] Value between 0.0 and 1.0 (non-inclusive upper bound)
+      def self.normalized_hash(key, salt)
+        combined = key.to_s + salt.to_s
+        hash_value = fnv1a_64(combined)
+        (hash_value % 100) / 100.0
+      end
+
+      # Prepare common query parameters for flags API
+      #
+      # @param token [String] Mixpanel project token
+      # @param $lib_version [String] SDK version
+      # @return [Hash] Query parameters
+      def self.prepare_common_query_params(token, lib_version)
+        {
+          'mp_lib' => 'ruby',
+          '$lib_version' => lib_version,
+          'token' => token
+        }
+      end
+
+      # Generate W3C traceparent header for distributed tracing
+      # Format: 00-{trace-id}-{parent-id}-{trace-flags}
+      #
+      # @return [String] traceparent header value
+      def self.generate_traceparent
+        version = '00'
+        trace_id = SecureRandom.hex(16)
+        parent_id = SecureRandom.hex(8)
+        trace_flags = '01'  # sampled
+
+        "#{version}-#{trace_id}-#{parent_id}-#{trace_flags}"
+      end
+    end
+  end
+end

data/lib/mixpanel-ruby/groups.rb

@@ -170,7 +170,7 @@ module Mixpanel
     def update(message)
       data = {
         '$token' => @token,
-        '$time' =>  Time.now.to_f,
+        '$time' =>  (Time.now.to_f * 1000).to_i,
       }.merge(message)
 
       message = {'data' => data}

data/lib/mixpanel-ruby/people.rb

@@ -223,7 +223,7 @@ module Mixpanel
     def update(message)
       data = {
         '$token' => @token,
-        '$time' =>  Time.now.to_f,
+        '$time' =>  (Time.now.to_f * 1000).to_i,
       }.merge(message)
 
       message = {'data' => data}

data/lib/mixpanel-ruby/tracker.rb

@@ -1,6 +1,8 @@
 require 'mixpanel-ruby/events.rb'
 require 'mixpanel-ruby/people.rb'
 require 'mixpanel-ruby/groups.rb'
+require 'mixpanel-ruby/flags/local_flags_provider.rb'
+require 'mixpanel-ruby/flags/remote_flags_provider.rb'
 
 module Mixpanel
   # Use Mixpanel::Tracker to track events and profile updates in your application.
@@ -33,6 +35,14 @@ module Mixpanel
     # An instance of Mixpanel::Groups. Use this to send groups updates
     attr_reader :groups
 
+    # An instance of Mixpanel::Flags::LocalFlagsProvider. Use this for
+    # client-side feature flag evaluation
+    attr_reader :local_flags
+
+    # An instance of Mixpanel::Flags::RemoteFlagsProvider. Use this for
+    # server-side feature flag evaluation
+    attr_reader :remote_flags
+
     # Takes your Mixpanel project token, as a string.
     #
     #    tracker = Mixpanel::Tracker.new(YOUR_MIXPANEL_TOKEN)
@@ -52,11 +62,31 @@ module Mixpanel
     # If a block is provided, it is passed a type (one of :event or :profile_update)
     # and a string message. This same format is accepted by Mixpanel::Consumer#send!
     # and Mixpanel::BufferedConsumer#send!
-    def initialize(token, error_handler=nil, &block)
+    def initialize(token, error_handler=nil, local_flags_config: nil, remote_flags_config: nil, &block)
       super(token, error_handler, &block)
       @token = token
       @people = People.new(token, error_handler, &block)
       @groups = Groups.new(token, error_handler, &block)
+
+      # Initialize local flags if config provided
+      if local_flags_config
+        @local_flags = Flags::LocalFlagsProvider.new(
+          token,
+          local_flags_config,
+          method(:track),  # Pass bound method as callback
+          error_handler || ErrorHandler.new
+        )
+      end
+
+      # Initialize remote flags if config provided
+      if remote_flags_config
+        @remote_flags = Flags::RemoteFlagsProvider.new(
+          token,
+          remote_flags_config,
+          method(:track),  # Pass bound method as callback
+          error_handler || ErrorHandler.new
+        )
+      end
     end
 
     # A call to #track is a report that an event has occurred.  #track
@@ -165,7 +195,7 @@ module Mixpanel
       properties = {
         'distinct_id' => distinct_id,
         'token' => @token,
-        'time' => Time.now.to_f,
+        'time' => (Time.now.to_f * 1000).to_i,
         'mp_lib' => 'ruby',
         '$lib_version' => Mixpanel::VERSION,
       }.merge(properties)

data/lib/mixpanel-ruby/version.rb

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

data/lib/mixpanel-ruby.rb

@@ -1,3 +1,8 @@
 require 'mixpanel-ruby/consumer.rb'
 require 'mixpanel-ruby/tracker.rb'
 require 'mixpanel-ruby/version.rb'
+require 'mixpanel-ruby/flags/utils.rb'
+require 'mixpanel-ruby/flags/types.rb'
+require 'mixpanel-ruby/flags/flags_provider.rb'
+require 'mixpanel-ruby/flags/local_flags_provider.rb'
+require 'mixpanel-ruby/flags/remote_flags_provider.rb'

data/mixpanel-ruby.gemspec

@@ -12,10 +12,17 @@ spec = Gem::Specification.new do |spec|
   spec.homepage = 'https://mixpanel.com/help/reference/ruby'
   spec.license = 'Apache License 2.0'
 
-  spec.required_ruby_version = '>= 2.0.0'
+  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_development_dependency 'activesupport', '~> 4.0'
-  spec.add_development_dependency 'rake', '~> 0'
+  spec.add_development_dependency 'rake', '~> 13'
   spec.add_development_dependency 'rspec', '~> 3.0'
-  spec.add_development_dependency 'webmock', '~> 1.18'
+  spec.add_development_dependency 'webmock', '~> 3.16.2'
+  spec.add_development_dependency 'debug'
+  spec.add_development_dependency 'ruby-lsp-rspec'
+  spec.add_development_dependency 'simplecov'
+  spec.add_development_dependency 'simplecov-cobertura'
 end

data/openfeature-provider/Gemfile

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+gemspec
+
+gem 'mixpanel-ruby', path: '..'

data/openfeature-provider/README.md

@@ -0,0 +1,286 @@
+# mixpanel-ruby-openfeature
+
+[![Gem Version](https://img.shields.io/gem/v/mixpanel-ruby-openfeature.svg)](https://rubygems.org/gems/mixpanel-ruby-openfeature)
+[![OpenFeature](https://img.shields.io/badge/OpenFeature-compatible-green)](https://openfeature.dev/)
+[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](https://github.com/mixpanel/mixpanel-ruby/blob/master/LICENSE)
+
+An [OpenFeature](https://openfeature.dev/) provider that wraps Mixpanel's feature flags for use with the OpenFeature Ruby SDK. This allows you to use Mixpanel's feature flagging capabilities through OpenFeature's standardized, vendor-agnostic API.
+
+## Overview
+
+This gem provides a bridge between Mixpanel's native feature flags implementation and the OpenFeature specification. By using this provider, you can:
+
+- Leverage Mixpanel's powerful feature flag and experimentation platform
+- Use OpenFeature's standardized API for flag evaluation
+- Easily switch between feature flag providers without changing your application code
+- Integrate with OpenFeature's ecosystem of tools and frameworks
+
+## Installation
+
+Add these gems to your `Gemfile`:
+
+```ruby
+gem 'mixpanel-ruby-openfeature'
+gem 'openfeature-sdk'
+gem 'mixpanel-ruby'
+```
+
+Then run:
+
+```bash
+bundle install
+```
+
+Or install directly:
+
+```bash
+gem install mixpanel-ruby-openfeature
+```
+
+## Quick Start
+
+### Local Evaluation (Recommended)
+
+Local evaluation downloads flag definitions and evaluates them locally, providing fast, synchronous flag checks with no per-evaluation network requests.
+
+```ruby
+require 'mixpanel-ruby'
+require 'mixpanel/openfeature'
+
+# 1. Create the provider with local evaluation
+provider = Mixpanel::OpenFeature::Provider.from_local(
+  'YOUR_PROJECT_TOKEN',
+  { poll_interval: 300 } # poll for updated definitions every 300 seconds
+)
+
+# 2. Register the provider with OpenFeature
+OpenFeature::SDK.configure do |config|
+  config.set_provider(provider)
+end
+
+# 3. Get a client and evaluate flags
+client = OpenFeature::SDK.build_client
+
+show_new_feature = client.fetch_boolean_value(flag_key: 'new-feature-flag', default_value: false)
+
+if show_new_feature
+  puts 'New feature is enabled!'
+end
+```
+
+### Remote Evaluation
+
+Remote evaluation sends each flag check to Mixpanel's servers, which is useful when you need server-side targeting or cannot download flag definitions locally.
+
+```ruby
+require 'mixpanel-ruby'
+require 'mixpanel/openfeature'
+
+# 1. Create the provider with remote evaluation
+provider = Mixpanel::OpenFeature::Provider.from_remote(
+  'YOUR_PROJECT_TOKEN',
+  {} # remote config options
+)
+
+# 2. Register the provider with OpenFeature
+OpenFeature::SDK.configure do |config|
+  config.set_provider(provider)
+end
+
+# 3. Evaluate flags the same way
+client = OpenFeature::SDK.build_client
+value = client.fetch_string_value(flag_key: 'button-color-test', default_value: 'blue')
+```
+
+### Manual Initialization
+
+If you already have a Mixpanel `Tracker` instance, you can pass its flags provider directly:
+
+```ruby
+tracker = Mixpanel::Tracker.new('YOUR_PROJECT_TOKEN', nil, local_flags_config: { poll_interval: 300 })
+flags_provider = tracker.local_flags
+flags_provider.start_polling_for_definitions!
+
+provider = Mixpanel::OpenFeature::Provider.new(flags_provider)
+```
+
+## Usage Examples
+
+### Basic Boolean Flag
+
+```ruby
+client = OpenFeature::SDK.build_client
+
+is_feature_enabled = client.fetch_boolean_value(flag_key: 'my-feature', default_value: false)
+
+if is_feature_enabled
+  # Show the new feature
+end
+```
+
+### Mixpanel Flag Types and OpenFeature Evaluation Methods
+
+Mixpanel feature flags support three flag types. Use the corresponding OpenFeature evaluation method based on your flag's variant values:
+
+| Mixpanel Flag Type | Variant Values | OpenFeature Method |
+|---|---|---|
+| Feature Gate | `true` / `false` | `fetch_boolean_value` |
+| Experiment | boolean, string, number, or JSON object | `fetch_boolean_value`, `fetch_string_value`, `fetch_number_value`, or `fetch_object_value` |
+| Dynamic Config | JSON object | `fetch_object_value` |
+
+```ruby
+client = OpenFeature::SDK.build_client
+
+# Feature Gate - boolean variants
+is_feature_on = client.fetch_boolean_value(flag_key: 'new-checkout', default_value: false)
+
+# Experiment with string variants
+button_color = client.fetch_string_value(flag_key: 'button-color-test', default_value: 'blue')
+
+# Experiment with number variants
+max_items = client.fetch_number_value(flag_key: 'max-items', default_value: 10)
+
+# Dynamic Config - JSON object variants
+feature_config = client.fetch_object_value(
+  flag_key: 'homepage-layout',
+  default_value: { 'layout' => 'grid', 'items_per_row' => 3 }
+)
+```
+
+### Getting Full Resolution Details
+
+If you need additional metadata about the flag evaluation:
+
+```ruby
+client = OpenFeature::SDK.build_client
+
+details = client.fetch_boolean_details(flag_key: 'my-feature', default_value: false)
+
+puts details.value       # The resolved value
+puts details.variant     # The variant key from Mixpanel
+puts details.reason      # Why this value was returned
+puts details.error_code  # Error code if evaluation failed
+```
+
+### Passing Evaluation Context
+
+You can pass evaluation context to provide additional properties for flag evaluation:
+
+```ruby
+context = OpenFeature::SDK::EvaluationContext.new(
+  targeting_key: 'user-123',
+  email: 'user@example.com',
+  plan: 'premium'
+)
+
+value = client.fetch_boolean_value(
+  flag_key: 'premium-feature',
+  default_value: false,
+  evaluation_context: context
+)
+```
+
+### Accessing the Mixpanel Tracker
+
+When using the `from_local` or `from_remote` class methods, you can access the underlying Mixpanel tracker for tracking events:
+
+```ruby
+provider = Mixpanel::OpenFeature::Provider.from_local('YOUR_PROJECT_TOKEN', {})
+
+# Access the tracker for event tracking
+provider.mixpanel.track('user-123', 'Page View', { 'page' => '/home' })
+```
+
+## Cleanup
+
+When you are done using the provider, shut it down to stop any background polling:
+
+```ruby
+provider.shutdown
+```
+
+## Error Handling
+
+The provider uses OpenFeature's standard error codes to indicate issues during flag evaluation:
+
+### PROVIDER_NOT_READY
+
+Returned when flags are evaluated before the provider has finished initializing (e.g., before flag definitions have been fetched for local evaluation).
+
+### FLAG_NOT_FOUND
+
+Returned when the requested flag does not exist in Mixpanel.
+
+```ruby
+details = client.fetch_boolean_details(flag_key: 'nonexistent-flag', default_value: false)
+
+if details.error_code == OpenFeature::SDK::Provider::ErrorCode::FLAG_NOT_FOUND
+  puts 'Flag does not exist, using default value'
+end
+```
+
+### TYPE_MISMATCH
+
+Returned when the flag value type does not match the requested type.
+
+```ruby
+# If 'my-flag' returns a string in Mixpanel but you request a boolean...
+details = client.fetch_boolean_details(flag_key: 'my-flag', default_value: false)
+
+if details.error_code == OpenFeature::SDK::Provider::ErrorCode::TYPE_MISMATCH
+  puts 'Flag is not a boolean, using default value'
+end
+```
+
+## FAQ
+
+### What Ruby versions are supported?
+
+Ruby 3.1.0 or later is required.
+
+### What is the difference between local and remote evaluation?
+
+**Local evaluation** downloads all flag definitions upfront and evaluates them in-process. This is faster (no network round-trip per evaluation) and works offline after the initial fetch. Use `from_local` for this mode.
+
+**Remote evaluation** sends each flag check to Mixpanel's servers. This ensures you always have the latest flag values and supports server-side-only targeting rules. Use `from_remote` for this mode.
+
+### Does targetingKey have special meaning?
+
+Unlike some feature flag providers, `targetingKey` is not used as a special bucketing key in Mixpanel. It is passed as another context property alongside all other fields. Mixpanel's server-side configuration determines which properties are used for targeting rules and bucketing.
+
+### Does the provider call mixpanel.identify()?
+
+No. User identity should be managed separately through the Mixpanel tracker's `track` or `people` methods. The provider only handles feature flag evaluation.
+
+### How are exposure events tracked?
+
+When a flag is successfully resolved, the provider automatically reports an exposure event via `report_exposure: true`. This tracks `$experiment_started` events in Mixpanel for analytics and experimentation reporting.
+
+### Can I use this with Rails?
+
+Yes. A common pattern is to initialize the provider in an initializer:
+
+```ruby
+# config/initializers/openfeature.rb
+provider = Mixpanel::OpenFeature::Provider.from_local(
+  ENV['MIXPANEL_TOKEN'],
+  { poll_interval: 300 }
+)
+
+OpenFeature::SDK.configure do |config|
+  config.set_provider(provider)
+end
+
+at_exit { provider.shutdown }
+```
+
+Then use it in controllers or services:
+
+```ruby
+client = OpenFeature::SDK.build_client
+show_banner = client.fetch_boolean_value(flag_key: 'show-banner', default_value: false)
+```
+
+## License
+
+Apache-2.0