xero_gateway 2.3.0 → 2.4.0

data/lib/xero_gateway/contact.rb

@@ -1,45 +1,46 @@
 module XeroGateway
   class Contact
     include Dates
-        
+
     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, :first_name, :last_name, :email, :addresses, :phones, :updated_at,
+
+    attr_accessor :contact_id, :contact_number, :account_number, :status, :name, :first_name, :last_name, :email, :addresses, :phones, :updated_at,
                   :bank_account_details, :tax_number, :accounts_receivable_tax_type, :accounts_payable_tax_type, :is_customer, :is_supplier,
                   :default_currency, :contact_groups
 
-        
+
     def initialize(params = {})
       @errors ||= []
 
-      params = {}.merge(params)      
+      params = {}.merge(params)
       params.each do |k,v|
         self.send("#{k}=", v)
       end
 
       @phones ||= []
-      @addresses ||= []
+      @addresses ||= nil
     end
-    
+
     def address=(address)
       self.addresses = [address]
     end
-    
+
     def address
+      self.addresses    ||= []
       self.addresses[0] ||= Address.new
     end
-    
+
     # Helper method to add a new address object to this contact.
     #
     # Usage:
@@ -54,11 +55,11 @@ module XeroGateway
     def add_address(address_params)
       self.addresses << Address.new(address_params)
     end
-    
+
     def phone=(phone)
       self.phones = [phone]
     end
-    
+
     def phone
       if @phones.size > 1
         @phones.detect {|p| p.phone_type == 'DEFAULT'} || phones[0]
@@ -66,7 +67,7 @@ module XeroGateway
         @phones[0] ||= Phone.new
       end
     end
-    
+
     # Helper method to add a new phone object to this contact.
     #
     # Usage:
@@ -77,41 +78,41 @@ module XeroGateway
     def add_phone(phone_params = {})
       self.phones << Phone.new(phone_params)
     end
-    
+
     # Validate the Contact record according to what will be valid by the gateway.
     #
-    # Usage: 
+    # 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 least 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
@@ -121,25 +122,26 @@ module XeroGateway
         update
       end
     end
-    
+
     # Creates this contact record (using gateway.create_contact) with the associated gateway.
     # If no gateway set, raise a 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 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.AccountNumber self.account_number if self.account_number
         b.Name self.name if self.name
         b.EmailAddress self.email if self.email
         b.FirstName self.first_name if self.first_name
@@ -154,13 +156,13 @@ module XeroGateway
         b.DefaultCurrency if self.default_currency
         b.Addresses {
           addresses.each { |address| address.to_xml(b) }
-        } if self.addresses.any?
+        } unless addresses.nil?
         b.Phones {
           phones.each { |phone| phone.to_xml(b) }
         } if self.phones.any?
       }
     end
-    
+
     # Take a Contact element and convert it into an Contact object
     def self.from_xml(contact_element, gateway = nil)
       contact = Contact.new(:gateway => gateway)
@@ -168,15 +170,14 @@ module XeroGateway
         case(element.name)
           when "ContactID" then contact.contact_id = element.text
           when "ContactNumber" then contact.contact_number = element.text
+          when "AccountNumber" then contact.account_number = element.text
           when "ContactStatus" then contact.status = element.text
           when "Name" then contact.name = element.text
           when "FirstName" then contact.first_name = element.text
           when "LastName" then contact.last_name = element.text
           when "EmailAddress" then contact.email = element.text
-          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)}
-          when "FirstName" then contact.first_name = element.text
-          when "LastName"  then contact.last_name  = element.text
+          when "Addresses" then element.children.each { |address_element| contact.addresses ||= []; contact.addresses << Address.from_xml(address_element) }
+          when "Phones" then element.children.each { |phone_element| contact.phones << Phone.from_xml(phone_element) }
           when "BankAccountDetails" then contact.bank_account_details = element.text
           when "TaxNumber" then contact.tax_number = element.text
           when "AccountsReceivableTaxType" then contact.accounts_receivable_tax_type = element.text
@@ -185,19 +186,20 @@ module XeroGateway
           when "IsCustomer" then contact.is_customer = (element.text == "true")
           when "IsSupplier" then contact.is_supplier = (element.text == "true")
           when "DefaultCurrency" then contact.default_currency = element.text
+          when "UpdatedDateUTC" then contact.updated_at = parse_date_time(element.text)
         end
       end
       contact
     end
-    
+
     def ==(other)
-      [ :contact_id, :contact_number, :status, :name, :first_name, :last_name, :email, :addresses, :phones, :updated_at,
+      [ :contact_id, :contact_number, :account_number, :status, :name, :first_name, :last_name, :email, :addresses, :phones, :updated_at,
         :bank_account_details, :tax_number, :accounts_receivable_tax_type, :accounts_payable_tax_type, :is_customer, :is_supplier,
         :default_currency, :contact_groups ].each do |field|
         return false if send(field) != other.send(field)
       end
       return true
-    end    
-        
+    end
+
   end
 end

data/lib/xero_gateway/contact_group.rb

@@ -1,20 +1,22 @@
 module XeroGateway
   class ContactGroup
-    
+
     # Xero::Gateway associated with this invoice.
     attr_accessor :gateway
-    
+
     # All accessible fields
-    attr_accessor :contact_group_id, :name, :status, :contacts
-    
+    attr_accessor :contact_group_id, :name, :status
+    attr_writer   :contacts
+
     # Boolean representing whether the accounts list has been loaded.
     attr_accessor :contacts_downloaded
-    
+
     def initialize(params = {})
       @contacts = []
       params.each do |k,v|
         self.send("#{k}=", v)
       end
+      @contacts_downloaded = (params.delete(:contacts_downloaded) == true)
     end
 
     # Return the list of Contacts. Will load the contacts if the group
@@ -32,11 +34,11 @@ module XeroGateway
       @contacts
     end
 
-    # Returns the array of ContactIDs. 
+    # Returns the array of ContactIDs.
     # If the contact_ids array has been assigned, will return that array.
     # Otherwise, returns any loaded ContactIDs
     def contact_ids
-      if @contact_ids
+      if defined?(@contact_ids)
         @contact_ids
       else
         contacts.map(&:contact_id)
@@ -80,8 +82,8 @@ module XeroGateway
             end
         end
       end
-      contact_group              
-    end  
+      contact_group
+    end
 
   end
-end
+end

data/lib/xero_gateway/credit_note.rb

@@ -3,18 +3,18 @@ module XeroGateway
     include Dates
     include Money
     include LineItemCalculations
-    
+
     CREDIT_NOTE_TYPE = {
       'ACCRECCREDIT' =>           'Accounts Receivable',
       'ACCPAYCREDIT' =>           'Accounts Payable'
     } unless defined?(CREDIT_NOTE_TYPE)
-    
+
     LINE_AMOUNT_TYPES = {
       "Inclusive" =>        'CreditNote lines are inclusive tax',
       "Exclusive" =>        'CreditNote lines are exclusive of tax (default)',
       "NoTax"     =>        'CreditNotes lines have no tax'
     } unless defined?(LINE_AMOUNT_TYPES)
-    
+
     CREDIT_NOTE_STATUS = {
       'AUTHORISED' =>       'Approved credit_notes awaiting payment',
       'DELETED' =>          'Draft credit_notes that are deleted',
@@ -23,53 +23,53 @@ module XeroGateway
       'SUBMITTED' =>        'CreditNotes entered by an employee awaiting approval',
       'VOID' =>             'Approved credit_notes that are voided'
     } unless defined?(CREDIT_NOTE_STATUS)
-    
+
     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)
-        
+
     # Xero::Gateway associated with this credit_note.
     attr_accessor :gateway
-    
+
     # Any errors that occurred when the #valid? method called.
     attr_reader :errors
 
     # Represents whether the line_items have been downloaded when getting from GET /API.XRO/2.0/CreditNotes
     attr_accessor :line_items_downloaded
-  
+
     # All accessible fields
-    attr_accessor :credit_note_id, :credit_note_number, :type, :status, :date, :reference, :line_amount_types, :currency_code, :line_items, :contact, :payments, :fully_paid_on, :amount_credited
+    attr_accessor :credit_note_id, :credit_note_number, :type, :status, :date, :reference, :line_amount_types, :currency_code, :payments, :fully_paid_on, :amount_credited
+    attr_writer :line_items, :contact
 
-    
     def initialize(params = {})
       @errors ||= []
       @payments ||= []
-      
+
       # Check if the line items have been downloaded.
       @line_items_downloaded = (params.delete(:line_items_downloaded) == true)
-      
+
       params = {
         :line_amount_types => "Inclusive"
       }.merge(params)
-      
+
       params.each do |k,v|
         self.send("#{k}=", v)
       end
-      
+
       @line_items ||= []
     end
-    
+
     # Validate the Address record according to what will be valid by the gateway.
     #
-    # Usage: 
+    # Usage:
     #  address.valid?     # Returns true/false
-    #  
+    #
     #  Additionally sets address.errors array to an array of field/error.
     def valid?
       @errors = []
-      
+
       if !credit_note_id.nil? && credit_note_id !~ GUID_REGEX
         @errors << ['credit_note_id', 'must be blank or a valid Xero GUID']
       end
-            
+
       if status && !CREDIT_NOTE_STATUS[status]
         @errors << ['status', "must be one of #{CREDIT_NOTE_STATUS.keys.join('/')}"]
       end
@@ -77,99 +77,93 @@ module XeroGateway
       if line_amount_types && !LINE_AMOUNT_TYPES[line_amount_types]
         @errors << ['line_amount_types', "must be one of #{LINE_AMOUNT_TYPES.keys.join('/')}"]
       end
-      
+
       unless date
         @errors << ['credit_note_date', "can't be blank"]
       end
-      
+
       # Make sure contact is valid.
       unless @contact && @contact.valid?
         @errors << ['contact', 'is invalid']
       end
-      
+
       # Make sure all line_items are valid.
       unless line_items.all? { | line_item | line_item.valid? }
         @errors << ['line_items', "at least one line item invalid"]
       end
-      
+
       @errors.size == 0
     end
-    
+
     # Helper method to create the associated contact object.
     def build_contact(params = {})
       self.contact = gateway ? gateway.build_contact(params) : Contact.new(params)
     end
-    
+
     def contact
       @contact ||= build_contact
     end
-    
+
     # Helper method to check if the credit_note is accounts payable.
     def accounts_payable?
       type == 'ACCPAYCREDIT'
     end
-    
+
     # Helper method to check if the credit_note is accounts receivable.
     def accounts_receivable?
       type == 'ACCRECCREDIT'
     end
-    
+
     # Whether or not the line_items have been downloaded (GET/credit_notes does not download line items).
     def line_items_downloaded?
       @line_items_downloaded
     end
-    
+
     # If line items are not downloaded, then attempt a download now (if this record was found to begin with).
     def line_items
       if line_items_downloaded?
         @line_items
-        
+
       # There is an credit_note_is so we can assume this record was loaded from Xero.
       # attempt to download the line_item records.
       elsif credit_note_id =~ GUID_REGEX
         raise NoGatewayError unless @gateway
-        
+
         response = @gateway.get_credit_note(credit_note_id)
         raise CreditNoteNotFoundError, "CreditNote with ID #{credit_note_id} not found in Xero." unless response.success? && response.credit_note.is_a?(XeroGateway::CreditNote)
-        
+
         @line_items = response.credit_note.line_items
         @line_items_downloaded = true
-        
+
         @line_items
-        
+
       # Otherwise, this is a new credit_note, so return the line_items reference.
       else
         @line_items
       end
     end
-    
+
     def ==(other)
       ["credit_note_number", "type", "status", "reference", "currency_code", "line_amount_types", "contact", "line_items"].each do |field|
         return false if send(field) != other.send(field)
       end
-      
+
       ["date"].each do |field|
         return false if send(field).to_s != other.send(field).to_s
       end
       return true
     end
-    
-    # General purpose createsave method.
-    # If contact_id and contact_number are nil then create, otherwise, attempt to save.
-    def save
-      create
-    end
-    
+
     # Creates this credit_note record (using gateway.create_credit_note) with the associated gateway.
     # If no gateway set, raise a NoGatewayError exception.
     def create
       raise NoGatewayError unless gateway
       gateway.create_credit_note(self)
     end
-    
+
     # Alias create as save as this is currently the only write action.
     alias_method :save, :create
-            
+
     def to_xml(b = Builder::XmlMarkup.new)
       b.CreditNote {
         b.Type self.type
@@ -187,14 +181,14 @@ module XeroGateway
         }
       }
     end
-    
+
     #TODO UpdatedDateUTC
     def self.from_xml(credit_note_element, gateway = nil, options = {})
       credit_note = CreditNote.new(options.merge({:gateway => gateway}))
       credit_note_element.children.each do |element|
         case(element.name)
           when "CreditNoteID" then credit_note.credit_note_id = element.text
-          when "CreditNoteNumber" then credit_note.credit_note_number = element.text            
+          when "CreditNoteNumber" then credit_note.credit_note_number = element.text
           when "Type" then credit_note.type = element.text
           when "CurrencyCode" then credit_note.currency_code = element.text
           when "Contact" then credit_note.contact = Contact.from_xml(element)
@@ -206,15 +200,13 @@ module XeroGateway
           when "SubTotal" then credit_note.sub_total = BigDecimal.new(element.text)
           when "TotalTax" then credit_note.total_tax = BigDecimal.new(element.text)
           when "Total" then credit_note.total = BigDecimal.new(element.text)
-          when "CreditNoteID" then credit_note.credit_note_id = element.text
-          when "CreditNoteNumber" then credit_note.credit_note_number = element.text            
           when "Payments" then element.children.each { | payment | credit_note.payments << Payment.from_xml(payment) }
           when "AmountDue" then credit_note.amount_due = BigDecimal.new(element.text)
           when "AmountPaid" then credit_note.amount_paid = BigDecimal.new(element.text)
           when "AmountCredited" then credit_note.amount_credited = BigDecimal.new(element.text)
         end
-      end      
+      end
       credit_note
-    end    
+    end
   end
 end

data/lib/xero_gateway/gateway.rb

@@ -147,7 +147,7 @@ module XeroGateway
     # Retreives a contact group by its id.
     def get_contact_group_by_id(contact_group_id)
       request_params = { :ContactGroupID => contact_group_id }
-      response_xml = http_get(@client, "#{@xero_url}/ContactGroups/#{URI.escape(contact_group_id)}", request_params)
+      response_xml = http_get(@client, "#{@xero_url}/ContactGroups/#{CGI.escape(contact_group_id)}", request_params)
 
       parse_response(response_xml, {:request_params => request_params}, {:request_signature => 'GET/contactgroup'})
     end
@@ -155,7 +155,9 @@ module XeroGateway
     # Retrieves all invoices from Xero
     #
     # Usage : get_invoices
-    #         get_invoices(:invoice_id => " 297c2dc5-cc47-4afd-8ec8-74990b8761e9")
+    #         get_invoices(:invoice_id => "297c2dc5-cc47-4afd-8ec8-74990b8761e9")
+    #         get_invoices(:invoice_number => "175")
+    #         get_invoices(:contact_ids => ["297c2dc5-cc47-4afd-8ec8-74990b8761e9"] )
     #
     # Note  : modified_since is in UTC format (i.e. Brisbane is UTC+10)
     def get_invoices(options = {})
@@ -166,6 +168,7 @@ module XeroGateway
       request_params[:InvoiceNumber] = options[:invoice_number] if options[:invoice_number]
       request_params[:order]         = options[:order] if options[:order]
       request_params[:ModifiedAfter] = options[:modified_since] if options[:modified_since]
+      request_params[:ContactIDs]    = Array(options[:contact_ids]).join(",") if options[:contact_ids]
 
       request_params[:where]         = options[:where] if options[:where]
 
@@ -186,7 +189,7 @@ module XeroGateway
 
       headers.merge!("Accept" => "application/pdf") if format == :pdf
 
-      url  = "#{@xero_url}/Invoices/#{URI.escape(invoice_id_or_number)}"
+      url  = "#{@xero_url}/Invoices/#{CGI.escape(invoice_id_or_number)}"
 
       response = http_get(@client, url, request_params, headers)
 
@@ -306,7 +309,7 @@ module XeroGateway
     def get_credit_note(credit_note_id_or_number)
       request_params = {}
 
-      url  = "#{@xero_url}/CreditNotes/#{URI.escape(credit_note_id_or_number)}"
+      url  = "#{@xero_url}/CreditNotes/#{CGI.escape(credit_note_id_or_number)}"
 
       response_xml = http_get(@client, url, request_params)
 
@@ -453,7 +456,7 @@ module XeroGateway
     #         get_bank_transaction("OIT-12345") # By number
     def get_bank_transaction(bank_transaction_id)
       request_params = {}
-      url = "#{@xero_url}/BankTransactions/#{URI.escape(bank_transaction_id)}"
+      url = "#{@xero_url}/BankTransactions/#{CGI.escape(bank_transaction_id)}"
       response_xml = http_get(@client, url, request_params)
       parse_response(response_xml, {:request_params => request_params}, {:request_signature => 'GET/BankTransaction'})
     end
@@ -503,7 +506,7 @@ module XeroGateway
     #         get_manual_journal("OIT-12345") # By number
     def get_manual_journal(manual_journal_id)
       request_params = {}
-      url = "#{@xero_url}/ManualJournals/#{URI.escape(manual_journal_id)}"
+      url = "#{@xero_url}/ManualJournals/#{CGI.escape(manual_journal_id)}"
       response_xml = http_get(@client, url, request_params)
       parse_response(response_xml, {:request_params => request_params}, {:request_signature => 'GET/ManualJournal'})
     end
@@ -621,7 +624,7 @@ module XeroGateway
 
     def get_contact(contact_id = nil, contact_number = nil)
       request_params = contact_id ? { :contactID => contact_id } : { :contactNumber => contact_number }
-      response_xml = http_get(@client, "#{@xero_url}/Contacts/#{URI.escape(contact_id||contact_number)}", request_params)
+      response_xml = http_get(@client, "#{@xero_url}/Contacts/#{CGI.escape(contact_id||contact_number)}", request_params)
 
       parse_response(response_xml, {:request_params => request_params}, {:request_signature => 'GET/contact'})
     end