setbit 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 9b8ccfb4587b58fc04c79c6557dafd02f05914742c58bd352e2e3786065b0446
+  data.tar.gz: cbee38616ee38877db945334e4ec36d2cd8a2c790880a52655600b37a8c523a9
+SHA512:
+  metadata.gz: aefc7d300599e61ac61e4591b6111eabc913fa9253d18f6d2f6d1681a99f6b638929d82ac166da9ef1749960c399accecd917ace25336895e72156374ebcd41b
+  data.tar.gz: 0bb36dac20e88bd51226a386755cffec66358b4a4f86deac5daa4275c1ab9fb750693263785cd8a75463f2f63742070eba4da7a7c7b70f9d0c48d9555d61b1c5

data/CHANGELOG.md

@@ -0,0 +1,34 @@
+# Changelog
+
+All notable changes to the SetBit Ruby SDK will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2025-11-23
+
+### Added
+- Initial release of SetBit Ruby SDK
+- Boolean flag checking with `enabled?` method
+- A/B test variant selection with `variant` method
+- Conversion tracking with `track` method
+- Tag-based targeting support
+- Manual flag refresh with `refresh` method
+- Comprehensive error handling with custom exceptions
+- Fail-open design - returns defaults on errors
+- Full test coverage with RSpec
+- Rails and Sinatra integration examples
+- Zero external runtime dependencies
+
+### Features
+- Boolean flag checking with consistent behavior
+- Rollout flags with percentage-based gradual rollout (requires user_id)
+- Weighted random distribution for A/B tests
+- In-memory flag caching
+- Silent failure for tracking (logs errors but doesn't crash)
+- Support for custom base URL (self-hosted instances)
+- Consistent user assignment using SHA-256 hashing
+- Idiomatic Ruby API with proper naming conventions
+- Thread-safe operations
+
+[0.1.0]: https://github.com/setbit/setbit-ruby/releases/tag/v0.1.0

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 SetBit
+
+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

@@ -0,0 +1,577 @@
+# SetBit Ruby SDK
+
+Official Ruby SDK for [SetBit](https://setbit.io) - Simple feature flags and A/B testing.
+
+## Features
+
+- ✅ **Boolean Flags** - Simple on/off feature toggles
+- 🧪 **A/B Testing** - Weighted variant distribution for experiments
+- 📊 **Conversion Tracking** - Track events and conversions
+- 🏷️ **Tag-Based Targeting** - Target by environment, app, team, region, etc.
+- 🚀 **Fail-Open Design** - Returns defaults if API is unreachable
+- 🪶 **Zero Dependencies** - Uses only Ruby standard library
+- 💎 **Idiomatic Ruby** - Follows Ruby conventions and best practices
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'setbit'
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+Or install it yourself as:
+
+```bash
+gem install setbit
+```
+
+## Quick Start
+
+```ruby
+require 'setbit'
+
+# Initialize the client
+client = SetBit::Client.new(
+  api_key: "pk_your_api_key_here",
+  tags: { env: "production", app: "web" }
+)
+
+# Check a boolean flag (user_id required for analytics)
+user_id = get_current_user_id
+if client.enabled?("new-checkout", user_id: user_id)
+  show_new_checkout
+else
+  show_old_checkout
+end
+
+# Rollout flag (gradual percentage-based rollout)
+variant = client.variant("new-api", user_id: current_user.id)
+if variant == "enabled"
+  use_new_api
+else
+  use_old_api
+end
+
+# Get A/B test variant
+variant = client.variant("pricing-experiment", user_id: current_user.id)
+case variant
+when "variant_a"
+  show_price_99
+when "variant_b"
+  show_price_149
+else # control
+  show_price_129
+end
+
+# Track conversions
+client.track("purchase", user_id: current_user.id, metadata: { amount: 99.99 })
+```
+
+## API Reference
+
+### Initialization
+
+```ruby
+SetBit::Client.new(api_key:, tags: {}, base_url: "https://flags.setbit.io", logger: nil)
+```
+
+**Parameters:**
+- `api_key` (String, required): Your SetBit API key
+- `tags` (Hash, optional): Tags for targeting flags (e.g., `{ env: "production", app: "web" }`)
+- `base_url` (String, optional): API endpoint URL (useful for self-hosted instances)
+- `logger` (Logger, optional): Custom logger instance
+
+**Raises:**
+- `SetBit::AuthError`: If API key is invalid
+- `SetBit::APIError`: If initial flag fetch fails
+
+**Example:**
+```ruby
+client = SetBit::Client.new(
+  api_key: "pk_abc123",
+  tags: { env: "production", app: "web", region: "us-east" }
+)
+```
+
+---
+
+### `enabled?(flag_name, user_id:, default: false)`
+
+Check if a flag is enabled. Returns `true` if the flag is globally enabled, `false` otherwise.
+
+**Parameters:**
+- `flag_name` (String): Name of the flag
+- `user_id` (String, **required**): User identifier (required for analytics and billing)
+- `default` (Boolean): Value to return if flag not found (default: `false`)
+
+**Returns:** `Boolean` - `true` if enabled, `false` otherwise
+
+**Note:** This method returns whether the flag is globally enabled. For rollout flags, use `variant()` to check which rollout group the user is in.
+
+**Example:**
+```ruby
+# Check if flag is enabled (user_id required)
+user_id = get_current_user_id
+if client.enabled?("new-dashboard", user_id: user_id)
+  render_new_dashboard
+else
+  render_old_dashboard
+end
+
+# With custom default
+if client.enabled?("beta-feature", user_id: user_id, default: true)
+  show_beta_feature
+end
+```
+
+---
+
+### `variant(flag_name, user_id:, default: "control")`
+
+Get the variant for an A/B test experiment or rollout flag.
+
+**Parameters:**
+- `flag_name` (String): Name of the experiment or rollout flag
+- `user_id` (String): User identifier (required)
+- `default` (String): Variant to return if flag not found (default: `"control"`)
+
+**Returns:** `String` - Variant name
+
+For experiments: `"control"`, `"variant_a"`, `"variant_b"`, etc.
+For rollout flags: `"enabled"` (user in rollout) or `"disabled"` (user not in rollout)
+
+**Example:**
+```ruby
+# A/B test experiment
+variant = client.variant("button-color-test", user_id: current_user.id)
+
+button_color = case variant
+when "variant_a" then "blue"
+when "variant_b" then "green"
+else "red" # control
+end
+
+# Rollout flag (gradual percentage-based rollout)
+variant = client.variant("new-api", user_id: current_user.id)
+
+if variant == "enabled"
+  use_new_api  # User is in the rollout group
+else
+  use_old_api  # User is not in the rollout group
+end
+```
+
+---
+
+### `track(event_name, user_id:, flag_name: nil, variant: nil, metadata: {})`
+
+Track a conversion event.
+
+**Parameters:**
+- `event_name` (String): Name of the event (e.g., `"purchase"`, `"signup"`)
+- `user_id` (String, **required**): User identifier (required for analytics and billing)
+- `flag_name` (String, optional): Flag to associate with this conversion
+- `variant` (String, optional): Variant the user was assigned to (for A/B test attribution)
+- `metadata` (Hash, optional): Additional event data
+
+**Returns:** `void`
+
+**Note:** This method fails silently - errors are logged but not raised.
+
+**Example:**
+```ruby
+user_id = current_user.id
+
+# Track conversion with variant attribution (recommended for A/B tests)
+variant = client.variant("pricing-test", user_id: user_id)
+# ... later when user converts ...
+client.track(
+  "purchase",
+  user_id: user_id,
+  flag_name: "pricing-test",
+  variant: variant,
+  metadata: { amount: 99.99, currency: "USD" }
+)
+
+# Track basic conversion
+client.track("signup", user_id: user_id)
+
+# Track with flag association only
+client.track("purchase", user_id: user_id, flag_name: "checkout-experiment")
+```
+
+---
+
+### `refresh`
+
+Manually refresh flags from the API.
+
+**Returns:** `void`
+
+**Raises:**
+- `SetBit::AuthError`: If API key is invalid
+- `SetBit::APIError`: If API request fails
+
+**Example:**
+```ruby
+# Refresh flags if you know they've changed
+client.refresh
+```
+
+---
+
+## Usage Examples
+
+### Boolean Flags
+
+```ruby
+require 'setbit'
+
+client = SetBit::Client.new(
+  api_key: "pk_abc123",
+  tags: { env: "production", app: "web" }
+)
+
+# Simple feature toggle (boolean flag)
+enable_dark_mode if client.enabled?("dark-mode")
+
+# With default value
+debug_mode = client.enabled?("debug-logging", default: false)
+```
+
+### Rollout Flags
+
+```ruby
+# Gradual percentage-based rollout
+# Use variant() to check which rollout group the user is in
+variant = client.variant("new-api-v2", user_id: current_user.id)
+
+if variant == "enabled"
+  use_api_v2  # User is in the rollout group
+else
+  use_api_v1  # User is not in the rollout group
+end
+
+# Example: Rollout new checkout flow
+checkout_variant = client.variant("new-checkout", user_id: current_user.id)
+
+if checkout_variant == "enabled"
+  render_new_checkout
+  client.track("checkout_started", user_id: current_user.id, flag_name: "new-checkout")
+else
+  render_old_checkout
+end
+```
+
+### A/B Testing
+
+```ruby
+# Get variant for experiment
+variant = client.variant("homepage-hero", user_id: current_user.id)
+
+case variant
+when "variant_a"
+  # Version A: Large hero image
+  render_hero(size: "large", style: "image")
+when "variant_b"
+  # Version B: Video hero
+  render_hero(size: "large", style: "video")
+when "variant_c"
+  # Version C: Minimal hero
+  render_hero(size: "small", style: "minimal")
+else
+  # Control: Original hero
+  render_hero(size: "medium", style: "image")
+end
+
+# Track conversion for this experiment (pass variant for proper attribution)
+client.track("signup", user_id: current_user.id, flag_name: "homepage-hero", variant: variant)
+```
+
+### Conversion Tracking
+
+```ruby
+# Track page view
+client.track("page_view", metadata: { page: "/pricing" })
+
+# Track user signup
+client.track("signup", metadata: {
+  plan: "pro",
+  source: "landing_page"
+})
+
+# Track purchase with detailed metadata
+client.track(
+  "purchase",
+  flag_name: "checkout-experiment",
+  metadata: {
+    amount: 149.99,
+    currency: "USD",
+    items: 3,
+    payment_method: "credit_card"
+  }
+)
+```
+
+### Error Handling
+
+```ruby
+require 'setbit'
+
+begin
+  client = SetBit::Client.new(api_key: "invalid_key")
+rescue SetBit::AuthError => e
+  puts "Invalid API key: #{e.message}"
+  # Fall back to default behavior
+  client = nil
+end
+
+# Client returns safe defaults if initialization failed
+if client&.enabled?("new-feature")
+  show_new_feature
+else
+  show_old_feature
+end
+```
+
+### Rails Integration
+
+```ruby
+# config/initializers/setbit.rb
+Rails.application.config.setbit = SetBit::Client.new(
+  api_key: ENV['SETBIT_API_KEY'],
+  tags: {
+    env: Rails.env,
+    app: "rails-app"
+  },
+  logger: Rails.logger
+)
+
+# app/controllers/application_controller.rb
+class ApplicationController < ActionController::Base
+  def setbit
+    Rails.application.config.setbit
+  end
+  helper_method :setbit
+end
+
+# app/controllers/checkout_controller.rb
+class CheckoutController < ApplicationController
+  def new
+    variant = setbit.variant("checkout-flow")
+
+    if variant == "one_page"
+      render :one_page_checkout
+    else
+      render :multi_step_checkout
+    end
+  end
+
+  def complete
+    setbit.track(
+      "purchase",
+      flag_name: "checkout-flow",
+      metadata: { amount: params[:amount] }
+    )
+    redirect_to thank_you_path
+  end
+end
+
+# app/views/layouts/application.html.erb
+<% if setbit.enabled?("new-header") %>
+  <%= render "shared/new_header" %>
+<% else %>
+  <%= render "shared/old_header" %>
+<% end %>
+```
+
+### Sinatra Integration
+
+```ruby
+require 'sinatra'
+require 'setbit'
+
+configure do
+  set :setbit, SetBit::Client.new(
+    api_key: ENV['SETBIT_API_KEY'],
+    tags: { env: ENV['RACK_ENV'], app: "sinatra-app" }
+  )
+end
+
+get '/' do
+  if settings.setbit.enabled?("new-homepage")
+    erb :homepage_v2
+  else
+    erb :homepage
+  end
+end
+
+post '/purchase' do
+  # Process purchase...
+
+  settings.setbit.track(
+    "purchase",
+    metadata: { amount: params[:amount] }
+  )
+
+  redirect '/thank-you'
+end
+```
+
+### Background Jobs (Sidekiq)
+
+```ruby
+class ProcessOrderJob
+  include Sidekiq::Worker
+
+  def perform(order_id)
+    order = Order.find(order_id)
+
+    # Use SetBit in background job
+    client = SetBit::Client.new(
+      api_key: ENV['SETBIT_API_KEY'],
+      tags: { env: Rails.env, app: "worker" }
+    )
+
+    if client.enabled?("advanced-fraud-detection")
+      run_advanced_fraud_check(order)
+    else
+      run_basic_fraud_check(order)
+    end
+
+    client.track("order_processed", metadata: { order_id: order_id })
+  end
+end
+```
+
+### Multi-Tenancy
+
+```ruby
+class ApplicationController < ActionController::Base
+  def setbit
+    @setbit ||= SetBit::Client.new(
+      api_key: ENV['SETBIT_API_KEY'],
+      tags: {
+        env: Rails.env,
+        app: "web",
+        tenant: current_tenant.slug
+      }
+    )
+  end
+  helper_method :setbit
+end
+
+# Now flags can be targeted per tenant
+# tags: { env: "production", tenant: "acme-corp" } → Show feature
+# tags: { env: "production", tenant: "other-corp" } → Hide feature
+```
+
+## Development
+
+### Setup
+
+```bash
+git clone https://github.com/setbit/setbit-ruby.git
+cd setbit-ruby
+bundle install
+```
+
+### Running Tests
+
+```bash
+# Run all tests
+bundle exec rspec
+
+# Run specific test file
+bundle exec rspec spec/client_spec.rb
+
+# Run with coverage
+bundle exec rake coverage
+```
+
+### Linting
+
+```bash
+# Run RuboCop
+bundle exec rubocop
+
+# Auto-fix issues
+bundle exec rubocop -a
+```
+
+### Generate Documentation
+
+```bash
+bundle exec yard doc
+```
+
+## Error Handling
+
+The SDK uses a **fail-open** philosophy - if something goes wrong, it returns safe default values rather than crashing your application.
+
+### Exception Types
+
+- `SetBit::Error`: Base exception for all SDK errors
+- `SetBit::AuthError`: Invalid API key (raised during initialization/refresh)
+- `SetBit::APIError`: API request failed (raised during initialization/refresh)
+
+### Behavior
+
+| Method | Error Behavior |
+|--------|----------------|
+| `new` | Raises exception if API key invalid or flags can't be fetched |
+| `enabled?` | Returns `default` value if flag not found |
+| `variant` | Returns `default` variant if flag not found |
+| `track` | Logs error but does not raise exception |
+| `refresh` | Raises exception if refresh fails |
+
+## API Endpoints
+
+The SDK communicates with these SetBit API endpoints:
+
+- **GET** `/api/sdk/flags` - Fetch flags for given tags
+- **POST** `/api/events` - Send conversion events
+
+## Requirements
+
+- Ruby >= 2.6.0
+- No external runtime dependencies (uses standard library only!)
+
+## Support
+
+- 📚 [Documentation](https://docs.setbit.io)
+- 💬 [Discord Community](https://discord.gg/setbit)
+- 📧 Email: support@setbit.io
+- 🐛 [Report Issues](https://github.com/setbit/setbit-ruby/issues)
+
+## License
+
+MIT License - see [LICENSE](LICENSE) file for details.
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add some amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+## Roadmap
+
+- [ ] Add memoization options for variant selection
+- [ ] Support for local flag evaluation
+- [ ] Streaming flag updates via WebSocket
+- [ ] Performance metrics and benchmarks
+
+---
+
+Made with ❤️ by the SetBit team

data/lib/setbit/client.rb

@@ -0,0 +1,190 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "json"
+require "uri"
+require "logger"
+
+module SetBit
+  # SetBit feature flag client
+  #
+  # @example
+  #   client = SetBit::Client.new(
+  #     api_key: "pk_abc123",
+  #     tags: { env: "production", app: "web" }
+  #   )
+  #
+  #   if client.enabled?("new-feature", user_id: "user_123")
+  #     show_new_feature
+  #   end
+  class Client
+    attr_reader :api_key, :tags, :base_url
+    attr_accessor :logger
+
+    # Initialize SetBit client
+    #
+    # @param api_key [String] SetBit API key (required)
+    # @param tags [Hash] Tags for targeting (env, app, team, region, etc.)
+    # @param base_url [String] API endpoint base URL
+    # @param logger [Logger] Optional logger instance
+    #
+    # @raise [SetBit::Error] if API key is missing
+    def initialize(api_key:, tags: {}, base_url: "https://flags.setbit.io", logger: nil)
+      raise SetBit::Error, "API key is required" if api_key.nil? || api_key.empty?
+
+      @api_key = api_key
+      @tags = tags || {}
+      @base_url = base_url.chomp("/")
+      @logger = logger || Logger.new(nil) # Silent logger by default
+    end
+
+    # Check if a flag is enabled
+    #
+    # @param flag_name [String] Name of the flag to check
+    # @param user_id [String] User identifier (required for analytics and billing)
+    # @param default [Boolean] Default value if flag not found or API fails
+    # @return [Boolean] true if flag is enabled, false otherwise
+    def enabled?(flag_name, user_id:, default: false)
+      url = URI("#{@base_url}/v1/evaluate")
+
+      payload = {
+        apiKey: @api_key,
+        userId: user_id,
+        tags: @tags,
+        flagName: flag_name
+      }
+
+      http = Net::HTTP.new(url.host, url.port)
+      http.use_ssl = url.scheme == "https"
+      http.open_timeout = 5
+      http.read_timeout = 5
+
+      request = Net::HTTP::Post.new(url, "Content-Type" => "application/json")
+      request.body = payload.to_json
+
+      response = http.request(request)
+
+      # Handle authentication errors
+      if response.code == "401"
+        @logger.error("Invalid API key")
+        return default
+      end
+
+      # Handle other errors - fail open
+      unless response.is_a?(Net::HTTPSuccess)
+        @logger.error("API error #{response.code}, returning default: #{default}")
+        return default
+      end
+
+      result = JSON.parse(response.body)
+      result["enabled"] || default
+
+    rescue JSON::ParserError => e
+      @logger.error("Failed to parse API response: #{e.message}, returning default: #{default}")
+      default
+    rescue StandardError => e
+      @logger.error("Failed to evaluate flag '#{flag_name}': #{e.message}, returning default: #{default}")
+      default
+    end
+
+    # Get the variant for an A/B test experiment
+    #
+    # @param flag_name [String] Name of the experiment flag
+    # @param user_id [String] User identifier (required)
+    # @param default [String] Default variant if flag not found or API fails
+    # @return [String] Variant name (e.g., "control", "variant_a", "variant_b")
+    def variant(flag_name, user_id:, default: "control")
+      url = URI("#{@base_url}/v1/evaluate")
+
+      payload = {
+        apiKey: @api_key,
+        userId: user_id,
+        tags: @tags,
+        flagName: flag_name
+      }
+
+      http = Net::HTTP.new(url.host, url.port)
+      http.use_ssl = url.scheme == "https"
+      http.open_timeout = 5
+      http.read_timeout = 5
+
+      request = Net::HTTP::Post.new(url, "Content-Type" => "application/json")
+      request.body = payload.to_json
+
+      response = http.request(request)
+
+      # Handle authentication errors
+      if response.code == "401"
+        @logger.error("Invalid API key")
+        return default
+      end
+
+      # Handle other errors - fail open
+      unless response.is_a?(Net::HTTPSuccess)
+        @logger.error("API error #{response.code}, returning default: #{default}")
+        return default
+      end
+
+      result = JSON.parse(response.body)
+
+      # If flag is disabled, return default
+      return default unless result["enabled"]
+
+      result["variant"] || default
+
+    rescue JSON::ParserError => e
+      @logger.error("Failed to parse API response: #{e.message}, returning default: #{default}")
+      default
+    rescue StandardError => e
+      @logger.error("Failed to get variant for '#{flag_name}': #{e.message}, returning default: #{default}")
+      default
+    end
+
+    # Track a conversion event
+    #
+    # @param event_name [String] Name of the event (e.g., "purchase", "signup")
+    # @param user_id [String] User identifier (required)
+    # @param flag_name [String, nil] Optional flag name to associate with event
+    # @param variant [String, nil] Optional variant the user was assigned to (for A/B test attribution)
+    # @param metadata [Hash] Optional metadata hash
+    # @return [void]
+    #
+    # @note Fails silently if tracking request fails (logs error but doesn't raise)
+    #
+    # @example Track conversion with variant attribution
+    #   variant = client.variant("pricing-test", user_id: user_id)
+    #   # ... later when user converts ...
+    #   client.track("purchase", user_id: user_id, flag_name: "pricing-test", variant: variant)
+    def track(event_name, user_id:, flag_name: nil, variant: nil, metadata: {})
+      url = URI("#{@base_url}/v1/track")
+
+      payload = {
+        apiKey: @api_key,
+        userId: user_id,
+        eventName: event_name
+      }
+
+      payload[:flagName] = flag_name if flag_name
+      payload[:variant] = variant if variant
+      payload[:metadata] = metadata if metadata && !metadata.empty?
+
+      http = Net::HTTP.new(url.host, url.port)
+      http.use_ssl = url.scheme == "https"
+      http.open_timeout = 5
+      http.read_timeout = 5
+
+      request = Net::HTTP::Post.new(url, "Content-Type" => "application/json")
+      request.body = payload.to_json
+
+      response = http.request(request)
+
+      if response.is_a?(Net::HTTPSuccess)
+        @logger.debug("Tracked event '#{event_name}' for user '#{user_id}'")
+      else
+        @logger.error("Failed to track event '#{event_name}': HTTP #{response.code}")
+      end
+    rescue StandardError => e
+      @logger.error("Failed to track event '#{event_name}': #{e.message}")
+    end
+  end
+end

data/lib/setbit/errors.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module SetBit
+  # Base error class for SetBit SDK
+  class Error < StandardError; end
+
+  # Raised when API key is invalid
+  class AuthError < Error; end
+
+  # Raised when API request fails
+  class APIError < Error; end
+end

data/lib/setbit/utils.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module SetBit
+  module Utils
+    # Compute a consistent percentage (0-99) for a given identifier
+    # Uses SHA-256 hash to ensure consistent assignment
+    #
+    # @param identifier [String] User ID or other unique identifier
+    # @return [Integer] Integer between 0 and 99 (inclusive)
+    def self.compute_rollout_percentage(identifier)
+      hash_bytes = Digest::SHA256.digest(identifier)
+      # Use first 4 bytes to get a number
+      hash_int = hash_bytes[0, 4].unpack1("N")
+      hash_int % 100
+    end
+
+    # Select a variant using weighted random distribution
+    #
+    # @param variants [Hash] Hash mapping variant names to config with 'weight' key
+    # @return [String] Selected variant name
+    def self.select_variant(variants)
+      return "control" if variants.nil? || variants.empty?
+
+      total_weight = variants.values.sum { |v| v["weight"] || 0 }
+
+      return variants.keys.first || "control" if total_weight.zero?
+
+      rand_value = rand(total_weight)
+
+      cumulative = 0
+      variants.each do |name, config|
+        cumulative += config["weight"] || 0
+        return name if rand_value < cumulative
+      end
+
+      "control" # fallback
+    end
+  end
+end

data/lib/setbit/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module SetBit
+  VERSION = "0.1.1"
+end

data/lib/setbit.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require_relative "setbit/version"
+require_relative "setbit/errors"
+require_relative "setbit/utils"
+require_relative "setbit/client"
+
+# SetBit Ruby SDK
+#
+# Simple feature flag and A/B testing client for SetBit.
+#
+# @example
+#   client = SetBit::Client.new(
+#     api_key: "pk_abc123",
+#     tags: { env: "production", app: "web" }
+#   )
+#
+#   if client.enabled?("new-feature")
+#     show_new_feature
+#   end
+module SetBit
+end

data/setbit.gemspec

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require_relative "lib/setbit/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "setbit"
+  spec.version = SetBit::VERSION
+  spec.authors = ["SetBit"]
+  spec.email = ["support@setbit.io"]
+
+  spec.summary = "Ruby SDK for SetBit feature flags and A/B testing"
+  spec.description = "Simple and powerful feature flag and A/B testing client for SetBit. " \
+                     "Provides boolean flags, weighted variant distribution, and conversion tracking."
+  spec.homepage = "https://setbit.io"
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 2.6.0"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = "https://github.com/setbit/setbit-ruby"
+  spec.metadata["changelog_uri"] = "https://github.com/setbit/setbit-ruby/blob/main/CHANGELOG.md"
+  spec.metadata["bug_tracker_uri"] = "https://github.com/setbit/setbit-ruby/issues"
+  spec.metadata["documentation_uri"] = "https://docs.setbit.io"
+
+  # Specify which files should be added to the gem when it is released.
+  spec.files = Dir[
+    "lib/**/*.rb",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE",
+    "setbit.gemspec"
+  ]
+
+  spec.require_paths = ["lib"]
+
+  # Runtime dependencies
+  # Using only standard library for HTTP - no external dependencies!
+
+  # Development dependencies
+  spec.add_development_dependency "rspec", "~> 3.12"
+  spec.add_development_dependency "webmock", "~> 3.18"
+  spec.add_development_dependency "rake", "~> 13.0"
+  spec.add_development_dependency "rubocop", "~> 1.50"
+  spec.add_development_dependency "yard", "~> 0.9"
+end

metadata

@@ -0,0 +1,128 @@
+--- !ruby/object:Gem::Specification
+name: setbit
+version: !ruby/object:Gem::Version
+  version: 0.1.1
+platform: ruby
+authors:
+- SetBit
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2025-11-26 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.18'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.18'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.50'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.50'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+description: Simple and powerful feature flag and A/B testing client for SetBit. Provides
+  boolean flags, weighted variant distribution, and conversion tracking.
+email:
+- support@setbit.io
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/setbit.rb
+- lib/setbit/client.rb
+- lib/setbit/errors.rb
+- lib/setbit/utils.rb
+- lib/setbit/version.rb
+- setbit.gemspec
+homepage: https://setbit.io
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://setbit.io
+  source_code_uri: https://github.com/setbit/setbit-ruby
+  changelog_uri: https://github.com/setbit/setbit-ruby/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/setbit/setbit-ruby/issues
+  documentation_uri: https://docs.setbit.io
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.6.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.10
+signing_key:
+specification_version: 4
+summary: Ruby SDK for SetBit feature flags and A/B testing
+test_files: []