smplkit 3.0.129 → 3.0.131

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0b6297c50f89cbe656fb1a9b3d26990f853fccc9f1894957d0e3a43fadca226f
-  data.tar.gz: 97364f6d0e110220f5945b1eb5e3060c843a8855921884e344ebaf0f765e676d
+  metadata.gz: 80d71501763192031a0fb659bbe16d4aa0b021c1995dbcef803cb3cc11298355
+  data.tar.gz: e8f81502fe54983ca18c2d83bda4089e36f21b6bd5e6b58aea74ebd4b6a5edec
 SHA512:
-  metadata.gz: deeb4adfddff9d195207ef70887157829816d0f933daca4bcecdbe149c8b2f93fe9798993cda6c26791168136ac4e5a2cd259f2481019e91c72fff2e97e10e64
-  data.tar.gz: 6beb5e6fff975ea31e05f02934003736228c8ec63431f9d3ffd74479f029328cac26c7c63af2caf85fe859eba43af26850a6868ccab45f0b2521337b207bd389
+  metadata.gz: cd8267d396fcb466ff2f4b2ac8addfbbd667b33bc122a599628d0a49134be4c93810fae6b779ae12f633d52062fc032ad3da0948d36c5fd472857ac0d604dfae
+  data.tar.gz: 36368e8ea040abb9905ff4d84650cd147cadf3bcef6038165970c1804df311d42e3e84fdd51e522042ee7c5a98324961a3733efc86f207243079db4a0872997d

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
@@ -37,6 +38,13 @@ module Smplkit
     # @param extra_headers [Hash{String => String}, nil] Extra headers attached
     #   to every request. SDK-owned headers (authorization, content-type,
     #   user-agent) cannot be overridden.
+    # @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
 
@@ -44,19 +52,21 @@ module Smplkit
 
       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
@@ -78,7 +88,10 @@ module Smplkit
         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)
+        @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

metadata

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