shipeasy-sdk 3.1.1 → 3.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e515d6b49fbcc5b0f080ff849666e2ddea3f1d5819b8fa3298755190d32cacb4
-  data.tar.gz: 12b01b42ade6f5ee60ade42e4f6ee8af1bcb26999086499cefc3d6a4c39ee575
+  metadata.gz: c1b1f478bea3279f979e85e04476381f719d3db27aa29ffb23447768ceefc560
+  data.tar.gz: c0d4f8f1ca49a6a1b34ac3b1198a3788dc115f640eb5845fb388a66175e1384c
 SHA512:
-  metadata.gz: 73ad05284d98820cbd2adcb19d7b9e8d4fff78b96f75e236f0c1f66722a492653eb356ab371e65c1e25919b29d63f1483c241aafa9d9a6bb2c513a15fc3a3e8b
-  data.tar.gz: 483dfab6644615b3f2774afed8182f6be4267d8f5302b58bc2fe5bf1edfce1d4cdf26b4587f5ff37a7b6eb52c1d6d57bb0434d789e047cf72f36206522102c03
+  metadata.gz: 94790b0a88b1524f35faf706245339db83908565b5adec3a7f8b9f5775d476cb703ce00ac55a697d79a343a1abe0c94145c2fd693538c1aecbdab81385525148
+  data.tar.gz: f35b460dd560167674a1a278c1e76600fd59040016ad06b3129ee77c5dd95d68d57d0c7695ca06dee7f7870f15489655ee20ca644b6d1a24d416fdf280c2daf7

data/docs/skill/SKILL.md

@@ -60,9 +60,9 @@ flags.get_killswitch("payments")             # true = killed; optional switch_ke
 
 # Ask the UNIVERSE, not the experiment. Returns an Assignment (never raises):
 #   .name / .group  → nil when not enrolled ·  .enrolled?  → group non-nil
-#   .get(field, fallback = nil) → variant override ?? universe default ?? fallback
-assignment = flags.universe("checkout").assign   # auto-logs one deduped exposure when enrolled
-render_cta(assignment.get("label", "Buy now"))
+#   .get(field, fallback = nil, exposure: true) → variant override ?? universe default ?? fallback
+assignment = flags.universe("checkout").assign   # side-effect free; exposure fires on first get read
+render_cta(assignment.get("label", "Buy now"))    # first read logs one deduped exposure (exposure: false to peek)
 
 flags.track("purchase", { revenue: 49 })     # conversion / metric event
 ```
@@ -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)
 

data/lib/shipeasy/config.rb

@@ -85,6 +85,13 @@ module Shipeasy
                   :cdn_base_url, :loader_url,
                   :manifest_cache_ttl, :label_file_cache_ttl, :http_timeout
 
+    # When true, `i18n_t` renders the translation KEY verbatim instead of
+    # resolving its value, so tests/snapshots assert against stable data instead
+    # of copy that changes when a translation is edited. nil (default) ⇒
+    # env-derived: on when the native env is "test" (RAILS_ENV / RACK_ENV /
+    # SHIPEASY_ENV / APP_ENV), off otherwise. Set true/false to override.
+    attr_accessor :render_keys_only
+
     def initialize
       @base_url             = "https://api.shipeasy.ai"
       @attributes           = nil
@@ -108,6 +115,16 @@ module Shipeasy
       @manifest_cache_ttl   = 60
       @label_file_cache_ttl = 3600
       @http_timeout         = 1
+      # nil ⇒ env-derived (on under RAILS_ENV/…=="test"); true/false overrides.
+      @render_keys_only     = nil
+    end
+
+    # Resolve the effective render_keys_only decision: an explicit true/false set
+    # in the configure block wins; otherwise default to env==test.
+    def render_keys_only?
+      return @render_keys_only unless @render_keys_only.nil?
+
+      Shipeasy::SDK::Env.is_test_env
     end
   end
 
@@ -309,6 +326,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

@@ -350,8 +350,13 @@ module Shipeasy
           candidates.each do |name, exp|
             result = eval_experiment(name, exp, u, flags_blob, exps_blob)
             next unless result.in_experiment
-            post_exposure(u, name, result.group)
-            landed = Eval::Assignment.new(name, result.group, result.params || {})
+            group = result.group
+            # On-read exposure (spec step 7): defer the single exposure to the
+            # first param read via the callback, instead of firing it here at
+            # assign time.
+            landed = Eval::Assignment.new(name, group, result.params || {}, lambda {
+              post_exposure(u, name, group)
+            })
             break
             # not enrolled: try the next candidate — under pooling only one slice
             # can match, so the loop lands on the winner (or falls through).

data/lib/shipeasy/i18n/view_helpers.rb

@@ -34,6 +34,10 @@ module Shipeasy
 
       def i18n_t(key, variables = {}, profile: nil, chunk: nil)
         config = Shipeasy.config
+        # render_keys_only (default: env==test): return the key verbatim,
+        # skipping value resolution + interpolation so tests assert stable data.
+        return key if config.render_keys_only?
+
         label_file = Shipeasy::I18n::LabelFetcher.new.fetch(
           profile: profile || config.profile,
           chunk:   chunk   || config.default_chunk,

data/lib/shipeasy/sdk/env.rb

@@ -38,6 +38,14 @@ module Shipeasy
         (configured_env || "prod").to_s.strip.downcase == "prod"
       end
 
+      # True when the host runtime looks like a test run — the first present
+      # native env var (SHIPEASY_ENV / RAILS_ENV / RACK_ENV / APP_ENV) is exactly
+      # "test" (what Rails/RSpec set). Used to default i18n render_keys_only on
+      # under test. No native var present ⇒ not test.
+      def is_test_env
+        read_native_env == "test"
+      end
+
       # Read the first present native env var (lowercased, trimmed), or nil when
       # none of them is set to a non-empty value.
       def read_native_env

data/lib/shipeasy/sdk/eval.rb

@@ -125,6 +125,28 @@ module Shipeasy
       # universe assign() path share ONE classify. The added steps are all guarded
       # by presence checks, so a legacy blob (no hashVersion/pool/reserved) behaves
       # exactly as before.
+      # Resolve a forced override group for +uid+ (spec step 1): ID overrides
+      # (tier 1) beat cohort/GK overrides (tier 2); within cohort overrides the
+      # first (pre-sorted by priority) gate that passes wins. Returns the forced
+      # group name or nil. The caller applies eligibility + group-existence
+      # (forced-but-gated). Mirrors @shipeasy/core resolveForcedGroup.
+      def self.resolve_forced_group(exp, uid, flags_blob, user)
+        id_overrides = exp["idOverrides"] || exp[:idOverrides]
+        if id_overrides
+          by_id = id_overrides[uid]
+          return by_id if by_id && !by_id.to_s.empty?
+        end
+        cohort_overrides = exp["cohortOverrides"] || exp[:cohortOverrides]
+        if cohort_overrides
+          cohort_overrides.each do |co|
+            gname = co["gate"] || co[:gate]
+            gate = flags_blob&.dig("gates", gname)
+            return (co["group"] || co[:group]) if gate && eval_gate(gate, user)
+          end
+        end
+        nil
+      end
+
       def self.eval_experiment(exp, flags_blob, exps_blob, user, exp_name: nil, sticky_store: nil)
         universe_name  = exp && exp["universe"]
         universe       = exps_blob&.dig("universes", universe_name)
@@ -172,6 +194,21 @@ module Shipeasy
         groups = exp["groups"] || []
         salt8 = (salt || "")[0, 8]
 
+        # Durable overrides (spec step 1, forced-but-gated). Reached only after the
+        # unit passes targeting and is not held out, so an override may now pin the
+        # group — bypassing allocation + the weighted pick but NOT the gates above.
+        # ID overrides (tier 1) beat cohort/GK overrides (tier 2); a forced group
+        # that no longer exists falls through to normal allocation. No-op when
+        # unconfigured, so v1/v2 stay byte-identical. Mirrors @shipeasy/core.
+        forced = resolve_forced_group(exp, uid, flags_blob, user)
+        if forced
+          g = groups.find { |x| x["name"] == forced }
+          if g
+            sticky_store.set(uid, exp_name, { "g" => forced, "s" => salt8 }) if sticky_store && exp_name
+            return as_group.call(g)
+          end
+        end
+
         # 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.
@@ -232,14 +269,19 @@ module Shipeasy
         attr_reader :group
 
         # +params+ is already merged (universeDefaults ⊕ variantOverride) when
-        # enrolled; defaults-only (or {}) when not.
-        def initialize(name, group, params)
-          @name   = name
-          @group  = group
-          @params = params || {}
+        # enrolled; defaults-only (or {}) when not. +on_expose+ fires the single
+        # exposure the first time an enrolled param is read (nil when not
+        # enrolled — nothing to expose); deduped downstream.
+        def initialize(name, group, params, on_expose = nil)
+          @name      = name
+          @group     = group
+          @params    = params || {}
+          @on_expose = on_expose
+          @exposed   = false
         end
 
         # True iff the unit is enrolled in an experiment in this universe.
+        # Reading it does NOT log an exposure (only +get+ of a param does).
         def enrolled?
           !@group.nil?
         end
@@ -248,7 +290,15 @@ module Shipeasy
         # universe default, else +fallback+. Works even when not enrolled (the
         # variant layer is absent, so you get universeDefault ?? fallback).
         # Looks up both string and symbol keys.
-        def get(field, fallback = nil)
+        #
+        # Exposure is logged **on read** (spec step 7): the first enrolled read
+        # fires the single exposure; pass +exposure: false+ to read without
+        # logging (peek).
+        def get(field, fallback = nil, exposure: true)
+          if exposure && !@exposed && @on_expose
+            @exposed = true
+            @on_expose.call
+          end
           if @params.key?(field)
             @params[field]
           elsif field.respond_to?(:to_s) && @params.key?(field.to_s)

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.
 
@@ -211,27 +222,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 +314,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,9 +326,54 @@ 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
   end

data/lib/shipeasy/sdk/version.rb

@@ -1,5 +1,5 @@
 module Shipeasy
   module SDK
-    VERSION = "3.1.1"
+    VERSION = "3.4.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.1.1
+  version: 3.4.0
 platform: ruby
 authors:
 - Shipeasy, Inc.
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-07-08 00:00:00.000000000 Z
+date: 2026-07-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec