mixpanel-ruby 3.0.0 → 3.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 99f6ea359c1b7a0f4248035f2ebe9a13380ee647b20722f73f49f45b3bb62ea3
-  data.tar.gz: c1dc8bf0e37d90a397654b263059458291eff144987b87bc3a9dcc153649c42e
+  metadata.gz: 6d3a5c579488b2cbe1c3b2c6e489070a0f438dca91b8e5f91d863709c517c978
+  data.tar.gz: '089600f43e3c29ef4f83d129dd1f8f58682ae041b1ffe776fad3ff3036140a5e'
 SHA512:
-  metadata.gz: cee44f99c3d4000ee9eb64a0353abcee02bec2a422d0a27c9cda160c8bb50db3f6abe72c550730633c719a51eb06f92dbba5e38cc17f7266a82bf8561488005e
-  data.tar.gz: db60ba774c9e32e2bb4199d46a3c192a40d35d3aaef84fdb87c0e29a7a66f76b4f4dbd0c6e2f28d5d7145844fadb91b9ccefb4bd82d2d9e2f287153182fcf176
+  metadata.gz: 81511ab17dfe9e72ffeb81a97752d82a581297dc002aa722ee50e2d12a5faa835f7dc198ea1be5b2b62cec7cb117fd8906177b427d8e8e9eddfab21f24c5d930
+  data.tar.gz: 97bac85d2cb9edd8dc4655f3657a42ff4a1c56fcb0f6fd983da8bb5b44baec1c684a63afd16f5612a02c545e53dd84d07853416f8aab79a0ddd00ac88dfbe2dd

data/.github/workflows/ruby.yml

@@ -22,7 +22,7 @@ jobs:
           - '3.4'
 
     steps:
-    - uses: actions/checkout@v6
+    - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
     - name: Set up Ruby
       uses: ruby/setup-ruby@d697be2f83c6234b20877c3b5eac7a7f342f0d0c # v1.269.0
       with:
@@ -31,7 +31,36 @@ jobs:
     - name: Run tests
       run: bundle exec rake
     - name: Upload coverage reports to Codecov
-      uses: codecov/codecov-action@v5
+      uses: codecov/codecov-action@75cd11691c0faa626561e295848008c8a7dddffe # v5
       with:
         token: ${{ secrets.CODECOV_TOKEN }}
         slug: mixpanel/mixpanel-ruby
+
+  test-openfeature:
+
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        ruby-version:
+          - '3.1'
+          - '3.2'
+          - '3.3'
+          - '3.4'
+
+    steps:
+    - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+    - name: Set up Ruby
+      uses: ruby/setup-ruby@d697be2f83c6234b20877c3b5eac7a7f342f0d0c # v1.269.0
+      with:
+        ruby-version: ${{ matrix.ruby-version }}
+    - name: Install dependencies
+      run: cd openfeature-provider && bundle install
+    - name: Run OpenFeature provider tests
+      run: cd openfeature-provider && bundle exec rspec
+    - name: Upload coverage reports to Codecov
+      uses: codecov/codecov-action@75cd11691c0faa626561e295848008c8a7dddffe # v5
+      with:
+        token: ${{ secrets.CODECOV_TOKEN }}
+        slug: mixpanel/mixpanel-ruby
+        flags: openfeature
+        directory: openfeature-provider

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

@@ -56,25 +56,29 @@ module Mixpanel
         request.basic_auth(@provider_config[:token], '')
 
         request['Content-Type'] = 'application/json'
-        request['traceparent'] = Utils.generate_traceparent()
+        request['traceparent'] = Utils.generate_traceparent
 
         begin
           response = http.request(request)
+        rescue Net::OpenTimeout, Net::ReadTimeout => e
+          raise ConnectionError.new("Request timeout: #{e.message}")
+        rescue StandardError => e
+          raise ConnectionError.new("Network error: #{e.message}")
+        end
 
-          unless response.code.to_i == 200
-            raise ServerError.new("HTTP #{response.code}: #{response.body}")
-          end
+        unless response.code == '200'
+          raise ServerError.new("HTTP #{response.code}: #{response.body}")
+        end
 
+        begin
           JSON.parse(response.body)
-        rescue Net::OpenTimeout, Net::ReadTimeout => e
-          raise ConnectionError.new("Request timeout: #{e.message}")
         rescue JSON::ParserError => e
           raise ServerError.new("Invalid JSON response: #{e.message}")
-        rescue StandardError => e
-          raise ConnectionError.new("Network error: #{e.message}")
         end
       end
 
+      def shutdown; end
+
       # Track exposure event to Mixpanel
       # @param flag_key [String] Feature flag key
       # @param selected_variant [SelectedVariant] The selected variant

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

@@ -64,6 +64,10 @@ module Mixpanel
         @polling_thread = nil
       end
 
+      def shutdown
+        stop_polling_for_definitions!
+      end
+
       # Check if flag is enabled (for boolean flags)
       # @param flag_key [String] Feature flag key
       # @param context [Hash] Evaluation context (must include 'distinct_id')
@@ -107,24 +111,17 @@ module Mixpanel
 
         context_value = context[context_key] || context[context_key.to_sym]
 
-        selected_variant = nil
+        selected_variant = get_variant_override_for_test_user(flag, context)
 
-        test_variant = get_variant_override_for_test_user(flag, context)
-        if test_variant
-          selected_variant = test_variant
-        else
+        unless selected_variant
           rollout = get_assigned_rollout(flag, context_value, context)
-          if rollout
-            selected_variant = get_assigned_variant(flag, context_value, flag_key, rollout)
-          end
+          selected_variant = get_assigned_variant(flag, context_value, flag_key, rollout) if rollout
         end
 
-        if selected_variant
-          track_exposure_event(flag_key, selected_variant, context) if report_exposure
-          return selected_variant
-        end
+        return fallback_variant unless selected_variant
 
-        fallback_variant
+        track_exposure_event(flag_key, selected_variant, context) if report_exposure
+        selected_variant
       end
 
       # Get all variants for user context
@@ -147,11 +144,9 @@ module Mixpanel
       def fetch_flag_definitions
         response = call_flags_endpoint
 
-        new_definitions = {}
-        (response['flags'] || []).each do |flag_data|
-          new_definitions[flag_data['key']] = flag_data
+        new_definitions = (response['flags'] || []).each_with_object({}) do |flag_data, definitions|
+          definitions[flag_data['key']] = flag_data
         end
-
         @flag_definitions = new_definitions
 
         response
@@ -175,9 +170,10 @@ module Mixpanel
       end
 
       def get_matching_variant(variant_key, flag)
-        return nil unless flag['ruleset'] && flag['ruleset']['variants']
+        variants = flag.dig('ruleset', 'variants')
+        return nil unless variants
 
-        flag['ruleset']['variants'].each do |v|
+        variants.each do |v|
           if variant_key.downcase == v['key'].downcase
             return SelectedVariant.new(
               variant_key: v['key'],
@@ -191,9 +187,10 @@ module Mixpanel
       end
 
       def get_assigned_rollout(flag, context_value, context)
-        return nil unless flag['ruleset'] && flag['ruleset']['rollout']
+        rollouts = flag.dig('ruleset', 'rollout')
+        return nil unless rollouts
 
-        flag['ruleset']['rollout'].each_with_index do |rollout, index|
+        rollouts.each_with_index do |rollout, index|
           salt = if flag['hash_salt']
                    "#{flag['key']}#{flag['hash_salt']}#{index}"
                  else
@@ -224,7 +221,7 @@ module Mixpanel
         salt = "#{flag_key}#{stored_salt}variant"
         variant_hash = Utils.normalized_hash(context_value.to_s, salt)
 
-        variants = flag['ruleset']['variants'].map { |v| v.dup }
+        variants = flag['ruleset']['variants'].map(&:dup)
         if rollout['variant_splits']
           variants.each do |v|
             v['split'] = rollout['variant_splits'][v['key']] if rollout['variant_splits'].key?(v['key'])

data/lib/mixpanel-ruby/version.rb

@@ -1,3 +1,3 @@
 module Mixpanel
-  VERSION = '3.0.0'
+  VERSION = '3.1.0'
 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

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.