shipeasy-sdk 1.4.0 → 1.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bacc8b94c722361a53df3156e4dc63159c75b0657e2c1f6ae246593e90cf7c12
-  data.tar.gz: 4450034aaee670f04015f396a960646fff27e5195e13ebd93ace4c032a82f023
+  metadata.gz: 73c3a9cf2fd1a6fb0a223b9db5bcbe13cd828bfd96a4e901de545ff56d254ce7
+  data.tar.gz: '0489c3e16d16592b1301e888c82fa1d5947c21c08c74adbd9eacb6db86420138'
 SHA512:
-  metadata.gz: cff2bbf433472f1e2be585ccbf5deb12d420e29130bb8f09961f2b277135a0c1726c1318a0f1b7b57fce511b114b6fcde982cc0735b884bb946de46016638c52
-  data.tar.gz: 1ff69897f3b0501e6c4e41fa5eb386017fc4d714a0a5423871ec867b969bea2d1097fda01fb3902b1a57bc37a0490aaf433169e9d829f11739f3ac63cbcabb56
+  metadata.gz: 9f2a91c5482d5eb3baf71e744116b7295ad50b19cea9a96c2ce6b6faa01467a38ca4db91f449ae773de76144156eaeec14052d14d12f3c68a3dc521fa1c6813b
+  data.tar.gz: b8e2512bbc85e404fa4528c411700bff22e7eea40f20be2d6392bd7f59166eb65464cfe17760f8b7a2f56c0eb2c7ca15a42fbc579c0937f04ce61c402824a862

data/lib/shipeasy/sdk/eval.rb

@@ -57,6 +57,19 @@ module Shipeasy
         end
       end
 
+      # Pick the bucketing identifier. When bucket_by is set and the user
+      # carries that attribute as a non-empty string (or any number, stringified),
+      # bucket on it — so a whole company/org lands on one variant. Otherwise fall
+      # back to user_id, then anonymous_id. Mirrors core's pickIdentifier.
+      def self.pick_identifier(user, bucket_by)
+        if bucket_by && !bucket_by.to_s.empty?
+          v = user[bucket_by] || user[bucket_by.to_sym]
+          return v if v.is_a?(String) && !v.empty?
+          return v.to_s if v.is_a?(Numeric)
+        end
+        user["user_id"] || user[:user_id] || user["anonymous_id"] || user[:anonymous_id]
+      end
+
       def self.eval_gate(gate, user)
         return false if enabled?(gate["killswitch"])
         return false unless enabled?(gate["enabled"])
@@ -79,7 +92,14 @@ module Shipeasy
 
       ExperimentResult = Struct.new(:in_experiment, :group, :params, keyword_init: true)
 
-      def self.eval_experiment(exp, flags_blob, exps_blob, user)
+      # exp_name + sticky_store are optional so existing callers stay deterministic.
+      # When a sticky_store is passed, an enrolled unit whose stored salt prefix
+      # still matches skips the allocation gate (so a shrinking allocation keeps
+      # it in) and returns the stored group without re-running the pick. A fresh
+      # pick is persisted via store.set; a salt mismatch / missing stored group
+      # falls through to re-bucket + overwrite. Mirrors the TS reference
+      # (doc 20 §2). exp_name is the key under which the entry is stored.
+      def self.eval_experiment(exp, flags_blob, exps_blob, user, exp_name: nil, sticky_store: nil)
         not_in = ExperimentResult.new(in_experiment: false, group: "control", params: nil)
 
         return not_in unless exp && exp["status"] == "running"
@@ -90,7 +110,8 @@ module Shipeasy
           return not_in unless gate && eval_gate(gate, user)
         end
 
-        uid = user["user_id"] || user[:user_id] || user["anonymous_id"] || user[:anonymous_id]
+        bucket_by = exp["bucketBy"] || exp[:bucketBy]
+        uid = pick_identifier(user, bucket_by)
         return not_in unless uid
 
         universe_name = exp["universe"]
@@ -103,14 +124,28 @@ module Shipeasy
 
         salt          = exp["salt"]
         allocation_pct = exp["allocationPct"] || 0
+        groups = exp["groups"] || []
+        salt8 = (salt || "")[0, 8]
+
+        # Sticky short-circuit: an enrolled unit whose stored salt prefix still
+        # matches skips allocation and returns the stored group. If the stored
+        # group no longer exists, fall through to re-bucket + overwrite.
+        if sticky_store && exp_name
+          entry = (sticky_store.get(uid) || {})[exp_name]
+          if entry && entry["s"] == salt8
+            g = groups.find { |x| x["name"] == entry["g"] }
+            return ExperimentResult.new(in_experiment: true, group: g["name"], params: g["params"]) if g
+          end
+        end
+
         return not_in if murmur3("#{salt}:alloc:#{uid}") % 10000 >= allocation_pct
 
         group_hash = murmur3("#{salt}:group:#{uid}") % 10000
         cumulative = 0
-        groups = exp["groups"] || []
         groups.each_with_index do |g, i|
           cumulative += g["weight"]
           if group_hash < cumulative || i == groups.length - 1
+            sticky_store.set(uid, exp_name, { "g" => g["name"], "s" => salt8 }) if sticky_store && exp_name
             return ExperimentResult.new(in_experiment: true, group: g["name"], params: g["params"])
           end
         end

data/lib/shipeasy/sdk/flags_client.rb

@@ -5,15 +5,29 @@ require "thread"
 require_relative "eval"
 require_relative "telemetry"
 require_relative "anon_id"
+require_relative "sticky_store"
+require_relative "see"
 
 module Shipeasy
   module SDK
     class FlagsClient
       DEFAULT_BASE_URL = "https://edge.shipeasy.dev"
 
-      def initialize(api_key:, base_url: nil, env: "prod", disable_telemetry: false, telemetry_url: nil, test_mode: false)
+      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
         @base_url    = (base_url || DEFAULT_BASE_URL).chomp("/")
+        # Read-env tag. Used by telemetry below and stamped onto see() error
+        # events so reports are attributable to an environment.
+        @env         = env
+        # Attribute names usable for targeting but stripped from every outbound
+        # /collect payload (LD/Statsig privateAttributes). The server evaluates
+        # locally so private attrs never leave for evaluation; the only egress is
+        # track(), where the listed keys are dropped from the props bag.
+        @private_attributes = (private_attributes || []).map(&:to_s)
+        # Pluggable sticky-bucketing store (doc 20 §2). Absent ⇒ deterministic.
+        # Threaded into get_experiment so an enrolled unit locks to its first
+        # assigned variant. Built-in: InMemoryStickyStore.
+        @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_*.
@@ -45,6 +59,13 @@ module Shipeasy
         # (HTTP 200, not 304). Never fired in test/offline mode. Guarded by
         # @mutex; see on_change / notify_change.
         @change_listeners = []
+        # see() structured error reporting. Per-process spam guard, bound here so
+        # repeated reports of the same issue collapse to one send. See see.rb.
+        @see_limiter = See::Limiter.new
+        # Register as the default client backing the module-level Shipeasy::SDK
+        # .see/.see_violation funcs (last constructed wins — the server-SDK
+        # analog of TS's shipeasy({key}) configure call).
+        Shipeasy::SDK.set_default_client(self)
       end
 
       # Build a no-network, immediately-usable client for tests. Telemetry is
@@ -228,7 +249,10 @@ module Shipeasy
         @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, with_anon_id(user))
+        result = Eval.eval_experiment(
+          exp, flags_blob, exps_blob, with_anon_id(user),
+          exp_name: name.to_s, sticky_store: @sticky_store,
+        )
         result.params ||= default_params
 
         if result.in_experiment && decode
@@ -250,13 +274,15 @@ module Shipeasy
       def track(user_id, event_name, props = {})
         return if @test_mode
 
+        safe_props = strip_private(props)
+
         payload = JSON.generate({
           events: [{
             type: "metric",
             event_name: event_name,
             user_id: user_id.to_s,
             ts: (Time.now.to_f * 1000).to_i,
-            **(props.empty? ? {} : { properties: props }),
+            **(safe_props.empty? ? {} : { properties: safe_props }),
           }],
         })
 
@@ -267,8 +293,96 @@ module Shipeasy
         end
       end
 
+      # Emit an exposure event for an experiment at the server-side decision
+      # point (parity with the browser's auto-exposure). The server is stateless
+      # and never auto-logs, so call this when you actually present the
+      # treatment. Re-evaluates the experiment for the user (a bare user_id
+      # string is wrapped as { "user_id" => id }); if enrolled, POSTs a single
+      # exposure to /collect. No-op in test mode or when the user isn't enrolled.
+      def log_exposure(user_or_user_id, experiment_name)
+        return if @test_mode
+
+        user = user_or_user_id.is_a?(Hash) ? user_or_user_id : { "user_id" => user_or_user_id.to_s }
+        result = get_experiment(experiment_name, user, {})
+        return unless result.in_experiment
+
+        u = user.transform_keys(&:to_s)
+        payload = JSON.generate({
+          events: [{
+            type: "exposure",
+            experiment: experiment_name.to_s,
+            group: result.group,
+            user_id: (u["user_id"] || u["anonymous_id"]).to_s,
+            ts: (Time.now.to_f * 1000).to_i,
+          }],
+        })
+
+        Thread.new do
+          post("/collect", payload)
+        rescue => e
+          warn "[shipeasy] log_exposure failed: #{e.message}"
+        end
+      end
+
+      # ---- see() structured error reporting -------------------------------
+
+      # Report a caught exception (or thrown non-exception). Fire-and-forget;
+      # never blocks or throws into the request path. Terminate with
+      # `.to(outcome)`:
+      #
+      #   client.see(e).causes_the("checkout").to("use cached prices")
+      def see(problem)
+        See::Chain.new(problem, method(:dispatch_see))
+      end
+
+      # Report a non-exception problem. The name is a stable fingerprint key —
+      # put variable data in `.extras`, never in the name.
+      def see_violation(name)
+        See::Chain.new(See::Violation.new(name), method(:dispatch_see))
+      end
+      alias seeViolation see_violation
+
+      # Mark an exception as expected control flow — reports nothing. Returns a
+      # `.because(reason)` tail (with optional `.extras` for local debug only).
+      def control_flow_exception(err)
+        See::ControlFlowChain.new(err)
+      end
+      alias controlFlowException control_flow_exception
+
       private
 
+      # Build the wire event and fire-and-forget POST it to /collect. No-op in
+      # test mode (mirrors track). Spam-guarded. Never raises into caller code.
+      def dispatch_see(built)
+        return if @test_mode
+
+        ev = See.build_event(
+          built.problem,
+          built.subject,
+          built.outcome,
+          strip_private(built.extras),
+          sdk_version: Shipeasy::SDK::VERSION,
+          env: @env,
+        )
+        return unless @see_limiter.should_send?(ev)
+
+        payload = JSON.generate({ events: [ev] })
+        Thread.new do
+          post("/collect", payload)
+        rescue => e
+          warn "[shipeasy] see() send failed: #{e.message}"
+        end
+      rescue => e
+        warn "[shipeasy] see() failed: #{e.message}"
+      end
+
+      # Drop caller-marked private attributes from an outbound props bag. Handles
+      # both string and symbol keys against the stringified private list.
+      def strip_private(props)
+        return props if props.nil? || props.empty? || @private_attributes.empty?
+        props.reject { |k, _| @private_attributes.include?(k.to_s) }
+      end
+
       # 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.

data/lib/shipeasy/sdk/openfeature.rb

@@ -0,0 +1,204 @@
+# frozen_string_literal: true
+
+# OpenFeature provider for Shipeasy (server paradigm).
+#
+# Lets apps standardized on the CNCF OpenFeature API plug Shipeasy in as the
+# backing provider. This file is intentionally NOT required by the main
+# `shipeasy-sdk` entrypoint — `openfeature-sdk` is an optional development
+# dependency, so the provider is loaded lazily and the gem is required from
+# inside this file. Require it explicitly when you want the provider:
+#
+#   require "open_feature/sdk"
+#   require "shipeasy/sdk/openfeature"
+#
+#   client = Shipeasy::SDK::FlagsClient.new(api_key: ENV.fetch("SHIPEASY_SERVER_KEY"))
+#   client.init
+#
+#   OpenFeature::SDK.configure do |config|
+#     config.set_provider(Shipeasy::OpenFeature::Provider.new(client))
+#   end
+#
+#   of = OpenFeature::SDK.build_client
+#   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
+# onto gates (`get_flag_detail`); string/number/integer/float/object map onto
+# dynamic configs (`get_config`).
+
+# `openfeature-sdk` (module `OpenFeature::SDK::Provider`) is an optional dep.
+# Require it lazily so the main SDK never pulls it in; surface a clear error if
+# the consumer forgot to add it.
+begin
+  require "open_feature/sdk"
+rescue LoadError => e
+  raise LoadError, "shipeasy/sdk/openfeature requires the `openfeature-sdk` gem " \
+                   "(module OpenFeature::SDK::Provider). Add it to your Gemfile: " \
+                   "gem \"openfeature-sdk\". (#{e.message})"
+end
+
+require_relative "flags_client"
+
+module Shipeasy
+  module OpenFeature
+    # Shipeasy OpenFeature provider (server paradigm). Wraps a
+    # `Shipeasy::SDK::FlagsClient`; evaluation is local against the cached blob,
+    # so resolution is effectively synchronous.
+    class Provider
+      OF = ::OpenFeature::SDK::Provider
+
+      # Shipeasy `FlagDetail#reason` → [OpenFeature reason, optional error_code].
+      # Per the cross-SDK contract (doc 20):
+      #   RULE_MATCH       → TARGETING_MATCH
+      #   DEFAULT          → DEFAULT
+      #   OFF              → DISABLED
+      #   OVERRIDE         → STATIC
+      #   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],
+      }.freeze
+
+      attr_reader :metadata
+
+      def initialize(client)
+        @client = client
+        @metadata = OF::ProviderMetadata.new(name: "shipeasy").freeze
+      end
+
+      # OpenFeature lifecycle (optional but supported): fetch the blob once and
+      # tear down the poll thread on shutdown.
+      def init(_evaluation_context = nil)
+        @client.init_once
+      end
+
+      def shutdown
+        @client.destroy
+      end
+
+      # --- Boolean → gate ------------------------------------------------------
+
+      def fetch_boolean_value(flag_key:, default_value:, evaluation_context: nil)
+        user = to_user(evaluation_context)
+        detail = @client.get_flag_detail(flag_key, user)
+        of_reason, error_code = REASON_MAP.fetch(detail.reason, [OF::Reason::UNKNOWN, nil])
+
+        if error_code
+          OF::ResolutionDetails.new(value: default_value, reason: of_reason, error_code: error_code)
+        else
+          OF::ResolutionDetails.new(value: detail.value, reason: of_reason)
+        end
+      rescue => e
+        OF::ResolutionDetails.new(
+          value: default_value, reason: OF::Reason::ERROR,
+          error_code: OF::ErrorCode::GENERAL, error_message: e.message,
+        )
+      end
+
+      # --- String / number / integer / float / object → dynamic config --------
+
+      def fetch_string_value(flag_key:, default_value:, evaluation_context: nil)
+        resolve_config(flag_key, default_value) { |v| v.is_a?(String) }
+      end
+
+      def fetch_number_value(flag_key:, default_value:, evaluation_context: nil)
+        resolve_config(flag_key, default_value) { |v| numeric?(v) }
+      end
+
+      def fetch_integer_value(flag_key:, default_value:, evaluation_context: nil)
+        resolve_config(flag_key, default_value) { |v| v.is_a?(Integer) }
+      end
+
+      def fetch_float_value(flag_key:, default_value:, evaluation_context: nil)
+        resolve_config(flag_key, default_value) { |v| numeric?(v) }
+      end
+
+      def fetch_object_value(flag_key:, default_value:, evaluation_context: nil)
+        resolve_config(flag_key, default_value) { |v| v.is_a?(Hash) || v.is_a?(Array) }
+      end
+
+      # OpenFeature `track()` → Shipeasy `track()`. No-ops without a targeting key.
+      def track(tracking_event_name, evaluation_context: nil, details: {})
+        ctx = normalize_context(evaluation_context)
+        user_id = ctx["targeting_key"] || ctx["user_id"]
+        return if user_id.nil? || user_id.to_s.empty?
+
+        props = details.is_a?(Hash) ? details : {}
+        @client.track(user_id, tracking_event_name, props)
+      end
+
+      private
+
+      # A sentinel distinct from any legitimate config value so we can tell an
+      # absent key (→ DEFAULT) from a present-but-nil value.
+      ABSENT = Object.new
+      private_constant :ABSENT
+
+      # Resolve a dynamic config and type-check it. Absent key → DEFAULT;
+      # present but failing the type predicate → TYPE_MISMATCH; otherwise
+      # TARGETING_MATCH with the value. Both return the default for the value.
+      def resolve_config(flag_key, default_value)
+        raw = @client.get_config(flag_key, nil, default: ABSENT)
+
+        if raw.equal?(ABSENT)
+          return OF::ResolutionDetails.new(value: default_value, reason: OF::Reason::DEFAULT)
+        end
+
+        unless yield(raw)
+          return OF::ResolutionDetails.new(
+            value: default_value, reason: OF::Reason::ERROR,
+            error_code: OF::ErrorCode::TYPE_MISMATCH,
+            error_message: "config value #{raw.inspect} does not match the requested type",
+          )
+        end
+
+        OF::ResolutionDetails.new(value: raw, reason: OF::Reason::TARGETING_MATCH)
+      rescue => e
+        OF::ResolutionDetails.new(
+          value: default_value, reason: OF::Reason::ERROR,
+          error_code: OF::ErrorCode::GENERAL, error_message: e.message,
+        )
+      end
+
+      def numeric?(value)
+        # Booleans are Integers' cousins in some langs but not Ruby; exclude
+        # them explicitly so `true` never satisfies a number/float request.
+        return false if value == true || value == false
+
+        value.is_a?(Numeric)
+      end
+
+      # Build a Shipeasy user hash from an OpenFeature EvaluationContext:
+      # `targeting_key` → `user_id`; every other field carried through verbatim
+      # for targeting. Accepts a real EvaluationContext, a plain Hash, or nil.
+      def to_user(evaluation_context)
+        ctx = normalize_context(evaluation_context)
+        targeting_key = ctx["targeting_key"]
+        rest = ctx.reject { |k, _| k == "targeting_key" }
+        user = rest
+        if targeting_key.is_a?(String) && !targeting_key.empty?
+          user = user.merge("user_id" => targeting_key)
+        end
+        user
+      end
+
+      # Coerce any of {EvaluationContext, Hash, nil} into a string-keyed Hash.
+      def normalize_context(evaluation_context)
+        return {} if evaluation_context.nil?
+
+        if evaluation_context.respond_to?(:fields)
+          evaluation_context.fields.transform_keys(&:to_s)
+        elsif evaluation_context.is_a?(Hash)
+          evaluation_context.transform_keys(&:to_s)
+        else
+          {}
+        end
+      end
+    end
+  end
+end

data/lib/shipeasy/sdk/see.rb

@@ -0,0 +1,284 @@
+# see — shipeasy error. Structured error reporting for the server SDK.
+#
+# Mirrors `@shipeasy/sdk` (packages/ts-sdk/src/see/core.ts) and the Python
+# reference (packages/server-sdks/sdk-python/shipeasy/_see.py). Every handled
+# exception documents its product *consequence*, not just its stack:
+#
+#   begin
+#     charge_card(order)
+#   rescue => e
+#     Shipeasy::SDK.see(e).causes_the("checkout").to("use the backup processor")
+#   end
+#
+# Dispatch model (differs from TS, which uses a microtask): `.to(outcome)` is
+# the terminal — it builds the wire event and fire-and-forgets the POST to
+# /collect. `causes_the` and `extras` are chainable setters that may be called
+# in any order *before* `.to`:
+#
+#   client.see(e).causes_the("checkout").to("use cached prices")
+#   client.see(e).causes_the("checkout").extras({ order_id: oid }).to("use cached prices")
+#
+# If you don't know the consequence of an exception, don't catch it.
+
+require "thread"
+require "json"
+require_relative "version"
+
+module Shipeasy
+  module SDK
+    module See
+      # ---- Limits (mirror core.ts; kept in sync with the worker's /collect) ----
+      SEE_MAX_MESSAGE     = 500
+      SEE_MAX_STACK       = 8000
+      SEE_MAX_SUBJECT     = 200 # used for subject, outcome, error_type
+      SEE_MAX_EXTRA_VALUE = 200
+      SEE_MAX_EXTRA_KEYS  = 20
+      SEE_DEDUP_WINDOW_MS = 30_000
+      SEE_MAX_PER_PROCESS = 25
+
+      # Default consequence parts when a chain omits them.
+      DEFAULT_SUBJECT = "app".freeze
+      DEFAULT_OUTCOME = "hit an error".freeze
+
+      # Marker attribute stamped onto an exception by control_flow_exception().
+      EXPECTED_IVAR = :@__shipeasy_see_expected
+
+      module_function
+
+      def truncate(str, limit)
+        s = str.to_s
+        s.length <= limit ? s : s[0, limit]
+      end
+
+      # Drop nil values, keep only String/Numeric(finite)/boolean, truncate
+      # string values to 200 chars, cap at 20 keys (insertion order). Returns
+      # nil if nothing is kept. Keys are stringified.
+      def sanitize_extras(extras)
+        return nil unless extras.is_a?(Hash)
+        return nil if extras.empty?
+
+        out = {}
+        extras.each do |k, v|
+          break if out.size >= SEE_MAX_EXTRA_KEYS
+          next if v.nil?
+
+          case v
+          when true, false
+            out[k.to_s] = v
+          when String
+            out[k.to_s] = truncate(v, SEE_MAX_EXTRA_VALUE)
+          when Numeric
+            # Reject NaN / Infinity (not representable in JSON).
+            next if v.respond_to?(:finite?) && !v.finite?
+
+            out[k.to_s] = v
+          else
+            next
+          end
+        end
+        out.empty? ? nil : out
+      end
+
+      # Best-effort stamp marking an exception as expected control flow.
+      def mark_expected(err, because, extras = nil)
+        mark = { "because" => because.to_s }
+        clean = sanitize_extras(extras)
+        mark["extras"] = clean if clean
+        err.instance_variable_set(EXPECTED_IVAR, mark)
+      rescue StandardError
+        # Frozen / builtin objects that reject ivars: best effort only.
+        nil
+      end
+
+      def expected?(err)
+        err.instance_variable_defined?(EXPECTED_IVAR) &&
+          !err.instance_variable_get(EXPECTED_IVAR).nil?
+      rescue StandardError
+        false
+      end
+
+      # A non-exception problem. The name is a stable fingerprint key — put
+      # variable data in `.extras`, never in the name.
+      class Violation
+        attr_reader :name
+
+        def initialize(name)
+          @name = name.to_s
+        end
+      end
+
+      # ---- Wire event construction ----
+
+      # Build the type:"error" event accepted by POST /collect.
+      def build_event(problem, subject, outcome, extras, sdk_version:, env:)
+        stack = nil
+
+        if problem.is_a?(Violation)
+          error_type = problem.name
+          message    = problem.name
+          kind       = "violation"
+        elsif problem.is_a?(Exception)
+          error_type = problem.class.name || "Error"
+          message    = (problem.message.to_s.empty? ? error_type : problem.message)
+          bt = problem.backtrace
+          stack = bt.join("\n") if bt && !bt.empty?
+          kind = "caught"
+        else
+          error_type = "Error"
+          message    = problem.to_s
+          kind       = "caught"
+        end
+
+        ev = {
+          "type"        => "error",
+          "kind"        => kind,
+          "error_type"  => truncate(error_type, SEE_MAX_SUBJECT),
+          "message"     => truncate(message, SEE_MAX_MESSAGE),
+          "subject"     => truncate(subject, SEE_MAX_SUBJECT),
+          "outcome"     => truncate(outcome, SEE_MAX_SUBJECT),
+          "side"        => "server",
+          "sdk_version" => sdk_version,
+          "ts"          => (Time.now.to_f * 1000).to_i,
+        }
+        ev["stack"] = truncate(stack, SEE_MAX_STACK) if stack
+        clean = sanitize_extras(extras)
+        ev["extras"] = clean if clean
+        ev["env"] = env if env && !env.to_s.empty?
+        ev
+      end
+
+      # ---- Spam limiter (mirror SeeLimiter) ----
+
+      # Per-process spam guard: identical events within 30s collapse to one
+      # send; a hard cap bounds total sends. Thread-safe. The worker dedupes by
+      # fingerprint anyway — this only bounds network chatter from a hot loop.
+      class Limiter
+        def initialize(max_per_process: SEE_MAX_PER_PROCESS, dedup_window_ms: SEE_DEDUP_WINDOW_MS)
+          @max    = max_per_process
+          @window = dedup_window_ms
+          @last   = {}
+          @sent   = 0
+          @mutex  = Mutex.new
+        end
+
+        def should_send?(ev)
+          @mutex.synchronize do
+            return false if @sent >= @max
+
+            key = [
+              ev["kind"],
+              ev["error_type"],
+              ev["message"].to_s[0, 200],
+              See.top_stack_line(ev["stack"]),
+            ].join("|")
+            now = (Time.now.to_f * 1000).to_i
+            prev = @last[key]
+            return false if prev && (now - prev) < @window
+
+            @last[key] = now
+            @sent += 1
+            true
+          end
+        end
+      end
+
+      def top_stack_line(stack)
+        return "" if stack.nil? || stack.empty?
+
+        stack.each_line do |line|
+          s = line.strip
+          return s[0, 200] if s.start_with?("File ") || s.start_with?("at ") || s.include?("line ") || s.include?(":in ")
+        end
+        ""
+      end
+
+      # ---- Fluent chains ----
+
+      # Accumulates consequence + extras; `.to(outcome)` dispatches once.
+      class Chain
+        def initialize(problem, dispatch)
+          @problem  = problem
+          @dispatch = dispatch
+          @subject  = nil
+          @outcome  = nil
+          @extras   = nil
+          @done     = false
+        end
+
+        def causes_the(subject)
+          @subject = subject.to_s
+          self
+        end
+        alias causesThe causes_the
+
+        def extras(extras)
+          if extras.is_a?(Hash) && !extras.empty?
+            @extras = (@extras || {}).merge(extras)
+          end
+          self
+        end
+
+        # Terminal: build the event and fire-and-forget the report. Idempotent.
+        def to(outcome)
+          return if @done
+
+          @done = true
+          @outcome = outcome.to_s
+          begin
+            @dispatch.call(
+              Built.new(@problem, @subject || DEFAULT_SUBJECT, @outcome.empty? ? DEFAULT_OUTCOME : @outcome, @extras)
+            )
+          rescue StandardError
+            # Reporting must never raise into caller code.
+            nil
+          end
+        end
+      end
+
+      # Plain carrier of a finalized chain handed to the client dispatcher.
+      Built = Struct.new(:problem, :subject, :outcome, :extras)
+
+      # `control_flow_exception(e).because("because ...")` — marks the exception
+      # expected and reports NOTHING. `.extras` is stored for local debugging
+      # only (an expected exception is never transmitted).
+      class ControlFlowChain
+        def initialize(err)
+          @err = err
+        end
+
+        def because(reason)
+          See.mark_expected(@err, reason)
+          ControlFlowTail.new(@err, reason)
+        end
+      end
+
+      class ControlFlowTail
+        def initialize(err, reason)
+          @err = err
+          @reason = reason
+        end
+
+        def extras(extras)
+          See.mark_expected(@err, @reason, extras)
+          self
+        end
+      end
+
+      # A no-op chain returned by the module-level see() when no client exists.
+      class NullChain
+        def causes_the(_subject)
+          self
+        end
+        alias causesThe causes_the
+
+        def extras(_extras)
+          self
+        end
+
+        def to(_outcome)
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/shipeasy/sdk/sticky_store.rb

@@ -0,0 +1,39 @@
+require "thread"
+
+module Shipeasy
+  module SDK
+    # Pluggable sticky-bucketing store for the server (doc 20 §2). Duck-typed:
+    # any object responding to the two methods below works.
+    #
+    #   get(unit) -> { exp_name => { "g" => group, "s" => salt8 } } or nil
+    #   set(unit, exp_name, entry)   # entry = { "g" => group, "s" => salt8 }
+    #
+    # Keyed by the bucketing unit (pick_identifier-resolved id). When threaded
+    # into experiment eval, an enrolled unit locks to its first-assigned variant
+    # — changing allocation % or weights won't re-bucket it; changing the
+    # experiment salt is the reshuffle lever. Absent ⇒ deterministic behavior.
+    class InMemoryStickyStore
+      # Optionally seed with { unit => { exp => { "g"=>.., "s"=>.. } } }.
+      def initialize(seed = nil)
+        @mutex = Mutex.new
+        @data  = {}
+        if seed
+          seed.each { |unit, exps| @data[unit.to_s] = exps.dup }
+        end
+      end
+
+      # Return this unit's per-experiment assignments, or nil if none.
+      def get(unit)
+        @mutex.synchronize { @data[unit.to_s] }
+      end
+
+      # Persist one assignment for (unit, exp).
+      def set(unit, exp, entry)
+        @mutex.synchronize do
+          (@data[unit.to_s] ||= {})[exp] = entry
+        end
+        nil
+      end
+    end
+  end
+end

data/lib/shipeasy/sdk/version.rb

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

data/lib/shipeasy-sdk.rb

@@ -2,6 +2,7 @@ require_relative "shipeasy/sdk/version"
 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/sdk/anon_id"
 require_relative "shipeasy/sdk/rack_middleware"
@@ -24,5 +25,54 @@ module Shipeasy
     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
+
+    # ---- see() module-level facade --------------------------------------
+    #
+    # Backed by a default client, registered when a FlagsClient 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
+    # client exists warns and returns a no-op chain (NEVER raises).
+
+    @see_default_client = nil
+    @see_default_mutex  = Mutex.new
+
+    # Register the client backing the module-level see() funcs. Called
+    # automatically from FlagsClient#initialize; also exposed for explicit use.
+    def self.set_default_client(client)
+      @see_default_mutex.synchronize { @see_default_client = client }
+      client
+    end
+
+    def self.default_client
+      @see_default_mutex.synchronize { @see_default_client }
+    end
+
+    # Report a caught exception via the default client. Use client.see to
+    # target a specific client.
+    def self.see(problem)
+      client = default_client
+      if client.nil?
+        warn "[shipeasy] see() called before a client was created — error dropped"
+        return See::NullChain.new
+      end
+      client.see(problem)
+    end
+
+    # Report a non-exception problem via the default client.
+    def self.see_violation(name)
+      client = default_client
+      if client.nil?
+        warn "[shipeasy] see_violation() called before a client was created — error dropped"
+        return See::NullChain.new
+      end
+      client.see_violation(name)
+    end
+
+    # Mark an exception as expected control flow (reports nothing). Works
+    # without a client — it only stamps the exception object.
+    def self.control_flow_exception(err)
+      See::ControlFlowChain.new(err)
+    end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: shipeasy-sdk
 version: !ruby/object:Gem::Version
-  version: 1.4.0
+  version: 1.6.0
 platform: ruby
 authors:
 - Shipeasy, Inc.
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-06-19 00:00:00.000000000 Z
+date: 2026-06-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
@@ -73,8 +73,11 @@ files:
 - 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
 - lib/shipeasy/sdk/railtie.rb
+- lib/shipeasy/sdk/see.rb
+- lib/shipeasy/sdk/sticky_store.rb
 - lib/shipeasy/sdk/telemetry.rb
 - lib/shipeasy/sdk/version.rb
 homepage: https://github.com/shipeasy-ai/sdk-ruby