flipt_client 0.16.1 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 717a1fe2a20f7f152ff30b3f64215ed35cfa281025513b5bd468f21852ed2a72
-  data.tar.gz: fba45e5687bb3c2ff658c632a8222afa149e8438a93234cd38098322402aec3f
+  metadata.gz: 8cfa993fb8a7521e64c37cef82bf58088f8961d9779e6c5dc9092696a127c6ff
+  data.tar.gz: 2cddbf45abafabd21660a60ab64378a2b1c4bfdafee4b931805ca8b2a1c2d002
 SHA512:
-  metadata.gz: 70130fe75d70bbc46a2ba89377a3c701c6b399fb0b2644f20c8f7fe9f0841bf012655478eda9aef92bee4eb30b55882365cb5eb2a789f757e49ce8cf3dec96e8
-  data.tar.gz: c33564298208867ba51cf2b91df5ff806bfc48a1ff6e396625e5ce984d2031e8c0318cc537a00aa9e15263ce8a50943c695823e039334fe833226f251951a438
+  metadata.gz: b2cc595e3b40f37c420b920415d65e439a6295ddc1d1b4c22dc0fb2cb98e43e36912842568e1eb47246a088f15eb6bcce530e020daf0c2d34253fec9fa18347d
+  data.tar.gz: 26c75eb569c0e0df06cf287ae7f9cb5beb0466be5e1c1cb8ec49252d38277914afa842f56650d7dd857cb3696d73d17a68ea6082ada6101f3bbfa729142c934f

data/README.md

@@ -26,12 +26,26 @@ Upon instantiation, the `flipt-client-ruby` library will fetch the flag state fr
 
 By default, the SDK will poll the Flipt server for new flag state at a regular interval. This interval can be configured using the `update_interval` option when constructing a client. The default interval is 120 seconds.
 
-### Streaming (Flipt Cloud Only)
+### Streaming (Flipt Cloud/Flipt v2)
 
-[Flipt Cloud](https://flipt.io/cloud) users can use the `streaming` fetch method to stream flag state changes from the Flipt server to the SDK.
+[Flipt Cloud](https://flipt.io/cloud) and [Flipt v2](https://docs.flipt.io/v2) users can use the `streaming` fetch method to stream flag state changes from the Flipt server to the SDK.
 
 When in streaming mode, the SDK will connect to the Flipt server and open a persistent connection that will remain open until the client is closed. The SDK will then receive flag state changes in real-time.
 
+### Retries
+
+The SDK will automatically retry fetching (or initiating streaming) flag state if the client is unable to reach the Flipt server temporarily.
+
+The SDK will retry up to 3 times with an exponential backoff interval between retries. The base delay is 1 second and the maximum delay is 30 seconds.
+
+Retriable errors include:
+
+- `429 Too Many Requests`
+- `502 Bad Gateway`
+- `503 Service Unavailable`
+- `504 Gateway Timeout`
+- Other potential transient network or DNS errors
+
 ## Supported Architectures
 
 This SDK currently supports the following OSes/architectures:
@@ -53,6 +67,21 @@ gem install ffi -- --enable-system-libffi        # to install the gem manually
 bundle config build.ffi --enable-system-libffi   # for bundle install
 ```
 
+## Migration Notes
+
+### Pre-1.0.0 -> 1.0.0
+
+This section is for users who are migrating from a previous (pre-1.0.0) version of the SDK.
+
+- `Flipt::EvaluationClient` has been renamed to `Flipt::Client`. Update all usages and imports accordingly. A deprecation warning is emitted if you use the old class.
+- All evaluation methods now use **keyword arguments** (e.g., `flag_key:`, `entity_id:`, `context:`) instead of a single hash argument. Update your method calls to use keyword arguments.
+- All evaluation methods now return **response model objects** (`VariantEvaluationResponse`, `BooleanEvaluationResponse`, `BatchEvaluationResponse`, `ErrorEvaluationResponse`) instead of raw hashes. Update your code to use attribute readers (e.g., `resp.flag_key`, `resp.enabled`).
+- Batch evaluation responses now contain an array of model objects, not hashes.
+- Error handling is now standardized and idiomatic. All errors inherit from `Flipt::Error` (with subclasses like `ValidationError`, `EvaluationError`). Update your rescue blocks accordingly.
+- The minimum supported Ruby version is now 2.7.0.
+- The client constructor now accepts keyword arguments for configuration (e.g., `url:`, `namespace:`, `authentication:`). The `environment` option is now supported.
+- The API and documentation are more idiomatic and Ruby-like throughout.
+
 ## Usage
 
 In your Ruby code you can import this client and use it as so:
@@ -60,40 +89,35 @@ In your Ruby code you can import this client and use it as so:
 ```ruby
 require 'flipt_client'
 
-# namespace is the first positional argument and is optional here and will have a value of "default" if not specified.
-# opts is the second positional argument and is also optional, the structure is:
-# {
-#   "url": "http://localhost:8080",
-#   "update_interval": 120,
-#   "authentication": {
-#     "client_token": "secret"
-#   }
-# }
-#
-# You can replace the url with where your upstream Flipt instance points to, the update interval for how long you are willing
-# to wait for updated flag state, and the auth token if your Flipt instance requires it.
-client = Flipt::EvaluationClient.new()
-resp = client.evaluate_variant({ flag_key: 'buzz', entity_id: 'someentity', context: { fizz: 'buzz' } })
-
-puts resp
+client = Flipt::Client.new(url: 'http://localhost:8080', authentication: Flipt::ClientTokenAuthentication.new('secret'))
+
+resp = client.evaluate_variant(flag_key: 'buzz', entity_id: 'someentity', context: { fizz: 'buzz' })
+puts resp.flag_key # => 'buzz'
+puts resp.match # => true
+puts resp.reason # => 'MATCH_EVALUATION_REASON'
+
+resp = client.evaluate_boolean(flag_key: 'my-feature', entity_id: 'someentity')
+puts resp.enabled # => true
 ```
 
 ### Constructor Arguments
 
-The `Flipt::EvaluationClient` constructor accepts two optional arguments:
+The `Flipt::Client` constructor accepts the following keyword arguments:
 
+- `environment`: The environment (Flipt v2) to fetch flag state from. If not provided, the client will default to the `default` environment.
 - `namespace`: The namespace to fetch flag state from. If not provided, the client will default to the `default` namespace.
-- `opts`: A hash that supports several options for the client. The structure is:
-  - `url`: The URL of the upstream Flipt instance. If not provided, the client will default to `http://localhost:8080`.
-  - `update_interval`: The interval (in seconds) in which to fetch new flag state. If not provided, the client will default to 120 seconds.
-  - `authentication`: The authentication strategy to use when communicating with the upstream Flipt instance. If not provided, the client will default to no authentication. See the [Authentication](#authentication) section for more information.
-  - `reference`: The [reference](https://docs.flipt.io/guides/user/using-references) to use when fetching flag state. If not provided, reference will not be used.
-  - `fetch_mode`: The fetch mode to use when fetching flag state. If not provided, the client will default to polling.
-  - `error_strategy`: The error strategy to use when fetching flag state. If not provide, the client will be default to fail. See the [Error Strategies](#error-strategies) section for more information.
+- `url`: The URL of the upstream Flipt instance. Defaults to `http://localhost:8080`.
+- `request_timeout`: Timeout (in seconds) for requests. Defaults to no timeout.
+- `update_interval`: Interval (in seconds) to fetch new flag state. Defaults to 120 seconds.
+- `authentication`: The authentication strategy to use. Defaults to no authentication. See [Authentication](#authentication).
+- `reference`: The [reference](https://docs.flipt.io/guides/user/using-references) to use when fetching flag state.
+- `fetch_mode`: The fetch mode to use. Defaults to polling.
+- `error_strategy`: The error strategy to use. Defaults to fail. See [Error Strategies](#error-strategies).
+- `snapshot`: The snapshot to use when initializing the client. Defaults to no snapshot. See [Snapshotting](#snapshotting).
 
 ### Authentication
 
-The `FliptEvaluationClient` supports the following authentication strategies:
+The `Flipt::Client` supports the following authentication strategies:
 
 - No Authentication (default)
 - [Client Token Authentication](https://docs.flipt.io/authentication/using-tokens)
@@ -106,6 +130,46 @@ The client supports the following error strategies:
 - `fail`: The client will throw an error if the flag state cannot be fetched. This is the default behavior.
 - `fallback`: The client will maintain the last known good state and use that state for evaluation in case of an error.
 
+### Response Models
+
+All evaluation methods return response model objects:
+
+- `evaluate_variant` returns a `Flipt::VariantEvaluationResponse`
+- `evaluate_boolean` returns a `Flipt::BooleanEvaluationResponse`
+- `evaluate_batch` returns a `Flipt::BatchEvaluationResponse`
+
+### Error Handling
+
+All errors inherit from `Flipt::Error`. Common subclasses include:
+
+- `Flipt::ValidationError`
+- `Flipt::EvaluationError`
+
+You can rescue these errors as needed:
+
+```ruby
+begin
+  client.evaluate_variant(flag_key: 'missing', entity_id: 'user')
+rescue Flipt::EvaluationError => e
+  puts "Evaluation failed: #{e.message}"
+end
+```
+
+### Snapshotting
+
+The client supports snapshotting of flag state as well as seeding the client with a snapshot for evaluation. This is helpful if you want to use the client in an environment where the Flipt server is not guaranteed to be available or reachable on startup.
+
+To get the snapshot for the client, you can use the `snapshot` method. This returns a base64 encoded JSON string that represents the flag state for the client.
+
+You can set the snapshot for the client using the `snapshot` option when constructing a client.
+
+**Note:** You most likely will want to also set the `error_strategy` to `fallback` when using snapshots. This will ensure that you wont get an error if the Flipt server is not available or reachable even on the initial fetch.
+
+You also may want to store the snapshot in a local file so that you can use it to seed the client on startup.
+
+> [!IMPORTANT]
+> If the Flipt server becomes reachable after the setting the snapshot, the client will replace the snapshot with the new flag state from the Flipt server.
+
 ## Load Test
 
 1. To run the load test, you'll need to have Flipt running locally. You can do this by running the following command from the root of the repository:

data/flipt-client-ruby.gemspec

@@ -11,7 +11,7 @@ Gem::Specification.new do |spec|
   spec.description   = 'Flipt Client Evaluation SDK'
   spec.homepage      = 'https://www.flipt.io'
   spec.license       = 'MIT'
-  spec.required_ruby_version = Gem::Requirement.new('>= 2.3.0')
+  spec.required_ruby_version = Gem::Requirement.new('>= 2.7.0')
 
   # spec.metadata['allowed_push_host'] = "TODO: Set to 'http://mygemserver.com'"
 

data/lib/ext/flipt_engine.h

@@ -8,7 +8,35 @@
  *
  * This function will initialize an Engine and return a pointer back to the caller.
  */
-void *initialize_engine(const char *namespace_, const char *opts);
+void *initialize_engine_ffi(const char *opts);
+
+/**
+ * # Safety
+ *
+ * This function will initialize an Engine and return a pointer back to the caller.
+ */
+void *initialize_engine(const char *opts);
+
+/**
+ * # Safety
+ *
+ * This function will take in a pointer to the engine and return the current snapshot as a JSON string.
+ */
+const char *get_snapshot_ffi(void *engine_ptr);
+
+/**
+ * # Safety
+ *
+ * This function will take in a pointer to the engine and return the current snapshot as a JSON string.
+ */
+const char *get_snapshot(void *engine_ptr);
+
+/**
+ * # Safety
+ *
+ * This function will take in a pointer to the engine and return a variant evaluation response.
+ */
+const char *evaluate_variant_ffi(void *engine_ptr, const char *evaluation_request);
 
 /**
  * # Safety
@@ -17,6 +45,13 @@ void *initialize_engine(const char *namespace_, const char *opts);
  */
 const char *evaluate_variant(void *engine_ptr, const char *evaluation_request);
 
+/**
+ * # Safety
+ *
+ * This function will take in a pointer to the engine and return a boolean evaluation response.
+ */
+const char *evaluate_boolean_ffi(void *engine_ptr, const char *evaluation_request);
+
 /**
  * # Safety
  *
@@ -24,6 +59,13 @@ const char *evaluate_variant(void *engine_ptr, const char *evaluation_request);
  */
 const char *evaluate_boolean(void *engine_ptr, const char *evaluation_request);
 
+/**
+ * # Safety
+ *
+ * This function will take in a pointer to the engine and return a batch evaluation response.
+ */
+const char *evaluate_batch_ffi(void *engine_ptr, const char *batch_evaluation_request);
+
 /**
  * # Safety
  *
@@ -34,30 +76,41 @@ const char *evaluate_batch(void *engine_ptr, const char *batch_evaluation_reques
 /**
  * # Safety
  *
- * This function will take in a pointer to the engine and return a list of flags for the given namespace.
+ * This function will take in a pointer to the engine and return a list of flags.
+ */
+const char *list_flags_ffi(void *engine_ptr);
+
+/**
+ * # Safety
+ *
+ * This function will take in a pointer to the engine and return a list of flags.
  */
 const char *list_flags(void *engine_ptr);
 
 /**
  * # Safety
  *
- * This function will free the memory occupied by the engine.
+ * This function will take in a pointer to the engine and destroy it.
+ */
+void destroy_engine_ffi(void *engine_ptr);
+
+/**
+ * # Safety
+ *
+ * This function will take in a pointer to the engine and destroy it.
  */
 void destroy_engine(void *engine_ptr);
 
 /**
  * # Safety
  *
- * This function will take in a pointer to the string and free the memory.
- * See Rust the safety section in CString::from_raw.
+ * This function will take in a pointer to a string and destroy it.
  */
-void destroy_string(char *ptr);
+void destroy_string_ffi(char *ptr);
 
-// Add missing external declarations for Rust functions
-extern void* initialize_engine_ffi(const char* namespace, const char* options);
-extern const char* evaluate_boolean_ffi(void* engine, const char* request);
-extern const char* evaluate_variant_ffi(void* engine, const char* request);
-extern const char* evaluate_batch_ffi(void* engine, const char* request);
-extern const char* list_flags_ffi(void* engine);
-extern void destroy_engine_ffi(void* engine);
-extern void destroy_string_ffi(char* str);
+/**
+ * # Safety
+ *
+ * This function will take in a pointer to a string and destroy it.
+ */
+void destroy_string(char *ptr);

data/lib/flipt_client/models.rb

@@ -40,4 +40,66 @@ module Flipt
       }
     end
   end
+
+  # VariantEvaluationResponse
+  # @attr_reader [String] flag_key
+  # @attr_reader [Boolean] match
+  # @attr_reader [String] reason
+  # @attr_reader [String] variant_key
+  # @attr_reader [String, nil] variant_attachment
+  # @attr_reader [Array<String>] segment_keys
+  class VariantEvaluationResponse
+    attr_reader :flag_key, :match, :reason, :variant_key, :variant_attachment, :segment_keys
+
+    def initialize(flag_key:, match:, reason:, variant_key:, variant_attachment: nil, segment_keys: [])
+      @flag_key = flag_key
+      @match = match
+      @reason = reason
+      @variant_key = variant_key
+      @variant_attachment = variant_attachment
+      @segment_keys = segment_keys
+    end
+  end
+
+  # BooleanEvaluationResponse
+  # @attr_reader [String] flag_key
+  # @attr_reader [Boolean] enabled
+  # @attr_reader [String] reason
+  # @attr_reader [Array<String>] segment_keys
+  class BooleanEvaluationResponse
+    attr_reader :flag_key, :enabled, :reason, :segment_keys
+
+    def initialize(flag_key:, enabled:, reason:, segment_keys: [])
+      @flag_key = flag_key
+      @enabled = enabled
+      @reason = reason
+      @segment_keys = segment_keys
+    end
+  end
+
+  # ErrorEvaluationResponse
+  # @attr_reader [String] flag_key
+  # @attr_reader [String] namespace_key
+  # @attr_reader [String] reason
+  # @attr_reader [String] error_message
+  class ErrorEvaluationResponse
+    attr_reader :flag_key, :namespace_key, :reason, :error_message
+
+    def initialize(flag_key:, namespace_key:, reason:, error_message:)
+      @flag_key = flag_key
+      @namespace_key = namespace_key
+      @reason = reason
+      @error_message = error_message
+    end
+  end
+
+  # BatchEvaluationResponse
+  # @attr_reader [Array] responses
+  class BatchEvaluationResponse
+    attr_reader :responses
+
+    def initialize(responses: [])
+      @responses = responses
+    end
+  end
 end

data/lib/flipt_client/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Flipt
-  VERSION = '0.16.1'
+  VERSION = '1.0.0'
 end

data/lib/flipt_client.rb

@@ -7,9 +7,11 @@ require 'json'
 
 module Flipt
   class Error < StandardError; end
+  class ValidationError < Error; end
+  class EvaluationError < Error; end
 
-  # EvaluationClient is a Ruby Client Side Evaluation Library for Flipt
-  class EvaluationClient
+  # Client is a Ruby Client Side Evaluation Library for Flipt
+  class Client
     extend FFI::Library
 
     FLIPTENGINE = 'fliptengine'
@@ -32,8 +34,8 @@ module Flipt
 
     ffi_lib File.expand_path(libfile, __dir__)
 
-    # void *initialize_engine(const char *namespace, const char *opts);
-    attach_function :initialize_engine, %i[string string], :pointer
+    # void *initialize_engine(const char *opts);
+    attach_function :initialize_engine, [:string], :pointer
     # void destroy_engine(void *engine_ptr);
     attach_function :destroy_engine, [:pointer], :void
     # const char *evaluate_variant(void *engine_ptr, const char *evaluation_request);
@@ -46,26 +48,31 @@ module Flipt
     attach_function :list_flags, [:pointer], :strptr
     # void destroy_string(const char *ptr);
     attach_function :destroy_string, [:pointer], :void
+    # const char *get_snapshot(void *engine_ptr);
+    attach_function :get_snapshot, [:pointer], :strptr
 
     # Create a new Flipt client
     #
-    # @param namespace [String] namespace
     # @param opts [Hash] options
+    # @option opts [String] :environment Flipt environment (default: 'default')
+    # @option opts [String] :namespace Flipt namespace (default: 'default')
     # @option opts [String] :url Flipt server url
     # @option opts [AuthenticationStrategy] :authentication strategy to authenticate with Flipt
+    # @option opts [Integer] :request_timeout timeout in seconds for the request
     # @option opts [Integer] :update_interval interval in seconds to update the cache
     # @option opts [String] :reference reference to use for namespace data
     # @option opts [Symbol] :fetch_mode fetch mode to use for the client (:polling or :streaming).
-    #   Note: Streaming is currently only supported when using the SDK with Flipt Cloud (https://flipt.io/cloud).
+    #   Note: Streaming is currently only supported when using the SDK with Flipt Cloud or Flipt v2.
     # @option opts [Symbol] :error_strategy error strategy to use for the client (:fail or :fallback).
-    def initialize(namespace = 'default', opts = {})
-      @namespace = namespace
+    # @option opts [String] :snapshot snapshot to use when initializing the client
+    def initialize(**opts)
+      @namespace = opts.fetch(:namespace, 'default')
 
       opts[:authentication] = validate_authentication(opts.fetch(:authentication, NoAuthentication.new))
       opts[:fetch_mode] = validate_fetch_mode(opts.fetch(:fetch_mode, :polling))
       opts[:error_strategy] = validate_error_strategy(opts.fetch(:error_strategy, :fail))
 
-      @engine = self.class.initialize_engine(namespace, opts.to_json)
+      @engine = self.class.initialize_engine(opts.to_json)
       ObjectSpace.define_finalizer(self, self.class.finalize(@engine))
     end
 
@@ -75,88 +82,154 @@ module Flipt
 
     # Evaluate a variant flag for a given request
     #
-    # @param evaluation_request [Hash] evaluation request
-    # @option evaluation_request [String] :entity_id entity id
-    # @option evaluation_request [String] :flag_key flag key
-    def evaluate_variant(evaluation_request = {})
-      validate_evaluation_request(evaluation_request)
-      resp, ptr = self.class.evaluate_variant(@engine, evaluation_request.to_json)
-      ptr = FFI::AutoPointer.new(ptr, EvaluationClient.method(:destroy_string))
+    # @param flag_key [String]
+    # @param entity_id [String]
+    # @param context [Hash]
+    def evaluate_variant(flag_key:, entity_id:, context: {})
+      validate_evaluation_request(flag_key, entity_id, context)
+      req = { flag_key: flag_key, entity_id: entity_id, context: context }
+      resp, ptr = self.class.evaluate_variant(@engine, req.to_json)
+      ptr = FFI::AutoPointer.new(ptr, Client.method(:destroy_string))
       data = JSON.parse(resp)
-      raise Error, data['error_message'] if data['status'] != 'success'
-
-      data['result']
+      raise EvaluationError, data['error_message'] if data['status'] != 'success'
+
+      r = data['result']
+      VariantEvaluationResponse.new(
+        flag_key: r['flag_key'],
+        match: r['match'],
+        reason: r['reason'],
+        variant_key: r['variant_key'],
+        variant_attachment: r['variant_attachment'],
+        segment_keys: r['segment_keys'] || []
+      )
     end
 
     # Evaluate a boolean flag for a given request
     #
-    # @param evaluation_request [Hash] evaluation request
-    # @option evaluation_request [String] :entity_id entity id
-    # @option evaluation_request [String] :flag_key flag key
-    def evaluate_boolean(evaluation_request = {})
-      validate_evaluation_request(evaluation_request)
-      resp, ptr = self.class.evaluate_boolean(@engine, evaluation_request.to_json)
-      ptr = FFI::AutoPointer.new(ptr, EvaluationClient.method(:destroy_string))
+    # @param flag_key [String]
+    # @param entity_id [String]
+    # @param context [Hash]
+    def evaluate_boolean(flag_key:, entity_id:, context: {})
+      validate_evaluation_request(flag_key, entity_id, context)
+      req = { flag_key: flag_key, entity_id: entity_id, context: context }
+      resp, ptr = self.class.evaluate_boolean(@engine, req.to_json)
+      ptr = FFI::AutoPointer.new(ptr, Client.method(:destroy_string))
       data = JSON.parse(resp)
-      raise Error, data['error_message'] if data['status'] != 'success'
-
-      data['result']
+      raise EvaluationError, data['error_message'] if data['status'] != 'success'
+
+      r = data['result']
+      BooleanEvaluationResponse.new(
+        flag_key: r['flag_key'],
+        enabled: r['enabled'],
+        reason: r['reason'],
+        segment_keys: r['segment_keys'] || []
+      )
     end
 
     # Evaluate a batch of flags for a given request
     #
-    # @param batch_evaluation_request [Array<Hash>] batch evaluation request
+    # @param requests [Array<Hash>] batch evaluation request
     #   - :entity_id [String] entity id
     #   - :flag_key [String] flag key
-    def evaluate_batch(batch_evaluation_request = [])
-      batch_evaluation_request.each do |request|
-        validate_evaluation_request(request)
+    def evaluate_batch(requests:)
+      unless requests.is_a?(Array)
+        raise ValidationError, 'requests must be an array of evaluation requests'
       end
 
-      resp, ptr = self.class.evaluate_batch(@engine, batch_evaluation_request.to_json)
-      ptr = FFI::AutoPointer.new(ptr, EvaluationClient.method(:destroy_string))
+      requests.each do |request|
+        validate_evaluation_request(request[:flag_key], request[:entity_id], request[:context] || {})
+      end
+      resp, ptr = self.class.evaluate_batch(@engine, requests.to_json)
+      ptr = FFI::AutoPointer.new(ptr, Client.method(:destroy_string))
       data = JSON.parse(resp)
-      raise Error, data['error_message'] if data['status'] != 'success'
-
-      data['result']
+      raise EvaluationError, data['error_message'] if data['status'] != 'success'
+
+      responses = (data['result']['responses'] || []).map do |r|
+        case r['type']
+        when 'VARIANT_EVALUATION_RESPONSE_TYPE'
+          v = r['variant_evaluation_response']
+          VariantEvaluationResponse.new(
+            flag_key: v['flag_key'],
+            match: v['match'],
+            reason: v['reason'],
+            variant_key: v['variant_key'],
+            variant_attachment: v['variant_attachment'],
+            segment_keys: v['segment_keys'] || []
+          )
+        when 'BOOLEAN_EVALUATION_RESPONSE_TYPE'
+          b = r['boolean_evaluation_response']
+          BooleanEvaluationResponse.new(
+            flag_key: b['flag_key'],
+            enabled: b['enabled'],
+            reason: b['reason'],
+            segment_keys: b['segment_keys'] || []
+          )
+        when 'ERROR_EVALUATION_RESPONSE_TYPE'
+          e = r['error_evaluation_response']
+          ErrorEvaluationResponse.new(
+            flag_key: e['flag_key'],
+            namespace_key: e['namespace_key'],
+            reason: e['reason'],
+            error_message: e['error_message']
+          )
+        else
+          raise EvaluationError, "Unknown response type encountered: #{r['type']}"
+        end
+      end
+      BatchEvaluationResponse.new(responses: responses)
     end
 
     # List all flags in the namespace
     def list_flags
       resp, ptr = self.class.list_flags(@engine)
-      ptr = FFI::AutoPointer.new(ptr, EvaluationClient.method(:destroy_string))
+      ptr = FFI::AutoPointer.new(ptr, Client.method(:destroy_string))
       data = JSON.parse(resp)
       raise Error, data['error_message'] if data['status'] != 'success'
 
       data['result']
     end
 
+    # Get the snapshot of the current flag state
+    def snapshot
+      resp, ptr = self.class.get_snapshot(@engine)
+      ptr = FFI::AutoPointer.new(ptr, Client.method(:destroy_string))
+      resp
+    end
+
     private
 
-    def validate_evaluation_request(evaluation_request)
-      if evaluation_request[:entity_id].nil? || evaluation_request[:entity_id].empty?
-        raise ArgumentError, 'entity_id is required'
-      elsif evaluation_request[:flag_key].nil? || evaluation_request[:flag_key].empty?
-        raise ArgumentError, 'flag_key is required'
-      end
+    def validate_evaluation_request(flag_key, entity_id, context)
+      raise ValidationError, 'flag_key is required' if flag_key.nil? || flag_key.empty?
+      raise ValidationError, 'entity_id is required' if entity_id.nil? || entity_id.empty?
+      return if context.is_a?(Hash)
+
+      raise ValidationError, 'context must be a Hash<String, String>'
     end
 
     def validate_authentication(authentication)
       return authentication.strategy if authentication.is_a?(AuthenticationStrategy)
 
-      raise ArgumentError, 'invalid authentication strategy'
+      raise ValidationError, 'invalid authentication strategy'
     end
 
     def validate_fetch_mode(fetch_mode)
       return fetch_mode if %i[polling streaming].include?(fetch_mode)
 
-      raise ArgumentError, 'invalid fetch mode'
+      raise ValidationError, 'invalid fetch mode'
     end
 
     def validate_error_strategy(error_strategy)
       return error_strategy if %i[fail fallback].include?(error_strategy)
 
-      raise ArgumentError, 'invalid error strategy'
+      raise ValidationError, 'invalid error strategy'
+    end
+  end
+
+  # Deprecation shim for EvaluationClient
+  class EvaluationClient < Client
+    def initialize(*args, **kwargs)
+      warn '[DEPRECATION] `EvaluationClient` is deprecated. Please use `Client` instead.'
+      super
     end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: flipt_client
 version: !ruby/object:Gem::Version
-  version: 0.16.1
+  version: 1.0.0
 platform: ruby
 authors:
 - Flipt Devs
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-03-07 00:00:00.000000000 Z
+date: 2025-06-09 00:00:00.000000000 Z
 dependencies: []
 description: Flipt Client Evaluation SDK
 email:
@@ -42,7 +42,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.3.0
+      version: 2.7.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="