xero_gateway-float 2.0.15

data/lib/xero_gateway/http.rb

@@ -0,0 +1,138 @@
+module XeroGateway
+  module Http
+    OPEN_TIMEOUT = 10 unless defined? OPEN_TIMEOUT
+    READ_TIMEOUT = 60 unless defined? READ_TIMEOUT
+    ROOT_CA_FILE = File.join(File.dirname(__FILE__), 'ca-certificates.crt') unless defined? ROOT_CA_FILE
+    
+    def http_get(client, url, extra_params = {})
+      http_request(client, :get, url, nil, extra_params)
+    end
+
+    def http_post(client, url, body, extra_params = {})
+      http_request(client, :post, url, body, extra_params)
+    end
+
+    def http_put(client, url, body, extra_params = {})
+      http_request(client, :put, url, body, extra_params)
+    end
+    
+    private
+    
+      def http_request(client, method, url, body, params = {})
+        # headers = {'Accept-Encoding' => 'gzip, deflate'}
+        headers = { 'charset' => 'utf-8' }
+
+        if method != :get
+          headers['Content-Type'] ||= "application/x-www-form-urlencoded"
+        end
+
+        headers['Accept'] = params.delete(:accept_type) if params[:accept_type]
+
+        # HAX.  Xero completely misuse the If-Modified-Since HTTP header.
+        headers['If-Modified-Since'] = params.delete(:ModifiedAfter).utc.strftime("%Y-%m-%dT%H:%M:%S") if params[:ModifiedAfter]
+
+        if params.any?
+          url += "?" + params.map {|key,value| "#{CGI.escape(key.to_s)}=#{CGI.escape(value.to_s)}"}.join("&")
+        end
+
+        uri   = URI.parse(url)
+
+        # # Only setup @cached_http once on first use as loading the CA file is quite expensive computationally.
+        # unless @cached_http && @cached_http.address == uri.host && @cached_http.port == uri.port
+        #   @cached_http = Net::HTTP.new(uri.host, uri.port) 
+        #   @cached_http.open_timeout = OPEN_TIMEOUT
+        #   @cached_http.read_timeout = READ_TIMEOUT
+        #   @cached_http.use_ssl      = true
+        # 
+        #   # Need to validate server's certificate against root certificate authority to prevent man-in-the-middle attacks.
+        #   @cached_http.ca_file        = ROOT_CA_FILE
+        #   # http.verify_mode    = OpenSSL::SSL::VERIFY_NONE
+        #   @cached_http.verify_mode    = OpenSSL::SSL::VERIFY_PEER
+        #   @cached_http.verify_depth   = 5
+        # end
+        
+        logger.info("\n== [#{Time.now.to_s}] XeroGateway Request: #{uri.request_uri} ") if self.logger
+        
+        response = case method
+          when :get   then    client.get(uri.request_uri, headers)
+          when :post  then    client.post(uri.request_uri, { :xml => body }, headers)
+          when :put   then    client.put(uri.request_uri, { :xml => body }, headers)
+        end
+        
+        if self.logger
+          logger.info("== [#{Time.now.to_s}] XeroGateway Response (#{response.code})")
+          
+          unless response.code.to_i == 200
+            logger.info("== #{uri.request_uri} Response Body \n\n #{response.plain_body} \n == End Response Body")
+          end
+        end
+        
+        case response.code.to_i
+          when 200
+            response.plain_body
+          when 400
+            handle_error!(body, response)  
+          when 401
+            handle_oauth_error!(response)
+          when 404
+            handle_object_not_found!(response, url)
+          when 503
+            handle_oauth_error!(response)
+          else
+            raise "Unknown response code: #{response.code.to_i}"
+        end
+      end
+       
+      def handle_oauth_error!(response)
+        error_details = CGI.parse(response.plain_body)
+        description   = error_details["oauth_problem_advice"].first
+      
+        # see http://oauth.pbworks.com/ProblemReporting
+        # In addition to token_expired and token_rejected, Xero also returns
+        # 'rate limit exceeded' when more than 60 requests have been made in
+        # a second.
+        case (error_details["oauth_problem"].first)
+          when "token_expired"        then raise OAuth::TokenExpired.new(description)
+          when "consumer_key_unknown" then raise OAuth::TokenInvalid.new(description)
+          when "token_rejected"       then raise OAuth::TokenInvalid.new(description)
+          when "rate limit exceeded"  then raise OAuth::RateLimitExceeded.new(description)
+          else raise OAuth::UnknownError.new(error_details["oauth_problem"].first + ':' + description)
+        end
+      end
+      
+      def handle_error!(request_xml, response)
+        
+        raw_response = response.plain_body
+        
+        # Xero Gateway API Exceptions *claim* to be UTF-16 encoded, but fail REXML/Iconv parsing...
+        # So let's ignore that :)
+        raw_response.gsub! '<?xml version="1.0" encoding="utf-16"?>', ''
+        
+        doc = REXML::Document.new(raw_response, :ignore_whitespace_nodes => :all)
+        
+        if doc.root.name == "ApiException"
+
+          raise ApiException.new(doc.root.elements["Type"].text, 
+                                 doc.root.elements["Message"].text,
+                                 request_xml, 
+                                 raw_response)
+
+        else
+          
+          raise "Unparseable 400 Response: #{raw_response}"
+          
+        end
+        
+      end
+      
+      def handle_object_not_found!(response, request_url)
+        case(request_url)
+          when /Invoices/ then raise InvoiceNotFoundError.new("Invoice not found in Xero.")
+          when /BankTransactions/ then raise BankTransactionNotFoundError.new("Bank Transaction not found in Xero.")
+          when /CreditNotes/ then raise CreditNoteNotFoundError.new("Credit Note not found in Xero.")
+          else raise ObjectNotFound.new(request_url)
+        end
+      end
+      
+  end
+end

data/lib/xero_gateway/http_encoding_helper.rb

@@ -0,0 +1,49 @@
+# Intended to extend the Net::HTTP response object
+# and adds support for decoding gzip and deflate encoded pages
+#
+# Author: Jason Stirk <http://griffin.oobleyboo.com>
+# Home: http://griffin.oobleyboo.com/projects/http_encoding_helper
+# Created: 5 September 2007
+# Last Updated: 23 November 2007
+#
+# Usage:
+#
+# require 'net/http'
+# require 'http_encoding_helper'
+# headers={'Accept-Encoding' => 'gzip, deflate' }
+# http = Net::HTTP.new('griffin.oobleyboo.com', 80)
+# http.start do |h|
+#   request = Net::HTTP::Get.new('/', headers)
+#   response = http.request(request)
+#   content=response.plain_body     # Method from our library
+#   puts "Transferred: #{response.body.length} bytes"
+#   puts "Compression: #{response['content-encoding']}"
+#   puts "Extracted: #{response.plain_body.length} bytes"  
+# end
+#	
+
+require 'zlib'
+require 'stringio'
+
+class Net::HTTPResponse
+  # Return the uncompressed content
+  def plain_body
+    encoding=self['content-encoding']
+    content=nil
+    if encoding then
+      case encoding
+        when 'gzip'
+          i=Zlib::GzipReader.new(StringIO.new(self.body))
+          content=i.read
+        when 'deflate'
+          i=Zlib::Inflate.new
+          content=i.inflate(self.body)
+        else
+          raise "Unknown encoding - #{encoding}"
+      end
+    else
+      content=self.body
+    end
+    return content
+  end
+end

data/lib/xero_gateway/invoice.rb

@@ -0,0 +1,236 @@
+module XeroGateway
+  class Invoice
+    include Dates
+    include Money
+    include LineItemCalculations
+    
+    class NoGatewayError < Error; end
+    
+    INVOICE_TYPE = {
+      'ACCREC' =>           'Accounts Receivable',
+      'ACCPAY' =>           'Accounts Payable'
+    } unless defined?(INVOICE_TYPE)
+    
+    LINE_AMOUNT_TYPES = {
+      "Inclusive" =>        'Invoice lines are inclusive tax',
+      "Exclusive" =>        'Invoice lines are exclusive of tax (default)',
+      "NoTax"     =>        'Invoices lines have no tax'
+    } unless defined?(LINE_AMOUNT_TYPES)
+    
+    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)
+    
+    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 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/INVOICES
+    attr_accessor :line_items_downloaded
+  
+    # All accessible fields
+    attr_accessor :invoice_id, :invoice_number, :invoice_type, :invoice_status, :date, :due_date, :reference, :line_amount_types, :currency_code, :line_items, :contact, :payments, :fully_paid_on, :amount_due, :amount_paid, :amount_credited, :sent_to_contact, :url, :sub_total, :total_tax, :total, :updated_date_utc
+
+    
+    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
+    
+    # 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
+
+      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 << ['invoice_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 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
+    
+    # Whether or not the line_items have been downloaded (GET/invoices 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
+
+      elsif invoice_id =~ GUID_REGEX && @gateway
+        # There is an invoice_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_invoice(invoice_id)
+        raise InvoiceNotFoundError, "Invoice with ID #{invoice_id} not found in Xero." unless response.success? && response.invoice.is_a?(XeroGateway::Invoice)
+        
+        @line_items = response.invoice.line_items
+        @line_items_downloaded = true
+        
+        @line_items
+        
+      # Otherwise, this is a new invoice, so return the line_items reference.
+      else
+        @line_items
+      end
+    end
+    
+    def ==(other)
+      ["invoice_number", "invoice_type", "invoice_status", "reference", "currency_code", "line_amount_types", "contact", "line_items"].each do |field|
+        return false if send(field) != other.send(field)
+      end
+      
+      ["date", "due_date"].each do |field|
+        return false if send(field).to_s != other.send(field).to_s
+      end
+      return true
+    end
+    
+    # General purpose create/save method.
+    # If invoice_id is nil then create, otherwise, attempt to save.
+    def save
+      if invoice_id.nil?
+        create
+      else
+        update
+      end
+    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
+    
+    # Updates this invoice record (using gateway.update_invoice) with the associated gateway.
+    # If no gateway set, raise a Xero::Invoice::NoGatewayError exception.
+    def update
+      raise NoGatewayError unless gateway
+      gateway.update_invoice(self)
+    end
+    
+    def to_xml(b = Builder::XmlMarkup.new)
+      b.Invoice {
+        b.InvoiceID self.invoice_id if self.invoice_id
+        b.InvoiceNumber self.invoice_number if invoice_number
+        b.Type self.invoice_type
+        b.CurrencyCode self.currency_code if self.currency_code
+        contact.to_xml(b)
+        b.Date Invoice.format_date(self.date || Date.today)
+        b.DueDate Invoice.format_date(self.due_date) if self.due_date
+        b.Status self.invoice_status if self.invoice_status
+        b.Reference self.reference if self.reference
+        b.LineAmountTypes self.line_amount_types
+        b.LineItems {
+          self.line_items.each do |line_item|
+            line_item.to_xml(b)
+          end
+        }
+        b.Url url if url
+      }
+    end
+    
+    #TODO UpdatedDateUTC
+    def self.from_xml(invoice_element, gateway = nil, options = {})
+      invoice = Invoice.new(options.merge({:gateway => gateway}))
+      invoice_element.children.each do |element|
+        case(element.name)
+          when "InvoiceID" then invoice.invoice_id = element.text
+          when "InvoiceNumber" then invoice.invoice_number = element.text            
+          when "Type" then invoice.invoice_type = element.text
+          when "CurrencyCode" then invoice.currency_code = element.text
+          when "Contact" then invoice.contact = Contact.from_xml(element)
+          when "Date" then invoice.date = parse_date(element.text)
+          when "DueDate" then invoice.due_date = parse_date(element.text)
+          when "FullyPaidOnDate" then invoice.fully_paid_on = parse_date(element.text)
+          when "Status" then invoice.invoice_status = element.text
+          when "Reference" then invoice.reference = element.text
+          when "LineAmountTypes" then invoice.line_amount_types = element.text
+          when "LineItems" then element.children.each {|line_item| invoice.line_items_downloaded = true; invoice.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 invoice.url = element.text
+          when "UpdatedDateUTC" then invoice.updated_date_utc = parse_utc_date_time(element.text)
+        end
+      end      
+      invoice
+    end    
+  end
+end

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