toggly 1.0.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: af67c2cd1ab3f935ea72b5f3959e0958f8e7225eb8d176a40fbdb9baf3b3f57d
-  data.tar.gz: 8911b6582910f651d545a1fd625314f7a5aab4c8972188bc31844156ee37882e
+  metadata.gz: 810c3cb9858347a1cb79212512e006bf2362ee97cd09c7a528eb334c0bf949cc
+  data.tar.gz: 7f6ef5ce376a28c1101ce65c1d82080c02e6b254487ed0908479c1a622adffeb
 SHA512:
-  metadata.gz: 78ff528d676027bb0379688179b888fae05c567f0a1f57b78982890e07fc3c68cf68c763f0ddd63c8611e21c2aea4bcc0e25d31dde2f33e6ba11adbb52653cf4
-  data.tar.gz: dbe5aad2ad173a579bd7385a24b00a18980be769ea89a46e875ec6ab31d5e5af4246a9ac74789530cc7bf673dd237addee389261e2c5fc515d3989fe520b5653
+  metadata.gz: e0c8fbd59c7cfa8baafd73f580da168fe0fe4114e802f0e55bec3c406994e8a4a169b773dbf6e97862f831157d7b011df18f6210cda33740a56a6f515c05fcfc
+  data.tar.gz: 92d791902d6bf591f9731647caa1963b2c589bf12255afe376b1f1fa9591437d9af10388503b54bbbf06e911afb41fb2b557be60c9564dd09eec423037fcbdab

data/CHANGELOG.md

@@ -5,6 +5,29 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.2.0] - 2026-09-24
+
+### Added
+
+- Soft-typed `get_variant_value(feature, as: Klass)` (and optional block form).
+  Missing assignment or bind failure returns `nil` — never raises solely for
+  shape mismatch. Untyped `get_variant_value` (no `as:`) is unchanged
+  [OPS-1365].
+
+## [1.1.0] - 2026-09-23
+
+### Added
+
+- Ambient targeting identity for catalog-local variants: `Config#identity`,
+  `Client#identity` / `Client#set_identity`. When `get_variant` /
+  `get_variant_value` are called with a nil context or a blank
+  `context.identity`, the client identity is used as the allocator
+  `userId`. Groups still come only from the per-call context (never Config).
+  Prefer config / `set_identity` (or Rails ambient context) over building
+  `Context.new(identity: …)` at every call site.
+  `Config#identity=` is configuration-time only (`Toggly.configure` /
+  `Config.new`); after `Client` is built, use `Client#set_identity`.
+
 ## [1.0.0] - 2026-09-23
 
 ### Changed (Breaking)

data/README.md

@@ -47,13 +47,19 @@ bit-for-bit — verified against the shared
 `variant-allocator-corpus/cases.json` gold corpus.
 
 ```ruby
-variant = client.get_variant('checkout-flow', context: Toggly::Context.new(identity: 'user-1'))
+# Prefer ambient identity: Config#identity, Client#set_identity, or Rails
+# feature_variant (uses toggly_context). Per-call context is an override.
+client = Toggly::Client.new(app_key: '...', environment: 'Production', identity: 'user-1')
+client.set_identity('user-2') # optional runtime update
+
+variant = client.get_variant('checkout-flow') # uses client identity
+variant = client.get_variant('checkout-flow', context: Toggly::Context.new(identity: 'override'))
 variant&.name                 # assigned variant name, or nil
 variant&.configuration_value  # untyped configuration payload
 variant&.enabled               # effective enabled after StatusOverride
 variant&.reason                # "User" | "Group" | "Percentile" | "DefaultWhenEnabled" | "DefaultWhenDisabled"
 
-client.get_variant_value('checkout-flow', context: context) # shortcut for configuration_value
+client.get_variant_value('checkout-flow') # shortcut for configuration_value
 ```
 
 `enabled?` stays filter-based only. The `enable_variants` /

data/lib/toggly/client.rb

@@ -47,6 +47,7 @@ module Toggly
       # True once a revision (including empty) or durable snapshot was applied.
       @definitions_loaded = false
       @mutex = Mutex.new
+      @identity = normalize_client_identity(@config.identity)
       @ready = false
       @closed = false
 
@@ -121,6 +122,16 @@ module Toggly
     # `enable_variants` / `evaluated-variants-signed` dual-rail removed in
     # 1.0 (see CHANGELOG).
     #
+    # Targeting identity resolution (first non-empty wins):
+    # 1. per-call `context.identity`
+    # 2. {#identity} from Config / {#set_identity}
+    # 3. empty (MF anonymous)
+    #
+    # Groups come only from the per-call context (never Config). Prefer
+    # Rails `feature_variant` / ambient `toggly_context`, or
+    # `set_identity` / `Config#identity` for non-HTTP hosts — not a
+    # hand-built identity on every call.
+    #
     # NOTE: this is the actual A/B assignment. It is unrelated to the
     # `variant:` telemetry label on `record_usage` / `record_view`, which is
     # a free-form usage tag (defaults to "enabled"/"disabled").
@@ -137,7 +148,7 @@ module Toggly
       assignment = VariantAllocator.assign(
         definition,
         enabled: enabled,
-        identity: context&.identity,
+        identity: variant_user_id(context),
         groups: context&.groups || []
       )
       return nil if assignment.variant_name.nil?
@@ -155,8 +166,32 @@ module Toggly
     # @param feature_key [String, Symbol] The feature key
     # @param context [Context, nil] Optional targeting context (userId + groups)
     # @return [Object, nil]
-    def get_variant_value(feature_key, context: nil)
-      get_variant(feature_key, context: context)&.configuration_value
+    def get_variant_value(feature_key, context: nil, as: nil, &block)
+      value = get_variant(feature_key, context: context)&.configuration_value
+      return value if as.nil? && !block
+
+      return nil if value.nil?
+
+      decode_variant_configuration(value, as, &block)
+    end
+
+    # Default targeting userId used by {#get_variant} / {#get_variant_value}
+    # when the per-call context has no identity.
+    #
+    # @return [String, nil]
+    def identity
+      @mutex.synchronize { @identity }
+    end
+
+    # Set the default targeting userId (overrides Config#identity at runtime).
+    # Pass +nil+ or an empty string to clear.
+    #
+    # Named +set_identity+ (not +identity=+) to match Python/Java/Go SDK APIs.
+    #
+    # @param value [String, nil]
+    # @return [String, nil]
+    def set_identity(value) # rubocop:disable Naming/AccessorMethodName
+      @mutex.synchronize { @identity = normalize_client_identity(value) }
     end
 
     # Get detailed evaluation result
@@ -320,6 +355,34 @@ module Toggly
 
     private
 
+    def decode_variant_configuration(value, as, &block)
+      return block.call(value) if block
+      return nil if as.nil?
+
+      # Scalars / :boolean before Class#new — String.new({}) would soft-fail to "".
+      if as == String
+        return value.is_a?(String) ? value : nil
+      end
+      if as == Integer
+        return value.is_a?(Integer) && !value.is_a?(TrueClass) && !value.is_a?(FalseClass) ? value : nil
+      end
+      if as == Float
+        return value.is_a?(Numeric) && !value.is_a?(TrueClass) && !value.is_a?(FalseClass) ? value.to_f : nil
+      end
+      if [TrueClass, FalseClass, :boolean].include?(as)
+        return [true, false].include?(value) ? value : nil
+      end
+
+      # is_a? requires a Module; symbols like :boolean are handled above.
+      return value if as.is_a?(Module) && value.is_a?(as)
+      return as.new(**value.transform_keys(&:to_sym)) if as.respond_to?(:new) && value.is_a?(Hash)
+      return as.json_create(value) if as.respond_to?(:json_create) && value.is_a?(Hash)
+
+      nil
+    rescue StandardError
+      nil
+    end
+
     # `definitions` / `definitions-signed` → local rule eval. The sole
     # source of truth for `enabled?`; also carries `variants` / `allocation`
     # for the catalog-local `get_variant` assignment.
@@ -452,6 +515,20 @@ module Toggly
       @telemetry.record_check(feature_key, enabled, identity)
     end
 
+    # Allocator userId: per-call context identity when present, else client identity.
+    def variant_user_id(context)
+      return context.identity if context&.identity?
+
+      identity
+    end
+
+    def normalize_client_identity(value)
+      return nil if value.nil?
+
+      text = value.to_s
+      text.empty? ? nil : text
+    end
+
     def log_info(message)
       @config.logger&.info("[Toggly] #{message}")
     end

data/lib/toggly/config.rb

@@ -12,6 +12,17 @@ module Toggly
     # @return [String] Application key from Toggly dashboard
     attr_reader :app_key
 
+    # Default targeting userId for catalog-local +get_variant+ /
+    # +get_variant_value+ when neither a per-call +Context#identity+ nor
+    # Rails ambient context supplies one. Groups are never taken from Config.
+    #
+    # Set at configuration time only ({Config.new}, +Toggly.configure+ block).
+    # After a {Client} is built, mutating this value has no effect — use
+    # {Client#set_identity} for runtime updates.
+    #
+    # @return [String, nil]
+    attr_reader :identity
+
     # @return [String] Environment name (e.g., "Production", "Staging")
     attr_accessor :environment
 
@@ -89,6 +100,7 @@ module Toggly
 
     def initialize(**options)
       @app_key = options[:app_key]
+      @identity = normalize_identity(options[:identity])
       @environment = options[:environment] || DEFAULT_ENVIRONMENT
       @base_url = normalize_url(options[:base_url] || DEFAULT_BASE_URL)
       @definitions_url = options[:definitions_url]
@@ -172,12 +184,23 @@ module Toggly
       (@app_key.nil? || @app_key.empty?) && !@defaults.empty?
     end
 
+    # Configuration-time identity only (e.g. inside +Toggly.configure+ before
+    # {Client} is constructed). Does not update an existing client's targeting
+    # identity — call {Client#set_identity} after initialization.
+    #
+    # @param value [String, nil]
+    # @return [String, nil]
+    def identity=(value)
+      @identity = normalize_identity(value)
+    end
+
     # Convert to hash
     #
     # @return [Hash]
     def to_h
       {
         app_key: @app_key,
+        identity: @identity,
         environment: @environment,
         base_url: @base_url,
         definitions_url: @definitions_url,
@@ -208,5 +231,12 @@ module Toggly
 
       url.end_with?("/") ? url : "#{url}/"
     end
+
+    def normalize_identity(value)
+      return nil if value.nil?
+
+      text = value.to_s
+      text.empty? ? nil : text
+    end
   end
 end

data/lib/toggly/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Toggly
-  VERSION = "1.0.0"
+  VERSION = "1.2.0"
 end

data/lib/toggly.rb

@@ -106,6 +106,29 @@ module Toggly
       !enabled?(feature_key, context: context)
     end
 
+    # Assign a catalog-local variant using the global client.
+    # See {Client#get_variant}.
+    #
+    # @param feature_key [String, Symbol]
+    # @param context [Context, nil]
+    # @return [VariantResult, nil]
+    def get_variant(feature_key, context: nil)
+      raise Error, "Toggly not configured. Call Toggly.configure first." unless @client
+
+      @client.get_variant(feature_key, context: context)
+    end
+
+    # Configuration value for the assigned variant. See {Client#get_variant_value}.
+    #
+    # @param feature_key [String, Symbol]
+    # @param context [Context, nil]
+    # @return [Object, nil]
+    def get_variant_value(feature_key, context: nil, as: nil, &)
+      raise Error, "Toggly not configured. Call Toggly.configure first." unless @client
+
+      @client.get_variant_value(feature_key, context: context, as: as, &)
+    end
+
     # Reset the global client (mainly for testing)
     def reset!
       @client&.close

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: toggly
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.2.0
 platform: ruby
 authors:
 - Ops.ai
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-09-23 00:00:00.000000000 Z
+date: 2026-09-25 00:00:00.000000000 Z
 dependencies: []
 description: High-performance Ruby SDK for Toggly feature flag management. Works with
   or without Toggly.io.