abmeter 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2d4ea3bdc7addec399a8644a3d8d2ee8f0329b4d85b117a56f4df51c58e04816
-  data.tar.gz: b03e52a1fe306fe68b7dd63879ff067e59f358bdf885d4a8905e86d743ba282d
+  metadata.gz: f33d4944ddd5acac49f58a672004aa3460a7d8435a651ad6172d88960f02ebdb
+  data.tar.gz: b800e19818cc9d408380c14ae7e7fc2bad8d421839f970f14e259b327acb314c
 SHA512:
-  metadata.gz: 18f1020d7926f3e7026441877010f730ef7ffc06078ad738a7be0121c9399465d3b056e39b6d0133f97d32fced489bec9a6f26c9d99f4f817e223b8927260eaf
-  data.tar.gz: 9952d1a56ed63530d25200b21d88b0aaf3aec868752b72c46029e5905af5ff20af1eb45c472323afa20251694949ba9df0ff611d13a1633d0a110546d1aa41a5
+  metadata.gz: 83e08361797d68f6367b1651358557b25635e8a8554a9fb3e7dd79169f08b0c7443a52da385535cda59a25b4276cf9424c696dc4130c2a42f75e114412555f8b
+  data.tar.gz: e60a8479335b24cc3f57b24a5af553ad77b5a8451c3b8801650ca13721e3281cda29d9c54717f064393f1b6d816157bc6b84a83290e56bb4abcef4edb8c2bbf0

data/README.md

@@ -1,6 +1,6 @@
 # ABMeter Gem
 
-A simple A/B testing client library for Ruby applications.
+[ABMeter](https://abmeter.ai) is a feature-flag and A/B-testing platform. You define parameters, experiments, and feature flags in the ABMeter Lab; this gem reads the value assigned to each user in your Ruby app and reports events back.
 
 > **Breaking change in 0.3.0:** `ABMeter.reset!` now discards queued data without any network I/O; use `ABMeter.reset` for the previous drain-on-exit behavior.
 
@@ -22,24 +22,35 @@ And then execute:
 $ bundle install
 ```
 
+## Getting an API key
+
+Sign up at [abmeter.ai](https://abmeter.ai), then in the **Lab** open **API Keys** and create one. Expose it to your app (e.g. as `ABMETER_API_KEY`).
+
 ## Usage
 
+Configure the client once at startup:
+
 ```ruby
-# configure the client
 ABMeter.configure do |config|
   config.api_key = ENV['ABMETER_API_KEY']
 end
+```
 
-# Somewhere in the renedring code:
-user = ABMeter.user(id: current_user.id, email: current_user.email)
-text = ABMeter.param('welcome_text', user)
+The example below assumes a parameter `welcome_text` (in a space, with a variant, controlled by a running experiment or feature flag) and an event type `user_purchases_plan` already exist — create them through the ABMeter API or, more easily, your AI assistant over MCP. Until they do, `resolve_parameter` just returns the parameter's default and `track_event` rejects unknown event types.
 
-# Somewhere in the model code:
-current_user.plan = purchased_plan.name
-user = ABMeter.user(id: current_user.id, email: current_user.email)
-ABMeter.event(`user_purchases_plan`, user, {plan: purchased_plan.name, price: purchased_plan.price})
+```ruby
+# In request handling: read the value assigned to this user. `user_id` is the
+# only required field; an optional `email:` is available for predicate-based
+# (email-pattern) audience targeting.
+user = ABMeter::User.new(user_id: current_user.id)
+text = ABMeter.resolve_parameter(user: user, parameter_slug: 'welcome_text')
+
+# In business logic: record an action that feeds a metric.
+ABMeter.track_event('user_purchases_plan', current_user.id, { plan: purchased_plan.name, price: purchased_plan.price })
 ```
 
+The two calls are one loop: the experiment varies `welcome_text`, and the event feeds a metric whose effect the experiment measures across variants. Note that `resolve_parameter` is **not** a pure read — it resolves the value locally and records an exposure in the background; use `get_exposure` for the same resolution without submitting. Full guides live at [abmeter.ai](https://abmeter.ai).
+
 ## Shutdown
 
 ```ruby

data/bin/generate_num_utils_parity_fixture.rb

@@ -0,0 +1,32 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Regenerates the cross-language num-utils parity fixture consumed by the
+# Python SDK (sdk-python/tests/test_num_utils_parity.py).
+#
+# Emits 1000 [salt, user_id, expected] triples where `expected` is the integer
+# returned by ABMeter::Core::Utils::NumUtils.to_percentage. The Python
+# implementation must reproduce every row. Run from the abmeter-sdk directory:
+#
+#   bundle exec ruby bin/generate_num_utils_parity_fixture.rb
+#
+# Regenerate only when the assignment algorithm changes (it shouldn't).
+
+require 'json'
+require_relative '../lib/abmeter/core/utils/num_utils'
+
+FIXTURE_PATH = File.expand_path(
+  '../../sdk-python/tests/fixtures/num_utils_parity.json', __dir__
+)
+ROW_COUNT = 1000
+
+rows = Array.new(ROW_COUNT) do |i|
+  # Deterministic, varied inputs — mixed shapes exercise the hashing across
+  # salts and user-id formats without depending on RNG.
+  salt = "space-salt-#{i}-#{format('%04d', (i * 7) % 9973)}"
+  user_id = "user_#{((i * 31) + 5) % 100_003}"
+  [salt, user_id, ABMeter::Core::Utils::NumUtils.to_percentage(salt, user_id)]
+end
+
+File.write(FIXTURE_PATH, "#{JSON.pretty_generate(rows)}\n")
+puts "Wrote #{rows.size} rows to #{FIXTURE_PATH}"

data/lib/abmeter/async_submitter.rb

@@ -1,3 +1,5 @@
+require 'time' # Time#iso8601
+
 module ABMeter
   class AsyncSubmitter
     # Private internal constants for async submitter behavior

data/lib/abmeter/core/assignment_config/audience.rb

@@ -64,6 +64,8 @@ module ABMeter
         end
 
         def matches?(user)
+          return false if user.email.nil?
+
           user.email.match?(predicate)
         end
 

data/lib/abmeter/core/assignment_config/exposable.rb

@@ -7,7 +7,11 @@ module ABMeter
         protected
 
         def resolve_parameter_value(parameter, variant)
-          variant&.parameter_value(parameter.slug) || parameter.default_value
+          # Fall back to the default only when the variant does not set this
+          # parameter (nil). An explicitly-set falsy value (false, 0, "") is a
+          # real override and must win — `||` would wrongly drop a Boolean false.
+          value = variant&.parameter_value(parameter.slug)
+          value.nil? ? parameter.default_value : value
         end
 
         def validate_expose_parameter_args!(user_id, parameter, audience)

data/lib/abmeter/core/user.rb

@@ -5,7 +5,7 @@ module ABMeter
     class User
       attr_reader :user_id, :email
 
-      def initialize(user_id:, email:)
+      def initialize(user_id:, email: nil)
         @user_id = user_id
         @email = email
       end

data/lib/abmeter/core/user_parameter_resolver.rb

@@ -43,7 +43,6 @@ module ABMeter
 
       def validate_user!(user)
         raise ArgumentError, 'User must have user_id' unless user.respond_to?(:user_id)
-        raise ArgumentError, 'User must have email' unless user.respond_to?(:email)
       end
 
       def find_matching_feature_flag(user, parameter_slug)

data/lib/abmeter/version.rb

@@ -1,3 +1,3 @@
 module ABMeter
-  VERSION = '0.3.0'.freeze
+  VERSION = '0.4.0'.freeze
 end

data/lib/abmeter.rb

@@ -14,6 +14,12 @@ require_relative 'abmeter/async_submitter'
 require_relative 'abmeter/error_safety'
 
 module ABMeter
+  # Top-level alias for the canonical user value object. Lets callers write
+  # `ABMeter::User.new(user_id: ...)` instead of reaching into `Core::User`,
+  # mirroring `abmeter.User(...)` in the Python SDK. Same class object, so
+  # `is_a?`/`===`/`instance_of?` keep working; `Core::User` stays canonical.
+  User = Core::User
+
   class << self
     include ErrorSafety
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: abmeter
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - ABMeter
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-07-03 00:00:00.000000000 Z
+date: 2026-07-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -49,6 +49,7 @@ files:
 - LICENSE.txt
 - README.md
 - bin/console
+- bin/generate_num_utils_parity_fixture.rb
 - bin/rspec
 - lib/abmeter.rb
 - lib/abmeter/api_error.rb
@@ -71,11 +72,11 @@ files:
 - lib/abmeter/error_safety.rb
 - lib/abmeter/resolver_provider.rb
 - lib/abmeter/version.rb
-homepage: https://github.com/abmeter/abmeter-ruby
+homepage: https://abmeter.ai
 licenses:
 - MIT
 metadata:
-  homepage_uri: https://github.com/abmeter/abmeter-ruby
+  homepage_uri: https://abmeter.ai
   source_code_uri: https://github.com/abmeter/abmeter-ruby
   rubygems_mfa_required: 'true'
 post_install_message: