shipeasy-sdk 1.6.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 73c3a9cf2fd1a6fb0a223b9db5bcbe13cd828bfd96a4e901de545ff56d254ce7
-  data.tar.gz: '0489c3e16d16592b1301e888c82fa1d5947c21c08c74adbd9eacb6db86420138'
+  metadata.gz: 97efde389fa7a5adc1ffdab3951d09837f435bd529d8f6c3b7e3d45387472628
+  data.tar.gz: 46f183776d94ccbddd8781e39d3ea5e56e6795cf26f3292f1482c2886b7d0836
 SHA512:
-  metadata.gz: 9f2a91c5482d5eb3baf71e744116b7295ad50b19cea9a96c2ce6b6faa01467a38ca4db91f449ae773de76144156eaeec14052d14d12f3c68a3dc521fa1c6813b
-  data.tar.gz: b8e2512bbc85e404fa4528c411700bff22e7eea40f20be2d6392bd7f59166eb65464cfe17760f8b7a2f56c0eb2c7ca15a42fbc579c0937f04ce61c402824a862
+  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
@@ -115,6 +138,31 @@ client.init
 at_exit { client.destroy }
 ```
 
+## Server-side rendering (SSR)
+
+Emit the request's evaluated flags as a declarative `<script>` tag so the
+browser SDK has them on first paint. `bootstrap_script_tag` carries the payload
+in `data-*` attributes (**no key**); the static `se-bootstrap.js` loader
+hydrates `window.__SE_BOOTSTRAP` and writes the `__se_anon_id` cookie so the
+browser buckets identically to the server.
+
+```ruby
+user = { "user_id" => "u_123" }
+
+# Two tags for the document <head>. The PUBLIC client key (not the server
+# key) goes on the i18n loader tag.
+head = client.bootstrap_script_tag(user, anon_id: anon_id) +
+       client.i18n_script_tag(client_key, profile: "en:prod")
+
+# …or get the raw payload ({ "flags", "configs", "experiments", "killswitches" }):
+boot = client.evaluate(user)
+```
+
+`bootstrap_script_tag` also accepts `i18n_profile:` and `base_url:` (defaults to
+`https://cdn.shipeasy.ai`). In **Rails**, the existing
+`Shipeasy::I18n::ViewHelpers#i18n_script_tag` view helper still renders the i18n
+loader tag from your app config.
+
 ## Default values
 
 `get_flag` and `get_config` take an optional `default:` returned **only when the
@@ -181,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, {})
@@ -210,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:
@@ -218,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)
@@ -247,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}

@@ -2,16 +2,36 @@ require "net/http"
 require "uri"
 require "json"
 require "thread"
-require_relative "eval"
-require_relative "telemetry"
-require_relative "anon_id"
-require_relative "sticky_store"
-require_relative "see"
+require "cgi"
+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.
+      DEFAULT_CDN_BASE = "https://cdn.shipeasy.ai"
 
       def initialize(api_key:, base_url: nil, env: "prod", disable_telemetry: false, telemetry_url: nil, test_mode: false, private_attributes: nil, sticky_store: nil)
         @api_key     = api_key
@@ -30,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.
@@ -271,6 +291,93 @@ 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
+      # window.__SE_BOOTSTRAP shape. Local overrides win. Killswitches are folded
+      # into per-gate evaluation, so the standalone +killswitches+ map is empty
+      # for this SDK. No telemetry (a batch evaluate is not a per-flag exposure).
+      def evaluate(user)
+        u = with_anon_id(user)
+        flags_blob, exps_blob, flag_ov, config_ov, exp_ov, sticky = @mutex.synchronize do
+          [@flags_blob, @exps_blob, @flag_overrides.dup, @config_overrides.dup,
+           @exp_overrides.dup, @sticky_store]
+        end
+
+        flags = {}
+        (flags_blob&.dig("gates") || {}).each do |name, gate|
+          flags[name] = flag_ov.key?(name) ? flag_ov[name] : Eval.eval_gate(gate, u)
+        end
+
+        configs = {}
+        (flags_blob&.dig("configs") || {}).each do |name, entry|
+          configs[name] = config_ov.key?(name) ? config_ov[name] : entry["value"]
+        end
+
+        experiments = {}
+        (exps_blob&.dig("experiments") || {}).each do |name, exp|
+          if exp_ov.key?(name)
+            ov = exp_ov[name]
+            experiments[name] = { "inExperiment" => true, "group" => ov[:group], "params" => ov[:params] }
+            next
+          end
+          r = Eval.eval_experiment(exp, flags_blob, exps_blob, u, exp_name: name, sticky_store: sticky)
+          experiments[name] = { "inExperiment" => r.in_experiment, "group" => r.group, "params" => r.params }
+        end
+
+        { "flags" => flags, "configs" => configs, "experiments" => experiments, "killswitches" => {} }
+      end
+
+      # Return the cross-platform SSR bootstrap <script> tag for a request:
+      # se-bootstrap.js reads its data-* attributes and hydrates
+      # window.__SE_BOOTSTRAP (and writes the anon cookie). No key is embedded.
+      def bootstrap_script_tag(user, anon_id: nil, i18n_profile: "en:prod", base_url: nil)
+        payload = evaluate(user)
+        base = cdn_base(base_url)
+        attrs = [
+          "data-se-bootstrap",
+          attr("data-flags", JSON.generate(payload["flags"])),
+          attr("data-configs", JSON.generate(payload["configs"])),
+          attr("data-experiments", JSON.generate(payload["experiments"])),
+          attr("data-killswitches", JSON.generate(payload["killswitches"])),
+          attr("data-i18n-profile", i18n_profile || "en:prod"),
+          attr("data-api-url", base),
+        ]
+        attrs << attr("data-anon-id", anon_id) if anon_id && !anon_id.empty?
+        %(<script src="#{CGI.escapeHTML("#{base}/sdk/bootstrap.js")}" #{attrs.join(' ')}></script>)
+      end
+
+      # Return the i18n loader <script> tag (framework-agnostic; the Rails view
+      # helper Shipeasy::I18n::ViewHelpers#i18n_script_tag is separate). The
+      # loader fetches translations for the profile using the PUBLIC client key.
+      def i18n_script_tag(client_key, profile: "en:prod", base_url: nil)
+        base = cdn_base(base_url)
+        %(<script src="#{CGI.escapeHTML("#{base}/sdk/i18n/loader.js")}" ) +
+          %(#{attr('data-key', client_key)} #{attr('data-profile', profile || 'en:prod')}></script>)
+      end
+
       def track(user_id, event_name, props = {})
         return if @test_mode
 
@@ -427,6 +534,14 @@ module Shipeasy
         v.nil? || v == ""
       end
 
+      def cdn_base(override)
+        (override && !override.empty? ? override : DEFAULT_CDN_BASE).chomp("/")
+      end
+
+      def attr(name, value)
+        %(#{name}="#{CGI.escapeHTML(value.to_s)}")
+      end
+
       def start_poll
         @timer = Thread.new do
           loop do
@@ -499,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.6.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.6.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