quonfig 0.0.9 → 0.0.10

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e2dfc7385d529233f3b0b7c5fc13dbe7d0d648851ea0815bde792465a1774319
-  data.tar.gz: f6c702ba4eccdebeda95b8f9341fc0bb077a2c141c9397cb7f3dccb1cbfa782a
+  metadata.gz: 94866b65b3e3c4e834897981847da01f350984b2f7126f8259318ba385b8fd77
+  data.tar.gz: bc173a4300c1475f596921de2a2d24e02e5de648503318491a602c19123dd329
 SHA512:
-  metadata.gz: 368273026e247c7c01df6e85f11865f94bb588d4c4e512bbc44de65dda0a7659b96a8bd321de6ea676934b9483b0dd99d0fe516d3b288cf93a709f401bbfd824
-  data.tar.gz: be80686fa0c8748c4e1c3f802cfc51c605b1a3e31ec7f9682885a139b5081a79d91d9155833143671bfffa75728bf1091116456defd90bd610d17a5133287e03
+  metadata.gz: 875265c218e5a465abced6d47563ef7c86ade61ca2d98367059bc800dec55e1148badf58e60b632e468ab565ef5ec80e587b8f0fd045f5300b000f64fe12b909
+  data.tar.gz: 6725f7b13ac6ba43d0e7903963c5de4b1bbe03f1ae7e51399e4d0cc8877f6ee637ef2850e396e65c8d5c44cac2ee7cfa0b2f1724d390d43746d421d7e465c42a

data/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## 0.0.10 - 2026-05-01
+
+- **BREAKING (env): `QUONFIG_TELEMETRY_URL` and `QUONFIG_API_URLS` env vars
+  removed.** Replaced by a single `QUONFIG_DOMAIN` env var (default
+  `quonfig.com`) that derives api, sse, and telemetry URLs uniformly. e.g.
+  `QUONFIG_DOMAIN=quonfig-staging.com` → `https://primary.quonfig-staging.com`,
+  `https://stream.primary.quonfig-staging.com`,
+  `https://telemetry.quonfig-staging.com`. Mirrors the CLI's
+  `domain-urls.ts` convention and matches sdk-go / sdk-node. Resolution order
+  (highest wins): explicit `api_urls:` / `telemetry_url:` kwargs >
+  `QUONFIG_DOMAIN` > hardcoded default. Fixes qfg-w6gg, where the prior
+  primary-prefix regex silently fell through to prod telemetry on staging
+  hosts. The new `Quonfig::Options#init` also accepts an explicit
+  `telemetry_url:` kwarg (was previously documented but not wired up).
+- **Default `api_urls` now includes secondary.** Was `[primary]`, now
+  `[primary, secondary]` to match every other SDK and provide failover.
+
 ## 0.0.8 - 2026-04-26
 
 - **Fix (gemspec): drop deleted `scripts/` entry from manifest** — regenerated

data/CLAUDE.md

@@ -26,4 +26,4 @@ integration suite cannot resolve its YAML specs.
 - `QUONFIG_BACKEND_SDK_KEY` — backend SDK key for authenticated config delivery
 - `QUONFIG_DIR` — path to a local Quonfig workspace (datadir mode)
 - `QUONFIG_ENVIRONMENT` — which environment to evaluate (`production`, `staging`, `development`)
-- `QUONFIG_TELEMETRY_URL` — telemetry ingest endpoint
+- `QUONFIG_DOMAIN` — base domain used to derive api/sse/telemetry URLs (default `quonfig.com`). Setting `QUONFIG_DOMAIN=quonfig-staging.com` derives `https://primary.quonfig-staging.com`, `https://stream.primary.quonfig-staging.com`, and `https://telemetry.quonfig-staging.com` automatically. Explicit `api_urls:` / `telemetry_url:` kwargs override this.

data/README.md

@@ -114,14 +114,14 @@ client = Quonfig::Client.new  # reads QUONFIG_DIR + QUONFIG_ENVIRONMENT
 | `QUONFIG_BACKEND_SDK_KEY`   | SDK key used to authenticate against the Quonfig API. Used when `sdk_key:` is omitted.   |
 | `QUONFIG_DIR`               | Path to a workspace directory. When set, the SDK runs in datadir/offline mode.           |
 | `QUONFIG_ENVIRONMENT`       | Environment name (`production`, `staging`, `development`) evaluated in datadir mode.     |
-| `QUONFIG_TELEMETRY_URL`     | Overrides the telemetry endpoint. Defaults to `https://telemetry.quonfig.com`.           |
+| `QUONFIG_DOMAIN`            | Base domain used to derive api, sse, and telemetry URLs. Defaults to `quonfig.com`. Set to `quonfig-staging.com` to point at staging. Explicit `api_urls:` / `telemetry_url:` kwargs override this. |
 
 ## Constructor options
 
 ```ruby
 Quonfig::Client.new(
   sdk_key:         '...',                          # required unless QUONFIG_BACKEND_SDK_KEY is set
-  api_urls:        ['https://primary.quonfig.com'],
+  api_urls:        ['https://primary.quonfig.com', 'https://secondary.quonfig.com'],
   telemetry_url:   'https://telemetry.quonfig.com',
   enable_sse:      true,
   enable_polling:  false,
@@ -137,8 +137,8 @@ Quonfig::Client.new(
 | Option            | Type                       | Default                                                             | Description                                                                                       |
 |-------------------|----------------------------|---------------------------------------------------------------------|---------------------------------------------------------------------------------------------------|
 | `sdk_key`         | `String`                   | `ENV['QUONFIG_BACKEND_SDK_KEY']`                                    | SDK key for API authentication.                                                                   |
-| `api_urls`        | `Array<String>`            | `['https://primary.quonfig.com']`                                    | Ordered list of API base URLs to try. SSE stream URLs are derived by prepending `stream.` to each hostname. |
-| `telemetry_url`   | `String`                   | `https://telemetry.quonfig.com` (or `ENV['QUONFIG_TELEMETRY_URL']`) | Base URL for the telemetry service.                                                               |
+| `api_urls`        | `Array<String>`            | `["https://primary.${QUONFIG_DOMAIN}", "https://secondary.${QUONFIG_DOMAIN}"]` | Ordered list of API base URLs to try. SSE stream URLs are derived by prepending `stream.` to each hostname. Defaults derive from `QUONFIG_DOMAIN` (default `quonfig.com`). |
+| `telemetry_url`   | `String`                   | `https://telemetry.${QUONFIG_DOMAIN}`                                          | Base URL for the telemetry service. Default derives from `QUONFIG_DOMAIN`.                        |
 | `enable_sse`      | `Boolean`                  | `true`                                                              | Receive real-time updates over Server-Sent Events.                                                |
 | `enable_polling`  | `Boolean`                  | `false`                                                             | Poll the API on an interval as a fallback.                                                        |
 | `poll_interval`   | `Integer` (seconds)        | `60`                                                                | Polling interval when `enable_polling` is `true`.                                                 |

data/VERSION

@@ -1 +1 @@
-0.0.9
+0.0.10

data/lib/quonfig/evaluation_details.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Quonfig
+  # Public details record returned by Quonfig::Client#get_*_details. Surfaces
+  # the resolution reason and (on error) an error_code/error_message alongside
+  # the resolved value, so downstream layers — most importantly the
+  # OpenFeature provider — can map the result without losing fidelity.
+  #
+  # +reason+ is one of the strings:
+  #   "STATIC"           — config has no targeting rules; matched value is the static default
+  #   "TARGETING_MATCH"  — a targeting rule matched (any non-ALWAYS_TRUE criterion)
+  #   "SPLIT"            — matched value came from a weighted variant
+  #   "DEFAULT"          — no rule matched (eval fell through)
+  #   "ERROR"            — evaluation failed
+  #
+  # +error_code+ (only when reason == "ERROR") is one of:
+  #   "FLAG_NOT_FOUND" — the key was unknown to the store
+  #   "TYPE_MISMATCH"  — the resolved value didn't satisfy the requested type
+  #   "GENERAL"        — any other failure
+  class EvaluationDetails
+    REASON_STATIC          = 'STATIC'
+    REASON_TARGETING_MATCH = 'TARGETING_MATCH'
+    REASON_SPLIT           = 'SPLIT'
+    REASON_DEFAULT         = 'DEFAULT'
+    REASON_ERROR           = 'ERROR'
+
+    ERROR_FLAG_NOT_FOUND = 'FLAG_NOT_FOUND'
+    ERROR_TYPE_MISMATCH  = 'TYPE_MISMATCH'
+    ERROR_GENERAL        = 'GENERAL'
+
+    attr_reader :value, :reason, :error_code, :error_message
+
+    def initialize(value:, reason:, error_code: nil, error_message: nil)
+      @value         = value
+      @reason        = reason
+      @error_code    = error_code
+      @error_message = error_message
+    end
+
+    def ==(other)
+      other.is_a?(EvaluationDetails) &&
+        other.value == @value &&
+        other.reason == @reason &&
+        other.error_code == @error_code &&
+        other.error_message == @error_message
+    end
+    alias eql? ==
+
+    def hash
+      [@value, @reason, @error_code, @error_message].hash
+    end
+
+    def inspect
+      parts = ["value=#{@value.inspect}", "reason=#{@reason.inspect}"]
+      parts << "error_code=#{@error_code.inspect}" if @error_code
+      parts << "error_message=#{@error_message.inspect}" if @error_message
+      "#<Quonfig::EvaluationDetails #{parts.join(' ')}>"
+    end
+  end
+end

data/lib/quonfig/options.rb

@@ -39,10 +39,38 @@ module Quonfig
     DEFAULT_MAX_EXAMPLE_CONTEXTS = 100_000
     DEFAULT_MAX_EVAL_SUMMARIES = 100_000
 
+    # Hardcoded fallback domain. Overridden by ENV['QUONFIG_DOMAIN'].
+    DEFAULT_DOMAIN = 'quonfig.com'
+
+    # Hardcoded fallback API URLs (used only when no QUONFIG_DOMAIN is set
+    # and no explicit api_urls are provided). Mirrors derive_api_urls(DEFAULT_DOMAIN).
     DEFAULT_API_URLS = [
       'https://primary.quonfig.com',
+      'https://secondary.quonfig.com',
     ].freeze
 
+    # Resolve the active domain. Reads QUONFIG_DOMAIN; falls back to
+    # DEFAULT_DOMAIN. Mirrors `cli/src/util/domain-urls.ts#getDomain`.
+    def self.domain
+      env = ENV['QUONFIG_DOMAIN']
+      env && !env.empty? ? env : DEFAULT_DOMAIN
+    end
+
+    # Derive default api_urls for a given domain. e.g. for domain
+    # `quonfig-staging.com` returns
+    # `["https://primary.quonfig-staging.com", "https://secondary.quonfig-staging.com"]`.
+    def self.derive_api_urls(domain)
+      [
+        "https://primary.#{domain}",
+        "https://secondary.#{domain}",
+      ]
+    end
+
+    # Derive the telemetry URL for a given domain.
+    def self.derive_telemetry_url(domain)
+      "https://telemetry.#{domain}"
+    end
+
     # Derive the SSE stream URL for a given API URL by prepending `stream.` to
     # the hostname. Preserves scheme, port, and path.
     #
@@ -58,6 +86,7 @@ module Quonfig
 
     private def init(
       api_urls: nil,
+      telemetry_url: nil,
       sdk_key: ENV['QUONFIG_BACKEND_SDK_KEY'],
       environment: ENV['QUONFIG_ENVIRONMENT'],
       datadir: ENV['QUONFIG_DIR'],
@@ -104,16 +133,19 @@ module Quonfig
       @collect_example_contexts = false
       @collect_max_example_contexts = 0
 
-      if ENV['QUONFIG_API_URLS'] && ENV['QUONFIG_API_URLS'].length > 0
-        api_urls = ENV['QUONFIG_API_URLS']
-      end
+      # URL resolution order (highest wins):
+      #   1. Explicit kwargs (api_urls:, telemetry_url:)
+      #   2. ENV['QUONFIG_DOMAIN'] -> derives all three
+      #   3. Hardcoded DEFAULT_DOMAIN ('quonfig.com')
+      domain = Quonfig::Options.domain
 
-      @api_urls = Array(api_urls || DEFAULT_API_URLS).map { |url| remove_trailing_slash(url) }
+      @api_urls = Array(api_urls || Quonfig::Options.derive_api_urls(domain))
+                    .map { |url| remove_trailing_slash(url) }
 
       @sse_api_urls = @api_urls.map { |url| Quonfig::Options.derive_stream_url(url) }
       @config_api_urls = @api_urls
 
-      @telemetry_destination = ENV['QUONFIG_TELEMETRY_URL'] || derive_telemetry_destination(@api_urls)
+      @telemetry_destination = telemetry_url || Quonfig::Options.derive_telemetry_url(domain)
 
       case context_upload_mode
       when :none
@@ -188,16 +220,5 @@ module Quonfig
     def remove_trailing_slash(url)
       url.end_with?('/') ? url[0..-2] : url
     end
-
-    # Derive a telemetry URL from the configured api_urls by swapping the
-    # primary/secondary host prefix for `telemetry` on a *.quonfig.com host.
-    # Falls back to https://telemetry.quonfig.com if no URL matches.
-    def derive_telemetry_destination(api_urls)
-      api_urls.each do |api_url|
-        match = api_url.match(%r{\Ahttps?://(?:primary|secondary)\.([^/]*quonfig\.com)}i)
-        return "https://telemetry.#{match[1]}" if match
-      end
-      'https://telemetry.quonfig.com'
-    end
   end
 end

data/quonfig.gemspec

@@ -2,16 +2,16 @@
 # DO NOT EDIT THIS FILE DIRECTLY
 # Instead, edit Juwelier::Tasks in Rakefile, and run 'rake gemspec'
 # -*- encoding: utf-8 -*-
-# stub: quonfig 0.0.9 ruby lib
+# stub: quonfig 0.0.10 ruby lib
 
 Gem::Specification.new do |s|
   s.name = "quonfig".freeze
-  s.version = "0.0.9".freeze
+  s.version = "0.0.10".freeze
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0".freeze) if s.respond_to? :required_rubygems_version=
   s.require_paths = ["lib".freeze]
   s.authors = ["Jeff Dwyer".freeze]
-  s.date = "2026-04-27"
+  s.date = "2026-05-01"
   s.description = "Quonfig \u2014 feature flags and live config, stored as files in git.".freeze
   s.email = "jeff@quonfig.com".freeze
   s.extra_rdoc_files = [
@@ -69,6 +69,7 @@ Gem::Specification.new do |s|
     "lib/quonfig/errors/type_mismatch_error.rb",
     "lib/quonfig/errors/uninitialized_error.rb",
     "lib/quonfig/evaluation.rb",
+    "lib/quonfig/evaluation_details.rb",
     "lib/quonfig/evaluator.rb",
     "lib/quonfig/exponential_backoff.rb",
     "lib/quonfig/fixed_size_hash.rb",
@@ -121,6 +122,7 @@ Gem::Specification.new do |s|
     "test/test_context_shape.rb",
     "test/test_context_shape_aggregator.rb",
     "test/test_datadir.rb",
+    "test/test_details_getters.rb",
     "test/test_dev_context.rb",
     "test/test_duration.rb",
     "test/test_encryption.rb",

data/test/test_details_getters.rb

@@ -0,0 +1,242 @@
+# frozen_string_literal: true
+
+require 'test_helper'
+
+# Coverage for the *_details getters on Quonfig::Client and Quonfig::BoundClient.
+# These return Quonfig::EvaluationDetails carrying an OpenFeature-aligned
+# +reason+ and (on the error path) error_code / error_message. They never raise.
+class TestDetailsGetters < Minitest::Test
+  Details = Quonfig::EvaluationDetails
+
+  INTEGRATION_FIXTURE_DIR = File.expand_path(
+    '../../integration-test-data/data/integration-tests', __dir__
+  )
+
+  # ---- Helpers --------------------------------------------------------
+
+  def fixture_client
+    skip "integration-test-data sibling missing at #{INTEGRATION_FIXTURE_DIR}" unless Dir.exist?(INTEGRATION_FIXTURE_DIR)
+
+    Quonfig::Client.new(
+      Quonfig::Options.new(
+        datadir: INTEGRATION_FIXTURE_DIR,
+        environment: 'Production',
+        enable_sse: false,
+        enable_polling: false
+      )
+    )
+  end
+
+  # An ALWAYS_TRUE-only config: no targeting rules anywhere -> STATIC.
+  def make_static_config(key:, value:, type:)
+    {
+      'id' => '1',
+      'key' => key,
+      'type' => 'config',
+      'valueType' => type,
+      'sendToClientSdk' => false,
+      'default' => {
+        'rules' => [
+          {
+            'criteria' => [{ 'operator' => 'ALWAYS_TRUE' }],
+            'value' => { 'type' => type, 'value' => value }
+          }
+        ]
+      },
+      'environment' => nil
+    }
+  end
+
+  def static_client(key:, value:, type:)
+    store = Quonfig::ConfigStore.new
+    store.set(key, make_static_config(key: key, value: value, type: type))
+    Quonfig::Client.new(Quonfig::Options.new, store: store)
+  end
+
+  # ---- STATIC reason --------------------------------------------------
+
+  def test_get_bool_details_static_reason_for_always_true_only_config
+    client = static_client(key: 'plain', value: true, type: 'bool')
+    details = client.get_bool_details('plain')
+    assert_kind_of Details, details
+    assert_equal true, details.value
+    assert_equal Details::REASON_STATIC, details.reason
+    assert_nil details.error_code
+    assert_nil details.error_message
+  end
+
+  def test_get_string_details_static_reason
+    client = static_client(key: 'plain.s', value: 'hi', type: 'string')
+    details = client.get_string_details('plain.s')
+    assert_equal 'hi', details.value
+    assert_equal Details::REASON_STATIC, details.reason
+  end
+
+  def test_static_reason_via_integration_fixture_always_true
+    client = fixture_client
+    details = client.get_bool_details('always.true')
+    assert_equal true, details.value
+    assert_equal Details::REASON_STATIC, details.reason
+  ensure
+    client&.stop
+  end
+
+  # ---- TARGETING_MATCH reason ----------------------------------------
+
+  def test_targeting_match_reason_via_integration_fixture
+    client = fixture_client
+    details = client.get_bool_details('of.targeting', context: { 'user' => { 'plan' => 'pro' } })
+    assert_equal true, details.value
+    assert_equal Details::REASON_TARGETING_MATCH, details.reason
+  ensure
+    client&.stop
+  end
+
+  def test_targeting_match_falls_through_to_default_branch_still_targeting
+    # The of.targeting fixture has a property-match rule + an ALWAYS_TRUE
+    # fallback. Even when the fallback wins, the *config* has targeting rules,
+    # so wire_reason / of_reason returns TARGETING_MATCH.
+    client = fixture_client
+    details = client.get_bool_details('of.targeting', context: { 'user' => { 'plan' => 'free' } })
+    assert_equal false, details.value
+    assert_equal Details::REASON_TARGETING_MATCH, details.reason
+  ensure
+    client&.stop
+  end
+
+  # ---- SPLIT reason ---------------------------------------------------
+
+  def test_split_reason_via_integration_fixture
+    client = fixture_client
+    # Pick a deterministic targetingKey so the outcome is reproducible.
+    details = client.get_string_details('of.weighted', context: { 'user' => { 'id' => 'user-123' } })
+    assert_equal Details::REASON_SPLIT, details.reason
+    assert_includes %w[variant-a variant-b], details.value
+  ensure
+    client&.stop
+  end
+
+  # ---- DEFAULT reason -------------------------------------------------
+
+  def test_default_reason_when_no_rule_matches
+    # Config exists but no rule matches against the empty context.
+    config = {
+      'id' => '9',
+      'key' => 'no.match.here',
+      'type' => 'config',
+      'valueType' => 'string',
+      'sendToClientSdk' => false,
+      'default' => {
+        'rules' => [
+          {
+            'criteria' => [
+              {
+                'propertyName' => 'user.plan',
+                'operator' => 'PROP_IS_ONE_OF',
+                'valueToMatch' => { 'type' => 'string_list', 'value' => ['enterprise'] }
+              }
+            ],
+            'value' => { 'type' => 'string', 'value' => 'gold' }
+          }
+        ]
+      },
+      'environment' => nil
+    }
+    store = Quonfig::ConfigStore.new
+    store.set('no.match.here', config)
+    client = Quonfig::Client.new(Quonfig::Options.new, store: store)
+
+    details = client.get_string_details('no.match.here')
+    assert_nil details.value
+    assert_equal Details::REASON_DEFAULT, details.reason
+    assert_nil details.error_code
+  end
+
+  # ---- ERROR / FLAG_NOT_FOUND ----------------------------------------
+
+  def test_flag_not_found_returns_error_details
+    client = Quonfig::Client.new(Quonfig::Options.new, store: Quonfig::ConfigStore.new)
+    details = client.get_bool_details('does.not.exist')
+    assert_nil details.value
+    assert_equal Details::REASON_ERROR, details.reason
+    assert_equal Details::ERROR_FLAG_NOT_FOUND, details.error_code
+    refute_nil details.error_message
+  end
+
+  def test_flag_not_found_for_string_details
+    client = Quonfig::Client.new(Quonfig::Options.new, store: Quonfig::ConfigStore.new)
+    details = client.get_string_details('nope')
+    assert_equal Details::REASON_ERROR, details.reason
+    assert_equal Details::ERROR_FLAG_NOT_FOUND, details.error_code
+  end
+
+  # ---- ERROR / TYPE_MISMATCH -----------------------------------------
+
+  def test_type_mismatch_for_int_when_value_is_string
+    client = static_client(key: 'wrong.type', value: 'oops', type: 'string')
+    details = client.get_int_details('wrong.type')
+    assert_nil details.value
+    assert_equal Details::REASON_ERROR, details.reason
+    assert_equal Details::ERROR_TYPE_MISMATCH, details.error_code
+    refute_nil details.error_message
+  end
+
+  def test_type_mismatch_for_bool_when_value_is_string
+    client = static_client(key: 'bool.miss', value: 'true', type: 'string')
+    details = client.get_bool_details('bool.miss')
+    assert_equal Details::REASON_ERROR, details.reason
+    assert_equal Details::ERROR_TYPE_MISMATCH, details.error_code
+  end
+
+  def test_type_mismatch_for_string_list_when_value_is_string
+    client = static_client(key: 'list.miss', value: 'a,b', type: 'string')
+    details = client.get_string_list_details('list.miss')
+    assert_equal Details::REASON_ERROR, details.reason
+    assert_equal Details::ERROR_TYPE_MISMATCH, details.error_code
+  end
+
+  # ---- json passes through unchanged ---------------------------------
+
+  def test_get_json_details_returns_hash_with_static_reason
+    payload = { 'a' => 1, 'b' => [1, 2] }
+    client = static_client(key: 'shape', value: payload, type: 'json')
+    details = client.get_json_details('shape')
+    assert_equal payload, details.value
+    assert_equal Details::REASON_STATIC, details.reason
+  end
+
+  # ---- Float / Int success path -------------------------------------
+
+  def test_get_int_details_static_reason
+    client = static_client(key: 'i', value: 42, type: 'int')
+    details = client.get_int_details('i')
+    assert_equal 42, details.value
+    assert_equal Details::REASON_STATIC, details.reason
+  end
+
+  def test_get_float_details_static_reason
+    client = static_client(key: 'f', value: 3.14, type: 'double')
+    details = client.get_float_details('f')
+    assert_in_delta 3.14, details.value, 1e-9
+    assert_equal Details::REASON_STATIC, details.reason
+  end
+
+  def test_get_string_list_details_static_reason
+    client = static_client(key: 'sl', value: %w[a b], type: 'string_list')
+    details = client.get_string_list_details('sl')
+    assert_equal %w[a b], details.value
+    assert_equal Details::REASON_STATIC, details.reason
+  end
+
+  # ---- BoundClient mirror --------------------------------------------
+
+  def test_bound_client_get_bool_details_passes_context
+    client = fixture_client
+    bound = client.in_context('user' => { 'plan' => 'pro' })
+    details = bound.get_bool_details('of.targeting')
+    assert_equal true, details.value
+    assert_equal Details::REASON_TARGETING_MATCH, details.reason
+  ensure
+    client&.stop
+  end
+end

data/test/test_http_connection.rb

@@ -65,15 +65,17 @@ module Quonfig
       refute(Options::DEFAULT_API_URLS.any? { |s| s.include?('reforge.com') })
     end
 
-    def test_telemetry_destination_honors_quonfig_telemetry_url_env
-      with_env('QUONFIG_TELEMETRY_URL', 'https://override-telemetry.example.com') do
-        assert_equal 'https://override-telemetry.example.com',
+    def test_telemetry_destination_honors_quonfig_domain_env
+      with_env('QUONFIG_DOMAIN', 'quonfig-staging.com') do
+        assert_equal 'https://telemetry.quonfig-staging.com',
                      Options.new.telemetry_destination
       end
     end
 
     def test_telemetry_destination_default
-      assert_equal 'https://telemetry.quonfig.com', Options.new.telemetry_destination
+      with_env('QUONFIG_DOMAIN', nil) do
+        assert_equal 'https://telemetry.quonfig.com', Options.new.telemetry_destination
+      end
     end
   end
 end

data/test/test_options.rb

@@ -5,23 +5,13 @@ require 'test_helper'
 class TestOptions < Minitest::Test
   API_KEY = 'abcdefg'
 
-  def test_api_urls_override_env_var
-    assert_equal Quonfig::Options::DEFAULT_API_URLS, Quonfig::Options.new.api_urls
-
-    # blank doesn't take effect
-    with_env('QUONFIG_API_URLS', '') do
-      assert_equal Quonfig::Options::DEFAULT_API_URLS, Quonfig::Options.new.api_urls
-    end
-
-    # non-blank does take effect
-    with_env('QUONFIG_API_URLS', 'https://override.example.com') do
-      assert_equal ["https://override.example.com"], Quonfig::Options.new.api_urls
-    end
-  end
-
   def test_default_api_urls_point_to_quonfig
+    # DEFAULT_API_URLS is the hardcoded fallback when neither QUONFIG_DOMAIN
+    # nor an explicit api_urls: kwarg is set. Domain-derivation happens at
+    # construction time, not at constant load time — see derive_api_urls.
     assert_equal [
       'https://primary.quonfig.com',
+      'https://secondary.quonfig.com',
     ], Quonfig::Options::DEFAULT_API_URLS
   end
 
@@ -150,18 +140,59 @@ class TestOptions < Minitest::Test
     assert_equal 0, options.collect_max_shapes
   end
 
-  def test_telemetry_destination_reads_env_first
-    with_env('QUONFIG_TELEMETRY_URL', 'https://custom-telemetry.example.com') do
-      assert_equal 'https://custom-telemetry.example.com', Quonfig::Options.new.telemetry_destination
+  # ---- QUONFIG_DOMAIN tests (qfg-w6gg) ----
+  # A single env var `QUONFIG_DOMAIN` governs api, sse, and telemetry URL
+  # derivation. Resolution order (highest wins): explicit kwargs >
+  # QUONFIG_DOMAIN > hardcoded default 'quonfig.com'.
+
+  def test_default_domain_is_quonfig_com
+    with_env('QUONFIG_DOMAIN', nil) do
+      options = Quonfig::Options.new
+      assert_equal [
+        'https://primary.quonfig.com',
+        'https://secondary.quonfig.com',
+      ], options.api_urls
+      assert_equal 'https://telemetry.quonfig.com', options.telemetry_destination
+    end
+  end
+
+  def test_quonfig_domain_env_var_derives_all_urls
+    with_env('QUONFIG_DOMAIN', 'quonfig-staging.com') do
+      options = Quonfig::Options.new
+      assert_equal [
+        'https://primary.quonfig-staging.com',
+        'https://secondary.quonfig-staging.com',
+      ], options.api_urls
+      assert_equal [
+        'https://stream.primary.quonfig-staging.com',
+        'https://stream.secondary.quonfig-staging.com',
+      ], options.sse_api_urls
+      assert_equal 'https://telemetry.quonfig-staging.com', options.telemetry_destination
+    end
+  end
+
+  def test_explicit_api_urls_override_quonfig_domain
+    with_env('QUONFIG_DOMAIN', 'quonfig-staging.com') do
+      options = Quonfig::Options.new(api_urls: ['http://localhost:8080'])
+      assert_equal ['http://localhost:8080'], options.api_urls
     end
   end
 
-  def test_telemetry_destination_derives_from_default_sources
-    assert_equal 'https://telemetry.quonfig.com', Quonfig::Options.new.telemetry_destination
+  def test_explicit_telemetry_url_overrides_quonfig_domain
+    with_env('QUONFIG_DOMAIN', 'quonfig-staging.com') do
+      options = Quonfig::Options.new(telemetry_url: 'http://localhost:6555')
+      assert_equal 'http://localhost:6555', options.telemetry_destination
+    end
   end
 
-  def test_telemetry_destination_derives_from_custom_quonfig_api_urls
-    options = Quonfig::Options.new(api_urls: ['https://primary.eu.quonfig.com'])
-    assert_equal 'https://telemetry.eu.quonfig.com', options.telemetry_destination
+  def test_quonfig_telemetry_url_env_var_no_longer_read
+    # QUONFIG_TELEMETRY_URL has been removed. Setting it must not affect
+    # anything; the default (quonfig.com) wins.
+    with_env('QUONFIG_DOMAIN', nil) do
+      with_env('QUONFIG_TELEMETRY_URL', 'https://should-be-ignored.example.com') do
+        assert_equal 'https://telemetry.quonfig.com',
+                     Quonfig::Options.new.telemetry_destination
+      end
+    end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: quonfig
 version: !ruby/object:Gem::Version
-  version: 0.0.9
+  version: 0.0.10
 platform: ruby
 authors:
 - Jeff Dwyer
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-04-27 00:00:00.000000000 Z
+date: 2026-05-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: concurrent-ruby
@@ -228,6 +228,7 @@ files:
 - lib/quonfig/errors/type_mismatch_error.rb
 - lib/quonfig/errors/uninitialized_error.rb
 - lib/quonfig/evaluation.rb
+- lib/quonfig/evaluation_details.rb
 - lib/quonfig/evaluator.rb
 - lib/quonfig/exponential_backoff.rb
 - lib/quonfig/fixed_size_hash.rb
@@ -280,6 +281,7 @@ files:
 - test/test_context_shape.rb
 - test/test_context_shape_aggregator.rb
 - test/test_datadir.rb
+- test/test_details_getters.rb
 - test/test_dev_context.rb
 - test/test_duration.rb
 - test/test_encryption.rb