xero_gateway-n8vision 2.0.20

data/lib/xero_gateway/organisation.rb

@@ -0,0 +1,75 @@
+module XeroGateway
+  class Organisation
+    
+    unless defined? ATTRS
+      ATTRS = {
+        "Name" 	                => :string,     # Display name of organisation shown in Xero
+        "LegalName"             => :string,	   # Organisation name shown on Reports
+        "PaysTax" 	            => :boolean,    # Boolean to describe if organisation is registered with a local tax authority i.e. true, false
+        "Version"   	          => :string,     # See Version Types
+        "BaseCurrency"          => :string,     # Default currency for organisation. See Currency types
+        "OrganisationType"      => :string,     # UNDOCUMENTED parameter, only returned for "real" (i.e non-demo) companies
+        "OrganisationStatus"    => :string,   # UNDOCUMENTED parameter
+        "IsDemoCompany"         => :boolean,    # UNDOCUMENTED parameter
+        "APIKey"                => :string,     # UNDOCUMENTED paramater, returned if organisations are linked via Xero Network
+        "CountryCode"           => :string,      # UNDOCUMENTED parameter
+        "TaxNumber"             => :string,
+        "FinancialYearEndDay"   => :string,
+        "FinancialYearEndMonth" => :string,
+        "PeriodLockDate"        => :string,
+        "CreatedDateUTC"        => :string        
+      }
+    end
+    
+    attr_accessor *ATTRS.keys.map(&:underscore)
+    
+    def initialize(params = {})
+      params.each do |k,v|
+        self.send("#{k}=", v)
+      end
+    end
+    
+    def ==(other)
+      ATTRS.keys.map(&:underscore).each do |field|
+        return false if send(field) != other.send(field)
+      end
+      return true
+    end
+    
+    def to_xml
+      b = Builder::XmlMarkup.new
+      
+      b.Organisation do
+        ATTRS.keys.each do |attr|
+          eval("b.#{attr} '#{self.send(attr.underscore.to_sym)}'")
+        end
+      end
+    end
+    
+    def self.from_xml(organisation_element)
+      Organisation.new.tap do |org|
+        organisation_element.children.each do |element|
+        
+          attribute             = element.name
+          underscored_attribute = element.name.underscore
+        
+          if ATTRS.keys.include?(attribute)
+                  
+            case (ATTRS[attribute])
+              when :boolean then  org.send("#{underscored_attribute}=", (element.text == "true"))
+              when :float   then  org.send("#{underscored_attribute}=", element.text.to_f)
+              else                org.send("#{underscored_attribute}=", element.text)
+            end
+            
+          else
+            
+            warn "Ignoring unknown attribute: #{attribute}" 
+            
+          end
+          
+        end
+      end
+    end
+    
+  end
+end

data/lib/xero_gateway/partner_app.rb

@@ -0,0 +1,30 @@
+module XeroGateway
+  class PartnerApp < Gateway
+    
+    class CertificateRequired < StandardError; end
+    
+    NO_SSL_CLIENT_CERT_MESSAGE   = "You need to provide a client ssl certificate and key pair (these are the ones you got from Entrust and should not be password protected) as :ssl_client_cert and :ssl_client_key (should be .crt or .pem files)"
+    NO_PRIVATE_KEY_ERROR_MESSAGE = "You need to provide your private key (corresponds to the public key you uploaded at api.xero.com) as :private_key_file (should be .crt or .pem files)"
+    
+    def_delegators :client, :session_handle, :renew_access_token
+     
+    def initialize(consumer_key, consumer_secret, options = {})
+      
+      raise CertificateRequired.new(NO_SSL_CLIENT_CERT_MESSAGE)   unless options[:ssl_client_cert]
+      raise CertificateRequired.new(NO_SSL_CLIENT_CERT_MESSAGE)   unless options[:ssl_client_key]
+      raise CertificateRequired.new(NO_PRIVATE_KEY_ERROR_MESSAGE) unless options[:private_key_file]
+      
+      options.merge!(
+        :site             => "https://api-partner.network.xero.com",
+        :authorize_url    => 'https://api.xero.com/oauth/Authorize', 
+        :signature_method => 'RSA-SHA1',
+        :ssl_client_cert  => OpenSSL::X509::Certificate.new(File.read(options[:ssl_client_cert])),
+        :ssl_client_key   => OpenSSL::PKey::RSA.new(File.read(options[:ssl_client_key])),
+        :private_key_file => options[:private_key_file]
+      )
+      
+      @xero_url = options[:xero_url] || "https://api-partner.xero.com/api.xro/2.0"  
+      @client   = OAuth.new(consumer_key, consumer_secret, options)
+    end
+  end
+end

data/lib/xero_gateway/payment.rb

@@ -0,0 +1,43 @@
+module XeroGateway
+  class Payment
+    include Money
+    include Dates
+
+    # Any errors that occurred when the #valid? method called.
+    attr_reader :errors
+
+    # All accessible fields
+    attr_accessor :payment_id, :date, :amount, :reference, :currency_rate
+        
+    def initialize(params = {})
+      @errors ||= []
+            
+      params.each do |k,v|
+        self.send("#{k}=", v)
+      end
+    end
+    
+    def self.from_xml(payment_element)
+      payment = Payment.new
+      payment_element.children.each do | element |
+        case element.name
+          when 'PaymentID'    then payment.payment_id = element.text
+          when 'Date'         then payment.date = parse_date_time(element.text)
+          when 'Amount'       then payment.amount = BigDecimal.new(element.text)
+          when 'Reference'    then payment.reference = element.text
+          when 'CurrencyRate' then payment.currency_rate = BigDecimal.new(element.text)
+        end    
+      end
+      payment
+    end 
+    
+    def ==(other)
+      [:payment_id, :date, :amount].each do |field|
+        return false if send(field) != other.send(field)
+      end
+      return true
+    end
+    
+
+  end
+end

data/lib/xero_gateway/phone.rb

@@ -0,0 +1,77 @@
+module XeroGateway
+  class Phone
+    
+    PHONE_TYPE = {
+      'DEFAULT' =>    'Default',
+      'DDI' =>        'Direct Dial-In',
+      'MOBILE' =>     'Mobile',
+      'FAX' =>        'Fax'
+    } unless defined?(PHONE_TYPE)
+    
+    # Any errors that occurred when the #valid? method called.
+    attr_reader :errors
+
+    attr_accessor :phone_type, :number, :area_code, :country_code
+    
+    def initialize(params = {})
+      @errors ||= []
+      
+      params = {
+        :phone_type => "DEFAULT"
+      }.merge(params)
+      
+      params.each do |k,v|
+        self.send("#{k}=", v)
+      end
+    end
+    
+    # Validate the Phone record according to what will be valid by the gateway.
+    #
+    # Usage: 
+    #  phone.valid?     # Returns true/false
+    #  
+    #  Additionally sets phone.errors array to an array of field/error.
+    def valid?
+      @errors = []
+            
+      unless number
+        @errors << ['number', "can't be blank"]
+      end
+      
+      if phone_type && !PHONE_TYPE[phone_type]
+        @errors << ['phone_type', "must be one of #{PHONE_TYPE.keys.join('/')}"]
+      end
+      
+      @errors.size == 0
+    end
+    
+    def to_xml(b = Builder::XmlMarkup.new)
+      b.Phone {
+        b.PhoneType phone_type
+        b.PhoneNumber number
+        b.PhoneAreaCode area_code if area_code
+        b.PhoneCountryCode country_code if country_code
+      }
+    end
+    
+    def self.from_xml(phone_element)
+      phone = Phone.new
+      phone_element.children.each do |element|
+        case(element.name)
+          when "PhoneType" then phone.phone_type = element.text
+          when "PhoneNumber" then phone.number = element.text
+          when "PhoneAreaCode" then phone.area_code = element.text
+          when "PhoneCountryCode" then phone.country_code = element.text      
+        end
+      end
+      phone
+    end
+    
+    def ==(other)
+      [:phone_type, :number, :area_code, :country_code].each do |field|
+        return false if send(field) != other.send(field)
+      end
+      return true
+    end    
+  end
+end

data/lib/xero_gateway/private_app.rb

@@ -0,0 +1,17 @@
+module XeroGateway
+  class PrivateApp < Gateway
+    #
+    # The consumer key and secret here correspond to those provided
+    # 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"
+      @client   = OAuth.new(consumer_key, consumer_secret, options)
+      @client.authorize_from_access(consumer_key, consumer_secret)
+    end
+  end
+end

data/lib/xero_gateway/response.rb

@@ -0,0 +1,43 @@
+module XeroGateway
+  class Response
+    attr_accessor :response_id, :status, :errors, :provider, :date_time, :response_item, :request_params, :request_xml, :response_xml
+    
+    def array_wrapped_response_item
+      Array(response_item)
+    end
+    
+    alias_method :invoice,              :response_item
+    alias_method :credit_note,          :response_item
+    alias_method :bank_transaction,     :response_item
+    alias_method :manual_journal,       :response_item
+    alias_method :contact,              :response_item
+    alias_method :organisation,         :response_item
+    alias_method :invoices,             :array_wrapped_response_item
+    alias_method :credit_notes,         :array_wrapped_response_item
+    alias_method :bank_transactions,    :array_wrapped_response_item
+    alias_method :manual_journals,      :array_wrapped_response_item
+    alias_method :contacts,             :array_wrapped_response_item
+    alias_method :accounts,             :array_wrapped_response_item
+    alias_method :tracking_categories,  :array_wrapped_response_item
+    alias_method :tax_rates,            :array_wrapped_response_item
+    alias_method :currencies,           :array_wrapped_response_item
+    
+    def initialize(params = {})
+      params.each do |k,v|
+        self.send("#{k}=", v)
+      end
+      
+      @errors ||= []
+      @response_item ||= []
+    end
+    
+    
+    def success?
+      status == "OK"
+    end
+    
+    def error
+      errors.blank? ? nil : errors[0]
+    end
+  end
+end

data/lib/xero_gateway/tax_rate.rb

@@ -0,0 +1,63 @@
+module XeroGateway
+  class TaxRate
+    
+    unless defined? ATTRS
+      ATTRS = {
+        "Name"                  => :string, 
+        "TaxType"               => :string,
+        "CanApplyToAssets"      => :boolean,
+        "CanApplyToEquity"      => :boolean,
+        "CanApplyToExpenses"    => :boolean,
+        "CanApplyToLiabilities" => :boolean,
+        "CanApplyToRevenue"     => :boolean,
+        "DisplayTaxRate"        => :float,
+        "EffectiveRate"         => :float
+      }
+    end
+    
+    attr_accessor *ATTRS.keys.map(&:underscore)
+    
+    def initialize(params = {})
+      params.each do |k,v|
+        self.send("#{k}=", v)
+      end
+    end
+    
+    def ==(other)
+      ATTRS.keys.map(&:underscore).each do |field|
+        return false if send(field) != other.send(field)
+      end
+      return true
+    end
+    
+    def to_xml
+      b = Builder::XmlMarkup.new
+      
+      b.TaxRate do
+        ATTRS.keys.each do |attr|
+          eval("b.#{attr} '#{self.send(attr.underscore.to_sym)}'")
+        end
+      end
+    end
+    
+    def self.from_xml(tax_rate_element)
+      TaxRate.new.tap do |tax_rate|
+        tax_rate_element.children.each do |element|
+        
+          attribute             = element.name
+          underscored_attribute = element.name.underscore
+        
+          raise "Unknown attribute: #{attribute}" unless ATTRS.keys.include?(attribute)
+        
+          case (ATTRS[attribute])
+            when :boolean then  tax_rate.send("#{underscored_attribute}=", (element.text == "true"))
+            when :float   then  tax_rate.send("#{underscored_attribute}=", element.text.to_f)
+            else                tax_rate.send("#{underscored_attribute}=", element.text)
+          end
+          
+        end
+      end
+    end
+    
+  end
+end

data/lib/xero_gateway/tracking_category.rb

@@ -0,0 +1,87 @@
+# Tacking categories look like:
+#
+# <TrackingCategory>
+#   <Name>Region</Name>
+#   <Status>ACTIVE</Status>
+#   <TrackingCategoryID>e4a95e64-ebaa-401e-81cf-b625c7532d01</TrackingCategoryID>
+#   <Options>
+#     <Option>
+#       <TrackingOptionID>ea7f7b6a-0d22-4d5c-9317-54542a10215e</TrackingOptionID>
+#       <Name>North</Name>
+#     </Option>
+#     <Option>
+#       <TrackingOptionID>8e8b8d7b-fa75-4b24-b429-8cbc1a21af23</TrackingOptionID>
+#       <Name>South</Name>
+#     </Option>
+#   </Options>
+# </TrackingCategory>
+#
+module XeroGateway
+  class TrackingCategory
+    attr_accessor :tracking_category_id, :name, :options
+    
+    def initialize(params = {})
+      @options = []
+      params.each do |k,v|
+        self.send("#{k}=", v)
+      end
+    end
+    
+    def option
+       options[0] if options.size == 1
+    end
+        
+    def to_xml(b = Builder::XmlMarkup.new)
+      b.TrackingCategory {
+        b.TrackingCategoryID tracking_category_id unless tracking_category_id.nil?
+        b.Name self.name
+        b.Options {
+          if self.options.is_a?(Array)
+            self.options.each do |option|
+              b.Option {
+                b.Name option
+              }
+            end
+          else
+            b.Option {
+              b.Name self.options.to_s
+            }            
+          end
+        }
+      }
+    end
+    
+    # When a tracking category is serialized as part of an invoice it may only have a single
+    # option, and the Options tag is omitted
+    def to_xml_for_invoice_messages(b = Builder::XmlMarkup.new)
+      b.TrackingCategory {
+        b.TrackingCategoryID self.tracking_category_id unless tracking_category_id.nil?
+        b.Name self.name
+        b.Option self.options.is_a?(Array) ? self.options.first : self.options.to_s 
+      }      
+    end
+    
+    def self.from_xml(tracking_category_element)
+      tracking_category = TrackingCategory.new
+      tracking_category_element.children.each do |element|
+        case(element.name)
+          when "TrackingCategoryID" then tracking_category.tracking_category_id = element.text
+          when "Name" then tracking_category.name = element.text
+          when "Options" then
+            element.children.each do |option_child|
+              tracking_category.options << option_child.children.detect {|c| c.name == "Name"}.text
+            end
+          when "Option" then tracking_category.options << element.text
+        end
+      end
+      tracking_category              
+    end  
+    
+    def ==(other)
+      [:tracking_category_id, :name, :options].each do |field|
+        return false if send(field) != other.send(field)
+      end
+      return true
+    end      
+  end
+end

data/test/integration/accounts_list_test.rb

@@ -0,0 +1,109 @@
+require File.dirname(__FILE__) + '/../test_helper'
+
+class AccountsListTest < Test::Unit::TestCase
+  include TestHelper
+  
+  def setup
+    @gateway = XeroGateway::Gateway.new(CONSUMER_KEY, CONSUMER_SECRET)
+    
+    # Always stub out calls for this integration test as we need to be able to control the data.
+    @gateway.xero_url = "DUMMY_URL"    
+    
+    @gateway.stubs(:http_get).with {|client, url, params| url =~ /Accounts$/ }.returns(get_file_as_string("accounts.xml"))
+  end
+  
+  def test_get_accounts_list
+    accounts_list = @gateway.get_accounts_list
+    assert_not_equal(0, accounts_list.accounts.size)
+  end  
+  
+  # Make sure that the list is loaded when finding things.
+  def test_raise_error_on_not_loaded
+    accounts_list = @gateway.get_accounts_list(false)
+    assert_equal(false, accounts_list.loaded?)
+    assert_raise(XeroGateway::AccountsListNotLoadedError) { accounts_list[200] }
+    assert_raise(XeroGateway::AccountsListNotLoadedError) { accounts_list.find_by_code(200) }
+    assert_raise(XeroGateway::AccountsListNotLoadedError) { accounts_list.find_all_by_type('EXPENSE') }
+    assert_raise(XeroGateway::AccountsListNotLoadedError) { accounts_list.find_all_by_tax_type('OUTPUT') }
+  end
+  
+  # Test simple lookup by account code (from cache).
+  def test_simple_lookup_by_account_code
+    accounts_list = @gateway.get_accounts_list
+    assert_equal(true, accounts_list.loaded?)
+    
+    # Load data in the stubbed response.
+    expected_accounts = accounts_as_array
+    
+    # Make sure that every single expected account exists in the cached lookup hash.
+    expected_accounts.each do | expected_account |
+      found_account = accounts_list.find_by_code(expected_account.code)
+      assert_kind_of(XeroGateway::Account, found_account)
+      assert(expected_account == found_account, "Found account does not match expected account.")
+
+      found_account_shortcut = accounts_list[expected_account.code]
+      assert_kind_of(XeroGateway::Account, found_account_shortcut)
+      assert(expected_account == found_account_shortcut, "Found account does not match expected account (shortcut).")
+    end
+  end
+  
+  # Test finding accounts by their account type (from cache).
+  def test_lookup_by_account_type
+    accounts_list = @gateway.get_accounts_list
+    assert_equal(true, accounts_list.loaded?)
+    
+    # Load data in the stubbed response.
+    expected_accounts = accounts_as_array
+
+    # Get all the unique account types present in the expected accounts data along with their counts.
+    unique_types = expected_accounts.inject({}) do | list, account | 
+      list[account.type] = 0 if list[account.type].nil?
+      list[account.type] += 1
+      list
+    end
+    
+    assert_not_equal(0, unique_types)
+    unique_types.each do | account_type, count |
+      found_accounts = accounts_list.find_all_by_type(account_type)
+      assert_equal(count, found_accounts.size)
+      found_accounts.each do | found_account | 
+        assert_kind_of(XeroGateway::Account, found_account)
+        assert_equal(account_type, found_account.type)
+      end
+    end    
+  end
+
+  # Test finding accounts by their tax type (from cache).
+  def test_lookup_by_tax_type
+    accounts_list = @gateway.get_accounts_list
+    assert_equal(true, accounts_list.loaded?)
+    
+    # Load data in the stubbed response.
+    expected_accounts = accounts_as_array
+
+    # Get all the unique tax types present in the expected accounts data along with their counts.
+    unique_types = expected_accounts.inject({}) do | list, account | 
+      list[account.tax_type] = 0 if list[account.tax_type].nil?
+      list[account.tax_type] += 1
+      list
+    end
+    
+    assert_not_equal(0, unique_types)
+    unique_types.each do | tax_type, count |
+      found_accounts = accounts_list.find_all_by_tax_type(tax_type)
+      assert_equal(count, found_accounts.size)
+      found_accounts.each do | found_account | 
+        assert_kind_of(XeroGateway::Account, found_account)
+        assert_equal(tax_type, found_account.tax_type)
+      end
+    end    
+  end
+  
+  private
+  
+    def accounts_as_array
+      response = @gateway.__send__(:parse_response, get_file_as_string("accounts.xml"))
+      response.accounts
+    end
+  
+end