xero_gateway-n8vision 2.0.20

data/lib/xero_gateway/line_item.rb

@@ -0,0 +1,125 @@
+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
+        
+    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.ItemCode item_code if item_code
+        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 = BigDecimal(element.text)
+          when "UnitAmount" then line_item.unit_amount = BigDecimal.new(element.text)
+          when "ItemCode" then line_item.item_code = 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, :item_code].each do |field|
+        return false if send(field) != other.send(field)
+      end
+      return true
+    end
+  end  
+end

data/lib/xero_gateway/line_item_calculations.rb

@@ -0,0 +1,51 @@
+module XeroGateway
+  module LineItemCalculations
+    def add_line_item(params = {})
+      line_item = nil
+      case params
+        when Hash then      line_item = LineItem.new(params)
+        when LineItem then  line_item = params
+        else                raise InvalidLineItemError
+      end
+      @line_items << line_item
+      line_item
+    end
+
+    # Deprecated (but API for setter remains).
+    #
+    # As sub_total must equal SUM(line_item.line_amount) for the API call to pass, this is now
+    # automatically calculated in the sub_total method.
+    def sub_total=(value)
+    end
+
+    # Calculate the sub_total as the SUM(line_item.line_amount).
+    def sub_total
+      line_items.inject(BigDecimal.new('0')) { | sum, line_item | sum + BigDecimal.new(line_item.line_amount.to_s) }
+    end
+
+    # Deprecated (but API for setter remains).
+    #
+    # As total_tax must equal SUM(line_item.tax_amount) for the API call to pass, this is now
+    # automatically calculated in the total_tax method.
+    def total_tax=(value)
+    end
+
+    # Calculate the total_tax as the SUM(line_item.tax_amount).
+    def total_tax
+      line_items.inject(BigDecimal.new('0')) { | sum, line_item | sum + BigDecimal.new(line_item.tax_amount.to_s) }
+    end
+
+    # Deprecated (but API for setter remains).
+    #
+    # As total must equal sub_total + total_tax for the API call to pass, this is now
+    # automatically calculated in the total method.
+    def total=(value)
+    end
+
+    # Calculate the toal as sub_total + total_tax.
+    def total
+      sub_total + total_tax
+    end
+
+  end
+end

data/lib/xero_gateway/manual_journal.rb

@@ -0,0 +1,163 @@
+module XeroGateway
+  class ManualJournal
+  	include Dates
+
+    GUID_REGEX = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/ unless defined?(GUID_REGEX)
+
+    STATUSES = {
+      'DRAFT' 	=> 'Draft Manual Journal',
+      'POSTED' 	=> 'Posted Manual Journal',
+      'DELETED' => 'Deleted Draft Manual Journal',
+      'VOIDED'	=> 'Voided Posted Manual Journal'
+    } unless defined?(STATUSES)
+
+    # Xero::Gateway associated with this invoice.
+    attr_accessor :gateway
+
+    # Any errors that occurred when the #valid? method called.
+    attr_reader :errors
+
+    # Represents whether the journal lines have been downloaded when getting from GET /API.XRO/2.0/ManualJournals
+    attr_accessor :journal_lines_downloaded
+
+    # accessible fields
+    attr_accessor :manual_journal_id, :narration, :date, :status, :journal_lines, :url, :show_on_cash_basis_reports
+
+    def initialize(params = {})
+      @errors ||= []
+      @payments ||= []
+
+      # Check if the line items have been downloaded.
+      @journal_lines_downloaded = (params.delete(:journal_lines_downloaded) == true)
+
+      params.each do |k,v|
+        self.send("#{k}=", v)
+      end
+
+      @journal_lines ||= []
+    end
+
+    def ==(other)
+      ['narration', 'status', 'journal_lines', 'show_on_cash_basis_reports'].each do |field|
+        return false if send(field) != other.send(field)
+      end
+
+      ["date"].each do |field|
+        return false if send(field).to_s != other.send(field).to_s
+      end
+      return true
+    end
+
+    # Validate the ManualJournal record according to what will be valid by the gateway.
+    #
+    # Usage:
+    #  manual_journal.valid?     # Returns true/false
+    #
+    #  Additionally sets manual_journal.errors array to an array of field/error.
+    def valid?
+      @errors = []
+
+      if !manual_journal_id.nil? && manual_journal_id !~ GUID_REGEX
+        @errors << ['manual_journal_id', 'must be blank or a valid Xero GUID']
+      end
+
+      if narration.blank?
+      	@errors << ['narration', "can't be blank"]
+      end
+
+      unless date
+        @errors << ['date', "can't be blank"]
+      end
+
+      # Make sure all journal_items are valid.
+      unless journal_lines.all? { | journal_line | journal_line.valid? }
+        @errors << ['journal_lines', "at least one journal line invalid"]
+      end
+
+      # make sure there are at least 2 journal lines
+      unless journal_lines.length > 1
+      	@errors << ['journal_lines', "journal must contain at least two individual journal lines"]
+      end
+
+      if journal_lines.length > 100
+      	@errors << ['journal_lines', "journal must contain less than one hundred journal lines"]
+      end
+
+      unless journal_lines.sum(&:line_amount).to_f == 0.0
+      	@errors << ['journal_lines', "the total debits must be equal to total credits"]
+      end
+
+      @errors.size == 0
+    end
+
+
+    def journal_lines_downloaded?
+      @journal_lines_downloaded
+    end
+
+    # If line items are not downloaded, then attempt a download now (if this record was found to begin with).
+    def journal_lines
+      if journal_lines_downloaded?
+        @journal_lines
+
+      elsif manual_journal_id =~ GUID_REGEX && @gateway
+        # There is a manual_journal_id so we can assume this record was loaded from Xero.
+        # Let's attempt to download the journal_line records (if there is a gateway)
+
+        response = @gateway.get_manual_journal(manual_journal_id)
+        raise ManualJournalNotFoundError, "Manual Journal with ID #{manual_journal_id} not found in Xero." unless response.success? && response.manual_journal.is_a?(XeroGateway::ManualJournal)
+
+        @journal_lines = response.manual_journal.journal_lines
+        @journal_lines_downloaded = true
+
+        @journal_lines
+
+      # Otherwise, this is a new manual journal, so return the journal_lines reference.
+      else
+        @journal_lines
+      end
+    end
+
+    def to_xml(b = Builder::XmlMarkup.new)
+      b.ManualJournal {
+        b.ManualJournalID manual_journal_id if manual_journal_id
+        b.Narration narration        
+        b.JournalLines {
+          self.journal_lines.each do |journal_line|
+            journal_line.to_xml(b)
+          end
+        }
+        b.Date ManualJournal.format_date(date || Date.today)
+        b.Status status if status
+        b.Url url if url
+      }
+    end
+
+    def self.from_xml(manual_journal_element, gateway = nil, options = {})
+      manual_journal = ManualJournal.new(options.merge({:gateway => gateway}))
+      manual_journal_element.children.each do |element|
+        case(element.name)
+          when "ManualJournalID" then manual_journal.manual_journal_id = element.text
+          when "Date" then manual_journal.date = parse_date(element.text)
+          when "Status" then manual_journal.status = element.text
+          when "Narration" then manual_journal.narration = element.text
+          when "JournalLines" then element.children.each {|journal_line| manual_journal.journal_lines_downloaded = true; manual_journal.journal_lines << JournalLine.from_xml(journal_line) }
+          when "Url" then manual_journal.url = element.text
+        end
+      end
+      manual_journal
+    end # from_xml
+
+    def add_journal_line(params = {})
+      journal_line = nil
+      case params
+        when Hash 			 then  journal_line = JournalLine.new(params)
+        when JournalLine then  journal_line = params
+        else             raise InvalidLineItemError
+      end
+      @journal_lines << journal_line
+      journal_line
+    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,92 @@
+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
+    class RateLimitExceeded < StandardError; end
+    class UnknownError < 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, :session_handle, :expires_at, :authorization_expires_at
+    
+    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
+      
+      update_attributes_from_token(access_token)
+    end
+    
+    def access_token
+      @access_token ||= ::OAuth::AccessToken.new(consumer, @atoken, @asecret)
+    end
+    
+    def authorize_from_access(atoken, asecret)
+      @atoken, @asecret = atoken, asecret
+    end
+  
+    # Renewing access tokens only works for Partner applications
+    def renew_access_token(access_token = nil, access_secret = nil, session_handle = nil)
+      access_token   ||= @atoken
+      access_secret  ||= @asecret 
+      session_handle ||= @session_handle
+      
+      old_token = ::OAuth::RequestToken.new(consumer, access_token, access_secret)
+      
+      access_token = old_token.get_access_token({
+        :oauth_session_handle => session_handle,
+        :token                => old_token
+      })
+      
+      update_attributes_from_token(access_token)
+    rescue ::OAuth::Unauthorized => e
+      # If the original access token is for some reason invalid an OAuth::Unauthorized could be raised.
+      # In this case raise a XeroGateway::OAuth::TokenInvalid which can be captured by the caller.  In this
+      # situation the end user will need to re-authorize the application via the request token authorization URL
+      raise XeroGateway::OAuth::TokenInvalid.new(e.message)
+    end
+    
+    private
+    
+      # Update instance variables with those from the AccessToken.
+      def update_attributes_from_token(access_token)
+        @expires_at               = Time.now + access_token.params[:oauth_expires_in].to_i
+        @authorization_expires_at = Time.now + access_token.params[:oauth_authorization_expires_in].to_i
+        @session_handle           = access_token.params[:oauth_session_handle]
+        @atoken, @asecret         = access_token.token, access_token.secret
+        @access_token             = nil
+      end
+    
+  end
+end