xero_gateway 2.1.0 → 2.3.0

data/lib/xero_gateway/base_record.rb

@@ -0,0 +1,97 @@
+module XeroGateway
+  class BaseRecord
+    class_attribute :element_name
+    class_attribute :attribute_definitions
+
+    class << self
+      def attributes(hash)
+        hash.each do |k, v|
+          attribute k, v
+        end
+      end
+
+      def attribute(name, value)
+        self.attribute_definitions ||= {}
+        self.attribute_definitions[name] = value
+
+        case value
+        when Hash
+          value.each do |k, v|
+            attribute("#{name}#{k}", v)
+          end
+        else
+          attr_accessor name.underscore
+        end
+      end
+
+      def from_xml(base_element)
+        new.from_xml(base_element)
+      end
+
+      def xml_element
+        element_name || self.name.split('::').last
+      end
+    end
+
+    def initialize(params = {})
+      params.each do |k,v|
+        self.send("#{k}=", v) if respond_to?("#{k}=")
+      end
+    end
+
+    def ==(other)
+      to_xml == other.to_xml
+    end
+
+    def to_xml
+      builder = Builder::XmlMarkup.new
+      builder.__send__(self.class.xml_element) do
+        to_xml_attributes(builder)
+      end
+    end
+
+    def from_xml(base_element)
+      from_xml_attributes(base_element)
+      self
+    end
+
+    def from_xml_attributes(element, attribute = nil, attr_definition = self.class.attribute_definitions)
+      if Hash === attr_definition
+        element.children.each do |child|
+          next unless child.respond_to?(:name)
+          
+          child_attribute = child.name
+          child_attr_definition = attr_definition[child_attribute]
+          next unless child_attr_definition
+
+          from_xml_attributes(child, "#{attribute}#{child_attribute}", child_attr_definition)
+        end
+
+        return
+      end
+
+      value = case attr_definition
+        when :boolean then  element.text == "true"
+        when :float   then  element.text.to_f
+        when :integer then  element.text.to_i
+        else                element.text
+      end if element.text.present?
+
+      send("#{attribute.underscore}=", value)
+    end
+
+    def to_xml_attributes(builder = Builder::XmlMarkup.new, path = nil, attr_definitions = self.class.attribute_definitions)
+      attr_definitions.each do |attr, value|
+        case value
+        when Hash
+          builder.__send__(attr) do
+            to_xml_attributes(builder, "#{path}#{attr}", value)
+          end
+        else
+          builder.__send__(attr, send("#{path}#{attr}".underscore))
+        end
+      end
+    end
+
+  end
+end

data/lib/xero_gateway/contact_group.rb

@@ -0,0 +1,87 @@
+module XeroGateway
+  class ContactGroup
+    
+    # Xero::Gateway associated with this invoice.
+    attr_accessor :gateway
+    
+    # All accessible fields
+    attr_accessor :contact_group_id, :name, :status, :contacts
+    
+    # Boolean representing whether the accounts list has been loaded.
+    attr_accessor :contacts_downloaded
+    
+    def initialize(params = {})
+      @contacts = []
+      params.each do |k,v|
+        self.send("#{k}=", v)
+      end
+    end
+
+    # Return the list of Contacts. Will load the contacts if the group
+    # hasn't loaded the contacts yet (i.e. returned by a index call)
+    #
+    # Loaded contacts will only have Name and ContactId set.
+    def contacts
+      if !@contacts_downloaded && contact_group_id
+        @contacts_downloaded = true
+
+        # Load the contact list.
+        @contacts = gateway.get_contact_group_by_id(contact_group_id).contact_group.contacts || []
+      end
+
+      @contacts
+    end
+
+    # Returns the array of ContactIDs. 
+    # If the contact_ids array has been assigned, will return that array.
+    # Otherwise, returns any loaded ContactIDs
+    def contact_ids
+      if @contact_ids
+        @contact_ids
+      else
+        contacts.map(&:contact_id)
+      end
+    end
+
+    # Assign ContactIDs to the group for updating.
+    def contact_ids=(contact_ids)
+      @contact_ids = contact_ids
+    end
+
+    def to_xml(b = Builder::XmlMarkup.new)
+      b.ContactGroup {
+        b.ContactGroupID contact_group_id unless contact_group_id.nil?
+        b.Name self.name
+        b.Status self.status
+
+        if @contacts_downloaded || @contact_ids
+          b.Contacts {
+            self.contact_ids.each do |contact_id|
+              b.Contact {
+                b.ContactID contact_id
+              }
+            end
+          }
+        end
+      }
+    end
+
+    def self.from_xml(contact_group_element, gateway, options = {})
+      contact_group = ContactGroup.new(gateway: gateway, contacts_downloaded: options[:contacts_downloaded])
+      contact_group_element.children.each do |element|
+        case(element.name)
+          when "ContactGroupID" then contact_group.contact_group_id = element.text
+          when "Name" then contact_group.name = element.text
+          when "Status" then contact_group.status = element.text
+          when "Contacts" then
+            contact_group.contacts_downloaded = true
+            element.children.each do |contact_child|
+              contact_group.contacts << Contact.from_xml(contact_child, gateway)
+            end
+        end
+      end
+      contact_group              
+    end  
+
+  end
+end

data/lib/xero_gateway/currency.rb

@@ -1,56 +1,10 @@
 module XeroGateway
-  class Currency
-    
-    unless defined? ATTRS
-      ATTRS = {
-        "Code" 	       => :string,     # 3 letter alpha code for the currency – see list of currency codes
-        "Description"  => :string, 	   # Name of Currency
-      }
-    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.Currency do
-        ATTRS.keys.each do |attr|
-          eval("b.#{attr} '#{self.send(attr.underscore.to_sym)}'")
-        end
-      end
-    end
-    
-    def self.from_xml(currency_element)
-      Currency.new.tap do |currency|
-        currency_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  currency.send("#{underscored_attribute}=", (element.text == "true"))
-            when :float   then  currency.send("#{underscored_attribute}=", element.text.to_f)
-            else                currency.send("#{underscored_attribute}=", element.text)
-          end
-          
-        end
-      end
-    end
-    
+  class Currency < BaseRecord
+
+    attributes({
+      "Code" 	       => :string,     # 3 letter alpha code for the currency – see list of currency codes
+      "Description"  => :string, 	   # Name of Currency
+    })
+
   end
-end
+end

data/lib/xero_gateway/dates.rb

@@ -20,6 +20,10 @@ module XeroGateway
       def parse_date_time(time)
         Time.local(time[0..3].to_i, time[5..6].to_i, time[8..9].to_i, time[11..12].to_i, time[14..15].to_i, time[17..18].to_i)
       end
+
+      def parse_date_time_utc(time)
+        Time.utc(time[0..3].to_i, time[5..6].to_i, time[8..9].to_i, time[11..12].to_i, time[14..15].to_i, time[17..18].to_i)
+      end
     end
   end
 end

data/lib/xero_gateway/exceptions.rb

@@ -4,48 +4,49 @@ module XeroGateway
   class InvalidLineItemError < StandardError; end
 
   class ApiException < StandardError
-    
+
     def initialize(type, message, request_xml, response_xml)
       @type     = type
       @message  = message
       @request_xml      = request_xml
       @response_xml      = response_xml
     end
-    
+
     attr_reader :request_xml, :response_xml
-    
+
     def message
       "#{@type}: #{@message} \n Generated by the following XML: \n #{@response_xml}"
     end
-    
+
   end
-  
+
   class UnparseableResponse < StandardError
-    
+
     def initialize(root_element_name)
       @root_element_name = root_element_name
     end
-    
+
     def message
       "A root element of #{@root_element_name} was returned, and we don't understand that!"
     end
-      
+
   end
-  
+
   class ObjectNotFound < StandardError
-    
+
     def initialize(api_endpoint)
       @api_endpoint = api_endpoint
     end
-    
+
     def message
       "Couldn't find object for API Endpoint #{@api_endpoint}"
     end
-    
+
   end
-  
+
   class InvoiceNotFoundError < StandardError; end
   class BankTransactionNotFoundError < StandardError; end
+  class PaymentNotFoundError < StandardError; end
   class CreditNoteNotFoundError < StandardError; end
   class ManualJournalNotFoundError < StandardError; end
 end

data/lib/xero_gateway/gateway.rb

@@ -34,9 +34,10 @@ module XeroGateway
 
       request_params[:ContactID]     = options[:contact_id] if options[:contact_id]
       request_params[:ContactNumber] = options[:contact_number] if options[:contact_number]
-      request_params[:OrderBy]       = options[:order] if options[:order]
+      request_params[:order]         = options[:order] if options[:order]
       request_params[:ModifiedAfter] = options[:modified_since] if options[:modified_since]
       request_params[:where]         = options[:where] if options[:where]
+      request_params[:page]          = options[:page]  if options[:page]
 
       response_xml = http_get(@client, "#{@xero_url}/Contacts", request_params)
 
@@ -126,6 +127,31 @@ module XeroGateway
       response
     end
 
+    # Retreives all contact groups from Xero
+    #
+    # Usage:
+    #   groups = gateway.get_contact_groups()
+    #
+    def get_contact_groups(options = {})
+      request_params = {}
+
+      request_params[:ContactGroupID] = options[:contact_group_id] if options[:contact_group_id]
+      request_params[:order]          = options[:order] if options[:order]
+      request_params[:where]          = options[:where] if options[:where]
+
+      response_xml = http_get(@client, "#{@xero_url}/ContactGroups", request_params)
+
+      parse_response(response_xml, {:request_params => request_params}, {:request_signature => 'GET/contactgroups'})
+    end
+
+    # Retreives a contact group by its id.
+    def get_contact_group_by_id(contact_group_id)
+      request_params = { :ContactGroupID => contact_group_id }
+      response_xml = http_get(@client, "#{@xero_url}/ContactGroups/#{URI.escape(contact_group_id)}", request_params)
+
+      parse_response(response_xml, {:request_params => request_params}, {:request_signature => 'GET/contactgroup'})
+    end
+
     # Retrieves all invoices from Xero
     #
     # Usage : get_invoices
@@ -138,7 +164,7 @@ module XeroGateway
 
       request_params[:InvoiceID]     = options[:invoice_id] if options[:invoice_id]
       request_params[:InvoiceNumber] = options[:invoice_number] if options[:invoice_number]
-      request_params[:OrderBy]       = options[:order] if options[:order]
+      request_params[:order]         = options[:order] if options[:order]
       request_params[:ModifiedAfter] = options[:modified_since] if options[:modified_since]
 
       request_params[:where]         = options[:where] if options[:where]
@@ -263,10 +289,10 @@ module XeroGateway
 
       request_params[:CreditNoteID]     = options[:credit_note_id] if options[:credit_note_id]
       request_params[:CreditNoteNumber] = options[:credit_note_number] if options[:credit_note_number]
-      request_params[:OrderBy]       = options[:order] if options[:order]
-      request_params[:ModifiedAfter] = options[:modified_since] if options[:modified_since]
+      request_params[:order]            = options[:order] if options[:order]
+      request_params[:ModifiedAfter]    = options[:modified_since] if options[:modified_since]
 
-      request_params[:where]         = options[:where] if options[:where]
+      request_params[:where]            = options[:where] if options[:where]
 
       response_xml = http_get(@client, "#{@xero_url}/CreditNotes", request_params)
 
@@ -413,6 +439,8 @@ module XeroGateway
       request_params = {}
       request_params[:BankTransactionID]  = options[:bank_transaction_id] if options[:bank_transaction_id]
       request_params[:ModifiedAfter]      = options[:modified_since] if options[:modified_since]
+      request_params[:order]              = options[:order] if options[:order]
+      request_params[:where]              = options[:where] if options[:where]
 
       response_xml = http_get(@client, "#{@xero_url}/BankTransactions", request_params)
 
@@ -529,6 +557,14 @@ module XeroGateway
       parse_response(response_xml, {}, {:request_signature => 'GET/tax_rates'})
     end
 
+    #
+    # Gets all Items for a specific organisation in Xero
+    #
+    def get_items
+      response_xml = http_get(@client, "#{xero_url}/Items")
+      parse_response(response_xml, {}, {:request_signature => 'GET/items'})
+    end
+
     #
     # Create Payment record in Xero
     #
@@ -543,6 +579,44 @@ module XeroGateway
       parse_response(response_xml, {:request_xml => request_xml}, {:request_signature => 'PUT/payments'})
     end
 
+    #
+    # Gets all Payments for a specific organisation in Xero
+    #
+    def get_payments(options = {})
+      request_params = {}
+      request_params[:PaymentID]     = options[:payment_id] if options[:payment_id]
+      request_params[:ModifiedAfter] = options[:modified_since] if options[:modified_since]
+      request_params[:order]         = options[:order] if options[:order]
+      request_params[:where]         = options[:where] if options[:where]
+
+      response_xml = http_get(@client, "#{@xero_url}/Payments", request_params)
+      parse_response(response_xml, {:request_params => request_params}, {:request_signature => 'GET/payments'})
+    end
+
+
+    #
+    # Gets a single Payment for a specific organsation in Xero
+    #
+    def get_payment(payment_id, options = {})
+      request_params = {}
+      response_xml = http_get(client, "#{xero_url}/Payments/#{payment_id}", request_params)
+      parse_response(response_xml, {:request_params => request_params}, {:request_signature => 'GET/payments'})
+    end
+
+    # Retrieves reports from Xero
+    #
+    # Usage : get_report("BankStatement", bank_account_id: "AC993F75-035B-433C-82E0-7B7A2D40802C")
+    #         get_report("297c2dc5-cc47-4afd-8ec8-74990b8761e9", bank_account_id: "AC993F75-035B-433C-82E0-7B7A2D40802C")
+    def get_report(id_or_name, options={})
+      request_params = options.inject({}) do  |params, (key, val)|
+        xero_key = key.to_s.camelize.gsub(/id/i, "ID").to_sym
+        params[xero_key] = val
+        params
+      end
+      response_xml = http_get(@client, "#{@xero_url}/reports/#{id_or_name}", request_params)
+      parse_response(response_xml, {:request_params => request_params}, {:request_signature => 'GET/reports'})
+    end
+
     private
 
     def get_contact(contact_id = nil, contact_number = nil)
@@ -682,6 +756,7 @@ module XeroGateway
           when "ManualJournal"
             response.response_item = ManualJournal.from_xml(element, self, {:journal_lines_downloaded => options[:request_signature] != "GET/ManualJournals"})
           when "Contacts" then element.children.each {|child| response.response_item << Contact.from_xml(child, self) }
+          when "ContactGroups" then element.children.each {|child| response.response_item << ContactGroup.from_xml(child, self, {:contacts_downloaded => options[:request_signature] != "GET/contactgroups"}) }
           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|
@@ -694,9 +769,19 @@ module XeroGateway
           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) }
+          when "Items" then element.children.each {|child| response.response_item << Item.from_xml(child) }
           when "Currencies" then element.children.each {|child| response.response_item << Currency.from_xml(child) }
           when "Organisations" then response.response_item = Organisation.from_xml(element.children.first) # Xero only returns the Authorized Organisation
           when "TrackingCategories" then element.children.each {|child| response.response_item << TrackingCategory.from_xml(child) }
+          when "Payment" then response.response_item = Payment.from_xml(element)
+          when "Payments"
+            element.children.each do |child|
+              response.response_item << Payment.from_xml(child)
+            end
+          when "Reports"
+            element.children.each do |child|
+              response.response_item << Report.from_xml(child)
+            end
           when "Errors" then response.errors = element.children.map { |error| Error.parse(error) }
         end
       end if response_element