RubyGems - shipeasy-sdk - Versions diffs - 1.5.0 → 1.7.0 - Mend

shipeasy-sdk 1.5.0 → 1.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (7) hide show

checksums.yaml +4 -4
data/README.md +25 -0
data/lib/shipeasy/sdk/flags_client.rb +138 -0
data/lib/shipeasy/sdk/see.rb +284 -0
data/lib/shipeasy/sdk/version.rb +1 -1
data/lib/shipeasy-sdk.rb +49 -0
metadata +3 -2

checksums.yaml CHANGED Viewed

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ff3dbc0f1f6f19484edafcb75460928392fd43278036b68ed2c8179f9d21ac4d
-  data.tar.gz: 04d7e38426d7be6c00e504749c6a33441d88db79f70e1eae533fa9fc115b94d4
+  metadata.gz: afdce684e3c6a83b220b7dfaa1d7db249284e3bb4c4ebfe3c9b27c54da0d801b
+  data.tar.gz: ecdfdf8aed19f1b5f18fe874ce5b13064bb61abe7bf7f1c47a76b08d9ab99bce
 SHA512:
-  metadata.gz: 93432ded1ed218653913a2895c0178741c4e4e06671e131722d45672f481d782791243fdc35d16347bd1462b2ea0cc2c8bdacdb7012d983a17f190c208159d9d
-  data.tar.gz: def56c79ef372df20b3a7325e838d8165955c39a2c8221e393546d60b61b9405ee2d5a346e2a467bc771d88c50af8806f116d1bfaac2eaed5db9f2e8f6cbd338
+  metadata.gz: e6a5470268bc584eaa2dbc8c89f722a22633d0bd6f896aaa1d73db74090b56667c87733c614b8a49bdeda88dab043740509153503943837a69be20a03dc315b7
+  data.tar.gz: 55289a4adf0559f41eca2d1f6bca03b53a19da9b3f00f4109dc4476ed0c5cbaaed453dbaf3f7c0ebcc1405f0d73a55fe702e02859c9a809d525e92b294e275ba

data/README.md CHANGED Viewed

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

data/lib/shipeasy/sdk/flags_client.rb CHANGED Viewed

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

data/lib/shipeasy/sdk/see.rb ADDED Viewed

@@ -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/version.rb CHANGED Viewed

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

data/lib/shipeasy-sdk.rb CHANGED Viewed

@@ -25,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 CHANGED Viewed

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: shipeasy-sdk
 version: !ruby/object:Gem::Version
-  version: 1.5.0
+  version: 1.7.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
@@ -76,6 +76,7 @@ files:
 - 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