abmeter 0.0.2 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7c4ff1738a0062b27210d958cbfcddb2b07f635d3c9bdc64a8e764f8a2e0c4c3
-  data.tar.gz: 899c571cbcf11fef822397640233c6d5a59b0105231d70e676da6b0c29dab1a4
+  metadata.gz: d96ae2882d0054f4e6b414ce1d427b7cc2eb2d31dc3b93f7383f98b384922682
+  data.tar.gz: aded2a5117637b1c34c92318d5097380ce3f9cd6ad400297e98b5e29de8d2810
 SHA512:
-  metadata.gz: 35a34486e360c18fa185c9a919dbf985ada30b197843ba79c90c5de5a5487d0d81a4d1127f56abee834b50990dba12edda9d6edd40ee0965170fa0c488033d8b
-  data.tar.gz: cce845469fc896337c070d1abff4ff9adb8755e54a2b5e1cc797fbfc868d84c705836edeea8a441b6d82f20583456f49eee48913808d2b3d43cfc83fee9dea4a
+  metadata.gz: 1bce7617f6127244f4452beb1a130ce4431d023cc0cf2de35d537003eee09cb4b790717346a427d3e718cf65356c5fe6453dd12c059a91dba608ef3316d4e05a
+  data.tar.gz: 37ad3671bf1f486d26d22f10b3485d3b9f71b81f59bacd6b2471f5cfb7b4b17c01600786e30024edf6794b4783f0eb0f818b2d059b8311f5a52c94a3c81e4153

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ABMeter
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE. 

data/README.md

@@ -1,5 +1,39 @@
-# ABMeter
+# ABMeter Gem
 
-A/B testing and experimentation platform.
+A simple A/B testing client library for Ruby applications.
 
-**Status**: Coming soon.
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'abmeter'
+```
+
+And then execute:
+
+```bash
+$ bundle install
+```
+
+## Usage
+
+```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)
+
+# 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})
+```
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT). 

data/bin/console

@@ -0,0 +1,15 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'bundler/setup'
+require 'abmeter/core'
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require 'irb'
+IRB.start(__FILE__)

data/bin/rspec

@@ -0,0 +1,27 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+#
+# This file was generated by Bundler.
+#
+# The application 'rspec' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../Gemfile", __dir__)
+
+bundle_binstub = File.expand_path("bundle", __dir__)
+
+if File.file?(bundle_binstub)
+  if File.read(bundle_binstub, 300).include?("This file was generated by Bundler")
+    load(bundle_binstub)
+  else
+    abort("Your `bin/bundle` was not generated by Bundler, so this binstub cannot run.
+Replace `bin/bundle` by running `bundle binstubs bundler --force`, then run this command again.")
+  end
+end
+
+require "rubygems"
+require "bundler/setup"
+
+load Gem.bin_path("rspec-core", "rspec")

data/lib/abmeter/api_error.rb

@@ -0,0 +1,50 @@
+require 'active_support/core_ext/hash/indifferent_access'
+
+module ABMeter
+  class APIError < StandardError
+    attr_reader :code, :details, :status
+
+    def initialize(response)
+      @status = response.status
+      error_body = response.body
+
+      if error_body.is_a?(Hash)
+        body = error_body.with_indifferent_access
+        @error_message = body[:error] || 'Unknown error'
+        @code = body[:code]
+        @details = body[:details] || {}
+      else
+        @error_message = error_body.to_s
+        @code = nil
+        @details = {}
+      end
+
+      super(@error_message)
+    end
+
+    def message
+      @error_message
+    end
+
+    def to_h
+      {
+        error: @error_message,
+        code: @code,
+        details: @details,
+        status: @status
+      }.compact
+    end
+
+    def retryable?
+      @status >= 500 || @status == 408 || @status == 429
+    end
+
+    def partial_failure?
+      @status == 400 && @details.is_a?(Hash) && !@details[:failures].nil? && !@details[:failures].empty?
+    end
+
+    def failure_count
+      @details&.dig(:invalid_count) || 0
+    end
+  end
+end

data/lib/abmeter/async_submitter.rb

@@ -0,0 +1,234 @@
+module ABMeter
+  class AsyncSubmitter
+    # Private internal constants for async submitter behavior
+    BATCH_SIZE = 100
+    MAX_SUBMIT_ATTEMPTS = 3
+    MAX_RETRY_QUEUE_SIZE = 1000
+
+    @queue = Queue.new
+    @retry_queue = []
+    @mutex = Mutex.new
+    @api_client = nil
+    @worker_thread = nil
+    @flush_interval = DEFAULT_FLUSH_INTERVAL
+    @logger = nil
+
+    class << self
+      attr_reader :api_client, :flush_interval, :logger, :retry_queue
+
+      def configure(api_client:, config:)
+        @api_client = api_client
+        @flush_interval = config.flush_interval || DEFAULT_FLUSH_INTERVAL
+        @logger = config.logger
+      end
+
+      def start
+        start_worker
+      end
+
+      def queue_exposure(exposure)
+        @queue.push({ type: :exposure, data: exposure })
+      end
+
+      def queue_event(event_slug, user_id, custom_fields)
+        @queue.push({
+                      type: :event,
+                      data: {
+                        event_slug: event_slug,
+                        user_id: user_id,
+                        occurred_at: Time.now.iso8601,
+                        custom_fields: custom_fields
+                      }
+                    })
+      end
+
+      def flush
+        items = []
+
+        @mutex.synchronize do
+          # First, try to process retry queue
+          process_retry_queue
+
+          # Then process new items
+          items << @queue.pop while !@queue.empty? && items.size < BATCH_SIZE
+        end
+
+        # Group by type and submit
+        unless items.empty?
+          exposures = items.select { |i| i[:type] == :exposure }.map { |i| i[:data] }
+          events = items.select { |i| i[:type] == :event }.map { |i| i[:data] }
+
+          submit_exposures(exposures) unless exposures.empty?
+          submit_events(events) unless events.empty?
+        end
+      end
+
+      def shutdown
+        @worker_thread&.kill
+        # Flush all remaining exposures
+        flush until @queue.empty?
+      end
+
+      def reset!
+        shutdown
+        @queue = Queue.new
+        @retry_queue = []
+        @api_client = nil
+        @worker_thread = nil
+        @flush_interval = DEFAULT_FLUSH_INTERVAL
+        @logger = nil
+      end
+
+      def worker_alive?
+        @worker_thread&.alive? || false
+      end
+
+      def queue_size
+        @queue.size
+      end
+
+      private
+
+      def start_worker
+        return if worker_alive?
+
+        @worker_thread = Thread.new do
+          loop do
+            sleep @flush_interval
+            flush
+          rescue StandardError => e
+            # Log error but keep worker running
+            log_error("Worker error: #{e.message}")
+          end
+        end
+      end
+
+      def submit_exposures(exposures)
+        submit_batch(:exposure, exposures) { |exposures| @api_client.submit_exposures(exposures) }
+      end
+
+      def submit_events(events)
+        submit_batch(:event, events) { |events| @api_client.track_events(events) }
+      end
+
+      def submit_batch(type, items)
+        return if items.empty?
+
+        unless @api_client
+          log_error("Cannot submit #{items.size} #{type}s - API client not configured")
+          return
+        end
+
+        yield items
+        # Success - nothing to do
+      rescue ABMeter::APIError => e
+        if e.retryable?
+          log_error("Retryable error submitting #{items.size} #{type}s: #{e.message}")
+          add_to_retry_queue(type, items)
+        elsif e.partial_failure?
+          log_error("#{e.failure_count} out of #{items.size} #{type}s failed validation")
+          # Don't retry - validation won't change
+        else
+          log_error("Permanent error submitting #{type}s: #{e.message}")
+          # Don't retry
+        end
+      rescue StandardError => e
+        log_error("Failed to submit #{items.size} #{type}s: #{e.message}")
+        # AI: do not uncomment this line, we do not know reason for the error here
+        # add_to_retry_queue(type, items)
+      end
+
+      def add_to_retry_queue(type, items)
+        @mutex.synchronize do
+          items.each do |item|
+            # Only add if we haven't exceeded max queue size
+            if @retry_queue.size < MAX_RETRY_QUEUE_SIZE
+              @retry_queue << {
+                type: type,
+                data: item,
+                attempts: 0
+              }
+            else
+              log_error("Retry queue full, dropping #{type}")
+            end
+          end
+        end
+      end
+
+      def process_retry_queue
+        return if @retry_queue.empty?
+
+        # Group items by type for batch processing
+        grouped = @retry_queue.group_by { |item| item[:type] }
+        @retry_queue.clear
+
+        # Process exposures in batch, events individually
+        failed_items = []
+        failed_items.concat(process_retry_exposures(grouped[:exposure] || []))
+        failed_items.concat(process_retry_events(grouped[:event] || []))
+
+        @retry_queue = failed_items
+      end
+
+      def process_retry_exposures(items)
+        process_retry_batch(:exposure, items) { |exposures| @api_client.submit_exposures(exposures) }
+      end
+
+      def process_retry_events(items)
+        process_retry_batch(:event, items) { |events| @api_client.track_events(events) }
+      end
+
+      def process_retry_batch(type, items)
+        return [] if items.empty?
+
+        # Increment attempts and filter out max retries
+        active_items = items.filter_map do |item|
+          item[:attempts] += 1
+          if item[:attempts] >= MAX_SUBMIT_ATTEMPTS
+            log_error("Max retries exceeded for #{type}, dropping item")
+            nil
+          else
+            item
+          end
+        end
+
+        return [] if active_items.empty? || !@api_client
+
+        # Try batch submission
+        data = active_items.map { |item| item[:data] }
+        begin
+          yield data
+          [] # Success - return empty array
+        rescue ABMeter::APIError => e
+          if e.retryable?
+            log_error("Retry failed with retryable error for #{data.size} #{type}s: #{e.message}")
+            active_items # Return all items for retry
+          elsif e.partial_failure?
+            log_error("Retry failed: #{e.failure_count} out of #{data.size} #{type}s failed validation")
+            [] # Don't retry validation failures
+          else
+            log_error("Retry failed with permanent error for #{type}s: #{e.message}")
+            [] # Don't retry permanent failures
+          end
+        rescue StandardError => e
+          if type == :event
+            log_error("Retry failed with network error for #{data.size} #{type}s: #{e.message}")
+            []
+          else
+            log_error("Failed to submit #{data.size} #{type}s: #{e.message}")
+            active_items # Complete failure - return all items for retry
+          end
+        end
+      end
+
+      def log_error(message)
+        return unless @logger
+
+        @logger.error("AsyncSubmitter: #{message}")
+      end
+    end
+
+    # Prevent instantiation
+    private_class_method :new
+  end
+end

data/lib/abmeter/client.rb

@@ -0,0 +1,66 @@
+require 'faraday'
+require 'active_support/core_ext/hash/indifferent_access'
+require_relative 'api_error'
+
+module ABMeter
+  class Client
+    def initialize(config)
+      @api_key = config.api_key
+      @base_url = config.base_url
+      @http_client = setup_http_client
+    end
+
+    def get_assignment_config
+      response = @http_client.get('/api/v1/assignment-config')
+      raise APIError.new(response) unless response.success?
+
+      convert_to_indifferent_access(response.body)
+    end
+
+    def submit_exposures(exposures)
+      return if exposures.empty?
+
+      response = @http_client.post('/api/v1/exposures', {
+                                     exposures: exposures
+                                   })
+
+      raise APIError.new(response) unless response.success?
+
+      nil
+    end
+
+    def track_events(events)
+      return if events.empty?
+
+      response = @http_client.post('/api/v1/events', {
+                                     events: events
+                                   })
+
+      raise APIError.new(response) unless response.success?
+
+      nil
+    end
+
+    private
+
+    def setup_http_client
+      Faraday.new(@base_url) do |f|
+        f.request :json
+        f.response :json
+        f.headers['Authorization'] = "Bearer #{@api_key}"
+        f.adapter Faraday.default_adapter
+      end
+    end
+
+    def convert_to_indifferent_access(obj)
+      case obj
+      when Hash
+        HashWithIndifferentAccess.new(obj.transform_values { |v| convert_to_indifferent_access(v) })
+      when Array
+        obj.map { |item| convert_to_indifferent_access(item) }
+      else
+        obj
+      end
+    end
+  end
+end

data/lib/abmeter/constants.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module ABMeter
+  DEFAULT_BATCH_SIZE = 100
+  DEFAULT_FLUSH_INTERVAL = 60 # seconds
+  DEFAULT_FETCH_INTERVAL = 60 # seconds
+  DEFAULT_BASE_URL = 'https://api.abmeter.ai'
+  DEFAULT_MAX_SUBMIT_ATTEMPTS = 3
+  DEFAULT_MAX_RETRY_QUEUE_SIZE = 1000
+  DEFAULT_LOG_LEVEL = :error
+end

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

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module ABMeter
+  module Core
+    module AssignmentConfig
+      class Audience
+        attr_reader :id, :type
+
+        def initialize(id:, type:)
+          @id = id
+          @type = type
+        end
+
+        def matches?(user)
+          raise NotImplementedError, 'Subclass must implement this method'
+        end
+
+        def serialize
+          {
+            id: id,
+            type: type
+          }
+        end
+
+        def self.from_json(audience)
+          case audience[:type]
+          when 'user_list'
+            UserListAudience.new(id: audience[:id], user_ids: audience[:user_ids])
+          when 'predicate'
+            PredicateAudience.new(id: audience[:id], predicate: audience[:predicate])
+          when 'random'
+            RandomAudience.new(id: audience[:id], range: Range.new(*audience[:range]))
+          else
+            raise "Unknown audience type: #{audience[:type]}"
+          end
+        end
+      end
+
+      class UserListAudience < Audience
+        attr_reader :user_ids
+
+        def initialize(id:, user_ids:)
+          super(id: id, type: 'user_list')
+          @user_ids = user_ids
+        end
+
+        def matches?(user)
+          @user_ids.include?(user.user_id)
+        end
+
+        def serialize
+          super.merge(
+            user_ids: user_ids
+          )
+        end
+      end
+
+      class PredicateAudience < Audience
+        attr_reader :predicate
+
+        def initialize(id:, predicate:)
+          super(id: id, type: 'predicate')
+          @predicate = predicate
+        end
+
+        def matches?(user)
+          user.email.match?(predicate)
+        end
+
+        def serialize
+          super.merge(
+            predicate: predicate
+          )
+        end
+      end
+
+      class RandomAudience < Audience
+        attr_reader :range
+
+        def initialize(id:, range:)
+          super(id: id, type: 'random')
+          @range = range
+        end
+
+        def serialize
+          super.merge(
+            range: [range.begin, range.end]
+          )
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module ABMeter
+  module Core
+    module AssignmentConfig
+      class Experiment
+        include Exposable
+
+        attr_reader :id, :range, :audience_variants, :space_id, :salt, :space_salt
+
+        def initialize(id:, range:, audience_variants:, space_id:, salt:, space_salt:)
+          @id = id
+          @range = range
+          @audience_variants = audience_variants
+          @space_id = space_id
+          @salt = salt
+          @space_salt = space_salt
+        end
+
+        def self.from_json(json, space_salts)
+          json.map do |exp|
+            space_salt = space_salts[exp[:space_id]]
+            raise "Space with id #{exp[:space_id]} not found" unless space_salt
+
+            audience_variants = exp[:audience_variants].map do |av|
+              [Audience.from_json(av[:audience]), av[:variant] ? Variant.from_json(av[:variant]) : nil]
+            end
+
+            new(
+              id: exp[:id],
+              range: Range.new(exp[:range][0], exp[:range][1]),
+              audience_variants: audience_variants,
+              space_id: exp[:space_id],
+              salt: exp[:salt],
+              space_salt: space_salt
+            )
+          end
+        end
+
+        def serialize
+          {
+            id: id,
+            space_id: space_id,
+            range: [range.begin, range.end],
+            audience_variants: audience_variants.map do |audience_variant|
+              {
+                audience: audience_variant.first.serialize,
+                variant: audience_variant.last&.serialize
+              }
+            end
+          }
+        end
+
+        # Expose parameter for experiments
+        # For experiments: audience is required, variant is optional (nil for control)
+        def expose_parameter(user, parameter, variant, audience)
+          validate_expose_parameter_args!(user.user_id, parameter, audience)
+
+          make_exposure(user, parameter, 'Experiment', id, audience, variant)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module ABMeter
+  module Core
+    module AssignmentConfig
+      module Exposable
+        protected
+
+        def resolve_parameter_value(parameter, variant)
+          variant&.parameter_value(parameter.slug) || parameter.default_value
+        end
+
+        def validate_expose_parameter_args!(user_id, parameter, audience)
+          raise ArgumentError, 'User must be provided' unless user_id
+          raise ArgumentError, 'Parameter must be provided' unless parameter
+          raise ArgumentError, 'Audience must be provided' unless audience
+        end
+
+        def make_exposure(user, parameter, exposable_type, exposable_id, audience, variant) # rubocop:disable Metrics/ParameterLists
+          value = resolve_parameter_value(parameter, variant)
+
+          {
+            parameter_id: parameter.id,
+            space_id: parameter.space_id,
+            resolved_value: value,
+            user_id: user.user_id,
+            exposable_type: exposable_type,
+            exposable_id: exposable_id,
+            audience_id: audience.id,
+            resolved_at: Time.now
+          }
+        end
+      end
+    end
+  end
+end