real_page 2.3.0

data/Rakefile

@@ -0,0 +1,7 @@
+require 'bundler/gem_tasks'
+
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/bin/console

@@ -0,0 +1,15 @@
+#!/usr/bin/env ruby
+
+require 'bundler/setup'
+require 'pry'
+require 'real_page'
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require 'irb'
+IRB.start

data/bin/setup

@@ -0,0 +1,7 @@
+#!/bin/bash
+set -euo pipefail
+IFS=$'\n\t'
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/config/multi_xml.rb

@@ -0,0 +1,4 @@
+require 'multi_xml'
+require 'ox'
+
+MultiXml.parser = :ox

data/lib/real_page.rb

@@ -0,0 +1,54 @@
+require_relative '../config/multi_xml.rb'
+
+require 'real_page/error/bad_request'
+require 'real_page/error/invalid_configuration'
+require 'real_page/error/invalid_response'
+require 'real_page/error/request_fault'
+
+require 'real_page/model/activity'
+require 'real_page/model/address'
+require 'real_page/model/amenity'
+require 'real_page/model/appointment'
+require 'real_page/model/floor_plan'
+require 'real_page/model/follow_up'
+require 'real_page/model/guest_card'
+require 'real_page/model/lease'
+require 'real_page/model/lease_action'
+require 'real_page/model/phone_number'
+require 'real_page/model/picklist_item'
+require 'real_page/model/preferences'
+require 'real_page/model/prospect'
+require 'real_page/model/quote'
+require 'real_page/model/rent_matrix'
+require 'real_page/model/rent_matrix/concessions'
+require 'real_page/model/rent_matrix/option'
+require 'real_page/model/rent_matrix/row'
+require 'real_page/model/screening'
+require 'real_page/model/unit'
+require 'real_page/model/unit_shown'
+
+require 'real_page/parameter/list_criterion'
+
+require 'real_page/request/get_floor_plan_list'
+require 'real_page/request/get_leases_by_traffic_source'
+require 'real_page/request/get_marketing_sources_by_property'
+require 'real_page/request/get_rent_matrix'
+require 'real_page/request/get_units_by_property'
+require 'real_page/request/prospect_search'
+
+require 'real_page/version'
+
+module RealPage
+  Config = Struct.new(:web_service_url, :username, :password, :license_key, :app_name)
+  private_constant :Config
+
+  class << self
+    def configure(&block)
+      yield config
+    end
+
+    def config
+      @config ||= Config.new
+    end
+  end
+end

data/lib/real_page/attribute_parser.rb

@@ -0,0 +1,48 @@
+require 'real_page/attribute_parser/boolean'
+require 'real_page/attribute_parser/date'
+require 'real_page/attribute_parser/date_time'
+require 'real_page/attribute_parser/decimal'
+require 'real_page/attribute_parser/integer'
+require 'real_page/attribute_parser/object'
+require 'real_page/attribute_parser/string'
+
+module RealPage
+  # Parse the string value from the XML response into the configured data type
+  class AttributeParser
+    # @param value [String] the response value from RealPage
+    # @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 :object
+        AttributeParser::Object.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/real_page/attribute_parser/base.rb

@@ -0,0 +1,21 @@
+module RealPage
+  class AttributeParser
+    # Base class for attribute parsers.
+    class Base
+      # @param value [String] the response value from RealPage
+      def initialize(value)
+        @value = value
+      end
+
+      # @return [Object] the parsed attribute value
+      def parse
+        raise NotImplementedError,
+              "#{self.class.name} must implement #{__method__}"
+      end
+
+      private
+
+      attr_reader :value
+    end
+  end
+end

data/lib/real_page/attribute_parser/boolean.rb

@@ -0,0 +1,25 @@
+require_relative 'base'
+
+module RealPage
+  class AttributeParser
+    # Parse the response value of a boolean attribute
+    class Boolean < Base
+      # Values that RealPage responds with for true
+      TRUE_VALUES = %w[1 true].freeze
+      private_constant :TRUE_VALUES
+
+      # Values that RealPage responds with for true
+      FALSE_VALUES = %w[0 false].freeze
+      private_constant :FALSE_VALUES
+
+      # @return [true|false] the parsed attribute value
+      # @raise [RealPage::Error::InvalidResponse] if the value doesn't parse
+      #   into true or false
+      def parse
+        return true if TRUE_VALUES.include?(value)
+        return false if FALSE_VALUES.include?(value)
+        raise Error::InvalidResponse, "Invalid boolean response value: #{value}"
+      end
+    end
+  end
+end

data/lib/real_page/attribute_parser/date.rb

@@ -0,0 +1,28 @@
+require_relative 'base'
+
+module RealPage
+  class AttributeParser
+    # Parse the response value of a date attribute
+    class Date < Base
+      # RealPage responds with multiple date formats. This is one format that
+      # Date.parse will not parse correctly, so we need special handling
+      FORMAT = '%m/%d/%Y'.freeze
+      private_constant :FORMAT
+
+      # @return [Date] the parsed attribute value
+      def parse
+        return if value == ''
+        if value =~ %r[/]
+          ::Date.strptime(value, FORMAT)
+        else
+          # RealPage sometimes returns 0001-01-01 for dates, which appears to be
+          # their representation of a NULL value.
+          date = ::Date.parse(value)
+          date.year == 1 ? nil : date
+        end
+      rescue ArgumentError
+        raise Error::InvalidResponse, "Invalid date response value: #{value}"
+      end
+    end
+  end
+end

data/lib/real_page/attribute_parser/date_time.rb

@@ -0,0 +1,23 @@
+require 'tzinfo'
+
+require_relative 'base'
+
+module RealPage
+  class AttributeParser
+    # Parse the response value of a date with time attribute.
+    class DateTime < Base
+      # RealPage 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/real_page/attribute_parser/decimal.rb

@@ -0,0 +1,15 @@
+require_relative 'base'
+
+module RealPage
+  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/real_page/attribute_parser/integer.rb

@@ -0,0 +1,15 @@
+require_relative 'base'
+
+module RealPage
+  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/real_page/attribute_parser/object.rb

@@ -0,0 +1,13 @@
+require_relative 'base'
+
+module RealPage
+  class AttributeParser
+    # Parse the response value of an object attribute
+    class Object < Base
+      # @return [Object] the parsed attribute value
+      def parse
+        value
+      end
+    end
+  end
+end

data/lib/real_page/attribute_parser/string.rb

@@ -0,0 +1,13 @@
+require_relative 'base'
+
+module RealPage
+  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/real_page/document_parser.rb

@@ -0,0 +1,6 @@
+module RealPage
+  module DocumentParser
+  end
+
+  private_constant :DocumentParser
+end

data/lib/real_page/document_parser/base.rb

@@ -0,0 +1,51 @@
+require 'multi_xml'
+
+require 'real_page/validator/request_fault'
+require 'real_page/document_parser'
+
+module RealPage
+  module DocumentParser
+    # Base class for parsing RealPage responses. Subclasses must implement
+    # #parse_body and can optionally override #validator_classes to add more
+    # validation than just the default
+    class Base
+      DEFAULT_VALIDATOR_CLASSES = [Validator::RequestFault].freeze
+      private_constant :DEFAULT_VALIDATOR_CLASSES
+
+      # @param xml [String] the XML response from the request
+      # @option param request_params [Object] the request parameter
+      # @return [Object] the parsed object(s) from the rsesponse
+      # @raise [RealPage::Error::Base] if the response is invalid
+
+      def initialize(request_params: nil, request_name: nil)
+        @request_params = request_params
+        @request_name = request_name
+      end
+
+      def parse(xml)
+        parsed = MultiXml.parse(xml)
+        [*DEFAULT_VALIDATOR_CLASSES, *validator_classes].each do |klass|
+          klass.new(parsed, request_params, request_name).validate!
+        end
+        parse_body(parsed['s:Envelope']['s:Body'])
+      end
+
+      attr_reader :request_params, :request_name
+
+      private
+
+      # @param body [Hash<String, Object>] the body of the XML response parsed
+      #   into a Hash
+      # @return [Object] the parsed object(s) from the rsesponse
+      # @raise [RealPage::Error::Base] if the response is invalid
+      def parse_body(body)
+        raise NotImplementedError,
+              "#{self.class.name} must implement #{__method__}"
+      end
+
+      def validator_classes
+        []
+      end
+    end
+  end
+end

data/lib/real_page/document_parser/floor_plan_object.rb

@@ -0,0 +1,30 @@
+require 'real_page/utils/array_fetcher'
+
+require_relative 'base'
+
+module RealPage
+  module DocumentParser
+    # Parse the GetFloorPlanList response
+    class FloorPlanObject < Base
+      private
+
+      # @param body [Hash<String, Object>] the body of the XML response parsed
+      #   into a Hash
+      # @return [Array<RealPage::Model::FloorPlan>] the floor_plans contained
+      #   in the response
+      # @raise [RealPage::Error::Base] if the response is invalid
+      def parse_body(body)
+        Utils::ArrayFetcher.new(
+          hash: floor_plans(body),
+          key: 'FloorPlanObject',
+          model: Model::FloorPlan
+        ).fetch
+      end
+
+      def floor_plans(body)
+        response = body['getfloorplanlistResponse']
+        response['getfloorplanlistResult']['GetFloorPlanList']
+      end
+    end
+  end
+end

data/lib/real_page/document_parser/guest_cards.rb

@@ -0,0 +1,102 @@
+require 'real_page/utils/array_fetcher'
+require 'real_page/validator/prospects_data'
+
+require_relative 'base'
+
+module RealPage
+  module DocumentParser
+    # Parse the ProspectSearch response
+    class GuestCards < Base
+      MULTIPLE_CHILDREN = {
+        'Activities'   => { model: Model::Activity,    key: 'Activity'    },
+        'FollowUps'    => { model: Model::FollowUp,    key: 'FollowUp'    },
+        'LeaseActions' => { model: Model::LeaseAction, key: 'LeaseAction' },
+        'Quotes'       => { model: Model::Quote,       key: 'Quote'       },
+        'Screenings'   => { model: Model::Screening,   key: 'Screening'   },
+        'UnitsShown'   => { model: Model::UnitShown,   key: 'UnitShown'   }
+      }
+      SINGLE_CHILDREN = %w[Appointment Preferences]
+      private_constant :MULTIPLE_CHILDREN, :SINGLE_CHILDREN
+
+      private
+
+      # @param body [Hash<String, Object>] the body of the XML response parsed
+      #   into a Hash
+      # @return [Array<RealPage::Model::GuestCard>] the guest_cards contained
+      #   in the response
+      # @raise [RealPage::Error::Base] if the response is invalid
+      def parse_body(body)
+        guest_cards(body).map do |guest_card|
+          attrs = guest_card.merge(children(guest_card))
+          attrs.delete('Amentities') # Remove the misspelled version
+          Model::GuestCard.new(attrs)
+        end
+      end
+
+      # @return [Hash<String,RealPage::Model] the guest_card's children that
+      #   require more specialized parsing
+      def custom_children(guest_card)
+        {}.tap do |kids|
+          if guest_card['Amentities']
+            kids['Amenities'] = Amenities.new.parse(guest_card['Amentities'])
+          end
+          if guest_card['Prospects']
+            kids['Prospects'] = Prospects.new.parse(guest_card['Prospects'])
+          end
+        end
+      end
+
+      # @return [Hash] the guest_card's children, parsed into RealPage::Models
+      def children(guest_card)
+        single_children(guest_card)
+          .merge(multiple_children(guest_card))
+          .merge(custom_children(guest_card))
+      end
+
+      # @return [Array<Hash<String, Object>>] an array of all GuestCard
+      #   attributes
+      def guest_cards(body)
+        response        = body['prospectsearchResponse']
+        result          = response['prospectsearchResult']
+        prospect_search = result['ProspectSearch'] if result
+        return [] unless prospect_search
+        guest_cards     = prospect_search['GuestCards']
+        Utils::ArrayFetcher.new(hash: guest_cards, key: 'GuestCard').fetch
+      end
+
+      # @return [Hash<String, Array<RealPage::Model>] the guest_card's children
+      #   that can have multiple entries
+      def multiple_children(guest_card)
+        Hash[
+          MULTIPLE_CHILDREN.map do |key, definition|
+            fetcher =
+              Utils::ArrayFetcher.new(definition.merge(hash: guest_card[key]))
+            [key, fetcher.fetch]
+          end
+        ]
+      end
+
+      # @return [Hash<String,RealPage::Model] the guest_card's children that
+      #   have  single entries
+      def single_children(guest_card)
+        Hash[
+          SINGLE_CHILDREN.map do |kid|
+            [kid, Model.const_get(kid).new(guest_card[kid])] if guest_card[kid]
+          end.compact
+        ]
+      end
+
+      def validator_classes
+        [Validator::ProspectsData]
+      end
+    end
+  end
+end
+
+# This file has a circular dependency with its sub-parsers. They file uses
+# the others to help parse the inner objects of the XML, and that file's class
+# definition is nested within this class.
+#
+# Having the require at the bottom of the file keeps the class loader happy
+require_relative 'guest_cards/prospects'
+require_relative 'guest_cards/amenities'