smplkit 3.0.95 → 3.0.97

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

@@ -1,44 +1,42 @@
 # 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
-      #   rest server-side; reads return them redacted.
+      #   request configuration. Header values often carry credentials and are
+      #   returned in plaintext on reads, so a get-mutate-put round-trip
+      #   preserves them without re-entering secrets.
       # @param environments [Hash{String => Smplkit::Audit::ForwarderEnvironment, Hash}, nil]
       #   Per-environment overrides keyed by environment key (e.g.
       #   +"production"+). A forwarder delivers in an environment only when that
@@ -56,11 +54,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 +64,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,
@@ -90,42 +86,50 @@ 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).
+      # Offset paginated: pass +page_number+ (1-based) and +page_size+
+      # (default 1000, max 1000).
       #
-      # @return [ForwarderListPage]
+      # @param forwarder_type [String, nil] Restrict the listing to forwarders of
+      #   this {Smplkit::Audit::ForwarderType}. Omit to list every type.
+      # @param page_number [Integer, nil] 1-based page index. Omit for the first
+      #   page.
+      # @param page_size [Integer, nil] Maximum number of forwarders to return in
+      #   this page (default 1000, max 1000).
+      # @param meta_total [Boolean, nil] When +true+, populate +total+ and
+      #   +total_pages+ in the returned page's +pagination+ block (costs an extra
+      #   count server-side). Omit to skip it.
+      # @return [ForwarderListPage] A page of the matching forwarders.
       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. Header values
+      # come back in plaintext, so mutating the returned forwarder and calling
+      # +save+ preserves them without re-entering secrets.
       #
-      # @param forwarder_id [String]
-      # @return [Smplkit::Audit::Forwarder]
+      # @param forwarder_id [String] The forwarder's id (key).
+      # @return [Smplkit::Audit::Forwarder] The matching forwarder, bound to this client.
+      # @raise [Smplkit::NotFoundError] If no live forwarder with that id exists.
       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.
+      # Delete a forwarder.
       #
       # @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 +140,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 come back in plaintext on the GET path, so a fetched
+      # forwarder round-trips through this full-replace PUT with its header
+      # values intact — no need to re-enter secrets.
       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 +163,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,31 +188,31 @@ 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
 
       def build_attrs(forwarder)
-        # The base ``enabled`` is server-pinned false (ADR-055); we don't send
-        # it. Enablement travels entirely through ``environments``.
+        # The base +enabled+ is server-pinned false; we don't send it.
+        # Enablement travels entirely through +environments+.
         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 +232,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

@@ -8,6 +8,8 @@ module Smplkit
     # failures route through {Smplkit::Errors.raise_for_status}, which
     # emits +PaymentRequiredError+ / +NotFoundError+ / +ConflictError+
     # / +ValidationError+ / +Error+ depending on the JSON:API body.
+    #
+    # @api private
     def self.call_api
       yield
     rescue SmplkitGeneratedClient::Audit::ApiError => e
@@ -24,6 +26,8 @@ module Smplkit
     # URL. Returns nil for non-string input or when the link carries
     # no cursor parameter; trims trailing query params at the next
     # ampersand so they don't leak into the token.
+    #
+    # @api private
     def self.next_cursor(link)
       return nil unless link.is_a?(String)
 
@@ -39,6 +43,8 @@ module Smplkit
     # Returns a hash with +:page+/+:size+ (and +:total+/+:total_pages+ when
     # the request opted into +meta[total]=true+). Always returns a hash so
     # callers don't have to nil-check before reading individual keys.
+    #
+    # @api private
     def self.extract_pagination(meta)
       pagination = meta&.pagination
       return {} if pagination.nil?
@@ -56,14 +62,16 @@ module Smplkit
     # The audit read endpoints (events list, the resource_type / event_type /
     # category discovery lists) accept an optional comma-separated
     # +filter[environment]+ of real environment keys and/or the reserved
-    # +"smplkit"+ control-plane bucket (ADR-055). The wrapper takes an
-    # array of keys for an ergonomic surface and joins it here.
+    # +"smplkit"+ control-plane bucket. The wrapper takes an array of keys for
+    # an ergonomic surface and joins it here.
     #
     # +nil+ or an empty array (or one whose entries are all blank) returns
     # +nil+ so the caller omits the query param entirely and behaves exactly
     # as before — existing callers are byte-for-byte unchanged on the wire.
     # +"smplkit"+ is passed through like any other key; it carries no special
     # handling in the SDK.
+    #
+    # @api private
     def self.join_environments(environments)
       return nil if environments.nil?
 
@@ -71,12 +79,12 @@ module Smplkit
       values.empty? ? nil : values.join(",")
     end
 
-    # Supported SIEM forwarder destination types (ADR-047 §2.12).
+    # Supported SIEM forwarder destination types.
     #
     # Members are declared in alphabetical order. Customers pass these
-    # constants — or the equivalent string — to the management
-    # +forwarders+ surface; the wrapper validates membership via {coerce}
-    # before round-tripping to the wire.
+    # constants — or the equivalent string — to the forwarders surface
+    # (+client.audit.forwarders+); the wrapper validates membership via
+    # {coerce} before round-tripping to the wire.
     module ForwarderType
       DATADOG = "datadog"
       ELASTIC = "elastic"
@@ -104,7 +112,7 @@ module Smplkit
       end
     end
 
-    # HTTP verb used by a forwarder's outbound delivery (ADR-047 §2.12).
+    # HTTP verb used by a forwarder's outbound delivery.
     #
     # Mirrors the audit spec's +HttpConfigurationMethod+ enum so the
     # +HttpConfiguration#method+ field is constrained to a known value
@@ -135,11 +143,10 @@ module Smplkit
       end
     end
 
-    # Engine that evaluates a forwarder's +transform+ template
-    # (ADR-047 §2.12). Only +JSONATA+ is supported today; the enum
-    # exists so the field is typed instead of accepting any string,
-    # and so additional engines can be added without breaking the
-    # public surface.
+    # Engine that evaluates a forwarder's +transform+ template.
+    # Only +JSONATA+ is supported today; the enum exists so the field is
+    # typed instead of accepting any string, and so additional engines
+    # can be added without breaking the public surface.
     module TransformType
       JSONATA = "JSONATA"
 
@@ -161,7 +168,7 @@ module Smplkit
       end
     end
 
-    # A single audit event as returned by the audit service (ADR-047 §2.3.1).
+    # A single audit event as returned by the audit service.
     #
     # @!attribute [rw] id
     #   @return [String] Server-assigned UUID for this event.
@@ -181,6 +188,11 @@ module Smplkit
     #   @return [String, nil] Customer-supplied free-form actor identifier — +nil+ when not provided.
     # @!attribute [rw] actor_label
     #   @return [String, nil] Customer-supplied display label for the actor — typically a name or email.
+    # @!attribute [rw] category
+    #   @return [String, nil] Free-form bucket label for the event — e.g.
+    #     +"auth"+, +"billing"+, +"config-change"+. Stored exactly as supplied;
+    #     drives the audit log's category filter and the +categories+ discovery
+    #     listing ({Smplkit::Audit::AuditClient#categories}). +nil+ when not supplied.
     # @!attribute [rw] data
     #   @return [Hash{String => Object}] Free-form per-event payload defined by the customer.
     # @!attribute [rw] idempotency_key
@@ -196,7 +208,7 @@ module Smplkit
     AuditEvent = Struct.new(
       :id, :event_type, :resource_type, :resource_id,
       :occurred_at, :created_at,
-      :actor_type, :actor_id, :actor_label,
+      :actor_type, :actor_id, :actor_label, :category,
       :data, :idempotency_key, :do_not_forward, :environment,
       keyword_init: true
     ) do
@@ -212,6 +224,7 @@ module Smplkit
           actor_type: attrs.actor_type,
           actor_id: attrs.actor_id,
           actor_label: attrs.actor_label,
+          category: attrs.category,
           data: Smplkit::Helpers.deep_stringify_keys(attrs.data || {}),
           idempotency_key: attrs.idempotency_key,
           do_not_forward: attrs.do_not_forward || false,
@@ -223,9 +236,9 @@ module Smplkit
     # A distinct +resource_type+ slug seen for the account.
     #
     # The +id+ and +resource_type+ are the same value — JSON:API surfaces
-    # the customer-facing key as the resource id (ADR-014). The duplication
-    # keeps SDK consumers from having to dig into the id field when
-    # filtering UI controls; pick whichever name reads better in context.
+    # the customer-facing key as the resource id. The duplication keeps SDK
+    # consumers from having to dig into the id field when filtering UI
+    # controls; pick whichever name reads better in context.
     #
     # @!attribute [rw] id
     #   @return [String] JSON:API resource id (same as +resource_type+).
@@ -272,8 +285,8 @@ module Smplkit
     #
     # Same shape as {ResourceType}/{EventType} — +id+ and +category+ are the
     # same value (JSON:API surfaces the customer-facing key as the resource
-    # id, ADR-014). +created_at+ is the earliest sighting of this category
-    # for the account.
+    # id). +created_at+ is the earliest sighting of this category for the
+    # account.
     #
     # @!attribute [rw] id
     #   @return [String] JSON:API resource id (same as +category+).
@@ -297,8 +310,8 @@ module Smplkit
     # @!attribute [rw] name
     #   @return [String] Header name (e.g. +"Authorization"+, +"DD-API-KEY"+).
     # @!attribute [rw] value
-    #   @return [String] Header value, plaintext on writes. The audit service
-    #     encrypts values at rest; reads return them as +"<redacted>"+.
+    #   @return [String] Header value. Returned in plaintext on reads, so a
+    #     get-mutate-put round-trip preserves it without re-entering secrets.
     HttpHeader = Struct.new(:name, :value, keyword_init: true)
 
     # Forwarder destination HTTP request shape.
@@ -309,8 +322,9 @@ module Smplkit
     #   @return [String] Destination URL the audit service sends each event to.
     # @!attribute [rw] headers
     #   @return [Array<HttpHeader>] Headers attached to every outbound request.
-    #     Values carry credentials and are encrypted at rest server-side; reads
-    #     return them redacted.
+    #     Values often carry credentials and are returned in plaintext on
+    #     reads, so a get-mutate-put round-trip preserves them without
+    #     re-entering secrets.
     # @!attribute [rw] success_status
     #   @return [String] Status the destination must return for delivery to count
     #     as success — an exact code (+"200"+, +"204"+) or a class (+"2xx"+, +"4xx"+).
@@ -401,8 +415,8 @@ module Smplkit
     #     configuration that fully replaces the forwarder's base
     #     {Forwarder#configuration} for this environment. +nil+ (the default)
     #     inherits the base configuration. As with the base configuration,
-    #     header values are plaintext on writes and returned redacted on reads —
-    #     re-supply real values before {Forwarder#save}.
+    #     header values are returned in plaintext on reads, so a get-mutate-put
+    #     round-trip preserves them without re-entering secrets.
     ForwarderEnvironment = Struct.new(:enabled, :configuration, keyword_init: true) do
       def initialize(enabled: false, configuration: nil)
         super
@@ -422,12 +436,11 @@ 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>"+.
-    # Re-supply real values before calling {#save}; the SDK does not cache
-    # them client-side.
+    # +configuration.headers+ are returned in plaintext on reads, so fetching
+    # a forwarder, mutating it, and calling {#save} preserves its header
+    # values without re-entering secrets.
     class Forwarder
       # @return [String, nil] Caller-supplied unique identifier (key) for this
       #   forwarder. Unique within an account; immutable for the lifetime of
@@ -494,7 +507,7 @@ module Smplkit
       # @return [String, nil] ISO-8601 timestamp of the most recent mutation.
       attr_accessor :updated_at
 
-      # @return [String, nil] Soft-delete timestamp. +nil+ for live forwarders.
+      # @return [String, nil] Deletion timestamp; +nil+ for live forwarders.
       attr_accessor :deleted_at
 
       # @return [Integer, nil] Monotonic version counter, bumped on every server-side write.
@@ -548,7 +561,7 @@ module Smplkit
       end
       alias save! save
 
-      # Soft-delete this forwarder on the server.
+      # Delete this forwarder on the server.
       #
       # @return [nil]
       def delete
@@ -558,6 +571,47 @@ 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.
+      #
+      # @api private
+      def _environment_override(environment)
+        @environments[environment] ||= ForwarderEnvironment.new
+      end
+
       # @api private
       def _apply(other)
         @id = other.id

data/lib/smplkit/audit/resource_types.rb

@@ -5,20 +5,32 @@ module Smplkit
     # +client.audit.resource_types.list+ — distinct +resource_type+ slugs
     # seen for the account.
     #
-    # Backed by a maintain-by-write side table (ADR-047 §2.5), so the
-    # response time is independent of how many years of events the
-    # account has accumulated. Sorted alphabetically; offset pagination
-    # (+page_number+ / +page_size+) per ADR-014.
+    # Response time is independent of how many years of events the account has
+    # accumulated. Sorted alphabetically; offset paginated.
     class ResourceTypes
       def initialize(api)
         @api = api
       end
 
-      # +environments+ is an optional array of environment keys (and/or the
-      # reserved +"smplkit"+ control-plane bucket) used to scope the read;
-      # the values are comma-joined into +filter[environment]+. Omitting it
-      # (or passing an empty array) leaves the filter unset — identical to
-      # the prior behavior on the wire.
+      # List the distinct +resource_type+ slugs seen in the account.
+      #
+      # +environments+ scopes the listing to a set of environments: pass an
+      # array of environment keys and/or the reserved +"smplkit"+ control-plane
+      # bucket; the values are comma-joined into +filter[environment]+. Omitting
+      # it (or passing an empty array) leaves the filter off entirely.
+      #
+      # @param page_number [Integer, nil] 1-based page index. Omit for the first
+      #   page.
+      # @param page_size [Integer, nil] Maximum number of slugs to return in this
+      #   page.
+      # @param meta_total [Boolean, nil] When +true+, populate +total+ and
+      #   +total_pages+ in the returned page's +pagination+ block (costs an extra
+      #   count server-side). Omit to skip it.
+      # @param environments [Array<String>, nil] Environment keys and/or the
+      #   reserved +"smplkit"+ control-plane bucket to scope the listing to. Omit
+      #   to leave the filter off entirely.
+      # @return [Smplkit::Audit::ResourceTypeListPage] A page of the matching
+      #   resource-type slugs.
       def list(page_number: nil, page_size: nil, meta_total: nil, environments: nil)
         opts = {}
         opts[:page_number] = page_number if page_number