shipeasy-sdk 1.7.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: afdce684e3c6a83b220b7dfaa1d7db249284e3bb4c4ebfe3c9b27c54da0d801b
-  data.tar.gz: ecdfdf8aed19f1b5f18fe874ce5b13064bb61abe7bf7f1c47a76b08d9ab99bce
+  metadata.gz: 97efde389fa7a5adc1ffdab3951d09837f435bd529d8f6c3b7e3d45387472628
+  data.tar.gz: 46f183776d94ccbddd8781e39d3ea5e56e6795cf26f3292f1482c2886b7d0836
 SHA512:
-  metadata.gz: e6a5470268bc584eaa2dbc8c89f722a22633d0bd6f896aaa1d73db74090b56667c87733c614b8a49bdeda88dab043740509153503943837a69be20a03dc315b7
-  data.tar.gz: 55289a4adf0559f41eca2d1f6bca03b53a19da9b3f00f4109dc4476ed0c5cbaaed453dbaf3f7c0ebcc1405f0d73a55fe702e02859c9a809d525e92b294e275ba
+  metadata.gz: 010654d1322131ab21b467fdff8176914e427558a5a620762c4417378f68c5cc5f3b189e7b0cdb8de6b741d2232e7c1552b8fd551bc3fce19b09e91263e18d12
+  data.tar.gz: 24730826e8f2de0ac3f1546ab4f42b2301bcd8f83bdaea0b9c50487d7b90d5b445470827199de73c4794bc16b2ddeed3e18fc44079c2000cd0c92aeb07f50e55

data/README.md

@@ -14,34 +14,56 @@ gem "shipeasy-sdk"
 
 ## Quickstart (Rails)
 
-`config/initializers/shipeasy.rb` is all you need:
+Two parts: **configure once** at boot, then build a **user-bound
+`Shipeasy::Client`** per request via its constructor.
+
+`config/initializers/shipeasy.rb`:
 
 ```ruby
 Shipeasy.configure do |c|
   c.api_key    = ENV.fetch("SHIPEASY_SERVER_KEY")
+
+  # Optional: map YOUR user object → the Shipeasy attribute hash. Runs once,
+  # in the Shipeasy::Client constructor. Omit it and the object you pass to
+  # Shipeasy::Client.new IS the attribute hash (identity).
+  c.attributes = ->(u) { { "user_id" => u.id, "plan" => u.plan } }
+
   c.public_key = ENV.fetch("SHIPEASY_CLIENT_KEY")  # for i18n view helpers
   c.profile    = "default"
 end
 ```
 
-Anywhere in your app:
+`configure` builds the single global engine for you and kicks off a one-shot
+fetch (fire-and-forget). Anywhere in your app, construct a bound client and call
+the getters with **no user argument** — the user is bound at construction:
 
 ```ruby
-user = { user_id: current_user.id, plan: current_user.plan }
+flags = Shipeasy::Client.new(current_user)   # runs the attributes transform once
 
-if Shipeasy.flags.get_flag("new_checkout", user)
+if flags.get_flag("new_checkout")            # NO user arg
   # ship it
 end
 
-color  = Shipeasy.flags.get_config("button_color")
-result = Shipeasy.flags.get_experiment("checkout_cta", user, { label: "Buy now" })
-Shipeasy.flags.track(current_user.id.to_s, "checkout_completed", { revenue: 49.99 })
+color  = flags.get_config("button_color")
+result = flags.get_experiment("checkout_cta", { label: "Buy now" })
+panic  = flags.get_killswitch("payments")
 ```
 
-`Shipeasy.flags` is a lazy, **fork-safe** singleton: the first call from
-each process spawns its own `FlagsClient` and starts the background poll
-thread, including post-fork Puma workers under `preload_app!`. No need
-for `before_worker_boot` hooks or holding a global constant.
+`Shipeasy::Client` is **cheap**: it delegates evaluation to the single engine
+built by `configure` — it never opens its own connection, fetches, or polls.
+Construct one per user / per request.
+
+Event ingestion (`track`) lives on the engine — `Shipeasy.engine` is the global
+one `configure` registered:
+
+```ruby
+Shipeasy.engine.track(current_user.id.to_s, "checkout_completed", { revenue: 49.99 })
+```
+
+> **Upgrading from 1.x?** The heavyweight client was renamed
+> `Shipeasy::SDK::FlagsClient` → `Shipeasy::Engine`, and `Shipeasy::Client` is
+> now the lightweight user-bound handle. The legacy `Shipeasy.flags.get_flag(name, user)`
+> singleton still works.
 
 In a Rails view (the railtie auto-mounts these helpers when Rails is loaded):
 
@@ -61,7 +83,7 @@ wiring** — `get_flag` on an anonymous request just works:
 
 ```ruby
 # current_user is nil → buckets on the __se_anon_id cookie automatically
-Shipeasy.flags.get_flag("new_checkout", {})
+Shipeasy::Client.new({}).get_flag("new_checkout")
 ```
 
 An explicit `user_id` / `anonymous_id` always wins. If you prefer to read the id
@@ -86,7 +108,8 @@ require "shipeasy-sdk"
 
 Shipeasy.configure { |c| c.api_key = ENV.fetch("SHIPEASY_SERVER_KEY") }
 
-Shipeasy.flags.get_flag("new_checkout", { user_id: "u_1" })
+# With no `attributes` transform, the hash you pass IS the attribute map.
+Shipeasy::Client.new({ "user_id" => "u_1" }).get_flag("new_checkout")
 ```
 
 The Rails view helpers (`i18n_*`) are not loaded outside Rails, so the
@@ -99,9 +122,9 @@ short-lived function. Build the client explicitly and call `init_once`
 for a single synchronous fetch:
 
 ```ruby
-client = Shipeasy::SDK::FlagsClient.new(api_key: ENV.fetch("SHIPEASY_SERVER_KEY"))
-client.init_once
-client.get_flag("new_checkout", user)
+engine = Shipeasy::Engine.new(api_key: ENV.fetch("SHIPEASY_SERVER_KEY"))
+engine.init_once
+engine.get_flag("new_checkout", user)
 ```
 
 ## Lifecycle escape hatch
@@ -206,9 +229,9 @@ endpoints:
 ```
 
 ```ruby
-client = Shipeasy::SDK::FlagsClient.from_file("snapshot.json")
+client = Shipeasy::Engine.from_file("snapshot.json")
 # or, from already-parsed blobs:
-client = Shipeasy::SDK::FlagsClient.from_snapshot(flags: flags_body, experiments: exps_body)
+client = Shipeasy::Engine.from_snapshot(flags: flags_body, experiments: exps_body)
 
 client.get_flag("new_checkout", user)        # real evaluation, no network
 client.get_experiment("checkout_cta", user, {})
@@ -235,7 +258,7 @@ snapshot.
 
 For unit/integration tests you want a client that does **zero network** and
 returns exactly the values you seed — no api_key, no fetch, no poll thread, no
-telemetry, no metric ingestion. Build one with `FlagsClient.for_testing` and
+telemetry, no metric ingestion. Build one with `Shipeasy::Engine.for_testing` and
 seed each entity with the `override_*` setters (Statsig-style local overrides).
 An override always wins over the fetched blob, so the getters answer
 deterministically:
@@ -243,7 +266,7 @@ deterministically:
 ```ruby
 require "shipeasy-sdk"
 
-client = Shipeasy::SDK::FlagsClient.for_testing
+client = Shipeasy::Engine.for_testing
 # init / init_once are no-ops here — nothing is ever fetched.
 
 # Flags (boolean)
@@ -272,31 +295,35 @@ client.clear_overrides
 
 The same `override_flag` / `override_config` / `override_experiment` /
 `clear_overrides` setters also work on a **normal** live client (built with
-`FlagsClient.new(...)`), so you can pin one value in local development while the
+`Shipeasy::Engine.new(...)`), so you can pin one value in local development while the
 rest comes from the fetched blob.
 
-### Rails singleton
+### Global engine / bound client
 
-`Shipeasy.flags` is a process-wide singleton that fetches over the network, so
-in tests prefer a `for_testing` client. If a code path reaches through
-`Shipeasy.flags` directly, stub the singleton to the test client in your test
-setup:
+`Shipeasy.engine` (registered by `configure`) and `Shipeasy.flags` (legacy
+singleton) both fetch over the network, so in tests stub them to a
+`for_testing` engine. `Shipeasy::Client.new(user)` reads `Shipeasy.engine`, so
+stubbing the engine also covers the bound-client path:
 
 ```ruby
 # RSpec
 before do
-  test_client = Shipeasy::SDK::FlagsClient.for_testing
-  test_client.override_flag("new_checkout", true)
-  allow(Shipeasy).to receive(:flags).and_return(test_client)
+  test_engine = Shipeasy::Engine.for_testing
+  test_engine.override_flag("new_checkout", true)
+  allow(Shipeasy).to receive(:engine).and_return(test_engine)
+  allow(Shipeasy).to receive(:flags).and_return(test_engine) # legacy path
+
+  # Shipeasy::Client.new(user).get_flag("new_checkout") now => true
 end
 ```
 
 ## Configuration
 
-| Parameter  | Default                   | Description                         |
-| ---------- | ------------------------- | ----------------------------------- |
-| `api_key`  | (required)                | SDK key from the Shipeasy dashboard |
-| `base_url` | `https://cdn.shipeasy.ai` | Override for local dev / staging    |
+| Parameter    | Default                       | Description                                                         |
+| ------------ | ----------------------------- | ------------------------------------------------------------------- |
+| `api_key`    | (required)                    | SDK key from the Shipeasy dashboard                                 |
+| `base_url`   | `https://edge.shipeasy.dev`   | Override for local dev / staging                                    |
+| `attributes` | identity (`->(u) { u }`)      | Callable mapping your user object → the Shipeasy attribute hash     |
 
 ## Documentation
 

data/lib/shipeasy/client.rb

@@ -0,0 +1,62 @@
+module Shipeasy
+  # A lightweight, user-bound evaluation handle. Construct one per user/request
+  # via its real constructor:
+  #
+  #   flags = Shipeasy::Client.new(current_user)
+  #   flags.get_flag("new_checkout")          # NO user arg — bound at construction
+  #   flags.get_experiment("price_test", { price: 9 })
+  #
+  # It is cheap: it delegates every evaluation to the single global engine built
+  # by `Shipeasy.configure { … }`. It does NOT open its own HTTP connection,
+  # fetch, or start a poll timer.
+  #
+  # The configured `attributes` transform (see Shipeasy::Configuration#attributes)
+  # runs ONCE here, in the constructor, against the raw user object you pass.
+  # The resulting attribute hash is then enriched with the request-scoped
+  # anonymous_id (when you supplied neither user_id nor anonymous_id) and bound,
+  # so every getter reads the same bag.
+  #
+  # Raises if constructed before `Shipeasy.configure` registered an engine.
+  class Client
+    # The resolved attribute hash this handle evaluates against.
+    attr_reader :attributes
+
+    def initialize(user)
+      engine = Shipeasy.engine
+      if engine.nil?
+        raise Error, "Shipeasy::Client.new(user) called before Shipeasy.configure " \
+                     "{ |c| c.api_key = … }. Call Shipeasy.configure once at app boot."
+      end
+      @engine = engine
+      # Run the configured attributes transform (default identity), then apply
+      # the existing anon-id merge exactly as the per-call engine path does.
+      mapped = Shipeasy.attributes_transform.call(user)
+      @attributes = engine.bind_attributes(mapped)
+    end
+
+    def get_flag(name, default: false)
+      @engine.get_flag(name, @attributes, default: default)
+    end
+
+    def get_flag_detail(name)
+      @engine.get_flag_detail(name, @attributes)
+    end
+
+    # Configs are not user-scoped, but exposed here for one-stop ergonomics.
+    def get_config(name, decode = nil, default: nil)
+      @engine.get_config(name, decode, default: default)
+    end
+
+    def get_experiment(name, default_params, decode = nil)
+      @engine.get_experiment(name, @attributes, default_params, decode)
+    end
+
+    # Killswitches are not user-scoped; forwarded straight to the engine.
+    def get_killswitch(name, switch_key = nil)
+      @engine.get_killswitch(name, switch_key)
+    end
+  end
+
+  # Raised by Shipeasy::Client when constructed before Shipeasy.configure.
+  class Error < StandardError; end
+end

data/lib/shipeasy/config.rb

@@ -1,7 +1,7 @@
 # Single configuration object for the Shipeasy gem.
 #
 # Covers both subsystems:
-#   - SDK / experimentation (api_key, base_url) — drives FlagsClient
+#   - SDK / experimentation (api_key, base_url) — drives Engine
 #   - i18n / string manager (public_key, profile, cdn_base_url, ...) — drives
 #     the Rails view helpers and label fetcher
 #
@@ -14,7 +14,7 @@
 #   end
 #
 # Anything not set falls back to the defaults below. The same Shipeasy.config
-# is read by FlagsClient and the Rails helpers, so there is one place to
+# is read by Engine and the Rails helpers, so there is one place to
 # point environment variables at.
 
 module Shipeasy
@@ -22,6 +22,18 @@ module Shipeasy
     # ---- experimentation / SDK ----
     attr_accessor :api_key, :base_url
 
+    # Optional transform from YOUR user object (any shape) to the Shipeasy
+    # attribute hash every flag/experiment evaluation uses. A callable
+    # (lambda/proc or anything responding to #call). Default = identity (the
+    # user object is assumed to already BE the attribute hash). Runs once, in
+    # the Shipeasy::Client constructor.
+    #
+    #   Shipeasy.configure do |c|
+    #     c.api_key    = ENV["SHIPEASY_SERVER_KEY"]
+    #     c.attributes = ->(u) { { "user_id" => u.id, "plan" => u.plan } }
+    #   end
+    attr_accessor :attributes
+
     # ---- i18n / string manager ----
     attr_accessor :public_key, :profile, :default_chunk,
                   :cdn_base_url, :loader_url,
@@ -29,6 +41,7 @@ module Shipeasy
 
     def initialize
       @base_url             = "https://edge.shipeasy.dev"
+      @attributes           = nil
 
       @profile              = "default"
       @default_chunk        = "index"
@@ -45,8 +58,68 @@ module Shipeasy
       @config ||= Configuration.new
     end
 
+    # Configure the gem once at boot. In addition to populating the shared
+    # Configuration, this builds and registers the ONE global Shipeasy::Engine
+    # (first-config-wins) from the api_key/base_url and kicks off its one-shot
+    # fetch (fire-and-forget) so `Shipeasy::Client.new(user).get_flag(...)`
+    # resolves against real rules with no explicit init call.
+    #
+    #   Shipeasy.configure do |c|
+    #     c.api_key    = ENV["SHIPEASY_SERVER_KEY"]
+    #     c.attributes = ->(u) { { "user_id" => u.id, "plan" => u.plan } }
+    #   end
+    #
+    #   Shipeasy::Client.new(current_user).get_flag("new_checkout")
+    #
+    # Long-running servers that also want the background poll can call
+    # `Shipeasy.engine.init` after configure.
     def configure
       yield config
+      register_engine!(config) if config.api_key
+      config
+    end
+
+    # The resolved attributes transform (callable). Default = identity, so a
+    # user object that is already the attribute hash is used verbatim.
+    def attributes_transform
+      transform = config.attributes
+      if transform.nil?
+        ->(user) { user }
+      elsif transform.respond_to?(:call)
+        transform
+      else
+        raise Error, "Shipeasy.configure { |c| c.attributes = … } must be a callable (e.g. a lambda)"
+      end
+    end
+
+    # The single global engine registered by configure, or nil if configure has
+    # not run (or ran without an api_key). Shipeasy::Client reads this.
+    def engine
+      pid = Process.pid
+      if @engine && @engine_pid != pid
+        # Post-fork: the parent's poll thread didn't survive. Rebuild lazily
+        # from the stored config in this child process.
+        @engine = nil
+        register_engine!(config) if config.api_key
+      end
+      @engine
+    end
+
+    # Build + register the one global engine (first-config-wins). Fires the
+    # one-shot fetch fire-and-forget. Idempotent within a process.
+    def register_engine!(cfg)
+      return @engine if @engine && @engine_pid == Process.pid
+      @engine_pid = Process.pid
+      engine = Engine.new(api_key: cfg.api_key, base_url: cfg.base_url)
+      @engine = engine
+      # Capture +engine+ in the closure (not the @engine ivar, which a concurrent
+      # reset/reconfigure could nil out before the thread runs).
+      Thread.new do
+        engine.init_once
+      rescue => e
+        warn "[shipeasy] configure() one-shot fetch failed: #{e.message}"
+      end
+      engine
     end
 
     # Reset the config back to defaults — primarily for tests.
@@ -55,9 +128,12 @@ module Shipeasy
       @flags_pid = nil
       @flags&.destroy
       @flags = nil
+      @engine&.destroy
+      @engine = nil
+      @engine_pid = nil
     end
 
-    # Lazy, fork-safe singleton FlagsClient. The first call from each
+    # Lazy, fork-safe singleton Engine. The first call from each
     # process spawns a fresh client + poll thread — including post-fork
     # workers under Puma's preload_app!. Callers can `Shipeasy.flags.get_flag(...)`
     # straight from a controller without holding a constant or worrying
@@ -70,7 +146,12 @@ module Shipeasy
     #
     # The first request that touches `Shipeasy.flags.*` triggers init().
     # For serverless / Lambda where you want a single fetch with no thread,
-    # build the client explicitly: `Shipeasy::SDK::FlagsClient.new(...).init_once`.
+    # build the engine explicitly: `Shipeasy::Engine.new(...).init_once`.
+    #
+    # NOTE: this remains a separate, polling engine from the one configure()
+    # registers (Shipeasy.engine). New code should prefer the
+    # Shipeasy.configure + Shipeasy::Client.new(user) front door; `Shipeasy.flags`
+    # is retained for the legacy `Shipeasy.flags.get_flag(name, user)` style.
     def flags
       pid = Process.pid
       if @flags && @flags_pid != pid
@@ -81,7 +162,7 @@ module Shipeasy
       end
       @flags ||= begin
         @flags_pid = pid
-        client = SDK::FlagsClient.new(
+        client = Engine.new(
           api_key:  config.api_key,
           base_url: config.base_url,
         )

data/lib/shipeasy/{sdk/flags_client.rb → engine.rb}

@@ -3,15 +3,31 @@ require "uri"
 require "json"
 require "thread"
 require "cgi"
-require_relative "eval"
-require_relative "telemetry"
-require_relative "anon_id"
-require_relative "sticky_store"
-require_relative "see"
+require_relative "sdk/eval"
+require_relative "sdk/telemetry"
+require_relative "sdk/anon_id"
+require_relative "sdk/sticky_store"
+require_relative "sdk/see"
 
 module Shipeasy
-  module SDK
-    class FlagsClient
+  # The heavyweight engine: owns the api key, HTTP transport, the blob cache,
+  # the background poll timer, init/init_once, local overrides, track, and
+  # see()/default-client wiring. Was `Shipeasy::SDK::FlagsClient` before 2.0;
+  # renamed to a clean top-level `Shipeasy::Engine` when the lightweight
+  # user-bound `Shipeasy::Client` became the primary front door.
+  #
+  # Most apps never construct an Engine directly — `Shipeasy.configure { … }`
+  # builds and registers the one global engine for you. Construct one explicitly
+  # only for advanced/serverless flows (multiple keys, offline snapshots).
+  class Engine
+      # Internal collaborators still live under Shipeasy::SDK; alias them so the
+      # body below can keep referring to them unqualified after the class moved
+      # out from under the SDK namespace.
+      Eval      = Shipeasy::SDK::Eval
+      Telemetry = Shipeasy::SDK::Telemetry
+      AnonId    = Shipeasy::SDK::AnonId
+      See       = Shipeasy::SDK::See
+
       DEFAULT_BASE_URL = "https://edge.shipeasy.dev"
       # CDN origin serving the static loader scripts (/sdk/bootstrap.js,
       # /sdk/i18n/loader.js) — distinct from the edge API the blobs are fetched from.
@@ -34,7 +50,7 @@ module Shipeasy
         @sticky_store = sticky_store
         # Test mode: no network, ever. init/init_once/track become no-ops and
         # evaluation answers come purely from local overrides. Built via the
-        # FlagsClient.for_testing factory; see clear_overrides / override_*.
+        # Engine.for_testing factory; see clear_overrides / override_*.
         @test_mode   = test_mode
         # Per-evaluation usage telemetry. ON by default; pass
         # disable_telemetry: true to opt out. See telemetry.rb.
@@ -275,6 +291,28 @@ module Shipeasy
         result
       end
 
+      # Public hook for the bound Shipeasy::Client: normalise an attribute hash
+      # and apply the request-scoped anonymous_id merge ONCE, at Client
+      # construction, exactly as every per-call getter does internally.
+      def bind_attributes(user)
+        with_anon_id(user)
+      end
+
+      # Read a killswitch from the cached flags blob. Without +switch_key+,
+      # returns true when the whole killswitch is killed. With +switch_key+,
+      # returns true when that specific per-key switch is on. Unknown
+      # killswitches / switches return false. Not user-scoped.
+      def get_killswitch(name, switch_key = nil)
+        @telemetry.emit("ks", name)
+        ks = @mutex.synchronize { @flags_blob&.dig("killswitches", name.to_s) }
+        return false unless ks
+        if switch_key.nil?
+          Eval.enabled?(ks["killed"])
+        else
+          Eval.enabled?(ks.dig("switches", switch_key.to_s))
+        end
+      end
+
       # Batch-evaluate every loaded gate, config and experiment for +user+ into
       # a bootstrap payload (+{ "flags" => ..., "configs" => ..., "experiments"
       # => ..., "killswitches" => ... }+) keyed to match the browser SDK's
@@ -576,6 +614,5 @@ module Shipeasy
         http.read_timeout = 10
         http.post(uri.request_uri, body, { "X-SDK-Key" => @api_key, "Content-Type" => "text/plain" })
       end
-    end
   end
 end

data/lib/shipeasy/sdk/anon_id.rb

@@ -33,7 +33,7 @@ module Shipeasy
       end
 
       # The anon id RackMiddleware resolved for the current request, or nil when
-      # no middleware ran (e.g. a background job). FlagsClient falls back to this
+      # no middleware ran (e.g. a background job). The Engine falls back to this
       # as the default anonymous_id, so evaluations need no per-call wiring.
       def current
         Thread.current[THREAD_KEY]

data/lib/shipeasy/sdk/openfeature.rb

@@ -11,7 +11,7 @@
 #   require "open_feature/sdk"
 #   require "shipeasy/sdk/openfeature"
 #
-#   client = Shipeasy::SDK::FlagsClient.new(api_key: ENV.fetch("SHIPEASY_SERVER_KEY"))
+#   client = Shipeasy::Engine.new(api_key: ENV.fetch("SHIPEASY_SERVER_KEY"))
 #   client.init
 #
 #   OpenFeature::SDK.configure do |config|
@@ -22,7 +22,7 @@
 #   on = of.fetch_boolean_value(flag_key: "new_checkout", default_value: false,
 #                               evaluation_context: OpenFeature::SDK::EvaluationContext.new(targeting_key: "u1"))
 #
-# Pure adapter over `FlagsClient` — no change to evaluation. Boolean values map
+# Pure adapter over `Shipeasy::Engine` — no change to evaluation. Boolean values map
 # onto gates (`get_flag_detail`); string/number/integer/float/object map onto
 # dynamic configs (`get_config`).
 
@@ -37,12 +37,12 @@ rescue LoadError => e
                    "gem \"openfeature-sdk\". (#{e.message})"
 end
 
-require_relative "flags_client"
+require_relative "../engine"
 
 module Shipeasy
   module OpenFeature
     # Shipeasy OpenFeature provider (server paradigm). Wraps a
-    # `Shipeasy::SDK::FlagsClient`; evaluation is local against the cached blob,
+    # `Shipeasy::Engine`; evaluation is local against the cached blob,
     # so resolution is effectively synchronous.
     class Provider
       OF = ::OpenFeature::SDK::Provider
@@ -56,12 +56,12 @@ module Shipeasy
       #   FLAG_NOT_FOUND   → ERROR (error_code FLAG_NOT_FOUND)
       #   CLIENT_NOT_READY → ERROR (error_code PROVIDER_NOT_READY)
       REASON_MAP = {
-        Shipeasy::SDK::FlagsClient::REASON_RULE_MATCH       => [OF::Reason::TARGETING_MATCH, nil],
-        Shipeasy::SDK::FlagsClient::REASON_DEFAULT          => [OF::Reason::DEFAULT, nil],
-        Shipeasy::SDK::FlagsClient::REASON_OFF              => [OF::Reason::DISABLED, nil],
-        Shipeasy::SDK::FlagsClient::REASON_OVERRIDE         => [OF::Reason::STATIC, nil],
-        Shipeasy::SDK::FlagsClient::REASON_FLAG_NOT_FOUND   => [OF::Reason::ERROR, OF::ErrorCode::FLAG_NOT_FOUND],
-        Shipeasy::SDK::FlagsClient::REASON_CLIENT_NOT_READY => [OF::Reason::ERROR, OF::ErrorCode::PROVIDER_NOT_READY],
+        Shipeasy::Engine::REASON_RULE_MATCH       => [OF::Reason::TARGETING_MATCH, nil],
+        Shipeasy::Engine::REASON_DEFAULT          => [OF::Reason::DEFAULT, nil],
+        Shipeasy::Engine::REASON_OFF              => [OF::Reason::DISABLED, nil],
+        Shipeasy::Engine::REASON_OVERRIDE         => [OF::Reason::STATIC, nil],
+        Shipeasy::Engine::REASON_FLAG_NOT_FOUND   => [OF::Reason::ERROR, OF::ErrorCode::FLAG_NOT_FOUND],
+        Shipeasy::Engine::REASON_CLIENT_NOT_READY => [OF::Reason::ERROR, OF::ErrorCode::PROVIDER_NOT_READY],
       }.freeze
 
       attr_reader :metadata

data/lib/shipeasy/sdk/version.rb

@@ -1,5 +1,5 @@
 module Shipeasy
   module SDK
-    VERSION = "1.7.0"
+    VERSION = "2.0.0"
   end
 end

data/lib/shipeasy-sdk.rb

@@ -3,7 +3,8 @@ require_relative "shipeasy/config"
 require_relative "shipeasy/sdk/murmur3"
 require_relative "shipeasy/sdk/eval"
 require_relative "shipeasy/sdk/sticky_store"
-require_relative "shipeasy/sdk/flags_client"
+require_relative "shipeasy/engine"
+require_relative "shipeasy/client"
 require_relative "shipeasy/sdk/anon_id"
 require_relative "shipeasy/sdk/rack_middleware"
 require_relative "shipeasy/i18n/label_fetcher"
@@ -19,16 +20,16 @@ end
 
 module Shipeasy
   module SDK
-    # Convenience constructor. Reads api_key + base_url from the gem-wide
-    # config when omitted, so a single `Shipeasy.configure { … }` block at
-    # boot is enough.
+    # Convenience constructor for a heavyweight Engine. Reads api_key + base_url
+    # from the gem-wide config when omitted. Most apps should prefer
+    # `Shipeasy.configure { … }` + `Shipeasy::Client.new(user)` instead.
     def self.new_client(api_key: Shipeasy.config.api_key, base_url: Shipeasy.config.base_url)
-      FlagsClient.new(api_key: api_key, base_url: base_url)
+      Shipeasy::Engine.new(api_key: api_key, base_url: base_url)
     end
 
     # ---- see() module-level facade --------------------------------------
     #
-    # Backed by a default client, registered when a FlagsClient is constructed
+    # Backed by a default client, registered when an Engine is constructed
     # (last constructed wins). Mirrors the package-level see() in the TS/Python
     # SDKs so callers can `Shipeasy::SDK.see(e).causes_the(...).to(...)` without
     # threading a client reference through every call site. A call before any
@@ -38,7 +39,7 @@ module Shipeasy
     @see_default_mutex  = Mutex.new
 
     # Register the client backing the module-level see() funcs. Called
-    # automatically from FlagsClient#initialize; also exposed for explicit use.
+    # automatically from Engine#initialize; also exposed for explicit use.
     def self.set_default_client(client)
       @see_default_mutex.synchronize { @see_default_client = client }
       client

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: shipeasy-sdk
 version: !ruby/object:Gem::Version
-  version: 1.7.0
+  version: 2.0.0
 platform: ruby
 authors:
 - Shipeasy, Inc.
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-06-20 00:00:00.000000000 Z
+date: 2026-06-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
@@ -65,13 +65,14 @@ files:
 - LICENSE
 - README.md
 - lib/shipeasy-sdk.rb
+- lib/shipeasy/client.rb
 - lib/shipeasy/config.rb
+- lib/shipeasy/engine.rb
 - lib/shipeasy/i18n/label_fetcher.rb
 - lib/shipeasy/i18n/railtie.rb
 - lib/shipeasy/i18n/view_helpers.rb
 - lib/shipeasy/sdk/anon_id.rb
 - lib/shipeasy/sdk/eval.rb
-- lib/shipeasy/sdk/flags_client.rb
 - lib/shipeasy/sdk/murmur3.rb
 - lib/shipeasy/sdk/openfeature.rb
 - lib/shipeasy/sdk/rack_middleware.rb