shipeasy-sdk 1.0.0 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4eafaff1d5be1131bb55a64dbbb1653ee18f2a5a9e22cd83a45bb92de7bcfcb6
-  data.tar.gz: 4b59ebf58017deb5def949f46235d53f6ca60320400ac72ada320eff92d7e5d5
+  metadata.gz: 6987470d45b6349d50b279a94bc0fb356812c23f354a743c3c052433dc5759aa
+  data.tar.gz: 34d847b481a67fd8876c5e7dfc1351dab1e832fa41f97053324cffb19e24a4c0
 SHA512:
-  metadata.gz: cb3f19e0215c65fed6db82a1ef181949ef0cb666a25e02e67103b6840bc79ee3e855e9f784a99f03d9ca54c73a74f431e3d16fd90fca29561317ab4b80b200f0
-  data.tar.gz: 480ac5a6fdeaef418e34488a668e4431bafa392a54d7e8eae7373541a48d401bdb687408e0759f6269c7263c9d38a11b4b4877930df65b4cd7bde859472b0eca
+  metadata.gz: 4a3899f6938f09b3e84f0de89f37aab45caca5ae1449157d9e6efd45274a0b224fadbbcfa54505ee84ff760a3b8309fa5545227b0f41cb2650bf83c48d7cfe1f
+  data.tar.gz: c5ea14a6d5e53fe124bb8fbb7de06ed3930975b764964698e4c3dbc771f8e68d1766062777fe527f57b8cbd59924b94b864e8f4ed5d7574aa86b066cd9c6d896

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,145 @@
-# 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)
 
-# 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" }
+Same pattern, just without `config/initializers`:
+
+```ruby
+require "shipeasy-sdk"
 
-# Track a metric event (fire-and-forget background thread)
-client.track("usr_123", "checkout_completed", { revenue: 49.99 })
+Shipeasy.configure { |c| c.api_key = ENV.fetch("SHIPEASY_SERVER_KEY") }
 
-# Shutdown (stops background poll thread)
-client.destroy
+Shipeasy.flags.get_flag("new_checkout", { user_id: "u_1" })
 ```
 
-## init vs init_once
+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:
 
-- `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).
+```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 }
+```
 
 ## 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.
 
 ## 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,26 @@ 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)
         @api_key     = api_key
         @base_url    = (base_url || DEFAULT_BASE_URL).chomp("/")
+        # 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
@@ -40,12 +51,14 @@ module Shipeasy
       end
 
       def get_flag(name, user)
+        @telemetry.emit("gate", name)
         gate = @mutex.synchronize { @flags_blob&.dig("gates", name) }
         return false unless gate
-        Eval.eval_gate(gate, user.transform_keys(&:to_s))
+        Eval.eval_gate(gate, with_anon_id(user))
       end
 
       def get_config(name, decode = nil)
+        @telemetry.emit("config", name)
         entry = @mutex.synchronize { @flags_blob&.dig("configs", name) }
         return nil unless entry
         value = entry["value"]
@@ -53,9 +66,10 @@ module Shipeasy
       end
 
       def get_experiment(name, user, default_params, decode = nil)
+        @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
@@ -94,6 +108,24 @@ module Shipeasy
 
       private
 
+      # 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

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.3.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.3.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-13 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: []