convert_sdk 2.0.0 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4971b19e554964f05a8c86555b919d102492a09190eac1747567177f375dc29e
-  data.tar.gz: b4a91c4ab52075f0268aa1f138989f406d4f9166f7cd06f859ea879a4f7e2975
+  metadata.gz: 01f414eebe47b8979033ef84e6d1f6c8c36147fce4075ca95258ddd3f8158e75
+  data.tar.gz: '01794d5e51f41191f2402fc0327e6d979f140b9fd105db70b140fb277dc3e513'
 SHA512:
-  metadata.gz: 288df65beff1f18b3dbe25334e31e852222705c0786113cb56fbd3a253ffc5edcfba335a00258c062ea7faf34728afd5e26ecd234f7df305cb74e043275e962b
-  data.tar.gz: 2ee04c45261064677c2cd2da5bd4a89e06747f39cf172a9d02a87a976ef167d48b7ddafaa5df3b1c1ad9961e5e7fced4d636313f9645dd5ac2b0bf670f9c748e
+  metadata.gz: ce9300fe59f844d33189e40c6c9532a9f71bcff6f73ab087d41839a9572b543ddfc1a1ebdfabf9bc868a29ab810ad80a88672f1ca923bc2f4c8aa221727826af
+  data.tar.gz: b2e48b3667a3f4597af73c09e143b1f6912561cadacd4aba6ca24f11092ad85493c7f24fd948221da356e1ec0e36285a8d8e2762f9aafdce726137c2602cd55c

data/RELEASE.md

@@ -202,13 +202,15 @@ Releases are fully automatic. The process:
 
 semantic-release checks the current branch against the `branches` entry in
 `release.config.mjs` (currently `['main']`). On `main`, the dry-run prints the
-next-version plan. On any other branch it exits with:
+next-version plan. On any other branch it stops with:
 
 ```
-This test run was not triggered in a known release branch
+This test run was triggered on the branch <your-branch>, while semantic-release
+is configured to only publish from main, therefore a new version won’t be published.
 ```
 
-That message is **expected** — it confirms the config parses. To exercise a full
+That message is **expected** — it confirms the config parses and every plugin in
+the chain loaded. To exercise a full
 dry-run on a feature branch, temporarily add the branch name to
 `release.config.mjs`'s `branches` array, run the dry-run, then discard the
 temporary edit before committing:
@@ -308,6 +310,6 @@ through:
 | Release ran but published nothing | No release-worthy commit since the last tag (only `chore`/`docs`/`ci`/`test`/`style`/`perf`). | Expected — semantic-release succeeds silently with no version. Land a `feat:`/`fix:` to publish. |
 | `gem push` failed / no RubyGems credential | The RubyGems Trusted Publisher is not registered (or the repo/workflow filename in the registration doesn't match `convertcom/ruby-sdk` ↔ `release.yml`). | Re-check the trusted-publisher entry on rubygems.org (One-Time Setup step 1). The workflow needs `id-token: write` (it has it) and the OIDC exchange step must run before semantic-release. |
 | GitHub Release/tag created but gem missing | Should not happen — publish runs before the Release (publish-before-Release). If you see it, a manual tag was likely pushed out of band. | Do not hand-create `v*` tags. Let the pipeline own tagging. |
-| `yarn release:dry-run` errors "This test run was not triggered in a known release branch" | Expected on any branch except `main`. | To force a full dry-run on a feature branch, temporarily add the branch to `release.config.mjs`'s `branches` array (discard before committing). On `main`, this means the local branch isn't pushed to `origin` — push first. |
+| `yarn release:dry-run` stops with "This test run was triggered on the branch …, while semantic-release is configured to only publish from `main`" | Expected on any branch except `main`. | To force a full dry-run on a feature branch, temporarily add the branch to `release.config.mjs`'s `branches` array (discard before committing). On `main`, this means the local branch isn't pushed to `origin` — push first. |
 | `Cannot find module '<preset>'` from a semantic-release plugin | The yarn node linker isn't producing a `node_modules/` tree the dynamic preset import can walk. | Confirm `.yarnrc.yml` selects the `node-modules` linker and re-run `yarn install --immutable`. |
 | Forbidden release mechanism reintroduced (lint job fails) | A `@semantic-release/git`/`@semantic-release/changelog` plugin, a `rake release` task, `bundler/gem_tasks`, or `rubygems/release-gem` was added. | These are blocked by the release-safety step in the `Lint (RuboCop)` job. Remove the forbidden mechanism — publishing happens only via OIDC `release.yml`. |

data/lib/convert_sdk/context.rb

@@ -46,6 +46,29 @@ module ConvertSdk
   # (+nil+ for lookups, +self+ for the chainable mutator). A raising collaborator
   # degrades the call; it never crashes the host request.
   class Context
+    # The reserved keys the public per-call hash accepts (CAP-3): a +:merged_map+ row
+    # lands in the engine envelope at +destination+, a +:raw_per_call+ row in that reader.
+    RESERVED_KEYS = {
+      "location_properties" => { source: :merged_map, destination: :location_properties,
+                                 scope: "every decision entry point" },
+      "environment" => { source: :merged_map, destination: :environment,
+                         scope: "every decision entry point" },
+      "enable_tracking" => { source: :raw_per_call, destination: :tracking_enabled_for_call,
+                             scope: "honoured on run_experience(s), accepted inert on run_feature(s)" },
+      "experience_keys" => { source: :raw_per_call, destination: :experiences,
+                             scope: "run_feature(s) only; narrows the experiences decided (CAP-1)" },
+      "type_casting" => { source: :raw_per_call, destination: :type_casting,
+                          scope: "run_feature(s) only; false returns the config-stored variables (CAP-2)" },
+      "ruleData" => { source: :raw_per_call, destination: :visitor_properties,
+                      scope: "run_custom_segments only; camelCase on a snake_case surface (SD-4)" }
+    }.freeze
+
+    # Engine-readable keys the seam never lifts, each with its reason (CAP-3's negative list).
+    NOT_LIFTED = {
+      "enable_storage" => "preview owns the persistence gate (D-4)",
+      "update_visitor_properties" => "documented Ruby divergence (D-5)"
+    }.freeze
+
     # @param visitor_id [String] the resolved visitor id (validated non-blank by
     #   {Client#create_context} before construction).
     # @param attributes [Hash, nil] the per-visitor attributes; deep-stringified
@@ -357,9 +380,12 @@ module ConvertSdk
     # {SystemEvents::BUCKETING} event, exactly as {#run_experience}'s forced
     # branch returns before {#fire_bucketing}. Every OTHER decided variation is
     # zero-trace like {#run_experience}'s other-experience branch:
-    # {#decision_attributes} suppresses the sticky persist and the tracking
-    # verdict is forced +false+, while the {SystemEvents::BUCKETING} event still
-    # fires per variation (see {#run_experience}'s doc for the Ruby/JS divergence).
+    # {#decision_attributes} suppresses the sticky persist, the tracking verdict
+    # is forced +false+ so the outbound enqueue is skipped, and
+    # {#fire_bucketing}'s +@preview.nil?+ guard suppresses the
+    # {SystemEvents::BUCKETING} event as well — NO event fires for ANY
+    # experience on a preview-active context (JS parity — +context.ts:260+:
+    # +if (!this._preview) { fire BUCKETING }+).
     #
     # @param attributes [Hash, nil] optional per-call visitor properties merged
     #   over the context attributes (deep-stringified). May carry +:enable_tracking+.
@@ -402,23 +428,30 @@ module ConvertSdk
     #     render_legacy_checkout
     #   end
     #
-    # NOTE (accepted parity break): JS +runFeature+ accepts an optional
-    # +experienceKeys+ filter argument; this Ruby surface intentionally OMITS it
-    # (deferred feature). Resolution always spans all configured experiences.
+    # A per-call +experience_keys+ Array narrows which experiences are decided,
+    # and so which sticky assignments the read commits (CAP-1); absent, nil or
+    # empty decides every configured experience (D-6).
+    # A per-call +type_casting+ of +false+ returns variables as config stores them (CAP-2).
+    #
+    # NOTE (accepted parity break): +type_casting: nil+ leaves casting ON here,
+    # where the JS presence-based rule would disable it (D-8).
     #
     # Never raises into the host: an internal failure degrades to a DISABLED
     # {BucketedFeature} (carrying the requested key) + an +error+ log (NFR9).
     #
     # @param key [String] the feature +key+ to evaluate.
-    # @param attributes [Hash, nil] optional per-call visitor properties merged
-    #   over the context attributes (deep-stringified).
+    # @param attributes [Hash, nil] optional per-call visitor properties merged over
+    #   the context attributes (deep-stringified). May carry +:experience_keys+
+    #   (CAP-1) and +:type_casting+ (CAP-2); only a boolean +false+ disables casting (D-8).
     # @return [BucketedFeature, Array<BucketedFeature>] the resolved feature(s).
     def run_feature(key, attributes = nil)
       manager = @feature_manager
       return disabled_feature(key) if manager.nil?
 
       @data_manager.ensure_fresh_config!
-      manager.run_feature(@visitor_id, key, decision_attributes(attributes))
+      manager.run_feature(@visitor_id, key, decision_attributes(attributes),
+                          experiences: experience_keys_for_call(attributes),
+                          type_casting: type_casting_for_call?(attributes))
     rescue StandardError => e
       @log_manager.error("Context#run_feature: #{e.class}: #{e.message}")
       disabled_feature(key)
@@ -437,15 +470,18 @@ module ConvertSdk
     # Never raises into the host: an internal failure degrades to +[]+ + an
     # +error+ log (NFR9).
     #
-    # @param attributes [Hash, nil] optional per-call visitor properties merged
-    #   over the context attributes (deep-stringified).
+    # @param attributes [Hash, nil] optional per-call visitor properties merged over
+    #   the context attributes (deep-stringified). May carry +:experience_keys+
+    #   (CAP-1) and +:type_casting+ (CAP-2); only a boolean +false+ disables casting (D-8).
     # @return [Array<BucketedFeature>] the resolved features (enabled + disabled).
     def run_features(attributes = nil)
       manager = @feature_manager
       return [] if manager.nil?
 
       @data_manager.ensure_fresh_config!
-      manager.run_features(@visitor_id, decision_attributes(attributes))
+      manager.run_features(@visitor_id, decision_attributes(attributes),
+                           experiences: experience_keys_for_call(attributes),
+                           type_casting: type_casting_for_call?(attributes))
     rescue StandardError => e
       @log_manager.error("Context#run_features: #{e.class}: #{e.message}")
       []
@@ -623,11 +659,16 @@ module ConvertSdk
 
     # {#run_experiences}'s preview branch, extracted to keep #run_experiences
     # within RuboCop's ABC/complexity budget: drop the previewed experience's
-    # normally-decided entry (so it fires no BUCKETING event for the overridden
-    # decision), fire every OTHER experience's event with tracking suppressed,
-    # then append the forced variation. A defensive Sentinel from
-    # {#forced_preview_variation} (set_preview pre-validates, so not expected)
-    # appends nothing.
+    # normally-decided entry (the forced decision replaces it), route every
+    # OTHER experience through {#fire_bucketing} with +track: false+, then
+    # append the forced variation. On a preview-active context that
+    # {#fire_bucketing} call is inert BY DESIGN — its +@preview.nil?+ guard
+    # suppresses the {SystemEvents::BUCKETING} event and +track: false+
+    # suppresses the enqueue, so all it emits is the +debug+ suppression line.
+    # The seam is kept rather than skipped so the zero-trace verdict stays
+    # enforced at the SINGLE bucketing site instead of being duplicated here.
+    # A defensive Sentinel from {#forced_preview_variation} (set_preview
+    # pre-validates, so not expected) appends nothing.
     def force_preview_in_run_all(variations, preview)
       others = variations.reject { |variation| variation.experience_key == preview[:experience_key] }
       others.each { |variation| fire_bucketing(variation.experience_key, variation, track: false) }
@@ -706,7 +747,8 @@ module ConvertSdk
     # per-call +ruleData+ (and context attributes) win over stored segments. All
     # deep-stringified to string keys (the rule engine reads string keys).
     def visitor_properties(attributes)
-      rule_data = attributes.is_a?(Hash) ? (attributes[:ruleData] || attributes["ruleData"]) : nil
+      key = reserved_key_name(:visitor_properties)&.to_s
+      rule_data = key && attributes.is_a?(Hash) ? attributes[key.to_sym] || attributes[key] : nil
       empty = {} #: Hash[String, untyped]
       merged = @attributes.merge(deep_stringify(rule_data || empty))
       stored = get_visitor_data["segments"]
@@ -738,12 +780,43 @@ module ConvertSdk
     # byte-identical to the pre-qs-03 behavior.
     def decision_attributes(per_call)
       merged = @attributes.merge(deep_stringify(per_call || {}))
-      {
-        visitor_properties: merged,
-        location_properties: merged["location_properties"],
-        environment: merged["environment"],
-        enable_storage: @preview.nil?
-      }
+      envelope = { visitor_properties: merged } #: Hash[Symbol, untyped]
+      reserved_rows(:merged_map).each { |name, fields| envelope[fields[:destination]] = merged[name.to_s] }
+      envelope[:enable_storage] = @preview.nil?
+      envelope
+    end
+
+    def reserved_rows(source)
+      RESERVED_KEYS.reject { |name, fields| NOT_LIFTED.key?(name.to_s) || fields[:source] != source }
+    end
+
+    # The per-call key name the enumeration routes to +destination+, nil when none does.
+    def reserved_key_name(destination)
+      row = reserved_rows(:raw_per_call).find { |_, fields| fields[:destination] == destination }
+      row&.first
+    end
+
+    # The per-call experience-key filter (CAP-1). A non-Array value degrades to
+    # no filter with a +warn+ (SD-2); nil is absence and never warns.
+    def experience_keys_for_call(attributes)
+      key = reserved_key_name(:experiences)&.to_s
+      return nil unless key && attributes.is_a?(Hash)
+
+      value = attributes.fetch(key.to_sym) { attributes.fetch(key, nil) }
+      return value if value.nil? || value.is_a?(Array)
+
+      @log_manager.warn("Context#run_feature: #{key} must be an Array, got #{value.class} — ignoring it")
+      nil
+    end
+
+    # The per-call casting switch (CAP-2): only an explicit +false+ turns it off (D-8).
+    def type_casting_for_call?(attributes)
+      return true unless attributes.is_a?(Hash)
+
+      key = reserved_key_name(:type_casting)&.to_s
+      return true if key.nil?
+
+      attributes.fetch(key.to_sym) { attributes.fetch(key, true) } != false
     end
 
     # The single named seam fired once per fresh/decided variation. It does TWO
@@ -809,7 +882,10 @@ module ConvertSdk
     def tracking_enabled_for_call?(attributes)
       return true unless attributes.is_a?(Hash)
 
-      value = attributes.fetch(:enable_tracking) { attributes.fetch("enable_tracking", true) }
+      key = reserved_key_name(:tracking_enabled_for_call)&.to_s
+      return true if key.nil?
+
+      value = attributes.fetch(key.to_sym) { attributes.fetch(key, true) }
       value != false
     end
 

data/lib/convert_sdk/feature_manager.rb

@@ -84,16 +84,20 @@ module ConvertSdk
     # @param feature_key [String] the feature +key+ to resolve.
     # @param attributes [Hash] bucketing attributes (+:visitor_properties+,
     #   +:location_properties+, +:environment+) — see {DataManager#get_bucketing}.
+    # @param experiences [Array<String>, nil] optional experience-key filter
+    #   narrowing which experiences are decided (CAP-1); nil/empty means all.
+    # @param type_casting [Boolean] +false+ returns variables as config stores them (CAP-2).
     # @return [BucketedFeature, Array<BucketedFeature>] enabled feature(s) or a
     #   frozen DISABLED {BucketedFeature} on a miss.
-    def run_feature(visitor_id, feature_key, attributes = {})
+    def run_feature(visitor_id, feature_key, attributes = {}, experiences: nil, type_casting: true)
       declared = @data_manager.feature_by_key(feature_key)
       unless declared
         @log_manager&.debug("FeatureManager#run_feature: feature not declared key=#{feature_key}")
         return disabled_feature(key: feature_key)
       end
 
-      enabled = run_features(visitor_id, attributes, features: [feature_key])
+      enabled = run_features(visitor_id, attributes,
+                             experiences: experiences, features: [feature_key], type_casting: type_casting)
       if enabled.empty?
         @log_manager&.debug("FeatureManager#run_feature: not bucketed into a carrying variation key=#{feature_key}")
         return disabled_from_declared(declared)
@@ -119,12 +123,13 @@ module ConvertSdk
     # @param experiences [Array<String>, nil] optional experience-key filter.
     # @param features [Array<String>, nil] optional feature-key filter (suppresses
     #   the DISABLED padding).
+    # @param type_casting [Boolean] +false+ skips the per-variable conversion (CAP-2).
     # @return [Array<BucketedFeature>] the resolved features.
-    def run_features(visitor_id, attributes = {}, experiences: nil, features: nil)
+    def run_features(visitor_id, attributes = {}, experiences: nil, features: nil, type_casting: true)
       declared_by_id = features_by_id
       variations = bucketed_variations(visitor_id, attributes, experiences)
 
-      bucketed = collect_enabled(variations, declared_by_id, features)
+      bucketed = collect_enabled(variations, declared_by_id, features, type_casting: type_casting)
 
       # Pad with DISABLED features ONLY when no feature filter is supplied.
       append_disabled(bucketed, declared_by_id) if features.nil?
@@ -179,11 +184,12 @@ module ConvertSdk
     # Walk every bucketed variation's +fullStackFeature+ changes, mapping each to
     # its declared feature (by id), casting the variables, and building an ENABLED
     # {BucketedFeature}. Honours the optional +feature_keys+ filter.
-    def collect_enabled(variations, declared_by_id, feature_keys)
+    def collect_enabled(variations, declared_by_id, feature_keys, type_casting: true)
       bucketed = [] #: Array[BucketedFeature]
       variations.each do |variation|
         feature_changes(variation).each do |change|
-          feature = enabled_feature_from_change(variation, change, declared_by_id, feature_keys)
+          feature = enabled_feature_from_change(variation, change, declared_by_id, feature_keys,
+                                                type_casting: type_casting)
           bucketed << feature if feature
         end
       end
@@ -208,13 +214,14 @@ module ConvertSdk
 
     # Build the ENABLED {BucketedFeature} for one feature change, or nil when the
     # change has no feature_id, the feature is undeclared, or it is filtered out.
-    def enabled_feature_from_change(variation, change, declared_by_id, feature_keys)
+    def enabled_feature_from_change(variation, change, declared_by_id, feature_keys, type_casting: true)
       data = change["data"]
       declared = declared_for_change(data, declared_by_id)
       return nil if declared.nil?
       return nil if filtered_out?(declared, feature_keys)
 
-      build_enabled(variation, declared, cast_variables(declared, data["variables_data"]))
+      variables = cast_variables(declared, data["variables_data"], type_casting: type_casting)
+      build_enabled(variation, declared, variables)
     end
 
     # The declared feature a feature-change maps to (by data.feature_id), or nil
@@ -239,7 +246,8 @@ module ConvertSdk
     # Cast every supplied raw variable per its declared type (data-driven). A
     # variable with no declared type passes through uncast (JS warns
     # FEATURE_VARIABLES_TYPE_NOT_FOUND). Returns a fresh string-keyed Hash.
-    def cast_variables(declared, raw)
+    # +type_casting+ +false+ skips the conversion only, not the walk or the warn (CAP-2, D-8).
+    def cast_variables(declared, raw, type_casting: true)
       unless raw.is_a?(Hash)
         @log_manager&.warn("FeatureManager#run_features: feature variables not found")
         return {}
@@ -250,7 +258,7 @@ module ConvertSdk
       raw.each do |name, value|
         type = variable_type(definitions, name)
         if type
-          cast[name.to_s] = cast_type(value, type)
+          cast[name.to_s] = type_casting ? cast_type(value, type) : value
         else
           @log_manager&.warn("FeatureManager#run_features: variable type not found name=#{name}")
           cast[name.to_s] = value

data/lib/convert_sdk/version.rb

@@ -10,5 +10,5 @@ module ConvertSdk
   # derives its version from this run's git tag, not from this file (FR66).
   # Mirrors the Android SDK's `0.0.0` placeholder in gradle/libs.versions.toml.
   # @return [String]
-  VERSION = "2.0.0"
+  VERSION = "2.1.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: convert_sdk
 version: !ruby/object:Gem::Version
-  version: 2.0.0
+  version: 2.1.0
 platform: ruby
 authors:
 - Convert Insights, Inc.