xero_gateway-float 2.0.15

data/lib/xero_gateway/contact.rb

@@ -0,0 +1,206 @@
+module XeroGateway
+  class Contact
+    include Dates
+    
+    class Error < RuntimeError; end
+    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)
+    
+    CONTACT_STATUS = {
+      'ACTIVE' =>     'Active',
+      'DELETED' =>    'Deleted'
+    } unless defined?(CONTACT_STATUS)
+            
+    # Xero::Gateway associated with this contact.
+    attr_accessor :gateway
+    
+    # Any errors that occurred when the #valid? method called.
+    attr_reader :errors
+    
+    attr_accessor :contact_id, :contact_number, :status, :name, :first_name, :last_name, :email, :addresses, :phones, :updated_at,
+                  :bank_account_details, :tax_number, :accounts_receivable_tax_type, :accounts_payable_tax_type, :is_customer, :is_supplier,
+                  :default_currency, :contact_groups
+
+        
+    def initialize(params = {})
+      @errors ||= []
+
+      params = {}.merge(params)      
+      params.each do |k,v|
+        self.send("#{k}=", v)
+      end
+
+      @phones ||= []
+      @addresses ||= []
+    end
+    
+    def address=(address)
+      self.addresses = [address]
+    end
+    
+    def address
+      self.addresses[0] ||= Address.new
+    end
+    
+    # Helper method to add a new address object to this contact.
+    #
+    # Usage:
+    #  contact.add_address({
+    #    :address_type =>   'STREET',
+    #    :line_1 =>         '100 Queen Street',
+    #    :city =>           'Brisbane',
+    #    :region =>         'QLD',
+    #    :post_code =>      '4000',
+    #    :country =>        'Australia'
+    #  })
+    def add_address(address_params)
+      self.addresses << Address.new(address_params)
+    end
+    
+    def phone=(phone)
+      self.phones = [phone]
+    end
+    
+    def phone
+      if @phones.size > 1
+        @phones.detect {|p| p.phone_type == 'DEFAULT'} || phones[0]
+      else
+        @phones[0] ||= Phone.new
+      end
+    end
+    
+    # Helper method to add a new phone object to this contact.
+    #
+    # Usage:
+    #  contact.add_phone({
+    #    :phone_type =>   'MOBILE',
+    #    :number =>       '0400123123'
+    #  })
+    def add_phone(phone_params = {})
+      self.phones << Phone.new(phone_params)
+    end
+    
+    # Validate the Contact record according to what will be valid by the gateway.
+    #
+    # Usage: 
+    #  contact.valid?     # Returns true/false
+    #  
+    #  Additionally sets contact.errors array to an array of field/error.
+    def valid?
+      @errors = []
+      
+      if !contact_id.nil? && contact_id !~ GUID_REGEX
+        @errors << ['contact_id', 'must be blank or a valid Xero GUID']
+      end
+      
+      if status && !CONTACT_STATUS[status]
+        @errors << ['status', "must be one of #{CONTACT_STATUS.keys.join('/')}"]
+      end
+      
+      unless name
+        @errors << ['name', "can't be blank"]
+      end
+      
+      # Make sure all addresses are correct.
+      unless addresses.all? { | address | address.valid? }
+        @errors << ['addresses', 'at least one address is invalid']
+      end
+      
+      # Make sure all phone numbers are correct.
+      unless phones.all? { | phone | phone.valid? }
+        @errors << ['phones', 'at least one phone is invalid']
+      end
+      
+      @errors.size == 0
+    end
+    
+    # General purpose create/save method.
+    # If contact_id and contact_number are nil then create, otherwise, attempt to save.
+    def save
+      if contact_id.nil? && contact_number.nil?
+        create
+      else
+        update
+      end
+    end
+    
+    # Creates this contact record (using gateway.create_contact) with the associated gateway.
+    # If no gateway set, raise a Xero::Contact::NoGatewayError exception.
+    def create
+      raise NoGatewayError unless gateway
+      gateway.create_contact(self)
+    end
+    
+    # Creates this contact record (using gateway.update_contact) with the associated gateway.
+    # If no gateway set, raise a Xero::Contact::NoGatewayError exception.
+    def update
+      raise NoGatewayError unless gateway
+      gateway.update_contact(self)
+    end
+        
+    def to_xml(b = Builder::XmlMarkup.new)
+      b.Contact {
+        b.ContactID self.contact_id if self.contact_id
+        b.ContactNumber self.contact_number if self.contact_number
+        b.Name self.name
+        b.EmailAddress self.email if self.email
+        b.FirstName self.first_name if self.first_name
+        b.LastName self.last_name if self.last_name
+        b.BankAccountDetails self.bank_account_details if self.bank_account_details
+        b.TaxNumber self.tax_number if self.tax_number
+        b.AccountsReceivableTaxType self.accounts_receivable_tax_type if self.accounts_receivable_tax_type
+        b.AccountsPayableTaxType self.accounts_payable_tax_type if self.accounts_payable_tax_type
+        b.ContactGroups if self.contact_groups
+        b.IsCustomer true if self.is_customer
+        b.IsSupplier true if self.is_supplier
+        b.DefaultCurrency if self.default_currency
+        b.Addresses {
+          addresses.each { |address| address.to_xml(b) }
+        }
+        b.Phones {
+          phones.each { |phone| phone.to_xml(b) }
+        }
+      }
+    end
+    
+    # Take a Contact element and convert it into an Contact object
+    def self.from_xml(contact_element, gateway = nil)
+      contact = Contact.new(:gateway => gateway)
+      contact_element.children.each do |element|
+        case(element.name)
+          when "ContactID" then contact.contact_id = element.text
+          when "ContactNumber" then contact.contact_number = element.text
+          when "ContactStatus" then contact.status = element.text
+          when "Name" then contact.name = element.text
+          when "FirstName" then contact.first_name = element.text
+          when "LastName" then contact.last_name = element.text
+          when "EmailAddress" then contact.email = element.text
+          when "Addresses" then element.children.each {|address_element| contact.addresses << Address.from_xml(address_element)}
+          when "Phones" then element.children.each {|phone_element| contact.phones << Phone.from_xml(phone_element)}
+          when "FirstName" then contact.first_name = element.text
+          when "LastName"  then contact.last_name  = element.text
+          when "BankAccountDetails" then contact.bank_account_details = element.text
+          when "TaxNumber" then contact.tax_number = element.text
+          when "AccountsReceivableTaxType" then contact.accounts_receivable_tax_type = element.text
+          when "AccountsPayableTaxType" then contact.accounts_payable_tax_type = element.text
+          when "ContactGroups" then contact.contact_groups = element.text
+          when "IsCustomer" then contact.is_customer = (element.text == "true")
+          when "IsSupplier" then contact.is_supplier = (element.text == "true")
+          when "DefaultCurrency" then contact.default_currency = element.text
+        end
+      end
+      contact
+    end
+    
+    def ==(other)
+      [ :contact_id, :contact_number, :status, :name, :first_name, :last_name, :email, :addresses, :phones, :updated_at,
+        :bank_account_details, :tax_number, :accounts_receivable_tax_type, :accounts_payable_tax_type, :is_customer, :is_supplier,
+        :default_currency, :contact_groups ].each do |field|
+        return false if send(field) != other.send(field)
+      end
+      return true
+    end    
+        
+  end
+end

data/lib/xero_gateway/credit_note.rb

@@ -0,0 +1,222 @@
+module XeroGateway
+  class CreditNote
+    include Dates
+    include Money
+    include LineItemCalculations
+    
+    class NoGatewayError < Error; end
+    
+    CREDIT_NOTE_TYPE = {
+      'ACCRECCREDIT' =>           'Accounts Receivable',
+      'ACCPAYCREDIT' =>           'Accounts Payable'
+    } unless defined?(CREDIT_NOTE_TYPE)
+    
+    LINE_AMOUNT_TYPES = {
+      "Inclusive" =>        'CreditNote lines are inclusive tax',
+      "Exclusive" =>        'CreditNote lines are exclusive of tax (default)',
+      "NoTax"     =>        'CreditNotes lines have no tax'
+    } unless defined?(LINE_AMOUNT_TYPES)
+    
+    CREDIT_NOTE_STATUS = {
+      'AUTHORISED' =>       'Approved credit_notes awaiting payment',
+      'DELETED' =>          'Draft credit_notes that are deleted',
+      'DRAFT' =>            'CreditNotes saved as draft or entered via API',
+      'PAID' =>             'CreditNotes approved and fully paid',
+      'SUBMITTED' =>        'CreditNotes entered by an employee awaiting approval',
+      'VOID' =>             'Approved credit_notes that are voided'
+    } unless defined?(CREDIT_NOTE_STATUS)
+    
+    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)
+        
+    # Xero::Gateway associated with this credit_note.
+    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/CreditNotes
+    attr_accessor :line_items_downloaded
+  
+    # All accessible fields
+    attr_accessor :credit_note_id, :credit_note_number, :type, :status, :date, :reference, :line_amount_types, :currency_code, :line_items, :contact, :payments, :fully_paid_on, :amount_credited
+
+    
+    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 => "Inclusive"
+      }.merge(params)
+      
+      params.each do |k,v|
+        self.send("#{k}=", v)
+      end
+      
+      @line_items ||= []
+    end
+    
+    # Validate the Address record according to what will be valid by the gateway.
+    #
+    # Usage: 
+    #  address.valid?     # Returns true/false
+    #  
+    #  Additionally sets address.errors array to an array of field/error.
+    def valid?
+      @errors = []
+      
+      if !credit_note_id.nil? && credit_note_id !~ GUID_REGEX
+        @errors << ['credit_note_id', 'must be blank or a valid Xero GUID']
+      end
+            
+      if status && !CREDIT_NOTE_STATUS[status]
+        @errors << ['status', "must be one of #{CREDIT_NOTE_STATUS.keys.join('/')}"]
+      end
+
+      if line_amount_types && !LINE_AMOUNT_TYPES[line_amount_types]
+        @errors << ['line_amount_types', "must be one of #{LINE_AMOUNT_TYPES.keys.join('/')}"]
+      end
+      
+      unless date
+        @errors << ['credit_note_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
+    
+    # Helper method to create the associated contact object.
+    def build_contact(params = {})
+      self.contact = gateway ? gateway.build_contact(params) : Contact.new(params)
+    end
+    
+    def contact
+      @contact ||= build_contact
+    end
+    
+    # Helper method to check if the credit_note is accounts payable.
+    def accounts_payable?
+      type == 'ACCPAYCREDIT'
+    end
+    
+    # Helper method to check if the credit_note is accounts receivable.
+    def accounts_receivable?
+      type == 'ACCRECCREDIT'
+    end
+    
+    # Whether or not the line_items have been downloaded (GET/credit_notes does not download line items).
+    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
+        
+      # There is an credit_note_is so we can assume this record was loaded from Xero.
+      # attempt to download the line_item records.
+      elsif credit_note_id =~ GUID_REGEX
+        raise NoGatewayError unless @gateway
+        
+        response = @gateway.get_credit_note(credit_note_id)
+        raise CreditNoteNotFoundError, "CreditNote with ID #{credit_note_id} not found in Xero." unless response.success? && response.credit_note.is_a?(XeroGateway::CreditNote)
+        
+        @line_items = response.credit_note.line_items
+        @line_items_downloaded = true
+        
+        @line_items
+        
+      # Otherwise, this is a new credit_note, so return the line_items reference.
+      else
+        @line_items
+      end
+    end
+    
+    def ==(other)
+      ["credit_note_number", "type", "status", "reference", "currency_code", "line_amount_types", "contact", "line_items"].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
+    
+    # General purpose createsave method.
+    # If contact_id and contact_number are nil then create, otherwise, attempt to save.
+    def save
+      create
+    end
+    
+    # Creates this credit_note record (using gateway.create_credit_note) with the associated gateway.
+    # If no gateway set, raise a Xero::CreditNote::NoGatewayError exception.
+    def create
+      raise NoGatewayError unless gateway
+      gateway.create_credit_note(self)
+    end
+    
+    # Alias create as save as this is currently the only write action.
+    alias_method :save, :create
+            
+    def to_xml(b = Builder::XmlMarkup.new)
+      b.CreditNote {
+        b.Type self.type
+        contact.to_xml(b)
+        b.Date CreditNote.format_date(self.date || Date.today)
+        b.Status self.status if self.status
+        b.CreditNoteNumber self.credit_note_number if credit_note_number
+        b.Reference self.reference if self.reference
+        b.CurrencyCode self.currency_code if self.currency_code
+        b.LineAmountTypes self.line_amount_types
+        b.LineItems {
+          self.line_items.each do |line_item|
+            line_item.to_xml(b)
+          end
+        }
+      }
+    end
+    
+    #TODO UpdatedDateUTC
+    def self.from_xml(credit_note_element, gateway = nil, options = {})
+      credit_note = CreditNote.new(options.merge({:gateway => gateway}))
+      credit_note_element.children.each do |element|
+        case(element.name)
+          when "CreditNoteID" then credit_note.credit_note_id = element.text
+          when "CreditNoteNumber" then credit_note.credit_note_number = element.text            
+          when "Type" then credit_note.type = element.text
+          when "CurrencyCode" then credit_note.currency_code = element.text
+          when "Contact" then credit_note.contact = Contact.from_xml(element)
+          when "Date" then credit_note.date = parse_date(element.text)
+          when "Status" then credit_note.status = element.text
+          when "Reference" then credit_note.reference = element.text
+          when "LineAmountTypes" then credit_note.line_amount_types = element.text
+          when "LineItems" then element.children.each {|line_item| credit_note.line_items_downloaded = true; credit_note.line_items << LineItem.from_xml(line_item) }
+          when "SubTotal" then credit_note.sub_total = BigDecimal.new(element.text)
+          when "TotalTax" then credit_note.total_tax = BigDecimal.new(element.text)
+          when "Total" then credit_note.total = BigDecimal.new(element.text)
+          when "CreditNoteID" then credit_note.credit_note_id = element.text
+          when "CreditNoteNumber" then credit_note.credit_note_number = element.text            
+          when "Payments" then element.children.each { | payment | credit_note.payments << Payment.from_xml(payment) }
+          when "AmountDue" then credit_note.amount_due = BigDecimal.new(element.text)
+          when "AmountPaid" then credit_note.amount_paid = BigDecimal.new(element.text)
+          when "AmountCredited" then credit_note.amount_credited = BigDecimal.new(element.text)
+        end
+      end      
+      credit_note
+    end    
+  end
+end

data/lib/xero_gateway/currency.rb

@@ -0,0 +1,56 @@
+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
+    
+  end
+end