smplkit 3.0.95 → 3.0.96

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: daa3b1ae6cdf8922badb57509c04e16d007372f82b95661de9f223602f174a2b
-  data.tar.gz: d03104fec0c8f27c9d5942821b8c49143d6321f4b9790da7be91f7a2aef55ddf
+  metadata.gz: a1d765730dd1bb26ebf38f16627878d7d33220bc20bd005b98b12303a18e88c1
+  data.tar.gz: 1109c9cd1b02865ae3d2148a8232509b185d828ed8762c025cf82dcfc9c9c09e
 SHA512:
-  metadata.gz: 86ef3645c6d7c44b4afd90ac2948762a3ff4d2d2df6076fb524f6f636cac2d0b0335d55e4bd3a6fac974933f65f332a2754eac9ac417d2aff91ab4b7bc57c874
-  data.tar.gz: 786ad2e7704b39d79090c51b6fc4663e6072fda4e1e3d51fb70abbb272f951a17246351a7a0600c4e56d9c696c82f486f2fda490398a9e0e4aa0e1be4c728c1e
+  metadata.gz: '099f6f60a8acdbd5804cd32743d7f6d6e28261de9901f08a354536da0e49a8b3cec0809790106b072cd7275daa60fdd4279b979dca22590ae74d87382bed04ed'
+  data.tar.gz: '089e631caa282df42aea0344a2e38fe17795e2d773d6799e6684ee1d389d418b0d4c1714fcf398c70b8961fdd4919b11c1b7b56f26b8e7a6e1b631853ac12447'

data/lib/smplkit/account/client.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "json"
+
+module Smplkit
+  module Account
+    # Resolve the (app_base_url, api_key, extra_headers) for the settings client.
+    #
+    # +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 management config resolver fills in whatever is missing.
+    def self.resolve_account_target(api_key:, base_url:, profile:, base_domain:, scheme:, debug:, extra_headers:)
+      cfg = ConfigResolution.resolve_management_config(
+        profile: profile, api_key: api_key, base_domain: base_domain, scheme: scheme, debug: debug
+      )
+      resolved_key = api_key.nil? ? cfg.api_key : api_key
+      app_url = base_url.nil? ? ConfigResolution.service_url(cfg.scheme, "app", cfg.base_domain) : base_url
+      headers = {}
+      headers.merge!(cfg.extra_headers || {})
+      headers.merge!(extra_headers || {})
+      [app_url.sub(%r{/+\z}, ""), resolved_key, headers]
+    end
+
+    # Sync account-settings get/save (+client.account.settings+).
+    #
+    # The endpoint isn't JSON:API — body is a raw JSON object — so we use an
+    # HTTP client directly rather than going through a generated client.
+    class SettingsClient
+      SETTINGS_PATH = "/api/v1/accounts/current/settings"
+
+      def initialize(app_base_url, api_key, extra_headers = nil)
+        @base_url = app_base_url
+        @headers = {
+          "Authorization" => "Bearer #{api_key}",
+          "Content-Type" => "application/json"
+        }.merge(extra_headers || {})
+      end
+
+      def get
+        resp = connection.get(SETTINGS_PATH)
+        Errors.raise_for_status(resp.status, resp.body.to_s)
+        AccountSettings.new(self, data: parse_body(resp.body))
+      end
+
+      def _save(data)
+        resp = connection.put(SETTINGS_PATH) { |req| req.body = JSON.generate(data) }
+        Errors.raise_for_status(resp.status, resp.body.to_s)
+        AccountSettings.new(self, data: parse_body(resp.body))
+      end
+
+      private
+
+      # A short-lived connection per call — mirrors the Python settings client
+      # opening and closing its own HTTP client each time.
+      def connection
+        Faraday.new(url: @base_url, headers: @headers, request: { timeout: 30 })
+      end
+
+      def parse_body(body)
+        return {} if body.nil? || body.to_s.empty?
+
+        parsed = JSON.parse(body)
+        parsed.is_a?(Hash) ? parsed : {}
+      rescue JSON::ParserError
+        {}
+      end
+    end
+
+    # The Smpl Account client (sync).
+    #
+    # Exposes the authenticated account's own configuration, reachable as
+    # +client.account+ (+Smplkit::Client+) or constructed directly:
+    #
+    #   account = Smplkit::AccountClient.new(api_key: "sk_...")
+    #   settings = account.settings.get
+    #   settings.environment_order = ["production", "staging"]
+    #   settings.save
+    #
+    # Sub-client: +settings+ (get/save). Pure CRUD — no +install+ required.
+    #
+    # @param api_key [String, nil] API key. When omitted, resolved from
+    #   +SMPLKIT_API_KEY+ or +~/.smplkit+.
+    # @param base_url [String, nil] Full app-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, nil] Extra headers attached to every request.
+    class AccountClient
+      attr_reader :settings
+
+      def initialize(api_key: nil, base_url: nil, profile: nil, base_domain: nil,
+                     scheme: nil, debug: nil, extra_headers: nil)
+        app_url, resolved_key, headers = Account.resolve_account_target(
+          api_key: api_key, base_url: base_url, profile: profile,
+          base_domain: base_domain, scheme: scheme, debug: debug, extra_headers: extra_headers
+        )
+        @settings = SettingsClient.new(app_url, resolved_key, headers.empty? ? nil : headers)
+      end
+
+      # No-op — the settings client opens a short-lived HTTP client per call.
+      def close; end
+
+      # Construct, yield to the block, and close on exit.
+      def self.open(**kwargs)
+        client = new(**kwargs)
+        begin
+          yield client
+        ensure
+          client.close
+        end
+      end
+    end
+  end
+
+  AccountClient = Account::AccountClient
+end

data/lib/smplkit/account/models.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Smplkit
+  module Account
+    # Active-record account-settings model.
+    #
+    # The wire format is opaque JSON. Documented keys are exposed as typed
+    # properties; unknown keys live in +raw+. +save+ writes the full settings
+    # object back.
+    class AccountSettings
+      def initialize(client = nil, data: nil)
+        @client = client
+        @data = data ? data.dup : {}
+      end
+
+      # The full settings dict. Mutations are persisted on save.
+      def raw
+        @data
+      end
+
+      def raw=(value)
+        @data = value.dup
+      end
+
+      # Canonical ordering of STANDARD environments. Empty list if unset.
+      def environment_order
+        Array(@data["environment_order"] || [])
+      end
+
+      def environment_order=(value)
+        @data["environment_order"] = value.to_a
+      end
+
+      def save
+        raise "AccountSettings was constructed without a client; cannot save" if @client.nil?
+
+        other = @client._save(@data)
+        _apply(other)
+        self
+      end
+      alias save! save
+
+      def to_s
+        "AccountSettings(#{@data.inspect})"
+      end
+      alias inspect to_s
+
+      def _apply(other)
+        @data = other.raw.dup
+      end
+    end
+  end
+end

data/lib/smplkit/api_support.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module Smplkit
+  # Ruby-internal adapters bridging the generated client layer to the wrapper.
+  module ApiSupport
+    # Default page[size] the runtime asks for when walking a list endpoint to
+    # completion. The platform caps page[size] at 1000; using the same value
+    # here makes the minimum number of round-trips per exhaustive fetch.
+    RUNTIME_PAGE_SIZE = 1000
+
+    # Wraps a generated-API call and converts any +ApiError+ raised by the
+    # generated layer into the +Smplkit::Error+ hierarchy. Connection-level
+    # failures (no response from the server) become +Smplkit::ConnectionError+;
+    # status-coded failures route through +Errors.raise_for_status+ which emits
+    # +NotFoundError+ / +ConflictError+ / +ValidationError+ / +Error+ depending
+    # on the JSON:API body.
+    module ErrorMapping
+      module_function
+
+      def call
+        yield
+      rescue StandardError => e
+        raise unless generated_api_error?(e)
+
+        raise Smplkit::ConnectionError, e.message.to_s if e.code.nil? || e.code.zero?
+
+        Smplkit::Errors.raise_for_status(e.code, e.response_body.to_s)
+        # raise_for_status only returns on 2xx; if we get here the generated
+        # layer raised on a 2xx (shouldn't happen) so re-raise the original.
+        raise
+      end
+
+      def generated_api_error?(err)
+        klass_name = err.class.name.to_s
+        klass_name.start_with?("SmplkitGeneratedClient::") && klass_name.end_with?("::ApiError")
+      end
+    end
+
+    # Walk a generated paginated list endpoint to completion.
+    #
+    # The block receives a per-page +opts+ hash with +page_number+ and
+    # +page_size+ filled in, calls the generated list method through
+    # {ErrorMapping.call}, and returns the response object. Pages stop when the
+    # server returns fewer rows than requested — the platform's standard
+    # last-page signal across every offset-paginated list endpoint. Returns the
+    # concatenated +response.data+ rows.
+    module PaginatedFetch
+      module_function
+
+      def collect(page_size: RUNTIME_PAGE_SIZE)
+        rows = []
+        page_number = 1
+        loop do
+          opts = { page_number: page_number, page_size: page_size }
+          response = ErrorMapping.call { yield(opts) }
+          page = response.data || []
+          rows.concat(page)
+          break if page.length < page_size
+
+          page_number += 1
+        end
+        rows
+      end
+    end
+
+    # Deep-stringify Hash keys so resources returned by generated +to_hash+
+    # (symbol-keyed) match what the wrapper helpers expect (string-keyed).
+    module ResourceShim
+      module_function
+
+      def stringify(value)
+        Smplkit::Helpers.deep_stringify_keys(value)
+      end
+
+      # Convenience: produce a string-keyed Hash from a generated model.
+      def from_model(model)
+        return {} if model.nil?
+
+        stringify(model.to_hash)
+      end
+    end
+  end
+end

data/lib/smplkit/audit/client.rb

@@ -2,18 +2,16 @@
 
 module Smplkit
   module Audit
-    # Audit-product entry point — accessed via +client.audit+.
+    # The Smpl Audit client — accessed via +client.audit+.
     #
-    # Owns event recording and read-side queries: fire-and-forget
-    # +#events.record+, plus the audit-log +list+ / +get+ and the
-    # distinct-value listings (+resource_types+, +event_types+,
-    # +categories+) that back the Activity tab filter dropdowns.
-    # ADR-047 §2.7.
-    #
-    # SIEM forwarder CRUD lives on {Smplkit::ManagementClient} under
-    # +mgmt.audit.forwarders.*+.
+    # One client exposes the full surface — there is no runtime/management
+    # split for audit. Owns event recording and read-side queries:
+    # fire-and-forget +#events.record+, plus the audit-log +list+ / +get+ and
+    # the distinct-value listings (+resource_types+, +event_types+,
+    # +categories+) that back the Activity tab filter dropdowns, plus SIEM
+    # forwarder CRUD on +#forwarders+. ADR-047 §2.7.
     class AuditClient
-      attr_reader :events, :resource_types, :event_types, :categories
+      attr_reader :events, :resource_types, :event_types, :categories, :forwarders
 
       SDK_OWNED_HEADERS = %w[authorization content-type user-agent].freeze
 
@@ -41,6 +39,7 @@ module Smplkit
         @resource_types = ResourceTypes.new(SmplkitGeneratedClient::Audit::ResourceTypesApi.new(api_client))
         @event_types = EventTypes.new(SmplkitGeneratedClient::Audit::EventTypesApi.new(api_client))
         @categories = Categories.new(SmplkitGeneratedClient::Audit::CategoriesApi.new(api_client))
+        @forwarders = ForwardersClient.new(SmplkitGeneratedClient::Audit::ForwardersApi.new(api_client))
       end
 
       def _close

data/lib/smplkit/{management/audit.rb → audit/forwarders.rb}

@@ -1,40 +1,37 @@
 # frozen_string_literal: true
 
+# SIEM forwarder CRUD for the Smpl Audit client.
+#
+# Forwarders are part of the single unified audit surface — there is no
+# runtime/management split for audit (see +Smplkit::Audit::AuditClient+). This
+# file holds the forwarder CRUD sub-client that the unified +AuditClient+
+# exposes as +.forwarders+:
+#
+# * +ForwardersClient+ — +forwarders.new/get/list/save/delete+
+#
+# The forwarder model classes (+Forwarder+, +ForwarderEnvironment+, …) live in
+# +lib/smplkit/audit/models.rb+.
 module Smplkit
-  module Management
-    # Audit management surface — accessed via +mgmt.audit.forwarders+.
+  module Audit
+    # Surface for +client.audit.forwarders.*+ — manage the customer's
+    # configured SIEM forwarders.
     #
-    # Counterpart to the runtime {Smplkit::Audit::AuditClient}. The
-    # runtime client owns event recording and read-side queries; this
-    # surface owns SIEM forwarder CRUD. ADR-047 §2.7.
-    class AuditNamespace
-      # @return [ForwardersNamespace] CRUD surface for +mgmt.audit.forwarders+.
-      attr_reader :forwarders
-
-      def initialize(api_client)
-        @forwarders = ForwardersNamespace.new(
-          SmplkitGeneratedClient::Audit::ForwardersApi.new(api_client)
-        )
-      end
-    end
-
-    # +mgmt.audit.forwarders.*+ — manage the customer's configured SIEM
-    # forwarders.
-    #
-    # The active-record entry point is {#new_forwarder}: instantiate a
-    # draft, mutate fields, then call {Smplkit::Audit::Forwarder#save}.
-    # The namespace exposes {#list}, {#get}, and {#delete} directly; the
-    # +_create_forwarder+ / +_update_forwarder+ helpers are private and
-    # invoked by {Smplkit::Audit::Forwarder#save}.
-    class ForwardersNamespace
+    # The active-record entry point is {#new}: instantiate a draft, mutate
+    # fields, then call {Smplkit::Audit::Forwarder#save}. The client exposes
+    # {#list}, {#get}, and {#delete} directly; the +_create_forwarder+ /
+    # +_update_forwarder+ helpers are invoked by {Smplkit::Audit::Forwarder#save}.
+    class ForwardersClient
       def initialize(api)
         @api = api
       end
 
-      # Construct an unsaved {Smplkit::Audit::Forwarder} bound to this
-      # namespace. Call +#save+ on the returned instance to persist.
+      # Construct an unsaved {Smplkit::Audit::Forwarder} bound to this client.
+      # Call +#save+ on the returned instance to persist.
       #
-      # @param name [String] Display name.
+      # @param id [String] Caller-supplied unique identifier (the forwarder's
+      #   key). Unique within the account; immutable. The audit service returns
+      #   409 if another live forwarder already uses this id.
+      # @param name [String] Display name. Defaults to +id+ when not supplied.
       # @param forwarder_type [String] One of {Smplkit::Audit::ForwarderType::VALUES}.
       # @param configuration [Smplkit::Audit::HttpConfiguration] Destination
       #   request configuration. Headers carry credentials and are encrypted at
@@ -56,11 +53,9 @@ module Smplkit
       # @param filter [Hash, nil] Optional JSON Logic filter; events that don't
       #   match are recorded as +filtered_out+ deliveries.
       # @param transform [Object, nil] Optional template applied to each event
-      #   before delivery. Free-form by default — the audit service passes the
-      #   value verbatim to the engine named by +transform_type+. Must be paired
-      #   with a non-nil +transform_type+; when +transform_type+ is
-      #   +TransformType::JSONATA+, +transform+ must be a +String+ (the JSONata
-      #   expression).
+      #   before delivery. Must be paired with a non-nil +transform_type+; when
+      #   +transform_type+ is +TransformType::JSONATA+, +transform+ must be a
+      #   +String+ (the JSONata expression).
       # @param transform_type [String, nil] Engine that evaluates +transform+ —
       #   one of {Smplkit::Audit::TransformType::VALUES}. Must be paired with a
       #   non-nil +transform+.
@@ -68,12 +63,12 @@ module Smplkit
       #   nil or both set, or when +transform_type+ is +JSONATA+ and +transform+
       #   is not a +String+.
       # @return [Smplkit::Audit::Forwarder]
-      def new_forwarder(id, forwarder_type:, configuration:, name: nil,
-                        environments: nil, description: nil,
-                        forward_smplkit_events: false,
-                        filter: nil, transform: nil, transform_type: nil)
-        Smplkit::Audit::Forwarder.send(:validate_transform_pair!, transform, transform_type)
-        Smplkit::Audit::Forwarder.new(
+      def new(id, forwarder_type:, configuration:, name: nil,
+              environments: nil, description: nil,
+              forward_smplkit_events: false,
+              filter: nil, transform: nil, transform_type: nil)
+        Forwarder.send(:validate_transform_pair!, transform, transform_type)
+        Forwarder.new(
           self,
           id: id,
           name: name || id,
@@ -91,33 +86,31 @@ module Smplkit
       # List forwarders for the authenticated account.
       #
       # Offset paginated per ADR-014: pass +page_number+ (1-based) and
-      # +page_size+ (default 1000, max 1000). Pass +meta_total: true+ to
-      # populate +total+ and +total_pages+ in the returned +pagination+
-      # block (costs an extra COUNT query server-side).
+      # +page_size+ (default 1000, max 1000). Pass +meta_total: true+ to populate
+      # +total+ and +total_pages+ in the returned +pagination+ block (costs an
+      # extra COUNT query server-side).
       #
       # @return [ForwarderListPage]
       def list(forwarder_type: nil, page_number: nil, page_size: nil, meta_total: nil)
         opts = {}
-        opts[:filter_forwarder_type] = Smplkit::Audit::ForwarderType.coerce(forwarder_type) if forwarder_type
+        opts[:filter_forwarder_type] = ForwarderType.coerce(forwarder_type) if forwarder_type
         opts[:page_number] = page_number if page_number
         opts[:page_size] = page_size if page_size
         opts[:meta_total] = meta_total unless meta_total.nil?
 
-        resp = Smplkit::Audit.call_api { @api.list_forwarders(opts) }
-        forwarders = (resp.data || []).map do |r|
-          Smplkit::Audit::Forwarder.from_resource(r, client: self)
-        end
-        ForwarderListPage.new(forwarders, Smplkit::Audit.extract_pagination(resp.meta))
+        resp = Audit.call_api { @api.list_forwarders(opts) }
+        forwarders = (resp.data || []).map { |r| Forwarder.from_resource(r, client: self) }
+        ForwarderListPage.new(forwarders, Audit.extract_pagination(resp.meta))
       end
 
-      # Fetch a single forwarder by id. The returned instance is bound to
-      # this namespace, so +forwarder.save+ and +forwarder.delete+ work.
+      # Fetch a single forwarder by id. The returned instance is bound to this
+      # client, so +forwarder.save+ and +forwarder.delete+ work.
       #
       # @param forwarder_id [String]
       # @return [Smplkit::Audit::Forwarder]
       def get(forwarder_id)
-        resp = Smplkit::Audit.call_api { @api.get_forwarder(forwarder_id) }
-        Smplkit::Audit::Forwarder.from_resource(resp.data, client: self)
+        resp = Audit.call_api { @api.get_forwarder(forwarder_id) }
+        Forwarder.from_resource(resp.data, client: self)
       end
 
       # Soft-delete a forwarder.
@@ -125,7 +118,7 @@ module Smplkit
       # @param forwarder_id [String]
       # @return [nil]
       def delete(forwarder_id)
-        Smplkit::Audit.call_api { @api.delete_forwarder(forwarder_id) }
+        Audit.call_api { @api.delete_forwarder(forwarder_id) }
         nil
       end
 
@@ -136,22 +129,21 @@ module Smplkit
           raise ArgumentError, "Forwarder.id is required on create (caller-supplied key)"
         end
 
-        resp = Smplkit::Audit.call_api { @api.create_forwarder(build_create_body(forwarder)) }
-        Smplkit::Audit::Forwarder.from_resource(resp.data, client: self)
+        resp = Audit.call_api { @api.create_forwarder(build_create_body(forwarder)) }
+        Forwarder.from_resource(resp.data, client: self)
       end
 
-      # @api private — Full-replace PUT for an existing forwarder. Called
-      #   by {Smplkit::Audit::Forwarder#save} on instances with +created_at+.
+      # @api private — Full-replace PUT for an existing forwarder. Called by
+      #   {Smplkit::Audit::Forwarder#save} on instances with +created_at+.
       #
-      # Header values must be re-supplied as plaintext; the GET path
-      # redacts them, so a PUT body containing +"<redacted>"+ would
-      # persist that literal. Track real header values client-side and
-      # round-trip them.
+      # Header values must be re-supplied as plaintext; the GET path redacts
+      # them, so a PUT body containing +"<redacted>"+ would persist that literal.
+      # Track real header values client-side and round-trip them.
       def _update_forwarder(forwarder)
         raise ArgumentError, "cannot update a Forwarder with no id" if forwarder.id.nil?
 
-        resp = Smplkit::Audit.call_api { @api.update_forwarder(forwarder.id, build_body(forwarder)) }
-        Smplkit::Audit::Forwarder.from_resource(resp.data, client: self)
+        resp = Audit.call_api { @api.update_forwarder(forwarder.id, build_body(forwarder)) }
+        Forwarder.from_resource(resp.data, client: self)
       end
 
       private
@@ -160,16 +152,15 @@ module Smplkit
       #
       # Accepts either {Smplkit::Audit::ForwarderEnvironment} values or plain
       # hashes (+{ enabled: true, configuration: HttpConfiguration.new(...) }+)
-      # so callers can use the lightweight hash form without importing the
-      # model.
+      # so callers can use the lightweight hash form without importing the model.
       def normalize_environments(environments)
         return {} if environments.nil? || environments.empty?
 
         environments.each_with_object({}) do |(env_key, value), out|
-          out[env_key.to_s] = if value.is_a?(Smplkit::Audit::ForwarderEnvironment)
+          out[env_key.to_s] = if value.is_a?(ForwarderEnvironment)
                                 value
                               else
-                                Smplkit::Audit::ForwarderEnvironment.new(
+                                ForwarderEnvironment.new(
                                   enabled: value[:enabled] || value["enabled"] || false,
                                   configuration: value[:configuration] || value["configuration"]
                                 )
@@ -186,7 +177,7 @@ module Smplkit
         (environments || {}).each_with_object({}) do |(env_key, env), out|
           out[env_key.to_s] = SmplkitGeneratedClient::Audit::ForwarderEnvironment.new(
             enabled: env.enabled,
-            configuration: env.configuration.nil? ? nil : Smplkit::Audit::HttpConfiguration.to_wire(env.configuration)
+            configuration: env.configuration.nil? ? nil : HttpConfiguration.to_wire(env.configuration)
           )
         end
       end
@@ -197,20 +188,20 @@ module Smplkit
         SmplkitGeneratedClient::Audit::Forwarder.new(
           name: forwarder.name,
           description: forwarder.description,
-          forwarder_type: Smplkit::Audit::ForwarderType.coerce(forwarder.forwarder_type),
+          forwarder_type: ForwarderType.coerce(forwarder.forwarder_type),
           forward_smplkit_events: forwarder.forward_smplkit_events,
           environments: environments_to_wire(forwarder.environments),
           filter: forwarder.filter,
-          transform_type: Smplkit::Audit::TransformType.coerce(forwarder.transform_type),
+          transform_type: TransformType.coerce(forwarder.transform_type),
           transform: forwarder.transform,
-          configuration: Smplkit::Audit::HttpConfiguration.to_wire(forwarder.configuration)
+          configuration: HttpConfiguration.to_wire(forwarder.configuration)
         )
       end
 
       def build_create_body(forwarder)
-        # Create uses the distinct ForwarderCreateRequest envelope; the
-        # audit service requires data.id (the customer-supplied key) on
-        # create and 409s on conflict.
+        # Create uses the distinct ForwarderCreateRequest envelope; the audit
+        # service requires data.id (the customer-supplied key) on create and
+        # 409s on conflict.
         resource = SmplkitGeneratedClient::Audit::ForwarderCreateResource.new(
           id: forwarder.id.to_s,
           type: "forwarder",
@@ -230,13 +221,19 @@ module Smplkit
       end
     end
 
-    # A single page returned from {ForwardersNamespace#list}.
+    # A single page returned from {ForwardersClient#list}.
     #
     # @!attribute [rw] forwarders
     #   @return [Array<Smplkit::Audit::Forwarder>] Forwarders in this page.
     # @!attribute [rw] pagination
     #   @return [Hash] +meta.pagination+ block (+:page+, +:size+, and — only when
     #     the caller passed +meta_total: true+ — +:total+ / +:total_pages+).
-    ForwarderListPage = Struct.new(:forwarders, :pagination)
+    ForwarderListPage = Struct.new(:forwarders, :pagination) do
+      include Enumerable
+
+      def each(&) = forwarders.each(&)
+      def length = forwarders.length
+      alias_method :size, :length
+    end
   end
 end

data/lib/smplkit/audit/models.rb

@@ -422,7 +422,7 @@ module Smplkit
     # A SIEM streaming forwarder configured on the customer's account.
     #
     # Active-record style: instantiate via
-    # +mgmt.audit.forwarders.new_forwarder(...)+, mutate fields directly,
+    # +client.audit.forwarders.new(...)+, mutate fields directly,
     # and call {#save} to persist or {#delete} to remove. Header values in
     # +configuration.headers+ are returned redacted on reads — the GET path
     # on the audit API replaces every header value with +"<redacted>"+.
@@ -558,6 +558,45 @@ module Smplkit
       end
       alias delete! delete
 
+      # Set this forwarder's destination configuration in memory.
+      #
+      # With +environment+ omitted, replaces the base {#configuration}. With
+      # +environment+ given, sets the per-environment override's configuration
+      # on {#environments}, creating the override entry if it doesn't exist yet
+      # (preserving any already-set +enabled+ on it). Call {#save} to persist.
+      def set_configuration(configuration, environment: nil)
+        if environment.nil?
+          @configuration = configuration
+        else
+          _environment_override(environment).configuration = configuration
+        end
+      end
+
+      # Set this forwarder's enablement in memory.
+      #
+      # With +environment+ omitted, sets the base {#enabled} (which the server
+      # pins false regardless — enablement is per-environment). With
+      # +environment+ given, sets the per-environment override's +enabled+ on
+      # {#environments}, creating the override entry if it doesn't exist yet
+      # (preserving any already-set +configuration+ on it). Call {#save} to
+      # persist.
+      def set_enabled(enabled, environment: nil)
+        if environment.nil?
+          @enabled = enabled
+        else
+          _environment_override(environment).enabled = enabled
+        end
+      end
+
+      # Return the override for +environment+, creating an empty one if absent.
+      #
+      # The per-environment mutators reach through here so an existing
+      # override's other field is preserved when only one of +enabled+ /
+      # +configuration+ is being set.
+      def _environment_override(environment)
+        @environments[environment] ||= ForwarderEnvironment.new
+      end
+
       # @api private
       def _apply(other)
         @id = other.id