xeroizer 0.2.0 → 0.2.1

data/README.md

@@ -465,4 +465,23 @@ Reports are accessed like the following example:
 				
 		end
 	end
-	
+
+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
+
+By default, the library will raise a `Xeroizer::OAuth::RateLimitExceeded`
+exception when one of these limits is exceeded.
+
+If required, the library can handle these exceptions internally by sleeping
+for a configurable number of seconds and then repeating the last request.
+You can set this option when initializing an application:
+
+    # Sleep for 2 seconds every time the rate limit is exceeded.
+    client = Xeroizer::PublicApplication.new(YOUR_OAUTH_CONSUMER_KEY,
+                                             YOUR_OAUTH_CONSUMER_SECRET,
+                                             :rate_limit_sleep => 2)

data/VERSION

@@ -1 +1 @@
-0.2.0
+0.2.1

data/lib/xeroizer.rb

@@ -1,7 +1,8 @@
 require 'rubygems'
 require 'date'
 require 'forwardable'
-require "active_support/inflector"
+require 'active_support/inflector'
+require 'active_support/memoizable'
 # require "active_support/core_ext"
 require 'oauth'
 require 'oauth/signature/rsa/sha1'
@@ -29,6 +30,7 @@ require 'xeroizer/models/account'
 require 'xeroizer/models/address'
 require 'xeroizer/models/branding_theme'
 require 'xeroizer/models/contact'
+require 'xeroizer/models/contact_group'
 require 'xeroizer/models/credit_note'
 require 'xeroizer/models/currency'
 require 'xeroizer/models/invoice'

data/lib/xeroizer/exceptions.rb

@@ -1,10 +1,13 @@
 module Xeroizer
   class ApiException < StandardError
     
-    def initialize(type, message, xml)
-      @type     = type
-      @message  = message
-      @xml      = xml
+    attr_reader :type, :message, :xml, :request_body
+    
+    def initialize(type, message, xml, request_body)
+      @type         = type
+      @message      = message
+      @xml          = xml
+      @request_body = request_body
     end
     
     def message

data/lib/xeroizer/generic_application.rb

@@ -6,7 +6,7 @@ module Xeroizer
     include Http
     extend Record::ApplicationHelper
     
-    attr_reader :client, :xero_url, :logger
+    attr_reader :client, :xero_url, :logger, :rate_limit_sleep, :rate_limit_max_attempts
     
     extend Forwardable
     def_delegators :client, :access_token
@@ -43,8 +43,10 @@ module Xeroizer
       # @see PartnerApplication
       def initialize(consumer_key, consumer_secret, options = {})
         @xero_url = options[:xero_url] || "https://api.xero.com/api.xro/2.0"
+        @rate_limit_sleep = options[:rate_limit_sleep] || false
+        @rate_limit_max_attempts = options[:rate_limit_max_attempts] || 5
         @client   = OAuth.new(consumer_key, consumer_secret, options)
       end
           
   end
-end
+end

data/lib/xeroizer/http.rb

@@ -64,34 +64,48 @@ module Xeroizer
         end
 
         uri   = URI.parse(url)
-        
-        logger.info("\n== [#{Time.now.to_s}] XeroGateway Request: #{uri.request_uri} ") if self.logger
-        
-        response = case method
-          when :get   then    client.get(uri.request_uri, headers)
-          when :post  then    client.post(uri.request_uri, { :xml => body }, headers)
-          when :put   then    client.put(uri.request_uri, { :xml => body }, headers)
-        end
-        
-        if self.logger
-          logger.info("== [#{Time.now.to_s}] XeroGateway Response (#{response.code})")
-          
-          unless response.code.to_i == 200
-            logger.info("== #{uri.request_uri} Response Body \n\n #{response.plain_body} \n == End Response Body")
+
+        attempts = 0
+
+        begin
+          attempts += 1
+          logger.info("\n== [#{Time.now.to_s}] XeroGateway Request: #{uri.request_uri} ") if self.logger
+
+          response = case method
+            when :get   then    client.get(uri.request_uri, headers)
+            when :post  then    client.post(uri.request_uri, { :xml => body }, headers)
+            when :put   then    client.put(uri.request_uri, { :xml => body }, headers)
           end
-        end
-        
-        case response.code.to_i
-          when 200
-            response.plain_body
-          when 400
-            handle_error!(response)  
-          when 401
-            handle_oauth_error!(response)
-          when 404
-            handle_object_not_found!(response, url)
+
+          if self.logger
+            logger.info("== [#{Time.now.to_s}] XeroGateway Response (#{response.code})")
+
+            unless response.code.to_i == 200
+              logger.info("== #{uri.request_uri} Response Body \n\n #{response.plain_body} \n == End Response Body")
+            end
+          end
+
+          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)
+            else
+              raise "Unknown response code: #{response.code.to_i}"
+          end
+        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 "Unknown response code: #{response.code.to_i}"
+            raise
+          end
         end
       end
        
@@ -111,7 +125,7 @@ module Xeroizer
         end
       end
       
-      def handle_error!(response)
+      def handle_error!(response, request_body)
         
         raw_response = response.plain_body
         
@@ -126,7 +140,8 @@ module Xeroizer
 
           raise ApiException.new(doc.root.xpath("Type").text, 
                                  doc.root.xpath("Message").text, 
-                                 raw_response)
+                                 raw_response,
+                                 request_body)
 
         else
           
@@ -143,6 +158,10 @@ module Xeroizer
           else raise ObjectNotFound.new(request_url)
         end
       end
+
+      def sleep_for(seconds = 1)
+        sleep seconds
+      end
       
   end
 end

data/lib/xeroizer/models/account.rb

@@ -35,10 +35,12 @@ module Xeroizer
         'RRINPUT' =>          'Reduced rate VAT on expenses (UK Only)', 
         'EXEMPTOUTPUT' =>     'VAT on sales exempt from VAT (UK only)',
         'OUTPUT' =>           'OUTPUT',
+        'OUTPUT2' =>          'OUTPUT2',
         'SROUTPUT' =>         'SROUTPUT',
         'ZERORATEDOUTPUT' =>  'Sales made from overseas (UK only)',
         'RROUTPUT' =>         'Reduced rate VAT on sales (UK Only)',
-        'ZERORATED' =>        'Zero-rated supplies/sales from overseas (NZ Only)'
+        'ZERORATED' =>        'Zero-rated supplies/sales from overseas (NZ Only)',
+        'ECZROUTPUT' =>       'Zero-rated EC Income (UK only)'
       } unless defined?(TAX_TYPE)
       
       set_primary_key :account_id

data/lib/xeroizer/models/contact.rb

@@ -36,6 +36,7 @@ module Xeroizer
       
       has_many  :addresses
       has_many  :phones
+      has_many  :contact_groups
       
       validates_presence_of :name
       validates_inclusion_of :contact_status, :in => CONTACT_STATUS.keys, :allow_blanks => true
@@ -43,4 +44,4 @@ module Xeroizer
     end
     
   end
-end
+end

data/lib/xeroizer/models/contact_group.rb

@@ -0,0 +1,16 @@
+module Xeroizer
+  module Record
+    
+    class ContactGroupModel < BaseModel      
+    end
+    
+    class ContactGroup < Base
+      
+      guid :contact_group_id
+      string :name
+      string :status
+      
+    end
+    
+  end
+end

data/lib/xeroizer/oauth.rb

@@ -61,7 +61,7 @@ module Xeroizer
     # 
     # @return [OAuth::Consumer] consumer object for GET/POST/PUT methods.
     def consumer
-      @consumer ||= create_consumer
+      create_consumer
     end
     
     # RequestToken for PUBLIC/PARTNER authorisation 
@@ -69,7 +69,7 @@ module Xeroizer
     #
     # @option params [String] :oauth_callback URL to redirect user to when they have authenticated your application with Xero. If not specified, the user will be shown an authorisation code on the screen that they need to get into your application.
     def request_token(params = {})
-      @request_token ||= consumer.get_request_token(params)
+      consumer.get_request_token(params)
     end
     
     # Create an AccessToken from a PUBLIC/PARTNER authorisation.
@@ -81,7 +81,7 @@ module Xeroizer
     
     # AccessToken created from authorize_from_access method.
     def access_token
-      @access_token ||= ::OAuth::AccessToken.new(consumer, @atoken, @asecret)
+      ::OAuth::AccessToken.new(consumer, @atoken, @asecret)
     end
     
     # Used for PRIVATE applications where the AccessToken uses the 

data/lib/xeroizer/record/base.rb

@@ -54,7 +54,7 @@ module Xeroizer
         end
         
         def new_record?
-          self.class.possible_primary_keys.all? { | key | @attributes[key].nil? }
+          id.nil?
         end
         
         # Check to see if the complete record is downloaded.
@@ -83,6 +83,13 @@ module Xeroizer
           end
           true
         end
+
+        def inspect
+          attribute_string = self.attributes.collect do |attr, value|
+            "#{attr.inspect}: #{value.inspect}"
+          end.join(", ")
+          "#<#{self.class} #{attribute_string}>"
+        end
                 
       protected
       
@@ -113,4 +120,4 @@ module Xeroizer
     end
     
   end
-end
+end

data/lib/xeroizer/record/base_model.rb

@@ -4,6 +4,8 @@ module Xeroizer
   module Record
     
     class BaseModel
+
+      extend ActiveSupport::Memoizable
       
       include ClassLevelInheritableAttributes
       class_inheritable_attributes :api_controller_name

data/lib/xeroizer/record/xml_helper.rb

@@ -85,7 +85,7 @@ module Xeroizer
 
               when :date
                 real_value = case value
-                  when Date         then 
+                  when Date         then value.strftime("%Y-%m-%d")
                   when Time         then value.utc.strftime("%Y-%m-%d")
                 end
                 b.tag!(field[:api_name], real_value)

data/lib/xeroizer/report/aged_receivables_by_contact.rb

@@ -0,0 +1,44 @@
+module Xeroizer
+  module Report
+    class AgedReceivablesByContact < Base
+
+      extend ActiveSupport::Memoizable
+
+      public
+
+        def total
+          summary.cell(:Total).value 
+        end
+
+        def total_paid
+          summary.cell(:Paid).value
+        end
+
+        def total_credited
+          summary.cell(:Credited).value
+        end
+
+        def total_due
+          summary.cell(:Due).value
+        end
+
+        def total_overdue
+          now = Time.now
+          sum(:Due) do | row | 
+            due_date = row.cell('Due Date').value
+            due_date && due_date < now
+          end
+        end
+
+        def sum(column_name, &block)
+          sections.first.rows.inject(BigDecimal.new('0')) do | sum, row |
+            cell = row.cell(column_name)
+            sum += row.cell(column_name).value if row.class == Xeroizer::Report::Row && (block.nil? || block.call(row))
+            sum
+          end
+        end
+        memoize :total, :total_paid, :total_credited, :total_due, :total_overdue, :sum
+      
+    end
+  end
+end

data/lib/xeroizer/report/base.rb

@@ -40,4 +40,4 @@ module Xeroizer
                   
     end
   end
-end
+end

data/lib/xeroizer/report/cell_xml_helper.rb

@@ -32,7 +32,7 @@ module Xeroizer
             cell = new
             node.elements.each do | element |
               case element.name.to_s
-                when 'Value' then cell.value = potentially_convert_to_number(element.text)
+                when 'Value' then cell.value = parse_value(element.text)
                 when 'Attributes'
                   element.elements.each do | attribute_node |
                     (id, value) = parse_attribute(attribute_node)
@@ -44,12 +44,15 @@ module Xeroizer
           end
           
         protected
-        
-          # If a cell's value is a valid number then return it is as BigDecimal.
-          def potentially_convert_to_number(value)
-            value =~ /^[-]?\d+(\.\d+)?$/ ? BigDecimal.new(value) : value
+
+          def parse_value(value)
+            case value
+              when /^[-]?\d+(\.\d+)?$/                      then BigDecimal.new(value)
+              when /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}$/  then Time.xmlschema(value)
+              else                                          value
+            end
           end
-          
+        
           def parse_attribute(attribute_node)
             id = nil
             value = nil
@@ -68,4 +71,4 @@ module Xeroizer
     
     end
   end
-end
+end

data/lib/xeroizer/report/factory.rb

@@ -1,10 +1,12 @@
 require 'xeroizer/application_http_proxy' 
 require 'xeroizer/report/base'
+require 'xeroizer/report/aged_receivables_by_contact'
 
 module Xeroizer
   module Report
     class Factory
       
+      extend ActiveSupport::Memoizable
       include ApplicationHttpProxy
 
       attr_reader :application
@@ -27,17 +29,26 @@ module Xeroizer
         end
       
         def api_controller_name
-          "Report/#{report_type}"
+          "Reports/#{report_type}"
         end
 
+        def klass
+          begin
+            Xeroizer::Report.const_get(report_type)
+          rescue NameError => ex # use default class
+            Base
+          end
+        end
+        memoize :klass
+
       protected
               
         def parse_reports(response, elements)
           elements.each do | element |
-            response.response_items << Base.build_from_node(element, self)
+            response.response_items << klass.build_from_node(element, self)
           end
         end
         
     end
   end
-end
+end

data/lib/xeroizer/report/row/header.rb

@@ -1,7 +1,12 @@
 module Xeroizer
   module Report
     class HeaderRow < Row
-            
+
+        def column_index(column_name)
+          cells.find_index { | cell | cell.value == column_name.to_s }
+        end
+        memoize :column_index
+        
     end
   end
-end
+end

data/lib/xeroizer/report/row/row.rb

@@ -4,6 +4,7 @@ module Xeroizer
   module Report
     class Row
       
+      extend ActiveSupport::Memoizable
       include RowXmlHelper
       
       attr_reader :report
@@ -37,7 +38,12 @@ module Xeroizer
         def parent?
           rows.size > 0
         end
-        
+
+        def cell(column_name)
+          index = header.column_index(column_name)
+          cells[index] if index >= 0
+        end
+
     end
   end
-end
+end

data/test/test_helper.rb

@@ -51,7 +51,7 @@ module TestHelper
   end
   
   def mock_report_api(report_type)
-    @client.stubs(:http_get).with { | client, url, params | url =~ /Report\/#{report_type}$/ }.returns(get_report_xml(report_type))
+    @client.stubs(:http_get).with { | client, url, params | url =~ /Reports\/#{report_type}$/ }.returns(get_report_xml(report_type))
   end
     
-end
+end

data/test/unit/oauth_test.rb

@@ -33,13 +33,38 @@ class OAuthTest < Test::Unit::TestCase
       end
     end
       
-    should "handle rate limit exceeded" do
+    should "raise rate limit exceeded" do
       Xeroizer::OAuth.any_instance.stubs(:get).returns(stub(:plain_body => get_file_as_string("rate_limit_exceeded"), :code => "401"))
       
       assert_raises Xeroizer::OAuth::RateLimitExceeded do
         @client.Organisation.first
       end
     end
+
+    should "automatically handle rate limit exceeded" do
+      auto_rate_limit_client = Xeroizer::PublicApplication.new(CONSUMER_KEY, CONSUMER_SECRET, :rate_limit_sleep => 1)
+
+      # Return rate limit exceeded on first call, OK on the second
+      Xeroizer::OAuth.any_instance.stubs(:get).returns(
+        stub(:plain_body => get_file_as_string("rate_limit_exceeded"), :code => "401"),
+        stub(:plain_body => get_record_xml(:organisation), :code => '200')
+      )
+
+      auto_rate_limit_client.expects(:sleep_for).with(1).returns(1)
+
+      auto_rate_limit_client.Organisation.first
+    end
+
+    should "only retry rate limited request a configurable number of times" do
+      auto_rate_limit_client = Xeroizer::PublicApplication.new(CONSUMER_KEY, CONSUMER_SECRET, :rate_limit_sleep => 1, :rate_limit_max_attempts => 4)
+      Xeroizer::OAuth.any_instance.stubs(:get).returns(stub(:plain_body => get_file_as_string("rate_limit_exceeded"), :code => "401"))
+
+      auto_rate_limit_client.expects(:sleep_for).with(1).times(4).returns(1)
+
+      assert_raises Xeroizer::OAuth::RateLimitExceeded do
+        auto_rate_limit_client.Organisation.first
+      end
+    end
       
     should "handle unknown errors" do
       Xeroizer::OAuth.any_instance.stubs(:get).returns(stub(:plain_body => get_file_as_string("bogus_oauth_error"), :code => "401"))
@@ -69,4 +94,4 @@ class OAuthTest < Test::Unit::TestCase
     
   end
   
-end
+end

data/test/unit/record/base_test.rb

@@ -41,12 +41,12 @@ class RecordBaseTest < Test::Unit::TestCase
       assert(@contact.contact_id =~ GUID_REGEX, "@contact.contact_id is not a GUID, it is '#{@contact.contact_id}'")
     end
     
-    should "new_record? should be false if we have specifid a primary key" do
+    should "new_record? should be false if we have specified a primary key" do
       contact = @client.Contact.build(:contact_id => 'ABC')
       assert_equal(false, contact.new_record?)
       
       contact = @client.Contact.build(:contact_number => 'CDE')
-      assert_equal(false, contact.new_record?)
+      assert_equal(true, contact.new_record?)
       
       contact = @client.Contact.build(:name => 'TEST NAME')
       assert_equal(true, contact.new_record?)

data/test/unit/report_test.rb

@@ -17,7 +17,7 @@ class FactoryTest < Test::Unit::TestCase
         :BudgetSummary, :ExecutiveSummary, :ProfitAndLoss, :TrialBalance
       ].each do | report_type |
         report_factory = @client.send(report_type)
-        assert_equal("Report/#{report_type}", report_factory.api_controller_name)
+        assert_equal("Reports/#{report_type}", report_factory.api_controller_name)
       end
     end
     
@@ -142,4 +142,4 @@ class FactoryTest < Test::Unit::TestCase
       end
     end
     
-end
+end

data/xeroizer.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = %q{xeroizer}
-  s.version = "0.2.0"
+  s.version = "0.2.1"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Wayne Robinson"]
-  s.date = %q{2011-03-23}
+  s.date = %q{2011-05-05}
   s.description = %q{Ruby library for the Xero accounting system API.}
   s.email = %q{wayne.robinson@gmail.com}
   s.extra_rdoc_files = [
@@ -39,6 +39,7 @@ Gem::Specification.new do |s|
     "lib/xeroizer/models/address.rb",
     "lib/xeroizer/models/branding_theme.rb",
     "lib/xeroizer/models/contact.rb",
+    "lib/xeroizer/models/contact_group.rb",
     "lib/xeroizer/models/credit_note.rb",
     "lib/xeroizer/models/currency.rb",
     "lib/xeroizer/models/invoice.rb",
@@ -72,6 +73,7 @@ Gem::Specification.new do |s|
     "lib/xeroizer/record/validators/presence_of_validator.rb",
     "lib/xeroizer/record/validators/validator.rb",
     "lib/xeroizer/record/xml_helper.rb",
+    "lib/xeroizer/report/aged_receivables_by_contact.rb",
     "lib/xeroizer/report/base.rb",
     "lib/xeroizer/report/cell.rb",
     "lib/xeroizer/report/cell_xml_helper.rb",

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: xeroizer
 version: !ruby/object:Gem::Version 
-  hash: 23
+  hash: 21
   prerelease: 
   segments: 
   - 0
   - 2
-  - 0
-  version: 0.2.0
+  - 1
+  version: 0.2.1
 platform: ruby
 authors: 
 - Wayne Robinson
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-03-23 00:00:00 +10:00
+date: 2011-05-05 00:00:00 +10:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -214,6 +214,7 @@ files:
 - lib/xeroizer/models/address.rb
 - lib/xeroizer/models/branding_theme.rb
 - lib/xeroizer/models/contact.rb
+- lib/xeroizer/models/contact_group.rb
 - lib/xeroizer/models/credit_note.rb
 - lib/xeroizer/models/currency.rb
 - lib/xeroizer/models/invoice.rb
@@ -247,6 +248,7 @@ files:
 - lib/xeroizer/record/validators/presence_of_validator.rb
 - lib/xeroizer/record/validators/validator.rb
 - lib/xeroizer/record/xml_helper.rb
+- lib/xeroizer/report/aged_receivables_by_contact.rb
 - lib/xeroizer/report/base.rb
 - lib/xeroizer/report/cell.rb
 - lib/xeroizer/report/cell_xml_helper.rb