command_tower 0.4.0 → 0.11.0

data/app/deserializers/command_tower/deserializers/audit/events.rb

@@ -0,0 +1,224 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Deserializers
+    module Audit
+      module Events
+        class UserListDeserializer < CommandTower::Deserializers::ApplicationDeserializer
+          Input = Data.define(:limit, :offset, :actions, :occurred_after, :occurred_before, :subject_types)
+          DEFAULT_LIMIT = 50
+          MAX_LIMIT = 100
+          MAX_MULTI = 50
+          EVENT_NAME = /\A[a-z][a-z0-9_]*\z/
+          SUBJECT_TYPE = /\A[A-Z][A-Za-z0-9_:]*\z/
+
+          def call(params)
+            limit = pagination_integer(fetch_param(params, :limit).value, default: DEFAULT_LIMIT, minimum: 1, maximum: MAX_LIMIT)
+            return failure(errors: { message: "invalid_limit" }) if limit.nil?
+
+            offset = pagination_integer(fetch_param(params, :offset).value, default: 0, minimum: 0)
+            return failure(errors: { message: "invalid_offset" }) if offset.nil?
+
+            actions = optional_event_names(params)
+            return actions if deserializer_result?(actions)
+
+            occurred_after = optional_time(fetch_param(params, :occurredAfter, :occurred_after).value, field: "occurredAfter")
+            return occurred_after if deserializer_result?(occurred_after)
+
+            occurred_before = optional_time(fetch_param(params, :occurredBefore, :occurred_before).value, field: "occurredBefore")
+            return occurred_before if deserializer_result?(occurred_before)
+
+            subject_types = optional_subject_types(params)
+            return subject_types if deserializer_result?(subject_types)
+
+            success(Input.new(limit:, offset:, actions:, occurred_after:, occurred_before:, subject_types:))
+          end
+
+          private
+
+          def pagination_integer(raw, default:, minimum:, maximum: nil)
+            return default if raw.nil? || (raw.is_a?(String) && raw.strip.empty?)
+
+            value = raw.is_a?(Integer) ? raw : (Integer(raw, 10) if raw.is_a?(String) && /\A-?\d+\z/.match?(raw.strip))
+            return if value.nil? || value < minimum || (maximum && value > maximum)
+
+            value
+          rescue ArgumentError
+            nil
+          end
+
+          # Prefer eventNames[] / event_names[]; singular eventName remains a one-element alias.
+          def optional_event_names(params)
+            multi = fetch_param(params, :eventNames, :event_names).value
+            singular = fetch_param(params, :eventName, :event_name).value
+            normalize_token_list(
+              multi,
+              singular,
+              regex: EVENT_NAME,
+              invalid_message: "invalid_eventName",
+              too_many_message: "invalid_eventNames"
+            )
+          end
+
+          def optional_subject_types(params)
+            multi = fetch_param(params, :subjectTypes, :subject_types).value
+            singular = fetch_param(params, :subjectType, :subject_type).value
+            normalize_token_list(
+              multi,
+              singular,
+              regex: SUBJECT_TYPE,
+              invalid_message: "invalid_subjectType",
+              too_many_message: "invalid_subjectTypes"
+            )
+          end
+
+          def normalize_token_list(multi, singular, regex:, invalid_message:, too_many_message:)
+            raw_values =
+              if multi.nil? || (multi.is_a?(String) && multi.strip.empty?)
+                singular.nil? || (singular.is_a?(String) && singular.strip.empty?) ? [] : [singular]
+              elsif multi.is_a?(Array)
+                multi
+              elsif multi.is_a?(String)
+                [multi]
+              else
+                return failure(errors: { message: too_many_message })
+              end
+
+            tokens = []
+            raw_values.each do |raw|
+              next if raw.nil? || (raw.is_a?(String) && raw.strip.empty?)
+              return failure(errors: { message: invalid_message }) unless raw.is_a?(String) && regex.match?(raw.strip)
+
+              tokens << raw.strip
+            end
+
+            tokens = tokens.uniq
+            return failure(errors: { message: too_many_message }) if tokens.length > MAX_MULTI
+
+            tokens
+          end
+
+          def optional_time(raw, field:)
+            return if raw.nil? || (raw.is_a?(String) && raw.strip.empty?)
+            return failure(errors: { message: "invalid_#{field}" }) unless raw.is_a?(String)
+
+            Time.iso8601(raw.strip)
+          rescue ArgumentError
+            failure(errors: { message: "invalid_#{field}" })
+          end
+
+          def optional_positive_integer(raw, field:)
+            return if raw.nil? || (raw.is_a?(String) && raw.strip.empty?)
+
+            value = raw.is_a?(Integer) ? raw : (Integer(raw, 10) if raw.is_a?(String) && /\A\d+\z/.match?(raw.strip))
+            return failure(errors: { message: "invalid_#{field}" }) unless value&.positive?
+
+            value
+          rescue ArgumentError
+            failure(errors: { message: "invalid_#{field}" })
+          end
+        end
+
+        class AdminListDeserializer < UserListDeserializer
+          Input = Data.define(
+            :limit,
+            :offset,
+            :actions,
+            :occurred_after,
+            :occurred_before,
+            :subject_types,
+            :affected_user_id,
+            :actor_user_id,
+            :originating_administrator_id,
+            :attribution_mode,
+            :scope_value
+          )
+          TOOL_ID = "audit"
+
+          def call(params)
+            base = super
+            return base unless base.success?
+
+            affected_user_id = optional_positive_integer(
+              fetch_param(params, :affectedUserId, :affected_user_id).value,
+              field: "affectedUserId"
+            )
+            return affected_user_id if deserializer_result?(affected_user_id)
+
+            actor_user_id = optional_positive_integer(
+              fetch_param(params, :actorUserId, :actor_user_id).value,
+              field: "actorUserId"
+            )
+            return actor_user_id if deserializer_result?(actor_user_id)
+
+            originating_administrator_id = optional_positive_integer(
+              fetch_param(params, :originatingAdministratorId, :originating_administrator_id).value,
+              field: "originatingAdministratorId"
+            )
+            return originating_administrator_id if deserializer_result?(originating_administrator_id)
+
+            attribution_mode = optional_attribution_mode(fetch_param(params, :attributionMode, :attribution_mode).value)
+            return attribution_mode if deserializer_result?(attribution_mode)
+
+            scope_value = CommandTower::Deserializers::Admin::ScopeParameter.extract(params, tool_id: TOOL_ID)
+
+            success(
+              Input.new(
+                limit: base.input.limit,
+                offset: base.input.offset,
+                actions: base.input.actions,
+                occurred_after: base.input.occurred_after,
+                occurred_before: base.input.occurred_before,
+                subject_types: base.input.subject_types,
+                affected_user_id:,
+                actor_user_id:,
+                originating_administrator_id:,
+                attribution_mode:,
+                scope_value:
+              )
+            )
+          end
+
+          private
+
+          def optional_attribution_mode(raw)
+            return if raw.nil? || (raw.is_a?(String) && raw.strip.empty?)
+            unless raw.is_a?(String) && CommandTower::Audit::Event::ATTRIBUTION_MODES.include?(raw.strip)
+              return failure(errors: { message: "invalid_attributionMode" })
+            end
+
+            raw.strip
+          end
+        end
+
+        class ShowDeserializer < CommandTower::Deserializers::ApplicationDeserializer
+          Input = Data.define(:id, :scope_value)
+          TOOL_ID = "audit"
+
+          def call(params)
+            id = optional_positive_integer(fetch_param(params, :id).value, field: "id")
+            return id if deserializer_result?(id)
+            return failure(errors: { message: "invalid_id" }) if id.nil?
+
+            scope_value = CommandTower::Deserializers::Admin::ScopeParameter.extract(params, tool_id: TOOL_ID)
+
+            success(Input.new(id:, scope_value:))
+          end
+
+          private
+
+          def optional_positive_integer(raw, field:)
+            return if raw.nil? || (raw.is_a?(String) && raw.strip.empty?)
+
+            value = raw.is_a?(Integer) ? raw : (Integer(raw, 10) if raw.is_a?(String) && /\A\d+\z/.match?(raw.strip))
+            return failure(errors: { message: "invalid_#{field}" }) unless value&.positive?
+
+            value
+          rescue ArgumentError
+            failure(errors: { message: "invalid_#{field}" })
+          end
+        end
+      end
+    end
+  end
+end

data/app/deserializers/command_tower/deserializers/auth/email_availability_deserializer.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Deserializers
+    module Auth
+      class EmailAvailabilityDeserializer < CommandTower::Deserializers::ApplicationDeserializer
+        Input = Data.define(:email)
+
+        def call(params)
+          email = params[:email].to_s.strip.downcase
+
+          return failure(errors: { message: "missing_email" }) if email.blank?
+
+          success(Input.new(email:))
+        end
+      end
+    end
+  end
+end

data/app/deserializers/command_tower/deserializers/auth/email_verification/verify_deserializer.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Deserializers
+    module Auth
+      module EmailVerification
+        class VerifyDeserializer < CommandTower::Deserializers::ApplicationDeserializer
+          Input = Data.define(:code)
+
+          def call(params)
+            code = params[:code].to_s.strip
+
+            return failure(errors: { message: "missing_code" }) if code.blank?
+
+            success(Input.new(code:))
+          end
+        end
+      end
+    end
+  end
+end

data/app/deserializers/command_tower/deserializers/auth/password_reset/reset_deserializer.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Deserializers
+    module Auth
+      module PasswordReset
+        class ResetDeserializer < CommandTower::Deserializers::ApplicationDeserializer
+          Input = Data.define(:token, :password, :password_confirmation, :email)
+
+          def call(params)
+            token = params[:token].to_s.strip
+            password = params[:password].to_s
+            password_confirmation = params[:passwordConfirmation].to_s.presence || params[:password_confirmation].to_s
+
+            errors = {}
+            errors[:token] = "Token is required" if token.blank?
+            errors[:password] = "Password is required" if password.blank?
+            errors[:passwordConfirmation] = "Password confirmation is required" if password_confirmation.blank?
+
+            return failure(errors:) if errors.any?
+
+            email = params[:email].to_s.strip.downcase
+            email = nil if email.blank?
+
+            success(Input.new(token:, password:, password_confirmation:, email:))
+          end
+        end
+      end
+    end
+  end
+end

data/app/deserializers/command_tower/deserializers/auth/password_reset/send_deserializer.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Deserializers
+    module Auth
+      module PasswordReset
+        class SendDeserializer < CommandTower::Deserializers::ApplicationDeserializer
+          Input = Data.define(:email)
+
+          def call(params)
+            email = params[:email].to_s.strip.downcase
+
+            return failure(errors: { email: "Email is required" }) if email.blank?
+
+            success(Input.new(email:))
+          end
+        end
+      end
+    end
+  end
+end

data/app/deserializers/command_tower/deserializers/auth/password_reset/validate_deserializer.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Deserializers
+    module Auth
+      module PasswordReset
+        class ValidateDeserializer < CommandTower::Deserializers::ApplicationDeserializer
+          Input = Data.define(:token, :email)
+
+          def call(params)
+            token = params[:token].to_s.strip
+            return failure(errors: { token: "Token is required" }) if token.blank?
+
+            email = params[:email].to_s.strip.downcase
+            email = nil if email.blank?
+
+            success(Input.new(token:, email:))
+          end
+        end
+      end
+    end
+  end
+end

data/app/deserializers/command_tower/deserializers/auth/plain_text/login_deserializer.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Deserializers
+    module Auth
+      module PlainText
+        class LoginDeserializer < CommandTower::Deserializers::ApplicationDeserializer
+          Input = Data.define(:identifier, :password)
+
+          def call(params)
+            identifier = params[:identifier].to_s.strip
+            password = params[:password].to_s.strip
+
+            if identifier.blank? || password.blank?
+              return failure(errors: { message: "invalid_credentials" })
+            end
+
+            success(Input.new(identifier:, password:))
+          end
+        end
+      end
+    end
+  end
+end

data/app/deserializers/command_tower/deserializers/auth/register_deserializer.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Deserializers
+    module Auth
+      class RegisterDeserializer < CommandTower::Deserializers::ApplicationDeserializer
+        Input = Data.define(
+          :first_name,
+          :last_name,
+          :username,
+          :email,
+          :password,
+          :password_confirmation
+        )
+
+        def call(params)
+          first_name = params[:first_name].to_s.strip
+          last_name = params[:last_name].to_s.strip
+          username = params[:username].to_s.strip
+          email = params[:email].to_s.strip.downcase
+          password = params[:password].to_s
+          password_confirmation = params[:password_confirmation].to_s
+
+          if [first_name, last_name, username, email, password, password_confirmation].any?(&:blank?)
+            return failure(errors: { message: "missing_required_fields" })
+          end
+
+          success(
+            Input.new(
+              first_name:,
+              last_name:,
+              username:,
+              email:,
+              password:,
+              password_confirmation:
+            )
+          )
+        end
+      end
+    end
+  end
+end

data/app/deserializers/command_tower/deserializers/auth/username_availability_deserializer.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Deserializers
+    module Auth
+      class UsernameAvailabilityDeserializer < CommandTower::Deserializers::ApplicationDeserializer
+        Input = Data.define(:username)
+
+        def call(params)
+          username = params[:username].to_s.strip
+
+          return failure(errors: { message: "missing_username" }) if username.blank?
+
+          success(Input.new(username:))
+        end
+      end
+    end
+  end
+end

data/app/deserializers/command_tower/deserializers/clients/errors.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Deserializers
+    module Clients
+      # Path composition for nested / indexed DeserializationError details.
+      module Errors
+        module_function
+
+        def prefix(error, segment)
+          unless error.is_a?(::CommandTower::Clients::Errors::DeserializationError)
+            raise ::CommandTower::Clients::Errors::ConfigurationError,
+                  "Errors.prefix expects CommandTower::Clients::Errors::DeserializationError"
+          end
+
+          details = error.details.is_a?(Hash) ? error.details.dup : {}
+          details[:path] = compose_path(details[:path], segment)
+
+          ::CommandTower::Clients::Errors::DeserializationError.new(
+            message: error.message,
+            details: details,
+            cause: error.cause || error
+          )
+        end
+
+        def compose_path(current, segment)
+          current = current.to_s
+          segment = segment.to_s
+
+          return segment if current.empty?
+          return current if segment.empty?
+
+          if segment.start_with?("[")
+            "#{segment}.#{current}"
+          elsif current.start_with?("[")
+            "#{segment}#{current}"
+          else
+            "#{segment}.#{current}"
+          end
+        end
+        module_function :compose_path
+      end
+    end
+  end
+end

data/app/deserializers/command_tower/deserializers/clients/missing.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Deserializers
+    module Clients
+      # Sentinel for "key absent from provider payload" — distinct from explicit nil.
+      Missing = Object.new.freeze
+    end
+  end
+end

data/app/deserializers/command_tower/deserializers/clients/payload.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Deserializers
+    module Clients
+      # Payload key extraction that distinguishes absent keys from explicit nil.
+      module Payload
+        module_function
+
+        def fetch(payload, key)
+          unless payload.is_a?(Hash)
+            raise ::CommandTower::Clients::Errors::ConfigurationError,
+                  "Deserializers::Clients::Payload.fetch expects a Hash payload"
+          end
+
+          payload.fetch(key, Missing)
+        end
+      end
+    end
+  end
+end

data/app/deserializers/command_tower/deserializers/clients/result.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Deserializers
+    module Clients
+      # Validated response Result contracts for client deserializers.
+      # ActiveModel attributes are storage only; validation policy lives in +field+ / +build!+.
+      class Result
+        include ActiveModel::Model
+        include ActiveModel::Attributes
+
+        DEFAULT_UNSET = Object.new.freeze
+        private_constant :DEFAULT_UNSET
+
+        class << self
+          def field(name, type:, required: false, nullable: false, default: DEFAULT_UNSET)
+            name = name.to_sym
+            normalized_type = Types.normalize(type)
+
+            if default.equal?(DEFAULT_UNSET)
+              has_default = false
+              default_value = nil
+            else
+              validate_default!(default)
+              has_default = true
+              default_value = default
+            end
+
+            field_definitions[name] = {
+              type: normalized_type,
+              required: required,
+              nullable: nullable,
+              has_default: has_default,
+              default: default_value
+            }
+
+            attribute name
+          end
+
+          def build!(**attrs)
+            values = {}
+            field_definitions.each do |name, meta|
+              raw = attrs.key?(name) ? attrs[name] : Missing
+              values[name] = resolve_field(name, meta, raw)
+            end
+
+            new(**values)
+          end
+
+          def field_definitions
+            @field_definitions ||= {}
+          end
+
+          private
+
+          def inherited(subclass)
+            super
+            subclass.instance_variable_set(:@field_definitions, field_definitions.dup)
+          end
+
+          def validate_default!(default)
+            return if default.is_a?(Proc)
+            return unless shared_mutable_default?(default)
+
+            raise ::CommandTower::Clients::Errors::ConfigurationError,
+                  "mutable field defaults must be a Proc (got: #{default.class})"
+          end
+
+          def shared_mutable_default?(value)
+            value.is_a?(Array) || value.is_a?(Hash)
+          end
+
+          def resolve_field(name, meta, raw)
+            path = name.to_s
+
+            if raw.equal?(Missing)
+              return fail_field!(path, "required", "required field is missing") if meta[:required]
+              return materialize_default(meta[:default]) if meta[:has_default]
+
+              return nil
+            end
+
+            if raw.nil?
+              return nil if meta[:nullable]
+
+              return fail_field!(
+                path,
+                "nullable",
+                "field is not nullable",
+                actual: "NilClass"
+              )
+            end
+
+            meta[:type].call(raw, path: path)
+          end
+
+          def materialize_default(default)
+            default.is_a?(Proc) ? default.call : default
+          end
+
+          def fail_field!(path, rule, message, actual: "Missing")
+            raise ::CommandTower::Clients::Errors::DeserializationError.new(
+              message: message,
+              details: {
+                path: path,
+                expected: rule == "required" ? "present" : "non-nil",
+                actual: actual,
+                rule: rule,
+                messages: [ message ]
+              }
+            )
+          end
+        end
+
+        def ==(other)
+          other.instance_of?(self.class) && attributes == other.attributes
+        end
+        alias eql? ==
+      end
+    end
+  end
+end