xero_gateway 2.0.2

data/lib/xero_gateway/line_item.rb

@@ -0,0 +1,123 @@
+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, :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: 
+    #  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
+    end
+    
+    def to_xml(b = Builder::XmlMarkup.new)
+      b.LineItem {
+        b.Description description
+        b.Quantity quantity if quantity
+        b.UnitAmount LineItem.format_money(unit_amount)
+        b.TaxType tax_type if tax_type
+        b.TaxAmount tax_amount if tax_amount
+        b.LineAmount line_amount if line_amount
+        b.AccountCode account_code if account_code
+        if has_tracking?
+          b.Tracking {
+            # Due to strange retardness in the Xero API, the XML structure for a tracking category within
+            # an invoice is different to a standalone tracking category.
+            # This means rather than going category.to_xml we need to call the special category.to_xml_for_invoice_messages
+            (tracking.is_a?(TrackingCategory) ? [tracking] : tracking).each do |category|
+              category.to_xml_for_invoice_messages(b)
+            end
+          }
+        end
+      }
+    end
+    
+    def self.from_xml(line_item_element)
+      line_item = LineItem.new
+      line_item_element.children.each do |element|
+        case(element.name)
+          when "LineItemID" then line_item.line_item_id = element.text
+          when "Description" then line_item.description = element.text
+          when "Quantity" then line_item.quantity = element.text.to_i
+          when "UnitAmount" then line_item.unit_amount = BigDecimal.new(element.text)
+          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 "AccountCode" then line_item.account_code = element.text
+          when "Tracking" then
+            element.children.each do | tracking_element |
+              line_item.tracking << TrackingCategory.from_xml(tracking_element)
+            end
+        end
+      end
+      line_item
+    end    
+
+    def ==(other)
+      [:description, :quantity, :unit_amount, :tax_type, :tax_amount, :line_amount, :account_code].each do |field|
+        return false if send(field) != other.send(field)
+      end
+      return true
+    end
+  end  
+end

data/lib/xero_gateway/money.rb

@@ -0,0 +1,16 @@
+module XeroGateway
+  module Money
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+    
+    module ClassMethods
+      def format_money(amount)
+        if amount.class == BigDecimal
+          return amount.to_s("F")
+        end
+        return amount
+      end
+    end
+  end
+end

data/lib/xero_gateway/oauth.rb

@@ -0,0 +1,56 @@
+module XeroGateway
+  
+  # Shamelessly based on the Twitter Gem's OAuth implementation by John Nunemaker
+  # Thanks!
+  # 
+  # http://twitter.rubyforge.org/
+  # http://github.com/jnunemaker/twitter/
+  
+  class OAuth
+    
+    class TokenExpired < StandardError; end
+    class TokenInvalid < StandardError; end
+        
+    unless defined? XERO_CONSUMER_OPTIONS
+      XERO_CONSUMER_OPTIONS = {
+        :site               => "https://api.xero.com",
+        :request_token_path => "/oauth/RequestToken",
+        :access_token_path  => "/oauth/AccessToken",
+        :authorize_path     => "/oauth/Authorize"
+      }.freeze
+    end
+    
+    extend Forwardable
+    def_delegators :access_token, :get, :post, :put, :delete
+    
+    attr_reader :ctoken, :csecret, :consumer_options
+    
+    def initialize(ctoken, csecret, options = {})
+      @ctoken, @csecret = ctoken, csecret
+      @consumer_options = XERO_CONSUMER_OPTIONS.merge(options)
+    end
+    
+    def consumer
+      @consumer ||= ::OAuth::Consumer.new(@ctoken, @csecret, consumer_options)
+    end
+    
+    def request_token(params = {})
+      @request_token ||= consumer.get_request_token(params)
+    end
+    
+    def authorize_from_request(rtoken, rsecret, params = {})
+      request_token     = ::OAuth::RequestToken.new(consumer, rtoken, rsecret)
+      access_token      = request_token.get_access_token(params)
+      @atoken, @asecret = access_token.token, access_token.secret
+    end
+    
+    def access_token
+      @access_token ||= ::OAuth::AccessToken.new(consumer, @atoken, @asecret)
+    end
+    
+    def authorize_from_access(atoken, asecret)
+      @atoken, @asecret = atoken, asecret
+    end
+    
+  end
+end

data/lib/xero_gateway/organisation.rb

@@ -0,0 +1,61 @@
+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
+        "APIKey"           => :string      # UNDOCUMENTED paramater, returned if organisations are linked via Xero Network
+      }
+    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
+        
+          raise "Unknown attribute: #{attribute}" unless 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
+          
+        end
+      end
+    end
+    
+  end
+end

data/lib/xero_gateway/payment.rb

@@ -0,0 +1,40 @@
+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 :date, :amount
+        
+    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 'Date' then    payment.date = parse_date_time(element.text)
+          when 'Amount' then  payment.amount = BigDecimal.new(element.text)
+        end    
+      end
+      payment
+    end 
+    
+    def ==(other)
+      [: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,37 @@
+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 :contact,      :response_item
+    alias_method :organisation, :response_item
+    alias_method :invoices,     :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