yield_star_client 0.1.0

data/.gitignore

@@ -0,0 +1,8 @@
+pkg/*
+*.gem
+.bundle
+.yardoc/*
+doc/*
+*~
+.DS_Store
+Gemfile.lock

data/.rspec

@@ -0,0 +1,2 @@
+--colour
+--format progress

data/.rvmrc

@@ -0,0 +1,3 @@
+branch_name=`git branch --no-color 2> /dev/null | sed -e '/^[^*]/d' -e 's/* \(.*\)/\1/'`
+rvm --create use 1.8.7@yield_star_client-${branch_name}
+#rvm --create use 1.9.2@yield_star_client-${branch_name}

data/Gemfile

@@ -0,0 +1,4 @@
+source "http://rubygems.org"
+
+# Specify your gem's dependencies in yield_star_client.gemspec
+gemspec

data/README.md

@@ -0,0 +1,38 @@
+# YieldStar Client #
+
+Client adapter for the YieldStar AppExchange web service.
+
+## Installation ##
+
+The YieldStar adapter is available on [Rubygems][rubygems] and can be installed via:
+
+        gem install 'yield_star_client'
+
+## Configuration ##
+
+You will probably only need to configure the username and password for connecting to the remote service:
+
+        YieldStarClient.configure do |config|
+            config.username = 'my_user'
+            config.password = 'my_pass'
+        end
+
+Sensible defaults are provided for other configuration options. **TODO**: link to the docs for the rest of the config.
+
+## Examples ##
+
+**TODO:** More thorough usage examples.
+
+        client = YieldStarClient::Client.new
+        client.get_properties('my_client_name')
+
+**TODO:** Link to docs for more info.
+
+## More Information ##
+
+* [YieldStar documentation][yieldstar-docs]
+* [YieldStar WSDL][yieldstar-wsdl]
+
+ [rubygems]: http://rubygems.org/gems/yield_star_client
+ [yieldstar-docs]: http://rmsws.yieldstar.com/rmsws/doc/AppExchange/index.html
+ [yieldstar-wsdl]: http://rmsws.yieldstar.com/rmsws/AppExchange?wsdl

data/Rakefile

@@ -0,0 +1,17 @@
+require 'bundler'
+Bundler::GemHelper.install_tasks
+
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec
+
+namespace :doc do
+  require 'yard'
+  YARD::Rake::YardocTask.new do |task|
+    task.files   = ['README.md', 'lib/**/*.rb']
+    task.options = [
+      '--markup', 'markdown',
+    ]
+  end
+end

data/lib/yield_star_client/amenity_methods.rb

@@ -0,0 +1,77 @@
+require 'yield_star_client/validations'
+require 'modelish'
+
+module YieldStarClient
+  # Represents a YieldStar amenity.
+  #
+  # All amenities are guaranteed to have a +name+ and +type+; +value+ is optional.
+  #
+  # @attr [String] name the name of the amenity
+  # @attr [String] type the type of the amenity
+  # @attr [Float[ value the value of the amenity
+  class Amenity < Modelish::Base
+    property :name
+    property :type
+    property :value, :type => Float
+  end
+
+  module AmenityMethods
+    include Validations
+
+    # Retrieves all of the amenities associated with a specific floor plan.
+    #
+    # @param [String] client_name the YieldStar client name
+    # @param [String] external_property_id the ID of the property where the floor plan is located
+    # @param [String] floor_plan_name the name of the floor plan
+    #
+    # @return [Array<YieldStarClient::Amenity>] list of amenities
+    #
+    # @raise [ArgumentError] when a required argument is missing or invalid
+    # @raise [YieldStarClient::AuthenticationError] when unable to authenticate to the web service
+    # @raise [YieldStarClient::OperationError] when the service raises an OperationError fault
+    # @raise [YieldStarClient::InternalError] when the service raises an InternalError fault
+    # @raise [YieldStarClient::ServerError] when any other server-side error occurs
+    def get_floor_plan_amenities(client_name, external_property_id, floor_plan_name)
+      validate_client_name!(client_name)
+      validate_external_property_id!(external_property_id)
+      validate_required!(:floor_plan_name => floor_plan_name)
+
+      response = send_soap_request(:get_floor_plan_amenities, :client_name => client_name, 
+                                                              :external_property_id => external_property_id, 
+                                                              :floor_plan_name => floor_plan_name)
+
+      amenities = response.to_hash[:get_floor_plan_amenities_response][:return][:amenity] || []
+      [amenities].flatten.collect { |a| Amenity.new(a) }
+    end
+
+    # Retrieves all of the amenities associated with a specific unit.
+    #
+    # @param [String] client_name the YieldStar client name
+    # @param [String] external_property_id the ID of the property where the floor plan is located
+    # @param [String] unit_name the name of the unit
+    # @param [optional,String] building the name of the building where the unit is located
+    #
+    # @return [Array<YieldStarClient::Amenity>] list of unit amenities
+    #
+    # @raise [ArgumentError] when a required argument is missing or invalid
+    # @raise [YieldStarClient::AuthenticationError] when unable to authenticate to the web service
+    # @raise [YieldStarClient::OperationError] when the service raises an OperationError fault
+    # @raise [YieldStarClient::InternalError] when the service raises an InternalError fault
+    # @raise [YieldStarClient::ServerError] when any other server-side error occurs
+    def get_unit_amenities(client_name, external_property_id, unit_name, building=nil)
+      validate_client_name!(client_name)
+      validate_external_property_id!(external_property_id)
+      validate_required!(:unit_name => unit_name)
+
+      body = {:client_name => client_name,
+              :external_property_id => external_property_id,
+              :unit_name => unit_name}
+      body[:building] = building if building
+
+      response = send_soap_request(:get_unit_amenities, body)
+
+      amenities = response.to_hash[:get_unit_amenities_response][:return][:amenity] || []
+      [amenities].flatten.collect { |a| Amenity.new(a) }
+    end
+  end
+end

data/lib/yield_star_client/client.rb

@@ -0,0 +1,84 @@
+require 'savon'
+
+require 'property_methods'
+require 'floor_plan_methods'
+require 'unit_methods'
+require 'amenity_methods'
+require 'rent_methods'
+require 'lease_term_rent_methods'
+
+require 'errors'
+
+module YieldStarClient
+  # YieldStarClient::Client is the main object for connecting to the YieldStar AppExchange service.
+  # The interface strives to be SOAP-agnostic whenever possible; all inputs and outputs are pure ruby 
+  # and no knowledge of SOAP is required in order to use the client.
+  class Client
+    include PropertyMethods
+    include FloorPlanMethods
+    include UnitMethods
+    include AmenityMethods
+    include RentMethods
+    include LeaseTermRentMethods
+
+    attr_writer *YieldStarClient::VALID_CONFIG_OPTIONS
+
+    YieldStarClient::VALID_CONFIG_OPTIONS.each do |opt|
+      define_method(opt) { get_value(opt) }
+    end
+
+    # Initializes the client. All options are truly optional; if the option
+    # is not supplied to this method, then it will be set based on the
+    # YieldStarClient configuration.
+    #
+    # @see YieldStarClient.configure
+    #
+    # @param [Hash] options
+    # @option options [String] :username The username for authenticating to the web service.
+    # @option options [String] :password The password for authenticating to the web service.
+    # @option options [String] :endpoint The address for connecting to the web service.
+    # @option options [String] :namespace The XML namespace to use for requests.
+    def initialize(options={})
+      options.each { |k,v| self.send("#{k}=", v) if self.respond_to?("#{k}=") }
+    end
+
+    private
+    # Sends a request directly to the SOAP service.
+    #
+    # @param [Symbol] soap_action the action to be invoked
+    # @param [Hash] soap_parameters the parameters to populate the request body
+    # @return [Savon::SOAP::Response]
+    def send_soap_request(soap_action,soap_parameters={})
+      begin
+        response = soap_client.request :wsdl, soap_action do
+          soap.element_form_default = :qualified
+          soap.body = { :request => soap_parameters }
+        end
+      rescue Savon::SOAP::Fault => f
+        raise ServerError.translate_fault(f)
+      end
+    end
+
+    # Sets up a SOAP client for sending SOAP requests directly.
+    #
+    # @return [Savon::Client]
+    def soap_client
+      Savon::Client.new do
+        wsdl.endpoint = self.endpoint.to_s
+        wsdl.namespace = self.namespace
+        http.auth.basic self.username, self.password
+      end
+    end
+
+    # Retrieves an attribute's value. If the attribute has not been set
+    # on this object, it is retrieved from the global configuration.
+    #
+    # @see YieldStarClient.configure
+    # 
+    # @param [Symbol] attribute the name of the attribute
+    # @return [String] the value of the attribute
+    def get_value(attribute)
+      instance_variable_get("@#{attribute}") || YieldStarClient.send(attribute)
+    end
+  end
+end

data/lib/yield_star_client/errors.rb

@@ -0,0 +1,52 @@
+module YieldStarClient
+  # Represents a server-side error returned by the YieldStar web service.
+  class ServerError < StandardError
+    attr_reader :code
+
+    # Creates a new error object.
+    #
+    # @param [String] message the error message. If no message is supplied, the
+    #                 object's class name will be used as the message.
+    # @param [String] code the error code    
+    def initialize(message=nil, code=nil)
+      super(message)
+      @code = code
+    end
+
+    # Translates a soap fault into the appropriate YieldStarClient error.
+    #
+    # @param [Savon::SOAP::Fault] soap_error the error object raised by the soap client
+    # @return [YieldStarClient::ServerError] the corresponding YieldStarClient error
+    def self.translate_fault(soap_error)
+      fault = soap_error.to_hash[:fault]
+
+      # set up defaults
+      error_class = YieldStarClient::ServerError
+      fault_detail = {:code => fault[:faultcode], :message => fault[:faultstring]}
+
+      if detail = fault[:detail]
+        if detail.has_key?(:authentication_fault)
+          error_class = YieldStarClient::AuthenticationError
+          fault_detail = detail[:authentication_fault]
+        elsif detail.has_key?(:operation_fault)
+          error_class = YieldStarClient::OperationError
+          fault_detail = detail[:operation_fault]
+        elsif detail.has_key?(:internal_error_fault)
+          error_class = YieldStarClient::InternalError
+          fault_detail = detail[:internal_error_fault]
+        end
+      end
+
+      error_class.new(fault_detail[:message], fault_detail[:code])
+    end
+  end
+
+  # Represents an error in authenticating to the web service
+  class AuthenticationError < ServerError; end
+
+  # Represents an internal error in the web service
+  class InternalError < ServerError; end
+
+  # Represents an operation error in the web service
+  class OperationError < ServerError; end
+end

data/lib/yield_star_client/floor_plan_methods.rb

@@ -0,0 +1,78 @@
+require 'yield_star_client/validations'
+require 'modelish'
+
+module YieldStarClient
+  # Represents a floor plan in the YieldStar system.
+  #
+  # A floor plan is guaranteed to have an +external_property_id+ and +name+. All other attributes are
+  # optional.
+  #
+  # @attr [String] external_property_id the property ID of this floor plan
+  # @attr [String] name the name of this floor plan
+  # @attr [String] description the description of this floor plan
+  # @attr [Integer] square_feet the average square footage of this floor plan
+  # @attr [Integer] unit_count the number of units with this floor plan
+  # @attr [Float] bedrooms the bedroom count of the floor plan
+  # @attr [Float] bathrooms the bathroom count of the floor plan
+  class FloorPlan < Modelish::Base
+    property :external_property_id
+    property :name
+    property :description
+    property :square_feet, :type => Integer, :from => :square_footage
+    property :unit_count, :type => Integer
+    property :bedrooms, :type => Float, :from => :bed_rooms
+    property :bathrooms, :type => Float, :from => :bath_rooms
+  end
+
+  module FloorPlanMethods
+    include YieldStarClient::Validations
+
+    # Retrieves all floor plans for a particular property.
+    #
+    # @param [String] client_name the YieldStar client name
+    # @param [String] external_property_id the ID of the property
+    # @return [Array<YieldStarClient::FloorPlan>] list of floor plans
+    #
+    # @raise [ArgumentError] when client_name or external_property_id is missing or invalid
+    # @raise [YieldStarClient::AuthenticationError] when unable to authenticate to the web service
+    # @raise [YieldStarClient::OperationError] when the service raises an OperationError fault
+    # @raise [YieldStarClient::InternalError] when the service raises an InternalError fault
+    # @raise [YieldStarClient::ServerError] when any other server-side error occurs
+    def get_floor_plans(client_name, external_property_id)
+      validate_client_name!(client_name)
+      validate_external_property_id!(external_property_id)
+
+      response = send_soap_request(:get_floor_plans, :client_name => client_name, :external_property_id => external_property_id)
+
+      floor_plans = response.to_hash[:get_floor_plans_response][:return][:floor_plan] || []
+      floor_plans = [floor_plans].flatten
+
+      floor_plans.collect { |fp| FloorPlan.new(fp) }
+    end
+
+    # Retrieves a specific floor plan.
+    #
+    # @param [String] client_name the YieldStar client name
+    # @param [String] external_property_id the ID of the property
+    # @param [String] floor_plan_name the name of the floor plan
+    # @return [YieldStarClient::FloorPlan] the floor plan data
+    #
+    # @raise [ArgumentError] when a parameter is missing or invalid
+    # @raise [YieldStarClient::AuthenticationError] when unable to authenticate to the web service
+    # @raise [YieldStarClient::OperationError] when the service raises an OperationError fault
+    # @raise [YieldStarClient::InternalError] when the service raises an InternalError fault
+    # @raise [YieldStarClient::ServerError] when any other server-side error occurs
+    def get_floor_plan(client_name, external_property_id, floor_plan_name)
+      validate_client_name!(client_name)
+      validate_external_property_id!(external_property_id)
+      validate_required!(:floor_plan_name => floor_plan_name)
+
+      response = send_soap_request(:get_floor_plan, :client_name => client_name, 
+                                                    :external_property_id => external_property_id, 
+                                                    :name => floor_plan_name)
+      floor_plan = response.to_hash[:get_floor_plan_response][:return][:floor_plan]
+
+      FloorPlan.new(floor_plan)
+    end
+  end
+end

data/lib/yield_star_client/lease_term_rent_methods.rb

@@ -0,0 +1,185 @@
+require 'yield_star_client/validations'
+require 'modelish'
+
+module YieldStarClient
+  # Represents common unit rate information.
+  #
+  # @attr [String] external_property_id the ID of the property where the unit is located
+  # @attr [String] building the building in which the unit is located
+  # @attr [String] unit_number the unit number identifying this unit
+  # @attr [Integer] lease_term the length, in months, of the lease term
+  # @attr [Date] end_date the date the proposed lease will expire
+  # @attr [Integer] market_rent the market rent for the current lease
+  # @attr [Integer] final_rent the effective rent for the current lease
+  # @attr [true,false] best indicates whether this is the best (i.e. highest) rent 
+  #                         for the unit; defaults to true
+  class UnitRate < Modelish::Base
+    property :external_property_id
+    property :building
+    property :unit_number
+    property :lease_term, :type => Integer
+    property :end_date, :type => Date
+    property :market_rent, :type => Integer
+    property :final_rent, :type => Integer
+    property :best, :type => lambda { |val| val.to_s.strip == 'true' }, :default => true
+  end
+
+  # Represents unit rate data for a combination of lease term
+  # and move-in date for a particular unit.
+  #
+  # @attr {see YieldStarClient::UnitRate}
+  # @attr [Date] make_ready_date the actual date the unit is made available
+  # @attr [Date] move_in_date the move-in date used in project optimum rents for the unit
+  # @attr [Integer] total_concession the total concession amount (defaults to 0)
+  # @attr [Integer] monthly_fixed_concession the monthly fixed concession amount (defaults to 0)
+  # @attr [Float] monthly_percent_concession the monthly concession percentage (defaults to 0.0)
+  # @attr [Float] months_concession the months concession (defaults to 0.0)
+  # @attr [Integer] one_time_fixed_concession the one time fixed concession (defaults to 0.0)
+  # @attr [Date] price_valid_end_date the last date for which the price is valid
+  class LeaseTermRent < UnitRate
+    property :make_ready_date, :type => Date
+    property :move_in_date, :type => Date
+    property :total_concession, :type => Integer, :default => 0
+    property :monthly_fixed_concession, :type => Integer, :default => 0
+    property :monthly_percent_concession, :type => Float, :default => 0.0
+    property :months_concession, :type => Float, :default => 0.0
+    property :one_time_fixed_concession, :type => Integer, :default => 0
+    property :price_valid_end_date, :type => Date, :from => :pv_end_date
+  end
+
+  # Represents rate data for a unit that is up for lease renewal.
+  #
+  # @attr {see YieldStarClient::UnitRate}
+  # @attr [Date] start_date the actual start date of the projected lease (this will only be
+  #                         present when a start date was passed in as input
+  class RenewalLeaseTermRent < UnitRate
+    property :start_date, :type => Date 
+  end
+
+  # @private
+  class LeaseTermRentOptions < Modelish::Base
+    property :unit_number, :required => true, :max_length => 50
+    property :building, :max_length => 50
+    property :min_lease_term, :type => Integer, :validate_type => true
+    property :max_lease_term, :type => Integer, :validate_type => true
+    property :first_move_in_date, :type => Date, :validate_type => true
+    property :last_move_in_date, :type => Date, :validate_type => true
+    property :ready_for_move_in_date, :type => Date, :validate_type => true
+    property :unit_available_date, :type => Date, :validate_type => true
+    property :start_date, :type => Date, :validate_type => true
+
+    def to_request_hash
+      h = {}
+      self.class.properties.each do |name|
+        h[name] = self.send(name).to_s if self.send(name)
+      end
+      h
+    end
+  end
+
+  module LeaseTermRentMethods
+    include Validations
+
+    # Retrieves a matrix providing the specific rate for each combination of 
+    # lease term and move-in date for a particular unit.
+    #
+    # @param [String] client_name the YieldStar client name
+    # @param [String] external_property_id the ID of the property where the unit is located
+    # @param [String] unit_number the unit_number that identifies the available unit
+    # @param [Hash] opts optional filters for lease term data
+    # @option opts [String] :building the building in which the unit is located
+    # @option opts [Integer] :min_lease_term the minimum lease term for the lease matrix projections
+    # @option opts [Integer] :max_lease_term the maximum lease term for the lease matrix projections
+    # @option opts [Date] :first_move_in_date the start of the move-in date range for projecting optimum rents
+    # @option opts [Date] :last_move_in_date the end of the move-in date range for projecting optimum rents
+    # @option opts [Date] :ready_for_move_in_date the date that the unit is made ready for occupancy
+    # @option opts [Date] :unit_available_date the first date that the unit is vacant
+    #
+    # @return [Array<YieldStarClient::LeaseTermRent>] unit rate data
+    #
+    # @raise [ArgumentError] when a required argument is missing or invalid
+    # @raise [YieldStarClient::AuthenticationError] when unable to authenticate to the web service
+    # @raise [YieldStarClient::OperationError] when the service raises an OperationError fault
+    # @raise [YieldStarClient::InternalError] when the service raises an InternalError fault
+    # @raise [YieldStarClient::ServerError] when any other server-side error occurs
+    def get_lease_term_rent(client_name, external_property_id, unit_number, opts={})
+      opts ||= {}
+      call_lease_term_rent_method(client_name, 
+                                  external_property_id, 
+                                  unit_number, 
+                                  opts.merge(:request_element => :lease_term_rent_unit_request,
+                                             :soap_action => :get_lease_term_rent,
+                                             :response_element => :lease_term_rent_unit_response,
+                                             :result_class => LeaseTermRent))
+    end
+
+    # This method is identical to {#get_lease_term_rent}, but the return value also includes
+    # the last date for which the price is valid.
+    #
+    # {see #get_lease_term_rent}
+    def get_lease_term_rent_plus(client_name, external_property_id, unit_number, opts={})
+      opts ||= {}
+      call_lease_term_rent_method(client_name, 
+                                  external_property_id, 
+                                  unit_number, 
+                                  opts.merge(:request_element => :lease_term_rent_unit_request,
+                                             :soap_action => :get_lease_term_rent_plus,
+                                             :response_element => :lease_term_rent_unit_plus_response,
+                                             :result_class => LeaseTermRent))
+    end
+
+    # Retrieves rate data for units that are within "Renewal Notice Days" of lease expiration, 
+    # and those units for which renewal rates have been manually generated and accepted.
+    #
+    # @param [String] client_name the YieldStar client name
+    # @param [String] external_property_id the ID of the property where the unit is located
+    # @param [String] unit_number the unit_number that identifies the available unit
+    # @param [Hash] opts optional filters for lease term data
+    # @option opts [String] :building the building in which the unit is located
+    # @option opts [Integer] :min_lease_term the minimum lease term for the lease matrix projections
+    # @option opts [Integer] :max_lease_term the maximum lease term for the lease matrix projections
+    # @option opts [Date] :start_date the actual start date of the renewal
+    #
+    # @return [Array<YieldStarClient::RenewalLeaseTermRent>] the list of units up for renewal
+    #
+    # @raise {see #get_lease_term_rent}
+    def get_renewal_lease_term_rent(client_name, external_property_id, unit_number, opts={})
+      opts ||= {}
+      call_lease_term_rent_method(client_name, 
+                                  external_property_id, 
+                                  unit_number, 
+                                  opts.merge(:request_element => :renewal_lease_term_rent_unit_request,
+                                             :soap_action => :get_renewal_lease_term_rent,
+                                             :response_element => :renewal_lease_term_rent_unit_response,
+                                             :result_class => RenewalLeaseTermRent))
+    end
+
+    private
+    def call_lease_term_rent_method(client_name, external_property_id, unit_number, opts={})
+      validate_client_name!(client_name)
+      validate_external_property_id!(external_property_id)
+
+      request_opts = opts.merge(:unit_number => unit_number)
+      request_opts.delete_if { |k,v| [:request_element, :soap_action, :response_element, :result_class].include?(k) }
+
+      lease_term_opts = LeaseTermRentOptions.new(request_opts.merge(:unit_number => unit_number))
+      lease_term_opts.validate!
+      request_params = {:client_name => client_name,
+                        :external_property_id => external_property_id,
+                        opts[:request_element] => lease_term_opts.to_request_hash}
+
+      response = send_soap_request(opts[:soap_action], request_params)
+      response_hash = response.to_hash["#{opts[:soap_action]}_response".to_sym][:return][opts[:response_element]] || {}
+
+      common_params = {:external_property_id => external_property_id.to_s}
+      common_params.merge!(response_hash.reject { |k,v| k == :unit_rate })
+
+      unit_rates = response_hash[:unit_rate] || []
+      unit_rates = [unit_rates].flatten
+
+      unit_rates.collect do |r|
+        opts[:result_class].new(common_params.merge(r)) 
+      end
+    end
+  end
+end