tlconnor-xero_gateway 1.0.3 → 1.0.4

data/lib/xero_gateway/invoice.rb

@@ -3,10 +3,35 @@ module XeroGateway
     include Dates
     include Money
     
+    class Error < RuntimeError; end
+    class NoGatewayError < Error; end
+    
+    INVOICE_TYPE = {
+      'ACCREC' =>           'Accounts Receivable',
+      'ACCPAY' =>           'Accounts Payable'
+    } unless defined?(INVOICE_TYPE)
+    
+    INVOICE_STATUS = {
+      'AUTHORISED' =>       'Approved invoices awaiting payment',
+      'DELETED' =>          'Draft invoices that are deleted',
+      'DRAFT' =>            'Invoices saved as draft or entered via API',
+      'PAID' =>             'Invoices approved and fully paid',
+      'SUBMITTED' =>        'Invoices entered by an employee awaiting approval',
+      'VOID' =>             'Approved invoices that are voided'
+    } unless defined?(INVOICE_STATUS)
+        
+    # Xero::Gateway associated with this invoice.
+    attr_accessor :gateway
+    
+    # Any errors that occurred when the #valid? method called.
+    attr_reader :errors
+  
     # All accessible fields
-    attr_accessor :invoice_id, :invoice_number, :invoice_type, :invoice_status, :date, :due_date, :reference, :tax_inclusive, :includes_tax, :sub_total, :total_tax, :total, :line_items, :contact
+    attr_accessor :invoice_id, :invoice_number, :invoice_type, :invoice_status, :date, :due_date, :reference, :tax_inclusive, :includes_tax, :line_items, :contact
     
     def initialize(params = {})
+      @errors ||= []
+      
       params = {
         :contact => Contact.new,
         :date => Time.now,
@@ -15,13 +40,96 @@ module XeroGateway
       }.merge(params)
       
       params.each do |k,v|
-        self.instance_variable_set("@#{k}", v)  ## create and initialize an instance variable for this key/value pair
         self.send("#{k}=", v)
       end
       
       @line_items ||= []
-    end    
-
+    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 !invoice_id.nil? && invoice_id !~ GUID_REGEX
+        @errors << ['invoice_id', 'must be blank or a valid Xero GUID']
+      end
+            
+      if invoice_status && !INVOICE_STATUS[invoice_status]
+        @errors << ['invoice_status', "must be one of #{INVOICE_STATUS.keys.join('/')}"]
+      end
+      
+      unless invoice_number
+        @errors << ['invoice_number', "can't be blank"]
+      end
+      
+      unless date
+        @errors << ['invoice_date', "can't be blank"]
+      end
+      
+      # Make sure contact is valid.
+      unless 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
+    
+    # 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 invoice is accounts payable.
+    def accounts_payable?
+      invoice_type == 'ACCPAY'
+    end
+    
+    # Helper method to check if the invoice is accounts receivable.
+    def accounts_receivable?
+      invoice_type == 'ACCREC'
+    end
+    
     def ==(other)
       ["invoice_number", "invoice_type", "invoice_status", "reference", "tax_inclusive", "includes_tax", "sub_total", "total_tax", "total", "contact", "line_items"].each do |field|
         return false if send(field) != other.send(field)
@@ -32,41 +140,28 @@ module XeroGateway
       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 invoice record (using gateway.create_invoice) with the associated gateway.
+    # If no gateway set, raise a Xero::Invoice::NoGatewayError exception.
+    def create
+      raise NoGatewayError unless gateway
+      gateway.create_invoice(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.Invoice {
         b.InvoiceType self.invoice_type
-        b.Contact {
-          b.ContactID self.contact.contact_id if self.contact.contact_id
-          b.Name self.contact.name
-          b.EmailAddress self.contact.email if self.contact.email
-          b.Addresses {
-            self.contact.addresses.each do |address|
-              b.Address {
-                b.AddressType address.address_type
-                b.AddressLine1 address.line_1 if address.line_1
-                b.AddressLine2 address.line_2 if address.line_2
-                b.AddressLine3 address.line_3 if address.line_3
-                b.AddressLine4 address.line_4 if address.line_4
-                b.City address.city if address.city
-                b.Region address.region if address.region
-                b.PostalCode address.post_code if address.post_code
-                b.Country address.country if address.country
-              }
-            end
-          }
-          b.Phones {
-            self.contact.phones.each do |phone|
-              b.Phone {
-                b.PhoneType phone.phone_type
-                b.PhoneNumber phone.number
-                b.PhoneAreaCode phone.area_code if phone.area_code
-                b.PhoneCountryCode phone.country_code if phone.country_code
-              }
-            end
-          }
-        }
+        contact.to_xml(b)
         b.InvoiceDate Invoice.format_date_time(self.date)
         b.DueDate Invoice.format_date_time(self.due_date) if self.due_date
         b.InvoiceNumber self.invoice_number
@@ -78,21 +173,7 @@ module XeroGateway
         b.Total Invoice.format_money(self.total) if self.total
         b.LineItems {
           self.line_items.each do |line_item|
-            b.LineItem {
-              b.Description line_item.description
-              b.Quantity line_item.quantity if line_item.quantity
-              b.UnitAmount Invoice.format_money(line_item.unit_amount)
-              b.TaxType line_item.tax_type if line_item.tax_type
-              b.TaxAmount Invoice.format_money(line_item.tax_amount) if line_item.tax_amount
-              b.LineAmount Invoice.format_money(line_item.line_amount)
-              b.AccountCode line_item.account_code || 200
-              b.Tracking {
-                b.TrackingCategory {
-                  b.Name line_item.tracking_category
-                  b.Option line_item.tracking_option
-                }
-              }
-            }              
+            line_item.to_xml(b)
           end
         }
       }
@@ -115,34 +196,10 @@ module XeroGateway
           when "TotalTax" then invoice.total_tax = BigDecimal.new(element.text)
           when "Total" then invoice.total = BigDecimal.new(element.text)
           when "Contact" then invoice.contact = Contact.from_xml(element)
-          when "LineItems" then element.children.each {|line_item| invoice.line_items << parse_line_item(line_item)}
+          when "LineItems" then element.children.each {|line_item| invoice.line_items << LineItem.from_xml(line_item)}
         end
       end      
       invoice
-    end
-    
-    private
-    
-    def self.parse_line_item(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
-          if element.elements['TrackingCategory']
-            line_item.tracking_category = element.elements['TrackingCategory/Name'].text
-            line_item.tracking_option = element.elements['TrackingCategory/Option'].text
-          end
-        end
-      end
-      line_item
-    end
+    end    
   end
 end

data/lib/xero_gateway/line_item.rb

@@ -1,17 +1,103 @@
+require File.join(File.dirname(__FILE__), 'account')
+
 module XeroGateway
   class LineItem
-    # All accessible fields
-    attr_accessor :line_item_id, :description, :quantity, :unit_amount, :tax_type, :tax_amount, :line_amount, :account_code, :tracking_category, :tracking_option
+    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_category, :tracking_option
+        
     def initialize(params = {})
-      params = {
-        :quantity => 1
-      }.merge(params)
+      @errors ||= []
+      @quantity = 1
+      @unit_amount = BigDecimal.new('0')
+      @tax_amount = BigDecimal.new('0')
       
       params.each do |k,v|
-        self.instance_variable_set("@#{k}", v)  ## create and initialize an instance variable for this key/value pair
         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
+    
+    # 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 LineItem.format_money(tax_amount) if tax_amount
+        b.LineAmount LineItem.format_money(line_amount)
+        b.AccountCode account_code if account_code
+        b.Tracking {
+          b.TrackingCategory {
+            b.Name tracking_category
+            b.Option tracking_option
+          }
+        }      
+      }
+    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
+          if element.elements['TrackingCategory']
+            line_item.tracking_category = element.elements['TrackingCategory/Name'].text
+            line_item.tracking_option = element.elements['TrackingCategory/Option'].text
+          end
+        end
+      end
+      line_item
     end    
 
     def ==(other)
@@ -21,5 +107,5 @@ module XeroGateway
       end
       return true
     end
-  end
+  end  
 end

data/lib/xero_gateway/phone.rb

@@ -1,18 +1,72 @@
 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.instance_variable_set("@#{k}", v)  ## create and initialize an instance variable for this key/value pair
         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)
@@ -20,4 +74,4 @@ module XeroGateway
       return true
     end    
   end
-end
+end