amsi 1.0.0

data/lib/amsi/attribute_parser/date_time.rb

@@ -0,0 +1,24 @@
+require 'tzinfo'
+
+require_relative 'base'
+
+module Amsi
+  class AttributeParser
+    # Parse the response value of a date with time attribute.
+    class DateTime < Base
+      # AMSI time strings are assumed to be in Central time.
+      TIME_ZONE = TZInfo::Timezone.get('America/Chicago')
+      private_constant :TIME_ZONE
+
+      # @return [Date] the parsed attribute value
+      def parse
+        return if value == ''
+        date_time = ::DateTime.parse(value)
+        TIME_ZONE.local_to_utc(date_time) { |periods| periods.last }
+      rescue ArgumentError
+        raise Error::InvalidResponse,
+              "Invalid date/time response value: #{value}"
+      end
+    end
+  end
+end

data/lib/amsi/attribute_parser/decimal.rb

@@ -0,0 +1,15 @@
+require_relative 'base'
+
+module Amsi
+  class AttributeParser
+    # Parse the response value of a decimal attribute
+    class Decimal < Base
+      # @return [Float] the parsed attribute value
+      def parse
+        Float(value)
+      rescue ArgumentError
+        raise Error::InvalidResponse, "Invalid decimal response value: #{value}"
+      end
+    end
+  end
+end

data/lib/amsi/attribute_parser/integer.rb

@@ -0,0 +1,15 @@
+require_relative 'base'
+
+module Amsi
+  class AttributeParser
+    # Parse the response value of an integer attribute
+    class Integer < Base
+      # @return [Integer] the parsed attribute value
+      def parse
+        Integer(value, 10)
+      rescue ArgumentError
+        raise Error::InvalidResponse, "Invalid integer response value: #{value}"
+      end
+    end
+  end
+end

data/lib/amsi/attribute_parser/string.rb

@@ -0,0 +1,13 @@
+require_relative 'base'
+
+module Amsi
+  class AttributeParser
+    # Parse the response value of a string attribute
+    class String < Base
+      # @return [String] the parsed attribute value
+      def parse
+        value
+      end
+    end
+  end
+end

data/lib/amsi/attribute_parser.rb

@@ -0,0 +1,45 @@
+require 'amsi/attribute_parser/boolean'
+require 'amsi/attribute_parser/date'
+require 'amsi/attribute_parser/date_time'
+require 'amsi/attribute_parser/decimal'
+require 'amsi/attribute_parser/integer'
+require 'amsi/attribute_parser/string'
+
+module Amsi
+  # Parse the string value from the XML response into the configured data type
+  class AttributeParser
+    # @param value [String] the response value from AMSI
+    # @param type [Symbol] the attribute's configured data type
+    def initialize(value:, type:)
+      @value = value
+      @type = type
+    end
+
+    # @return [Object] the parsed attribute value
+    def parse
+      return unless value
+      case type
+      when :boolean
+        AttributeParser::Boolean.new(value).parse
+      when :date
+        AttributeParser::Date.new(value).parse
+      when :date_time
+        AttributeParser::DateTime.new(value).parse
+      when :decimal
+        AttributeParser::Decimal.new(value).parse
+      when :integer
+        AttributeParser::Integer.new(value).parse
+      when :string
+        AttributeParser::String.new(value).parse
+      else
+        raise ArgumentError, "Invalid attribute type: #{type}"
+      end
+    end
+
+    private
+
+    attr_reader :value, :type
+  end
+
+  private_constant :AttributeParser
+end

data/lib/amsi/document_parser/base.rb

@@ -0,0 +1,52 @@
+require 'multi_xml'
+require 'amsi/validator/prospect_event_validator'
+require 'amsi/validator/resident_event_validator'
+
+module Amsi
+  module DocumentParser
+    # Base class for parsing AMSI responses. Subclasses must implement
+    # #parse_body and can optionally override #validator_classes to add more
+    # validation than just the default
+    class Base
+      def initialize(params = {})
+        @params = params
+      end
+
+      # @param xml [String] the XML response from the request
+      # @return [Object] the parsed object(s) from the response
+      # @raise [Amsi::Error::Base] if the response is invalid
+      def parse(xml)
+        begin
+          parsed_response = MultiXml.parse(xml)
+        rescue MultiXml::ParseError => e
+          raise Amsi::Error::UnparsableResponse.new(xml)
+        end
+
+        validate_response!(parsed_response)
+
+        parse_body(parsed_response['soap:Envelope']['soap:Body'])
+      end
+
+      private
+
+      def validate_response!(response_hash)
+        [*validator_classes].each do |klass|
+          klass.new(response_hash).validate!
+        end
+      end
+
+      # @param body [Hash<String, Object>] the body of the XML response parsed
+      #   into a Hash
+      # @return [Object] the parsed object(s) from the response
+      # @raise [Amsi::Error::Base] if the response is invalid
+      def parse_body(body)
+        raise NotImplementedError,
+              "#{self.class.name} must implement #{__method__}"
+      end
+
+      def validator_classes
+        [Validator::RequestErrors, Validator::RequestFault, Validator::ResidentEventValidator, Validator::ProspectEventValidator]
+      end
+    end
+  end
+end

data/lib/amsi/document_parser/get_moveins.rb

@@ -0,0 +1,66 @@
+require 'amsi/validator/request_errors'
+
+require_relative 'base'
+
+module Amsi
+  module DocumentParser
+    # Parse the GetMoveinsByFirstMarketingSource response
+    class GetMoveins < Base
+      private
+
+      # @param body [Hash<String, Object>] the body of the XML response parsed
+      #   into a Hash
+      # @return [Array<Amsi::Model::Lease>] the leases contained in the
+      #   response
+      # @raise [Amsi::Error::Base] if the response is invalid
+      def parse_body(body)
+        lease_hashes(body).map do |lease_hash|
+          lease = Model::Lease.new(lease_hash)
+          lease.occupants = occupants(lease_hash)
+          lease.guest_card = guest_card(lease_hash)
+          lease.matched_guest_cards = matched_guest_cards(lease_hash)
+
+          lease
+        end
+      end
+
+      def lease_hashes(body)
+        response = body['GetMoveinsByFirstMarketingSourceResponse']
+        escaped_result = response['GetMoveinsByFirstMarketingSourceResult']
+        parsed_result = MultiXml.parse(escaped_result)
+        leases = parsed_result['Leases']['Lease']
+
+        return [] if leases.nil?
+        leases.is_a?(Array) ? leases : [leases]
+      end
+
+      def occupants(lease_hash)
+        occupant_hashes(lease_hash).map do |occupant_hash|
+          Model::Occupant.new(occupant_hash)
+        end
+      end
+
+      def occupant_hashes(lease_hash)
+        occupants = lease_hash['Occupant']
+
+        return [] if occupants.nil?
+        occupants.is_a?(Array) ? occupants : [occupants]
+      end
+
+      def guest_card(lease_hash)
+        guest_card_hash = lease_hash['GuestCard']
+        Model::GuestCard.new(guest_card_hash) unless guest_card_hash.nil?
+      end
+
+      def matched_guest_cards(lease_hash)
+        matched_guest_card_hashes = lease_hash['MatchedGuestCard']
+
+        if matched_guest_card_hashes.is_a?(Hash)
+          [matched_guest_card_hashes]
+        else
+          [*matched_guest_card_hashes]
+        end.map { |h| Model::GuestCard.new(h) }
+      end
+    end
+  end
+end

data/lib/amsi/document_parser/guest_card_result.rb

@@ -0,0 +1,31 @@
+require 'amsi/validator/request_errors'
+require 'amsi/validator/request_fault'
+require 'amsi/error/bad_request'
+
+require_relative 'base'
+
+module Amsi
+  module DocumentParser
+    # Parse the AddGuestCard response
+    class GuestCardResult < Base
+      private
+
+      # @param body [Hash<String, Object>] the body of the XML response parsed
+      #   into a Hash
+      # @return [Array<Amsi::Model::Lease>] the leases contained in the
+      #   response
+      # @raise [Amsi::Error::Base] if the response is invalid
+      def parse_body(body)
+        response = body['AddGuestCardResponse']
+        escaped_result = response['AddGuestCardResult']
+        parsed_result = MultiXml.parse(escaped_result)['EDEX']
+        Model::GuestCardResult.new(
+          contact_seq_no: parsed_result['contactseqno'],
+          guest_card_id: parsed_result['guestcardid'],
+          property_id: parsed_result['propertyid'],
+          status: parsed_result['status']
+        )
+      end
+    end
+  end
+end

data/lib/amsi/document_parser/leases.rb

@@ -0,0 +1,46 @@
+require 'amsi/validator/request_errors'
+
+require_relative 'base'
+
+module Amsi
+  module DocumentParser
+    # Parse the GetPropertyResidents response
+    class Leases < Base
+      private
+
+      # @param body [Hash<String, Object>] the body of the XML response parsed
+      #   into a Hash
+      # @return [Array<Amsi::Model::Lease>] the leases contained in the
+      #   response
+      # @raise [Amsi::Error::Base] if the response is invalid
+      def parse_body(body)
+        lease_hashes(body).map do |lease_hash|
+          lease = Model::Lease.new(lease_hash)
+          lease.occupants = occupant_hashes(lease_hash).map do |occupant_hash|
+            Model::Occupant.new(occupant_hash)
+          end
+          Validator::ResidentEventValidator.new.send_event(lease, @params)
+          Validator::ProspectEventValidator.new.send_event(lease, @params)
+          lease
+        end
+      end
+
+      def lease_hashes(body)
+        response = body['GetPropertyResidentsResponse']
+        escaped_result = response['GetPropertyResidentsResult']
+        parsed_result = MultiXml.parse(escaped_result)
+        leases = parsed_result['PropertyResidents']['Lease']
+
+        return [] if leases.nil?
+        leases.is_a?(Array) ? leases : [leases]
+      end
+
+      def occupant_hashes(lease_hash)
+        occupants = lease_hash['Occupant']
+
+        return [] if occupants.nil?
+        occupants.is_a?(Array) ? occupants : [occupants]
+      end
+    end
+  end
+end

data/lib/amsi/document_parser/properties.rb

@@ -0,0 +1,103 @@
+require 'amsi/validator/request_errors'
+
+require_relative 'base'
+
+module Amsi
+  module DocumentParser
+    # Parse the GetPropertyList response
+    class Properties < Base
+      ADDRESS_ATTRS = %i[
+        Line1
+        Line2
+        Line3
+        Line4
+        City
+        State
+        ZipCode
+        Country
+      ].freeze
+      private_constant :ADDRESS_ATTRS
+
+      MANAGER_ATTR_MAP = {
+        'MgrOffPhoneNo' => 'phone',
+        'MgrFaxNo' => 'fax',
+        'MgrSalutation' => 'salutation',
+        'MgrFirstName' => 'first_name',
+        'MgrMiName' => 'middle_name',
+        'MgrLastName' => 'last_name'
+      }.freeze
+      private_constant :MANAGER_ATTR_MAP
+
+      private
+
+      # @param body [Hash<String, Object>] the body of the XML response parsed
+      #   into a Hash
+      # @return [Array<Amsi::Model::Property>] the properties contained in
+      #   the response
+      # @raise [Amsi::Error::Base] if the response is invalid
+      def parse_body(body)
+        property_hashes(body).map do |property_hash|
+          property = Model::Property.new(property_hash)
+          property.address = address(property_hash, 'Property')
+          property.remit_to_address = address(property_hash, 'RemitTo')
+          property.manager = manager(property_hash)
+          property.leasing_agents = leasing_agents(property_hash)
+          property.marketing_sources = marketing_sources(property_hash)
+          property.unit_types = unit_types(property_hash)
+          property
+        end
+      end
+
+      def address(property_hash, prefix)
+        address_attrs = ADDRESS_ATTRS.map.with_object({}) do |field, hash|
+          hash[field] = property_hash["#{prefix}Addr#{field}"]
+        end
+        Model::Address.new(address_attrs)
+      end
+
+      def manager(property_hash)
+        manager_attrs = MANAGER_ATTR_MAP.map.with_object({}) do |(node, attr), hash|
+          hash[attr] = property_hash[node]
+        end
+        Model::Manager.new(manager_attrs)
+      end
+
+      def leasing_agents(property_hash)
+        agent_hashes = property_hash['LeasingAgent']
+        return [] if agent_hashes.nil?
+        agent_hashes = [agent_hashes] unless agent_hashes.is_a?(Array)
+        agent_hashes.map do |agent_hash|
+          Model::LeasingAgent.new(agent_hash)
+        end
+      end
+
+      def marketing_sources(property_hash)
+        source_hashes = property_hash['MarketingSource']
+        return [] if source_hashes.nil?
+        source_hashes = [source_hashes] unless source_hashes.is_a?(Array)
+        source_hashes.map do |source_hash|
+          Model::MarketingSource.new(source_hash)
+        end
+      end
+
+      def unit_types(property_hash)
+        type_hashes = property_hash['UnitType']
+        return [] if type_hashes.nil?
+        type_hashes = [type_hashes] unless type_hashes.is_a?(Array)
+        type_hashes.map do |type_hash|
+          Model::UnitType.new(type_hash)
+        end
+      end
+
+      def property_hashes(body)
+        response = body['GetPropertyListResponse']
+        escaped_result = response['GetPropertyListResult']
+        parsed_result = MultiXml.parse(escaped_result)
+        properties = parsed_result['Properties']['Property']
+
+        return [] if properties.nil?
+        properties.is_a?(Array) ? properties : [properties]
+      end
+    end
+  end
+end

data/lib/amsi/error/bad_request.rb

@@ -0,0 +1,18 @@
+require_relative 'base'
+
+module Amsi
+  module Error
+    # Raised when an AMSI request has an error node in the contents. This
+    # generally happens when one of the parameters in a section other than the
+    # auth section is invalid.
+    class BadRequest < Base
+      attr_reader :errors
+
+      # @param errors [Object] object must respond to message
+      def initialize(errors)
+        super(errors.map(&:message).join('; '))
+        @errors = errors
+      end
+    end
+  end
+end

data/lib/amsi/error/base.rb

@@ -0,0 +1,9 @@
+module Amsi
+  module Error
+    # A base class for all errors that originate from this gem
+    class Base < StandardError
+    end
+
+    private_constant :Base
+  end
+end

data/lib/amsi/error/invalid_response.rb

@@ -0,0 +1,9 @@
+require_relative 'base'
+
+module Amsi
+  module Error
+    # Raised when we cannot parse the response
+    class InvalidResponse < Base
+    end
+  end
+end

data/lib/amsi/error/request_fault.rb

@@ -0,0 +1,18 @@
+require_relative 'base'
+
+module Amsi
+  module Error
+    # Raised when a AMSI request has a fault node, which general appears
+    # when there is an issue with the auth section in the request (e.g.
+    # invalid password)
+    class RequestFault < Base
+      attr_reader :fault_code, :details
+
+      def initialize(message, fault_code, details = nil)
+        super(message)
+        @fault_code = fault_code
+        @details = details
+      end
+    end
+  end
+end

data/lib/amsi/error/request_timeout.rb

@@ -0,0 +1,9 @@
+require_relative 'base'
+
+module Amsi
+  module Error
+    # Raised when a AMSI request times out
+    class RequestTimeout < Base
+    end
+  end
+end

data/lib/amsi/error/unparsable_response.rb

@@ -0,0 +1,11 @@
+require_relative 'base'
+
+module Amsi
+  module Error
+    ##
+    # An Error that is raised when Amsi response cannot be parsed.
+    #
+    class UnparsableResponse < Base
+    end
+  end
+end

data/lib/amsi/model/address.rb

@@ -0,0 +1,18 @@
+require_relative 'base'
+
+module Amsi
+  module Model
+    class Address < Base
+      string_attrs *%i[
+        line_1
+        line_2
+        line_3
+        line_4
+        city
+        state
+        zip_code
+        country
+      ]
+    end
+  end
+end

data/lib/amsi/model/base/attribute.rb

@@ -0,0 +1,63 @@
+module Amsi
+  module Model
+    class Base
+      # Encapsulate a model attribute
+      class Attribute
+        attr_reader :prefix, :type, :name
+
+        def initialize(prefix:, type:, name:)
+          @prefix = prefix
+          @type = type
+          @name = name.to_s
+        end
+
+        # @return [String] the name of the method on the model used to access
+        #   this attribute
+        def accessor_name
+          type == :boolean ? "#{name}?" : name
+        end
+
+        # There is some magic happening here to support more convenient
+        # attribute names. Since Model::Base.new can take parameters from a
+        # parsed XML document or from a human, we need to be able to look up
+        # the attribute based on either. The general mapping looks like:
+        #
+        #  XML node      | attribute name
+        # ---------------+--------------------
+        #  SomeThing     | some_thing
+        #  something     | some_thing
+        #  SomeThingID   | some_thing_id
+        #  somethingID   | some_thing_id
+        #  foobarid      | bar_id (if in Model::Foo)
+        #  somethingbit  | some_thing (if defined as a :boolean)
+        #  somethingflag | some_thing (if defined as a :boolean)
+        #
+        # @param attr [String|Symbol] the name of the attribute or the XML node
+        #   name from the AMSI response, e.g. :made_ready_date or
+        #   "MadeReadyDate"
+        # @return [true|false] true iff the value passed in is for this
+        #   Attribute
+        def matches?(attr)
+          possible_names.include?(attr.to_s.downcase)
+        end
+
+        private
+
+        def possible_names
+          squished_name = name.gsub(/_/, '')
+          prefixed_name = "#{prefix}#{squished_name}"
+          names = [name, squished_name, prefixed_name]
+          if name.end_with?('id')
+            big_id_names = [squished_name.gsub(/id$/, 'ID'),
+                            prefixed_name.gsub(/id$/, 'ID')]
+            names.concat(big_id_names)
+          end
+          if type == :boolean
+            names.concat(["#{squished_name}flag", "#{squished_name}bit"])
+          end
+          names
+        end
+      end
+    end
+  end
+end

data/lib/amsi/model/base/attribute_store.rb

@@ -0,0 +1,37 @@
+require_relative 'attribute'
+
+module Amsi
+  module Model
+    class Base
+      # Hold attributes defined with the DSL in Models
+      class AttributeStore
+        def initialize(model_class)
+          @model_class = model_class
+          @attributes = []
+        end
+
+        # Add all attributes of the same type to the AttributeStore
+        def add(type, attrs)
+          attrs.map do |attr|
+            attribute = Attribute.new(prefix: prefix, type: type, name: attr)
+            @attributes << attribute
+            attribute
+          end
+        end
+
+        # Find a specific attribute with the given name
+        def find(attr)
+          attributes.detect { |attribute| attribute.matches?(attr) }
+        end
+
+        private
+
+        attr_reader :attributes, :model_class
+
+        def prefix
+          ''
+        end
+      end
+    end
+  end
+end

data/lib/amsi/model/base.rb

@@ -0,0 +1,64 @@
+require 'amsi/attribute_parser'
+require_relative 'base/attribute_store'
+
+module Amsi
+  module Model
+    # Base class for models, which are the return values from Requests
+    class Base
+      class << self
+        attr_accessor :attribute_store
+      end
+
+      # Create a DSL to define the models attributes and their data types. This
+      # bit of meta-programming will create a class method for each data type
+      # to define the model's attributes of the type, e.g.
+      #
+      #   class LostAndFound < Base
+      #     date_attr :found_date, :lost_date
+      #   end
+      #
+      # When a new LostAndFound is initialized (from an AMSI response hash,
+      # that may have the keys 'founddate' and 'lostdate'), it will create
+      # attribute readers for #found_date and #lost_date that return Date
+      # instances.
+      #
+      # Boolean attributes will have the existential '?', e.g.
+      #
+      #   class LostAndFound < Base
+      #     boolean_attr :found
+      #   end
+      #
+      # lost_and_found = LostAndFound.new('foundbit' => '1')
+      # lost_and_found.found?
+      # # => true
+      %i[
+        boolean date date_time decimal integer object string phone
+      ].each do |data_type|
+        define_singleton_method "#{data_type}_attrs" do |*attrs|
+          self.attribute_store ||= AttributeStore.new(self)
+          attribute_store.add(data_type, attrs).each do |attribute|
+            define_method attribute.accessor_name do
+              instance_variable_get("@#{attribute.name}")
+            end
+          end
+        end
+      end
+
+      # Initialize a new model with the response hash from AMSI. Attribute
+      # values are parsed into their configured data types.
+      #
+      # @param attrs [Hash<String, Object>] the response hash from AMSI.
+      #   Attribute keys are case insensitive.
+      def initialize(attrs = {})
+        attrs.each do |attr, value|
+          attribute = self.class.attribute_store.find(attr)
+          next unless attribute
+          parser = AttributeParser.new(value: value, type: attribute.type)
+          instance_variable_set("@#{attribute.name}", parser.parse)
+        end
+      end
+    end
+
+    private_constant :Base
+  end
+end