tlconnor-xero_gateway 1.0.3 → 1.0.4

data/lib/xero_gateway/contact.rb

@@ -2,12 +2,29 @@ module XeroGateway
   class Contact
     include Dates
     
-    attr_accessor :contact_id, :contact_number, :status, :name, :email, :addresses, :phones, :updated_at
+    class Error < RuntimeError; end
+    class NoGatewayError < Error; end
+    
+    GUID_REGEX = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/ unless defined?(GUID_REGEX)
+    
+    CONTACT_STATUS = {
+      'ACTIVE' =>     'Active',
+      'DELETED' =>    'Deleted'
+    } unless defined?(CONTACT_STATUS)
+            
+    # Xero::Gateway associated with this contact.
+    attr_accessor :gateway
     
+    # Any errors that occurred when the #valid? method called.
+    attr_reader :errors
+    
+    attr_accessor :contact_id, :contact_number, :status, :name, :email, :addresses, :phones, :updated_at
+        
     def initialize(params = {})
+      @errors ||= []
+
       params = {}.merge(params)      
       params.each do |k,v|
-        self.instance_variable_set("@#{k}", v)  ## create and initialize an instance variable for this key/value pair
         self.send("#{k}=", v)
       end
 
@@ -23,6 +40,21 @@ module XeroGateway
       self.addresses[0] ||= Address.new
     end
     
+    # Helper method to add a new address object to this contact.
+    #
+    # Usage:
+    #  contact.add_address({
+    #    :address_type =>   'STREET',
+    #    :line_1 =>         '100 Queen Street',
+    #    :city =>           'Brisbane',
+    #    :region =>         'QLD',
+    #    :post_code =>      '4000',
+    #    :country =>        'Australia'
+    #  })
+    def add_address(address_params)
+      self.addresses << Address.new(address_params)
+    end
+    
     def phone=(phone)
       self.phones = [phone]
     end
@@ -35,45 +67,86 @@ module XeroGateway
       end
     end
     
-    def ==(other)
-      [:contact_number, :status, :name, :email, :addresses, :phones].each do |field|
-        return false if send(field) != other.send(field)
-      end
-      return true
+    # Helper method to add a new phone object to this contact.
+    #
+    # Usage:
+    #  contact.add_phone({
+    #    :phone_type =>   'MOBILE',
+    #    :number =>       '0400123123'
+    #  })
+    def add_phone(phone_params = {})
+      self.phones << Phone.new(phone_params)
     end
     
-    def to_xml
-      b = Builder::XmlMarkup.new
+    # Validate the Contact record according to what will be valid by the gateway.
+    #
+    # Usage: 
+    #  contact.valid?     # Returns true/false
+    #  
+    #  Additionally sets contact.errors array to an array of field/error.
+    def valid?
+      @errors = []
+      
+      if !contact_id.nil? && contact_id !~ GUID_REGEX
+        @errors << ['contact_id', 'must be blank or a valid Xero GUID']
+      end
+      
+      if status && !CONTACT_STATUS[status]
+        @errors << ['status', "must be one of #{CONTACT_STATUS.keys.join('/')}"]
+      end
+      
+      unless name
+        @errors << ['name', "can't be blank"]
+      end
+      
+      # Make sure all addresses are correct.
+      unless addresses.all? { | address | address.valid? }
+        @errors << ['addresses', 'at least one address is invalid']
+      end
+      
+      # Make sure all phone numbers are correct.
+      unless phones.all? { | phone | phone.valid? }
+        @errors << ['phones', 'at leaset one phone is invalid']
+      end
       
+      @errors.size == 0
+    end
+    
+    # General purpose create/save method.
+    # If contact_id and contact_number are nil then create, otherwise, attempt to save.
+    def save
+      if contact_id.nil? && contact_number.nil?
+        create
+      else
+        update
+      end
+    end
+    
+    # Creates this contact record (using gateway.create_contact) with the associated gateway.
+    # If no gateway set, raise a Xero::Contact::NoGatewayError exception.
+    def create
+      raise NoGatewayError unless gateway
+      gateway.create_contact(self)
+    end
+    
+    # Creates this contact record (using gateway.update_contact) with the associated gateway.
+    # If no gateway set, raise a Xero::Contact::NoGatewayError exception.
+    def update
+      raise NoGatewayError unless gateway
+      gateway.update_contact(self)
+    end
+        
+    def to_xml(b = Builder::XmlMarkup.new)
       b.Contact {
         b.ContactID self.contact_id if self.contact_id
         b.ContactNumber self.contact_number if self.contact_number
         b.Name self.name
         b.EmailAddress self.email if self.email
         b.Addresses {
-          self.addresses.each do |address|
-            b.Address {
-              b.AddressType address.address_type
-              b.AddressLine1 address.line_1 if address.line_1
-              b.AddressLine2 address.line_2 if address.line_2
-              b.AddressLine3 address.line_3 if address.line_3
-              b.AddressLine4 address.line_4 if address.line_4
-              b.City address.city if address.city
-              b.Region address.region if address.region
-              b.PostalCode address.post_code if address.post_code
-              b.Country address.country if address.country
-            }
-          end
+          addresses.each { |address| address.to_xml(b) }
         }
         b.Phones {
-          self.phones.each do |phone|
-            b.Phone {
-              b.PhoneType phone.phone_type
-              b.PhoneNumber phone.number
-              b.PhoneAreaCode phone.area_code if phone.area_code
-              b.PhoneCountryCode phone.country_code if phone.country_code
-            }
-          end
+          phones.each { |phone| phone.to_xml(b) }
         }
       }
     end
@@ -88,44 +161,19 @@ module XeroGateway
           when "ContactStatus" then contact.status = element.text
           when "Name" then contact.name = element.text
           when "EmailAddress" then contact.email = element.text
-          when "Addresses" then element.children.each {|address| contact.addresses << parse_address(address)}
-          when "Phones" then element.children.each {|phone| contact.phones << parse_phone(phone)}
+          when "Addresses" then element.children.each {|address_element| contact.addresses << Address.from_xml(address_element)}
+          when "Phones" then element.children.each {|phone_element| contact.phones << Phone.from_xml(phone_element)}
         end
       end
       contact
     end
     
-    private
-    
-    def self.parse_address(address_element)
-      address = Address.new
-      address_element.children.each do |element|
-        case(element.name)
-          when "AddressType" then address.address_type = element.text
-          when "AddressLine1" then address.line_1 = element.text
-          when "AddressLine2" then address.line_2 = element.text
-          when "AddressLine3" then address.line_3 = element.text
-          when "AddressLine4" then address.line_4 = element.text        
-          when "City" then address.city = element.text
-          when "Region" then address.region = element.text
-          when "PostalCode" then address.post_code = element.text
-          when "Country" then address.country = element.text
-        end
-      end
-      address
-    end
-    
-    def self.parse_phone(phone_element)
-      phone = Phone.new
-      phone_element.children.each do |element|
-        case(element.name)
-          when "PhoneType" then phone.phone_type = element.text
-          when "PhoneNumber" then phone.number = element.text
-          when "PhoneAreaCode" then phone.area_code = element.text
-          when "PhoneCountryCode" then phone.country_code = element.text      
-        end
+    def ==(other)
+      [:contact_number, :status, :name, :email, :addresses, :phones].each do |field|
+        return false if send(field) != other.send(field)
       end
-      phone
+      return true
     end    
+        
   end
 end

data/lib/xero_gateway/error.rb

@@ -4,7 +4,6 @@ module XeroGateway
     
     def initialize(params = {})
       params.each do |k,v|
-        self.instance_variable_set("@#{k}", v)  ## create and initialize an instance variable for this key/value pair
         self.send("#{k}=", v)
       end
     end
@@ -16,4 +15,4 @@ module XeroGateway
       return true
     end
   end
-end
+end

data/lib/xero_gateway/gateway.rb

@@ -35,6 +35,15 @@ module XeroGateway
       get_contact(nil, contact_number)
     end
     
+    # Factory method for building new Contact objects associated with this gateway.
+    def build_contact(contact = {})
+      case contact
+        when Contact then   contact.gateway = self
+        when Hash then      contact = Contact.new(contact.merge({:gateway => self}))
+      end
+      contact
+    end
+    
     #
     # Creates a contact in Xero
     #
@@ -54,10 +63,7 @@ module XeroGateway
     #
     # create_contact(contact)
     def create_contact(contact)
-      request_xml = contact.to_xml
-      response_xml = http_put("#{@xero_url}/contact", request_xml, {})
-
-      parse_response(response_xml, :request_xml => request_xml)
+      save_contact(contact)
     end
     
     #
@@ -71,13 +77,9 @@ module XeroGateway
     # xero_gateway.update_contact(contact)  
     def update_contact(contact)
       raise "contact_id or contact_number is required for updating contacts" if contact.contact_id.nil? and contact.contact_number.nil?
-      
-      request_xml = contact.to_xml
-      response_xml = http_post("#{@xero_url}/contact", request_xml, {})
-
-      parse_response(response_xml, :request_xml => request_xml)
+      save_contact(contact)
     end
-
+    
     # Retrieves an invoice from Xero based on its GUID
     #
     # Usage : get_invoice_by_id("8c69117a-60ae-4d31-9eb4-7f5a76bc4947")
@@ -103,8 +105,19 @@ module XeroGateway
 
       parse_response(response_xml, :request_params => request_params)
     end
+    
+    # Factory method for building new Invoice objects associated with this gateway.
+    def build_invoice(invoice = {})
+      case invoice
+        when Invoice then     invoice.gateway = self
+        when Hash then        invoice = Invoice.new(invoice.merge(:gateway => self))
+      end
+      invoice
+    end
   
-    # Creates an invoice in Xero based on an invoice object
+    # Creates an invoice in Xero based on an invoice object.
+    #
+    # Invoice and line item totals are calculated automatically.
     #
     # Usage : 
     #
@@ -113,10 +126,7 @@ module XeroGateway
     #      :due_date => 1.month.from_now,
     #      :invoice_number => "YOUR INVOICE NUMBER",
     #      :reference => "YOUR REFERENCE (NOT NECESSARILY UNIQUE!)",
-    #      :includes_tax => false,
-    #      :sub_total => 1000,
-    #      :total_tax => 125,
-    #      :total => 1125
+    #      :includes_tax => false
     #    })
     #    invoice.contact = XeroGateway::Contact.new(:name => "THE NAME OF THE CONTACT")
     #    invoice.contact.phone.number = "12345"
@@ -125,7 +135,6 @@ module XeroGateway
     #      :description => "THE DESCRIPTION OF THE LINE ITEM",
     #      :unit_amount => 100,
     #      :tax_amount => 12.5,
-    #      :line_amount => 125,
     #      :tracking_category => "THE TRACKING CATEGORY FOR THE LINE ITEM",
     #      :tracking_option => "THE TRACKING OPTION FOR THE LINE ITEM"
     #    )
@@ -135,7 +144,10 @@ module XeroGateway
       request_xml = invoice.to_xml
       response_xml = http_put("#{@xero_url}/invoice", request_xml)
 
-      parse_response(response_xml, :request_xml => request_xml)
+      response = parse_response(response_xml, :request_xml => request_xml)
+      invoice.invoice_id = response.invoice.invoice_id if response.invoice && response.invoice.invoice_id
+      
+      response
     end
 
     #
@@ -145,6 +157,14 @@ module XeroGateway
       response_xml = http_get("#{xero_url}/accounts")
       parse_response(response_xml)
     end
+    
+    #
+    # Returns a XeroGateway::AccountsList object that makes working with
+    # the Xero list of accounts easier and allows caching the results.
+    #
+    def get_accounts_list(load_on_init = true)
+      AccountsList.new(self, load_on_init)
+    end
 
     #
     # Gets all tracking categories for a specific organization in Xero.
@@ -170,6 +190,24 @@ module XeroGateway
 
       parse_response(response_xml, :request_params => request_params)
     end
+    
+    # Create or update a contact record based on if it has a contact_id or contact_number.
+    def save_contact(contact)
+      request_xml = contact.to_xml
+      
+      response_xml = nil
+      if contact.contact_id.nil? && contact.contact_number.nil?
+        # Create new contact record.
+        response_xml = http_put("#{@xero_url}/contact", request_xml, {})
+      else
+        # Update existing contact record.
+        response_xml = http_post("#{@xero_url}/contact", request_xml, {})
+      end
+
+      response = parse_response(response_xml, :request_xml => request_xml)
+      contact.contact_id = response.contacts.contact_id if response.contacts && response.contacts.contact_id
+      response
+    end
 
     def parse_response(response_xml, request = {})
       doc = REXML::Document.new(response_xml)

data/lib/xero_gateway/http.rb

@@ -2,58 +2,54 @@ module XeroGateway
   module Http
     OPEN_TIMEOUT = 10 unless defined? OPEN_TIMEOUT
     READ_TIMEOUT = 60 unless defined? READ_TIMEOUT
-
+    ROOT_CA_FILE = File.join(File.dirname(__FILE__), 'ca-certificates.crt') unless defined? ROOT_CA_FILE
+    
     def http_get(url, extra_params = {})
-      params = {:apiKey => @api_key, :xeroKey => @customer_key}
-      params = params.merge(extra_params).map {|key,value| "#{key}=#{CGI.escape(value.to_s)}"}.join("&")
-
-      uri   = URI.parse(url + "?" + params)
-
-      http = Net::HTTP.new(uri.host, uri.port) 
-      http.open_timeout = OPEN_TIMEOUT
-      http.read_timeout = READ_TIMEOUT
-      http.use_ssl      = true
-      http.verify_mode    = OpenSSL::SSL::VERIFY_NONE
-
-      http.get(uri.request_uri).body
+      http_request(:get, url, nil, extra_params)
     end
 
     def http_post(url, body, extra_params = {})
-      headers = {}
-      headers['Content-Type'] ||= "application/x-www-form-urlencoded"      
-
-      params = {:apiKey => @api_key, :xeroKey => @customer_key}
-      params = params.merge(extra_params).map {|key,value| "#{key}=#{CGI.escape(value.to_s)}"}.join("&")
-
-      uri   = URI.parse(url + "?" + params)
-
-      http = Net::HTTP.new(uri.host, uri.port) 
-      http.open_timeout = OPEN_TIMEOUT
-      http.read_timeout = READ_TIMEOUT
-      http.use_ssl      = true
-
-      http.verify_mode    = OpenSSL::SSL::VERIFY_NONE
-
-      http.post(uri.request_uri, body, headers).body
+      http_request(:post, url, body, extra_params)
     end
 
     def http_put(url, body, extra_params = {})
-      headers = {}
-      headers['Content-Type'] ||= "application/x-www-form-urlencoded"      
-
-      params = {:apiKey => @api_key, :xeroKey => @customer_key}
-      params = params.merge(extra_params).map {|key,value| "#{key}=#{CGI.escape(value.to_s)}"}.join("&")
-
-      uri   = URI.parse(url + "?" + params)
-
-      http = Net::HTTP.new(uri.host, uri.port) 
-      http.open_timeout = OPEN_TIMEOUT
-      http.read_timeout = READ_TIMEOUT
-      http.use_ssl      = true
-
-      http.verify_mode    = OpenSSL::SSL::VERIFY_NONE
-
-      http.put(uri.request_uri, body, headers).body    
-    end      
+      http_request(:put, url, body, extra_params)
+    end
+    
+    private
+    
+      def http_request(method, url, body, extra_params = {})
+        headers = {} 
+
+        if method != :get
+         headers['Content-Type'] ||= "application/x-www-form-urlencoded"
+        end
+
+        params = {:apiKey => @api_key, :xeroKey => @customer_key}
+        params = params.merge(extra_params).map {|key,value| "#{CGI.escape(key.to_s)}=#{CGI.escape(value.to_s)}"}.join("&")
+
+        uri   = URI.parse(url + "?" + params)
+
+        # Only setup @cached_http once on first use as loading the CA file is quite expensive computationally.
+        unless @cached_http && @cached_http.address == uri.host && @cached_http.port == uri.port
+          @cached_http = Net::HTTP.new(uri.host, uri.port) 
+          @cached_http.open_timeout = OPEN_TIMEOUT
+          @cached_http.read_timeout = READ_TIMEOUT
+          @cached_http.use_ssl      = true
+
+          # Need to validate server's certificate against root certificate authority to prevent man-in-the-middle attacks.
+          @cached_http.ca_file        = ROOT_CA_FILE
+          # http.verify_mode    = OpenSSL::SSL::VERIFY_NONE
+          @cached_http.verify_mode    = OpenSSL::SSL::VERIFY_PEER
+          @cached_http.verify_depth   = 5
+        end
+
+        case method
+          when :get   then    @cached_http.get(uri.request_uri, headers).body
+          when :post  then    @cached_http.post(uri.request_uri, body, headers).body
+          when :put   then    @cached_http.put(uri.request_uri, body, headers).body
+        end
+      end
+       
   end
 end