command_tower 0.4.0 → 0.11.0

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

@@ -0,0 +1,219 @@
+# 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 float
+          FloatType.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 FloatType < Type
+          include Singleton
+
+          def call(value, path:)
+            return value if value.is_a?(Float)
+            return value.to_f if value.is_a?(Integer)
+
+            if value.is_a?(String)
+              begin
+                return Float(value)
+              rescue ArgumentError
+                reject!(path, value, "float", "not a numeric string")
+              end
+            end
+
+            reject!(path, value, "float", "expected Float")
+          end
+
+          def expected_label
+            "float"
+          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

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

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Deserializers
+    module Messaging
+      module Preferences
+        class UpdateDeserializer < CommandTower::Deserializers::ApplicationDeserializer
+          Input = Data.define(:notification_type_key, :preference_state)
+
+          ROUTING_KEYS = %w[controller action format notification_type_key preference].freeze
+          ALLOWED_PREFERENCE_KEYS = %w[inboxEnabled channels].freeze
+
+          def call(params)
+            raw = normalize_hash(params)
+            return failure(errors: { message: "invalid_notification_type_key" }) if raw.nil?
+
+            notification_type_key = raw["notification_type_key"]
+            if notification_type_key.nil? || !notification_type_key.is_a?(String) || notification_type_key.strip.empty?
+              return failure(errors: { message: "invalid_notification_type_key" })
+            end
+
+            extras = raw.keys - ROUTING_KEYS - ["preferences"]
+            return failure(errors: { message: "unexpected_fields" }) if extras.any?
+            return failure(errors: { message: "missing_preferences" }) unless raw.key?("preferences")
+
+            preferences = raw["preferences"]
+            return failure(errors: { message: "invalid_preferences" }) unless preferences.is_a?(Hash)
+
+            preference_state = parse_preferences(preferences)
+            return preference_state if preference_state.is_a?(DeserializerResult)
+
+            success(
+              Input.new(
+                notification_type_key: notification_type_key.strip,
+                preference_state:,
+              ),
+            )
+          end
+
+          private
+
+          def normalize_hash(params)
+            hash =
+              if params.respond_to?(:to_unsafe_h)
+                params.to_unsafe_h
+              elsif params.respond_to?(:to_h)
+                params.to_h
+              else
+                return nil
+              end
+
+            hash.each_with_object({}) do |(key, value), result|
+              result[key.to_s] =
+                if value.respond_to?(:to_unsafe_h)
+                  value.to_unsafe_h.transform_keys(&:to_s)
+                elsif value.is_a?(Hash)
+                  value.transform_keys(&:to_s)
+                else
+                  value
+                end
+            end
+          end
+
+          def parse_preferences(preferences)
+            unknown = preferences.keys - ALLOWED_PREFERENCE_KEYS
+            return failure(errors: { message: "unexpected_preference_fields" }) if unknown.any?
+
+            state = {}
+
+            if preferences.key?("channels")
+              channels = preferences["channels"]
+              return failure(errors: { message: "invalid_channels" }) unless channels.is_a?(Hash)
+
+              parsed_channels = {}
+              channels.each do |channel_key, channel_value|
+                return failure(errors: { message: "invalid_channel_key" }) unless channel_key.is_a?(String) || channel_key.is_a?(Symbol)
+                return failure(errors: { message: "invalid_channel_value" }) unless [true, false].include?(channel_value)
+
+                parsed_channels[channel_key.to_s] = channel_value
+              end
+              state["channels"] = parsed_channels
+            end
+
+            if preferences.key?("inboxEnabled")
+              inbox = preferences["inboxEnabled"]
+              return failure(errors: { message: "invalid_inbox_enabled" }) unless [true, false].include?(inbox)
+
+              state["inbox"] = inbox
+            end
+
+            state
+          end
+        end
+      end
+    end
+  end
+end

data/app/errors/command_tower/errors/account/phone_already_verified_error.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Errors
+    module Account
+      class PhoneAlreadyVerifiedError < CommandTower::Errors::ApplicationError
+        def code
+          "phone_already_verified"
+        end
+
+        def message
+          "Phone number is already verified"
+        end
+      end
+    end
+  end
+end

data/app/errors/command_tower/errors/account/phone_missing_error.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Errors
+    module Account
+      class PhoneMissingError < CommandTower::Errors::ApplicationError
+        def code
+          "phone_missing"
+        end
+
+        def message
+          "Phone number is required"
+        end
+      end
+    end
+  end
+end

data/app/errors/command_tower/errors/account/phone_verification_code_invalid_error.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Errors
+    module Account
+      class PhoneVerificationCodeInvalidError < CommandTower::Errors::ApplicationError
+        def code
+          "phone_verification_code_invalid"
+        end
+
+        def message
+          "Incorrect verification code"
+        end
+      end
+    end
+  end
+end

data/app/errors/command_tower/errors/account/phone_verification_expired_error.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Errors
+    module Account
+      class PhoneVerificationExpiredError < CommandTower::Errors::ApplicationError
+        def code
+          "phone_verification_code_expired"
+        end
+
+        def message
+          "Verification code has expired"
+        end
+      end
+    end
+  end
+end