xero_gateway 2.5.0 → 2.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 9c288d4d30be0c8ce139ffd5b3c714f077835e47
-  data.tar.gz: b09d959c33ebacbf10a98509e59cf8e19d53b1f1
+  metadata.gz: 15bce269e603d39203dbafb5858843c8e8fe8b3e
+  data.tar.gz: a996fa84e4ca2471b3efc06eb68c080fbe4ed8cb
 SHA512:
-  metadata.gz: 56dc6a1fc73e3ad5118caa9c10662a64dafeef89e902dc9080053953042cd571895379622be61126c4ecfaeb79c99b5712e14230948aac614ae04dfc0dcc3800
-  data.tar.gz: d3906629a8c6acc8856ac23f3fb1e7f91fca06b9ad22d51d3feb6d455b69ef61cec9381deb8861530c9d860d65b8c5054c30638432e3efa895d3871a7aa20986
+  metadata.gz: 57f8ec61dbe74dcd7fb6fbdb4a2f65087079e2f4808bc8a08696e445d6f91b2b9ec4661ca557029041b1ffe35a11e3b2f49f42faf458c9b42c4bacad77b02cca
+  data.tar.gz: 4a203e5a9a76a0146c758249126bc595946422960d4cb37a056fb9607e0e5ad1493d336f5b24ad02a87076875a41b5dfd2ed09c3cc51f5d14b27caccb9158045

data/README.md

@@ -26,19 +26,19 @@ The Xero Gateway uses [OAuth 1.0a](https://oauth.net/core/1.0a/) for authenticat
 implements OAuth in a very similar manner to the [Twitter gem by John Nunemaker](http://github.com/jnunemaker/twitter)
 , so if you've used that before this will all seem familiar.
 
-### Authenticating: Public/Partner Applications
+### Authenticating: Public Applications
 
-Public (or Partner, if you've been through the process to be approved) are traditional three-legged OAuth apps that can be used to access many different Xero accounts.
+Public are traditional three-legged OAuth apps that can be used to access many different Xero accounts.
 
   1. **Get a Consumer Key & Secret**
 
   First off, you'll need to get a Consumer Key/Secret pair for your application from Xero.
 
-  Head to <https://api.xero.com>, log in and then click My Applications &gt; Add Application.
+  Head to <https://developer.xero.com/myapps>, log in and then click New Application.
 
-  Part of the process for this will ask you for an "OAuth Redirect URL". This is where customers will be redirected once they complete logging in with Xero.
+  Part of the process for this will ask you for an "OAuth Callback Domain". This is the domain where customers will be redirected once they complete logging in with Xero.
 
-  On the right-hand-side of your application's page there's a box titled "OAuth Credentials". Use the Key and Secret from this box in order to set up a new Gateway instance.
+  Further down in your application's page there's a box titled "App Credentials". Use the Key and Secret from this box in order to set up a new Gateway instance.
 
   2. **Create a Xero Gateway in your App**
 
@@ -106,7 +106,7 @@ Public (or Partner, if you've been through the process to be approved) are tradi
     gateway.authorize_from_access(your_stored_token.access_token, your_stored_token.access_secret)
   ```
 
- ### Authenticating: Private Applications
+### Authenticating: Private Applications
 
 Private applications are used to access a single Xero account.
 
@@ -117,8 +117,8 @@ Private applications are used to access a single Xero account.
   You'll need to generate an RSA keypair and an X509 certificate. This can be done with OpenSSL as below:
 
   ```bash
-    openssl genrsa -out privatekey.pem
-    openssl req -newkey rsa:1024 -x509 -days 365 -in privatekey.pem -out publickey.cer
+    openssl genrsa -out privatekey.pem 1024
+    openssl req -new -x509 -key privatekey.pem -out publickey.cer -days 1825
   ```
 
   You can then copy `publickey.cer` and paste it into the certificate box (`cat publickey.cer | pbcopy` on a Mac :apple:)
@@ -138,13 +138,28 @@ Private applications are used to access a single Xero account.
 
   Note that for private apps, your consumer key and secret do double duty as your access token and secret pair :)
 
+### Authenticating: Partner Applications
+  
+Partner applications are public applications that have been upgraded to support long-term access tokens.
+
+Use the same three-legged authentication process as for public applications, but with an RSA keypair and an X509 certificate as for private applications:
+
+  ```ruby
+    require 'xero_gateway'
+    gateway = XeroGateway::PartnerApp.new(YOUR_OAUTH_CONSUMER_KEY, YOUR_OAUTH_CONSUMER_SECRET, PATH_TO_YOUR_PRIVATE_KEY)
+
+    pp gateway.get_contacts
+  ```
+
+For more information on partner applications see the Xero documentation: <https://developer.xero.com/documentation/auth-and-limits/partner-applications>  
+  
 ## Examples
 
 Open `examples/oauth.rb` and change `CONSUMER_KEY` and `CONSUMER_SECRET` to
 the values for a Test OAuth Public Application in order to see an example of
 OAuth at work.
 
-There's also `examples/private_app.rb` if you'd like to see an example private app.
+See also `examples/private_app.rb` for an example private app or `examples/partner_app.rb` for an example partner app.
 
 If you're working with Rails, a controller similar to this might come in
 handy:

data/lib/xero_gateway.rb

@@ -24,8 +24,11 @@ require File.join(File.dirname(__FILE__), 'xero_gateway', 'accounts_list')
 require File.join(File.dirname(__FILE__), 'xero_gateway', 'tracking_category')
 require File.join(File.dirname(__FILE__), 'xero_gateway', 'contact')
 require File.join(File.dirname(__FILE__), 'xero_gateway', 'contact_group')
+require File.join(File.dirname(__FILE__), 'xero_gateway', 'contact_person')
 require File.join(File.dirname(__FILE__), 'xero_gateway', 'line_item')
 require File.join(File.dirname(__FILE__), 'xero_gateway', 'payment')
+require File.join(File.dirname(__FILE__), 'xero_gateway', 'payroll_calendar')
+require File.join(File.dirname(__FILE__), 'xero_gateway', 'pay_run')
 require File.join(File.dirname(__FILE__), 'xero_gateway', 'invoice')
 require File.join(File.dirname(__FILE__), 'xero_gateway', 'bank_transaction')
 require File.join(File.dirname(__FILE__), 'xero_gateway', 'credit_note')

data/lib/xero_gateway/base_record.rb

@@ -76,9 +76,13 @@ module XeroGateway
       end
 
       value = case attr_definition
-        when :boolean  then  element.text == "true"
-        when :float    then  element.text.to_f
-        when :integer  then  element.text.to_i
+        when :boolean      then  element.text == "true"
+        when :float        then  element.text.to_f
+        when :integer      then  element.text.to_i
+        when :currency     then  BigDecimal.new(element.text)
+        when :date         then  Date.strptime(element.text, "%Y-%m-%d")
+        when :datetime     then  Date.strptime(element.text, "%Y-%m-%dT%H:%M:%S")
+        when :datetime_utc then  Date.strptime(element.text + "Z", "%Y-%m-%dT%H:%M:%S%Z")
         when Array     then  array_from_xml(element, attr_definition)
         else                 element.text
       end if element.text.present? || element.children.present?

data/lib/xero_gateway/contact.rb

@@ -17,7 +17,7 @@ module XeroGateway
 
     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
+                  :default_currency, :contact_groups, :contact_persons
 
 
     def initialize(params = {})
@@ -79,6 +79,11 @@ module XeroGateway
       self.phones << Phone.new(phone_params)
     end
 
+    def add_contact_person(contact_person_params = {})
+      self.contact_persons ||= []
+      self.contact_persons << ContactPerson.new(contact_person_params)
+    end
+
     # Validate the Contact record according to what will be valid by the gateway.
     #
     # Usage:
@@ -160,6 +165,9 @@ module XeroGateway
         b.Phones {
           phones.each { |phone| phone.to_xml(b) }
         } if self.phones.any?
+        b.ContactPersons {
+          contact_persons.each { |contact_person| contact_person.to_xml(b) }
+        } unless contact_persons.nil?
       }
     end
 
@@ -187,6 +195,7 @@ module XeroGateway
           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)
+          when "ContactPersons" then element.children.each { |contact_person_element| contact.contact_persons ||= []; contact.contact_persons << ContactPerson.from_xml(contact_person_element) }
         end
       end
       contact

data/lib/xero_gateway/contact_person.rb

@@ -0,0 +1,33 @@
+module XeroGateway
+  class ContactPerson
+    attr_accessor :first_name, :last_name, :email_address, :include_in_emails
+
+    def initialize(params = {})
+      params.each do |k,v|
+        self.send("#{k}=", v)
+      end
+    end
+
+    def to_xml(b = Builder::XmlMarkup.new)
+      b.ContactPerson {
+        b.FirstName first_name if first_name
+        b.LastName last_name if last_name
+        b.EmailAddress email_address if email_address
+        b.IncludeInEmails include_in_emails if include_in_emails
+      }
+    end
+
+    def self.from_xml(contact_person_element)
+      contact_person = ContactPerson.new
+      contact_person_element.children.each do |element|
+        case(element.name)
+          when "FirstName"       then contact_person.first_name = element.text
+          when "LastName"        then contact_person.last_name = element.text
+          when "EmailAddress"    then contact_person.email_address = element.text
+          when "IncludeInEmails" then contact_person.include_in_emails = (element.text == "true")
+        end
+      end
+      contact_person
+    end
+  end
+end

data/lib/xero_gateway/gateway.rb

@@ -4,7 +4,7 @@ module XeroGateway
     include Http
     include Dates
 
-    attr_accessor :client, :xero_url, :logger
+    attr_accessor :client, :xero_url, :payroll_url, :logger
 
     extend Forwardable
     def_delegators :client, :request_token, :access_token, :authorize_from_request, :authorize_from_access, :expires_at, :authorization_expires_at
@@ -14,6 +14,7 @@ module XeroGateway
     # to you by Xero inside the API Previewer.
     def initialize(consumer_key, consumer_secret, options = {})
       @xero_url = options[:xero_url] || "https://api.xero.com/api.xro/2.0"
+      @payroll_url = options[:payroll_url] || "https://api.xero.com/payroll.xro/1.0"
       @client   = OAuth.new(consumer_key, consumer_secret, options)
     end
 
@@ -445,6 +446,7 @@ module XeroGateway
       request_params[:ModifiedAfter]      = options[:modified_since] if options[:modified_since]
       request_params[:order]              = options[:order] if options[:order]
       request_params[:where]              = options[:where] if options[:where]
+      request_params[:page]               = options[:page] if options[:page]
 
       response_xml = http_get(@client, "#{@xero_url}/BankTransactions", request_params)
 
@@ -603,10 +605,28 @@ module XeroGateway
     #
     def get_payment(payment_id, options = {})
       request_params = {}
-      response_xml = http_get(client, "#{xero_url}/Payments/#{payment_id}", request_params)
+      response_xml = http_get(client, "#{@xero_url}/Payments/#{payment_id}", request_params)
       parse_response(response_xml, {:request_params => request_params}, {:request_signature => 'GET/payments'})
     end
 
+    #
+    # Get the Payroll calendars for a specific organization in Xero
+    #
+    def get_payroll_calendars(options = {})
+      request_params = {}
+      response_xml = http_get(client, "#{@payroll_url}/PayrollCalendars", request_params)
+      parse_response(response_xml, {:request_params => request_params}, {:request_signature => 'GET/payroll_calendars'})
+    end
+
+    #
+    # Get the Pay Runs for a specific organization in Xero
+    #
+    def get_pay_runs(options = {})
+      request_params = {}
+      response_xml = http_get(client, "#{@payroll_url}/PayRuns", request_params)
+      parse_response(response_xml, {:request_params => request_params}, {:request_signature => 'GET/pay_runs'})
+    end
+
     # Retrieves reports from Xero
     #
     # Usage : get_report("BankStatement", bank_account_id: "AC993F75-035B-433C-82E0-7B7A2D40802C")
@@ -782,6 +802,8 @@ module XeroGateway
             element.children.each do |child|
               response.response_item << Payment.from_xml(child)
             end
+          when "PayrollCalendars" then element.children.each {|child| response.response_item << PayrollCalendar.from_xml(child) }
+          when "PayRuns" then element.children.each {|child| response.response_item << PayRun.from_xml(child) }
           when "Reports"
             element.children.each do |child|
               response.response_item << Report.from_xml(child)

data/lib/xero_gateway/invoice.rb

@@ -185,6 +185,7 @@ module XeroGateway
         contact.to_xml(b)
         b.Date Invoice.format_date(self.date || Date.today)
         b.DueDate Invoice.format_date(self.due_date) if self.due_date
+        b.FullyPaidOnDate Invoice.format_date(self.fully_paid_on) if self.fully_paid_on
         b.Status self.invoice_status if self.invoice_status
         b.Reference self.reference if self.reference
         b.BrandingThemeID self.branding_theme_id if self.branding_theme_id
@@ -212,6 +213,7 @@ module XeroGateway
           when "Contact" then invoice.contact = Contact.from_xml(element)
           when "Date" then invoice.date = parse_date(element.text)
           when "DueDate" then invoice.due_date = parse_date(element.text)
+          when "FullyPaidOnDate" then invoice.fully_paid_on = parse_date(element.text)
           when "UpdatedDateUTC" then invoice.updated_date_utc = parse_date(element.text)
           when "Status" then invoice.invoice_status = element.text
           when "Reference" then invoice.reference = element.text

data/lib/xero_gateway/line_item.rb

@@ -3,73 +3,75 @@ require File.join(File.dirname(__FILE__), 'account')
 module XeroGateway
   class LineItem
     include Money
-    
+
     TAX_TYPE = Account::TAX_TYPE unless defined?(TAX_TYPE)
 
     # Any errors that occurred when the #valid? method called.
     attr_reader :errors
 
     # All accessible fields
-    attr_accessor :line_item_id, :description, :quantity, :unit_amount, :item_code, :tax_type, :tax_amount, :account_code, :tracking
-        
+    attr_accessor :line_item_id, :description, :quantity, :unit_amount, :discount_rate, :item_code, :tax_type, :tax_amount, :account_code, :tracking
+
     def initialize(params = {})
       @errors ||= []
       @tracking ||= []
       @quantity = 1
       @unit_amount = BigDecimal.new('0')
-      
+
       params.each do |k,v|
         self.send("#{k}=", v)
       end
     end
-    
+
     # Validate the LineItem record according to what will be valid by the gateway.
     #
-    # Usage: 
+    # Usage:
     #  line_item.valid?     # Returns true/false
-    #  
+    #
     #  Additionally sets line_item.errors array to an array of field/error.
     def valid?
       @errors = []
-      
+
       if !line_item_id.nil? && line_item_id !~ GUID_REGEX
         @errors << ['line_item_id', 'must be blank or a valid Xero GUID']
       end
-      
+
       unless description
         @errors << ['description', "can't be blank"]
       end
-            
+
       if tax_type && !TAX_TYPE[tax_type]
         @errors << ['tax_type', "must be one of #{TAX_TYPE.keys.join('/')}"]
       end
-      
+
       @errors.size == 0
     end
-    
+
     def has_tracking?
       return false if tracking.nil?
-      
+
       if tracking.is_a?(Array)
         return tracking.any?
       else
         return tracking.is_a?(TrackingCategory)
       end
     end
-    
+
     # Deprecated (but API for setter remains).
     #
     # As line_amount must equal quantity * unit_amount for the API call to pass, this is now
     # automatically calculated in the line_amount method.
     def line_amount=(value)
     end
-    
+
     # Calculate the line_amount as quantity * unit_amount as this value must be correct
     # for the API call to succeed.
     def line_amount
-      quantity * unit_amount
+      total = quantity * unit_amount
+      total = total * (1 - (discount_rate / BigDecimal.new(100))) if discount_rate
+      total
     end
-    
+
     def to_xml(b = Builder::XmlMarkup.new)
       b.LineItem {
         b.Description description
@@ -79,6 +81,7 @@ module XeroGateway
         b.TaxType tax_type if tax_type
         b.TaxAmount tax_amount if tax_amount
         b.LineAmount line_amount if line_amount
+        b.DiscountRate discount_rate if discount_rate
         b.AccountCode account_code if account_code
         if has_tracking?
           b.Tracking {
@@ -92,7 +95,7 @@ module XeroGateway
         end
       }
     end
-    
+
     def self.from_xml(line_item_element)
       line_item = LineItem.new
       line_item_element.children.each do |element|
@@ -105,6 +108,7 @@ module XeroGateway
           when "TaxType" then line_item.tax_type = element.text
           when "TaxAmount" then line_item.tax_amount = BigDecimal.new(element.text)
           when "LineAmount" then line_item.line_amount = BigDecimal.new(element.text)
+          when "DiscountRate" then line_item.discount_rate = BigDecimal.new(element.text)
           when "AccountCode" then line_item.account_code = element.text
           when "Tracking" then
             element.children.each do | tracking_element |
@@ -113,13 +117,13 @@ module XeroGateway
         end
       end
       line_item
-    end    
+    end
 
     def ==(other)
-      [:description, :quantity, :unit_amount, :tax_type, :tax_amount, :line_amount, :account_code, :item_code].each do |field|
+      [:description, :quantity, :unit_amount, :tax_type, :tax_amount, :line_amount, :discount_rate, :account_code, :item_code].each do |field|
         return false if send(field) != other.send(field)
       end
       return true
     end
-  end  
+  end
 end

data/lib/xero_gateway/pay_run.rb

@@ -0,0 +1,19 @@
+module XeroGateway
+  class PayRun  < BaseRecord
+    attributes({
+      "PayRunID"                => :string,
+      "PayrollCalendarID"       => :string,
+      "PayRunPeriodStartDate"   => :date,
+      "PayRunPeriodEndDate"     => :date,
+      "PaymentDate"             => :date,
+      "Wages"                   => :currency,
+      "Deductions"              => :currency,
+      "Tax"                     => :currency,
+      "Super"                   => :currency,
+      "Reimbursement"           => :currency,
+      "NetPay"                  => :currency,
+      "PayRunStatus"            => :string,
+      "UpdatedDateUTC"          => :datetime_utc
+    })
+  end
+end

data/lib/xero_gateway/payroll_calendar.rb

@@ -0,0 +1,12 @@
+module XeroGateway
+  class PayrollCalendar  < BaseRecord
+    attributes({
+      "PayrollCalendarID"     => :string,
+      "Name"                  => :string,
+      "CalendarType"          => :string,
+      "StartDate"             => :date,
+      "PaymentDate"           => :date,
+      "UpdatedDateUTC"        => :datetime_utc
+    })
+  end
+end

data/lib/xero_gateway/private_app.rb

@@ -2,14 +2,15 @@ module XeroGateway
   class PrivateApp < Gateway
     #
     # The consumer key and secret here correspond to those provided
-    # to you by Xero inside the API Previewer. 
+    # to you by Xero inside the API Previewer.
     def initialize(consumer_key, consumer_secret, path_to_private_key, options = {})
       options.merge!(
         :signature_method => 'RSA-SHA1',
         :private_key_file => path_to_private_key
       )
-      
+
       @xero_url = options[:xero_url] || "https://api.xero.com/api.xro/2.0"
+      @payroll_url = options[:payroll_url] || "https://api.xero.com/payroll.xro/1.0"
       @client   = OAuth.new(consumer_key, consumer_secret, options)
       @client.authorize_from_access(consumer_key, consumer_secret)
     end

data/lib/xero_gateway/report.rb

@@ -1,5 +1,9 @@
+require_relative './report/cell'
+require_relative './report/row'
+
 module XeroGateway
   class Report
+
     include Money
     include Dates
 
@@ -7,6 +11,8 @@ module XeroGateway
     attr_accessor :report_id, :report_name, :report_type, :report_titles, :report_date, :updated_at,
                   :body, :column_names
 
+    alias :rows :body
+
     def initialize(params={})
       @errors         ||= []
       @report_titles  ||= []
@@ -17,78 +23,93 @@ module XeroGateway
       end
     end
 
-    def self.from_xml(report_element)
-      report = Report.new
-      report_element.children.each do | element |
-        case element.name
-          when 'ReportID'         then report.report_id = element.text
-          when 'ReportName'       then report.report_name = element.text
-          when 'ReportType'       then report.report_type = element.text
-          when 'ReportTitles'
-            each_title(element) do |title|
-              report.report_titles << title
-            end
-          when 'ReportDate'       then report.report_date = Date.parse(element.text)
-          when 'UpdatedDateUTC'   then report.updated_at = parse_date_time_utc(element.text)
-          when 'Rows'
-            report.column_names   ||= find_body_column_names(element)
-            each_row_content(element) do |content_hash|
-              report.body << OpenStruct.new(content_hash)
-            end
+    class << self
+
+      def from_xml(report_element)
+        report = Report.new
+        report_element.children.each do | element |
+          case element.name
+            when 'ReportID'         then report.report_id = element.text
+            when 'ReportName'       then report.report_name = element.text
+            when 'ReportType'       then report.report_type = element.text
+            when 'ReportTitles'
+              each_title(element) do |title|
+                report.report_titles << title
+              end
+            when 'ReportDate'       then report.report_date = Date.parse(element.text)
+            when 'UpdatedDateUTC'   then report.updated_at = parse_date_time_utc(element.text)
+            when 'Rows'
+              report.column_names ||= find_body_column_names(element)
+              each_row_content(element) do |row|
+                report.body << row
+              end
+          end
         end
+        report
       end
-      report
-    end
 
-  private
-
-    def self.each_row_content(xml_element, &block)
-      column_names   = find_body_column_names(xml_element).keys
-      xpath_body     = REXML::XPath.first(xml_element, "//RowType[text()='Section']").parent
-      rows_contents  = []
-      xpath_body.elements.each("Rows/Row") do |xpath_cells|
-        values        = find_body_cell_values(xpath_cells)
-        content_hash  = Hash[column_names.zip values]
-        rows_contents << content_hash
-        yield content_hash if block_given?
-      end
-      rows_contents
-    end
+      private
 
-    def self.each_title(xml_element, &block)
-      xpath_titles = REXML::XPath.first(xml_element, "//ReportTitles")
-      xpath_titles.elements.each("//ReportTitle") do |xpath_title|
-        title = xpath_title.text.strip
-        yield title if block_given?
-      end
-    end
+        def each_row_content(xml_element, &block)
+          column_names    = find_body_column_names(xml_element).values
+          report_sections = REXML::XPath.each(xml_element, "//RowType[text()='Section']/parent::Row")
 
-    def self.find_body_cell_values(xml_cells)
-      values = []
-      xml_cells.elements.each("Cells/Cell") do |xml_cell|
-        if value = xml_cell.children.first # finds <Value>...</Value>
-          values << value.text.try(:strip)
-          next
+          report_sections.each do |section_row|
+            section_name = section_row.get_elements("Title").first.try(:text)
+            section_row.elements.each("Rows/Row") do |xpath_cells|
+              values = find_body_cell_values(xpath_cells)
+              yield Row.new(column_names, values, section_name)
+            end
+          end
         end
-        values << nil
-      end
-      values
-    end
 
-    # returns something like { column_1: "Amount", column_2: "Description", ... }
-    def self.find_body_column_names(body)
-      header       = REXML::XPath.first(body, "//RowType[text()='Header']")
-      names_map    = {}
-      column_count = 0
-      header.parent.elements.each("Cells/Cell") do |header_cell|
-        column_count += 1
-        column_key    = "column_#{column_count}".to_sym
-        column_name   = nil
-        name_value    = header_cell.children.first
-        column_name   = name_value.text.strip unless name_value.blank? # finds <Value>...</Value>
-        names_map[column_key] = column_name
-      end
-      names_map
+        def each_title(xml_element, &block)
+          xpath_titles = REXML::XPath.first(xml_element, "//ReportTitles")
+          xpath_titles.elements.each("//ReportTitle") do |xpath_title|
+            title = xpath_title.text.strip
+            yield title if block_given?
+          end
+        end
+
+        def find_body_cell_values(xml_cells)
+          values = []
+          xml_cells.elements.each("Cells/Cell") do |xml_cell|
+            if value = xml_cell.children.first # finds <Value>...</Value>
+              values << Cell.new(value.text.try(:strip), collect_attributes(xml_cell))
+              next
+            end
+            values << nil
+          end
+          values
+        end
+
+        # Collects "<Attribute>" elements into a hash
+        def collect_attributes(xml_cell)
+          Array.wrap(xml_cell.elements["Attributes/Attribute"]).inject({}) do |hash, xml_attribute|
+            if (key   = xml_attribute.elements["Id"].try(:text)) &&
+              (value = xml_attribute.elements["Value"].try(:text))
+
+              hash[key] = value
+            end
+            hash
+          end.symbolize_keys
+        end
+
+        # returns something like { column_1: "Amount", column_2: "Description", ... }
+        def find_body_column_names(body)
+          header       = REXML::XPath.first(body, "//RowType[text()='Header']")
+          names_map    = {}
+          column_count = 0
+          header.parent.elements.each("Cells/Cell") do |header_cell|
+            column_count += 1
+            column_key    = "column_#{column_count}".to_sym
+            column_name   = nil
+            name_value    = header_cell.children.first
+            column_name   = name_value.text.strip unless name_value.blank? # finds <Value>...</Value>
+            names_map[column_key] = column_name
+          end
+          names_map
+        end
     end
 
   end

data/lib/xero_gateway/report/cell.rb

@@ -0,0 +1,28 @@
+module XeroGateway
+  class Report
+
+    # Adds #attributes to the cells we're grabbing, since Xero Report Cells use XML like:
+    # <Cell>
+    #   <Value>Interest Income (270)</Value>
+    #   <Attributes>
+    #     <Attribute>
+    #       <Value>e9482110-7245-4a76-bfe2-14500495a076</Value>
+    #       <Id>account</Id>
+    #     </Attribute>
+    #   </Attributes>
+    # </Cell>
+    #
+    # We delegate to the topmost "<Value>" class and decorate with an "attributes" hash
+    # for the "attribute: value" pairs
+    class Cell < SimpleDelegator
+      attr_reader :attributes, :value
+
+      def initialize(value, new_attributes = {})
+        @value        = value
+        @attributes   = new_attributes
+        super(value)
+      end
+    end
+
+  end
+end

data/lib/xero_gateway/report/row.rb

@@ -0,0 +1,57 @@
+module XeroGateway
+  class Report
+    class Row
+      COLUMN_METHOD_NAME_RE = /^column\_([0-9])+$/
+
+      attr_accessor :section_name
+
+      def initialize(column_titles, columns, section_name = nil)
+        @columns                   = columns
+        @column_titles             = column_titles
+        @column_titles_underscored = column_titles.map(&:to_s).map(&:underscore)
+        @section_name              = section_name
+      end
+
+      def [](key)
+        return @columns[key] if key.is_a?(Integer)
+
+        [ @column_titles, @column_titles_underscored ].each do |names|
+          if index = names.index(key.to_s)
+            return @columns[index]
+          end
+        end
+
+        nil
+      end
+
+      def method_missing(method_name, *args, &block)
+        if method_name =~ COLUMN_METHOD_NAME_RE
+          # support column_#{n} style deprecated API
+          ActiveSupport::Deprecation.warn("XeroGateway: The #column_n API for accessing report cells will be deprecated in a future version. Please use the underscored column title, a hash or array index accessor", caller_locations)
+          @columns[$1.to_i - 1]
+        elsif (column_index = @column_titles_underscored.index(method_name.to_s))
+          @columns[column_index]
+        else
+          super
+        end
+      end
+
+      def respond_to_missing?(method_name, *args)
+        (method_name =~ COLUMN_METHOD_NAME_RE) || @column_titles_underscored.include?(method_name.to_s) || super
+      end
+
+      def inspect
+        "<XeroGateway::Report::Row:#{object_id} #{pairs}>"
+      end
+
+      private
+
+        def pairs
+          @column_titles.zip(@columns).map do |title, value|
+            "#{title.to_s.underscore}: #{value.inspect}"
+          end.join(" ")
+        end
+
+    end
+  end
+end

data/lib/xero_gateway/version.rb

@@ -1,3 +1,3 @@
 module XeroGateway
-  VERSION = "2.5.0"
+  VERSION = "2.6.0"
 end

data/test/unit/contact_test.rb

@@ -80,6 +80,14 @@ class ContactTest < Test::Unit::TestCase
           <PhoneType>MOBILE</PhoneType>
         </Phone>
       </Phones>
+      <ContactPersons>
+        <ContactPerson>
+          <FirstName>John</FirstName>
+          <LastName>Smith</LastName>
+          <EmailAddress>john@acme.com</EmailAddress>
+          <IncludeInEmails>true</IncludeInEmails>
+        </ContactPerson>
+      </ContactPersons>
       <UpdatedDateUTC>2016-08-31T04:55:39.217</UpdatedDateUTC>
       <IsSupplier>false</IsSupplier>
       <IsCustomer>false</IsCustomer>
@@ -172,6 +180,7 @@ class ContactTest < Test::Unit::TestCase
     contact.phone.number = "12345"
     contact.is_customer = true
     contact.is_supplier = true
+    contact.add_contact_person(first_name: 'John', last_name: 'Smith', email_address: 'john@acme.com', include_in_emails: true)
 
     contact
   end

data/test/unit/gateway_test.rb

@@ -75,6 +75,18 @@ class GatewayTest < Test::Unit::TestCase
       assert result.response_item.first.is_a? XeroGateway::Payment
     end
 
+    should :get_payroll_calendars do
+      XeroGateway::OAuth.any_instance.stubs(:get).returns(stub(:plain_body => get_file_as_string("payroll_calendars.xml"), :code => "200"))
+      result = @gateway.get_payroll_calendars
+      assert result.response_item.first.is_a? XeroGateway::PayrollCalendar
+    end
+
+    should :get_pay_runs do
+      XeroGateway::OAuth.any_instance.stubs(:get).returns(stub(:plain_body => get_file_as_string("pay_runs.xml"), :code => "200"))
+       result = @gateway.get_pay_runs
+      assert result.response_item.is_a? XeroGateway::PayRun
+    end
+
     should :get_contacts do
       XeroGateway::OAuth.any_instance.stubs(:get).returns(stub(:plain_body => get_file_as_string("contacts.xml"), :code => "200"))
       result = @gateway.get_contacts

data/test/unit/invoice_test.rb

@@ -68,6 +68,27 @@ class InvoiceTest < Test::Unit::TestCase
       parsed_invoice = XeroGateway::Invoice.from_xml(invoice_element)
       assert_equal 'http://example.com?with=params&and=more', parsed_invoice.url
     end
+
+    should "work with line_item discount rates" do
+      invoice = create_test_invoice
+      invoice.line_items.first.discount_rate = 27
+      invoice_as_xml = invoice.to_xml
+
+      invoice_element = REXML::XPath.first(REXML::Document.new(invoice_as_xml), "/Invoice")
+      result_invoice = XeroGateway::Invoice.from_xml(invoice_element)
+
+      assert_equal(invoice, result_invoice)
+      assert_equal 27, result_invoice.line_items.first.discount_rate
+    end
+
+    should "handle paid-on date" do
+      invoice = create_test_invoice(:fully_paid_on => Date.yesterday)
+      invoice_element = REXML::XPath.first(REXML::Document.new(invoice.to_xml), "/Invoice")
+      result_invoice = XeroGateway::Invoice.from_xml(invoice_element)
+
+      assert_equal(invoice, result_invoice)
+      assert_equal Date.yesterday, result_invoice.fully_paid_on
+    end
   end
 
   # Tests the sub_total calculation and that setting it manually doesn't modify the data.
@@ -154,6 +175,26 @@ class InvoiceTest < Test::Unit::TestCase
     assert_equal(quantity * line_item.unit_amount, line_item.line_amount)
   end
 
+  def test_line_amount_discount_calculation
+    invoice = create_test_invoice
+    line_item = invoice.line_items.first
+    line_item.discount_rate = 12.5
+
+    # Make sure that everything adds up to begin with.
+    expected_amount = line_item.quantity * line_item.unit_amount * 0.875
+    assert_equal(expected_amount, line_item.line_amount)
+
+    # Change the line_amount and check that it doesn't modify anything.
+    line_item.line_amount = expected_amount * 10
+    assert_equal(expected_amount, line_item.line_amount)
+
+    # Change the quantity and check that the line_amount has been updated.
+    quantity = line_item.quantity + 2
+    line_item.quantity = quantity
+    assert_not_equal(expected_amount, line_item.line_amount)
+    assert_equal(quantity * line_item.unit_amount * 0.875, line_item.line_amount)
+  end
+
   # Ensure that the totalling methods don't raise exceptions, even when
   # invoice.line_items is empty.
   def test_totalling_methods_when_line_items_empty
@@ -286,7 +327,7 @@ class InvoiceTest < Test::Unit::TestCase
   def test_optional_params
     eur_code = "EUR"
     eur_rate = 1.80
-    
+
     invoice = create_test_invoice(:url => 'http://example.com', :branding_theme_id => 'a94a78db-5cc6-4e26-a52b-045237e56e6e', :currency_code => eur_code, :currency_rate => eur_rate)
     assert_equal 'http://example.com', invoice.url
     assert_equal 'a94a78db-5cc6-4e26-a52b-045237e56e6e', invoice.branding_theme_id

data/test/unit/report/row_test.rb

@@ -0,0 +1,45 @@
+require_relative '../../test_helper.rb'
+
+class ReportRowTest < Test::Unit::TestCase
+
+  context "with a sample row" do
+    setup do
+      @row = XeroGateway::Report::Row.new(
+        ["Account",     "Debit", "Credit"],
+        ["Sales (200)",  560_00,  0],
+        "Bank Accounts"
+      )
+    end
+
+    should "be able to access using the deprecated column_n API" do
+      ActiveSupport::Deprecation.silence do
+        assert_equal @row.column_1, "Sales (200)"
+        assert_equal @row.column_3, 0
+
+        assert @row.respond_to?(:column_1)
+      end
+    end
+
+    should "be able to access using an underscored column name" do
+      assert_equal @row.account, "Sales (200)"
+      assert @row.respond_to?(:account)
+    end
+
+    should "be able to access using an array index" do
+      assert_equal @row[0], "Sales (200)"
+      assert_equal @row[1], 560_00
+    end
+
+    should "be able to access using a string index" do
+      assert_equal @row["Account"], "Sales (200)"
+      assert_equal @row["Debit"],    560_00
+    end
+
+    should "be able to access using a symbol index" do
+      assert_equal @row[:account], "Sales (200)"
+      assert_equal @row[:debit],    560_00
+    end
+
+  end
+
+end

data/test/unit/report_test.rb

@@ -19,60 +19,86 @@ class ReportTest < Test::Unit::TestCase
   end
 
   context :from_xml do
-    setup do
-      xml_response = get_file("reports/bank_statement.xml")
-      xml_response.gsub!(/\n +/,'')
-      xml_doc = REXML::Document.new(xml_response)
-      xpath_report = XPath.first(xml_doc, "//Report")
-      @report = XeroGateway::Report.from_xml(xpath_report)
-    end
+    context "with a bank statement report" do
+      setup do
+        @report = make_report_from_xml("bank_statement")
+      end
+
+      should "create a bank statement report" do
+        assert @report.is_a?(XeroGateway::Report)
+        assert_equal [], @report.errors
+        assert_equal Date.parse("27 May 2014"), @report.report_date
+        assert_equal "BankStatement", @report.report_id
+        assert_equal "Bank Statement", @report.report_name
+        expected_titles = ["Bank Statement", "Business Bank Account", "Demo Company (NZ)", "From 1 May 2014 to 27 May 2014"]
+        assert_equal expected_titles, @report.report_titles
+        assert_equal "BankStatement", @report.report_type
+        assert_equal Time.parse("2014-05-26 22:36:07 +0000").to_i, @report.updated_at.to_i
+        expected_names = { :column_1=>"Date", :column_2=>"Description", :column_3=>"Reference", :column_4=>"Reconciled", :column_5=>"Source", :column_6=>"Amount", :column_7=>"Balance" }
+        assert_equal expected_names, @report.column_names
+
+        ###
+        # REPORT BODY
+        assert @report.body.is_a?(Array)
 
-    should "create a bank statement report" do
-      assert @report.is_a?(XeroGateway::Report)
-      assert_equal [], @report.errors
-      assert_equal Date.parse("27 May 2014"), @report.report_date
-      assert_equal "BankStatement", @report.report_id
-      assert_equal "Bank Statement", @report.report_name
-      expected_titles = ["Bank Statement", "Business Bank Account", "Demo Company (NZ)", "From 1 May 2014 to 27 May 2014"]
-      assert_equal expected_titles, @report.report_titles
-      assert_equal "BankStatement", @report.report_type
-      assert_equal Time.parse("2014-05-26 22:36:07 +0000").to_i, @report.updated_at.to_i
-      expected_names = { :column_1=>"Date", :column_2=>"Description", :column_3=>"Reference", :column_4=>"Reconciled", :column_5=>"Source", :column_6=>"Amount", :column_7=>"Balance" }
-      assert_equal expected_names, @report.column_names
+        # First = Opening Balance
+        first_statement = @report.body.first
+        assert_equal "2014-05-01T00:00:00", first_statement.date
+        assert_equal "Opening Balance", first_statement.description
+        assert_equal nil, first_statement.reference
+        assert_equal nil, first_statement.reconciled
+        assert_equal nil, first_statement.source
+        assert_equal nil, first_statement.amount
+        assert_equal "15461.97", first_statement.balance
 
-      ###
-      # REPORT BODY
-      assert @report.body.is_a?(Array)
+        # Second = Bank Transaction/Statement
+        second_statement = @report.body.second
+        assert_equal "2014-05-01T00:00:00", second_statement.date
+        assert_equal "Ridgeway Banking Corporation", second_statement.description
+        assert_equal "Fee", second_statement.reference
+        assert_equal "No", second_statement.reconciled
+        assert_equal "Import", second_statement.source
+        assert_equal "-15.00", second_statement.amount
+        assert_equal "15446.97", second_statement.balance
+
+        # Third
+        third_statement = @report.body.third
+        assert_equal nil, third_statement.description.value # no description, but other attributes
+        assert_equal "Eft", third_statement.reference
+        assert_equal "No", third_statement.reconciled
+        assert_equal "Import", third_statement.source
+        assert_equal "-15.75", third_statement.amount
+        assert_equal "15431.22", third_statement.balance
+      end
+    end
 
-      # First = Opening Balance
-      first_statement = @report.body.first
-      assert_equal "2014-05-01T00:00:00", first_statement.column_1
-      assert_equal "Opening Balance", first_statement.column_2
-      assert_equal nil, first_statement.column_3
-      assert_equal nil, first_statement.column_4
-      assert_equal nil, first_statement.column_5
-      assert_equal nil, first_statement.column_6
-      assert_equal "15461.97", first_statement.column_7
+    context "with a trial balance report" do
+      setup do
+        @report = make_report_from_xml("trial_balance")
+      end
 
-      # Second = Bank Transaction/Statement
-      second_statement = @report.body.second
-      assert_equal "2014-05-01T00:00:00", second_statement.column_1
-      assert_equal "Ridgeway Banking Corporation", second_statement.column_2
-      assert_equal "Fee", second_statement.column_3
-      assert_equal "No", second_statement.column_4
-      assert_equal "Import", second_statement.column_5
-      assert_equal "-15.00", second_statement.column_6
-      assert_equal "15446.97", second_statement.column_7
+      should "set attributes on individual cells" do
+        first_statement = @report.body.first
+        assert_equal "Sales (200)", first_statement.account.value
+        assert_equal({ account: "7d05a53d-613d-4eb2-a2fc-dcb6adb80b80" }, first_statement.account.attributes)
+      end
 
-      # Third
-      third_statement = @report.body.third
-      assert_equal nil, third_statement.column_2 # no description, but other attributes
-      assert_equal "Eft", third_statement.column_3
-      assert_equal "No", third_statement.column_4
-      assert_equal "Import", third_statement.column_5
-      assert_equal "-15.75", third_statement.column_6
-      assert_equal "15431.22", third_statement.column_7
+      should "have all rows and section titles" do
+        assert_equal 15, @report.rows.length
+        assert_equal %w(Revenue Expenses Assets Liabilities Equity), @report.rows.map(&:section_name).uniq.compact
+      end
     end
+
+  end
+
+  private
+
+  def make_report_from_xml(report_name = "bank_statement")
+    xml_response = get_file("reports/#{report_name}.xml")
+    xml_response.gsub!(/\n +/,'')
+    xml_doc = REXML::Document.new(xml_response)
+    xpath_report = XPath.first(xml_doc, "//Report")
+    XeroGateway::Report.from_xml(xpath_report)
   end
 
 end

data/xero_gateway.gemspec

@@ -10,7 +10,6 @@ Gem::Specification.new do |s|
   s.email       = ["me@nikwakelin.com", "jared@minutedock.com"]
   s.homepage    = "http://github.com/xero-gateway/xero_gateway"
   s.description = "Enables Ruby based applications to communicate with the Xero API"
-  s.has_rdoc    = false
   s.authors     = ["Tim Connor", "Nik Wakelin", "Jared Armstrong"]
   s.license     = "MIT"
 
@@ -32,5 +31,6 @@ Gem::Specification.new do |s|
   s.add_development_dependency "mocha"
   s.add_development_dependency "shoulda"
   s.add_development_dependency "libxml-ruby", "2.7.0"
+  s.add_development_dependency "byebug"
 
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: xero_gateway
 version: !ruby/object:Gem::Version
-  version: 2.5.0
+  version: 2.6.0
 platform: ruby
 authors:
 - Tim Connor
@@ -10,7 +10,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-11-03 00:00:00.000000000 Z
+date: 2019-02-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: builder
@@ -152,6 +152,20 @@ dependencies:
     - - '='
       - !ruby/object:Gem::Version
         version: 2.7.0
+- !ruby/object:Gem::Dependency
+  name: byebug
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: Enables Ruby based applications to communicate with the Xero API
 email:
 - me@nikwakelin.com
@@ -177,6 +191,7 @@ files:
 - lib/xero_gateway/ca-certificates.crt
 - lib/xero_gateway/contact.rb
 - lib/xero_gateway/contact_group.rb
+- lib/xero_gateway/contact_person.rb
 - lib/xero_gateway/credit_note.rb
 - lib/xero_gateway/currency.rb
 - lib/xero_gateway/dates.rb
@@ -195,10 +210,14 @@ files:
 - lib/xero_gateway/oauth.rb
 - lib/xero_gateway/organisation.rb
 - lib/xero_gateway/partner_app.rb
+- lib/xero_gateway/pay_run.rb
 - lib/xero_gateway/payment.rb
+- lib/xero_gateway/payroll_calendar.rb
 - lib/xero_gateway/phone.rb
 - lib/xero_gateway/private_app.rb
 - lib/xero_gateway/report.rb
+- lib/xero_gateway/report/cell.rb
+- lib/xero_gateway/report/row.rb
 - lib/xero_gateway/response.rb
 - lib/xero_gateway/tax_rate.rb
 - lib/xero_gateway/tracking_category.rb
@@ -246,6 +265,7 @@ files:
 - test/unit/oauth_test.rb
 - test/unit/organisation_test.rb
 - test/unit/payment_test.rb
+- test/unit/report/row_test.rb
 - test/unit/report_test.rb
 - test/unit/tax_rate_test.rb
 - test/unit/tracking_category_test.rb
@@ -270,7 +290,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.5.1
+rubygems_version: 2.5.2.3
 signing_key: 
 specification_version: 4
 summary: Enables Ruby based applications to communicate with the Xero API