shipeasy-sdk 3.3.0 → 3.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 60cefd35bba21f86ef6b77da83d0c918744721d9c564066b12e8d2b95dba8740
-  data.tar.gz: 22b03ac85fbd29bba861770120c2a78bbcbc5069e0e7af0cbe8b1c33b8ebee88
+  metadata.gz: 0453ca27510264bd268b40868bb5c55a942835b7a20076b11e19305b4eeb27a7
+  data.tar.gz: c9c0b1ee3c80cf28abac5af4ec8bdaec1613f8b3235708b79b27223e38d2d463
 SHA512:
-  metadata.gz: 226eccc8d981ce982ed132eb697c39e37cde9f9d62d9f84970cea6119601696383520bc1f03606abd58b81574be31d26962aedf2e000acfe45e1ac7bdb2c5f2c
-  data.tar.gz: 1e213dba4152299e0e0ad0d4480f02ca55c108d3fc7e5b70c966612799972a8b450fb24e5a74f4524e719d007994211fa903e6c5b76706012c9ba57f786b547e
+  metadata.gz: d92ea1c2016d7e81791a7d7b8d6a0cd631da001893227685297e570c86372dc905da89cf54641d85ef7715e6ffd5ae0498a8781714326352fc139cf5adae0320
+  data.tar.gz: bfd396eeac063d46053f15fc865f8444f8284dae480cee7f064809a43bb288cd48ebd7cf559d08d5d3f0f68c3252a360800a8a2f787c5b63e2a3c25601e8d555

data/docs/skill/SKILL.md

@@ -126,12 +126,17 @@ rescue => e
 end
 ```
 
+Attach context with `.extras({...})` before `.to`, or inline as
+`.to(outcome, {...})`. To attach it from anywhere without threading it into the
+rescue, buffer it earlier with `Shipeasy.add_extras(order_id: id)` — it merges
+into every see() report later in the same (fiber-local, per-request) scope.
+
 `Shipeasy.see_violation(name)` for non-exception problems;
 `Shipeasy.control_flow_exception(e).because(...)` marks expected control flow
 (reports nothing).
 
 → More: `pages/error-reporting.md` · snippets `snippets/ops/see.md`
-(`.extras`, violations, control-flow exceptions).
+(`.extras`, `add_extras`, violations, control-flow exceptions).
 
 ## i18n (Rails)
 
@@ -150,6 +155,7 @@ the loader tag (public client key).
 - Anon bucketing: `Shipeasy::SDK::RackMiddleware` mints the shared `__se_anon_id`
   cookie (Rails Railtie auto-mounts it); anonymous `get_flag` then just works.
 - `c.private_attributes = ["email"]` strips keys from outbound events.
+- `c.clean_backtrace` (default on) filters `see()` stacks to app frames via `Rails.backtrace_cleaner`; set `false` for raw backtraces.
 - `c.sticky_store = Shipeasy::SDK::InMemoryStickyStore.new` pins experiment assignment.
 - SSR: `Shipeasy.bootstrap_script_tag(user)` + `Shipeasy.i18n_script_tag(client_key, "en:prod")`.
 - `Shipeasy.on_change { ... }` (requires `c.poll = true`) fires after a poll fetches new data.

data/lib/shipeasy/config.rb

@@ -46,9 +46,14 @@ module Shipeasy
     #     swallows one of its OWN internal errors it normally ships a structured
     #     see event to Shipeasy's own project (NOT yours) so the SDK team can
     #     track SDK bugs; set true to disable that entirely.
+    #   - clean_backtrace (default true): pass see() error backtraces through the
+    #     host framework's own backtrace cleaner so reports carry only your
+    #     application frames (gem/framework noise stripped). We do not invent the
+    #     filtering rules — this leverages `Rails.backtrace_cleaner` and is a
+    #     no-op outside Rails. Set false to always report the raw backtrace.
     attr_accessor :env, :is_network_enabled, :disable_telemetry, :telemetry_url,
                   :private_attributes, :sticky_store,
-                  :disable_internal_error_reporting
+                  :disable_internal_error_reporting, :clean_backtrace
 
     # SDK-wide diagnostic verbosity for the leveled logger (Shipeasy::Logging).
     # One of :silent, :error, :warn (default), :info, :debug (strings accepted
@@ -103,6 +108,7 @@ module Shipeasy
       @is_network_enabled   = nil
       @disable_telemetry    = nil
       @disable_internal_error_reporting = false
+      @clean_backtrace      = true
       @telemetry_url        = nil
       @private_attributes   = nil
       @sticky_store         = nil
@@ -197,6 +203,7 @@ module Shipeasy
         sticky_store:       cfg.sticky_store,
         log_level:          cfg.log_level,
         disable_internal_error_reporting: cfg.disable_internal_error_reporting,
+        clean_backtrace:    cfg.clean_backtrace,
       )
       @engine = engine
       # Capture +engine+ in the closure (not the @engine ivar, which a concurrent
@@ -326,6 +333,17 @@ module Shipeasy
       Shipeasy::SDK.control_flow_exception(err)
     end
 
+    # Ambient per-request see() extras — attach context from anywhere that
+    # merges into every see() report firing later in the same request, so you
+    # never thread it into the rescue block. See Shipeasy::SDK.add_extras.
+    def add_extras(extras = nil, **kwargs)
+      Shipeasy::SDK.add_extras(extras, **kwargs)
+    end
+
+    def clear_extras
+      Shipeasy::SDK.clear_extras
+    end
+
     # Replace the registered global engine + attributes transform (used by the
     # configure_for_* siblings — unlike configure, they replace so a test suite
     # can reconfigure between cases). Returns the engine.

data/lib/shipeasy/engine.rb

@@ -36,7 +36,7 @@ module Shipeasy
       # /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", is_network_enabled: nil, disable_telemetry: nil, telemetry_url: nil, test_mode: false, private_attributes: nil, sticky_store: nil, log_level: nil, disable_internal_error_reporting: false)
+      def initialize(api_key:, base_url: nil, env: "prod", is_network_enabled: nil, disable_telemetry: nil, telemetry_url: nil, test_mode: false, private_attributes: nil, sticky_store: nil, log_level: nil, disable_internal_error_reporting: false, clean_backtrace: true)
         # SDK-wide diagnostic verbosity. Set the leveled logger from the passed
         # level (default :warn; unknown falls back to :warn). The logger is
         # module-scoped, so the last-built engine wins — mirrors the TS SDK,
@@ -52,6 +52,13 @@ module Shipeasy
         # 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)
+        # When true (default), see() error stacks are passed through the host
+        # framework's own backtrace cleaner so a report carries only application
+        # frames (gem/framework noise stripped). We never invent the filtering —
+        # today this leverages Rails.backtrace_cleaner and is a no-op outside
+        # Rails. Set false to always send the raw backtrace. See
+        # see_backtrace_cleaner.
+        @clean_backtrace = clean_backtrace != false
         # Pluggable sticky-bucketing store (doc 20 §2). Absent ⇒ deterministic.
         # Threaded into experiment eval so an enrolled unit locks to its first
         # assigned variant. Built-in: InMemoryStickyStore.
@@ -645,6 +652,7 @@ module Shipeasy
           strip_private(built.extras),
           sdk_version: Shipeasy::SDK::VERSION,
           env: @env,
+          backtrace_cleaner: see_backtrace_cleaner,
         )
         return unless @see_limiter.should_send?(ev)
 
@@ -658,6 +666,26 @@ module Shipeasy
         Shipeasy::Logging.error "[shipeasy] see() failed: #{e.message}"
       end
 
+      # The framework-provided backtrace cleaner used to strip gem/framework
+      # frames from see() stacks, or nil to send the raw backtrace. Resolved
+      # lazily (not memoized) because Rails installs its cleaner during boot,
+      # which can finish after Shipeasy.configure runs. Today the only supported
+      # cleaner is Rails' own `ActiveSupport::BacktraceCleaner` — we leverage it
+      # rather than reimplementing the app-vs-gem frame rules ourselves. Returns
+      # nil when disabled or when not running under Rails.
+      def see_backtrace_cleaner
+        return nil unless @clean_backtrace
+        return nil unless defined?(::Rails) && ::Rails.respond_to?(:backtrace_cleaner)
+
+        cleaner = ::Rails.backtrace_cleaner
+        return nil unless cleaner.respond_to?(:clean)
+
+        ->(bt) { cleaner.clean(bt) }
+      rescue StandardError
+        # Rails present but the cleaner blew up while resolving: fall back to raw.
+        nil
+      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)

data/lib/shipeasy/sdk/rack_middleware.rb

@@ -1,4 +1,5 @@
 require_relative "anon_id"
+require_relative "see"
 
 module Shipeasy
   module SDK
@@ -32,8 +33,10 @@ module Shipeasy
         begin
           status, headers, body = @app.call(env)
         ensure
-          # Don't leak the id onto the next request handled by this thread.
+          # Don't leak the id — or any ambient see() extras — onto the next
+          # request handled by this thread.
           AnonId.current = nil
+          See::Context.clear
         end
         set_cookie!(headers, id, env) if minted
         [status, headers, body]

data/lib/shipeasy/sdk/see.rb

@@ -12,11 +12,22 @@
 #
 # 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`:
+# /collect. `causes_the` and `extras` are chainable setters called *before*
+# `.to`; `.to` also accepts the extras inline as a second arg, so there is no
+# ordering trap to remember:
 #
 #   client.see(e).causes_the("checkout").to("use cached prices")
 #   client.see(e).causes_the("checkout").extras({ order_id: oid }).to("use cached prices")
+#   client.see(e).causes_the("checkout").to("use cached prices", { order_id: oid })
+#
+# `.extras` chained AFTER `.to` is ignored with a warning (the report already
+# went out) — it never raises into the rescue block.
+#
+# To attach context from anywhere in a request without threading it into the
+# rescue block, use the ambient buffer (see `Context` below):
+# `Shipeasy.add_extras(order_id: oid)` merges into EVERY see() report that fires
+# later in the same request. It is fiber-local (concurrent requests never bleed)
+# and the Rack middleware clears it at the end of each request.
 #
 # If you don't know the consequence of an exception, don't catch it.
 
@@ -110,7 +121,15 @@ module Shipeasy
       # ---- Wire event construction ----
 
       # Build the type:"error" event accepted by POST /collect.
-      def build_event(problem, subject, outcome, extras, sdk_version:, env:)
+      #
+      # `backtrace_cleaner` (optional) is a callable that takes the raw backtrace
+      # array and returns an application-only subset (framework/gem frames
+      # stripped) — e.g. `->(bt) { Rails.backtrace_cleaner.clean(bt) }`. It is
+      # applied before the stack is joined; if it strips every frame (a stack
+      # that is purely framework/gem code) we fall back to the raw backtrace so
+      # an error is never left with an empty stack. We never invent the filtering
+      # rules — the callable is supplied by the framework's own cleaner.
+      def build_event(problem, subject, outcome, extras, sdk_version:, env:, backtrace_cleaner: nil)
         stack = nil
 
         if problem.is_a?(Violation)
@@ -120,7 +139,7 @@ module Shipeasy
         elsif problem.is_a?(Exception)
           error_type = problem.class.name || "Error"
           message    = (problem.message.to_s.empty? ? error_type : problem.message)
-          bt = problem.backtrace
+          bt = clean_backtrace(problem.backtrace, backtrace_cleaner)
           stack = bt.join("\n") if bt && !bt.empty?
           kind = "caught"
         else
@@ -147,6 +166,21 @@ module Shipeasy
         ev
       end
 
+      # Apply the framework-provided backtrace cleaner to a raw backtrace,
+      # returning an application-only frame array. No cleaner (or no backtrace)
+      # ⇒ the input is returned untouched. If the cleaner raises, or strips every
+      # frame, fall back to the raw backtrace — a cleaned-to-empty stack would
+      # lose all debugging signal for an error that lives entirely in framework
+      # code. Never raises.
+      def clean_backtrace(bt, cleaner)
+        return bt if cleaner.nil? || bt.nil? || bt.empty?
+
+        cleaned = cleaner.call(bt)
+        cleaned && !cleaned.empty? ? cleaned : bt
+      rescue StandardError
+        bt
+      end
+
       # ---- Spam limiter (mirror SeeLimiter) ----
 
       # Per-process spam guard: identical events within 30s collapse to one
@@ -211,27 +245,65 @@ module Shipeasy
         end
         alias causesThe causes_the
 
+        # Attach debugging metadata. Chainable — call repeatedly (keys merge,
+        # later wins) *before* `.to`. Called after `.to` it is a no-op with a
+        # warning: the report already shipped, so there is nothing to amend and,
+        # crucially, it must not raise into the caller's rescue block. Use
+        # `.to(outcome, extras)` or `Shipeasy.add_extras` for late/scattered
+        # context instead.
         def extras(extras)
-          if extras.is_a?(Hash) && !extras.empty?
-            @extras = (@extras || {}).merge(extras)
+          if @done
+            Shipeasy::Logging.warn(
+              "[shipeasy] see() .extras(...) called after .to(...) is ignored — " \
+              "pass extras to .to(outcome, extras) or call .extras before .to"
+            )
+            return self
           end
+          merge_extras(extras)
           self
         end
 
         # Terminal: build the event and fire-and-forget the report. Idempotent.
-        def to(outcome)
-          return if @done
+        # `extras` may be passed inline here as the trailing form
+        # `.to(outcome, { order_id: oid })` — merged like a final `.extras` call.
+        # Returns self so a stray trailing `.extras` chains harmlessly.
+        def to(outcome, extras = nil)
+          return self if @done
 
+          merge_extras(extras) unless extras.nil?
           @done = true
           @outcome = outcome.to_s
           begin
             @dispatch.call(
-              Built.new(@problem, @subject || DEFAULT_SUBJECT, @outcome.empty? ? DEFAULT_OUTCOME : @outcome, @extras)
+              Built.new(@problem, @subject || DEFAULT_SUBJECT, @outcome.empty? ? DEFAULT_OUTCOME : @outcome, resolved_extras)
             )
           rescue StandardError
             # Reporting must never raise into caller code.
             nil
           end
+          self
+        end
+
+        private
+
+        def merge_extras(extras)
+          return unless extras.is_a?(Hash) && !extras.empty?
+
+          @extras = (@extras || {}).merge(extras)
+        end
+
+        # The chain's own extras merged OVER the ambient per-request buffer, so a
+        # chained key of the same name wins over an ambient one. Keys normalized
+        # to strings only when a merge actually happens; sanitize_extras
+        # stringifies the rest at build time.
+        def resolved_extras
+          ambient = Context.current
+          return @extras if ambient.empty?
+          return ambient if @extras.nil? || @extras.empty?
+
+          out = ambient.dup
+          @extras.each { |k, v| out[k.to_s] = v }
+          out
         end
       end
 
@@ -265,6 +337,8 @@ module Shipeasy
       end
 
       # A no-op chain returned by the module-level see() when no client exists.
+      # Every method returns self so the full grammar — including a trailing
+      # `.extras` after `.to` — chains without ever raising.
       class NullChain
         def causes_the(_subject)
           self
@@ -275,8 +349,53 @@ module Shipeasy
           self
         end
 
-        def to(_outcome)
+        def to(_outcome, _extras = nil)
+          self
+        end
+      end
+
+      # ---- Ambient per-request extras -------------------------------------
+
+      # A per-request buffer of extras that merge into EVERY see() report firing
+      # later in the same execution context. Lets a request attach context
+      # (order id, route, tenant) from anywhere without threading it into the
+      # rescue block: `Shipeasy.add_extras(order_id: oid)` here, and any
+      # subsequent `see()` in this request carries it.
+      #
+      # Fiber-local (like AnonId), so concurrent requests never bleed into each
+      # other. The Rack middleware clears it in an `ensure` at the end of each
+      # request; outside a Rack request (jobs, scripts) call
+      # `Shipeasy.clear_extras` yourself when a logical unit of work ends.
+      #
+      # Values are stored raw and sanitized (scalar-only, truncated, 20-key cap,
+      # private-attribute stripped) at build time, exactly like chained extras.
+      module Context
+        THREAD_KEY = :shipeasy_see_ambient_extras
+
+        module_function
+
+        # Merge fields into the current context's buffer (string keys, later
+        # wins). Non-hash / empty input is ignored. Never raises.
+        def add(extras)
+          return unless extras.is_a?(Hash) && !extras.empty?
+
+          buf = (Thread.current[THREAD_KEY] ||= {})
+          extras.each { |k, v| buf[k.to_s] = v }
           nil
+        rescue StandardError
+          nil
+        end
+
+        # A copy of the current context's buffer, or {} when empty.
+        def current
+          buf = Thread.current[THREAD_KEY]
+          buf.nil? || buf.empty? ? {} : buf.dup
+        end
+
+        # Drop the current context's buffer so extras never leak to the next
+        # request handled by this thread/fiber.
+        def clear
+          Thread.current[THREAD_KEY] = nil
         end
       end
     end

data/lib/shipeasy/sdk/version.rb

@@ -1,5 +1,5 @@
 module Shipeasy
   module SDK
-    VERSION = "3.3.0"
+    VERSION = "3.5.0"
   end
 end

data/lib/shipeasy-sdk.rb

@@ -76,5 +76,34 @@ module Shipeasy
     def self.control_flow_exception(err)
       See::ControlFlowChain.new(err)
     end
+
+    # ---- ambient per-request see() extras -------------------------------
+    #
+    # Attach context that merges into every see() report firing later in this
+    # request, from anywhere — no need to thread it into the rescue block:
+    #
+    #   Shipeasy::SDK.add_extras(order_id: order.id, tenant: tenant.slug)
+    #   # ...later, somewhere else in the same request...
+    #   rescue => e
+    #     Shipeasy::SDK.see(e).causes_the("checkout").to("use cached prices")
+    #     # ^ report carries order_id + tenant automatically
+    #
+    # Fiber-local, so concurrent requests never bleed. The Rack middleware
+    # clears the buffer per request (Rails auto-mounts it); outside Rack, call
+    # `clear_extras` when a unit of work ends. Accepts a hash and/or keywords.
+    # Works with no client configured (it only writes the buffer); never raises.
+    def self.add_extras(extras = nil, **kwargs)
+      merged = {}
+      merged.merge!(extras) if extras.is_a?(Hash)
+      merged.merge!(kwargs) unless kwargs.empty?
+      See::Context.add(merged)
+      nil
+    end
+
+    # Drop the ambient extras buffer for the current request/context.
+    def self.clear_extras
+      See::Context.clear
+      nil
+    end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: shipeasy-sdk
 version: !ruby/object:Gem::Version
-  version: 3.3.0
+  version: 3.5.0
 platform: ruby
 authors:
 - Shipeasy, Inc.
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-07-10 00:00:00.000000000 Z
+date: 2026-07-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec