shipeasy-sdk 3.1.1 → 3.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e515d6b49fbcc5b0f080ff849666e2ddea3f1d5819b8fa3298755190d32cacb4
-  data.tar.gz: 12b01b42ade6f5ee60ade42e4f6ee8af1bcb26999086499cefc3d6a4c39ee575
+  metadata.gz: 60cefd35bba21f86ef6b77da83d0c918744721d9c564066b12e8d2b95dba8740
+  data.tar.gz: 22b03ac85fbd29bba861770120c2a78bbcbc5069e0e7af0cbe8b1c33b8ebee88
 SHA512:
-  metadata.gz: 73ad05284d98820cbd2adcb19d7b9e8d4fff78b96f75e236f0c1f66722a492653eb356ab371e65c1e25919b29d63f1483c241aafa9d9a6bb2c513a15fc3a3e8b
-  data.tar.gz: 483dfab6644615b3f2774afed8182f6be4267d8f5302b58bc2fe5bf1edfce1d4cdf26b4587f5ff37a7b6eb52c1d6d57bb0434d789e047cf72f36206522102c03
+  metadata.gz: 226eccc8d981ce982ed132eb697c39e37cde9f9d62d9f84970cea6119601696383520bc1f03606abd58b81574be31d26962aedf2e000acfe45e1ac7bdb2c5f2c
+  data.tar.gz: 1e213dba4152299e0e0ad0d4480f02ca55c108d3fc7e5b70c966612799972a8b450fb24e5a74f4524e719d007994211fa903e6c5b76706012c9ba57f786b547e

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
 ```

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
 

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

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