smplkit 3.0.19 → 3.0.20

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8dc0e8067c66c43e659ad29aff4756448763e90c251e300d598762a7aad1130b
-  data.tar.gz: 0a658e3773fcb670b7891c6fc5b18ffeea16780a3195c8e0aa866132e2018fe9
+  metadata.gz: 4fd326702343cd2c8f212f2964214c6c5b12eaf3d38747207a3aa26642b68af8
+  data.tar.gz: 1a298755b3fb4d87ec58d09664720ea078595bd77ce11cd7bef20184b4e20f0a
 SHA512:
-  metadata.gz: 6f1ef7cc9470990ee57fbe8587fff5f4a0ac5f9ab2199186b4f585fbe8dfc8dc9efd74acc8787f3c4a3fab4b9acc4c2860118e6f5b91c4934f8684d0c8d88f7f
-  data.tar.gz: 9c8cf307db3e470c047b518aeb079b558d7c19f1687293e1103d1570104fc2c2bfde6f2591f090a94bf46cc3b438123d38e7caa7db2f7b1a923aad91b096e4c5
+  metadata.gz: fffd9940159bb8e141024235be5a3c0d9992a7ee23cc1bc454e1baca7d286bc19be8ee7114bd36fbff599f9ea05ed71853891fff43a98dcf97c94c7bc9065b3c
+  data.tar.gz: 500a7b954f794cd50c59e4d56e4354e9e5908f8f9e27a09c662d64c74aa64f90a9f1c3d8962314c8d312a5c1d80947db823eab2f859b0d87025caee78a3bddce

data/lib/smplkit/audit/models.rb

@@ -2,10 +2,6 @@
 
 module Smplkit
   module Audit
-    # Parse the +page[after]+ cursor out of a JSON:API +links.next+
-    # 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.
     # Wrap a generated-audit-API call and translate +ApiError+ into the
     # +Smplkit::Error+ hierarchy. Connection-level failures (no
     # response code) become {Smplkit::ConnectionError}; status-coded
@@ -24,6 +20,10 @@ module Smplkit
       raise
     end
 
+    # Parse the +page[after]+ cursor out of a JSON:API +links.next+
+    # 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.
     def self.next_cursor(link)
       return nil unless link.is_a?(String)
 
@@ -49,23 +49,28 @@ module Smplkit
       out
     end
 
-    # Public-facing enum for SIEM streaming destination types.
+    # Supported SIEM forwarder destination types (ADR-047 §2.12).
     #
-    # Mirrors the +ForwarderType+ enum the audit OpenAPI spec emits
-    # (ADR-047 §2.12). Customers pass these constants — or any string
-    # in {VALUES} — to the management +forwarders+ surface. The wrapper
-    # validates membership before round-tripping to the wire.
+    # 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.
     module ForwarderType
-      HTTP = "HTTP"
       DATADOG = "DATADOG"
+      ELASTIC = "ELASTIC"
+      HONEYCOMB = "HONEYCOMB"
+      HTTP = "HTTP"
+      NEW_RELIC = "NEW_RELIC"
       SPLUNK_HEC = "SPLUNK_HEC"
       SUMO_LOGIC = "SUMO_LOGIC"
-      NEW_RELIC = "NEW_RELIC"
-      HONEYCOMB = "HONEYCOMB"
-      ELASTIC = "ELASTIC"
 
-      VALUES = [HTTP, DATADOG, SPLUNK_HEC, SUMO_LOGIC, NEW_RELIC, HONEYCOMB, ELASTIC].freeze
+      VALUES = [DATADOG, ELASTIC, HONEYCOMB, HTTP, NEW_RELIC, SPLUNK_HEC, SUMO_LOGIC].freeze
 
+      # Validate and normalize an input to a wire-format string.
+      #
+      # @param value [String, nil] a published constant or its literal string.
+      # @return [String, nil] the canonical wire value (or +nil+ when input is +nil+).
+      # @raise [ArgumentError] when +value+ is not a member of {VALUES}.
       def self.coerce(value)
         return nil if value.nil?
 
@@ -77,7 +82,64 @@ module Smplkit
       end
     end
 
-    # Public-facing audit event resource. ADR-047 §2.3.1.
+    # HTTP verb used by a forwarder's outbound delivery (ADR-047 §2.12).
+    #
+    # Mirrors the audit spec's +HttpConfigurationMethod+ enum so the
+    # +HttpConfiguration#method+ field is constrained to a known value
+    # instead of accepting any string. Members are declared in
+    # alphabetical order.
+    module HttpMethod
+      DELETE = "DELETE"
+      GET = "GET"
+      PATCH = "PATCH"
+      POST = "POST"
+      PUT = "PUT"
+
+      VALUES = [DELETE, GET, PATCH, POST, PUT].freeze
+
+      # Validate and normalize an input to a wire-format string.
+      #
+      # @param value [String, nil] a published constant or its literal string.
+      # @return [String, nil] the canonical wire value (or +nil+ when input is +nil+).
+      # @raise [ArgumentError] when +value+ is not a member of {VALUES}.
+      def self.coerce(value)
+        return nil if value.nil?
+
+        s = value.to_s
+        return s if VALUES.include?(s)
+
+        raise ArgumentError,
+              "Unknown HttpMethod #{value.inspect}; expected one of #{VALUES.inspect}"
+      end
+    end
+
+    # A single audit event as returned by the audit service (ADR-047 §2.3.1).
+    #
+    # @!attribute [rw] id
+    #   @return [String] Server-assigned UUID for this event.
+    # @!attribute [rw] action
+    #   @return [String] Action slug — e.g. +"user.created"+, +"invoice.paid"+.
+    # @!attribute [rw] resource_type
+    #   @return [String] Type of resource the action operated on — e.g. +"invoice"+.
+    # @!attribute [rw] resource_id
+    #   @return [String] Customer-facing id of the resource the action operated on.
+    # @!attribute [rw] occurred_at
+    #   @return [String] ISO-8601 timestamp of when the action happened, as reported by the source.
+    # @!attribute [rw] created_at
+    #   @return [String] ISO-8601 timestamp of when the audit service first ingested this event.
+    # @!attribute [rw] actor_type
+    #   @return [String, nil] Type of actor (+"user"+, +"api_key"+, +"system"+, …) — +nil+ when unknown.
+    # @!attribute [rw] actor_id
+    #   @return [String, nil] UUID of the actor when the actor is a tracked entity (user, api_key);
+    #     +nil+ for system or anonymous events.
+    # @!attribute [rw] actor_label
+    #   @return [String, nil] Display label for the actor — typically a name or email.
+    # @!attribute [rw] data
+    #   @return [Hash{String => Object}] Free-form per-event payload defined by the customer.
+    # @!attribute [rw] idempotency_key
+    #   @return [String, nil] Customer-supplied dedupe key, +nil+ if not provided.
+    # @!attribute [rw] do_not_forward
+    #   @return [Boolean] When +true+, skip SIEM forwarder delivery regardless of any matching filter.
     AuditEvent = Struct.new(
       :id, :action, :resource_type, :resource_id,
       :occurred_at, :created_at,
@@ -110,6 +172,13 @@ module Smplkit
     # 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.
+    #
+    # @!attribute [rw] id
+    #   @return [String] JSON:API resource id (same as +resource_type+).
+    # @!attribute [rw] resource_type
+    #   @return [String] The distinct resource_type slug.
+    # @!attribute [rw] created_at
+    #   @return [String] ISO-8601 timestamp of the earliest sighting for this slug.
     ResourceType = Struct.new(:id, :resource_type, :created_at, keyword_init: true) do
       def self.from_resource(resource)
         attrs = resource.attributes
@@ -127,6 +196,13 @@ module Smplkit
     # +created_at+ is the earliest sighting; when the parent list call
     # filtered by +resource_type+, this is the first sighting of that
     # specific (action, resource_type) triple, not the action overall.
+    #
+    # @!attribute [rw] id
+    #   @return [String] JSON:API resource id (same as +action+).
+    # @!attribute [rw] action
+    #   @return [String] The distinct action slug.
+    # @!attribute [rw] created_at
+    #   @return [String] ISO-8601 timestamp of the earliest sighting for this slug.
     Action = Struct.new(:id, :action, :created_at, keyword_init: true) do
       def self.from_resource(resource)
         attrs = resource.attributes
@@ -138,19 +214,41 @@ module Smplkit
       end
     end
 
+    # A single name/value HTTP header on a forwarder destination.
+    #
+    # @!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>"+.
     HttpHeader = Struct.new(:name, :value, keyword_init: true)
 
+    # Forwarder destination HTTP request shape.
+    #
+    # @!attribute [rw] method
+    #   @return [String] HTTP verb used for delivery. Defaults to {HttpMethod::POST}.
+    # @!attribute [rw] url
+    #   @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.
+    # @!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"+).
+    #     Defaults to +"2xx"+.
+    #
     # rubocop:disable Lint/StructNewOverride -- ``:method`` matches the
     # API attribute and shadowing Struct#method is the expected ergonomics.
     HttpConfiguration = Struct.new(:method, :url, :headers, :success_status, keyword_init: true) do
-      def initialize(method: "POST", url: "", headers: nil, success_status: "2xx")
-        super(method: method, url: url, headers: headers || [], success_status: success_status)
+      def initialize(method: HttpMethod::POST, url: "", headers: nil, success_status: "2xx")
+        super(method: HttpMethod.coerce(method), url: url, headers: headers || [], success_status: success_status)
       end
 
       def self.to_wire(src)
         h = src.is_a?(Hash) ? new(**src) : src
         SmplkitGeneratedClient::Audit::HttpConfiguration.new(
-          method: h.method,
+          method: HttpMethod.coerce(h.method),
           url: h.url,
           headers: (h.headers || []).map do |hdr|
             name, value = if hdr.is_a?(Hash)
@@ -169,7 +267,7 @@ module Smplkit
         return new if src.nil?
 
         new(
-          method: src.method || "POST",
+          method: src.method || HttpMethod::POST,
           url: src.url || "",
           headers: (src.headers || []).map { |h| HttpHeader.new(name: h.name, value: h.value) },
           success_status: src.success_status || "2xx"
@@ -178,17 +276,130 @@ module Smplkit
     end
     # rubocop:enable Lint/StructNewOverride
 
-    # rubocop:disable Lint/StructNewOverride -- ``:filter`` matches the
-    # API attribute and shadowing Struct#filter is the expected ergonomics.
-    Forwarder = Struct.new(
-      :id, :name, :description, :forwarder_type, :enabled,
-      :filter, :transform_type, :transform, :configuration,
-      :created_at, :updated_at, :deleted_at, :version,
-      keyword_init: true
-    ) do
-      def self.from_resource(resource)
+    # A SIEM streaming forwarder configured on the customer's account.
+    #
+    # Active-record style: instantiate via
+    # +mgmt.audit.forwarders.new_forwarder(...)+, 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.
+    class Forwarder
+      # @return [String, nil] Server-assigned UUID, +nil+ until {#save} has run.
+      attr_accessor :id
+
+      # @return [String] Display name. Free-form.
+      attr_accessor :name
+
+      # @return [String] One of {ForwarderType::VALUES}.
+      attr_accessor :forwarder_type
+
+      # @return [Boolean] When +false+, the audit service skips delivery for
+      #   this forwarder but still records +filtered_out+ deliveries.
+      attr_accessor :enabled
+
+      # @return [HttpConfiguration] Destination request configuration.
+      attr_accessor :configuration
+
+      # @return [String, nil] Optional free-text description.
+      attr_accessor :description
+
+      # @return [Hash, nil] Optional JSON Logic expression evaluated per event.
+      #   When set, events that don't match are recorded as +filtered_out+
+      #   deliveries instead of being delivered to the destination.
+      attr_accessor :filter
+
+      # @return [String, nil] Optional template applied to each event before
+      #   delivery. Shape depends on {#transform_type}; for +"JSONATA"+, a
+      #   JSONata expression. +nil+ delivers the event JSON as-is.
+      attr_accessor :transform
+
+      # @return [String, nil] Engine that evaluates {#transform}. Currently
+      #   only +"JSONATA"+ is supported.
+      attr_accessor :transform_type
+
+      # @return [String, nil] ISO-8601 timestamp of first persist. +nil+ for an unsaved instance.
+      attr_accessor :created_at
+
+      # @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.
+      attr_accessor :deleted_at
+
+      # @return [Integer, nil] Monotonic version counter, bumped on every server-side write.
+      attr_accessor :version
+
+      def initialize(client = nil, name:, forwarder_type:, configuration:,
+                     id: nil, enabled: true, description: nil,
+                     filter: nil, transform: nil, transform_type: nil,
+                     created_at: nil, updated_at: nil, deleted_at: nil, version: nil)
+        @client = client
+        @id = id
+        @name = name
+        @forwarder_type = ForwarderType.coerce(forwarder_type)
+        @configuration = configuration
+        @enabled = enabled
+        @description = description
+        @filter = filter
+        @transform = transform
+        @transform_type = transform_type
+        @created_at = created_at
+        @updated_at = updated_at
+        @deleted_at = deleted_at
+        @version = version
+      end
+
+      # Create or update this forwarder on the server.
+      #
+      # Upsert behavior is driven by {#created_at}: a forwarder with no
+      # +created_at+ is created (POST); otherwise it's full-replace updated
+      # (PUT). After the call, every field is refreshed from the server
+      # response (including newly-assigned +id+, +created_at+, +updated_at+,
+      # +version+).
+      #
+      # @return [self]
+      def save
+        raise "Forwarder was constructed without a client; cannot save" if @client.nil?
+
+        updated = @created_at.nil? ? @client._create_forwarder(self) : @client._update_forwarder(self)
+        _apply(updated)
+        self
+      end
+      alias save! save
+
+      # Soft-delete this forwarder on the server.
+      #
+      # @return [nil]
+      def delete
+        raise "Forwarder was constructed without a client or id; cannot delete" if @client.nil? || @id.nil?
+
+        @client.delete(@id)
+      end
+      alias delete! delete
+
+      # @api private
+      def _apply(other)
+        @id = other.id
+        @name = other.name
+        @forwarder_type = other.forwarder_type
+        @configuration = other.configuration
+        @enabled = other.enabled
+        @description = other.description
+        @filter = other.filter
+        @transform = other.transform
+        @transform_type = other.transform_type
+        @created_at = other.created_at
+        @updated_at = other.updated_at
+        @deleted_at = other.deleted_at
+        @version = other.version
+      end
+
+      def self.from_resource(resource, client: nil)
         a = resource.attributes
         new(
+          client,
           id: resource.id,
           name: a.name,
           description: a.description,
@@ -205,6 +416,5 @@ module Smplkit
         )
       end
     end
-    # rubocop:enable Lint/StructNewOverride
   end
 end

data/lib/smplkit/config/models.rb

@@ -4,12 +4,12 @@ module Smplkit
   module Config
     # Type of a +ConfigItem+ value.
     module ItemType
-      STRING = "STRING"
-      NUMBER = "NUMBER"
       BOOLEAN = "BOOLEAN"
       JSON = "JSON"
+      NUMBER = "NUMBER"
+      STRING = "STRING"
 
-      ALL = [STRING, NUMBER, BOOLEAN, JSON].freeze
+      ALL = [BOOLEAN, JSON, NUMBER, STRING].freeze
     end
 
     # A single typed item in a +Config+.

data/lib/smplkit/flags/types.rb

@@ -7,16 +7,16 @@ module Smplkit
   # can validate calls. Raw strings are still accepted for backward
   # compatibility.
   module Op
+    CONTAINS = "contains"
     EQ = "=="
-    NEQ = "!="
-    LT = "<"
-    LTE = "<="
     GT = ">"
     GTE = ">="
     IN = "in"
-    CONTAINS = "contains"
+    LT = "<"
+    LTE = "<="
+    NEQ = "!="
 
-    ALL = [EQ, NEQ, LT, LTE, GT, GTE, IN, CONTAINS].freeze
+    ALL = [CONTAINS, EQ, GT, GTE, IN, LT, LTE, NEQ].freeze
   end
 
   # A typed entity referenced by targeting rules and registered with smplkit.

data/lib/smplkit/log_level.rb

@@ -4,11 +4,17 @@ module Smplkit
   # Log severity levels used by the Smpl Logging service.
   #
   # Acts as a string-valued enum: each constant equals its name when used in
-  # string contexts, and supports comparison via the +ordinal+.
+  # string contexts, and supports comparison via the +ordinal+. Members are
+  # declared in alphabetical order; severity is encoded in {#ordinal}, not
+  # in declaration order.
   class LogLevel
-    NAMES = %w[TRACE DEBUG INFO WARN ERROR FATAL SILENT].freeze
+    NAMES = %w[DEBUG ERROR FATAL INFO SILENT TRACE WARN].freeze
 
-    attr_reader :name, :ordinal
+    # @return [String] Canonical level name (e.g. +"INFO"+).
+    attr_reader :name
+
+    # @return [Integer] Severity ordinal — TRACE=0 (lowest) through SILENT=6 (highest).
+    attr_reader :ordinal
 
     def initialize(name, ordinal)
       @name = name.freeze
@@ -26,15 +32,15 @@ module Smplkit
 
     include Comparable
 
-    TRACE  = new("TRACE", 0)
     DEBUG  = new("DEBUG", 1)
-    INFO   = new("INFO", 2)
-    WARN   = new("WARN", 3)
     ERROR  = new("ERROR", 4)
     FATAL  = new("FATAL", 5)
+    INFO   = new("INFO", 2)
     SILENT = new("SILENT", 6)
+    TRACE  = new("TRACE", 0)
+    WARN   = new("WARN", 3)
 
-    ALL = [TRACE, DEBUG, INFO, WARN, ERROR, FATAL, SILENT].freeze
+    ALL = [DEBUG, ERROR, FATAL, INFO, SILENT, TRACE, WARN].freeze
 
     BY_NAME = ALL.to_h { |lvl| [lvl.name, lvl] }.freeze
 

data/lib/smplkit/management/audit.rb

@@ -8,6 +8,7 @@ module Smplkit
     # 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)
@@ -19,41 +20,56 @@ module Smplkit
 
     # +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
       def initialize(api)
         @api = api
       end
 
-      # Create a forwarder.
+      # Construct an unsaved {Smplkit::Audit::Forwarder} bound to this
+      # namespace. Call +#save+ on the returned instance to persist.
       #
       # @param name [String] Display name.
-      # @param forwarder_type [String, Smplkit::Audit::ForwarderType]
-      #   One of the published {Smplkit::Audit::ForwarderType} constants
-      #   (or the equivalent string).
-      # @param configuration [Smplkit::Audit::HttpConfiguration, Hash]
-      #   Transport-specific delivery configuration. Today every
-      #   forwarder_type uses {HttpConfiguration}; the URL and header
-      #   values inside are stored encrypted server-side and round-trip
-      #   to GET in plaintext.
+      # @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.
+      # @param enabled [Boolean] Whether the forwarder is active. Defaults +true+.
       # @param description [String, nil] Optional free-text description.
-      # @param enabled [Boolean] Whether the forwarder is active.
-      # @param filter [Hash, nil] Optional JSON Logic filter; events
-      #   that don't match are recorded as +filtered_out+ deliveries.
-      # @param transform_type [String, nil] Engine that evaluates
-      #   +transform+. Set to +"JSONATA"+ whenever +transform+ is set.
-      # @param transform [String, nil] Optional template applied to the
-      #   event payload before delivery (for +JSONATA+, a JSONata
-      #   expression). Nil sends the event JSON unchanged.
-      def create(name:, forwarder_type:, configuration:, description: nil, enabled: true,
-                 filter: nil, transform_type: nil, transform: nil)
-        body = build_body(nil, name: name, forwarder_type: forwarder_type,
-                               configuration: configuration, description: description,
-                               enabled: enabled, filter: filter,
-                               transform_type: transform_type, transform: transform)
-        resp = Smplkit::Audit.call_api { @api.create_forwarder(body) }
-        Smplkit::Audit::Forwarder.from_resource(resp.data)
+      # @param filter [Hash, nil] Optional JSON Logic filter; events that don't
+      #   match are recorded as +filtered_out+ deliveries.
+      # @param transform [String, nil] Optional JSONata template applied to the
+      #   event payload before delivery. Nil sends the event JSON unchanged.
+      # @return [Smplkit::Audit::Forwarder]
+      def new_forwarder(name:, forwarder_type:, configuration:,
+                        enabled: true, description: nil,
+                        filter: nil, transform: nil)
+        Smplkit::Audit::Forwarder.new(
+          self,
+          name: name,
+          forwarder_type: forwarder_type,
+          configuration: configuration,
+          enabled: enabled,
+          description: description,
+          filter: filter,
+          transform: transform,
+          transform_type: transform.nil? ? nil : "JSONATA"
+        )
       end
 
+      # 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).
+      #
+      # @return [ForwarderListPage]
       def list(forwarder_type: nil, enabled: nil, page_number: nil, page_size: nil, meta_total: nil)
         opts = {}
         opts[:filter_forwarder_type] = Smplkit::Audit::ForwarderType.coerce(forwarder_type) if forwarder_type
@@ -63,51 +79,67 @@ module Smplkit
         opts[:meta_total] = meta_total unless meta_total.nil?
 
         resp = Smplkit::Audit.call_api { @api.list_forwarders(opts) }
-        forwarders = (resp.data || []).map { |r| Smplkit::Audit::Forwarder.from_resource(r) }
+        forwarders = (resp.data || []).map do |r|
+          Smplkit::Audit::Forwarder.from_resource(r, client: self)
+        end
         ForwarderListPage.new(forwarders, Smplkit::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.
+      #
+      # @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)
+        Smplkit::Audit::Forwarder.from_resource(resp.data, client: self)
       end
 
-      # Full-replace update. PUT semantics — every field is overwritten.
+      # Soft-delete a forwarder.
       #
-      # The URL and header values inside +configuration+ are returned in
-      # plaintext on GET, so a fetched forwarder can be round-tripped to
-      # PUT without re-entering secrets.
-      def update(forwarder_id, name:, forwarder_type:, configuration:, description: nil,
-                 enabled: true, filter: nil, transform_type: nil, transform: nil)
-        body = build_body(forwarder_id, name: name, forwarder_type: forwarder_type,
-                                        configuration: configuration, description: description,
-                                        enabled: enabled, filter: filter,
-                                        transform_type: transform_type, transform: transform)
-        resp = Smplkit::Audit.call_api { @api.update_forwarder(forwarder_id, body) }
-        Smplkit::Audit::Forwarder.from_resource(resp.data)
-      end
-
+      # @param forwarder_id [String]
+      # @return [nil]
       def delete(forwarder_id)
         Smplkit::Audit.call_api { @api.delete_forwarder(forwarder_id) }
         nil
       end
 
+      # @api private — POST a new forwarder. Called by
+      #   {Smplkit::Audit::Forwarder#save} on unsaved instances.
+      def _create_forwarder(forwarder)
+        resp = Smplkit::Audit.call_api { @api.create_forwarder(build_body(forwarder)) }
+        Smplkit::Audit::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+.
+      #
+      # 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)
+      end
+
       private
 
-      def build_body(id, name:, forwarder_type:, configuration:, description:, enabled:,
-                     filter:, transform_type:, transform:)
+      def build_body(forwarder)
         attrs = SmplkitGeneratedClient::Audit::Forwarder.new(
-          name: name,
-          description: description,
-          forwarder_type: Smplkit::Audit::ForwarderType.coerce(forwarder_type),
-          enabled: enabled,
-          filter: filter,
-          transform_type: transform_type,
-          transform: transform,
-          configuration: Smplkit::Audit::HttpConfiguration.to_wire(configuration)
+          name: forwarder.name,
+          description: forwarder.description,
+          forwarder_type: Smplkit::Audit::ForwarderType.coerce(forwarder.forwarder_type),
+          enabled: forwarder.enabled,
+          filter: forwarder.filter,
+          transform_type: forwarder.transform_type,
+          transform: forwarder.transform,
+          configuration: Smplkit::Audit::HttpConfiguration.to_wire(forwarder.configuration)
         )
         resource = SmplkitGeneratedClient::Audit::ForwarderResource.new(
-          id: id ? id.to_s : "",
+          id: forwarder.id ? forwarder.id.to_s : "",
           type: "forwarder",
           attributes: attrs
         )
@@ -115,6 +147,13 @@ module Smplkit
       end
     end
 
+    # A single page returned from {ForwardersNamespace#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)
   end
 end

data/lib/smplkit/management/types.rb

@@ -9,10 +9,10 @@ module Smplkit
     # +AD_HOC+ environments are transient targets (preview branches, individual
     # developer sandboxes) that should not appear in the standard ordering.
     module EnvironmentClassification
-      STANDARD = "STANDARD"
       AD_HOC = "AD_HOC"
+      STANDARD = "STANDARD"
 
-      ALL = [STANDARD, AD_HOC].freeze
+      ALL = [AD_HOC, STANDARD].freeze
     end
 
     HEX_RE = /\A#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})\z/

metadata

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