command_tower 0.4.0 → 0.10.0

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

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

@@ -0,0 +1,192 @@
+# frozen_string_literal: true
+
+require "singleton"
+
+module CommandTower
+  module Deserializers
+    module Clients
+      # Composable type processors for response Result validation.
+      # Each raises CommandTower::Clients::Errors::DeserializationError intentionally — no broad rescue.
+      module Types
+        module_function
+
+        def integer
+          IntegerType.instance
+        end
+
+        def string
+          StringType.instance
+        end
+
+        def boolean
+          BooleanType.instance
+        end
+
+        def array(element_type)
+          ArrayType.new(normalize(element_type))
+        end
+
+        def union(*member_types)
+          raise ::CommandTower::Clients::Errors::ConfigurationError, "Types.union requires at least one member" if member_types.empty?
+
+          UnionType.new(member_types.map { |t| normalize(t) })
+        end
+
+        def normalize(type)
+          case type
+          when Type
+            type
+          when Class
+            unless type < Result
+              raise ::CommandTower::Clients::Errors::ConfigurationError,
+                    "nested type must be a CommandTower::Deserializers::Clients::Result subclass (got: #{type})"
+            end
+
+            ResultInstanceType.new(type)
+          when nil
+            raise ::CommandTower::Clients::Errors::ConfigurationError, "type must not be nil"
+          else
+            raise ::CommandTower::Clients::Errors::ConfigurationError,
+                  "unknown type declaration: #{type.inspect}"
+          end
+        end
+        module_function :normalize
+
+        class Type
+          def call(_value, path:)
+            raise NotImplementedError
+          end
+
+          def expected_label
+            self.class.name
+          end
+
+          private
+
+          def reject!(path, value, expected, message)
+            raise ::CommandTower::Clients::Errors::DeserializationError.new(
+              message: message,
+              details: {
+                path: path.to_s,
+                expected: expected,
+                actual: value.nil? ? "NilClass" : value.class.name,
+                rule: "type",
+                messages: [ message ]
+              }
+            )
+          end
+        end
+
+        class IntegerType < Type
+          include Singleton
+
+          def call(value, path:)
+            return value if value.is_a?(Integer)
+
+            if value.is_a?(String)
+              begin
+                return Integer(value, 10)
+              rescue ArgumentError
+                reject!(path, value, "integer", "not a whole-number string")
+              end
+            end
+
+            reject!(path, value, "integer", "expected Integer")
+          end
+
+          def expected_label
+            "integer"
+          end
+        end
+
+        class StringType < Type
+          include Singleton
+
+          def call(value, path:)
+            return value if value.is_a?(String)
+
+            reject!(path, value, "string", "expected String")
+          end
+
+          def expected_label
+            "string"
+          end
+        end
+
+        class BooleanType < Type
+          include Singleton
+
+          def call(value, path:)
+            return value if value == true || value == false
+
+            reject!(path, value, "boolean", "expected true or false")
+          end
+
+          def expected_label
+            "boolean"
+          end
+        end
+
+        class ResultInstanceType < Type
+          def initialize(klass)
+            @klass = klass
+          end
+
+          def call(value, path:)
+            return value if value.instance_of?(@klass)
+
+            reject!(path, value, @klass.name, "expected #{@klass.name} instance")
+          end
+
+          def expected_label
+            @klass.name
+          end
+        end
+
+        class ArrayType < Type
+          def initialize(element_type)
+            @element_type = element_type
+          end
+
+          def call(value, path:)
+            unless value.is_a?(Array)
+              reject!(path, value, "array", "expected Array")
+            end
+
+            value.each_with_index.map do |item, index|
+              member_path = path.empty? ? "[#{index}]" : "#{path}[#{index}]"
+              @element_type.call(item, path: member_path)
+            end
+          end
+
+          def expected_label
+            "array"
+          end
+        end
+
+        class UnionType < Type
+          def initialize(member_types)
+            @member_types = member_types
+          end
+
+          def call(value, path:)
+            @member_types.each do |member|
+              begin
+                return member.call(value, path: path)
+              rescue ::CommandTower::Clients::Errors::DeserializationError
+                next
+              end
+            end
+
+            labels = @member_types.map(&:expected_label).join(" | ")
+            reject!(path, value, labels, "value matched no union member")
+          end
+
+          def expected_label
+            @member_types.map(&:expected_label).join(" | ")
+          end
+        end
+      end
+    end
+  end
+end

data/app/deserializers/command_tower/deserializers/coercion_result.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Deserializers
+    class CoercionResult
+      attr_reader :value, :failures
+
+      def initialize(ok:, value: nil, failures: [])
+        @ok = ok
+        @value = value
+        @failures = failures
+      end
+
+      def ok?
+        @ok
+      end
+
+      def failure?
+        !ok?
+      end
+
+      def self.ok(value)
+        new(ok: true, value: value, failures: [])
+      end
+
+      def self.fail(code:, field: nil, details: {})
+        new(
+          ok: false,
+          value: nil,
+          failures: [Failure.build(code: code, field: field, details: details)]
+        )
+      end
+    end
+  end
+end

data/app/deserializers/command_tower/deserializers/failure.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Deserializers
+    module Failure
+      module_function
+
+      def build(code:, field: nil, details: {})
+        entry = { code: code.to_s, field: field&.to_s, details: details || {} }
+        entry
+      end
+    end
+  end
+end

data/app/deserializers/command_tower/deserializers/me/change_password_deserializer.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Deserializers
+    module Me
+      # Transport-only: required fields, camelCase/snake_case, blank detection.
+      # LoginStrategy owns password policy, confirmation match, and current-password check.
+      class ChangePasswordDeserializer < CommandTower::Deserializers::ApplicationDeserializer
+        Input = Data.define(:current_password, :password, :password_confirmation)
+
+        def call(params)
+          current_password = params[:current_password] || params[:currentPassword]
+          password = params[:password]
+          password_confirmation = params[:password_confirmation] || params[:passwordConfirmation]
+
+          if blank?(current_password) || blank?(password) || blank?(password_confirmation)
+            return failure(errors: { message: "missing_required_fields" })
+          end
+
+          unless current_password.is_a?(String) && password.is_a?(String) && password_confirmation.is_a?(String)
+            return failure(errors: { message: "invalid_field_types" })
+          end
+
+          success(
+            Input.new(
+              current_password: current_password,
+              password: password,
+              password_confirmation: password_confirmation
+            )
+          )
+        end
+
+        private
+
+        def blank?(value)
+          value.nil? || (value.is_a?(String) && value.strip.empty?)
+        end
+      end
+    end
+  end
+end

data/app/deserializers/command_tower/deserializers/me/phone_verification/verify_deserializer.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Deserializers
+    module Me
+      module PhoneVerification
+        class VerifyDeserializer
+          Result = Struct.new(:success?, :input, :errors, keyword_init: true)
+          Input = Struct.new(:code, keyword_init: true)
+
+          def self.call(params)
+            raw = params[:code].presence || params.dig(:phone_verification, :code).presence
+            code = raw.to_s.strip
+
+            if code.blank?
+              return Result.new(
+                success?: false,
+                input: nil,
+                errors: { code: "is required" }
+              )
+            end
+
+            Result.new(success?: true, input: Input.new(code:), errors: {})
+          end
+        end
+      end
+    end
+  end
+end

data/app/deserializers/command_tower/deserializers/me/pushover/credentials_deserializer.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Deserializers
+    module Me
+      module Pushover
+        class CredentialsDeserializer < CommandTower::Deserializers::ApplicationDeserializer
+          Input = Data.define(:user_key, :application_token)
+
+          def call(params)
+            user_key = extract(params, :user_key, :userKey)
+            application_token = extract(params, :application_token, :applicationToken)
+
+            if user_key.blank? || application_token.blank?
+              return failure(errors: { message: "missing_required_fields" })
+            end
+
+            success(Input.new(user_key:, application_token:))
+          end
+
+          private
+
+          def extract(params, snake, camel)
+            raw = params[snake] || params[camel]
+            raw.nil? ? "" : raw.to_s.strip
+          end
+        end
+      end
+    end
+  end
+end

data/app/deserializers/command_tower/deserializers/me/update_name_deserializer.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Deserializers
+    module Me
+      class UpdateNameDeserializer < CommandTower::Deserializers::ApplicationDeserializer
+        Input = Data.define(:first_name, :last_name)
+
+        def call(params)
+          first_name = (params[:first_name] || params[:firstName]).to_s.strip
+          last_name = (params[:last_name] || params[:lastName]).to_s.strip
+
+          if first_name.blank? || last_name.blank?
+            return failure(errors: { message: "missing_required_fields" })
+          end
+
+          success(Input.new(first_name:, last_name:))
+        end
+      end
+    end
+  end
+end

data/app/deserializers/command_tower/deserializers/me/update_phone_deserializer.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Deserializers
+    module Me
+      class UpdatePhoneDeserializer < CommandTower::Deserializers::ApplicationDeserializer
+        Input = Data.define(:phone_number)
+
+        def call(params)
+          raw = params[:phone_number] || params[:phoneNumber]
+          phone_number = raw.nil? ? "" : raw.to_s
+
+          if phone_number.strip.blank?
+            return failure(errors: { message: "missing_required_fields" })
+          end
+
+          success(Input.new(phone_number:))
+        end
+      end
+    end
+  end
+end

data/app/deserializers/command_tower/deserializers/messaging/inbox.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Deserializers
+    module Messaging
+      module Inbox
+        class ListDeserializer < CommandTower::Deserializers::ApplicationDeserializer
+          Input = Data.define(:limit, :offset, :scope)
+          DEFAULT_LIMIT = 50
+          MAX_LIMIT = 100
+          ALLOWED_SCOPES = %w[inbox archived].freeze
+
+          def call(params)
+            limit = integer(params[:limit], default: DEFAULT_LIMIT, minimum: 1, maximum: MAX_LIMIT)
+            return failure(errors: { message: "invalid_limit" }) if limit.nil?
+
+            offset = integer(params[:offset], default: 0, minimum: 0)
+            return failure(errors: { message: "invalid_offset" }) if offset.nil?
+
+            scope = params[:scope].presence || "inbox"
+            return failure(errors: { message: "invalid_scope" }) unless scope.is_a?(String) && ALLOWED_SCOPES.include?(scope.strip)
+
+            success(Input.new(limit:, offset:, scope: scope.strip))
+          end
+
+          private
+
+          def 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
+        end
+
+        class ShowDeserializer < CommandTower::Deserializers::ApplicationDeserializer
+          Input = Data.define(:inbox_item_id)
+
+          def call(params)
+            value = positive_integer(params[:id])
+            return failure(errors: { message: "invalid_inbox_item_id" }) unless value
+
+            success(Input.new(inbox_item_id: value))
+          end
+
+          private
+
+          def positive_integer(raw)
+            value = raw.is_a?(Integer) ? raw : (Integer(raw, 10) if raw.is_a?(String) && /\A\d+\z/.match?(raw.strip))
+            value if value&.positive?
+          rescue ArgumentError
+            nil
+          end
+        end
+
+        class BulkIdsDeserializer < ShowDeserializer
+          Input = Data.define(:inbox_item_ids)
+          MAX_IDS = 100
+
+          def call(params)
+            raw = params[:ids]
+            return failure(errors: { message: "invalid_ids" }) unless raw.is_a?(Array) && raw.any? && raw.size <= MAX_IDS
+
+            values = raw.map { |entry| positive_integer(entry) }
+            return failure(errors: { message: "invalid_ids" }) if values.any?(&:nil?)
+
+            success(Input.new(inbox_item_ids: values.uniq))
+          end
+        end
+      end
+    end
+  end
+end

data/app/deserializers/command_tower/deserializers/messaging/preferences/show_deserializer.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Deserializers
+    module Messaging
+      module Preferences
+        class ShowDeserializer < CommandTower::Deserializers::ApplicationDeserializer
+          Input = Data.define
+
+          def call(_params)
+            success(Input.new)
+          end
+        end
+      end
+    end
+  end
+end