shipeasy-sdk 1.0.0 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4eafaff1d5be1131bb55a64dbbb1653ee18f2a5a9e22cd83a45bb92de7bcfcb6
-  data.tar.gz: 4b59ebf58017deb5def949f46235d53f6ca60320400ac72ada320eff92d7e5d5
+  metadata.gz: bacc8b94c722361a53df3156e4dc63159c75b0657e2c1f6ae246593e90cf7c12
+  data.tar.gz: 4450034aaee670f04015f396a960646fff27e5195e13ebd93ace4c032a82f023
 SHA512:
-  metadata.gz: cb3f19e0215c65fed6db82a1ef181949ef0cb666a25e02e67103b6840bc79ee3e855e9f784a99f03d9ca54c73a74f431e3d16fd90fca29561317ab4b80b200f0
-  data.tar.gz: 480ac5a6fdeaef418e34488a668e4431bafa392a54d7e8eae7373541a48d401bdb687408e0759f6269c7263c9d38a11b4b4877930df65b4cd7bde859472b0eca
+  metadata.gz: cff2bbf433472f1e2be585ccbf5deb12d420e29130bb8f09961f2b277135a0c1726c1318a0f1b7b57fce511b114b6fcde982cc0735b884bb946de46016638c52
+  data.tar.gz: 1ff69897f3b0501e6c4e41fa5eb386017fc4d714a0a5423871ec867b969bea2d1097fda01fb3902b1a57bc37a0490aaf433169e9d829f11739f3ac63cbcabb56

data/LICENSE

@@ -0,0 +1,40 @@
+Shipeasy Source-Available License (Shipeasy-SAL) 1.0
+
+Copyright (c) 2026 Shipeasy, Inc. All rights reserved.
+
+1. License Grant.
+   Subject to the terms of this License, Shipeasy, Inc. ("Shipeasy") grants
+   you a non-exclusive, non-transferable, revocable, worldwide license to:
+
+   (a) Use, copy, and modify the Software solely as a client integration for
+       interacting with Shipeasy's hosted services (the "Service");
+   (b) Distribute the Software as part of an application that calls the
+       Service, in object form, provided the recipient also agrees to this
+       License.
+
+2. Restrictions.
+   You may not:
+
+   (a) Use the Software, in whole or in part, to build, host, or operate any
+       service that competes with the Service or that provides feature-flag,
+       experimentation, configuration, internationalization, or related
+       functionality to third parties on a commercial basis;
+   (b) Sublicense, sell, rent, or lease the Software;
+   (c) Remove or alter copyright notices, license terms, or attribution.
+
+3. Contributions.
+   Any pull request you submit is licensed back to Shipeasy under this
+   License plus a perpetual, irrevocable right for Shipeasy to relicense.
+
+4. Trademarks.
+   This License does not grant rights in the names "Shipeasy", related
+   marks, or logos.
+
+5. No Warranty / Limitation of Liability.
+   THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND. IN NO
+   EVENT SHALL SHIPEASY BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER
+   LIABILITY ARISING FROM USE OF THE SOFTWARE.
+
+6. Termination.
+   This License terminates automatically if you breach it. Sections 2-5
+   survive termination.

data/README.md

@@ -1,61 +1,283 @@
-# shipeasy-sdk
+# shipeasy-sdk (Ruby)
 
-Ruby SDK for the ShipEasy experiment platform. Evaluates feature flags and A/B experiments locally against blobs polled from the ShipEasy edge worker.
+Ruby gem for the [Shipeasy](https://shipeasy.ai) hosted service. Server-side
+gate evaluation, runtime configs, experiments, and metric ingestion.
 
-## Installation
+> Source-available under the [Shipeasy-SAL 1.0](./LICENSE).
+
+## Install
 
 ```ruby
 # Gemfile
 gem "shipeasy-sdk"
 ```
 
-## Quick start
+## Quickstart (Rails)
+
+`config/initializers/shipeasy.rb` is all you need:
 
 ```ruby
-require "shipeasy-sdk"
+Shipeasy.configure do |c|
+  c.api_key    = ENV.fetch("SHIPEASY_SERVER_KEY")
+  c.public_key = ENV.fetch("SHIPEASY_CLIENT_KEY")  # for i18n view helpers
+  c.profile    = "default"
+end
+```
 
-client = Shipeasy::SDK.new_client(api_key: "sdk_live_xxxxx")
-client.init   # fetches flags/experiments + starts background polling thread
+Anywhere in your app:
 
-user = { user_id: "usr_123", plan: "pro", country: "US" }
+```ruby
+user = { user_id: current_user.id, plan: current_user.plan }
 
-# Feature flag
-if client.get_flag("new_checkout", user)
-  # show new checkout
+if Shipeasy.flags.get_flag("new_checkout", user)
+  # ship it
 end
 
-# Remote config
-color = client.get_config("button_color")   # => "blue" (raw value)
+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 })
+```
+
+`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.
+
+In a Rails view (the railtie auto-mounts these helpers when Rails is loaded):
+
+```erb
+<%= i18n_head_tags %>
+<h1><%= i18n_t("hero.title", name: current_user.name) %></h1>
+```
+
+### Anonymous visitors (zero-config bucketing)
+
+For logged-out traffic you need a *stable* unit so a fractional rollout buckets
+the same on the server and in the browser. In Rails this is automatic: a Railtie
+mounts `Shipeasy::SDK::RackMiddleware`, which mints the shared `__se_anon_id`
+first-party cookie (read + written by every Shipeasy SDK, including the browser)
+for any request without one. Evaluations then default to it with **no per-call
+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", {})
+```
+
+An explicit `user_id` / `anonymous_id` always wins. If you prefer to read the id
+yourself it's also on the Rack env as `request.env["shipeasy.anon_id"]`. The
+cookie is non-`HttpOnly` by design so the browser SDK can bucket identically. A
+request with **no** unit still resolves a fully-rolled (100%) gate as on; only
+fractional gates need the id. Cookie name + format are a cross-SDK contract —
+see `18-identity-bucketing.md`.
+
+For **Sinatra / Hanami / bare Rack** (no Railtie), mount it yourself:
+
+```ruby
+use Shipeasy::SDK::RackMiddleware
+```
+
+## Quickstart (plain Ruby / Sinatra / Hanami / scripts)
+
+Same pattern, just without `config/initializers`:
+
+```ruby
+require "shipeasy-sdk"
+
+Shipeasy.configure { |c| c.api_key = ENV.fetch("SHIPEASY_SERVER_KEY") }
+
+Shipeasy.flags.get_flag("new_checkout", { user_id: "u_1" })
+```
+
+The Rails view helpers (`i18n_*`) are not loaded outside Rails, so the
+gem doesn't pull Rails into Sinatra/Hanami apps.
+
+## Lambda / Cloud Run / serverless
+
+Skip the auto-init facade — it spawns a poll thread you don't want in a
+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)
+```
+
+## Lifecycle escape hatch
+
+If you want explicit shutdown control in a long-running worker, build the
+client yourself and skip the singleton:
+
+```ruby
+client = Shipeasy::SDK.new_client     # reads api_key + base_url from Shipeasy.config
+client.init
+at_exit { client.destroy }
+```
+
+## Default values
+
+`get_flag` and `get_config` take an optional `default:` returned **only when the
+value cannot be resolved** — never when a flag genuinely evaluates to `false`.
 
-# A/B experiment
-result = client.get_experiment("checkout_cta", user, { label: "Buy now" })
-puts result.in_experiment  # true/false
-puts result.group          # "control" | "treatment"
-puts result.params         # { "label" => "Checkout" }
+```ruby
+# Flag: default is returned only when the client isn't ready yet (no blob
+# fetched) or the gate doesn't exist. A gate that evaluates to false (disabled,
+# or outside its rollout) returns false, NOT the default.
+Shipeasy.flags.get_flag("new_checkout", user, default: true)
+
+# Config: default is returned when the config key is absent. A decode proc still
+# runs on a present value.
+Shipeasy.flags.get_config("button_color", default: "blue")
+Shipeasy.flags.get_config("limits", ->(v) { v["max"] }, default: 0)
+```
 
-# Track a metric event (fire-and-forget background thread)
-client.track("usr_123", "checkout_completed", { revenue: 49.99 })
+## Evaluation detail
 
-# Shutdown (stops background poll thread)
-client.destroy
+`get_flag_detail(name, user)` returns the boolean **and the reason** it was
+reached, as a `FlagDetail` struct (`.value`, `.reason`). `get_flag` is built on
+top of it. The reason is one of the `REASON_*` constants:
+
+| Reason             | Meaning                                              |
+| ------------------ | --------------------------------------------------- |
+| `OVERRIDE`         | answered by a local `override_flag` (no telemetry)  |
+| `CLIENT_NOT_READY` | no flag blob fetched/loaded yet                     |
+| `FLAG_NOT_FOUND`   | blob present, but this gate isn't in it             |
+| `OFF`              | gate present but disabled or killswitched           |
+| `RULE_MATCH`       | evaluated to `true`                                 |
+| `DEFAULT`          | evaluated to `false` (rollout/rule)                 |
+
+```ruby
+detail = Shipeasy.flags.get_flag_detail("new_checkout", user)
+detail.value   # => true / false
+detail.reason  # => "RULE_MATCH" / "DEFAULT" / "OFF" / ...
 ```
 
-## init vs init_once
+The `gate` usage beacon fires exactly once per `get_flag_detail` call (never on
+the `OVERRIDE` short-circuit).
+
+## Change listeners
+
+`on_change` registers a callback fired after a background poll fetches **new**
+flag/config data (HTTP 200, not a 304). It accepts a block or any callable and
+returns an unsubscribe proc. Listeners never fire in test/offline mode (there is
+no poll thread). A raising listener is isolated and logged, not propagated.
+
+```ruby
+unsubscribe = Shipeasy.flags.on_change { reload_local_cache! }
+# ... later
+unsubscribe.call
+```
 
-- `init` — fetches data, marks initialized, starts the background poll thread. Call once at app boot.
-- `init_once` — same as `init` but is a no-op if already initialized. Safe to call multiple times (e.g. in middleware).
+## Offline snapshot
+
+For CI, air-gapped runs, or reproducing a production decision from a captured
+blob, build a **no-network** client that still runs the real evaluator against a
+snapshot. The snapshot JSON holds the raw response bodies of the two SDK
+endpoints:
+
+```json
+{ "flags": <body of /sdk/flags>, "experiments": <body of /sdk/experiments> }
+```
+
+```ruby
+client = Shipeasy::SDK::FlagsClient.from_file("snapshot.json")
+# or, from already-parsed blobs:
+client = Shipeasy::SDK::FlagsClient.from_snapshot(flags: flags_body, experiments: exps_body)
+
+client.get_flag("new_checkout", user)        # real evaluation, no network
+client.get_experiment("checkout_cta", user, {})
+```
+
+`init` / `init_once` / `track` are no-ops and telemetry is off (it reuses the
+`for_testing` plumbing). Local `override_*` setters still apply on top of the
+snapshot.
 
 ## Evaluation details
 
-- **Gates** — rules matched in order; rollout bucket computed as `murmur3("#{salt}:#{uid}") % 10000 < rolloutPct`.
-- **Experiments** — checks `status == "running"`, optional targeting gate, universe holdout range, allocation bucket, then group assignment by weight.
-- **MurmurHash3** — pure Ruby implementation, x86_32 variant, seed 0.
-- **ETag caching** — each poll sends `If-None-Match`; a `304` response skips the JSON parse.
-- **Poll interval** — initial default 30 s; overridden by `X-Poll-Interval` response header from the flags endpoint.
+- **Gates** — rules matched in order; rollout bucket =
+  `murmur3("#{salt}:#{uid}") % 10000 < rollout_pct`.
+- **Experiments** — `status == "running"`, optional targeting gate,
+  universe holdout range, allocation bucket, then group assignment by
+  weight.
+- **MurmurHash3** — pure-Ruby x86_32 variant, seed 0.
+- **ETag caching** — each poll sends `If-None-Match`; a 304 skips the
+  JSON parse.
+- **Poll interval** — defaults to 30 s; overridden by the
+  `X-Poll-Interval` header from the flags endpoint.
+
+## Testing
+
+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
+seed each entity with the `override_*` setters (Statsig-style local overrides).
+An override always wins over the fetched blob, so the getters answer
+deterministically:
+
+```ruby
+require "shipeasy-sdk"
+
+client = Shipeasy::SDK::FlagsClient.for_testing
+# init / init_once are no-ops here — nothing is ever fetched.
+
+# Flags (boolean)
+client.override_flag("new_checkout", true)
+client.get_flag("new_checkout", { user_id: "u_1" })   # => true
+
+# Configs (any value; an optional decode proc still runs)
+client.override_config("button_color", "blue")
+client.get_config("button_color")                     # => "blue"
+client.override_config("limits", { "max" => 10 })
+client.get_config("limits", ->(v) { v["max"] })       # => 10
+
+# Experiments — returns an in-experiment Eval::ExperimentResult
+client.override_experiment("checkout_cta", "treatment", { label: "Buy now" })
+r = client.get_experiment("checkout_cta", { user_id: "u_1" }, { label: "default" })
+r.in_experiment   # => true
+r.group           # => "treatment"
+r.params          # => { label: "Buy now" }
+
+# track is a no-op (no thread, no network) — assert call counts without stubbing.
+client.track("u_1", "checkout_completed", { revenue: 49.99 })  # => nil
+
+# Reset between examples
+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
+rest comes from the fetched blob.
+
+### Rails singleton
+
+`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:
+
+```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)
+end
+```
 
 ## Configuration
 
-| Parameter  | Default                        | Description                       |
-|------------|--------------------------------|-----------------------------------|
-| `api_key`  | (required)                     | SDK key from the ShipEasy dashboard |
-| `base_url` | `https://edge.shipeasy.dev`    | Override for local dev / staging  |
+| Parameter  | Default                   | Description                         |
+| ---------- | ------------------------- | ----------------------------------- |
+| `api_key`  | (required)                | SDK key from the Shipeasy dashboard |
+| `base_url` | `https://cdn.shipeasy.ai` | Override for local dev / staging    |
+
+## Documentation
+
+[docs.shipeasy.ai](https://docs.shipeasy.ai)
+
+## License
+
+[Shipeasy-SAL 1.0](./LICENSE) — source-available, non-commercial-use,
+permitted as a Shipeasy client.

data/lib/shipeasy/config.rb

@@ -0,0 +1,93 @@
+# Single configuration object for the Shipeasy gem.
+#
+# Covers both subsystems:
+#   - SDK / experimentation (api_key, base_url) — drives FlagsClient
+#   - i18n / string manager (public_key, profile, cdn_base_url, ...) — drives
+#     the Rails view helpers and label fetcher
+#
+# Usage:
+#
+#   Shipeasy.configure do |c|
+#     c.api_key    = ENV["SHIPEASY_SERVER_KEY"]
+#     c.public_key = ENV["SHIPEASY_CLIENT_KEY"]
+#     c.profile    = "default"
+#   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
+# point environment variables at.
+
+module Shipeasy
+  class Configuration
+    # ---- experimentation / SDK ----
+    attr_accessor :api_key, :base_url
+
+    # ---- i18n / string manager ----
+    attr_accessor :public_key, :profile, :default_chunk,
+                  :cdn_base_url, :loader_url,
+                  :manifest_cache_ttl, :label_file_cache_ttl, :http_timeout
+
+    def initialize
+      @base_url             = "https://edge.shipeasy.dev"
+
+      @profile              = "default"
+      @default_chunk        = "index"
+      @cdn_base_url         = "https://cdn.i18n.shipeasy.ai"
+      @loader_url           = "https://cdn.i18n.shipeasy.ai/loader.js"
+      @manifest_cache_ttl   = 60
+      @label_file_cache_ttl = 3600
+      @http_timeout         = 1
+    end
+  end
+
+  class << self
+    def config
+      @config ||= Configuration.new
+    end
+
+    def configure
+      yield config
+    end
+
+    # Reset the config back to defaults — primarily for tests.
+    def reset_config!
+      @config = nil
+      @flags_pid = nil
+      @flags&.destroy
+      @flags = nil
+    end
+
+    # Lazy, fork-safe singleton FlagsClient. 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
+    # about `before_worker_boot` hooks.
+    #
+    # Initializers stay minimal:
+    #
+    #   # config/initializers/shipeasy.rb
+    #   Shipeasy.configure { |c| c.api_key = ENV["SHIPEASY_SERVER_KEY"] }
+    #
+    # 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`.
+    def flags
+      pid = Process.pid
+      if @flags && @flags_pid != pid
+        # Post-fork: parent's poll thread didn't survive. Don't destroy
+        # @flags (its mutex/state is invalid in this child anyway); just
+        # rebuild from scratch.
+        @flags = nil
+      end
+      @flags ||= begin
+        @flags_pid = pid
+        client = SDK::FlagsClient.new(
+          api_key:  config.api_key,
+          base_url: config.base_url,
+        )
+        client.init
+        client
+      end
+    end
+  end
+end

data/lib/shipeasy/i18n/label_fetcher.rb

@@ -0,0 +1,66 @@
+require "net/http"
+require "uri"
+require "json"
+require "digest"
+
+module Shipeasy
+  module I18n
+    class LabelFetcher
+      MANIFEST_KEY_PREFIX = "i18n:manifest:"
+      LABEL_KEY_PREFIX    = "i18n:label:"
+
+      def initialize(config = Shipeasy.config)
+        @config = config
+      end
+
+      def fetch(profile: @config.profile, chunk: @config.default_chunk)
+        manifest = fetch_manifest(profile)
+        return nil unless manifest
+
+        file_url = manifest[chunk]
+        return nil unless file_url
+
+        fetch_label_file(file_url)
+      rescue => e
+        ::Rails.logger.warn("[Shipeasy::I18n] Failed to fetch labels: #{e.message}") if defined?(::Rails)
+        nil
+      end
+
+      private
+
+      def fetch_manifest(profile)
+        cache_key = "#{MANIFEST_KEY_PREFIX}#{@config.public_key}:#{profile}"
+        cache_fetch(cache_key, @config.manifest_cache_ttl) do
+          url = "#{@config.cdn_base_url}/labels/#{@config.public_key}/#{profile}/manifest.json"
+          http_get_json(url)
+        end
+      end
+
+      def fetch_label_file(url)
+        cache_key = "#{LABEL_KEY_PREFIX}#{Digest::MD5.hexdigest(url)}"
+        cache_fetch(cache_key, @config.label_file_cache_ttl) do
+          http_get_json(url)
+        end
+      end
+
+      def cache_fetch(key, ttl, &block)
+        if defined?(::Rails) && ::Rails.cache
+          ::Rails.cache.fetch(key, expires_in: ttl.seconds, &block)
+        else
+          block.call
+        end
+      end
+
+      def http_get_json(url)
+        uri  = URI.parse(url)
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl      = (uri.scheme == "https")
+        http.open_timeout = @config.http_timeout
+        http.read_timeout = @config.http_timeout
+        res  = http.get(uri.request_uri, { "Accept" => "application/json" })
+        raise "HTTP #{res.code} fetching #{url}" unless res.is_a?(Net::HTTPSuccess)
+        JSON.parse(res.body)
+      end
+    end
+  end
+end

data/lib/shipeasy/i18n/railtie.rb

@@ -0,0 +1,14 @@
+module Shipeasy
+  module I18n
+    # Auto-mounts ViewHelpers into ActionView when the gem is loaded inside
+    # a Rails app. Skipped silently when ::Rails isn't defined (plain Ruby
+    # consumers of the SDK never see the i18n surface).
+    class Railtie < ::Rails::Railtie
+      initializer "shipeasy.i18n.view_helpers" do
+        ActiveSupport.on_load(:action_view) do
+          include Shipeasy::I18n::ViewHelpers
+        end
+      end
+    end
+  end
+end

data/lib/shipeasy/i18n/view_helpers.rb

@@ -0,0 +1,49 @@
+module Shipeasy
+  module I18n
+    module ViewHelpers
+      def i18n_head_tags(profile: nil, chunk: nil)
+        safe_join([
+          i18n_inline_data(profile: profile, chunk: chunk),
+          i18n_script_tag,
+        ], "\n")
+      end
+
+      def i18n_inline_data(profile: nil, chunk: nil)
+        config = Shipeasy.config
+        label_file = Shipeasy::I18n::LabelFetcher.new.fetch(
+          profile: profile || config.profile,
+          chunk:   chunk   || config.default_chunk,
+        )
+        return "".html_safe unless label_file
+
+        json_content = JSON.generate(label_file)
+        content_tag(:script, json_content.html_safe, id: "i18n-data", type: "application/json")
+      end
+
+      def i18n_script_tag(hide_until_ready: false)
+        config = Shipeasy.config
+        attrs  = {
+          src: config.loader_url,
+          "data-key":     config.public_key,
+          "data-profile": config.profile,
+          async: true,
+        }
+        attrs[:"data-hide-until-ready"] = "true" if hide_until_ready
+        tag(:script, attrs)
+      end
+
+      def i18n_t(key, variables = {}, profile: nil, chunk: nil)
+        config = Shipeasy.config
+        label_file = Shipeasy::I18n::LabelFetcher.new.fetch(
+          profile: profile || config.profile,
+          chunk:   chunk   || config.default_chunk,
+        )
+        return key unless label_file && label_file["strings"]
+
+        value = label_file["strings"][key] || key
+        variables.each { |k, v| value = value.gsub("{{#{k}}}", v.to_s) }
+        value
+      end
+    end
+  end
+end

data/lib/shipeasy/sdk/anon_id.rb

@@ -0,0 +1,47 @@
+require "securerandom"
+
+module Shipeasy
+  module SDK
+    # Anonymous bucketing identity — the cross-SDK `__se_anon_id` cookie.
+    #
+    # Gates and experiments bucket a unit with murmur3(salt:unit). For a
+    # logged-out visitor the unit is a stable anonymous id carried in a single
+    # first-party cookie that EVERY Shipeasy SDK (server + browser) reads and
+    # writes, so a server render and the browser bucket a fractional rollout
+    # identically. The cookie name + format are frozen across every language;
+    # see experiment-platform/18-identity-bucketing.md.
+    module AnonId
+      COOKIE  = "__se_anon_id".freeze
+      MAX_AGE = 31_536_000 # 1 year, in seconds
+
+      # The cookie value is client-controllable and feeds bucketing, so a
+      # tampered value is treated as absent and a fresh id is minted. UUIDs
+      # satisfy this charset.
+      VALID_RX = /\A[A-Za-z0-9_-]{1,64}\z/.freeze
+
+      THREAD_KEY = :shipeasy_anon_id
+
+      module_function
+
+      # A fresh opaque bucketing id (UUIDv4).
+      def mint
+        SecureRandom.uuid
+      end
+
+      def valid?(value)
+        value.is_a?(String) && VALID_RX.match?(value)
+      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
+      # as the default anonymous_id, so evaluations need no per-call wiring.
+      def current
+        Thread.current[THREAD_KEY]
+      end
+
+      def current=(value)
+        Thread.current[THREAD_KEY] = value
+      end
+    end
+  end
+end

data/lib/shipeasy/sdk/eval.rb

@@ -66,7 +66,12 @@ module Shipeasy
         end
 
         uid = user["user_id"] || user[:user_id] || user["anonymous_id"] || user[:anonymous_id]
-        return false unless uid
+        # No unit id (an unidentified request before any anon id is minted): a
+        # fully-rolled gate is on for everyone, so it can be answered without
+        # bucketing; a fractional rollout genuinely needs a stable unit, so deny
+        # until one exists. Rules above are still checked, so targeting wins.
+        # See experiment-platform/18-identity-bucketing.md.
+        return (gate["rolloutPct"] || gate[:rolloutPct] || 0) >= 10000 unless uid
 
         salt = gate["salt"] || gate[:salt]
         murmur3("#{salt}:#{uid}") % 10000 < (gate["rolloutPct"] || gate[:rolloutPct] || 0)

data/lib/shipeasy/sdk/flags_client.rb

@@ -3,15 +3,30 @@ require "uri"
 require "json"
 require "thread"
 require_relative "eval"
+require_relative "telemetry"
+require_relative "anon_id"
 
 module Shipeasy
   module SDK
     class FlagsClient
       DEFAULT_BASE_URL = "https://edge.shipeasy.dev"
 
-      def initialize(api_key:, base_url: nil)
+      def initialize(api_key:, base_url: nil, env: "prod", disable_telemetry: false, telemetry_url: nil, test_mode: false)
         @api_key     = api_key
         @base_url    = (base_url || DEFAULT_BASE_URL).chomp("/")
+        # 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_*.
+        @test_mode   = test_mode
+        # Per-evaluation usage telemetry. ON by default; pass
+        # disable_telemetry: true to opt out. See telemetry.rb.
+        @telemetry = Telemetry.new(
+          endpoint: telemetry_url || Telemetry::DEFAULT_TELEMETRY_URL,
+          sdk_key: api_key,
+          side: "server",
+          env: env,
+          disabled: disable_telemetry,
+        )
         @flags_blob  = nil
         @exps_blob   = nil
         @flags_etag  = nil
@@ -20,42 +35,200 @@ module Shipeasy
         @mutex       = Mutex.new
         @timer       = nil
         @initialized = false
+        # Statsig-style local overrides. Keyed by resource name; an override,
+        # when present, short-circuits the corresponding getter. Usable on any
+        # client (test or live) for deterministic tests / local development.
+        @flag_overrides   = {}
+        @config_overrides = {}
+        @exp_overrides    = {}
+        # Change listeners — fired after a background poll returns NEW data
+        # (HTTP 200, not 304). Never fired in test/offline mode. Guarded by
+        # @mutex; see on_change / notify_change.
+        @change_listeners = []
+      end
+
+      # Build a no-network, immediately-usable client for tests. Telemetry is
+      # disabled, init/init_once/track are no-ops (never fetch), and no api_key
+      # is required. Seed it with override_flag / override_config /
+      # override_experiment, then call the normal getters.
+      def self.for_testing(env: "prod")
+        new(
+          api_key: "test",
+          env: env,
+          disable_telemetry: true,
+          test_mode: true,
+        )
+      end
+
+      # Build an offline client from a JSON snapshot file. The file holds the
+      # raw response bodies of the two SDK endpoints under "flags" and
+      # "experiments" keys:
+      #
+      #   { "flags": <body of /sdk/flags>, "experiments": <body of /sdk/experiments> }
+      #
+      # The returned client does ZERO network (reuses test_mode plumbing:
+      # init/init_once/track are no-ops, telemetry off) but, unlike a bare
+      # for_testing client, runs the REAL evaluator against the loaded blobs.
+      # Local overrides still apply on top. Handy for CI, air-gapped runs, and
+      # reproducing a production decision from a captured blob.
+      def self.from_file(path, env: "prod")
+        data = JSON.parse(File.read(path))
+        from_snapshot(flags: data["flags"], experiments: data["experiments"], env: env)
+      end
+
+      # Build an offline client directly from already-parsed blobs (same shape
+      # as the /sdk/flags and /sdk/experiments response bodies). See from_file.
+      def self.from_snapshot(flags: nil, experiments: nil, env: "prod")
+        client = for_testing(env: env)
+        client.send(:load_snapshot, flags, experiments)
+        client
       end
 
       def init
+        return if @test_mode
         fetch_all
         @initialized = true
         start_poll
       end
 
       def init_once
+        return if @test_mode
         return if @initialized
         fetch_all
         @initialized = true
       end
 
+      # --- Local overrides -------------------------------------------------
+      # An override wins over the fetched blob in the matching getter. Setters
+      # are mutex-guarded so they're safe to call alongside background polling
+      # on a live client.
+
+      def override_flag(name, value)
+        @mutex.synchronize { @flag_overrides[name.to_s] = (value ? true : false) }
+        self
+      end
+
+      def override_config(name, value)
+        @mutex.synchronize { @config_overrides[name.to_s] = value }
+        self
+      end
+
+      def override_experiment(name, group, params)
+        @mutex.synchronize do
+          @exp_overrides[name.to_s] = { group: group, params: params }
+        end
+        self
+      end
+
+      def clear_overrides
+        @mutex.synchronize do
+          @flag_overrides.clear
+          @config_overrides.clear
+          @exp_overrides.clear
+        end
+        self
+      end
+
+      # Register a listener fired after a background poll fetches NEW flag/config
+      # data (HTTP 200, not 304). Accepts either a block or any callable (an
+      # object responding to #call). Returns an unsubscribe proc — call it to
+      # remove the listener. Never fires in test/offline mode (no poll thread).
+      def on_change(callable = nil, &block)
+        listener = callable || block
+        raise ArgumentError, "on_change requires a block or callable" unless listener.respond_to?(:call)
+        @mutex.synchronize { @change_listeners << listener }
+        proc { @mutex.synchronize { @change_listeners.delete(listener) } }
+      end
+
       def destroy
         @timer&.kill
         @timer = nil
       end
 
-      def get_flag(name, user)
-        gate = @mutex.synchronize { @flags_blob&.dig("gates", name) }
-        return false unless gate
-        Eval.eval_gate(gate, user.transform_keys(&:to_s))
+      # Flag evaluation with the reason the value was reached. :value is the
+      # boolean result; :reason is one of the REASON_* constants below.
+      FlagDetail = Struct.new(:value, :reason, keyword_init: true)
+
+      # Reason constants for FlagDetail#reason / get_flag_detail.
+      REASON_CLIENT_NOT_READY = "CLIENT_NOT_READY" # no blob fetched/loaded yet
+      REASON_FLAG_NOT_FOUND   = "FLAG_NOT_FOUND"   # blob present, gate absent
+      REASON_OFF              = "OFF"              # gate present but disabled/killed
+      REASON_OVERRIDE         = "OVERRIDE"         # answered by a local override
+      REASON_RULE_MATCH       = "RULE_MATCH"       # evaluated true
+      REASON_DEFAULT          = "DEFAULT"          # evaluated false (rollout/rule)
+
+      # Evaluate a flag and return why. Telemetry ("gate" beacon) is emitted
+      # exactly once here (steps 2–5), never on the OVERRIDE short-circuit.
+      def get_flag_detail(name, user)
+        key = name.to_s
+
+        # 1. Override short-circuits before any telemetry (mirrors get_config).
+        override = @mutex.synchronize { @flag_overrides[key] if @flag_overrides.key?(key) }
+        return FlagDetail.new(value: override, reason: REASON_OVERRIDE) unless override.nil?
+
+        @telemetry.emit("gate", name)
+
+        flags_blob, gate = @mutex.synchronize { [@flags_blob, @flags_blob&.dig("gates", name)] }
+
+        # 2. Not initialized — no blob fetched or loaded yet.
+        return FlagDetail.new(value: false, reason: REASON_CLIENT_NOT_READY) if flags_blob.nil?
+
+        # 3. Blob present but this gate isn't in it.
+        return FlagDetail.new(value: false, reason: REASON_FLAG_NOT_FOUND) unless gate
+
+        # 4. Gate present but disabled (or killswitched) — eval_gate would also
+        #    return false here, but the reason is OFF, not a rollout DEFAULT.
+        if Eval.enabled?(gate["killswitch"]) || !Eval.enabled?(gate["enabled"])
+          return FlagDetail.new(value: false, reason: REASON_OFF)
+        end
+
+        # 5. Run the canonical evaluator; reason follows the boolean result.
+        result = Eval.eval_gate(gate, with_anon_id(user))
+        FlagDetail.new(value: result, reason: result ? REASON_RULE_MATCH : REASON_DEFAULT)
+      end
+
+      def get_flag(name, user, default: false)
+        detail = get_flag_detail(name, user)
+        if detail.reason == REASON_CLIENT_NOT_READY || detail.reason == REASON_FLAG_NOT_FOUND
+          default
+        else
+          detail.value
+        end
       end
 
-      def get_config(name, decode = nil)
+      def get_config(name, decode = nil, default: nil)
+        key = name.to_s
+        has_override, override = @mutex.synchronize do
+          [@config_overrides.key?(key), @config_overrides[key]]
+        end
+        if has_override
+          return decode ? decode.call(override) : override
+        end
+
+        @telemetry.emit("config", name)
         entry = @mutex.synchronize { @flags_blob&.dig("configs", name) }
-        return nil unless entry
+        return default unless entry
         value = entry["value"]
         decode ? decode.call(value) : value
       end
 
       def get_experiment(name, user, default_params, decode = nil)
+        key = name.to_s
+        override = @mutex.synchronize { @exp_overrides[key] }
+        if override
+          params = override[:params]
+          params = decode.call(params) if decode
+          return Eval::ExperimentResult.new(
+            in_experiment: true,
+            group: override[:group],
+            params: params,
+          )
+        end
+
+        @telemetry.emit("experiment", name)
         flags_blob, exps_blob = @mutex.synchronize { [@flags_blob, @exps_blob] }
         exp = exps_blob&.dig("experiments", name)
-        result = Eval.eval_experiment(exp, flags_blob, exps_blob, user.transform_keys(&:to_s))
+        result = Eval.eval_experiment(exp, flags_blob, exps_blob, with_anon_id(user))
         result.params ||= default_params
 
         if result.in_experiment && decode
@@ -75,6 +248,8 @@ module Shipeasy
       end
 
       def track(user_id, event_name, props = {})
+        return if @test_mode
+
         payload = JSON.generate({
           events: [{
             type: "metric",
@@ -94,6 +269,50 @@ module Shipeasy
 
       private
 
+      # Load a parsed snapshot into the local blobs and mark the client ready,
+      # without any network. Used by from_snapshot / from_file on a test_mode
+      # client so the real evaluator runs against captured data.
+      def load_snapshot(flags, experiments)
+        @mutex.synchronize do
+          @flags_blob = flags
+          @exps_blob  = experiments
+        end
+        @initialized = true
+        self
+      end
+
+      # Fire each change listener, snapshotting the array under the mutex so a
+      # listener that unsubscribes mid-callback doesn't mutate the list we're
+      # iterating. Listener errors are isolated (warn, never propagate).
+      def notify_change
+        listeners = @mutex.synchronize { @change_listeners.dup }
+        listeners.each do |listener|
+          begin
+            listener.call
+          rescue => e
+            warn "[shipeasy] on_change listener raised: #{e.message}"
+          end
+        end
+      end
+
+      # Normalise the user hash to string keys and, when the caller passed no
+      # explicit unit, default anonymous_id to the request's __se_anon_id (set by
+      # RackMiddleware). Lets `get_flag("x", {})` bucket anonymous traffic with
+      # zero per-call wiring. A caller-supplied user_id/anonymous_id always wins.
+      def with_anon_id(user)
+        u = user.transform_keys(&:to_s)
+        has_unit = !blank?(u["user_id"]) || !blank?(u["anonymous_id"])
+        unless has_unit
+          anon = AnonId.current
+          u["anonymous_id"] = anon if anon
+        end
+        u
+      end
+
+      def blank?(v)
+        v.nil? || v == ""
+      end
+
       def start_poll
         @timer = Thread.new do
           loop do
@@ -130,6 +349,8 @@ module Shipeasy
           @flags_etag = etag if etag
           @flags_blob = blob
         end
+        # New data arrived (200, not the 304 returned above) — notify listeners.
+        notify_change
         interval
       end
 

data/lib/shipeasy/sdk/rack_middleware.rb

@@ -0,0 +1,85 @@
+require_relative "anon_id"
+
+module Shipeasy
+  module SDK
+    # Rack middleware that mints the shared `__se_anon_id` bucketing cookie.
+    #
+    # For every request without a valid `__se_anon_id` cookie it mints a UUIDv4,
+    # exposes it for the duration of the request, and Set-Cookies it on the
+    # response. Once installed, gate/experiment evaluations with no explicit
+    # user_id / anonymous_id automatically bucket on the cookie id — anonymous
+    # visitors get stable, SSR/browser-consistent bucketing with zero per-call
+    # wiring.
+    #
+    # Rails apps get this automatically (a Railtie inserts it). For Sinatra /
+    # Hanami / bare Rack, add it yourself:
+    #
+    #   use Shipeasy::SDK::RackMiddleware
+    #
+    # The resolved id is also stored in the Rack env under "shipeasy.anon_id"
+    # for callers that prefer to read it explicitly.
+    class RackMiddleware
+      ENV_KEY = "shipeasy.anon_id".freeze
+
+      def initialize(app)
+        @app = app
+      end
+
+      def call(env)
+        id, minted = read_or_mint(env)
+        env[ENV_KEY] = id
+        AnonId.current = id
+        begin
+          status, headers, body = @app.call(env)
+        ensure
+          # Don't leak the id onto the next request handled by this thread.
+          AnonId.current = nil
+        end
+        set_cookie!(headers, id, env) if minted
+        [status, headers, body]
+      end
+
+      private
+
+      def read_or_mint(env)
+        raw = parse_cookies(env["HTTP_COOKIE"])[AnonId::COOKIE]
+        return [raw, false] if AnonId.valid?(raw)
+
+        [AnonId.mint, true]
+      end
+
+      def parse_cookies(header)
+        out = {}
+        return out unless header
+
+        header.split(/;\s*/).each do |pair|
+          k, v = pair.split("=", 2)
+          out[k] = v if k && v && !out.key?(k)
+        end
+        out
+      end
+
+      def set_cookie!(headers, id, env)
+        cookie = +"#{AnonId::COOKIE}=#{id}; Path=/; Max-Age=#{AnonId::MAX_AGE}; SameSite=Lax"
+        cookie << "; Secure" if https?(env)
+
+        # Append without clobbering any Set-Cookie the app already emitted, and
+        # match the existing header key's case (Rack 3 mandates lowercase).
+        key = headers.keys.find { |k| k.respond_to?(:casecmp) && k.casecmp("set-cookie").zero? } || "Set-Cookie"
+        existing = headers[key]
+        headers[key] =
+          case existing
+          when nil   then cookie
+          when Array then existing + [cookie]
+          else "#{existing}\n#{cookie}"
+          end
+      end
+
+      def https?(env)
+        env["HTTPS"] == "on" ||
+          env["rack.url_scheme"] == "https" ||
+          env["HTTP_X_FORWARDED_PROTO"].to_s.split(",").first.to_s.strip.casecmp("https").zero?
+      end
+    end
+  end
+end

data/lib/shipeasy/sdk/railtie.rb

@@ -0,0 +1,14 @@
+require_relative "rack_middleware"
+
+module Shipeasy
+  module SDK
+    # Auto-mounts RackMiddleware in a Rails app so anonymous bucketing works
+    # out of the box — no manual `config.middleware.use`. Loaded only when Rails
+    # is present (see lib/shipeasy-sdk.rb), so plain Ruby apps are unaffected.
+    class Railtie < ::Rails::Railtie
+      initializer "shipeasy.sdk.anon_id_middleware" do |app|
+        app.middleware.use Shipeasy::SDK::RackMiddleware
+      end
+    end
+  end
+end

data/lib/shipeasy/sdk/telemetry.rb

@@ -0,0 +1,78 @@
+require "net/http"
+require "uri"
+require "digest"
+require "erb"
+require "thread"
+
+module Shipeasy
+  module SDK
+    # Per-evaluation usage telemetry. Fires one fire-and-forget HTTP beacon per
+    # evaluation so usage is counted by Cloudflare's native per-path analytics.
+    # Mirrors the contract in the TypeScript reference SDK and
+    # experiment-platform/15-usage-metering.md. The path carries sha256(api_key)
+    # -- never the raw key -- plus side/env, then feature/resource. A long-lived
+    # Ruby process emits reliably; the 2s dedup window bounds volume under loops.
+    class Telemetry
+      DEFAULT_TELEMETRY_URL = "https://t.shipeasy.ai"
+
+      def initialize(endpoint:, sdk_key:, side: "server", env: "prod", disabled: false, dedupe_ms: 2000)
+        endpoint = (endpoint || "").chomp("/")
+        @disabled  = disabled || sdk_key.nil? || sdk_key.empty? || endpoint.empty?
+        @dedupe_ms = dedupe_ms
+        @last      = {}
+        @mutex     = Mutex.new
+        unless @disabled
+          key_hash = Digest::SHA256.hexdigest(sdk_key)
+          @prefix = "#{endpoint}/t/#{key_hash}/#{side}/#{enc(env)}"
+        end
+      end
+
+      # Best-effort usage beacon for one evaluation. Never blocks the caller
+      # (the thread owns the request) and never raises into evaluation.
+      def emit(feature, resource)
+        return if @disabled
+
+        if @dedupe_ms > 0
+          dedupe_key = "#{feature}/#{resource}"
+          now = Process.clock_gettime(Process::CLOCK_MONOTONIC) * 1000.0
+          duplicate = @mutex.synchronize do
+            last = @last[dedupe_key]
+            if last && (now - last) < @dedupe_ms
+              true
+            else
+              @last[dedupe_key] = now
+              false
+            end
+          end
+          return if duplicate
+        end
+
+        dispatch("#{@prefix}/#{feature}/#{enc(resource)}")
+      end
+
+      private
+
+      # Fire-and-forget HTTP GET on a background thread. Isolated as its own
+      # method so tests can intercept it without real network/timing.
+      def dispatch(url)
+        Thread.new do
+          begin
+            uri = URI(url)
+            http = Net::HTTP.new(uri.host, uri.port)
+            http.use_ssl = uri.scheme == "https"
+            http.open_timeout = 2
+            http.read_timeout = 2
+            http.get(uri.request_uri)
+          rescue StandardError
+            # telemetry must never affect the caller
+          end
+        end
+      end
+
+      # encodeURIComponent-equivalent: %20 for space, %2F for slash (NOT "+").
+      def enc(value)
+        ERB::Util.url_encode(value.to_s)
+      end
+    end
+  end
+end

data/lib/shipeasy/sdk/version.rb

@@ -1,5 +1,5 @@
 module Shipeasy
   module SDK
-    VERSION = "1.0.0"
+    VERSION = "1.4.0"
   end
 end

data/lib/shipeasy-sdk.rb

@@ -1,11 +1,27 @@
 require_relative "shipeasy/sdk/version"
+require_relative "shipeasy/config"
 require_relative "shipeasy/sdk/murmur3"
 require_relative "shipeasy/sdk/eval"
 require_relative "shipeasy/sdk/flags_client"
+require_relative "shipeasy/sdk/anon_id"
+require_relative "shipeasy/sdk/rack_middleware"
+require_relative "shipeasy/i18n/label_fetcher"
+
+# Rails-only surface. Skipped on plain Ruby so the gem stays usable in
+# non-Rails apps (Sinatra, Hanami, scripts) without pulling Rails in.
+if defined?(::Rails)
+  require_relative "shipeasy/i18n/view_helpers"
+  require_relative "shipeasy/i18n/railtie"
+  # Auto-mounts RackMiddleware so anonymous bucketing works with no config.
+  require_relative "shipeasy/sdk/railtie"
+end
 
 module Shipeasy
   module SDK
-    def self.new_client(api_key:, base_url: nil)
+    # Convenience constructor. Reads api_key + base_url from the gem-wide
+    # config when omitted, so a single `Shipeasy.configure { … }` block at
+    # boot is enough.
+    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)
     end
   end

metadata

@@ -1,32 +1,93 @@
 --- !ruby/object:Gem::Specification
 name: shipeasy-sdk
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.4.0
 platform: ruby
 authors:
-- ShipEasy
+- Shipeasy, Inc.
+autorequire:
 bindir: bin
 cert_chain: []
-date: 1980-01-02 00:00:00.000000000 Z
-dependencies: []
-description: Server SDK for ShipEasy — polls /sdk/flags and /sdk/experiments, evaluates
-  flags and experiments locally.
+date: 2026-06-19 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.71'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.71'
+description: Server SDK for Shipeasy. Polls /sdk/flags and /sdk/experiments, evaluates
+  gates and experiments locally, forwards exposures + metrics to /collect, and (when
+  loaded inside Rails) auto-mounts i18n_head_tags / i18n_inline_data / i18n_script_tag
+  / i18n_t view helpers for the Shipeasy string-manager CDN.
 email:
-- sdk@shipeasy.dev
+- sdk@shipeasy.ai
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- LICENSE
 - README.md
 - lib/shipeasy-sdk.rb
+- lib/shipeasy/config.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/rack_middleware.rb
+- lib/shipeasy/sdk/railtie.rb
+- lib/shipeasy/sdk/telemetry.rb
 - lib/shipeasy/sdk/version.rb
-homepage: https://github.com/shipeasy/sdk-ruby
+homepage: https://github.com/shipeasy-ai/sdk-ruby
 licenses:
-- MIT
-metadata: {}
+- Nonstandard
+metadata:
+  homepage_uri: https://github.com/shipeasy-ai/sdk-ruby
+  source_code_uri: https://github.com/shipeasy-ai/sdk-ruby
+  bug_tracker_uri: https://github.com/shipeasy-ai/sdk-ruby/issues
+  documentation_uri: https://docs.shipeasy.ai
+  license_file: LICENSE
+  rubygems_mfa_required: 'true'
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -34,14 +95,16 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.7.0
+      version: '3.0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.6
+rubygems_version: 3.5.22
+signing_key:
 specification_version: 4
-summary: ShipEasy feature flag and experimentation SDK for Ruby
+summary: Shipeasy feature gates, runtime configs, experiments, metrics, and i18n helpers
+  — Ruby gem.
 test_files: []