smplkit 3.0.22 → 3.0.23

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 81748d66161d109c1a8948824656edb9ad0fd9bef8dffd37a1969474c8a731fa
-  data.tar.gz: 188a085ba9c2c99fe3ff5c3e246a75b033e264e7d87efe9e87d94f8e46c8cb34
+  metadata.gz: 3e85fd7fac73ac4413a382782c353db02d602232de188ed1c8a9b7a1c53fcc78
+  data.tar.gz: '04096b74f6d24e798c3eff83a53bad846786f4a077503db5c4c826676a0bfc69'
 SHA512:
-  metadata.gz: 704759f5899aa706dcd6a4217634ca7ab722b452583d470a10f4dd23411f23d429b2989503658bdf6142a4b5a87e024592eceae6a22b5e33d299da7a0b9bb1b6
-  data.tar.gz: b4916402670ef7c2659a2a776388dbd4ef7954560f219f0cb62e69d69b937e24e4a8a930a8d2e2c282a35a0a04134103456d92146611968c7aa14c9a6b1b8e11
+  metadata.gz: 50cb93abf4662d156a38e6609bee9932a8079514d30853485e13b517b7f524b4e4fa9cade5ab36fefa90becfdba5964ae46d6c38afb92df19f9f5fd11c6611b1
+  data.tar.gz: cafaee08710826d6238eaec8e552f25dc0a987ab062c84629a84d340ba73001045b8097b35963f19c31adc55d7895b7d2ca881d9cc29570065f694e8e6962ff3

data/lib/smplkit/audit/models.rb

@@ -113,6 +113,32 @@ 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.
+    module TransformType
+      JSONATA = "JSONATA"
+
+      VALUES = [JSONATA].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 TransformType #{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
@@ -128,12 +154,11 @@ module Smplkit
     # @!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.
+    #   @return [String, nil] Customer-supplied free-form actor type string — +nil+ when not provided.
     # @!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.
+    #   @return [String, nil] Customer-supplied free-form actor identifier — +nil+ when not provided.
     # @!attribute [rw] actor_label
-    #   @return [String, nil] Display label for the actor — typically a name or email.
+    #   @return [String, nil] Customer-supplied 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
@@ -310,13 +335,15 @@ module Smplkit
       #   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.
+      # @return [Object, nil] Optional template applied to each event before
+      #   delivery. Free-form — the audit service passes the value verbatim to
+      #   the engine named by {#transform_type}. For +TransformType::JSONATA+ a
+      #   JSONata expression string; +nil+ delivers the event JSON as-is. Must
+      #   be paired with a non-nil {#transform_type}.
       attr_accessor :transform
 
-      # @return [String, nil] Engine that evaluates {#transform}. Currently
-      #   only +"JSONATA"+ is supported.
+      # @return [String, nil] Engine that evaluates {#transform} — one of
+      #   {TransformType::VALUES}. Required whenever {#transform} is set.
       attr_accessor :transform_type
 
       # @return [String, nil] ISO-8601 timestamp of first persist. +nil+ for an unsaved instance.
@@ -344,7 +371,7 @@ module Smplkit
         @description = description
         @filter = filter
         @transform = transform
-        @transform_type = transform_type
+        @transform_type = TransformType.coerce(transform_type)
         @created_at = created_at
         @updated_at = updated_at
         @deleted_at = deleted_at

data/lib/smplkit/log_level.rb

@@ -5,10 +5,10 @@ module Smplkit
   #
   # Acts as a string-valued enum: each constant equals its name when used in
   # string contexts, and supports comparison via the +ordinal+. Members are
-  # declared in alphabetical order; severity is encoded in {#ordinal}, not
-  # in declaration order.
+  # declared in increasing severity order — matching the Ruby stdlib
+  # +Logger+ convention (TRACE = least severe, SILENT = most severe).
   class LogLevel
-    NAMES = %w[DEBUG ERROR FATAL INFO SILENT TRACE WARN].freeze
+    NAMES = %w[TRACE DEBUG INFO WARN ERROR FATAL SILENT].freeze
 
     # @return [String] Canonical level name (e.g. +"INFO"+).
     attr_reader :name
@@ -32,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 = [DEBUG, ERROR, FATAL, INFO, SILENT, TRACE, WARN].freeze
+    ALL = [TRACE, DEBUG, INFO, WARN, ERROR, FATAL, SILENT].freeze
 
     BY_NAME = ALL.to_h { |lvl| [lvl.name, lvl] }.freeze
 

data/lib/smplkit/management/audit.rb

@@ -43,12 +43,24 @@ module Smplkit
       # @param description [String, nil] Optional free-text description.
       # @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.
+      # @param transform [Object, nil] Optional template applied to each event
+      #   before delivery. Free-form — the audit service passes the value
+      #   verbatim to the engine named by +transform_type+. Must be paired with
+      #   a non-nil +transform_type+.
+      # @param transform_type [String, nil] Engine that evaluates +transform+ —
+      #   one of {Smplkit::Audit::TransformType::VALUES}. Required when
+      #   +transform+ is provided.
+      # @raise [ArgumentError] when +transform+ is set but +transform_type+ is nil.
       # @return [Smplkit::Audit::Forwarder]
       def new_forwarder(name:, forwarder_type:, configuration:,
                         enabled: true, description: nil,
-                        filter: nil, transform: nil)
+                        filter: nil, transform: nil, transform_type: nil)
+        if !transform.nil? && transform_type.nil?
+          raise ArgumentError,
+                "transform_type is required when transform is provided " \
+                "(one of #{Smplkit::Audit::TransformType::VALUES.inspect})"
+        end
+
         Smplkit::Audit::Forwarder.new(
           self,
           name: name,
@@ -58,7 +70,7 @@ module Smplkit
           description: description,
           filter: filter,
           transform: transform,
-          transform_type: transform.nil? ? nil : "JSONATA"
+          transform_type: transform_type
         )
       end
 
@@ -134,7 +146,7 @@ module Smplkit
           forwarder_type: Smplkit::Audit::ForwarderType.coerce(forwarder.forwarder_type),
           enabled: forwarder.enabled,
           filter: forwarder.filter,
-          transform_type: forwarder.transform_type,
+          transform_type: Smplkit::Audit::TransformType.coerce(forwarder.transform_type),
           transform: forwarder.transform,
           configuration: Smplkit::Audit::HttpConfiguration.to_wire(forwarder.configuration)
         )

metadata

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