mixpanel-ruby 3.0.0 → 3.2.0

data/lib/mixpanel-ruby/tracker.rb

@@ -62,9 +62,14 @@ module Mixpanel
     # If a block is provided, it is passed a type (one of :event or :profile_update)
     # and a string message. This same format is accepted by Mixpanel::Consumer#send!
     # and Mixpanel::BufferedConsumer#send!
-    def initialize(token, error_handler=nil, local_flags_config: nil, remote_flags_config: nil, &block)
-      super(token, error_handler, &block)
-      @token = token
+    #
+    # Optional parameters:
+    # - credentials: ServiceAccountCredentials for authentication (used for import and feature flags)
+    # - local_flags_config: Configuration hash for local feature flags
+    # - remote_flags_config: Configuration hash for remote feature flags
+    def initialize(token, error_handler=nil, credentials: nil, local_flags_config: nil, remote_flags_config: nil, &block)
+      super(token, error_handler, credentials: credentials, &block)
+
       @people = People.new(token, error_handler, &block)
       @groups = Groups.new(token, error_handler, &block)
 
@@ -74,7 +79,8 @@ module Mixpanel
           token,
           local_flags_config,
           method(:track),  # Pass bound method as callback
-          error_handler || ErrorHandler.new
+          error_handler || ErrorHandler.new,
+          credentials
         )
       end
 
@@ -84,7 +90,8 @@ module Mixpanel
           token,
           remote_flags_config,
           method(:track),  # Pass bound method as callback
-          error_handler || ErrorHandler.new
+          error_handler || ErrorHandler.new,
+          credentials
         )
       end
     end
@@ -122,14 +129,15 @@ module Mixpanel
     #
     #     tracker = Mixpanel::Tracker.new(YOUR_MIXPANEL_TOKEN)
     #
-    #     # Import event that user "12345"'s credit card was declined
+    #     # Using deprecated API key (still supported)
     #     tracker.import("API_KEY", "12345", "Credit Card Declined", {
     #       'time' => 1310111365
     #     })
     #
-    #     # Properties describe the circumstances of the event,
-    #     # or aspects of the source or user associated with the event
-    #     tracker.import("API_KEY", "12345", "Welcome Email Sent", {
+    #     # Using service account credentials (recommended)
+    #     credentials = Mixpanel::ServiceAccountCredentials.new(username, secret, project_id)
+    #     tracker = Mixpanel::Tracker.new(YOUR_MIXPANEL_TOKEN, credentials: credentials)
+    #     tracker.import(nil, "12345", "Welcome Email Sent", {
     #         'Email Template' => 'Pretty Pink Welcome',
     #         'User Sign-up Cohort' => 'July 2013',
     #         'time' => 1310111365
@@ -140,6 +148,28 @@ module Mixpanel
       super
     end
 
+    # Import an event using service account credentials from the constructor.
+    # This is the recommended method for importing historical events with service accounts.
+    #
+    # Service account credentials must be provided when creating the Tracker.
+    # This method provides a cleaner API than import() as it doesn't require
+    # passing nil as the first parameter.
+    #
+    #     credentials = Mixpanel::ServiceAccountCredentials.new(username, secret, project_id)
+    #     tracker = Mixpanel::Tracker.new(YOUR_MIXPANEL_TOKEN, credentials: credentials)
+    #
+    #     # Import a historical event
+    #     tracker.import_events('user123', 'Past Event', {
+    #         'Email Template' => 'Welcome Email',
+    #         'time' => 1369353600
+    #     })
+    #
+    def import_events(distinct_id, event, properties={}, ip=nil)
+      # This is here strictly to allow rdoc to include the relevant
+      # documentation
+      super
+    end
+
     # Creates a distinct_id alias. \Events and updates with an alias
     # will be considered by mixpanel to have the same source, and
     # refer to the same profile.

data/lib/mixpanel-ruby/version.rb

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

data/lib/mixpanel-ruby.rb

@@ -1,6 +1,7 @@
 require 'mixpanel-ruby/consumer.rb'
 require 'mixpanel-ruby/tracker.rb'
 require 'mixpanel-ruby/version.rb'
+require 'mixpanel-ruby/credentials.rb'
 require 'mixpanel-ruby/flags/utils.rb'
 require 'mixpanel-ruby/flags/types.rb'
 require 'mixpanel-ruby/flags/flags_provider.rb'

data/openfeature-provider/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## [openfeature/v0.1.0](https://github.com/mixpanel/mixpanel-ruby/tree/openfeature/v0.1.0) (2026-05-13)
+
+Initial release of the Mixpanel OpenFeature provider for Ruby.

data/openfeature-provider/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,288 @@
+# mixpanel-ruby-openfeature
+
+##### _May 13, 2026_ - [openfeature/v0.1.0](https://github.com/mixpanel/mixpanel-ruby/releases/tag/openfeature/v0.1.0)
+
+[![Gem Version](https://img.shields.io/gem/v/mixpanel-ruby-openfeature.svg)](https://rubygems.org/gems/mixpanel-ruby-openfeature)
+[![OpenFeature](https://img.shields.io/badge/OpenFeature-compatible-green)](https://openfeature.dev/)
+[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](https://github.com/mixpanel/mixpanel-ruby/blob/master/LICENSE)
+
+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

data/openfeature-provider/RELEASE.md

@@ -0,0 +1,52 @@
+# Releasing the OpenFeature Provider
+
+The OpenFeature provider (`mixpanel-ruby-openfeature`) is published to RubyGems independently from the core SDK.
+
+## Release Order
+
+The OpenFeature provider depends on features added to `mixpanel-ruby` in version 3.1.0+ (e.g., `shutdown` methods on flags providers). You **must** publish the core SDK first:
+
+1. Publish `mixpanel-ruby` (bump version in `lib/mixpanel-ruby/version.rb`, build, push)
+2. Verify the new version is live on https://rubygems.org/gems/mixpanel-ruby
+3. Then publish `mixpanel-ruby-openfeature` (steps below)
+
+If you update the core SDK version, update the dependency constraint in `mixpanel-ruby-openfeature.gemspec` to match.
+
+## Prerequisites
+
+- Ruby 3.1+
+- A RubyGems account with permission to push to the `mixpanel-ruby-openfeature` gem
+  - For the first upload, you'll need owner access or to create the gem under the Mixpanel org
+  - Sign in and get your API key at https://rubygems.org/profile/edit
+
+## Releasing
+
+1. Update the version in `mixpanel-ruby-openfeature.gemspec`
+
+2. Build the gem:
+   ```bash
+   cd openfeature-provider
+   gem build mixpanel-ruby-openfeature.gemspec
+   ```
+
+3. Verify the built artifact:
+   ```bash
+   ls *.gem
+   # Should show: mixpanel-ruby-openfeature-<version>.gem
+   ```
+
+4. Push to RubyGems:
+   ```bash
+   gem push mixpanel-ruby-openfeature-<version>.gem
+   ```
+   You'll be prompted for your RubyGems credentials on first push. Alternatively, configure `~/.gem/credentials` with your API key:
+   ```yaml
+   ---
+   :rubygems_api_key: rubygems_<your-key>
+   ```
+
+5. Verify at https://rubygems.org/gems/mixpanel-ruby-openfeature
+
+## Versioning
+
+The OpenFeature provider is versioned independently from the core SDK. The core SDK dependency is declared in the gemspec (`mixpanel-ruby ~> 3.0`) — update it when the provider needs features from a newer core SDK release.

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

@@ -0,0 +1,170 @@
+# frozen_string_literal: true
+
+require 'open_feature/sdk'
+
+module Mixpanel
+  module OpenFeature
+    class Provider
+      attr_reader :metadata, :mixpanel
+
+      def self.from_local(token, config, error_handler: nil)
+        tracker = ::Mixpanel::Tracker.new(token, error_handler, local_flags_config: config)
+        flags_provider = tracker.local_flags
+        flags_provider.start_polling_for_definitions!
+        provider = new(flags_provider)
+        provider.instance_variable_set(:@mixpanel, tracker)
+        provider
+      end
+
+      def self.from_remote(token, config, error_handler: nil)
+        tracker = ::Mixpanel::Tracker.new(token, error_handler, remote_flags_config: config)
+        flags_provider = tracker.remote_flags
+        provider = new(flags_provider)
+        provider.instance_variable_set(:@mixpanel, tracker)
+        provider
+      end
+
+      def initialize(flags_provider)
+        @flags_provider = flags_provider
+        @metadata = ::OpenFeature::SDK::Provider::ProviderMetadata.new(name: 'mixpanel-provider').freeze
+      end
+
+      def shutdown
+        @flags_provider.shutdown if @flags_provider.respond_to?(:shutdown)
+      end
+
+      def fetch_boolean_value(flag_key:, default_value:, evaluation_context: nil)
+        resolve(flag_key, default_value, :boolean, evaluation_context)
+      end
+
+      def fetch_string_value(flag_key:, default_value:, evaluation_context: nil)
+        resolve(flag_key, default_value, :string, evaluation_context)
+      end
+
+      def fetch_number_value(flag_key:, default_value:, evaluation_context: nil)
+        resolve(flag_key, default_value, :number, evaluation_context)
+      end
+
+      def fetch_integer_value(flag_key:, default_value:, evaluation_context: nil)
+        resolve(flag_key, default_value, :integer, evaluation_context)
+      end
+
+      def fetch_float_value(flag_key:, default_value:, evaluation_context: nil)
+        resolve(flag_key, default_value, :float, evaluation_context)
+      end
+
+      def fetch_object_value(flag_key:, default_value:, evaluation_context: nil)
+        resolve(flag_key, default_value, :object, evaluation_context)
+      end
+
+      private
+
+      def resolve(flag_key, default_value, expected_type, evaluation_context)
+        unless flags_ready?
+          return error_result(default_value, ::OpenFeature::SDK::Provider::ErrorCode::PROVIDER_NOT_READY)
+        end
+
+        context = build_context(evaluation_context)
+        fallback = ::Mixpanel::Flags::SelectedVariant.new(variant_value: default_value)
+
+        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)
+        end
+
+        if result.equal?(fallback)
+          return ::OpenFeature::SDK::Provider::ResolutionDetails.new(
+            value: default_value,
+            error_code: ::OpenFeature::SDK::Provider::ErrorCode::FLAG_NOT_FOUND,
+            reason: ::OpenFeature::SDK::Provider::Reason::DEFAULT
+          )
+        end
+
+        value = result.variant_value
+
+        if value.nil? && expected_type != :object
+          return error_result(default_value, ::OpenFeature::SDK::Provider::ErrorCode::TYPE_MISMATCH)
+        end
+
+        coerced = coerce_value(value, expected_type)
+        if coerced.nil? && !value.nil?
+          return error_result(default_value, ::OpenFeature::SDK::Provider::ErrorCode::TYPE_MISMATCH)
+        end
+
+        ::OpenFeature::SDK::Provider::ResolutionDetails.new(
+          value: coerced.nil? ? value : coerced,
+          variant: result.variant_key,
+          reason: ::OpenFeature::SDK::Provider::Reason::TARGETING_MATCH
+        )
+      end
+
+      def coerce_value(value, expected_type)
+        case expected_type
+        when :boolean
+          value == true || value == false ? value : nil
+        when :string
+          value.is_a?(String) ? value : nil
+        when :integer
+          if value.is_a?(Integer)
+            value
+          elsif value.is_a?(Float) && value.finite? && value == value.floor
+            value.to_i
+          end
+        when :float
+          if value.is_a?(Float)
+            value
+          elsif value.is_a?(Integer)
+            value.to_f
+          end
+        when :number
+          value.is_a?(Numeric) ? value : nil
+        when :object
+          value
+        end
+      end
+
+      def build_context(evaluation_context)
+        return {} if evaluation_context.nil?
+
+        ctx = {}
+        if evaluation_context.respond_to?(:fields)
+          evaluation_context.fields.each { |k, v| ctx[k] = unwrap_value(v) }
+        end
+        if evaluation_context.respond_to?(:targeting_key) && evaluation_context.targeting_key
+          ctx['targetingKey'] = unwrap_value(evaluation_context.targeting_key)
+        end
+        ctx
+      end
+
+      def unwrap_value(value)
+        case value
+        when Float
+          value.finite? && value == value.floor ? value.to_i : value
+        when Array
+          value.map { |v| unwrap_value(v) }
+        when Hash
+          value.transform_values { |v| unwrap_value(v) }
+        else
+          value
+        end
+      end
+
+      def flags_ready?
+        if @flags_provider.respond_to?(:are_flags_ready)
+          @flags_provider.are_flags_ready
+        else
+          true
+        end
+      end
+
+      def error_result(default_value, error_code)
+        ::OpenFeature::SDK::Provider::ResolutionDetails.new(
+          value: default_value,
+          error_code: error_code,
+          reason: ::OpenFeature::SDK::Provider::Reason::ERROR
+        )
+      end
+    end
+  end
+end

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

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

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

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

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

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require File.join(File.dirname(__FILE__), 'lib/mixpanel/openfeature/version.rb')
+
+Gem::Specification.new do |spec|
+  spec.name = 'mixpanel-ruby-openfeature'
+  spec.version = Mixpanel::OpenFeature::VERSION
+  spec.authors = ['Mixpanel']
+  spec.email = 'support@mixpanel.com'
+  spec.summary = 'OpenFeature provider for Mixpanel feature flags'
+  spec.description = 'An OpenFeature provider that wraps the Mixpanel Ruby SDK feature flags'
+  spec.homepage = 'https://mixpanel.com'
+  spec.license = 'Apache-2.0'
+  spec.required_ruby_version = '>= 3.1.0'
+
+  spec.files = Dir['lib/**/*.rb']
+  spec.require_paths = ['lib']
+
+  spec.add_runtime_dependency 'openfeature-sdk', '~> 0.5'
+  spec.add_runtime_dependency 'mixpanel-ruby', '~> 3.1'
+
+  spec.add_development_dependency 'rspec', '~> 3.0'
+  spec.add_development_dependency 'simplecov'
+  spec.add_development_dependency 'simplecov-cobertura'
+end