xeroizer 2.16.5 → 2.17.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 661b00281b09048f7c58f3bc0e4c12d3401fc9c3
-  data.tar.gz: 79db1f4fa930e1deb41f78fd0cee48ee6e30ab95
+  metadata.gz: 0b4149d832f1cb36887a460f7f8258d049fdd991
+  data.tar.gz: c8ea7a95afb25ee8f41f7a1f15f9f6ce4ae3914e
 SHA512:
-  metadata.gz: 5dec38c448515e18f9aad030a0ae05bcd7504133474fcc8b52d06be00947db73556416414bb528483810d894a97785d862540b4d7a4cdd948632b99c5ef0abdf
-  data.tar.gz: 091ef6309c0a17f85976b1135eaca233de6b3e7031b972bfbdc14c81b9016c67177f6fdf1ebdca9694047aba232a5f5c6d7e95cf2f1f1f49c13c3cab7b139156
+  metadata.gz: bbaef5a37d2b986f9e81f7b2cd229f501d711563f5634f2cc50125f541cca510386e5110dae6a483fd4782db4213641cc827ab6a6cab43b33bc43deaeb68c6ea
+  data.tar.gz: e37566c54ffddbc031712a08ff0c3179ea26f8def7f75c709d9430ed01a185f70f639976741599bef4307ac9846034c533c060e982129311f23f7f0aaf60b884

data/README.md

@@ -1,4 +1,4 @@
-Xeroizer API Library ![Project status](http://stillmaintained.com/waynerobinson/xeroizer.png)
+Xeroizer API Library ![Project status](http://stillmaintained.com/waynerobinson/xeroizer.png) [![Build Status](https://travis-ci.org/waynerobinson/xeroizer.svg)](https://travis-ci.org/waynerobinson/xeroizer)
 ====================
 
 **Homepage**: 		[http://waynerobinson.github.com/xeroizer](http://waynerobinson.github.com/xeroizer)		
@@ -114,8 +114,8 @@ class XeroSessionController < ApplicationController
 					:access_token => @xero_client.access_token.token,
 					:access_key => @xero_client.access_token.secret }
 															
-			session[:request_token] = nil
-            session[:request_secret] = nil
+			session.data.delete(:request_token)
+			session.data.delete(:request_secret)
 		end
 		
 		def destroy
@@ -176,22 +176,9 @@ contacts = client.Contact.all
 
 ### Partner Applications
 
-Partner applications use a combination of 3-legged authorisation, private key message signing and client-side SSL
-certificate signing.
+Partner applications use a combination of 3-legged authorisation and private key message signing.
 
-Partner applications are only in beta testing via the Xero API and you will need to contact Xero (network@xero.com) to 
-get permission to create a partner application and for them to send you information on obtaining your client-side SSL
-certificate.
-
-Ruby's OpenSSL library requires the certificate and private key to be extracted from the `entrust-client.p12` file
-downloaded via Xero's instructions. To extract:
-
-	openssl pkcs12 -in entrust-client.p12 -clcerts -nokeys -out entrust-cert.pem
-	openssl pkcs12 -in entrust-client.p12 -nocerts -out entrust-private.pem
-	openssl rsa -in entrust-private.pem -out entrust-private-nopass.pem
-	
-	# This last step removes the password that you added to the private key
-	# when it was exported.
+You will need to contact Xero (network@xero.com) to get permission to create a partner application.
 
 After you have followed the instructions provided by Xero for partner applications and uploaded your certificate you can
 access the partner application in a similar way to public applications.
@@ -202,9 +189,7 @@ Authentication occcurs in 3 steps:
 client = Xeroizer::PartnerApplication.new(
 					YOUR_OAUTH_CONSUMER_KEY,
 					YOUR_OAUTH_CONSUMER_SECRET, 
-					"/path/to/privatekey.pem",
-					"/path/to/entrust-cert.pem",
-					"/path/to/entrust-private-nopass.pem"
+					"/path/to/privatekey.pem"
 					)
 
 # 1. Get a RequestToken from Xero. :oauth_callback is the URL the user will be redirected to
@@ -356,15 +341,23 @@ in the resulting response, including all nested XML elements.
 	
 		invoices = xero.Invoice.all(:where => 'FullyPaidOnDate>=DateTime.Parse("2010-01-01T00:00:00")&&FullyPaidOnDate<=DateTime.Parse("2010-01-08T00:00:00")')
 	
-**Example 4: Retrieve all Bank Accounts:**
+**Example 4: Retrieve all Invoices using Paging (batches of 100)**
+
+		invoices = xero.Invoice.find_in_batches({page_number: 1}) do |invoice_batch|
+		  invoice_batch.each do |invoice|
+		    ...
+		  end
+		end
+				
+**Example 5: Retrieve all Bank Accounts:**
 	
 		accounts = xero.Account.all(:where => 'Type=="BANK"')
 	
-**Example 5: Retrieve all DELETED or VOIDED Invoices:**
+**Example 6: Retrieve all DELETED or VOIDED Invoices:**
 	
 		invoices = xero.Invoice.all(:where => 'Status=="VOIDED" OR Status=="DELETED"')
 	
-**Example 6: Retrieve all contacts with specific text in the contact name:**
+**Example 7: Retrieve all contacts with specific text in the contact name:**
 
 		contacts = xero.Contact.all(:where => 'Name.Contains("Peter")')
 		contacts = xero.Contact.all(:where => 'Name.StartsWith("Pet")')
@@ -481,7 +474,7 @@ end
 ```
 
 `batch_save` will issue one PUT request for every 2,000 unsaved records built within its block, and one
-POST request for evert 2,000 existing records that have been altered within its block. If any of the
+POST request for every 2,000 existing records that have been altered within its block. If any of the
 unsaved records aren't valid, it'll return `false` before sending anything across the wire;
 otherwise, it returns `true`. `batch_save` takes one optional argument: the number of records to
 create/update per request. (Defaults to 2,000.)
@@ -572,7 +565,7 @@ Xero API Rate Limits
 The Xero API imposes the following limits on calls per organisation:
 
 * A limit of 60 API calls in any 60 second period
-* A limit of 1000 API calls in any 24 hour period
+* A limit of 5000 API calls in any 24 hour period
 
 By default, the library will raise a `Xeroizer::OAuth::RateLimitExceeded`
 exception when one of these limits is exceeded.
@@ -622,7 +615,7 @@ client = Xeroizer::PublicApplication.new(YOUR_OAUTH_CONSUMER_KEY,
 HTTP Callbacks
 --------------------
 
-You can provide "before" and "after" callbacks which will be invoked every
+You can provide "before", "after" and "around" callbacks which will be invoked every
 time Xeroizer makes an HTTP request, which is potentially useful for both
 throttling and logging:
 
@@ -631,6 +624,7 @@ Xeroizer::PublicApplication.new(
   credentials[:key], credentials[:secret],
   before_request: ->(request) { puts "Hitting this URL: #{request.url}" },
   after_request: ->(request, response) { puts "Got this response: #{response.code}" }
+  around_request: -> (request, &block)  { puts "About to send request"; block.call; puts "After request"}
 )
 ```
 

data/lib/class_level_inheritable_attributes.rb

@@ -16,10 +16,13 @@ module ClassLevelInheritableAttributes
     end
     
     def inherited(subclass)
+      original_verbose, $VERBOSE = $VERBOSE, nil
       @xeroizer_inheritable_attributes.each do |inheritable_attribute|
         instance_var = "@#{inheritable_attribute}"
         subclass.instance_variable_set(instance_var, instance_variable_get(instance_var))
       end
+      $VERBOSE = original_verbose
+
     end
   end
 end

data/lib/xeroizer.rb

@@ -15,13 +15,15 @@ require 'cgi'
 $: << File.expand_path(File.dirname(__FILE__))
 
 require 'class_level_inheritable_attributes'
+require 'xeroizer/exceptions'
 require 'xeroizer/oauth'
 require 'xeroizer/http_encoding_helper'
 require 'xeroizer/http'
-require 'xeroizer/exceptions'
 
 require 'xeroizer/record/base_model'
+require 'xeroizer/record/payroll_base_model'
 require 'xeroizer/record/base'
+require 'xeroizer/record/payroll_base'
 require 'xeroizer/configuration'
 
 # Include models
@@ -31,6 +33,9 @@ require 'xeroizer/models/allocation'
 require 'xeroizer/models/branding_theme'
 require 'xeroizer/models/bank_transaction'
 require 'xeroizer/models/bank_account'
+require 'xeroizer/models/from_bank_account'
+require 'xeroizer/models/to_bank_account'
+require 'xeroizer/models/bank_transfer'
 require 'xeroizer/models/contact'
 require 'xeroizer/models/contact_group'
 require 'xeroizer/models/credit_note'
@@ -38,6 +43,7 @@ require 'xeroizer/models/currency'
 require 'xeroizer/models/employee'
 require 'xeroizer/models/expense_claim'
 require 'xeroizer/models/invoice'
+require 'xeroizer/models/invoice_reminder'
 require 'xeroizer/models/item'
 require 'xeroizer/models/item_purchase_details'
 require 'xeroizer/models/item_sales_details'
@@ -50,6 +56,7 @@ require 'xeroizer/models/option'
 require 'xeroizer/models/organisation'
 require 'xeroizer/models/payment'
 require 'xeroizer/models/prepayment'
+require 'xeroizer/models/overpayment'
 require 'xeroizer/models/phone'
 require 'xeroizer/models/purchase_order'
 require 'xeroizer/models/receipt'
@@ -64,6 +71,10 @@ require 'xeroizer/models/journal_line_tracking_category'
 require 'xeroizer/models/contact_sales_tracking_category'
 require 'xeroizer/models/contact_purchases_tracking_category'
 
+require 'xeroizer/models/payroll/home_address'
+require 'xeroizer/models/payroll/bank_account'
+require 'xeroizer/models/payroll/employee'
+
 require 'xeroizer/report/factory'
 
 require 'xeroizer/response'
@@ -72,3 +83,4 @@ require 'xeroizer/generic_application'
 require 'xeroizer/public_application'
 require 'xeroizer/private_application'
 require 'xeroizer/partner_application'
+require 'xeroizer/payroll_application'

data/lib/xeroizer/exceptions.rb

@@ -143,7 +143,7 @@ module Xeroizer
     end
 
     def message
-      case new_status
+      case @new_status
         when 'DELETED', 'VOIDED'
           unless @invoice.payments.size == 0
             "There must be no payments in this invoice to change to '#{@new_status}'"

data/lib/xeroizer/generic_application.rb

@@ -7,7 +7,7 @@ module Xeroizer
     extend Record::ApplicationHelper
 
     attr_reader :client, :xero_url, :logger, :rate_limit_sleep, :rate_limit_max_attempts,
-                :default_headers, :unitdp, :before_request, :after_request, :nonce_used_max_attempts
+                :default_headers, :unitdp, :before_request, :after_request, :around_request, :nonce_used_max_attempts
 
     extend Forwardable
     def_delegators :client, :access_token
@@ -16,6 +16,7 @@ module Xeroizer
     record :Allocation
     record :Attachment
     record :BrandingTheme
+    record :Balances
     record :Contact
     record :ContactGroup
     record :CreditNote
@@ -23,12 +24,15 @@ module Xeroizer
     record :Employee
     record :ExpenseClaim
     record :Invoice
+    record :InvoiceReminder
     record :Item
     record :Journal
+    record :LineItem
     record :ManualJournal
     record :Organisation
     record :Payment
     record :Prepayment
+    record :Overpayment
     record :PurchaseOrder
     record :Receipt
     record :RepeatingInvoice
@@ -37,6 +41,7 @@ module Xeroizer
     record :TrackingCategory
     record :TrackingCategoryChild
     record :BankTransaction
+    record :BankTransfer
     record :User
 
     report :AgedPayablesByContact
@@ -63,10 +68,17 @@ module Xeroizer
         @default_headers = options[:default_headers] || {}
         @before_request = options.delete(:before_request)
         @after_request = options.delete(:after_request)
+        @around_request = options.delete(:around_request)
         @client = OAuth.new(consumer_key, consumer_secret, options.merge({default_headers: default_headers}))
         @logger = options[:logger] || false
         @unitdp = options[:unitdp] || 2
       end
 
+      def payroll(options = {})
+        xero_client = self.clone
+        xero_client.xero_url = options[:xero_url] || "https://api.xero.com/payroll.xro/1.0"
+        @payroll ||= PayrollApplication.new(xero_client)
+      end
+          
   end
 end

data/lib/xeroizer/http.rb

@@ -14,7 +14,7 @@
 
 module Xeroizer
   module Http
-    class BadResponse < StandardError; end
+    class BadResponse < XeroizerError; end
     RequestInfo = Struct.new(:url, :headers, :params, :body)
 
     ACCEPT_MIME_MAP = {
@@ -53,90 +53,100 @@ module Xeroizer
 
     private
 
-      def http_request(client, method, url, body, params = {})
-        # headers = {'Accept-Encoding' => 'gzip, deflate'}
+    def http_request(client, method, url, body, params = {})
+      # headers = {'Accept-Encoding' => 'gzip, deflate'}
 
-        headers = self.default_headers.merge({ 'charset' => 'utf-8' })
+      headers = self.default_headers.merge({ 'charset' => 'utf-8' })
 
-        # include the unitdp query string parameter
-        params.merge!(unitdp_param(url))
+      # include the unitdp query string parameter
+      params.merge!(unitdp_param(url))
 
-        if method != :get
-          headers['Content-Type'] ||= "application/x-www-form-urlencoded"
-        end
+      if method != :get
+        headers['Content-Type'] ||= "application/x-www-form-urlencoded"
+      end
 
-        content_type = params.delete(:content_type)
-        headers['Content-Type'] = content_type if content_type
+      content_type = params.delete(:content_type)
+      headers['Content-Type'] = content_type if content_type
 
-        # HAX.  Xero completely misuse the If-Modified-Since HTTP header.
-        headers['If-Modified-Since'] = params.delete(:ModifiedAfter).utc.strftime("%Y-%m-%dT%H:%M:%S") if params[:ModifiedAfter]
+      # HAX.  Xero completely misuse the If-Modified-Since HTTP header.
+      headers['If-Modified-Since'] = params.delete(:ModifiedAfter).utc.strftime("%Y-%m-%dT%H:%M:%S") if params[:ModifiedAfter]
 
-        # Allow 'Accept' header to be specified with :accept parameter.
-        # Valid values are :pdf or :json.
-        if params[:response]
-          response_type = params.delete(:response)
-          headers['Accept'] = case response_type
-            when Symbol then  ACCEPT_MIME_MAP[response_type]
-            else              response_type
-          end
+      # Allow 'Accept' header to be specified with :accept parameter.
+      # Valid values are :pdf or :json.
+      if params[:response]
+        response_type = params.delete(:response)
+        headers['Accept'] = case response_type
+          when Symbol then  ACCEPT_MIME_MAP[response_type]
+          else              response_type
         end
+      end
 
-        if params.any?
-          url += "?" + params.map {|key,value| "#{CGI.escape(key.to_s)}=#{CGI.escape(value.to_s)}"}.join("&")
-        end
+      if params.any?
+        url += "?" + params.map {|key, value| "#{CGI.escape(key.to_s)}=#{CGI.escape(value.to_s)}"}.join("&")
+      end
 
-        uri = URI.parse(url)
+      uri = URI.parse(url)
 
-        attempts = 0
+      attempts = 0
 
-        request_info = RequestInfo.new(url, headers, params, body)
-        before_request.call(request_info) if before_request
+      request_info = RequestInfo.new(url, headers, params, body)
+      before_request.call(request_info) if before_request
 
-        begin
-          attempts += 1
-          logger.info("XeroGateway Request: #{method.to_s.upcase} #{uri.request_uri}") if self.logger
+      begin
+        attempts += 1
+        logger.info("XeroGateway Request: #{method.to_s.upcase} #{uri.request_uri}") if self.logger
 
-          raw_body = params.delete(:raw_body) ? body : {:xml => body}
+        raw_body = params.delete(:raw_body) ? body : {:xml => body}
 
-          response = case method
+        response = with_around_request(request_info) do
+          case method
             when :get   then    client.get(uri.request_uri, headers)
             when :post  then    client.post(uri.request_uri, raw_body, headers)
             when :put   then    client.put(uri.request_uri, raw_body, headers)
           end
+        end
 
-          log_response(response, uri)
-          after_request.call(request_info, response) if after_request
-
-          case response.code.to_i
-            when 200
-              response.plain_body
-            when 400
-              handle_error!(response, body)
-            when 401
-              handle_oauth_error!(response)
-            when 404
-              handle_object_not_found!(response, url)
-            when 503
-              handle_oauth_error!(response)
-            else
-              handle_unknown_response_error!(response)
-          end
-        rescue Xeroizer::OAuth::NonceUsed => exception
-          raise if attempts > nonce_used_max_attempts
-          logger.info("Nonce used: " + exception.to_s) if self.logger
-          sleep_for(1)
-          retry
-        rescue Xeroizer::OAuth::RateLimitExceeded
-          if self.rate_limit_sleep
-            raise if attempts > rate_limit_max_attempts
-            logger.info("Rate limit exceeded, retrying") if self.logger
-            sleep_for(self.rate_limit_sleep)
-            retry
+        log_response(response, uri)
+        after_request.call(request_info, response) if after_request
+
+        case response.code.to_i
+          when 200
+            response.plain_body
+          when 400
+            handle_error!(response, body)
+          when 401
+            handle_oauth_error!(response)
+          when 404
+            handle_object_not_found!(response, url)
+          when 503
+            handle_oauth_error!(response)
           else
-            raise
-          end
+            handle_unknown_response_error!(response)
+        end
+      rescue Xeroizer::OAuth::NonceUsed => exception
+        raise if attempts > nonce_used_max_attempts
+        logger.info("Nonce used: " + exception.to_s) if self.logger
+        sleep_for(1)
+        retry
+      rescue Xeroizer::OAuth::RateLimitExceeded
+        if self.rate_limit_sleep
+          raise if attempts > rate_limit_max_attempts
+          logger.info("Rate limit exceeded, retrying") if self.logger
+          sleep_for(self.rate_limit_sleep)
+          retry
+        else
+          raise
         end
       end
+    end
+
+    def with_around_request(request, &block)
+      if around_request
+        around_request.call(request, &block)
+      else
+        block.call
+      end
+    end
 
     def log_response(response, uri)
       if self.logger
@@ -148,78 +158,76 @@ module Xeroizer
     end
 
     def handle_oauth_error!(response)
-        error_details = CGI.parse(response.plain_body)
-        description   = error_details["oauth_problem_advice"].first
-        problem = error_details["oauth_problem"].first
-
-        # see http://oauth.pbworks.com/ProblemReporting
-        # In addition to token_expired and token_rejected, Xero also returns
-        # 'rate limit exceeded' when more than 60 requests have been made in
-        # a second.
-        if problem
-          case (problem)
-            when "token_expired"                then raise OAuth::TokenExpired.new(description)
-            when "token_rejected"               then raise OAuth::TokenInvalid.new(description)
-            when "rate limit exceeded"          then raise OAuth::RateLimitExceeded.new(description)
-            when "consumer_key_unknown"         then raise OAuth::ConsumerKeyUnknown.new(description)
-            when "nonce_used"                   then raise OAuth::NonceUsed.new(description)
-            else raise OAuth::UnknownError.new(problem + ':' + description)
-          end
-        else
-          raise OAuth::UnknownError.new("Xero API may be down or the way OAuth errors are provided by Xero may have changed.")
+      error_details = CGI.parse(response.plain_body)
+      description   = error_details["oauth_problem_advice"].first
+      problem = error_details["oauth_problem"].first
+
+      # see http://oauth.pbworks.com/ProblemReporting
+      # In addition to token_expired and token_rejected, Xero also returns
+      # 'rate limit exceeded' when more than 60 requests have been made in
+      # a second.
+      if problem
+        case problem
+          when "token_expired"                then raise OAuth::TokenExpired.new(description)
+          when "token_rejected"               then raise OAuth::TokenInvalid.new(description)
+          when "rate limit exceeded"          then raise OAuth::RateLimitExceeded.new(description)
+          when "consumer_key_unknown"         then raise OAuth::ConsumerKeyUnknown.new(description)
+          when "nonce_used"                   then raise OAuth::NonceUsed.new(description)
+          when "organisation offline"         then raise OAuth::OrganisationOffline.new(description)
+          else raise OAuth::UnknownError.new(problem + ':' + description)
         end
+      else
+        raise OAuth::UnknownError.new("Xero API may be down or the way OAuth errors are provided by Xero may have changed.")
       end
+    end
 
-      def handle_error!(response, request_body)
-
-        raw_response = response.plain_body
-
-        # XeroGenericApplication API Exceptions *claim* to be UTF-16 encoded, but fail REXML/Iconv parsing...
-        # So let's ignore that :)
-        raw_response.gsub! '<?xml version="1.0" encoding="utf-16"?>', ''
-
-        # doc = REXML::Document.new(raw_response, :ignore_whitespace_nodes => :all)
-        doc = Nokogiri::XML(raw_response)
+    def handle_error!(response, request_body)
 
-        if doc && doc.root && doc.root.name == "ApiException"
+      raw_response = response.plain_body
 
-          raise ApiException.new(doc.root.xpath("Type").text,
-                                 doc.root.xpath("Message").text,
-                                 raw_response,
-                                 doc,
-                                 request_body)
+      # XeroGenericApplication API Exceptions *claim* to be UTF-16 encoded, but fail REXML/Iconv parsing...
+      # So let's ignore that :)
+      raw_response.gsub! '<?xml version="1.0" encoding="utf-16"?>', ''
 
-        else
+      # doc = REXML::Document.new(raw_response, :ignore_whitespace_nodes => :all)
+      doc = Nokogiri::XML(raw_response)
 
-          raise BadResponse.new("Unparseable 400 Response: #{raw_response}")
+      if doc && doc.root && doc.root.name == "ApiException"
 
-        end
+        raise ApiException.new(doc.root.xpath("Type").text,
+                               doc.root.xpath("Message").text,
+                               raw_response,
+                               doc,
+                               request_body)
 
+      else
+        raise BadResponse.new("Unparseable 400 Response: #{raw_response}")
       end
+    end
 
-      def handle_object_not_found!(response, request_url)
-        case(request_url)
-          when /Invoices/ then raise InvoiceNotFoundError.new("Invoice not found in Xero.")
-          when /CreditNotes/ then raise CreditNoteNotFoundError.new("Credit Note not found in Xero.")
-          else raise ObjectNotFound.new(request_url)
-        end
+    def handle_object_not_found!(response, request_url)
+      case request_url
+        when /Invoices/ then raise InvoiceNotFoundError.new("Invoice not found in Xero.")
+        when /CreditNotes/ then raise CreditNoteNotFoundError.new("Credit Note not found in Xero.")
+        else raise ObjectNotFound.new(request_url)
       end
+    end
 
-      def handle_unknown_response_error!(response)
-        raise BadResponse.new("Unknown response code: #{response.code.to_i}")
-      end
+    def handle_unknown_response_error!(response)
+      raise BadResponse.new("Unknown response code: #{response.code.to_i}")
+    end
 
-      def sleep_for(seconds = 1)
-        sleep seconds
-      end
+    def sleep_for(seconds = 1)
+      sleep seconds
+    end
 
-      # unitdp query string parameter to be added to request params
-      # when the application option has been set and the model has line items
-      # http://developer.xero.com/documentation/advanced-docs/rounding-in-xero/#unitamount
-      def unitdp_param(request_url)
-        models = [/Invoices/, /CreditNotes/, /BankTransactions/, /Receipts/]
-        self.unitdp == 4 && models.any?{ |m| request_url =~ m } ? {:unitdp => 4} : {}
-      end
+    # unitdp query string parameter to be added to request params
+    # when the application option has been set and the model has line items
+    # http://developer.xero.com/documentation/advanced-docs/rounding-in-xero/#unitamount
+    def unitdp_param(request_url)
+      models = [/Invoices/, /CreditNotes/, /BankTransactions/, /Receipts/]
+      self.unitdp == 4 && models.any?{ |m| request_url =~ m } ? {:unitdp => 4} : {}
+    end
 
   end
 end