xero_gateway 2.0.13 → 2.0.14

data/Gemfile

@@ -5,7 +5,8 @@ gem 'oauth',   '>= 0.3.6'
 gem 'activesupport'
 
 group :test do
+  gem 'i18n' # For fixing undocumented active_support dependency
   gem 'mocha'
   gem 'shoulda'
   gem 'libxml-ruby'
-end
+end

data/README.textile

@@ -222,14 +222,17 @@ Invoice and line item totals are calculated automatically.
     })
     invoice.contact.name = "THE NAME OF THE CONTACT"
     invoice.contact.phone.number = "12345"
-    invoice.contact.address.line_1 = "LINE 1 OF THE ADDRESS"    
-    invoice.add_line_item({
+    invoice.contact.address.line_1 = "LINE 1 OF THE ADDRESS"
+    
+    line_item = XeroGateway::LineItem.new(
       :description => "THE DESCRIPTION OF THE LINE ITEM",
-      :unit_amount => 1000,
-      :tax_amount => 125,
-      :tracking_category => "THE TRACKING CATEGORY FOR THE LINE ITEM",
-      :tracking_option => "THE TRACKING OPTION FOR THE LINE ITEM"
-    })
+      :account_code => 200,
+      :unit_amount => 1000
+    )
+    
+    line_item.tracking << XeroGateway::TrackingCategory.new(:name => "tracking category", :options => "tracking option")
+
+    invoice.line_items << line_item
 	
 		invoice.create</code></pre>
 

data/Rakefile

@@ -7,7 +7,7 @@ task :default => :test
 
 desc 'Test the xero gateway.'
 Rake::TestTask.new(:test) do |t|
-  t.libs << 'lib'
+  t.libs << '.'
   t.pattern = 'test/**/*_test.rb'
   t.verbose = true
 end

data/lib/xero_gateway.rb

@@ -15,6 +15,7 @@ require File.join(File.dirname(__FILE__), 'xero_gateway', 'http_encoding_helper'
 require File.join(File.dirname(__FILE__), 'xero_gateway', 'http')
 require File.join(File.dirname(__FILE__), 'xero_gateway', 'dates')
 require File.join(File.dirname(__FILE__), 'xero_gateway', 'money')
+require File.join(File.dirname(__FILE__), 'xero_gateway', 'line_item_calculations')
 require File.join(File.dirname(__FILE__), 'xero_gateway', 'response')
 require File.join(File.dirname(__FILE__), 'xero_gateway', 'account')
 require File.join(File.dirname(__FILE__), 'xero_gateway', 'accounts_list')
@@ -23,6 +24,7 @@ require File.join(File.dirname(__FILE__), 'xero_gateway', 'contact')
 require File.join(File.dirname(__FILE__), 'xero_gateway', 'line_item')
 require File.join(File.dirname(__FILE__), 'xero_gateway', 'payment')
 require File.join(File.dirname(__FILE__), 'xero_gateway', 'invoice')
+require File.join(File.dirname(__FILE__), 'xero_gateway', 'bank_transaction')
 require File.join(File.dirname(__FILE__), 'xero_gateway', 'credit_note')
 require File.join(File.dirname(__FILE__), 'xero_gateway', 'address')
 require File.join(File.dirname(__FILE__), 'xero_gateway', 'phone')

data/lib/xero_gateway/account.rb

@@ -35,7 +35,7 @@ module XeroGateway
       'ZERORATED' =>        'Zero-rated supplies/sales from overseas (NZ Only)'
     } unless defined?(TAX_TYPE)
     
-    attr_accessor :account_id, :code, :name, :type, :tax_type, :description, :system_account, :enable_payments_to_account
+    attr_accessor :account_id, :code, :name, :type, :tax_type, :description, :system_account, :enable_payments_to_account, :currency_code
     
     def initialize(params = {})
       params.each do |k,v|
@@ -50,10 +50,8 @@ module XeroGateway
       return true
     end
     
-    def to_xml
-      b = Builder::XmlMarkup.new
-      
-      b.Account {
+    def to_xml(b = Builder::XmlMarkup.new, options={})
+      b.tag!(options[:name] ? options[:name] : 'Account') {
         b.AccountID self.account_id
         b.Code self.code
         b.Name self.name
@@ -62,6 +60,7 @@ module XeroGateway
         b.Description self.description
         b.SystemAccount self.system_account unless self.system_account.nil?
         b.EnablePaymentsToAccount self.enable_payments_to_account
+        b.CurrencyCode currency_code if currency_code
       }
     end
     
@@ -77,6 +76,7 @@ module XeroGateway
           when "Description" then account.description = element.text
           when "SystemAccount" then account.system_account = element.text
           when "EnablePaymentsToAccount" then account.enable_payments_to_account = (element.text == 'true')
+          when "CurrencyCode" then account.currency_code = element.text
         end
       end      
       account

data/lib/xero_gateway/address.rb

@@ -3,8 +3,7 @@ module XeroGateway
     
     ADDRESS_TYPE = {
       'STREET' =>     'Street',
-      'POBOX' =>      'PO Box',
-      'DEFAULT' =>    'Default address type'
+      'POBOX' =>      'PO Box'
     } unless defined?(ADDRESS_TYPE)
     
     # Any errors that occurred when the #valid? method called.
@@ -16,7 +15,7 @@ module XeroGateway
       @errors ||= []
       
       params = {
-        :address_type => "DEFAULT"
+        :address_type => "POBOX"
       }.merge(params)
       
       params.each do |k,v|

data/lib/xero_gateway/bank_transaction.rb

@@ -0,0 +1,175 @@
+module XeroGateway
+  class BankTransaction
+    include Dates
+    include LineItemCalculations
+
+    class NoGatewayError < Error; end
+
+    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)
+
+    TYPES = {
+      'RECEIVE' => 'Receive Bank Transaction',
+      'SPEND'   => 'Spend Bank Transaction',
+    } unless defined?(TYPES)
+
+    STATUSES = {
+      'ACTIVE'  => 'Bank Transaction is active',
+      'DELETED' => 'Bank Transaction is deleted',
+    } 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 line_items have been downloaded when getting from GET /API.XRO/2.0/BankTransactions
+    attr_accessor :line_items_downloaded
+
+    # accessible fields
+    attr_accessor :bank_transaction_id, :type, :date, :reference, :status, :contact, :line_items, :bank_account, :url
+
+    def initialize(params = {})
+      @errors ||= []
+      @payments ||= []
+
+      # Check if the line items have been downloaded.
+      @line_items_downloaded = (params.delete(:line_items_downloaded) == true)
+
+      # params = {
+      #   :line_amount_types => "Exclusive"
+      # }.merge(params)
+      params.each do |k,v|
+        self.send("#{k}=", v)
+      end
+
+      @line_items ||= []
+    end
+
+    def ==(other)
+      ['type', 'reference', 'status', 'contact', 'line_items', 'bank_account'].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 BankTransaction record according to what will be valid by the gateway.
+    #
+    # Usage:
+    #  bank_transaction.valid?     # Returns true/false
+    #
+    #  Additionally sets bank_transaction.errors array to an array of field/error.
+    def valid?
+      @errors = []
+
+      if !bank_transaction_id.nil? && bank_transaction_id !~ GUID_REGEX
+        @errors << ['bank_transaction_id', 'must be blank or a valid Xero GUID']
+      end
+
+      if type && !TYPES[type]
+        @errors << ['type', "must be one of #{TYPES.keys.join('/')}"]
+      end
+
+      if status && !STATUSES[status]
+        @errors << ['status', "must be one of #{STATUSES.keys.join('/')}"]
+      end
+
+      unless date
+        @errors << ['date', "can't be blank"]
+      end
+
+      # Make sure contact is valid.
+      unless @contact && @contact.valid?
+        @errors << ['contact', 'is invalid']
+      end
+
+      # Make sure all line_items are valid.
+      unless line_items.all? { | line_item | line_item.valid? }
+        @errors << ['line_items', "at least one line item invalid"]
+      end
+
+      @errors.size == 0
+    end
+
+
+    def line_items_downloaded?
+      @line_items_downloaded
+    end
+
+    # If line items are not downloaded, then attempt a download now (if this record was found to begin with).
+    def line_items
+      if line_items_downloaded?
+        @line_items
+
+      elsif bank_transaction_id =~ GUID_REGEX && @gateway
+        # There is a bank_transaction_id so we can assume this record was loaded from Xero.
+        # Let's attempt to download the line_item records (if there is a gateway)
+
+        response = @gateway.get_bank_transaction(bank_transaction_id)
+        raise BankTransactionNotFoundError, "Bank Transaction with ID #{bank_transaction_id} not found in Xero." unless response.success? && response.bank_transaction.is_a?(XeroGateway::BankTransaction)
+
+        @line_items = response.bank_transaction.line_items
+        @line_items_downloaded = true
+
+        @line_items
+
+      # Otherwise, this is a new bank transaction, so return the line_items reference.
+      else
+        @line_items
+      end
+    end
+
+    def to_xml(b = Builder::XmlMarkup.new)
+      b.BankTransaction {
+        b.BankTransactionID bank_transaction_id if bank_transaction_id
+        b.Type type
+        # b.CurrencyCode self.currency_code if self.currency_code
+        contact.to_xml(b)
+        bank_account.to_xml(b, :name => 'BankAccount')
+        b.Date BankTransaction.format_date(date || Date.today)
+        b.Status status if status
+        b.Reference reference if reference
+        b.LineItems {
+          self.line_items.each do |line_item|
+            line_item.to_xml(b)
+          end
+        }
+        b.Url url if url
+      }
+    end
+
+    def self.from_xml(bank_transaction_element, gateway = nil, options = {})
+      bank_transaction = BankTransaction.new(options.merge({:gateway => gateway}))
+      bank_transaction_element.children.each do |element|
+        case(element.name)
+          when "BankTransactionID" then bank_transaction.bank_transaction_id = element.text
+          when "Type" then bank_transaction.type = element.text
+          # when "CurrencyCode" then invoice.currency_code = element.text
+          when "Contact" then bank_transaction.contact = Contact.from_xml(element)
+          when "BankAccount" then bank_transaction.bank_account = Account.from_xml(element)
+          when "Date" then bank_transaction.date = parse_date(element.text)
+          when "Status" then bank_transaction.status = element.text
+          when "Reference" then bank_transaction.reference = element.text
+          when "LineItems" then element.children.each {|line_item| bank_transaction.line_items_downloaded = true; bank_transaction.line_items << LineItem.from_xml(line_item) }
+          # when "SubTotal" then invoice.sub_total = BigDecimal.new(element.text)
+          # when "TotalTax" then invoice.total_tax = BigDecimal.new(element.text)
+          # when "Total" then invoice.total = BigDecimal.new(element.text)
+          # when "InvoiceID" then invoice.invoice_id = element.text
+          # when "InvoiceNumber" then invoice.invoice_number = element.text
+          # when "Payments" then element.children.each { | payment | invoice.payments << Payment.from_xml(payment) }
+          # when "AmountDue" then invoice.amount_due = BigDecimal.new(element.text)
+          # when "AmountPaid" then invoice.amount_paid = BigDecimal.new(element.text)
+          # when "AmountCredited" then invoice.amount_credited = BigDecimal.new(element.text)
+          # when "SentToContact" then invoice.sent_to_contact = (element.text.strip.downcase == "true")
+          when "Url" then bank_transaction.url = element.text
+        end
+      end
+      bank_transaction
+    end # from_xml
+
+  end
+end

data/lib/xero_gateway/contact.rb

@@ -109,7 +109,7 @@ module XeroGateway
       
       # Make sure all phone numbers are correct.
       unless phones.all? { | phone | phone.valid? }
-        @errors << ['phones', 'at leaset one phone is invalid']
+        @errors << ['phones', 'at least one phone is invalid']
       end
       
       @errors.size == 0

data/lib/xero_gateway/credit_note.rb

@@ -2,10 +2,9 @@ module XeroGateway
   class CreditNote
     include Dates
     include Money
+    include LineItemCalculations
     
-    class Error < RuntimeError; end
     class NoGatewayError < Error; end
-    class InvalidLineItemError < Error; end
     
     CREDIT_NOTE_TYPE = {
       'ACCRECCREDIT' =>           'Accounts Receivable',
@@ -107,58 +106,6 @@ module XeroGateway
       @contact ||= build_contact
     end
     
-    # Helper method to create a new associated line_item.
-    # Usage:
-    #   credit_note.add_line_item({:description => "Bob's Widgets", :quantity => 1, :unit_amount => 120})
-    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
-    
     # Helper method to check if the credit_note is accounts payable.
     def accounts_payable?
       type == 'ACCPAYCREDIT'

data/lib/xero_gateway/exceptions.rb

@@ -41,6 +41,6 @@ module XeroGateway
   end
   
   class InvoiceNotFoundError < StandardError; end
-
+  class BankTransactionNotFoundError < StandardError; end
   class CreditNoteNotFoundError < StandardError; end
 end

data/lib/xero_gateway/gateway.rb

@@ -349,6 +349,75 @@ module XeroGateway
       response
     end
 
+    # Creates a bank transaction in Xero based on a bank transaction object.
+    #
+    # Bank transaction and line item totals are calculated automatically.
+    #
+    # Usage :
+    #
+    #    bank_transaction = XeroGateway::BankTransaction.new({
+    #      :type => "RECEIVE",
+    #      :date => 1.month.from_now,
+    #      :reference => "YOUR INVOICE NUMBER",
+    #    })
+    #    bank_transaction.contact = XeroGateway::Contact.new(:name => "THE NAME OF THE CONTACT")
+    #    bank_transaction.contact.phone.number = "12345"
+    #    bank_transaction.contact.address.line_1 = "LINE 1 OF THE ADDRESS"
+    #    bank_transaction.line_items << XeroGateway::LineItem.new(
+    #      :description => "THE DESCRIPTION OF THE LINE ITEM",
+    #      :unit_amount => 100,
+    #      :tax_amount => 12.5,
+    #      :tracking_category => "THE TRACKING CATEGORY FOR THE LINE ITEM",
+    #      :tracking_option => "THE TRACKING OPTION FOR THE LINE ITEM"
+    #    )
+    #    bank_transaction.bank_account = XeroGateway::Account.new(:code => 'BANK-ABC)
+    #
+    #    create_bank_transaction(bank_transaction)
+    def create_bank_transaction(bank_transaction)
+      save_bank_transaction(bank_transaction)
+    end
+
+    #
+    # Updates an existing Xero bank transaction
+    #
+    # Usage :
+    #
+    # bank_transaction = xero_gateway.get_bank_transaction(some_bank_transaction_id)
+    # bank_transaction.due_date = Date.today
+    #
+    # xero_gateway.update_bank_transaction(bank_transaction)
+    def update_bank_transaction(bank_transaction)
+      raise "bank_transaction_id is required for updating bank transactions" if bank_transaction.bank_transaction_id.nil?
+      save_bank_transaction(bank_transaction)
+    end
+
+    # Retrieves all bank transactions from Xero
+    #
+    # Usage : get_bank_transactions
+    #         get_bank_transactions(:bank_transaction_id => " 297c2dc5-cc47-4afd-8ec8-74990b8761e9")
+    #
+    # Note  : modified_since is in UTC format (i.e. Brisbane is UTC+10)
+    def get_bank_transactions(options = {})
+      request_params = {}
+      request_params[:BankTransactionID]  = options[:bank_transaction_id] if options[:bank_transaction_id]
+      request_params[:ModifiedAfter]      = options[:modified_since] if options[:modified_since]
+
+      response_xml = http_get(@client, "#{@xero_url}/BankTransactions", request_params)
+
+      parse_response(response_xml, {:request_params => request_params}, {:request_signature => 'GET/BankTransactions'})
+    end
+
+    # Retrieves a single bank transaction
+    #
+    # Usage : get_bank_transaction("297c2dc5-cc47-4afd-8ec8-74990b8761e9") # By ID
+    #         get_bank_transaction("OIT-12345") # By number
+    def get_bank_transaction(bank_transaction_id)
+      request_params = {}
+      url = "#{@xero_url}/BankTransactions/#{URI.escape(bank_transaction_id)}"
+      response_xml = http_get(@client, url, request_params)
+      parse_response(response_xml, {:request_params => request_params}, {:request_signature => 'GET/BankTransaction'})
+    end
+
     #
     # Gets all accounts for a specific organization in Xero.
     #
@@ -457,6 +526,35 @@ module XeroGateway
       response
     end
 
+    # Create or update a bank transaction record based on if it has an bank_transaction_id.
+    def save_bank_transaction(bank_transaction)
+      request_xml = bank_transaction.to_xml
+      response_xml = nil
+      create_or_save = nil
+
+      if bank_transaction.bank_transaction_id.nil?
+        # Create new bank transaction record.
+        response_xml = http_put(@client, "#{@xero_url}/BankTransactions", request_xml, {})
+        create_or_save = :create
+      else
+        # Update existing bank transaction record.
+        response_xml = http_post(@client, "#{@xero_url}/BankTransactions", request_xml, {})
+        create_or_save = :save
+      end
+
+      response = parse_response(response_xml, {:request_xml => request_xml}, {:request_signature => "#{create_or_save == :create ? 'PUT' : 'POST'}/BankTransactions"})
+
+      # Xero returns bank transactions inside an <BankTransactions> tag, even though there's only ever
+      # one for this request
+      response.response_item = response.bank_transactions.first
+
+      if response.success? && response.bank_transaction && response.bank_transaction.bank_transaction_id
+        bank_transaction.bank_transaction_id = response.bank_transaction.bank_transaction_id
+      end
+
+      response
+    end
+
     def parse_response(raw_response, request = {}, options = {})
 
       response = XeroGateway::Response.new
@@ -476,8 +574,14 @@ module XeroGateway
           when "DateTimeUTC" then response.date_time = element.text
           when "Contact" then response.response_item = Contact.from_xml(element, self)
           when "Invoice" then response.response_item = Invoice.from_xml(element, self, {:line_items_downloaded => options[:request_signature] != "GET/Invoices"})
+          when "BankTransaction"
+            response.response_item = BankTransaction.from_xml(element, self, {:line_items_downloaded => options[:request_signature] != "GET/BankTransactions"})
           when "Contacts" then element.children.each {|child| response.response_item << Contact.from_xml(child, self) }
           when "Invoices" then element.children.each {|child| response.response_item << Invoice.from_xml(child, self, {:line_items_downloaded => options[:request_signature] != "GET/Invoices"}) }
+          when "BankTransactions"
+            element.children.each do |child|
+              response.response_item << BankTransaction.from_xml(child, self, {:line_items_downloaded => options[:request_signature] != "GET/BankTransactions"})
+            end
           when "CreditNotes" then element.children.each {|child| response.response_item << CreditNote.from_xml(child, self, {:line_items_downloaded => options[:request_signature] != "GET/CreditNotes"}) }
           when "Accounts" then element.children.each {|child| response.response_item << Account.from_xml(child) }
           when "TaxRates" then element.children.each {|child| response.response_item << TaxRate.from_xml(child) }