smplkit 3.0.129 → 3.0.132

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0b6297c50f89cbe656fb1a9b3d26990f853fccc9f1894957d0e3a43fadca226f
-  data.tar.gz: 97364f6d0e110220f5945b1eb5e3060c843a8855921884e344ebaf0f765e676d
+  metadata.gz: b949ca8853996a6f2963a8d281f7d9c78b1ffd076d8bdf592c01ba8b536af7fe
+  data.tar.gz: ae9880e7ed0b32619b88edbdaf45a9755d657c53b2dae211164e394cad33d27b
 SHA512:
-  metadata.gz: deeb4adfddff9d195207ef70887157829816d0f933daca4bcecdbe149c8b2f93fe9798993cda6c26791168136ac4e5a2cd259f2481019e91c72fff2e97e10e64
-  data.tar.gz: 6beb5e6fff975ea31e05f02934003736228c8ec63431f9d3ffd74479f029328cac26c7c63af2caf85fe859eba43af26850a6868ccab45f0b2521337b207bd389
+  metadata.gz: 8ae977dfa3241a4f325ff0c86c60e917ff26c412b889408eddbf8bc39f1dc6c525a3238dc70917364828e04b68424b953b4a1c4f64e8cdcd2ba13aeaec017144
+  data.tar.gz: 77bf283d211b3fe647c0ec00f59f928b8727b780cc101aeecae68a4e7979c740d258f94b35ea60fd33d6a88f0b759183f4ed8e8cd230fdabd15a231c15c471b0

data/lib/smplkit/account/client.rb

@@ -36,7 +36,12 @@ module Smplkit
         @headers = {
           "Authorization" => "Bearer #{api_key}",
           "Content-Type" => "application/json"
-        }.merge(extra_headers || {})
+        }
+        # Default SDK User-Agent unless the caller supplied one (any casing) —
+        # without it this raw Faraday connection would fall through to
+        # Faraday's own "Faraday vX.Y.Z" default.
+        @headers["User-Agent"] = Smplkit.user_agent unless Transport.user_agent_supplied?(extra_headers)
+        @headers.merge!(extra_headers || {})
       end
 
       # Fetch the authenticated account's current settings.

data/lib/smplkit/audit/client.rb

@@ -23,7 +23,8 @@ module Smplkit
     # @param environment [String, nil] Deployment environment to scope recording
     #   and reads to. Sent on the event request body when recording and as the
     #   default +filter[environment]+ on the read surfaces (events list and the
-    #   resource_type / event_type / category discovery lists). Optional —
+    #   resource_type / event_type / category discovery lists). When omitted,
+    #   resolved from +SMPLKIT_ENVIRONMENT+ or +~/.smplkit+. Optional —
     #   forwarder CRUD is environment-agnostic, and reads accept an explicit
     #   +environments: [...]+ filter that overrides this default. With no
     #   configured environment, recording falls back to the server-side default
@@ -35,28 +36,36 @@ module Smplkit
     # @param debug [Boolean, nil] Enable SDK debug logging.
     # @param timeout [Float] Per-request timeout, in seconds. Defaults to +10.0+.
     # @param extra_headers [Hash{String => String}, nil] Extra headers attached
-    #   to every request. SDK-owned headers (authorization, content-type,
-    #   user-agent) cannot be overridden.
+    #   to every request. SDK-owned headers (authorization, content-type)
+    #   cannot be overridden. A caller-supplied User-Agent (any casing)
+    #   replaces the SDK default +smplkit-sdk-ruby/<version>+.
+    # @param buffered [Boolean] Buffer event recording (default +true+):
+    #   +events.record+ enqueues onto an in-memory buffer that a background
+    #   worker drains with retry, and returns immediately. Set +false+ for the
+    #   stateless write path: +events.record+ performs one blocking POST per
+    #   call and raises on failure, +events.flush+ is a no-op, and no worker
+    #   thread or background state is created — the right shape for serverless
+    #   and edge runtimes, where an instance may be constructed per request.
     class AuditClient
       attr_reader :events, :resource_types, :event_types, :categories, :forwarders
 
-      SDK_OWNED_HEADERS = %w[authorization content-type user-agent].freeze
-
       def initialize(api_key: nil, base_url: nil, environment: nil, profile: nil,
                      base_domain: nil, scheme: nil, debug: nil, timeout: 10.0,
-                     extra_headers: nil)
-        # +base_url+/+api_key+ are used directly when both are supplied (the
-        # path the top-level client takes after it has already resolved them);
-        # otherwise the config resolver fills in whatever is missing
-        # (+~/.smplkit+ / env vars / defaults) and the audit base URL is derived
-        # from +base_domain+/+scheme+ via +service_url+.
-        if api_key.nil? || base_url.nil?
+                     extra_headers: nil, buffered: true)
+        # +api_key+/+base_url+/+environment+ are used directly when all three
+        # are supplied (the path the top-level client takes after it has
+        # already resolved them); otherwise the config resolver fills in
+        # whatever is missing (+~/.smplkit+ / env vars / defaults) and the
+        # audit base URL is derived from +base_domain+/+scheme+ via
+        # +service_url+.
+        if api_key.nil? || base_url.nil? || environment.nil?
           resolved = ConfigResolution.resolve_client_config(
             profile: profile, api_key: api_key, base_domain: base_domain,
-            scheme: scheme, debug: debug
+            scheme: scheme, environment: environment, debug: debug
           )
           api_key = resolved.api_key if api_key.nil?
           base_url = ConfigResolution.service_url(resolved.scheme, "audit", resolved.base_domain) if base_url.nil?
+          environment = resolved.environment if environment.nil?
           debug = resolved.debug if debug.nil?
         end
         cfg = SmplkitGeneratedClient::Audit::Configuration.new
@@ -67,18 +76,19 @@ module Smplkit
         cfg.debugging = debug unless debug.nil?
         HttpPool.configure(cfg)
         api_client = SmplkitGeneratedClient::Audit::ApiClient.new(cfg)
-        api_client.default_headers["User-Agent"] = "smplkit-ruby-sdk/#{Smplkit::VERSION}"
         # Runtime audit ops are environment-scoped, but the scoping is
         # body-driven (ADR-055): +events.record+ stamps the configured
         # environment onto the event request body, and the read surfaces
         # (events list plus the resource_type / event_type / category discovery
         # lists) default +filter[environment]+ to it. The transport therefore
-        # carries only auth plus any caller-supplied +extra_headers+ — no
-        # environment header. Forwarder CRUD is environment-agnostic.
-        extra_headers&.each do |k, v|
-          api_client.default_headers[k] = v unless SDK_OWNED_HEADERS.include?(k.downcase)
-        end
-        @events = Events.new(SmplkitGeneratedClient::Audit::EventsApi.new(api_client), environment: environment)
+        # carries only auth, the default User-Agent, and any caller-supplied
+        # +extra_headers+ — no environment header. Forwarder CRUD is
+        # environment-agnostic.
+        Transport.apply_headers(api_client, extra_headers)
+        @events = Events.new(
+          SmplkitGeneratedClient::Audit::EventsApi.new(api_client),
+          environment: environment, buffered: buffered
+        )
         @resource_types = ResourceTypes.new(
           SmplkitGeneratedClient::Audit::ResourceTypesApi.new(api_client), environment: environment
         )

data/lib/smplkit/audit/events.rb

@@ -7,22 +7,33 @@ module Smplkit
     # +#record+ is fire-and-forget by default — the call enqueues the event
     # onto an in-memory bounded buffer and returns immediately. Pass
     # +flush: true+ to block until the event is durable before continuing.
+    # In stateless mode (+buffered: false+ on the client) there is no buffer:
+    # every +#record+ performs one blocking POST and raises on failure.
     # +#list+ and +#get+ are synchronous reads.
     class Events
-      def initialize(api, environment: nil)
+      def initialize(api, environment: nil, buffered: true)
         @api = api
         @environment = environment
-        @buffer = EventBuffer.new(api)
+        # Stateless mode installs no buffer at all — no worker thread, no
+        # background state — so a client may be constructed per request in
+        # serverless or edge runtimes.
+        @buffer = buffered ? EventBuffer.new(api) : nil
       end
 
-      # Enqueue an audit event for asynchronous delivery.
+      # Record an audit event.
       #
-      # Returns immediately when +flush+ is +false+ (the default) — the
-      # buffer's worker thread performs the actual POST with retry on
-      # transient failures. When +flush: true+, this call blocks until the
-      # buffer has drained or +flush_timeout+ elapses; use it when the caller
-      # needs the event durable before continuing (CLI tools, in-test
-      # assertions, or any flow about to terminate the process).
+      # In the default buffered mode this enqueues for asynchronous delivery
+      # and returns immediately — the buffer's worker thread performs the
+      # actual POST with retry on transient failures. When +flush: true+,
+      # the call blocks until the buffer has drained or +flush_timeout+
+      # elapses; use it when the caller needs the event durable before
+      # continuing (CLI tools, in-test assertions, or any flow about to
+      # terminate the process).
+      #
+      # In stateless mode (+buffered: false+ on the client) every call
+      # performs one blocking POST and raises one of the SDK's typed errors
+      # on failure; +flush+/+flush_timeout+ are meaningless there and
+      # ignored.
       #
       # Actor attribution (+actor_type+, +actor_id+, +actor_label+) is
       # customer-supplied and free-form. The audit service stores
@@ -69,10 +80,11 @@ module Smplkit
       #   enabled forwarder so the skip is visible in the forwarder delivery log.
       # @param flush [Boolean] When +true+, block until the buffer has drained
       #   (or +flush_timeout+ elapses) before returning. Defaults to +false+
-      #   (fire-and-forget).
+      #   (fire-and-forget). Ignored in stateless mode (+buffered: false+),
+      #   where every record is already durable on return.
       # @param flush_timeout [Float, nil] Upper bound on the blocking flush, in
-      #   seconds. Ignored when +flush+ is +false+. +nil+ blocks indefinitely.
-      #   Defaults to +5.0+.
+      #   seconds. Ignored when +flush+ is +false+ and in stateless mode.
+      #   +nil+ blocks indefinitely. Defaults to +5.0+.
       # @return [void]
       def record(event_type:, resource_type:, resource_id:,
                  occurred_at: nil, actor_type: nil, actor_id: nil,
@@ -124,6 +136,14 @@ module Smplkit
           attributes: attrs
         )
         body = SmplkitGeneratedClient::Audit::EventRequest.new(data: resource)
+        if @buffer.nil?
+          # Stateless path: one blocking POST per call — the same wire call
+          # the buffer's worker performs, but failures surface to the caller
+          # as the SDK's typed errors instead of being retried in background.
+          opts = idempotency_key ? { idempotency_key: idempotency_key } : {}
+          Smplkit::Audit.call_api { @api.record_event(body, opts) }
+          return nil
+        end
         @buffer.enqueue(body, idempotency_key)
         @buffer.flush(timeout: flush_timeout) if flush
         nil
@@ -171,6 +191,9 @@ module Smplkit
       #   equals this value. Omit to match any.
       # @param actor_id [String, nil] Return only events whose +actor_id+
       #   matches this value as a literal string. Omit to match any.
+      # @param category [String, nil] Filter to this exact category — the
+      #   indexed correlation label callers stamp on related events. Omit to
+      #   match any.
       # @param occurred_at_range [String, nil] Restrict to events whose
       #   +occurred_at+ falls in this range. Omit to leave the time window open.
       # @param search [String, nil] Optional free-text filter — returns only
@@ -189,7 +212,7 @@ module Smplkit
       # @return [Smplkit::Audit::ListEventsPage] A page of the matching events;
       #   its +#next_cursor+ is set when more pages are available.
       def list(event_type: nil, resource_type: nil, resource_id: nil,
-               actor_type: nil, actor_id: nil, occurred_at_range: nil,
+               actor_type: nil, actor_id: nil, category: nil, occurred_at_range: nil,
                search: nil, environments: nil, page_size: nil, page_after: nil)
         # Generated client opts use snake_case keys that internally map
         # to the JSON:API ``filter[*]`` / ``page[*]`` query-string format
@@ -202,6 +225,7 @@ module Smplkit
         opts[:filter_resource_id] = resource_id if resource_id
         opts[:filter_actor_type] = actor_type if actor_type
         opts[:filter_actor_id] = actor_id if actor_id
+        opts[:filter_category] = category if category
         opts[:filter_occurred_at] = occurred_at_range if occurred_at_range
         opts[:filter_search] = search if search
         resolved_environment = Smplkit::Audit.resolve_environment_filter(environments, @environment)
@@ -217,18 +241,22 @@ module Smplkit
       # Block until the in-memory buffer is drained or the timeout elapses.
       #
       # Useful for draining buffered events at process shutdown or after a batch
-      # of fire-and-forget records.
+      # of fire-and-forget records. A no-op in stateless mode
+      # (+buffered: false+), where every record is already durable on return.
       #
       # @param timeout [Float, nil] Upper bound on the blocking flush, in
       #   seconds. +nil+ blocks indefinitely. Defaults to +5.0+.
       # @return [void]
       def flush(timeout: 5.0)
-        @buffer.flush(timeout: timeout)
+        @buffer&.flush(timeout: timeout)
+        nil
       end
 
-      # @api private — drains best-effort and stops the worker thread.
+      # @api private — drains best-effort and stops the worker thread. A no-op
+      #   in stateless mode (+buffered: false+), which has no worker to stop.
       def _close
-        @buffer.close
+        @buffer&.close
+        nil
       end
     end
 

data/lib/smplkit/config/client.rb

@@ -337,8 +337,9 @@ module Smplkit
     # +base_url+/+api_key+ are used directly when supplied (the path a top-level
     # client takes after it has already resolved them); otherwise the config
     # resolver fills in whatever is missing (+~/.smplkit+ / env vars /
-    # defaults). The app base URL is returned alongside so a standalone client
-    # can open its own WebSocket against the event gateway.
+    # defaults). +environment+/+service+ resolve the same way (constructor
+    # argument wins). The app base URL is returned alongside so a standalone
+    # client can open its own WebSocket against the event gateway.
     #
     # @api private
     # @param api_key [String, nil] API key, or +nil+ to resolve it.
@@ -347,14 +348,20 @@ module Smplkit
     # @param profile [String, nil] Named +~/.smplkit+ profile section.
     # @param base_domain [String, nil] Base domain for API requests.
     # @param scheme [String, nil] URL scheme.
+    # @param environment [String, nil] Deployment environment, or +nil+ to
+    #   resolve it.
+    # @param service [String, nil] Service name, or +nil+ to resolve it.
     # @param debug [Boolean, nil] Enable SDK debug logging.
     # @param extra_headers [Hash{String => String}, nil] Headers attached to
     #   every request.
-    # @return [Array(Object, String, String)] The transport, the app base URL,
-    #   and the resolved API key.
-    def self.config_transport(api_key:, base_url:, profile:, base_domain:, scheme:, debug:, extra_headers:)
+    # @return [Array(Object, String, String, String, String)] The transport,
+    #   the app base URL, the resolved API key, the resolved environment, and
+    #   the resolved service (the last two +nil+ when configured nowhere).
+    def self.config_transport(api_key:, base_url:, profile:, base_domain:, scheme:,
+                              environment:, service:, debug:, extra_headers:)
       cfg = ConfigResolution.resolve_client_config(
-        profile: profile, api_key: api_key, base_domain: base_domain, scheme: scheme, debug: debug
+        profile: profile, api_key: api_key, base_domain: base_domain, scheme: scheme,
+        environment: environment, service: service, debug: debug
       )
       resolved_key = api_key.nil? ? cfg.api_key : api_key
       merged = {}
@@ -366,7 +373,7 @@ module Smplkit
       )
       app_url = ConfigResolution.service_url(cfg.scheme, "app", cfg.base_domain)
       transport = Transport.build_api_client(SmplkitGeneratedClient::Config, "config", tcfg, base_url: base_url)
-      [transport, app_url, resolved_key]
+      [transport, app_url, resolved_key, cfg.environment, cfg.service]
     end
 
     # The Smpl Config client (sync).
@@ -396,7 +403,11 @@ module Smplkit
       # @param api_key [String, nil] API key. When omitted, resolved from
       #   +SMPLKIT_API_KEY+ or +~/.smplkit+.
       # @param environment [String, nil] Deployment environment used to resolve
-      #   runtime config values and to scope discovery declarations.
+      #   runtime config values and to scope discovery declarations. When
+      #   omitted, resolved from +SMPLKIT_ENVIRONMENT+ or +~/.smplkit+.
+      # @param service [String, nil] Service name attached to discovery
+      #   declarations. When omitted, resolved from +SMPLKIT_SERVICE+ or
+      #   +~/.smplkit+. Optional.
       # @param base_url [String, nil] Full config-service base URL. Usually
       #   resolved from +base_domain+/+scheme+; supplied directly by the
       #   top-level clients which have already computed it.
@@ -407,30 +418,49 @@ module Smplkit
       # @param debug [Boolean, nil] Enable SDK debug logging.
       # @param extra_headers [Hash{String => String}, nil] Extra headers
       #   attached to every request.
+      # @param streaming [Boolean] Live updates over WebSocket (default
+      #   +true+): the first live call opens a shared socket and config changes
+      #   stream in. Set +false+ for the stateless read-through surface: the
+      #   first live call still fetches and resolves every config once
+      #   (blocking), reads stay local, +refresh+ re-fetches on demand, and NO
+      #   socket or background thread is ever created — the right shape for
+      #   serverless and edge runtimes. +on_change+ listeners fire only from
+      #   explicit +refresh+ calls in this mode (there is no stream to drive
+      #   them).
       # @param parent [Smplkit::Client, nil] Internal — the owning client. Not
       #   for direct use.
       # @param transport [Object, nil] Internal — a pre-built config transport
       #   supplied by a top-level client so the config surface shares one
       #   connection pool. Not for direct use.
       # @param metrics [Object, nil] Internal — the parent's metrics reporter.
-      def initialize(api_key = nil, environment: nil, base_url: nil, profile: nil,
+      def initialize(api_key = nil, environment: nil, service: nil, base_url: nil, profile: nil,
                      base_domain: nil, scheme: nil, debug: nil, extra_headers: nil,
-                     parent: nil, transport: nil, metrics: nil)
+                     streaming: true, parent: nil, transport: nil, metrics: nil)
         @parent = parent
         @metrics = metrics
-        @environment = parent.nil? ? environment : parent._environment
-        @service = parent&._service
+        @streaming = streaming ? true : false
         @standalone_api_key = nil
         if transport.nil?
-          @http, @app_base_url, @standalone_api_key = Smplkit::Config.config_transport(
-            api_key: api_key, base_url: base_url, profile: profile,
-            base_domain: base_domain, scheme: scheme, debug: debug, extra_headers: extra_headers
-          )
+          # Standalone: resolve like Smplkit::Client — defaults → ~/.smplkit →
+          # SMPLKIT_* env vars → constructor args — environment and service
+          # included.
+          @http, @app_base_url, @standalone_api_key, resolved_env, resolved_service =
+            Smplkit::Config.config_transport(
+              api_key: api_key, base_url: base_url, profile: profile,
+              base_domain: base_domain, scheme: scheme, environment: environment,
+              service: service, debug: debug, extra_headers: extra_headers
+            )
+          @environment = parent.nil? ? resolved_env : parent._environment
+          @service = parent.nil? ? resolved_service : parent._service
           @owns_transport = true
         else
           @http = transport
           @app_base_url = nil
           @owns_transport = false
+          # Wired: the parent has already resolved environment/service once —
+          # its values win over both the raw kwargs and re-resolution.
+          @environment = parent.nil? ? environment : parent._environment
+          @service = parent.nil? ? service : parent._service
         end
         @api = SmplkitGeneratedClient::Config::ConfigsApi.new(@http)
 
@@ -839,7 +869,8 @@ module Smplkit
       # Flushes any buffered discovery declarations, fetches and resolves every
       # config for the configured environment into the local cache, opens the
       # shared WebSocket, and subscribes to +config_changed+ / +config_deleted+
-      # / +configs_changed+ events.
+      # / +configs_changed+ events. In stateless mode (+streaming: false+) no
+      # socket is ever created; +refresh+ re-fetches on demand.
       #
       # Idempotent and internal — every live method calls it on first use, so
       # the live surface auto-connects with no explicit step.
@@ -859,6 +890,7 @@ module Smplkit
         # old_cache, so any registered listeners see "initial" events).
         do_refresh("initial")
         @connected = true
+        return unless @streaming
 
         @ws_manager = ensure_ws
         @ws_manager.on("config_changed") { |data| handle_config_changed(data) }
@@ -992,7 +1024,13 @@ module Smplkit
       def trigger_background_flush_if_needed
         return unless @buffer.pending_count >= CONFIG_BATCH_FLUSH_SIZE
 
-        Thread.new { threshold_flush }
+        # Stateless mode (+streaming: false+) never spawns background threads —
+        # the threshold flush runs inline (blocking) instead.
+        if @streaming
+          Thread.new { threshold_flush }
+        else
+          threshold_flush
+        end
       end
 
       def threshold_flush

data/lib/smplkit/config_resolution.rb

@@ -36,7 +36,7 @@ module Smplkit
     )
 
     ResolvedClientConfig = Struct.new(
-      :api_key, :base_domain, :scheme, :debug, :extra_headers,
+      :api_key, :base_domain, :scheme, :environment, :service, :debug, :extra_headers,
       keyword_init: true
     )
 
@@ -160,18 +160,21 @@ module Smplkit
     end
 
     def resolve_client_config(profile: nil, api_key: nil, base_domain: nil,
-                              scheme: nil, debug: nil, home_dir: nil)
+                              scheme: nil, environment: nil, service: nil,
+                              debug: nil, home_dir: nil)
       resolved = {
         "api_key" => nil,
         "base_domain" => "smplkit.com",
         "scheme" => "https",
+        "environment" => nil,
+        "service" => nil,
         "debug" => false
       }
 
       active_profile = profile || ENV["SMPLKIT_PROFILE"] || "default"
 
       file_values = read_config_file(active_profile, home_dir: home_dir)
-      %w[api_key base_domain scheme debug].each do |key|
+      %w[api_key base_domain scheme environment service debug].each do |key|
         next unless file_values.key?(key)
 
         val = file_values[key]
@@ -180,7 +183,8 @@ module Smplkit
 
       [
         %w[api_key SMPLKIT_API_KEY], %w[base_domain SMPLKIT_BASE_DOMAIN],
-        %w[scheme SMPLKIT_SCHEME], %w[debug SMPLKIT_DEBUG]
+        %w[scheme SMPLKIT_SCHEME], %w[environment SMPLKIT_ENVIRONMENT],
+        %w[service SMPLKIT_SERVICE], %w[debug SMPLKIT_DEBUG]
       ].each do |key, env_var|
         env_val = ENV.fetch(env_var, "")
         next if env_val.empty?
@@ -188,7 +192,10 @@ module Smplkit
         resolved[key] = key == "debug" ? parse_bool(env_val, env_var) : env_val
       end
 
-      ctor = { "api_key" => api_key, "base_domain" => base_domain, "scheme" => scheme, "debug" => debug }
+      ctor = {
+        "api_key" => api_key, "base_domain" => base_domain, "scheme" => scheme,
+        "environment" => environment, "service" => service, "debug" => debug
+      }
       ctor.each { |k, v| resolved[k] = v unless v.nil? }
 
       missing_required(resolved, "api_key", active_profile)
@@ -197,6 +204,11 @@ module Smplkit
         api_key: resolved["api_key"].to_s,
         base_domain: resolved["base_domain"].to_s,
         scheme: resolved["scheme"].to_s,
+        # Preserve nil rather than coercing to the literal string "" —
+        # +environment+ and +service+ are optional and their absence is
+        # meaningful (no environment signal is sent on the wire).
+        environment: resolved["environment"]&.to_s,
+        service: resolved["service"]&.to_s,
         debug: resolved["debug"] ? true : false
       )
     end

data/lib/smplkit/flags/client.rb

@@ -145,14 +145,17 @@ module Smplkit
     # +base_url+/+api_key+ are used directly when supplied (the path a top-level
     # client takes after it has already resolved them); otherwise the management
     # config resolver fills in whatever is missing (+~/.smplkit+ / env vars /
-    # defaults). The app transport backs the standalone contexts client
+    # defaults). +environment+/+service+ resolve the same way (constructor
+    # argument wins). The app transport backs the standalone contexts client
     # (evaluation-context registration); the app base URL is returned so a
     # standalone client can open its own WebSocket against the event gateway.
     #
     # @api private
-    def self.flags_transport(api_key:, base_url:, profile:, base_domain:, scheme:, debug:, extra_headers:)
+    def self.flags_transport(api_key:, base_url:, profile:, base_domain:, scheme:,
+                             environment:, service:, debug:, extra_headers:)
       cfg = ConfigResolution.resolve_client_config(
-        profile: profile, api_key: api_key, base_domain: base_domain, scheme: scheme, debug: debug
+        profile: profile, api_key: api_key, base_domain: base_domain, scheme: scheme,
+        environment: environment, service: service, debug: debug
       )
       resolved_key = api_key.nil? ? cfg.api_key : api_key
       merged = {}
@@ -165,7 +168,7 @@ module Smplkit
       app_url = ConfigResolution.service_url(cfg.scheme, "app", cfg.base_domain)
       flags_http = Transport.build_api_client(SmplkitGeneratedClient::Flags, "flags", tcfg, base_url: base_url)
       app_http = Transport.build_api_client(SmplkitGeneratedClient::App, "app", tcfg)
-      [flags_http, app_http, app_url, resolved_key]
+      [flags_http, app_http, app_url, resolved_key, cfg.environment, cfg.service]
     end
 
     # The Smpl Flags client (sync).
@@ -186,24 +189,68 @@ module Smplkit
     # definitions into the local cache, and opens the live-updates WebSocket. No
     # explicit install step is required.
     class FlagsClient
-      def initialize(api_key = nil, environment: nil, base_url: nil, profile: nil,
+      # @param api_key [String, nil] API key. When omitted, resolved from
+      #   +SMPLKIT_API_KEY+ or +~/.smplkit+.
+      # @param environment [String, nil] Deployment environment used to resolve
+      #   runtime flag values and to scope discovery declarations. When
+      #   omitted, resolved from +SMPLKIT_ENVIRONMENT+ or +~/.smplkit+.
+      # @param service [String, nil] Service name attached to discovery
+      #   declarations and auto-injected into the evaluation context. When
+      #   omitted, resolved from +SMPLKIT_SERVICE+ or +~/.smplkit+. Optional.
+      # @param base_url [String, nil] Full flags-service base URL. Usually
+      #   resolved from +base_domain+/+scheme+; supplied directly by the
+      #   top-level clients which have already computed it.
+      # @param profile [String, nil] Named +~/.smplkit+ profile section.
+      # @param base_domain [String, nil] Base domain for API requests (default
+      #   +"smplkit.com"+).
+      # @param scheme [String, nil] URL scheme (default +"https"+).
+      # @param debug [Boolean, nil] Enable SDK debug logging.
+      # @param extra_headers [Hash{String => String}, nil] Extra headers
+      #   attached to every request.
+      # @param streaming [Boolean] Live updates over WebSocket (default
+      #   +true+): the first live call opens a shared socket and flag changes
+      #   stream in. Set +false+ for the stateless read-through surface: the
+      #   first live call still fetches all flag definitions once (blocking),
+      #   evaluation stays local, +refresh+ re-fetches on demand, and NO socket
+      #   or background thread is ever created — the right shape for serverless
+      #   and edge runtimes. +on_change+ listeners fire only from explicit
+      #   +refresh+ calls in this mode (there is no stream to drive them).
+      # @param parent [Smplkit::Client, nil] Internal — the owning client. Not
+      #   for direct use.
+      # @param transport [Object, nil] Internal — a pre-built flags transport
+      #   supplied by a top-level client so the flags surface shares one
+      #   connection pool. Not for direct use.
+      # @param contexts [Object, nil] Internal — +client.platform.contexts+
+      #   used for evaluation-context registration. Not for direct use.
+      # @param metrics [Object, nil] Internal — the parent's metrics reporter.
+      def initialize(api_key = nil, environment: nil, service: nil, base_url: nil, profile: nil,
                      base_domain: nil, scheme: nil, debug: nil, extra_headers: nil,
-                     parent: nil, transport: nil, contexts: nil, metrics: nil)
+                     streaming: true, parent: nil, transport: nil, contexts: nil, metrics: nil)
         @parent = parent
         @metrics = metrics
-        @environment = parent.nil? ? environment : parent._environment
-        @service = parent&._service
+        @streaming = streaming ? true : false
         @standalone_api_key = nil
         if transport.nil?
-          @flags_http, app_http, @app_base_url, @standalone_api_key = Flags.flags_transport(
-            api_key: api_key, base_url: base_url, profile: profile,
-            base_domain: base_domain, scheme: scheme, debug: debug, extra_headers: extra_headers
-          )
+          # Standalone: resolve like Smplkit::Client — defaults → ~/.smplkit →
+          # SMPLKIT_* env vars → constructor args — environment and service
+          # included.
+          @flags_http, app_http, @app_base_url, @standalone_api_key, resolved_env, resolved_service =
+            Flags.flags_transport(
+              api_key: api_key, base_url: base_url, profile: profile,
+              base_domain: base_domain, scheme: scheme, environment: environment,
+              service: service, debug: debug, extra_headers: extra_headers
+            )
+          @environment = parent.nil? ? resolved_env : parent._environment
+          @service = parent.nil? ? resolved_service : parent._service
           # Standalone: build our own contexts client (and own its app transport).
           @contexts = Platform::ContextsClient.new(app_http, ContextRegistrationBuffer.new)
         else
           @flags_http = transport
           @app_base_url = nil
+          # Wired: the parent has already resolved environment/service once —
+          # its values win over both the raw kwargs and re-resolution.
+          @environment = parent.nil? ? environment : parent._environment
+          @service = parent.nil? ? service : parent._service
           # Wired: borrow client.platform.contexts as the evaluation-context
           # registration seam.
           @contexts = contexts
@@ -372,7 +419,13 @@ module Smplkit
         end
         return unless @buffer.pending_count >= FLAG_BATCH_FLUSH_SIZE
 
-        Thread.new { threshold_flush }
+        # Stateless mode (+streaming: false+) never spawns background threads —
+        # the threshold flush runs inline (blocking) instead.
+        if @streaming
+          Thread.new { threshold_flush }
+        else
+          threshold_flush
+        end
       end
 
       # POST pending declarations to the flags bulk endpoint.
@@ -648,6 +701,8 @@ module Smplkit
       # Flushes any buffered discovery declarations, fetches all flag
       # definitions into the local cache, opens the shared WebSocket, and
       # subscribes to +flag_changed+ / +flag_deleted+ / +flags_changed+ events.
+      # In stateless mode (+streaming: false+) no socket is ever created;
+      # +refresh+ re-fetches on demand.
       #
       # Idempotent and internal — every live method calls it on first use, so
       # the live surface auto-connects with no explicit step.
@@ -666,6 +721,7 @@ module Smplkit
         fetch_all_flags
         @cache.clear
         @connected = true
+        return unless @streaming
 
         @ws_manager = ensure_ws
         return if @ws_subscribed

data/lib/smplkit/jobs/client.rb

@@ -284,12 +284,14 @@ module Smplkit
     # Reuses the config resolver (jobs is account-global and never
     # environment-scoped at the transport layer) so a standalone jobs client
     # resolves credentials/base-domain from +~/.smplkit+ / env vars /
-    # constructor args exactly like the top-level clients do. Smpl Jobs is
-    # JSON:API, so the transport carries the +application/vnd.api+json+ Accept
-    # header.
-    def self.jobs_transport(api_key:, profile:, base_domain:, scheme:, debug:, extra_headers:)
+    # constructor args exactly like the top-level clients do. The client-level
+    # default +environment+ resolves through the same chain (constructor
+    # argument wins) and is returned alongside. Smpl Jobs is JSON:API, so the
+    # transport carries the +application/vnd.api+json+ Accept header.
+    def self.jobs_transport(api_key:, profile:, base_domain:, scheme:, environment:, debug:, extra_headers:)
       cfg = ConfigResolution.resolve_client_config(
-        profile: profile, api_key: api_key, base_domain: base_domain, scheme: scheme, debug: debug
+        profile: profile, api_key: api_key, base_domain: base_domain, scheme: scheme,
+        environment: environment, debug: debug
       )
       merged = {}
       merged.merge!(cfg.extra_headers || {})
@@ -298,7 +300,10 @@ module Smplkit
         api_key: cfg.api_key, base_domain: cfg.base_domain, scheme: cfg.scheme,
         debug: cfg.debug, extra_headers: merged
       )
-      Transport.build_api_client(SmplkitGeneratedClient::Jobs, "jobs", tcfg, accept: "application/vnd.api+json")
+      transport = Transport.build_api_client(
+        SmplkitGeneratedClient::Jobs, "jobs", tcfg, accept: "application/vnd.api+json"
+      )
+      [transport, cfg.environment]
     end
 
     # The active-record entry points are {#new_recurring_job}, {#new_manual_job},
@@ -327,18 +332,26 @@ module Smplkit
       # @param environment [String, nil] Default environment for
       #   environment-scoped operations — the environment a one-off job created
       #   through this client is born in, the default a manual run executes in,
-      #   and the default scope for +runs.list+. +nil+ leaves these unset (the
+      #   and the default scope for +runs.list+. When omitted, resolved from
+      #   +SMPLKIT_ENVIRONMENT+ or +~/.smplkit+. +nil+ leaves these unset (the
       #   credential's permitted environment is implied where unambiguous).
       # @param auth_client [Object, nil] Internal — a pre-built transport
       #   supplied by a top-level client so the jobs surface shares one
       #   connection pool. Not for direct use.
       def initialize(api_key = nil, profile: nil, base_domain: nil, scheme: nil,
                      debug: nil, extra_headers: nil, environment: nil, auth_client: nil)
-        auth = auth_client || Jobs.jobs_transport(
-          api_key: api_key, profile: profile, base_domain: base_domain,
-          scheme: scheme, debug: debug, extra_headers: extra_headers
-        )
-        @environment = environment
+        if auth_client.nil?
+          # Standalone: resolve like Smplkit::Client — defaults → ~/.smplkit →
+          # SMPLKIT_* env vars → constructor args — environment included.
+          auth, resolved_env = Jobs.jobs_transport(
+            api_key: api_key, profile: profile, base_domain: base_domain,
+            scheme: scheme, environment: environment, debug: debug, extra_headers: extra_headers
+          )
+          @environment = resolved_env
+        else
+          auth = auth_client
+          @environment = environment
+        end
         @api = SmplkitGeneratedClient::Jobs::JobsApi.new(auth)
         @runs = RunsClient.new(SmplkitGeneratedClient::Jobs::RunsApi.new(auth), environment: environment)
         @retry_policies = RetryPoliciesClient.new(SmplkitGeneratedClient::Jobs::RetryPoliciesApi.new(auth))

data/lib/smplkit/logging/client.rb

@@ -44,14 +44,18 @@ module Smplkit
     # +base_url+/+api_key+ are used directly when supplied (the path a top-level
     # client takes after it has already resolved them); otherwise the management
     # config resolver fills in whatever is missing (+~/.smplkit+ / env vars /
-    # defaults). The app transport is needed for the WebSocket gateway, which
-    # lives on the app service (like flags); the app base URL is returned so a
-    # standalone client can open its own WebSocket against the event gateway.
+    # defaults). +environment+/+service+ resolve the same way (constructor
+    # argument wins). The app transport is needed for the WebSocket gateway,
+    # which lives on the app service (like flags); the app base URL is returned
+    # so a standalone client can open its own WebSocket against the event
+    # gateway.
     #
     # @api private
-    def self.logging_transport(api_key:, base_url:, profile:, base_domain:, scheme:, debug:, extra_headers:)
+    def self.logging_transport(api_key:, base_url:, profile:, base_domain:, scheme:,
+                               environment:, service:, debug:, extra_headers:)
       cfg = ConfigResolution.resolve_client_config(
-        profile: profile, api_key: api_key, base_domain: base_domain, scheme: scheme, debug: debug
+        profile: profile, api_key: api_key, base_domain: base_domain, scheme: scheme,
+        environment: environment, service: service, debug: debug
       )
       resolved_key = api_key.nil? ? cfg.api_key : api_key
       merged = {}
@@ -64,7 +68,7 @@ module Smplkit
       app_url = ConfigResolution.service_url(cfg.scheme, "app", cfg.base_domain)
       logging_http = Transport.build_api_client(SmplkitGeneratedClient::Logging, "logging", tcfg, base_url: base_url)
       app_http = Transport.build_api_client(SmplkitGeneratedClient::App, "app", tcfg)
-      [logging_http, app_http, app_url, resolved_key]
+      [logging_http, app_http, app_url, resolved_key, cfg.environment, cfg.service]
     end
 
     # Discover and load the SDK's built-in logging adapters.
@@ -107,9 +111,15 @@ module Smplkit
     # +LoggingClient+ and shared here so discovery (driven by
     # +LoggingClient#install+) and explicit +register+ drain through one queue.
     class LoggersClient
-      def initialize(http_client, buffer:)
+      # @param http_client [Object] The logging-service transport.
+      # @param buffer [LoggerRegistrationBuffer] The shared discovery buffer,
+      #   owned by the fused +LoggingClient+.
+      # @param streaming [Boolean] Internal — +false+ runs threshold flushes
+      #   inline instead of on a background thread (stateless mode).
+      def initialize(http_client, buffer:, streaming: true)
         @api = SmplkitGeneratedClient::Logging::LoggersApi.new(http_client)
         @buffer = buffer
+        @streaming = streaming ? true : false
       end
 
       # Queue one or more logger sources for registration with the server.
@@ -138,7 +148,13 @@ module Smplkit
         end
         return unless @buffer.pending_count >= LOGGER_BATCH_FLUSH_SIZE
 
-        Thread.new { threshold_flush }
+        # Stateless mode (+streaming: false+) never spawns background threads —
+        # the threshold flush runs inline (blocking) instead.
+        if @streaming
+          Thread.new { threshold_flush }
+        else
+          threshold_flush
+        end
       end
 
       # Drain the buffer and POST pending logger sources to the bulk endpoint.
@@ -423,28 +439,70 @@ module Smplkit
     class LoggingClient
       attr_reader :loggers, :log_groups
 
-      def initialize(api_key = nil, environment: nil, base_url: nil, profile: nil,
+      # @param api_key [String, nil] API key. When omitted, resolved from
+      #   +SMPLKIT_API_KEY+ or +~/.smplkit+.
+      # @param environment [String, nil] Deployment environment used to resolve
+      #   logger levels and to scope discovery declarations. When omitted,
+      #   resolved from +SMPLKIT_ENVIRONMENT+ or +~/.smplkit+.
+      # @param service [String, nil] Service name attached to discovery
+      #   declarations. When omitted, resolved from +SMPLKIT_SERVICE+ or
+      #   +~/.smplkit+. Optional.
+      # @param base_url [String, nil] Full logging-service base URL. Usually
+      #   resolved from +base_domain+/+scheme+; supplied directly by the
+      #   top-level clients which have already computed it.
+      # @param profile [String, nil] Named +~/.smplkit+ profile section.
+      # @param base_domain [String, nil] Base domain for API requests (default
+      #   +"smplkit.com"+).
+      # @param scheme [String, nil] URL scheme (default +"https"+).
+      # @param debug [Boolean, nil] Enable SDK debug logging.
+      # @param extra_headers [Hash{String => String}, nil] Extra headers
+      #   attached to every request.
+      # @param streaming [Boolean] Live updates over WebSocket (default
+      #   +true+): +install+ opens a shared socket and server-side level
+      #   changes stream in. Set +false+ for the stateless apply-once surface:
+      #   +install+ still loads adapters, flushes discovery, and applies the
+      #   server's levels — all blocking — but NO socket or background thread
+      #   is ever created; +refresh+ re-fetches and re-applies on demand. The
+      #   right shape for serverless and edge runtimes; note that live level
+      #   changes then arrive only via +refresh+.
+      # @param parent [Smplkit::Client, nil] Internal — the owning client. Not
+      #   for direct use.
+      # @param transport [Object, nil] Internal — a pre-built logging transport
+      #   supplied by a top-level client so the logging surface shares one
+      #   connection pool. Not for direct use.
+      # @param metrics [Object, nil] Internal — the parent's metrics reporter.
+      def initialize(api_key = nil, environment: nil, service: nil, base_url: nil, profile: nil,
                      base_domain: nil, scheme: nil, debug: nil, extra_headers: nil,
-                     parent: nil, transport: nil, metrics: nil)
+                     streaming: true, parent: nil, transport: nil, metrics: nil)
         @parent = parent
         @metrics = metrics
-        @environment = parent.nil? ? environment : parent._environment
-        @service = parent&._service
+        @streaming = streaming ? true : false
         @standalone_api_key = nil
         if transport.nil?
-          @logging_http, _app_http, @app_base_url, @standalone_api_key = Logging.logging_transport(
-            api_key: api_key, base_url: base_url, profile: profile,
-            base_domain: base_domain, scheme: scheme, debug: debug, extra_headers: extra_headers
-          )
+          # Standalone: resolve like Smplkit::Client — defaults → ~/.smplkit →
+          # SMPLKIT_* env vars → constructor args — environment and service
+          # included.
+          @logging_http, _app_http, @app_base_url, @standalone_api_key, resolved_env, resolved_service =
+            Logging.logging_transport(
+              api_key: api_key, base_url: base_url, profile: profile,
+              base_domain: base_domain, scheme: scheme, environment: environment,
+              service: service, debug: debug, extra_headers: extra_headers
+            )
+          @environment = parent.nil? ? resolved_env : parent._environment
+          @service = parent.nil? ? resolved_service : parent._service
         else
           @logging_http = transport
           @app_base_url = nil
+          # Wired: the parent has already resolved environment/service once —
+          # its values win over both the raw kwargs and re-resolution.
+          @environment = parent.nil? ? environment : parent._environment
+          @service = parent.nil? ? service : parent._service
         end
 
         # Discovery buffer is owned by this client; the loggers sub-client shares
         # it so discovery and explicit registration drain together.
         @buffer = LoggerRegistrationBuffer.new
-        @loggers = LoggersClient.new(@logging_http, buffer: @buffer)
+        @loggers = LoggersClient.new(@logging_http, buffer: @buffer, streaming: @streaming)
         @log_groups = LogGroupsClient.new(@logging_http)
 
         # Live-surface state.
@@ -542,9 +600,13 @@ module Smplkit
                         "(logging: #{@logging_http&.config&.host}): #{e.class}: #{e.message}")
         end
 
-        # 7. Register WebSocket event handlers for real-time level updates
-        @ws_manager = ensure_ws
-        ws_handlers.each { |event, handler| @ws_manager.on(event, &handler) }
+        # 7. Register WebSocket event handlers for real-time level updates.
+        # In stateless mode (+streaming: false+) no socket is ever created —
+        # level changes then arrive only via +refresh+.
+        if @streaming
+          @ws_manager = ensure_ws
+          ws_handlers.each { |event, handler| @ws_manager.on(event, &handler) }
+        end
 
         @connected = true
         self

data/lib/smplkit/transport.rb

@@ -15,10 +15,37 @@ module Smplkit
   #
   # @api private
   module Transport
-    SDK_OWNED_HEADERS = %w[authorization content-type user-agent].freeze
+    # Headers the SDK always owns — +extra_headers+ cannot override these
+    # (authorization carries the credential; content-type is set per request
+    # by the generated client). User-Agent is deliberately NOT in this list:
+    # a caller-supplied User-Agent wins over the SDK default.
+    SDK_OWNED_HEADERS = %w[authorization content-type].freeze
 
     module_function
 
+    # Whether an extra-headers hash carries a caller-supplied User-Agent,
+    # under any representation the surface accepts — string keys in any
+    # casing ("User-Agent", "user-agent", …) and symbol keys (:"user-agent").
+    def user_agent_supplied?(extra_headers)
+      (extra_headers || {}).keys.any? { |k| k.to_s.casecmp("user-agent").zero? }
+    end
+
+    # Stamp the default headers onto a generated +ApiClient+.
+    #
+    # User-Agent precedence: caller-supplied via +extra_headers+ (any casing
+    # or symbol representation) > the SDK default (+Smplkit.user_agent+,
+    # +smplkit-sdk-ruby/<version>+) > the generated stack's own default
+    # (+OpenAPI-Generator/x.y.z/ruby+, removed here so exactly one
+    # User-Agent representation remains). Other +extra_headers+ entries are
+    # applied as-is unless SDK-owned.
+    def apply_headers(client, extra_headers)
+      client.default_headers.delete("User-Agent")
+      client.default_headers["User-Agent"] = Smplkit.user_agent unless user_agent_supplied?(extra_headers)
+      (extra_headers || {}).each do |k, v|
+        client.default_headers[k] = v unless SDK_OWNED_HEADERS.include?(k.to_s.downcase)
+      end
+    end
+
     # Project the runtime +ResolvedConfig+ down to the transport subset.
     #
     # The top-level client's resolved config is a superset of what the
@@ -92,11 +119,8 @@ module Smplkit
       configuration.debugging = cfg.debug
       HttpPool.configure(configuration)
       generated_module::ApiClient.new(configuration).tap do |client|
-        client.default_headers["User-Agent"] = "smplkit-ruby-sdk/#{Smplkit::VERSION}"
         client.default_headers["Accept"] = accept if accept
-        (cfg.extra_headers || {}).each do |k, v|
-          client.default_headers[k] = v unless SDK_OWNED_HEADERS.include?(k.downcase)
-        end
+        apply_headers(client, cfg.extra_headers)
       end
     end
   end

data/lib/smplkit/version.rb

@@ -1,5 +1,41 @@
 # frozen_string_literal: true
 
 module Smplkit
+  # Local-development fallback only. The canonical version of a published gem
+  # is stamped into the gem's build-time metadata from the release tag by the
+  # gemspec (see +smplkit.gemspec+); +Smplkit.gem_version+ reads that metadata
+  # at runtime. This constant is used when the SDK runs from a source
+  # checkout that has no installed gem to consult.
   VERSION = "0.0.0"
+
+  # The version of the smplkit gem actually loaded, read from RubyGems
+  # package metadata.
+  #
+  # The release workflow never rewrites +VERSION+ above — the published
+  # version exists only in the git tag and, via the gemspec's build-time
+  # derivation, in the built gem's serialized specification. An installed gem
+  # therefore reports the real release version through +Gem.loaded_specs+,
+  # while a plain source checkout falls back to +VERSION+. The +smplkit-sdk+
+  # name is the ADR-046 §2.1 fallback gem name.
+  #
+  # @api private
+  # @return [String] the loaded gem's version, or +VERSION+ when the SDK is
+  #   not running from an installed gem.
+  def self.gem_version
+    spec = Gem.loaded_specs["smplkit"] || Gem.loaded_specs["smplkit-sdk"]
+    spec ? spec.version.to_s : VERSION
+  end
+
+  # The default User-Agent stamped on every outbound request (HTTP and the
+  # WebSocket handshake) when the caller has not supplied their own.
+  #
+  # The platform sits behind a WAF that rejects requests carrying no
+  # User-Agent, and an SDK-identifying value keeps support/telemetry able to
+  # attribute traffic to an SDK and version in access logs.
+  #
+  # @api private
+  # @return [String] +smplkit-sdk-ruby/<version>+
+  def self.user_agent
+    "smplkit-sdk-ruby/#{gem_version}"
+  end
 end

data/lib/smplkit/ws.rb

@@ -34,7 +34,10 @@ module Smplkit
   class SharedWebSocket
     BACKOFF_SCHEDULE = [1, 2, 4, 8, 16, 32, 60].freeze
 
-    USER_AGENT = "smplkit-ruby-sdk/#{Smplkit::VERSION}".freeze
+    # Sent on the WebSocket upgrade request — the platform WAF rejects
+    # handshakes that carry no User-Agent. There is no caller-supplied
+    # header surface on the WebSocket, so the SDK default always applies.
+    USER_AGENT = Smplkit.user_agent.freeze
 
     def initialize(app_base_url:, api_key:, metrics: nil)
       @app_base_url = app_base_url

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: smplkit
 version: !ruby/object:Gem::Version
-  version: 3.0.129
+  version: 3.0.132
 platform: ruby
 authors:
 - Smpl Solutions LLC