reps_client 0.0.1

data/.gitignore

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

data/.rspec

@@ -0,0 +1 @@
+--colour

data/.rvmrc

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

data/Gemfile

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

data/README.md

@@ -0,0 +1,62 @@
+# REPS Client #
+
+This adapter provides a simple wrapper around a SOAP client for the [MDI Achieve][mdi] REPS Leads web service.
+
+## Installation ##
+
+To use this library prior to the initial release, add this to your Gemfile:
+
+        gem 'reps_client', :git => 'git@github.com:g5search/reps_client.git', :branch => 'development'
+
+## Basics ##
+
+For more details on any topic, see the [RDocs][rdocs].
+
+### Configuration ###
+
+Most commonly, you will only need to supply the enterprise key in order to access the service.
+
+Configuration options can be set at the module level to automatically apply it to all client instances:
+
+        RepsClient.configure do |config|
+          config.enterprise_key = 'mykey'
+        end
+
+        client = RepsClient::Client.new
+
+Or you can set it on each individual client instance:
+
+        client = RepsClient::Client.new(:enterprise_key => 'mykey')
+
+### Examples ###
+
+To retrieve a list of communities that belong to this enterprise:
+
+        communities = client.get_communities
+        # => [#<RepsClient::Community address1="123 Anywhere Ln" city="Somewhere" community_id="2" name="Pine View Terrace" state="AK" zip="12345">, #<RepsClient::Community community_id="8" name="The Hills at Dale Valley">]
+
+To retrieve a list of enumerated data types (e.g. relationship type, ad source) that are available for a particular community:
+
+        pick_lists = client.get_pick_lists(2)
+        # => {:prefix => [#<RepsClient::Prefix prefix_id="1" value="Mr.">, #<RepsClient::Prefix prefix_id="2" value="Ms.">],
+        #     :suffix => [#<RepsClient::Suffix suffix_id="200" value="Jr.">, #<RepsClient::Suffix suffix_id="99" value="M.D">],
+        #     :relationship_type => [#<RepsClient::RelationshipType relationship_type_id="42" name="Self">],
+        #     :source => [#<RepsClient::Source source_id="99" code="WEB" description="From the community website">]}
+
+To save a lead, which include a contact and prospect. A very simple lead might look like this:
+
+        contact = RepsClient::Contact.new(:prefix => 'Mr.',
+                                          :first_name => 'Fred',
+                                          :last_name => 'Rogers',
+                                          :email => 'misterrogers@neighborhood.com',
+                                          :relationship_to_prospect_id => 2,
+                                          :source_id => 99)
+        prospect = RepsClient::Prospect.new(:prefix => 'Mr.',
+                                            :first_name => 'Fred',
+                                            :last_name => 'Rogers',
+                                            :email => 'misterrogers@neighborhood.com',
+                                            :notes => 'Request for Brochure')
+        client.save_lead(2, contact, prospect)
+
+ [mdi]: http://mdiachieve.com
+ [rdocs]: http://rubydoc.info/gems/reps_client

data/Rakefile

@@ -0,0 +1,14 @@
+require 'bundler/gem_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/reps_client.rb

@@ -0,0 +1,12 @@
+require 'reps_client/version'
+require 'reps_client/configuration'
+
+module RepsClient
+  extend Configuration
+
+  require 'reps_client/client'
+
+  Modelish.configure do |config|
+    config.ignore_unknown_properties = true
+  end
+end

data/lib/reps_client/client.rb

@@ -0,0 +1,95 @@
+require 'savon'
+
+require 'reps_client/community'
+require 'reps_client/errors'
+require 'reps_client/pick_list'
+require 'reps_client/lead'
+
+module RepsClient
+  # TODO: document RepsClient::Client
+  class Client
+    include CommunityMethods
+    include PickListMethods
+    include LeadMethods
+
+    # Mutators for configuration options
+    attr_writer *RepsClient::VALID_CONFIG_OPTIONS
+
+    # Accessors for configuration options
+    RepsClient::VALID_CONFIG_OPTIONS.each do |opt|
+      define_method(opt) { get_value(opt) }
+    end
+
+    # Initializes the client.
+    #
+    # @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] :enterprise_key The enterprise key for authentication 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
+
+    # The raw SOAP client to directly execute requests against the REPS service.
+    # Preconfigures all service-wide endpoints, namespace URLs, credentials, etc.
+    # This method is provided as a convenience to developers; it should rarely be
+    # used directly.
+    #
+    # @return [Savon::Client] the SOAP client
+    def soap_client
+      Savon::Client.new do
+        wsdl.endpoint = self.endpoint.to_s
+        wsdl.namespace = self.namespace.to_s
+        wsse.credentials self.username, self.password, false
+
+        # We have to override the wsse timestamp method to force UTC
+        # (the reps service cacks on any other timezone)
+        class << wsse
+          define_method(:timestamp, lambda { @timestamp ||= Time.now.utc.xs_datetime })
+        end
+      end
+    end
+
+    # Sends a SOAP request to the remote service. This method takes care of
+    # constructing the SOAP envelope and headers as well as common parameters
+    # for REPS (e.g. the enterprise key)
+    #
+    # @param [Symbol] soap_action the name of the soap action to invoke (in snake-case, e.g. ":my_soap_action")
+    # @param [Hash] soap_parameters the input parameters for the soap action. All symbolic keys will
+    #                               converted to strings in lowerCamelCase (e.g. :my_soap_param becomes
+    #                               'mySoapParam'); no conversion is performed on string keys.
+    # @return [Savon::SOAP::Response] the response from the service
+    def send_soap_request(soap_action,soap_parameters={})
+      begin
+        # The service requires that the soap action be in capitalized camelcase
+        # (e.g. 'GetCommunities') but the rest of the XML elements need to be in
+        # lower camelcase (e.g. 'enterpriseKey'). So we handle the soap_action
+        # format ourselves and retain Gyoku's default lower camelcase translation
+        # for everything else
+        camelcase_action = Gyoku::XMLKey.create(soap_action).gsub(/^[a-z]/) { |m| m.upcase }
+
+        response = soap_client.request :wsdl, camelcase_action do
+          soap.element_form_default = :qualified
+          soap.body = {:enterprise_key => self.enterprise_key}.merge(soap_parameters)
+          http.headers['SOAPAction'] = %{"#{URI.join(self.namespace, camelcase_action)}"}
+        end
+      rescue Savon::SOAP::Fault => f
+        raise RepsClient::ServiceError.translate_fault(f)
+      end
+    end
+
+
+    # Retrieves an attribute value. If the attribute has not been set
+    # on this object, it is retrieved from the global configuration.
+    #
+    # @see RepsClient.configure
+    # 
+    # @param [Symbol] attribute the name of the attribute
+    # @return [String] the value of the attribute
+    def get_value(attribute)
+      instance_variable_get("@#{attribute}") || RepsClient.send(attribute)
+    end
+  end
+end

data/lib/reps_client/community.rb

@@ -0,0 +1,23 @@
+require 'modelish'
+
+module RepsClient
+  # A community (i.e. location) as configured in the MDI REPS service.
+  class Community < Modelish::Base
+    property :community_id, :from => :community_idy, :type => Integer
+    property :name, :type => String
+    property :address1, :from => :community_address1, :type => String
+    property :address2, :from => :community_address2, :type => String
+    property :city, :from => :community_city, :type => String
+    property :state, :from => :community_state, :type => String
+    property :zip, :from => :community_zip, :type => String
+  end
+
+  module CommunityMethods
+    def get_communities
+      response = send_soap_request(:get_communities)
+      communities = response.to_hash[:get_communities_response][:get_communities_result][:diffgram][:document_element][:community]
+      communities ||= []
+      [communities].flatten.collect { |c| Community.new(c) }
+    end
+  end
+end

data/lib/reps_client/configuration.rb

@@ -0,0 +1,83 @@
+require 'configlet'
+
+module RepsClient
+  # All valid configurations options
+  VALID_CONFIG_OPTIONS = [:endpoint, :username, :password, :namespace, :enterprise_key]
+
+  DEFAULT_ENDPOINT = 'https://repssuite.mdiachieve.com/webservices/lead.asmx?wsdl'
+  DEFAULT_NAMESPACE = 'http://www.mdiachieve.com/'
+
+  module Configuration
+    include Configlet
+ 
+    def self.extended(base)
+      # Default configuration - happens whether or not .configure is called
+      base.config :reps_client do
+        default :endpoint => DEFAULT_ENDPOINT
+        default :namespace => DEFAULT_NAMESPACE
+      end
+    end
+
+    # Mutators and accessors for configuration options
+    VALID_CONFIG_OPTIONS.each do |config_opt|
+      define_method(config_opt) do
+        self[config_opt]
+      end
+
+      define_method("#{config_opt}=".to_sym) do |val|
+        self[config_opt] = val
+      end
+    end
+
+    # Configures this module through the given +block+.
+    # Default configuration options will be applied unless 
+    # they are explicitly overridden in the +block+.
+    #
+    # @yield [_self] configures service connection options
+    # @yieldparam [YieldstarClient] _self the object on which the configure method was called
+    # @example Typical case utilizing defaults
+    #   RepsClient.configure do |config|
+    #     config.username = 'my_user'
+    #     config.password = 'my_pass'
+    #     config.enterprise_key = 'my_key'
+    #   end
+    # @example Overriding defaults
+    #   RepsClient.configure do |config|
+    #     config.username = 'my_user'
+    #     config.password = 'my_pass'
+    #     config.endpoint = 'http://my.endpoint.com'
+    #     config.namespace = 'http://my.namespace.com'
+    #     config.enterprise_key = 'my_key'
+    #   end
+    # @return [RepsClient] _self
+    # @see VALID_CONFIG_OPTIONS
+    def configure
+      config :reps_client do
+        yield self
+      end
+
+      self
+    end
+
+    # Create a hash of configuration options and their
+    # values.
+    #
+    # @return [Hash<Symbol,Object>] the options hash
+    def options
+      VALID_CONFIG_OPTIONS.inject({}) do |option, key|
+        option.merge!(key => send(key))
+      end
+    end
+
+    # Resets this module's configuration.
+    # Configuration options will be set to default values
+    # if they exist; otherwise, they will be set to nil.
+    #
+    # @see VALID_CONFIG_OPTIONS
+    # @see DEFAULT_ENDPOINT
+    # @see DEFAULT_NAMESPACE
+    def reset
+      VALID_CONFIG_OPTIONS.each { |opt| self.send("#{opt}=", nil) } 
+    end
+  end
+end

data/lib/reps_client/errors.rb

@@ -0,0 +1,36 @@
+module RepsClient
+  # Represents a server-side error returned by the REPS web service.
+  class ServiceError < 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 RepsClient error.
+    #
+    # @param [Savon::SOAP::Fault] soap_error the error object raised by the soap client
+    # @return [RepsClient::ServiceError] the corresponding RepsClient error
+    def self.translate_fault(soap_error)
+      fault = soap_error.to_hash[:fault]
+
+      # set up defaults
+      error_class = RepsClient::ServiceError
+
+      if fault[:faultcode] == 'InvalidEnterpriseKey'
+        error_class = RepsClient::InvalidEnterpriseKeyError
+      end
+
+      error_class.new(fault[:faultstring], fault[:faultcode])
+    end
+  end
+
+  # Represents an error in the enterprise key sent to the REPS service
+  class InvalidEnterpriseKeyError < ServiceError; end
+end

data/lib/reps_client/lead.rb

@@ -0,0 +1,291 @@
+require 'modelish'
+
+module RepsClient
+  # The person who is the primary contact for a lead.
+  #
+  # Minimally, a Contact is required to have a first name,
+  # last name, and some means of contacting them (email, phone,
+  # or mailing address). All other attributes are optional.
+  #
+  # @example Creating a valid contact with an email address
+  #   contact = RepsClient::Contact.new(:first_name => 'Alice',
+  #                                     :last_name => 'Aardvark',
+  #                                     :email => 'alice@aardvark.com')
+  #
+  # @example Creating a valid contact with a phone number
+  #   contact = RepsClient::Contact.new(:first_name => 'Bob',
+  #                                     :last_name => 'Builder',
+  #                                     :phone => '5551234567')
+  #
+  # @example Creating a valid contact with a mailing address
+  #   contact = RepsClient::Contact.new(:first_name => 'Charleston',
+  #                                     :last_name => 'Chew',
+  #                                     :address1 => '123 Gumdrop Ct',
+  #                                     :city => 'Candyland',
+  #                                     :state => 'CA',
+  #                                     :zip_code => '12345')
+  class Contact < Modelish::Base
+    # @attribute [rw] 
+    # @return [String] the contact's salutation (e.g. "Mr.", "Ms.", "Dr.", etc.)
+    # @see RepsClient::PickListMethods#get_pick_lists
+    property :prefix, :type => String, :max_length => 30
+
+    # @attribute [rw] 
+    # @return [String] the contact's first name
+    # @note This attribute is required on initialization.
+    property :first_name, :type => String, :required => true, :max_length => 30
+
+    # @attribute [rw]
+    # @return [String] the contact's middle name or initial
+    property :middle_name, :type => String, :max_length => 30
+
+    # @attribute [rw]
+    # @return [String] the contact's last name
+    # @note This attribute is required on initialization.
+    property :last_name, :type => String, :required => true, :max_length => 30
+
+    # @attribute [rw]
+    # @return [String] the contact's name suffix (e.g. 'Jr.', 'M.D.', etc.)
+    # @see RepsClient::PickListMethods#get_pick_lists
+
+    property :suffix, :type => String, :max_length => 30
+
+    # @attribute [rw]
+    # @return [String] the first line of the contact's street address
+    # @note This attribute is only required when there is no phone or email.
+    property :address1, :type => String, :max_length => 100
+
+    # @attribute [rw]
+    # @return [String] the second line of the contact's street address
+    property :address2, :type => String, :max_length => 100
+
+    # @attribute [rw]
+    # @return [String] the city for the contact's mailing address
+    property :city, :type => String, :max_length => 50
+
+    # @attribute [rw]
+    # @return [String] the state code for the contact's mailing address
+    property :state, :type => String, :max_length => 2
+
+    # @attribute [rw]
+    # @return [String] the zip code for the contact's mailing address
+    property :zip_code, :type => String, :max_length => 10
+
+    # @attribute [rw]
+    # @return [String] the country from the contact's mailing address
+    property :country, :type => String
+
+    # @attribute [rw]
+    # @return [String] the contact's phone number
+    property :phone, :type => String, :max_length => 20
+
+    # @attribute [rw]
+    # @return [String] the contact's phone number extension
+    property :phone_extension, :type => String, :max_length => 5
+
+    # @attribute [rw]
+    # @return [String] the contact's email address
+    property :email, :type => String, :max_length => 100
+
+    # @attribute [rw]
+    # @return [int] the relationship type id describing the contact's relationship to the prospect
+    # @note The relationship type is determined based on the contact's answer to the question 'What
+    # is your relationship to the prospect?' For instance, if a contact was acting on behalf of their
+    # mother, the relationship type name might be 'Child'. Valid relationship types are available from
+    # the remote service.
+    # @see RepsClient::PickListMethods#get_pick_lists
+    property :relationship_to_prospect_id, :type => Integer
+
+    # @attribute [rw]
+    # @return [true,false] contact opted in to mailings (defaults to false)
+    property :include_in_mailings, :default => false, :type => lambda { |v| !!v }
+
+    # @attribute [rw]
+    # @return [true,false] contact opted in to mailings (defaults to false)
+    property :include_in_emailings, :default => false, :type => lambda { |v| !!v }
+
+    # @attribute [rw]
+    # @return [int]
+    # @see RepsClient::PickListMethods#get_pick_lists
+    # @note This attribute is required on initialization.
+    property :source_id, :type => Integer, :required => true, :validate_type => true
+
+    # Validates attributes (including contact method), returning errors.
+    # @see http://rubydoc.info/gems/modelish/Modelish/Validations#validate-instance_method
+    def validate
+      errors = super
+      [:phone, :email, :address1, :city, :state, :zip_code].each do |k|
+        errors[k] ||= []
+        errors[k] << contact_method_error
+      end unless has_contact_method?
+      errors
+    end
+
+    # Validates attributes (including contact method), raising errors.
+    # @see http://rubydoc.info/gems/modelish/Modelish/Validations#validate%21-instance_method
+    def validate!
+      super
+      raise contact_method_error unless has_contact_method?
+    end
+
+    # Checks that at least one contact method has been supplied.
+    # Possible contact methods include email, phone, and mailing address.
+    #
+    # @return [true,false] true if there is at least one contact method; false otherwise
+    def has_contact_method?
+      !(phone.blank? && email.blank? && (address1.blank? || city.blank? || state.blank? || zip_code.blank?))
+    end
+
+    # @private
+    # Wrangle the model into a format that the service will accept
+    def to_soap_hash
+      hash = {:order! => []}
+
+      [:prefix, :first_name, :middle_name, :last_name, :suffix,
+       :address1, :address2, :city, :state, :zip_code, :country,
+       :phone, :phone_extension, :email, :relationship_to_prospect_id,
+       :include_in_mailings, :include_in_emailings, :source_id].each do |prop|
+        val = self.send(prop)
+
+        unless val.nil?
+          key = prop == :source_id ? 'SourceIDY' : prop.to_s.camelcase
+          hash[key] = val
+          hash[:order!] << key
+        end
+      end
+
+      hash
+    end
+
+    private
+    def contact_method_error
+      ArgumentError.new('Must have one or more of the following: phone, email, or mailing address.')
+    end
+  end
+
+  # The person on whose behalf the lead was submitted; the prospective resident.
+  class Prospect < Modelish::Base
+    # @attribute [rw]
+    # @return [String] the prospect's salutation (e.g. 'Mr.', 'Ms.', 'Dr.', etc.)
+    # @see RepsClient::PickListMethods#get_pick_lists
+    property :prefix, :type => String, :max_length => 30
+
+    # @attribute [rw]
+    # @return [String] the prospect's first name 
+    property :first_name, :type => String, :max_length => 30
+
+    # @attribute [rw]
+    # @return [String] the prospect's middle name
+    property :middle_name, :type => String, :max_length => 30
+
+    # @attribute [rw]
+    # @return [String] the prospect's last name
+    property :last_name, :type => String, :max_length => 30
+
+    # @attribute [rw]
+    # @return [String] the prospect's name suffix (e.g. 'Jr.', 'M.D.', etc.)
+    # @see RepsClient::PickListMethods#get_pick_lists
+    property :suffix, :type => String, :max_length => 30
+
+    # @attribute [rw]
+    # @return [String] the prospect's nickname
+    property :nickname, :type => String, :max_length => 30
+
+    # @attribute [rw]
+    # @return [String] the first line of the prospect's street address
+    property :address1, :type => String, :max_length => 100
+
+    # @attribute [rw]
+    # @return [String] the second line of the prospect's street address
+    property :address2, :type => String, :max_length => 100
+
+    # @attribute [rw]
+    # @return [String] the city for the prospect's mailing address
+    property :city, :type => String, :max_length => 50
+
+    # @attribute [rw]
+    # @return [String] the state code for the prospect's mailing address
+    property :state, :type => String, :max_length => 2
+
+    # @attribute [rw]
+    # @return [String] the zip code for the prospect's mailing address
+    property :zip_code, :type => String, :max_length => 10
+
+    # @attribute [rw]
+    # @return [String] the country for the prospect's mailing address
+    property :country, :type => String
+
+    # @attribute [rw]
+    # @return [String] the prospect's phone number
+    property :phone, :type => String, :max_length => 20
+
+    # @attribute [rw]
+    # @return [String] the prospect's phone extension
+    property :phone_extension, :type => String, :max_length => 5
+
+    # @attribute [rw]
+    # @return [String] the prospect's email address
+    property :email, :type => String, :max_length => 100
+
+    # @attribute [rw]
+    # @return [String] notes on the prospect (maximum 250 characters)
+    property :notes, :type => String
+
+    # @attribute [rw]
+    # @return [true,false] true if prospect opts in to mailings, false otherwise (defaults to false)
+    property :include_in_mailings, :default => false, :type => lambda { |v| !!v }
+
+    # @attribute [rw]
+    # @return [true,false] true if prospect opts in to emailings, false otherwise (defaults to false)
+    property :include_in_emailings, :default => false, :type => lambda { |v| !!v }
+
+    # @private
+    # Wrangle the model into a format that the service will accept
+    def to_soap_hash
+      hash = { :order! => [] }
+
+      [:prefix, :first_name, :middle_name, :last_name, :suffix, :nickname,
+        :address1, :address2, :city, :state, :zip_code, :country,
+        :phone, :phone_extension, :email, :notes, :include_in_mailings,
+        :include_in_emailings].each do |prop|
+        val = self.send(prop)
+        unless val.nil?
+          key = prop.to_s.camelcase
+          hash[key] = val
+          hash[:order!] << key
+        end
+      end
+
+      hash
+    end
+  end
+
+  module LeadMethods
+    include Modelish::Validations
+
+    # Submit a new lead to the remote REPS service.
+    # Each lead must have a contact and community_id.
+    #
+    # @param [Integer] community_id the REPS ID of the community
+    # @param [RepsClient::Contact] contact the contact person for the lead
+    # @param [RepsClient::Prospect] prospect the prospective resident (if different than contact)
+    #
+    def save_lead(community_id,contact,prospect=nil)
+      LeadMethods.validate_required!(:community_id => community_id,
+                                     :contact => contact)
+      LeadMethods.validate_type!(:community_id, community_id, Integer)
+
+      contact.validate!
+      soap_params = {:community_id => community_id,
+                     :new_contact => contact.to_soap_hash,
+                     :order! => [:enterprise_key, :community_id, :new_contact] }
+      if prospect
+        prospect.validate!
+        soap_params[:new_prospect] = prospect.to_soap_hash
+        soap_params[:order!] << :new_prospect
+      end
+
+      send_soap_request(:save_lead, soap_params)
+    end
+  end
+end