subflag-openfeature-provider 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 40e8537098d52a561735926123fc60c1ad200f3762151588e101f815447cf822
+  data.tar.gz: 42821e1d8a10786803898a2d17d1c82002f24a314351cb3b61aa7b43c0cca2ba
+SHA512:
+  metadata.gz: 8ae9b2658c93632d4cbcbee3af96c27fccda6c099f8f144a225b79961298f5851f7757c7404583bc235fc643f510ce0175fb579def7ebf285f9d97bb3f14cf67
+  data.tar.gz: e59f3c5b24a9a3f18fad1ceb09fb1d0dda9084f355abfd8d2862f3da81fcf4dc564dbf7143cbfa4fc948482a0efe69c8a94444f1b47c19d076ba5c0605fd0cd4

data/.rspec

@@ -0,0 +1,3 @@
+--require spec_helper
+--format documentation
+--color

data/.rspec_status

@@ -0,0 +1,70 @@
+example_id                                       | status | run_time        |
+------------------------------------------------ | ------ | --------------- |
+./spec/subflag/client_spec.rb[1:1:1]             | passed | 0.00269 seconds |
+./spec/subflag/client_spec.rb[1:1:2]             | passed | 0.0005 seconds  |
+./spec/subflag/client_spec.rb[1:1:3]             | passed | 0.00036 seconds |
+./spec/subflag/client_spec.rb[1:1:4]             | passed | 0.00034 seconds |
+./spec/subflag/client_spec.rb[1:1:5]             | passed | 0.00028 seconds |
+./spec/subflag/client_spec.rb[1:2:1:1]           | passed | 0.03835 seconds |
+./spec/subflag/client_spec.rb[1:2:1:2]           | passed | 0.01594 seconds |
+./spec/subflag/client_spec.rb[1:2:1:3]           | passed | 0.01299 seconds |
+./spec/subflag/client_spec.rb[1:2:1:4]           | passed | 0.01766 seconds |
+./spec/subflag/client_spec.rb[1:2:1:5]           | passed | 0.03152 seconds |
+./spec/subflag/client_spec.rb[1:2:2:1]           | passed | 0.02146 seconds |
+./spec/subflag/client_spec.rb[1:2:3:1]           | passed | 0.01918 seconds |
+./spec/subflag/client_spec.rb[1:2:4:1]           | passed | 0.01256 seconds |
+./spec/subflag/client_spec.rb[1:2:4:2]           | passed | 0.02079 seconds |
+./spec/subflag/client_spec.rb[1:2:5:1]           | passed | 0.01744 seconds |
+./spec/subflag/client_spec.rb[1:2:6:1]           | passed | 0.01392 seconds |
+./spec/subflag/client_spec.rb[1:2:6:2]           | passed | 0.01303 seconds |
+./spec/subflag/client_spec.rb[1:2:7:1]           | passed | 0.01581 seconds |
+./spec/subflag/client_spec.rb[1:3:1:1]           | passed | 0.01796 seconds |
+./spec/subflag/client_spec.rb[1:3:1:2]           | passed | 0.01345 seconds |
+./spec/subflag/client_spec.rb[1:3:2:1]           | passed | 0.01236 seconds |
+./spec/subflag/errors_spec.rb[1:1]               | passed | 0.00544 seconds |
+./spec/subflag/errors_spec.rb[2:1]               | passed | 0.0002 seconds  |
+./spec/subflag/evaluation_context_spec.rb[1:1:1] | passed | 0.00274 seconds |
+./spec/subflag/evaluation_context_spec.rb[1:1:2] | passed | 0.00038 seconds |
+./spec/subflag/evaluation_context_spec.rb[1:1:3] | passed | 0.00025 seconds |
+./spec/subflag/evaluation_context_spec.rb[1:1:4] | passed | 0.00016 seconds |
+./spec/subflag/evaluation_context_spec.rb[1:1:5] | passed | 0.00014 seconds |
+./spec/subflag/evaluation_context_spec.rb[1:2:1] | passed | 0.00012 seconds |
+./spec/subflag/evaluation_context_spec.rb[1:2:2] | passed | 0.00277 seconds |
+./spec/subflag/evaluation_context_spec.rb[1:2:3] | passed | 0.00018 seconds |
+./spec/subflag/evaluation_context_spec.rb[1:3:1] | passed | 0.00013 seconds |
+./spec/subflag/evaluation_context_spec.rb[1:3:2] | passed | 0.00011 seconds |
+./spec/subflag/evaluation_context_spec.rb[1:3:3] | passed | 0.00011 seconds |
+./spec/subflag/evaluation_context_spec.rb[1:3:4] | passed | 0.00012 seconds |
+./spec/subflag/evaluation_context_spec.rb[1:3:5] | passed | 0.02665 seconds |
+./spec/subflag/evaluation_context_spec.rb[1:3:6] | passed | 0.00018 seconds |
+./spec/subflag/evaluation_context_spec.rb[1:3:7] | passed | 0.00014 seconds |
+./spec/subflag/evaluation_result_spec.rb[1:1:1]  | passed | 0.00012 seconds |
+./spec/subflag/evaluation_result_spec.rb[1:2:1]  | passed | 0.0001 seconds  |
+./spec/subflag/evaluation_result_spec.rb[1:2:2]  | passed | 0.0001 seconds  |
+./spec/subflag/provider_spec.rb[1:1:1]           | passed | 0.0005 seconds  |
+./spec/subflag/provider_spec.rb[1:2:1]           | passed | 0.00039 seconds |
+./spec/subflag/provider_spec.rb[1:3:1]           | passed | 0.00038 seconds |
+./spec/subflag/provider_spec.rb[1:4:1:1]         | passed | 0.0132 seconds  |
+./spec/subflag/provider_spec.rb[1:4:1:2]         | passed | 0.01269 seconds |
+./spec/subflag/provider_spec.rb[1:4:2:1]         | passed | 0.01343 seconds |
+./spec/subflag/provider_spec.rb[1:4:3:1]         | passed | 0.01265 seconds |
+./spec/subflag/provider_spec.rb[1:4:4:1]         | passed | 0.01326 seconds |
+./spec/subflag/provider_spec.rb[1:4:5:1]         | passed | 0.0197 seconds  |
+./spec/subflag/provider_spec.rb[1:5:1]           | passed | 0.01297 seconds |
+./spec/subflag/provider_spec.rb[1:5:2]           | passed | 0.01226 seconds |
+./spec/subflag/provider_spec.rb[1:6:1]           | passed | 0.01201 seconds |
+./spec/subflag/provider_spec.rb[1:6:2]           | passed | 0.01698 seconds |
+./spec/subflag/provider_spec.rb[1:7:1]           | passed | 0.01183 seconds |
+./spec/subflag/provider_spec.rb[1:7:2]           | passed | 0.01746 seconds |
+./spec/subflag/provider_spec.rb[1:8:1]           | passed | 0.01125 seconds |
+./spec/subflag/provider_spec.rb[1:8:2]           | passed | 0.0119 seconds  |
+./spec/subflag/provider_spec.rb[1:9:1]           | passed | 0.01764 seconds |
+./spec/subflag/provider_spec.rb[1:9:2]           | passed | 0.01244 seconds |
+./spec/subflag/provider_spec.rb[1:10:1]          | passed | 0.01167 seconds |
+./spec/subflag/provider_spec.rb[1:10:2]          | passed | 0.01133 seconds |
+./spec/subflag/provider_spec.rb[1:10:3]          | passed | 0.01184 seconds |
+./spec/subflag/provider_spec.rb[1:10:4]          | passed | 0.01362 seconds |
+./spec/subflag/provider_spec.rb[1:10:5]          | passed | 0.01628 seconds |
+./spec/subflag/provider_spec.rb[1:10:6]          | passed | 0.0151 seconds  |
+./spec/subflag/provider_spec.rb[1:11:1]          | passed | 0.01314 seconds |
+./spec/subflag/provider_spec.rb[1:11:2]          | passed | 0.01556 seconds |

data/.rubocop.yml

@@ -0,0 +1,21 @@
+AllCops:
+  TargetRubyVersion: 3.1
+  NewCops: enable
+  SuggestExtensions: false
+
+Style/Documentation:
+  Enabled: false
+
+Style/FrozenStringLiteralComment:
+  Enabled: true
+
+Metrics/BlockLength:
+  Exclude:
+    - 'spec/**/*'
+    - '*.gemspec'
+
+Metrics/MethodLength:
+  Max: 15
+
+Layout/LineLength:
+  Max: 120

data/README.md

@@ -0,0 +1,116 @@
+# Subflag OpenFeature Provider for Ruby
+
+Ruby provider for [OpenFeature](https://openfeature.dev) that integrates with [Subflag](https://subflag.com) feature flag management.
+
+## Installation
+
+```ruby
+gem 'subflag-openfeature-provider'
+```
+
+Or with Bundler:
+
+```bash
+bundle add subflag-openfeature-provider
+```
+
+## Usage
+
+### With OpenFeature SDK
+
+```ruby
+require "openfeature/sdk"
+require "subflag"
+
+# Configure the provider
+provider = Subflag::Provider.new(
+  api_url: ENV["SUBFLAG_API_URL"],
+  api_key: ENV["SUBFLAG_API_KEY"]
+)
+
+OpenFeature::SDK.configure do |config|
+  config.set_provider(provider)
+end
+
+# Get a client and evaluate flags
+client = OpenFeature::SDK.build_client
+
+# Boolean flag
+if client.fetch_boolean_value(flag_key: "dark-mode", default_value: false)
+  enable_dark_mode
+end
+
+# String flag
+theme = client.fetch_string_value(flag_key: "theme", default_value: "light")
+
+# Number flag
+limit = client.fetch_integer_value(flag_key: "rate-limit", default_value: 100)
+
+# Object flag
+config = client.fetch_object_value(flag_key: "feature-config", default_value: {})
+```
+
+### With Evaluation Context
+
+```ruby
+context = {
+  targeting_key: "user-123",
+  plan: "premium",
+  country: "US"
+}
+
+enabled = client.fetch_boolean_value(
+  flag_key: "premium-feature",
+  default_value: false,
+  evaluation_context: context
+)
+```
+
+### Direct Client Usage
+
+You can also use the Subflag client directly without OpenFeature:
+
+```ruby
+require "subflag"
+
+client = Subflag::Client.new(
+  api_url: "https://api.subflag.com",
+  api_key: "sdk-production-abc123"
+)
+
+result = client.evaluate("my-flag")
+puts result.value    # => true
+puts result.variant  # => "enabled"
+puts result.reason   # => "DEFAULT"
+
+# Bulk evaluation
+results = client.evaluate_all
+```
+
+## Configuration
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `api_url` | Subflag API base URL | Required |
+| `api_key` | SDK API key (`sdk-{env}-{random}`) | Required |
+| `timeout` | Request timeout in seconds | 5 |
+
+## Error Handling
+
+The provider returns default values on errors, following OpenFeature conventions:
+
+```ruby
+result = client.fetch_boolean_value(flag_key: "unknown", default_value: false)
+# result[:value] => false (default)
+# result[:reason] => :error
+# result[:error_code] => :flag_not_found
+```
+
+## Requirements
+
+- Ruby >= 3.1
+- openfeature-sdk >= 0.3
+
+## License
+
+MIT

data/Rakefile

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+require "rubocop/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/lib/subflag/client.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "json"
+
+module Subflag
+  # HTTP client for communicating with the Subflag API
+  #
+  # @example Basic usage
+  #   client = Client.new(api_url: "https://api.subflag.com", api_key: "sdk-dev-abc123")
+  #   result = client.evaluate("my-flag")
+  #
+  # @example With evaluation context
+  #   context = EvaluationContext.new(targeting_key: "user-123", attributes: { plan: "premium" })
+  #   result = client.evaluate("my-flag", context: context)
+  class Client
+    DEFAULT_TIMEOUT = 5 # seconds
+
+    attr_reader :api_url, :api_key, :timeout
+
+    # @param api_url [String] The base URL of the Subflag API
+    # @param api_key [String] The SDK API key (format: sdk-{env}-{random})
+    # @param timeout [Integer] Request timeout in seconds (default: 5)
+    def initialize(api_url:, api_key:, timeout: DEFAULT_TIMEOUT)
+      @api_url = api_url.chomp("/")
+      @api_key = api_key
+      @timeout = timeout
+      @connection = build_connection
+    end
+
+    # Evaluate a single flag
+    #
+    # @param flag_key [String] The key of the flag to evaluate
+    # @param context [EvaluationContext, nil] Optional evaluation context
+    # @return [EvaluationResult] The evaluation result
+    # @raise [FlagNotFoundError] If the flag doesn't exist
+    # @raise [AuthenticationError] If the API key is invalid
+    # @raise [ApiError] For other API errors
+    def evaluate(flag_key, context: nil)
+      response = post("/sdk/evaluate/#{encode_uri_component(flag_key)}", context&.to_h)
+      EvaluationResult.from_response(response)
+    end
+
+    # Evaluate all flags in the environment
+    #
+    # @param context [EvaluationContext, nil] Optional evaluation context
+    # @return [Array<EvaluationResult>] Array of evaluation results
+    # @raise [AuthenticationError] If the API key is invalid
+    # @raise [ApiError] For other API errors
+    def evaluate_all(context: nil)
+      response = post("/sdk/evaluate-all", context&.to_h)
+      response.map { |data| EvaluationResult.from_response(data) }
+    end
+
+    private
+
+    def build_connection
+      Faraday.new(url: @api_url) do |conn|
+        conn.request :json
+        conn.response :json
+        conn.options.timeout = @timeout
+        conn.options.open_timeout = @timeout
+        conn.headers["Content-Type"] = "application/json"
+        conn.headers["X-Subflag-API-Key"] = @api_key
+        conn.adapter Faraday.default_adapter
+      end
+    end
+
+    def post(path, body)
+      response = @connection.post(path) do |req|
+        req.body = body.to_json if body && !body.empty?
+      end
+
+      handle_response(response, path)
+    rescue Faraday::TimeoutError => e
+      raise TimeoutError, "Request timed out after #{@timeout}s: #{e.message}"
+    rescue Faraday::ConnectionFailed => e
+      raise ConnectionError, "Failed to connect to #{@api_url}: #{e.message}"
+    rescue Faraday::Error => e
+      raise ApiError.new("HTTP request failed: #{e.message}")
+    end
+
+    def handle_response(response, path)
+      body = parse_body(response.body)
+
+      case response.status
+      when 200, 201
+        body
+      when 401, 403
+        raise AuthenticationError.new(
+          extract_message(body) || "Authentication failed",
+          status: response.status,
+          details: body
+        )
+      when 404
+        flag_key = path.split("/").last
+        raise FlagNotFoundError.new(flag_key, status: 404, details: body)
+      else
+        raise ApiError.new(
+          extract_message(body) || "API request failed with status #{response.status}",
+          status: response.status,
+          details: body
+        )
+      end
+    end
+
+    def parse_body(body)
+      return body if body.is_a?(Hash) || body.is_a?(Array)
+      return {} if body.nil? || body.empty?
+
+      JSON.parse(body)
+    rescue JSON::ParserError
+      { "message" => body }
+    end
+
+    def extract_message(body)
+      body["message"] if body.is_a?(Hash)
+    end
+
+    def encode_uri_component(str)
+      URI.encode_www_form_component(str.to_s)
+    end
+  end
+end

data/lib/subflag/errors.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Subflag
+  # Base error class for all Subflag errors
+  class Error < StandardError; end
+
+  # Raised when API request fails
+  class ApiError < Error
+    attr_reader :status, :details
+
+    def initialize(message, status: nil, details: nil)
+      @status = status
+      @details = details
+      super(message)
+    end
+  end
+
+  # Raised when authentication fails (401/403)
+  class AuthenticationError < ApiError
+    def initialize(message = "Invalid or missing API key", **kwargs)
+      super(message, **kwargs)
+    end
+  end
+
+  # Raised when a flag is not found (404)
+  class FlagNotFoundError < ApiError
+    attr_reader :flag_key
+
+    def initialize(flag_key, **kwargs)
+      @flag_key = flag_key
+      super("Flag not found: #{flag_key}", **kwargs)
+    end
+  end
+
+  # Raised when flag value type doesn't match requested type
+  class TypeMismatchError < Error
+    attr_reader :flag_key, :expected_type, :actual_type
+
+    def initialize(flag_key, expected_type:, actual_type:)
+      @flag_key = flag_key
+      @expected_type = expected_type
+      @actual_type = actual_type
+      super("Type mismatch for flag '#{flag_key}': expected #{expected_type}, got #{actual_type}")
+    end
+  end
+
+  # Raised when network/connection fails
+  class ConnectionError < Error
+    def initialize(message = "Failed to connect to Subflag API")
+      super(message)
+    end
+  end
+
+  # Raised when request times out
+  class TimeoutError < Error
+    def initialize(message = "Request to Subflag API timed out")
+      super(message)
+    end
+  end
+end

data/lib/subflag/evaluation_context.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module Subflag
+  # Represents the context for flag evaluation, including targeting information
+  # and custom attributes for segment matching and percentage rollouts.
+  #
+  # @example Basic usage with targeting key
+  #   context = EvaluationContext.new(targeting_key: "user-123")
+  #
+  # @example With custom attributes
+  #   context = EvaluationContext.new(
+  #     targeting_key: "user-123",
+  #     kind: "user",
+  #     attributes: { plan: "premium", country: "US" }
+  #   )
+  class EvaluationContext
+    attr_reader :targeting_key, :kind, :attributes
+
+    # @param targeting_key [String, nil] Unique identifier for targeting (user ID, session ID, etc.)
+    # @param kind [String, nil] The kind of context ("user", "organization", "device", etc.)
+    # @param attributes [Hash, nil] Custom attributes for targeting rules
+    def initialize(targeting_key: nil, kind: nil, attributes: nil)
+      @targeting_key = targeting_key
+      @kind = kind
+      @attributes = attributes || {}
+    end
+
+    # Convert to hash for API request
+    # @return [Hash] The context as a hash
+    def to_h
+      {
+        targetingKey: @targeting_key,
+        kind: @kind,
+        attributes: @attributes.empty? ? nil : @attributes
+      }.compact
+    end
+
+    # Create from OpenFeature evaluation context
+    # @param openfeature_context [OpenFeature::SDK::EvaluationContext, Hash, nil]
+    # @return [EvaluationContext]
+    def self.from_openfeature(openfeature_context)
+      return new if openfeature_context.nil?
+
+      # Handle Hash-like context (OpenFeature context is typically a hash-like object)
+      if openfeature_context.respond_to?(:to_h)
+        ctx = openfeature_context.to_h
+      elsif openfeature_context.is_a?(Hash)
+        ctx = openfeature_context
+      else
+        return new
+      end
+
+      # Extract targeting_key (OpenFeature standard)
+      targeting_key = ctx[:targeting_key] || ctx["targeting_key"]
+
+      # Extract other attributes (excluding targeting_key)
+      attributes = ctx.reject { |k, _| [:targeting_key, "targeting_key"].include?(k) }
+
+      new(
+        targeting_key: targeting_key,
+        kind: "user", # Default to "user" kind for OpenFeature contexts
+        attributes: attributes.empty? ? nil : symbolize_keys(attributes)
+      )
+    end
+
+    private
+
+    def self.symbolize_keys(hash)
+      hash.transform_keys(&:to_sym)
+    end
+  end
+end

data/lib/subflag/evaluation_result.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Subflag
+  # Represents the result of a flag evaluation from the Subflag API
+  class EvaluationResult
+    # Valid evaluation reasons
+    REASONS = %w[
+      DEFAULT
+      OVERRIDE
+      SEGMENT_MATCH
+      PERCENTAGE_ROLLOUT
+      TARGETING_MATCH
+      ERROR
+    ].freeze
+
+    attr_reader :flag_key, :value, :variant, :reason
+
+    # @param flag_key [String] The key of the evaluated flag
+    # @param value [Object] The evaluated value (type depends on flag configuration)
+    # @param variant [String] The name of the selected variant
+    # @param reason [String] Why this value was selected (one of REASONS)
+    def initialize(flag_key:, value:, variant:, reason:)
+      @flag_key = flag_key
+      @value = value
+      @variant = variant
+      @reason = reason
+    end
+
+    # Create from API response hash
+    # @param data [Hash] The API response data
+    # @return [EvaluationResult]
+    def self.from_response(data)
+      new(
+        flag_key: fetch_key(data, "flagKey"),
+        value: fetch_key(data, "value"),
+        variant: fetch_key(data, "variant"),
+        reason: fetch_key(data, "reason")
+      )
+    end
+
+    # Fetch a key from hash, checking both string and symbol keys
+    # Can't use || because false values would be skipped
+    def self.fetch_key(data, key)
+      data.key?(key) ? data[key] : data[key.to_sym]
+    end
+
+    # Check if evaluation was successful (not an error)
+    # @return [Boolean]
+    def success?
+      reason != "ERROR"
+    end
+
+    # Convert to hash
+    # @return [Hash]
+    def to_h
+      {
+        flag_key: @flag_key,
+        value: @value,
+        variant: @variant,
+        reason: @reason
+      }
+    end
+  end
+end

data/lib/subflag/provider.rb

@@ -0,0 +1,213 @@
+# frozen_string_literal: true
+
+module Subflag
+  # OpenFeature provider for Subflag feature flag management.
+  #
+  # This provider implements the OpenFeature provider interface using duck-typing,
+  # following the on-demand evaluation pattern (like the Node.js provider).
+  # Each flag evaluation makes an HTTP request to the Subflag API.
+  #
+  # @example Basic usage with OpenFeature
+  #   require "openfeature/sdk"
+  #   require "subflag"
+  #
+  #   provider = Subflag::Provider.new(
+  #     api_url: "https://api.subflag.com",
+  #     api_key: "sdk-production-abc123"
+  #   )
+  #
+  #   OpenFeature::SDK.configure do |config|
+  #     config.set_provider(provider)
+  #   end
+  #
+  #   client = OpenFeature::SDK.build_client
+  #   enabled = client.fetch_boolean_value(flag_key: "dark-mode", default_value: false)
+  #
+  # @example With evaluation context
+  #   context = { targeting_key: "user-123", plan: "premium" }
+  #   enabled = client.fetch_boolean_value(
+  #     flag_key: "premium-feature",
+  #     default_value: false,
+  #     evaluation_context: context
+  #   )
+  class Provider
+    # Provider metadata for OpenFeature SDK
+    # @return [Hash] Provider metadata
+    def metadata
+      { name: "Subflag Ruby Provider" }
+    end
+
+    # @param api_url [String] The base URL of the Subflag API
+    # @param api_key [String] The SDK API key (format: sdk-{env}-{random})
+    # @param timeout [Integer] Request timeout in seconds (default: 5)
+    def initialize(api_url:, api_key:, timeout: Client::DEFAULT_TIMEOUT)
+      @client = Client.new(api_url: api_url, api_key: api_key, timeout: timeout)
+    end
+
+    # Called when provider is registered with OpenFeature
+    # Named `init` instead of `initialize` to avoid Ruby constructor conflict
+    def init
+      # No-op for on-demand evaluation pattern
+      # Could be used for connection validation or pre-warming in the future
+    end
+
+    # Called when provider is unregistered or SDK is shutdown
+    def shutdown
+      # No-op for stateless HTTP client
+      # Could be used for connection pool cleanup in the future
+    end
+
+    # Evaluate a boolean flag
+    #
+    # @param flag_key [String] The flag key to evaluate
+    # @param default_value [Boolean] Value to return if evaluation fails
+    # @param evaluation_context [Hash, nil] Optional targeting context
+    # @return [Hash] Resolution details with :value, :reason, :variant, :error_code, :error_message
+    def fetch_boolean_value(flag_key:, default_value:, evaluation_context: nil)
+      evaluate_flag(flag_key, default_value, evaluation_context, :boolean)
+    end
+
+    # Evaluate a string flag
+    #
+    # @param flag_key [String] The flag key to evaluate
+    # @param default_value [String] Value to return if evaluation fails
+    # @param evaluation_context [Hash, nil] Optional targeting context
+    # @return [Hash] Resolution details
+    def fetch_string_value(flag_key:, default_value:, evaluation_context: nil)
+      evaluate_flag(flag_key, default_value, evaluation_context, :string)
+    end
+
+    # Evaluate a number flag (returns Float)
+    #
+    # @param flag_key [String] The flag key to evaluate
+    # @param default_value [Numeric] Value to return if evaluation fails
+    # @param evaluation_context [Hash, nil] Optional targeting context
+    # @return [Hash] Resolution details
+    def fetch_number_value(flag_key:, default_value:, evaluation_context: nil)
+      evaluate_flag(flag_key, default_value, evaluation_context, :number)
+    end
+
+    # Evaluate an integer flag
+    #
+    # @param flag_key [String] The flag key to evaluate
+    # @param default_value [Integer] Value to return if evaluation fails
+    # @param evaluation_context [Hash, nil] Optional targeting context
+    # @return [Hash] Resolution details
+    def fetch_integer_value(flag_key:, default_value:, evaluation_context: nil)
+      evaluate_flag(flag_key, default_value, evaluation_context, :integer)
+    end
+
+    # Evaluate a float flag
+    #
+    # @param flag_key [String] The flag key to evaluate
+    # @param default_value [Float] Value to return if evaluation fails
+    # @param evaluation_context [Hash, nil] Optional targeting context
+    # @return [Hash] Resolution details
+    def fetch_float_value(flag_key:, default_value:, evaluation_context: nil)
+      evaluate_flag(flag_key, default_value, evaluation_context, :float)
+    end
+
+    # Evaluate an object/hash flag
+    #
+    # @param flag_key [String] The flag key to evaluate
+    # @param default_value [Hash] Value to return if evaluation fails
+    # @param evaluation_context [Hash, nil] Optional targeting context
+    # @return [Hash] Resolution details
+    def fetch_object_value(flag_key:, default_value:, evaluation_context: nil)
+      evaluate_flag(flag_key, default_value, evaluation_context, :object)
+    end
+
+    private
+
+    # Core evaluation logic shared by all type-specific methods
+    def evaluate_flag(flag_key, default_value, evaluation_context, expected_type)
+      context = EvaluationContext.from_openfeature(evaluation_context)
+      result = @client.evaluate(flag_key, context: context)
+
+      # Validate type matches
+      unless type_matches?(result.value, expected_type)
+        return error_result(
+          default_value,
+          error_code: :type_mismatch,
+          error_message: "Flag '#{flag_key}' value type doesn't match requested type #{expected_type}"
+        )
+      end
+
+      # Convert value if needed (e.g., number -> integer)
+      converted_value = convert_value(result.value, expected_type)
+
+      {
+        value: converted_value,
+        reason: map_reason(result.reason),
+        variant: result.variant,
+        flag_metadata: { flag_key: result.flag_key }
+      }
+    rescue FlagNotFoundError => e
+      error_result(default_value, error_code: :flag_not_found, error_message: e.message)
+    rescue AuthenticationError => e
+      error_result(default_value, error_code: :invalid_context, error_message: e.message)
+    rescue TypeMismatchError => e
+      error_result(default_value, error_code: :type_mismatch, error_message: e.message)
+    rescue TimeoutError, ConnectionError => e
+      error_result(default_value, error_code: :general, error_message: e.message)
+    rescue StandardError => e
+      error_result(default_value, error_code: :general, error_message: "Unexpected error: #{e.message}")
+    end
+
+    # Check if value matches expected type
+    def type_matches?(value, expected_type)
+      case expected_type
+      when :boolean
+        value == true || value == false
+      when :string
+        value.is_a?(String)
+      when :number, :integer, :float
+        value.is_a?(Numeric)
+      when :object
+        value.is_a?(Hash)
+      else
+        true
+      end
+    end
+
+    # Convert value to specific type if needed
+    def convert_value(value, expected_type)
+      case expected_type
+      when :integer
+        value.to_i
+      when :float
+        value.to_f
+      else
+        value
+      end
+    end
+
+    # Map Subflag reason to OpenFeature reason
+    def map_reason(subflag_reason)
+      case subflag_reason
+      when "DEFAULT"
+        :default
+      when "TARGETING_MATCH", "SEGMENT_MATCH"
+        :targeting_match
+      when "OVERRIDE"
+        :static
+      when "PERCENTAGE_ROLLOUT"
+        :split
+      when "ERROR"
+        :error
+      else
+        :unknown
+      end
+    end
+
+    # Build error result hash
+    def error_result(default_value, error_code:, error_message:)
+      {
+        value: default_value,
+        reason: :error,
+        error_code: error_code,
+        error_message: error_message
+      }
+    end
+  end
+end

data/lib/subflag/version.rb

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

data/lib/subflag.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require_relative "subflag/version"
+require_relative "subflag/errors"
+require_relative "subflag/evaluation_context"
+require_relative "subflag/evaluation_result"
+require_relative "subflag/client"
+require_relative "subflag/provider"
+
+# Subflag Ruby SDK for OpenFeature
+#
+# This module provides integration with Subflag feature flag management
+# through the OpenFeature standard.
+#
+# @example Quick start with OpenFeature
+#   require "openfeature/sdk"
+#   require "subflag"
+#
+#   # Configure the provider
+#   provider = Subflag::Provider.new(
+#     api_url: ENV["SUBFLAG_API_URL"],
+#     api_key: ENV["SUBFLAG_API_KEY"]
+#   )
+#
+#   OpenFeature::SDK.configure do |config|
+#     config.set_provider(provider)
+#   end
+#
+#   # Use the client
+#   client = OpenFeature::SDK.build_client
+#
+#   if client.fetch_boolean_value(flag_key: "new-checkout", default_value: false)
+#     # New checkout flow
+#   else
+#     # Legacy checkout flow
+#   end
+#
+# @example Direct client usage (without OpenFeature)
+#   client = Subflag::Client.new(
+#     api_url: "https://api.subflag.com",
+#     api_key: "sdk-production-abc123"
+#   )
+#
+#   result = client.evaluate("my-flag")
+#   puts result.value    # => true
+#   puts result.variant  # => "enabled"
+#   puts result.reason   # => "DEFAULT"
+#
+module Subflag
+end

data/subflag-openfeature-provider.gemspec

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require_relative "lib/subflag/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "subflag-openfeature-provider"
+  spec.version = Subflag::VERSION
+  spec.authors = ["Subflag"]
+  spec.email = ["support@subflag.com"]
+
+  spec.summary = "OpenFeature provider for Subflag feature flag management"
+  spec.description = "A Ruby provider for OpenFeature that integrates with Subflag's feature flag management system. Supports boolean, string, number, and object flag types with evaluation context."
+  spec.homepage = "https://github.com/subflag/subflag"
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 3.1.0"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = "https://github.com/subflag/subflag/tree/main/sdk/packages/openfeature-ruby-provider"
+  spec.metadata["changelog_uri"] = "https://github.com/subflag/subflag/blob/main/sdk/packages/openfeature-ruby-provider/CHANGELOG.md"
+  spec.metadata["rubygems_mfa_required"] = "true"
+
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      (File.expand_path(f) == __FILE__) ||
+        f.start_with?(*%w[bin/ test/ spec/ features/ .git .github appveyor Gemfile])
+    end
+  end
+  spec.require_paths = ["lib"]
+
+  # Runtime dependencies
+  spec.add_dependency "faraday", ">= 2.0", "< 3.0"
+  spec.add_dependency "openfeature-sdk", ">= 0.3", "< 1.0"
+
+  # Development dependencies
+  spec.add_development_dependency "bundler", "~> 2.0"
+  spec.add_development_dependency "rake", "~> 13.0"
+  spec.add_development_dependency "rspec", "~> 3.12"
+  spec.add_development_dependency "rubocop", "~> 1.50"
+  spec.add_development_dependency "webmock", "~> 3.18"
+end

metadata

@@ -0,0 +1,172 @@
+--- !ruby/object:Gem::Specification
+name: subflag-openfeature-provider
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Subflag
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2025-11-30 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: openfeature-sdk
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.3'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.3'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !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: 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: 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: 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'
+description: A Ruby provider for OpenFeature that integrates with Subflag's feature
+  flag management system. Supports boolean, string, number, and object flag types
+  with evaluation context.
+email:
+- support@subflag.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rspec"
+- ".rspec_status"
+- ".rubocop.yml"
+- README.md
+- Rakefile
+- lib/subflag.rb
+- lib/subflag/client.rb
+- lib/subflag/errors.rb
+- lib/subflag/evaluation_context.rb
+- lib/subflag/evaluation_result.rb
+- lib/subflag/provider.rb
+- lib/subflag/version.rb
+- subflag-openfeature-provider.gemspec
+homepage: https://github.com/subflag/subflag
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/subflag/subflag
+  source_code_uri: https://github.com/subflag/subflag/tree/main/sdk/packages/openfeature-ruby-provider
+  changelog_uri: https://github.com/subflag/subflag/blob/main/sdk/packages/openfeature-ruby-provider/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: OpenFeature provider for Subflag feature flag management
+test_files: []