smplkit 3.0.95 → 3.0.97

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: daa3b1ae6cdf8922badb57509c04e16d007372f82b95661de9f223602f174a2b
-  data.tar.gz: d03104fec0c8f27c9d5942821b8c49143d6321f4b9790da7be91f7a2aef55ddf
+  metadata.gz: c317a0f573d990742547e60f7e17bba0bd65a6abc13dae8bcf8ab13ca7e167e3
+  data.tar.gz: c02f2385189d409d3f1a8263156f0a659e55ae762d4c2f9940bdf6a51d61f19d
 SHA512:
-  metadata.gz: 86ef3645c6d7c44b4afd90ac2948762a3ff4d2d2df6076fb524f6f636cac2d0b0335d55e4bd3a6fac974933f65f332a2754eac9ac417d2aff91ab4b7bc57c874
-  data.tar.gz: 786ad2e7704b39d79090c51b6fc4663e6072fda4e1e3d51fb70abbb272f951a17246351a7a0600c4e56d9c696c82f486f2fda490398a9e0e4aa0e1be4c728c1e
+  metadata.gz: 33f03cf3bde2e7a38b9856b558be13546c374ceddec2c02ec9cb5d454922f373d46f39188e86ffbbba194421318b9d04bba1a966ac2930ad088c6cf46f6d7cf5
+  data.tar.gz: 91337cdc5b3da03eae931e8b67b7454d0d04925e667446b49ba003ecd0c6bcd091f319f15df58d2c926f818a563a5ab4648ef769261ffacc9422636f125dd3a6

data/lib/smplkit/account/client.rb

@@ -0,0 +1,128 @@
+# 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 config resolver fills in whatever is missing.
+    #
+    # @api private
+    def self.resolve_account_target(api_key:, base_url:, profile:, base_domain:, scheme:, debug:, extra_headers:)
+      cfg = ConfigResolution.resolve_client_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
+
+      # Fetch the authenticated account's current settings.
+      #
+      # @return [Smplkit::Account::AccountSettings] An active record. Mutate its
+      #   fields and call +save+ to persist the changes.
+      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
+
+      # @api private
+      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,71 @@
+# 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.
+      #
+      # @return [Hash] The full settings dict.
+      def raw
+        @data
+      end
+
+      # Replace the full settings dict.
+      #
+      # @param value [Hash] The new settings dict.
+      # @return [void]
+      def raw=(value)
+        @data = value.dup
+      end
+
+      # Canonical ordering of STANDARD environments. Empty list if unset.
+      #
+      # @return [Array<String>] The environment ids in canonical order.
+      def environment_order
+        Array(@data["environment_order"] || [])
+      end
+
+      # Set the canonical ordering of STANDARD environments.
+      #
+      # @param value [Array<String>] The environment ids in canonical order.
+      # @return [void]
+      def environment_order=(value)
+        @data["environment_order"] = value.to_a
+      end
+
+      # Write the full settings object back to the account.
+      #
+      # @return [AccountSettings] +self+, updated with the server response.
+      # @raise [RuntimeError] If this model was constructed without a client
+      #   (e.g. built by hand rather than returned from +get+).
+      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
+
+      # @api private
+      def _apply(other)
+        @data = other.raw.dup
+      end
+    end
+  end
+end

data/lib/smplkit/api_support.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module Smplkit
+  # Ruby-internal adapters bridging the generated client layer to the wrapper.
+  #
+  # @api private
+  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.
+    #
+    # @api private
+    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.
+    #
+    # @api private
+    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).
+    #
+    # @api private
+    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/buffer.rb

@@ -3,13 +3,15 @@
 module Smplkit
   module Audit
     # Bounded in-memory queue + worker thread for fire-and-forget audit
-    # emits (ADR-047 §2.6).
+    # emits.
     #
     # +#enqueue+ returns immediately. The worker drains on either a
     # periodic tick or once depth crosses the high-water mark, retries
     # transient failures with exponential backoff, drops permanent 4xx
     # (other than 429), and evicts the oldest item under sustained
     # back-pressure.
+    #
+    # @api private
     class EventBuffer
       MAX_BUFFER_SIZE = 1000
       WATERMARK = 50

data/lib/smplkit/audit/categories.rb

@@ -5,21 +5,32 @@ module Smplkit
     # +client.audit.categories.list+ — distinct +category+ values seen for
     # the account.
     #
-    # Backed by a maintain-by-write side table populated whenever an event
-    # is recorded with a non-null +category+ (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 Categories
       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 +category+ values 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 categories 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::CategoryListPage] A page of the matching
+      #   category values.
       def list(page_number: nil, page_size: nil, meta_total: nil, environments: nil)
         opts = {}
         opts[:page_number] = page_number if page_number

data/lib/smplkit/audit/client.rb

@@ -2,18 +2,26 @@
 
 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.
+    # One client exposes the full surface — event recording and reads,
+    # distinct-value discovery, and SIEM forwarder CRUD. Owns fire-and-forget
+    # +#events.record+, plus the audit-log +list+ / +get+ and the distinct-value
+    # listings (+resource_types+, +event_types+, +categories+), plus SIEM
+    # forwarder CRUD on +#forwarders+.
     #
-    # SIEM forwarder CRUD lives on {Smplkit::ManagementClient} under
-    # +mgmt.audit.forwarders.*+.
+    # @param api_key [String] API key used to authenticate every request.
+    # @param base_url [String] Full audit-service base URL.
+    # @param environment [String, nil] Deployment environment to scope recording
+    #   and reads to. Optional — forwarder CRUD and discovery are
+    #   environment-agnostic, and reads accept an explicit +environments: [...]+
+    #   filter.
+    # @param timeout [Float] Per-request timeout, in seconds. Defaults to +10.0+.
+    # @param extra_headers [Hash{String => String}, nil] Extra headers attached
+    #   to every request. SDK-owned headers (authorization, content-type,
+    #   user-agent) cannot be overridden.
     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 +49,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/audit/event_types.rb

@@ -7,22 +7,38 @@ module Smplkit
     #
     # Without +filter_resource_type+, returns one row per distinct
     # event type — an event type recorded with multiple resource_types appears
-    # once. With the filter, returns the event types seen with that
-    # specific resource_type, powering the cascading-filter behavior
-    # on the Activity tab.
+    # once. With the filter, returns the event types seen with that specific
+    # resource_type, which supports building a cascading resource-type-then-
+    # event-type filter.
     #
-    # ADR-047 §2.5. Sorted alphabetically; offset pagination
-    # (+page_number+ / +page_size+) per ADR-014.
+    # Sorted alphabetically; offset paginated.
     class EventTypes
       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 +event_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 filter_resource_type [String, nil] Restrict the listing to
+      #   event_types seen with this +resource_type+. Omit to list every distinct
+      #   event_type.
+      # @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::EventTypeListPage] A page of the matching
+      #   event-type slugs.
       def list(filter_resource_type: nil, page_number: nil, page_size: nil, meta_total: nil, environments: nil)
         opts = {}
         opts[:filter_resource_type] = filter_resource_type if filter_resource_type

data/lib/smplkit/audit/events.rb

@@ -4,9 +4,9 @@ module Smplkit
   module Audit
     # Audit events surface — accessed via +client.audit.events+.
     #
-    # +#record+ is fire-and-forget per ADR-047 §2.6 — the call enqueues
-    # the event onto an in-memory bounded buffer and returns
-    # immediately. +#list+ and +#get+ are synchronous reads.
+    # +#record+ is fire-and-forget — the call enqueues the event onto an
+    # in-memory bounded buffer and returns immediately. +#list+ and +#get+
+    # are synchronous reads.
     class Events
       def initialize(api)
         @api = api
@@ -15,18 +15,53 @@ module Smplkit
 
       # Enqueue an audit event for asynchronous delivery.
       #
+      # Returns immediately — the buffer's worker thread performs the actual
+      # POST with retry on transient failures.
+      #
       # Actor attribution (+actor_type+, +actor_id+, +actor_label+) is
       # customer-supplied and free-form. The audit service stores
       # whatever the caller passed and never backfills from the request
       # credential — supply the fields explicitly when you want the
       # event attributed.
       #
-      # Customer attempts to record events with +resource_type+ starting
-      # with +smpl.+ are rejected by the server with a 403 (the buffer
-      # logs and drops permanent failures).
+      # @param event_type [String] What happened (e.g. +"invoice.created"+).
+      #   Any non-empty string.
+      # @param resource_type [String] Kind of resource the event is about (e.g.
+      #   +"invoice"+). Any non-empty string. Customer events must NOT use the
+      #   +smpl.+ prefix — that namespace is reserved for smplkit-emitted events
+      #   and the server rejects customer attempts with a 403 (the buffer logs
+      #   and drops permanent failures).
+      # @param resource_id [String] Identifier of the affected resource.
+      # @param occurred_at [Time, DateTime, String, nil] When the event happened
+      #   in the originating system. Defaults to +now+ server-side if omitted.
+      # @param actor_type [String, nil] Free-form label for the kind of actor
+      #   that caused the event (e.g. +"USER"+, +"API_KEY"+, +"SYSTEM"+, or any
+      #   custom value). The audit service never backfills this from the request
+      #   credential — supply it explicitly when you want the event attributed.
+      # @param actor_id [String, nil] Free-form identifier of the actor that
+      #   caused the event. Any string scheme is accepted.
+      # @param actor_label [String, nil] Human-readable label for the actor
+      #   (e.g. an email address or API key name).
+      # @param category [String, nil] Optional free-form bucket label for the
+      #   event (e.g. +"auth"+, +"billing"+, +"config-change"+). Stored exactly
+      #   as supplied; powers the audit log's category filter and the
+      #   +categories+ discovery listing ({Smplkit::Audit::AuditClient#categories}).
+      #   Omit it to leave the event uncategorized.
+      # @param data [Hash, nil] Free-form contextual JSON. To record a resource
+      #   snapshot, place it inside +data+ — smplkit's own convention nests it at
+      #   +data["snapshot"]+ for consistency, but the shape is unconstrained.
+      # @param idempotency_key [String, nil] Optional caller-supplied idempotency
+      #   key. If omitted, the server derives one from event content (account_id
+      #   + event_type + resource_type + resource_id + occurred_at + actor_* +
+      #   data).
+      # @param do_not_forward [Boolean] When +true+, the audit service records
+      #   the event normally but does NOT POST it through any configured SIEM
+      #   forwarder. A +skipped_do_not_forward+ delivery row is recorded for each
+      #   enabled forwarder so the skip is visible in the forwarder delivery log.
+      # @return [void]
       def record(event_type:, resource_type:, resource_id:,
                  occurred_at: nil, actor_type: nil, actor_id: nil,
-                 actor_label: nil, data: nil, idempotency_key: nil,
+                 actor_label: nil, category: nil, data: nil, idempotency_key: nil,
                  do_not_forward: false)
         raise ArgumentError, "event_type is required" if event_type.nil? || event_type.to_s.empty?
         raise ArgumentError, "resource_type is required" if resource_type.nil? || resource_type.to_s.empty?
@@ -55,6 +90,7 @@ module Smplkit
           actor_type: actor_type,
           actor_id: actor_id,
           actor_label: actor_label,
+          category: category,
           data: data || {},
           do_not_forward: do_not_forward
         )
@@ -69,22 +105,55 @@ module Smplkit
 
       # Single-event retrieval.
       #
-      # Raises {Smplkit::NotFoundError} when no event with that id
-      # exists in the caller's account.
+      # @param event_id [String] The event's UUID, as a string parseable as one.
+      # @return [Smplkit::Audit::AuditEvent] The matching event.
+      # @raise [Smplkit::NotFoundError] If no event with that id exists in the
+      #   caller's account.
       def get(event_id)
         resp = Smplkit::Audit.call_api { @api.get_event(event_id) }
         AuditEvent.from_resource(resp.data)
       end
 
-      # List events with filters and cursor pagination. Returns a
-      # +Smplkit::Audit::ListEventsPage+ whose +#events+ is the page and
-      # +#next_cursor+ is the opaque token for the next page (or nil).
+      # List audit events for the authenticated account.
+      #
+      # Filters apply server-side. +actor_id+ is matched as a literal string
+      # against whatever the recording call stored. Pagination uses an opaque
+      # cursor (+page_after+); the returned page exposes +#next_cursor+ when
+      # more pages are available.
+      #
+      # +search+ is an optional free-text filter: pass a string to return only
+      # events whose +resource_id+ or +description+ contains it as a
+      # case-insensitive substring; omit it (the default) to disable text
+      # filtering. A +search+ filter must be scoped — combine it with
+      # +occurred_at_range+, or with both +resource_type+ and +resource_id+ —
+      # or the request is rejected.
       #
-      # +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.
+      # @param event_type [String, nil] Return only events with this
+      #   +event_type+. Omit to match any.
+      # @param resource_type [String, nil] Return only events about this
+      #   +resource_type+. Omit to match any.
+      # @param resource_id [String, nil] Return only events about this resource
+      #   id. Omit to match any.
+      # @param actor_type [String, nil] Return only events whose +actor_type+
+      #   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 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
+      #   events whose +resource_id+ or +description+ contains it as a
+      #   case-insensitive substring. Must be scoped (combine with
+      #   +occurred_at_range+, or with both +resource_type+ and +resource_id+)
+      #   or the request is rejected. Omit to disable text filtering.
+      # @param environments [Array<String>, nil] Environment keys (and/or the
+      #   reserved +"smplkit"+ control-plane bucket) to scope the read to. Omit
+      #   to leave the filter off entirely.
+      # @param page_size [Integer, nil] Maximum number of events to return in
+      #   this page.
+      # @param page_after [String, nil] Opaque cursor from a previous page's
+      #   +next_cursor+. Omit for the first page.
+      # @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,
                search: nil, environments: nil, page_size: nil, page_after: nil)
@@ -112,6 +181,13 @@ module Smplkit
       end
 
       # 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.
+      #
+      # @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)
       end