kameleoon-openfeature-ruby 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: aeeddfee1813205e7afa99fe74684a056233268d96383fcb5c98a9e2d555b183
+  data.tar.gz: e1b9e9e7353c54e9b0c54d4481b13b9eccf19ccded1171bd51b4ac840cb3940e
+SHA512:
+  metadata.gz: 796225f66e0bc342064a7bd647fbb4788e4208c583aa40dd7445a0e706438d7f722858acc6f2ab81df55197af811f9936d3dc84c57c83c0e2621df32d6944753
+  data.tar.gz: b947424769ab79c1a3fd45fffec0aa6da3e999d14baf6123a2abfdee861653d7f5db0ec65ba3ab6a458e4ce8b0465628686b81f28db954be16e386097ac6d564

data/README.md

@@ -0,0 +1,171 @@
+# Kameleoon OpenFeature provider for Ruby
+
+The Kameleoon OpenFeature provider for Ruby allows you to connect your OpenFeature Ruby implementation to Kameleoon without installing the Ruby Kameleoon SDK.
+
+> [!WARNING]
+> This is a beta version. Breaking changes may be introduced before general release.
+
+## Supported Ruby versions
+
+This version of the SDK is built for the following targets:
+
+* Ruby 3.1.4 and above.
+
+## Get started
+
+This section explains how to install, configure, and customize the Kameleoon OpenFeature provider.
+
+### Install dependencies
+
+First, install the required dependencies in your application.
+
+```sh
+gem install bundler
+bundle install
+```
+
+### Usage
+
+The following example shows how to use the Kameleoon provider with the OpenFeature SDK.
+
+```ruby
+require 'kameleoon-client'
+require 'open_feature/sdk'
+
+client_config = Kameleoon::KameleoonClientConfig.new(
+  'clientId',
+  'clientSecret',
+  top_level_domain: 'topLevelDomain',
+)
+
+provider = Kameleoon::KameleoonProvider.new('siteCode', config: client_config)
+OpenFeature::SDK.configure do |config|
+  config.set_provider(provider)
+end
+
+client = OpenFeature::SDK.build_client
+
+data_dictionary = {
+  'targeting_key' => 'visitorCode',
+  'variableKey' => 'variableKey' 
+}
+eval_context = OpenFeature::SDK::EvaluationContext.new(**data_dictionary)
+
+resolution_details = client.fetch_integer_value(flag_key: 'featureKey', default_value: 5,
+                                                           evaluation_context: eval_context)
+number_of_recommended_products = resolution_details.value
+
+puts "Number of recommended products: #{number_of_recommended_products}"
+```
+
+#### Customize the Kameleoon provider
+
+You can customize the Kameleoon provider by changing the `KameleoonClientConfig` object that you passed to the constructor above. For example:
+
+```ruby
+client_config = Kameleoon::KameleoonClientConfig.new(
+  'clientId',
+  'clientSecret',
+  top_level_domain: 'topLevelDomain',
+  refresh_interval_minute: 1,    # Optional field
+  session_duration_minute: 5,    # Optional field
+)
+
+provider = Kameleoon::KameleoonProvider.new('siteCode', config: client_config)
+```
+> [!NOTE]
+> For additional configuration options, see the [Kameleoon documentation](https://developers.kameleoon.com/feature-management-and-experimentation/web-sdks/ruby-sdk/#example-code).
+
+## EvaluationContext and Kameleoon Data
+
+Kameleoon uses the concept of associating `Data` to users, while the OpenFeature SDK uses the concept of an `EvaluationContext`, which is a dictionary of string keys and values. The Kameleoon provider maps the `EvaluationContext` to the Kameleoon `Data`.
+
+> [!NOTE]
+> To get the evaluation for a specific visitor, set the `targeting_key` value for the `EvaluationContext` to the visitor code (user ID). If the value is not provided, then the `defaultValue` parameter will be returned.
+
+```ruby
+values = { 'targeting_key' => 'userId' }
+
+eval_context = OpenFeature::SDK::EvaluationContext.new(**values)
+```
+
+The Kameleoon provider provides a few predefined parameters that you can use to target a visitor from a specific audience and track each conversion. These are:
+
+| Parameter                 | Description                                                                                                                                                           |
+|---------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `Data::Type::CUSTOM_DATA` | The parameter is used to set [`CustomData`](https://developers.kameleoon.com/feature-management-and-experimentation/web-sdks/ruby-sdk/#customdata) for a visitor.     |
+| `Data::Type::CONVERSION`  | The parameter is used to track a [`Conversion`](https://developers.kameleoon.com/feature-management-and-experimentation/web-sdks/ruby-sdk/#conversion) for a visitor. |
+
+### Data::Type::CUSTOM_DATA
+
+Use `Data::Type::CUSTOM_DATA` to set [`CustomData`](https://developers.kameleoon.com/feature-management-and-experimentation/web-sdks/ruby-sdk/#customdata) for a visitor. The `Data::Type::CUSTOM_DATA` field has the following parameters:
+
+| Parameter                      | Type    | Description                                                       |
+|--------------------------------|---------|-------------------------------------------------------------------|
+| `Data::CustomDataType::INDEX`  | Integer | Index or ID of the custom data to store. This field is mandatory. |
+| `Data::CustomDataType::VALUES` | String  | Value of the custom data to store. This field is mandatory.       |
+
+#### Example
+
+```ruby
+custom_data_dictionary = {
+  'targeting_key' => 'userId',
+  Kameleoon::Types::Data::Type::CUSTOM_DATA => {
+      Kameleoon::Types::Data::CustomDataType::INDEX => 1,
+      Kameleoon::Types::Data::CustomDataType::VALUES => '10'
+    }
+}
+
+eval_context = OpenFeature::SDK::EvaluationContext.new(**custom_data_dictionary)
+```
+
+### Data::Type::CONVERSION
+
+Use `Data::Type::CONVERSION` to track a [`Conversion`](https://developers.kameleoon.com/feature-management-and-experimentation/web-sdks/ruby-sdk/#conversion) for a visitor. The `Data::Type::CONVERSION` field has the following parameters:
+
+| Parameter                       | Type    | Description                                                     |
+|---------------------------------|---------|-----------------------------------------------------------------|
+| `Data::ConversionType::GOAL_ID` | Integer | Identifier of the goal. This field is mandatory.                |
+| `Data::ConversionType::REVENUE` | Float   | Revenue associated with the conversion. This field is optional. |
+
+#### Example
+
+```ruby
+conversion_dictionary = {
+  Kameleoon::Types::Data::ConversionType::GOAL_ID => 1,
+  Kameleoon::Types::Data::ConversionType::REVENUE => 200
+}
+
+eval_context = OpenFeature::SDK::EvaluationContext.new(**{
+    'targeting_key' => 'userId',
+    Kameleoon::Types::Data::Type::CONVERSION => conversion_dictionary
+})
+```
+
+### Use multiple Kameleoon Data types
+
+You can provide many different kinds of Kameleoon data within a single `EvaluationContext` instance.
+
+For example, the following code provides one `Data::Type::CONVERSION` instance and two `Data::Type::CUSTOM_DATA` instances.
+
+```ruby
+data_dictionary = {
+  'targeting_key' => 'userId',
+  Kameleoon::Types::Data::Type::CONVERSION => {
+    Kameleoon::Types::Data::ConversionType::GOAL_ID => 1,
+    Kameleoon::Types::Data::ConversionType::REVENUE => 200
+  },
+  Kameleoon::Types::Data::Type::CUSTOM_DATA => [
+    {
+      Kameleoon::Types::Data::CustomDataType::INDEX => 1,
+      Kameleoon::Types::Data::CustomDataType::VALUES => ['10', '30']
+    },
+    {
+      Kameleoon::Types::Data::CustomDataType::INDEX => 2,
+      Kameleoon::Types::Data::CustomDataType::VALUES => '20'
+    }
+  ]
+}
+
+eval_context = OpenFeature::SDK::EvaluationContext.new(**data_dictionary)
+```

data/lib/kameleoon/data_converter.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require 'kameleoon/types'
+require 'kameleoon/data/conversion'
+require 'kameleoon/data/custom_data'
+
+module Kameleoon
+  # DataConverter is used to convert data from OpenFeature to Kameleoon.
+  class DataConverter
+    class << self
+      def conversion_methods
+        # Dictionary which contains conversion methods by keys
+        @conversion_methods ||= {
+          Kameleoon::Types::Data::Type::CONVERSION => method(:make_conversion),
+          Kameleoon::Types::Data::Type::CUSTOM_DATA => method(:make_custom_data)
+        }
+      end
+
+      # ToKameleoon converts EvaluationContext to Kameleoon SDK data types.
+      def to_kameleoon(context)
+        return [] if context.nil?
+
+        data = []
+        context.fields.each do |key, value|
+          method = conversion_methods[key]
+          next if method.nil? || value.nil?
+          values = value.is_a?(Array) ? value : [value]
+          values.each do |val|
+            data << method.call(val)
+          end
+        end
+        data
+      end
+
+      private
+
+      # make_conversion creates a Conversion object from the value.
+      def make_conversion(value)
+        return nil unless value.is_a?(Hash)
+
+        goal_id = value[Kameleoon::Types::Data::ConversionType::GOAL_ID]
+        revenue = value[Kameleoon::Types::Data::ConversionType::REVENUE]
+        revenue = revenue.to_f if revenue.is_a?(Integer)
+        revenue ||= 0.0
+
+        Kameleoon::Conversion.new(goal_id, revenue, false)
+      end
+
+      # make_custom_data creates a CustomData object from the value.
+      def make_custom_data(value)
+        return nil unless value.is_a?(Hash)
+
+        index = value[Kameleoon::Types::Data::CustomDataType::INDEX]
+        values = value[Kameleoon::Types::Data::CustomDataType::VALUES]
+        values = [values] if values.is_a?(String)
+
+        Kameleoon::CustomData.new(index, *values)
+      end
+    end
+  end
+end

data/lib/kameleoon/kameleoon_provider.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+require 'kameleoon/kameleoon_client_factory'
+require 'kameleoon/resolver'
+require 'open_feature/sdk/provider/provider_metadata'
+require 'open_feature/sdk/provider/resolution_details'
+
+module Kameleoon
+  # The KameleoonProvider class integrates with the OpenFeature SDK to provide feature flag resolution.
+  class KameleoonProvider
+    Provider = OpenFeature::SDK::Provider
+    NAME = 'Kameleoon Provider'
+
+    attr_reader :client, :metadata, :ready_state
+
+    # Initializes a new instance of the KameleoonProvider.
+    #
+    # @param site_code [String] The site code for the Kameleoon client.
+    # @param config [KameleoonClientConfig, nil] Optional configuration for the Kameleoon client.
+    # @param config_path [String, nil] Optional path to the configuration file.
+    def initialize(site_code, config: nil, config_path: nil)
+      @ready_state = false
+      @site_code = site_code
+      make_kameleoon_client(site_code, config, config_path)
+      @resolver = KameleoonResolver.new(@client)
+      @metadata = OpenFeature::SDK::Provider::ProviderMetadata.new(name: NAME).freeze
+    end
+
+    # Creates a Kameleoon client with the given site code and configuration.
+    #
+    # @param site_code [String] The site code for the Kameleoon client.
+    # @param config [KameleoonClientConfig, nil] Optional configuration for the Kameleoon client.
+    # @param config_path [String, nil] Optional path to the configuration file.
+    # @return [void]
+    private def make_kameleoon_client(site_code, config, config_path)
+      begin
+        @client = KameleoonClientFactory.create(site_code, config: config, config_path: config_path)
+      rescue Kameleoon::Exception::KameleoonError => exception
+
+      end
+    end
+
+    # Fetches a boolean value for the given feature flag.
+    #
+    # @param flag_key [String] The key of the feature flag.
+    # @param default_value [Boolean] The default value to return if the flag is not found.
+    # @param evaluation_context [EvaluationContext, nil] The evaluation context.
+    # @return [ResolutionDetails] The resolution details.
+    def fetch_boolean_value(flag_key: String, default_value:, evaluation_context: nil)
+      fetch_value(allowed_classes: [TrueClass, FalseClass], flag_key: flag_key, default_value: default_value, evaluation_context: evaluation_context)
+    end
+
+    # Fetches a string value for the given feature flag.
+    #
+    # @param flag_key [String] The key of the feature flag.
+    # @param default_value [String] The default value to return if the flag is not found.
+    # @param evaluation_context [EvaluationContext, nil] The evaluation context.
+    # @return [ResolutionDetails] The resolution details.
+    def fetch_string_value(flag_key: String, default_value: String, evaluation_context: nil)
+      fetch_value(allowed_classes: [String], flag_key: flag_key, default_value: default_value, evaluation_context: evaluation_context)
+    end
+
+    # Fetches a numeric value for the given feature flag.
+    #
+    # @param flag_key [String] The key of the feature flag.
+    # @param default_value [Numeric] The default value to return if the flag is not found.
+    # @param evaluation_context [EvaluationContext, nil] The evaluation context.
+    # @return [ResolutionDetails] The resolution details.
+    def fetch_number_value(flag_key: String, default_value: Numeric, evaluation_context: nil)
+      fetch_value(allowed_classes: [Numeric], flag_key: flag_key, default_value: default_value, evaluation_context: evaluation_context)
+    end
+
+    # Fetches an integer value for the given feature flag.
+    #
+    # @param flag_key [String] The key of the feature flag.
+    # @param default_value [Integer] The default value to return if the flag is not found.
+    # @param evaluation_context [EvaluationContext, nil] The evaluation context.
+    # @return [ResolutionDetails] The resolution details.
+    def fetch_integer_value(flag_key: String, default_value: Integer, evaluation_context: nil)
+      fetch_value(allowed_classes: [Integer], flag_key: flag_key, default_value: default_value, evaluation_context: evaluation_context)
+    end
+
+    # Fetches a float value for the given feature flag.
+    #
+    # @param flag_key [String] The key of the feature flag.
+    # @param default_value [Float] The default value to return if the flag is not found.
+    # @param evaluation_context [EvaluationContext, nil] The evaluation context.
+    # @return [ResolutionDetails] The resolution details.
+    def fetch_float_value(flag_key: String, default_value: Float, evaluation_context: nil)
+      fetch_value(allowed_classes: [Float], flag_key: flag_key, default_value: default_value, evaluation_context: evaluation_context)
+    end
+
+    # Fetches an object value for the given feature flag.
+    #
+    # @param flag_key [String] The key of the feature flag.
+    # @param default_value [Array, Hash] The default value to return if the flag is not found.
+    # @param evaluation_context [EvaluationContext, nil] The evaluation context.
+    # @return [ResolutionDetails] The resolution details.
+    def fetch_object_value(flag_key: String, default_value:, evaluation_context: nil)
+      fetch_value(allowed_classes: [Array, Hash], flag_key: flag_key, default_value: default_value, evaluation_context: evaluation_context)
+    end
+
+    # Initializes the Kameleoon client and sets the ready state.
+    #
+    # @return [Boolean]
+    def init
+      begin
+        success = @client.nil? ? false : @client.wait_init
+      rescue StandardError => e
+        success = false
+      end
+      @ready_state = success
+    end
+
+    # Shuts down the Kameleoon client and resets the ready state.
+    #
+    # @return [void]
+    def shutdown
+      KameleoonClientFactory.forget(@site_code)
+      @ready_state = false
+      @client = nil
+    end
+
+    private
+
+    # Fetches a value for the given feature flag based on the allowed classes.
+    #
+    # @param allowed_classes [Array<Class>] The allowed classes for the value.
+    # @param flag_key [String] The key of the feature flag.
+    # @param default_value [Any] The default value to return if the flag is not found.
+    # @param evaluation_context [EvaluationContext, nil] The evaluation context.
+    # @return [ResolutionDetails] The resolution details.
+    def fetch_value(allowed_classes:, flag_key:, default_value:, evaluation_context:)
+      if @ready_state
+        @resolver.resolve(allowed_classes: allowed_classes, flag_key: flag_key, default_value: default_value,
+                          evaluation_context: evaluation_context)
+      else
+        Provider::ResolutionDetails.new(
+          value: default_value,
+          error_code: @client.nil? ? Provider::ErrorCode::PROVIDER_FATAL : Provider::ErrorCode::PROVIDER_NOT_READY,
+          error_message: 'The provider is not ready to resolve flags.',
+          reason: Provider::Reason::ERROR)
+      end
+    end
+  end
+end

data/lib/kameleoon/resolver.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+require 'open_feature/sdk/provider/error_code'
+require 'open_feature/sdk/provider/resolution_details'
+require 'open_feature/sdk/provider/reason'
+require 'open_feature/sdk/provider'
+require 'kameleoon/data_converter'
+
+module Kameleoon
+  VARIABLE_KEY = 'variableKey'
+
+  # Resolver interface which contains method for evaluations based on provided data
+  class Resolver
+    def resolve(flag: String, default_value:, evaluation_context: OpenFeature::SDK::EvaluationContext)
+      raise NotImplementedError, 'Subclasses must implement the resolve method'
+    end
+  end
+
+  # KameleoonResolver makes evaluations based on provided data, conforms to Resolver interface
+  class KameleoonResolver < Resolver
+    Provider = OpenFeature::SDK::Provider
+
+    def initialize(client)
+      @client = client
+    end
+
+    # Main method for getting resolution details based on provided data.
+    def resolve(allowed_classes: Array, flag_key: String, default_value:, evaluation_context: nil)
+      if !evaluation_context.is_a?(OpenFeature::SDK::EvaluationContext) ||
+        (visitor_code = get_targeting_key(evaluation_context)).nil? || visitor_code.empty?
+        return make_resolution_error(
+          default_value,
+          Provider::ErrorCode::TARGETING_KEY_MISSING,
+          'The TargetingKey is required in context and cannot be omitted.')
+      end
+
+      # Add targeting data from context to KameleoonClient by visitor code
+      @client.add_data(visitor_code, *DataConverter.to_kameleoon(evaluation_context))
+
+      # Get a variation (main SDK method)
+      variation = @client.get_variation(visitor_code, flag_key)
+
+      # Get a variant (variation key)
+      variant = variation.key
+
+      # Get variableKey if it's provided in context or any first in variation.
+      # It's the responsibility of the client to have only one variable per variation if
+      # variableKey is not provided.
+      variable_key = get_variable_key(evaluation_context, variation.variables)
+
+      # Get value by variable key
+      value = variation.variables[variable_key]&.value
+
+      if value.nil? || variable_key.empty?
+        return make_resolution_error(
+          default_value,
+          Provider::ErrorCode::FLAG_NOT_FOUND,
+          make_error_description(variant, variable_key),
+          variant: variant)
+      end
+
+      # Check if the variable value has a required type
+      if allowed_classes.any? { |klass| value.is_a?(klass) }
+        return Provider::ResolutionDetails.new(
+          value: value,
+          reason: Provider::Reason::STATIC,
+          variant: variant)
+      else
+        make_resolution_error(
+          default_value,
+          Provider::ErrorCode::TYPE_MISMATCH,
+          'The type of value received is different from the requested value.',
+          variant: variant)
+      end
+    rescue Kameleoon::Exception::FeatureError => e
+      make_resolution_error(default_value, Provider::ErrorCode::FLAG_NOT_FOUND, e.message)
+    rescue Kameleoon::Exception::VisitorCodeInvalid => e
+      make_resolution_error(default_value, Provider::ErrorCode::INVALID_CONTEXT, e.message)
+    rescue StandardError => e
+      make_resolution_error(default_value, Provider::ErrorCode::GENERAL, e.message, variant: variant)
+    end
+
+    private
+
+    # Helper method to get the targeting key from the context.
+    def get_targeting_key(evaluation_context)
+      targeting_key = evaluation_context.targeting_key
+      targeting_key if targeting_key.is_a?(String)
+    end
+
+    # Helper method to get the variable key from the context or variables map.
+    def get_variable_key(context, variables)
+      variable_key = context.field(VARIABLE_KEY)
+      variable_key = variables.keys.first if variable_key.nil? || variable_key.empty?
+      variable_key
+    end
+
+    # Helper method to generate an error description based on the variant and variable key.
+    def make_error_description(variant, variable_key)
+      if variable_key.nil? || variable_key.empty?
+        "The variation '#{variant}' has no variables"
+      else
+        "The value for provided variable key '#{variable_key}' isn't found in variation '#{variant}'"
+      end
+    end
+
+    # Helper method to generate a resolution details with error.
+    def make_resolution_error(default_value, error_code, error_message, variant: nil)
+      Provider::ResolutionDetails.new(
+        value: default_value,
+        error_code: error_code,
+        error_message: error_message,
+        reason: Provider::Reason::ERROR,
+        variant: variant)
+    end
+  end
+end

data/lib/kameleoon/types.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Kameleoon
+  module Types
+    module Data
+      # Type is used to add different Kameleoon data types using
+      # OpenFeature::SDK::EvaluationContext.
+      module Type
+        CONVERSION = 'conversion'
+        CUSTOM_DATA = 'customData'
+      end
+
+      # CustomDataType is used to add Kameleoon::CustomData using
+      # OpenFeature::SDK::EvaluationContext.
+      module CustomDataType
+        INDEX = 'index'
+        VALUES = 'values'
+      end
+
+      # ConversionType is used to add Kameleoon::Conversion using
+      # OpenFeature::SDK::EvaluationContext.
+      module ConversionType
+        GOAL_ID = 'goalId'
+        REVENUE = 'revenue'
+      end
+    end
+  end
+end

data/lib/kameleoon/util/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Kameleoon
+  OPENFEATURE_SDK_VERSION = '0.0.1'
+end

metadata

@@ -0,0 +1,77 @@
+--- !ruby/object:Gem::Specification
+name: kameleoon-openfeature-ruby
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Kameleoon
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2024-10-15 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: openfeature-sdk
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.4.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.4.0
+- !ruby/object:Gem::Dependency
+  name: kameleoon-client-ruby
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 3.4.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 3.4.0
+description: Kameleoon OpenFeature provider for the Ruby SDK
+email:
+- sdk@kameleoon.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/kameleoon/data_converter.rb
+- lib/kameleoon/kameleoon_provider.rb
+- lib/kameleoon/resolver.rb
+- lib/kameleoon/types.rb
+- lib/kameleoon/util/version.rb
+homepage: https://developers.kameleoon.com/ruby-sdk.html
+licenses:
+- GPL-3.0
+metadata: {}
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.3.26
+signing_key:
+specification_version: 4
+summary: Kameleoon OpenFeature Ruby
+test_files: []