xeroizer-3-pre-beta 3.0.0.pre.beta

data/lib/xeroizer/configuration.rb

@@ -0,0 +1,19 @@
+module Xeroizer
+  OAuthCredentials = Struct.new "OAuthCredentials", :consumer_key, :consumer_secret, :key_file
+
+  class OAuthConfig
+    class << self
+      def load yaml_text
+        require "yaml"
+        yaml = YAML.load yaml_text
+        consumer_credential = yaml["consumer"]
+
+        OAuthCredentials.new(
+          consumer_credential["key"],
+          consumer_credential["secret"],
+          consumer_credential["key_file"]
+        )
+      end
+    end
+  end
+end

data/lib/xeroizer/connection.rb

@@ -0,0 +1,31 @@
+module Xeroizer
+  class Connection
+    class << self
+      def current_connections(client)
+        response = do_request(client)
+
+        if response.success?
+          JSON.parse(response.plain_body).map do |connection_json|
+            new(connection_json)
+          end
+        else
+          raise Xeroizer::OAuth::TokenInvalid, response.plain_body
+        end
+      end
+
+      private
+
+      def do_request(client)
+        client.get('https://api.xero.com/connections')
+      end
+    end
+
+    def initialize(json)
+      @json = json
+    end
+
+    def method_missing(name, *_args)
+      @json.send(:[], name.to_s.camelcase(:lower))
+    end
+  end
+end

data/lib/xeroizer/exceptions.rb

@@ -0,0 +1,161 @@
+# Copyright (c) 2008 Tim Connor <tlconnor@gmail.com>
+# 
+# Permission to use, copy, modify, and/or distribute this software for any
+# purpose with or without fee is hereby granted, provided that the above
+# copyright notice and this permission notice appear in all copies.
+# 
+# THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+# WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+# MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+# ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+# WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+# ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+# OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+
+module Xeroizer
+  
+  class XeroizerError < StandardError; end
+  
+  class ApiException < XeroizerError
+    
+    attr_reader :type, :message, :xml, :parsed_xml, :request_body
+    
+    def initialize(type, message, xml, parsed_xml, request_body)
+      @type         = type
+      @message      = message
+      @xml          = xml
+      @parsed_xml   = parsed_xml
+      @request_body = request_body
+    end
+    
+    def message
+      "#{@type}: #{@message} \n Generated by the following XML: \n #{@xml}"
+    end
+
+    def validation_errors
+      errors = []
+      @parsed_xml.xpath("//ValidationError").each do |err|
+        errors << err.text.gsub(/^\s+/, '').gsub(/\s+$/, '')
+      end
+      errors
+    rescue
+      []
+    end
+    
+  end
+  
+  class UnparseableResponse < XeroizerError
+    
+    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 < XeroizerError
+    
+    def initialize(api_endpoint)
+      @api_endpoint = api_endpoint
+    end
+    
+    def message
+      "Couldn't find object for API Endpoint #{@api_endpoint}"
+    end
+    
+  end
+  
+  class InvoiceNotFoundError < XeroizerError; end
+
+  class CreditNoteNotFoundError < XeroizerError; end
+  
+  class MethodNotAllowed < XeroizerError
+    
+    def initialize(klass, method)
+      @klass = klass
+      @method = method
+    end
+    
+    def message
+      "Method #{@method} not allowed on #{@klass}"
+    end
+    
+  end
+  
+  class RecordKeyMustBeDefined < XeroizerError
+    
+    def initialize(possible_keys)
+      @possible_keys = possible_keys
+    end
+    
+    def message
+      "One of the keys #{@possible_keys.join(', ')} need to be defined to update the record."
+    end
+    
+  end
+
+  class RecordInvalid < XeroizerError; end
+
+  class SettingTotalDirectlyNotSupported < XeroizerError
+    
+    def initialize(attribute_name)
+      @attribute_name = attribute_name
+    end
+    
+    def message
+      "Can't set the total #{@attribute_name} directly as this is calculated automatically."
+    end
+    
+  end
+
+  class InvalidAttributeInWhere < XeroizerError
+    
+    def initialize(model_name, attribute_name)
+      @model_name = model_name
+      @attribute_name = attribute_name
+    end
+    
+    def message
+      "#{@attribute_name} is not an attribute of #{@model_name}."
+    end
+    
+  end
+  
+  class AssociationTypeMismatch < XeroizerError
+    
+    def initialize(model_class, actual_class)
+      @model_class = model_class
+      @actual_class = actual_class
+    end
+  
+    def message
+      "#{@model_class} expected, got #{@actual_class}"
+    end
+    
+  end
+
+  class CannotChangeInvoiceStatus < XeroizerError
+
+    def initialize(invoice, new_status)
+      @invoice = invoice
+      @new_status = new_status
+    end
+
+    def message
+      case @new_status
+        when 'DELETED', 'VOIDED'
+          unless @invoice.payments.size == 0
+            "There must be no payments in this invoice to change to '#{@new_status}'"
+          end
+
+      end
+    end
+
+  end
+
+  class InvalidClientError < XeroizerError; end
+  
+end

data/lib/xeroizer/generic_application.rb

@@ -0,0 +1,90 @@
+require 'xeroizer/record/application_helper'
+
+module Xeroizer
+  class GenericApplication
+
+    include Http
+    extend Record::ApplicationHelper
+
+    attr_reader :client, :logger, :rate_limit_sleep, :rate_limit_max_attempts,
+                :default_headers, :unitdp, :before_request, :after_request, :around_request, :nonce_used_max_attempts
+
+    attr_accessor :xero_url
+
+    extend Forwardable
+    def_delegators :client, :access_token
+
+    record :Account
+    record :Allocation
+    record :Attachment
+    record :Balances
+    record :BatchPayment
+    record :BrandingTheme
+    record :Contact
+    record :ContactGroup
+    record :CreditNote
+    record :Currency
+    record :Employee
+    record :ExpenseClaim
+    record :Invoice
+    record :InvoiceReminder
+    record :OnlineInvoice
+    record :Item
+    record :Journal
+    record :LineItem
+    record :ManualJournal
+    record :Organisation
+    record :Payment
+    record :PaymentService
+    record :Prepayment
+    record :Overpayment
+    record :PurchaseOrder
+    record :Receipt
+    record :RepeatingInvoice
+    record :Schedule
+    record :TaxRate
+    record :TrackingCategory
+    record :TrackingCategoryChild
+    record :BankTransaction
+    record :BankTransfer
+    record :User
+
+    report :AgedPayablesByContact
+    report :AgedReceivablesByContact
+    report :BalanceSheet
+    report :BankStatement
+    report :BankSummary
+    report :BudgetSummary
+    report :ExecutiveSummary
+    report :ProfitAndLoss
+    report :TrialBalance
+
+    public
+
+      # Never used directly. Use sub-classes instead.
+      # @see PublicApplication
+      # @see PrivateApplication
+      # @see PartnerApplication
+      def initialize(client, options = {})
+        raise Xeroizer::InvalidClientError.new unless [OAuth, OAuth2].member?(client.class)
+        @xero_url = options[:xero_url] || "https://api.xero.com/api.xro/2.0"
+        @rate_limit_sleep = options[:rate_limit_sleep] || false
+        @rate_limit_max_attempts = options[:rate_limit_max_attempts] || 5
+        @nonce_used_max_attempts = options[:nonce_used_max_attempts] || 1
+        @default_headers = options[:default_headers] || {}
+        @before_request = options.delete(:before_request)
+        @after_request = options.delete(:after_request)
+        @around_request = options.delete(:around_request)
+        @client = client
+        @logger = options[:logger] || false
+        @unitdp = options[:unitdp] || 2
+      end
+
+      def payroll(options = {})
+        xero_client = self.clone
+        xero_client.xero_url = options[:xero_url] || "https://api.xero.com/payroll.xro/1.0"
+        @payroll ||= PayrollApplication.new(xero_client)
+      end
+
+  end
+end

data/lib/xeroizer/http.rb

@@ -0,0 +1,160 @@
+# Copyright (c) 2008 Tim Connor <tlconnor@gmail.com>
+#
+# Permission to use, copy, modify, and/or distribute this software for any
+# purpose with or without fee is hereby granted, provided that the above
+# copyright notice and this permission notice appear in all copies.
+#
+# THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+# WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+# MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+# ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+# WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+# ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+# OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+
+module Xeroizer
+  module Http
+    class BadResponse < XeroizerError; end
+    RequestInfo = Struct.new(:url, :headers, :params, :body, :method)
+
+    ACCEPT_MIME_MAP = {
+      :pdf  => 'application/pdf',
+      :json => 'application/json'
+    }
+
+    # Shortcut method for #http_request with `method` = :get.
+    #
+    # @param [OAuth] client OAuth client
+    # @param [String] url URL of request
+    # @param [Hash] extra_params extra query string parameters.
+    def http_get(client, url, extra_params = {})
+      http_request(client, :get, url, nil, extra_params)
+    end
+
+    # Shortcut method for #http_request with `method` = :post.
+    #
+    # @param [OAuth] client OAuth client
+    # @param [String] url URL of request
+    # @param [String] body XML message to post.
+    # @param [Hash] extra_params extra query string parameters.
+    def http_post(client, url, body, extra_params = {})
+      http_request(client, :post, url, body, extra_params)
+    end
+
+    # Shortcut method for #http_request with `method` = :put.
+    #
+    # @param [OAuth] client OAuth client
+    # @param [String] url URL of request
+    # @param [String] body XML message to put.
+    # @param [Hash] extra_params extra query string parameters.
+    def http_put(client, url, body, extra_params = {})
+      http_request(client, :put, url, body, extra_params)
+    end
+
+    private
+
+    def http_request(client, method, url, request_body, params = {})
+      # headers = {'Accept-Encoding' => 'gzip, deflate'}
+
+      headers = self.default_headers.merge({ 'charset' => 'utf-8' })
+
+      # include the unitdp query string parameter
+      params.merge!(unitdp_param(url))
+
+      if method != :get
+        headers['Content-Type'] ||= "application/x-www-form-urlencoded"
+      end
+
+      content_type = params.delete(:content_type)
+      headers['Content-Type'] = content_type if content_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]
+
+      # Allow 'Accept' header to be specified with :accept parameter.
+      # Valid values are :pdf or :json.
+      if params[:response]
+        response_type = params.delete(:response)
+        headers['Accept'] = case response_type
+          when Symbol then  ACCEPT_MIME_MAP[response_type]
+          else              response_type
+        end
+      end
+
+      if params.any?
+        url += "?" + params.map {|key, value| "#{CGI.escape(key.to_s)}=#{CGI.escape(value.to_s)}"}.join("&")
+      end
+
+      uri = URI.parse(url)
+
+      attempts = 0
+
+      request_info = RequestInfo.new(url, headers, params, request_body, method)
+      before_request.call(request_info) if before_request
+
+      begin
+        attempts += 1
+        logger.info("XeroGateway Request: #{method.to_s.upcase} #{uri.request_uri}") if self.logger
+
+        raw_body = params.delete(:raw_body) ? request_body : {:xml => request_body}
+
+        response = with_around_request(request_info) do
+          case method
+            when :get   then    client.get(uri.request_uri, headers)
+            when :post  then    client.post(uri.request_uri, raw_body, headers)
+            when :put   then    client.put(uri.request_uri, raw_body, headers)
+          end
+        end
+
+        log_response(response, uri)
+        after_request.call(request_info, response) if after_request
+
+        HttpResponse.from_response(response, request_body, url).body
+      rescue Xeroizer::OAuth::NonceUsed => exception
+        raise if attempts > nonce_used_max_attempts
+        logger.info("Nonce used: " + exception.to_s) if self.logger
+        sleep_for(1)
+        retry
+      rescue Xeroizer::OAuth::RateLimitExceeded
+        if self.rate_limit_sleep
+          raise if attempts > rate_limit_max_attempts
+          logger.info("Rate limit exceeded, retrying") if self.logger
+          sleep_for(self.rate_limit_sleep)
+          retry
+        else
+          raise
+        end
+      end
+    end
+
+    def with_around_request(request, &block)
+      if around_request
+        around_request.call(request, &block)
+      else
+        block.call
+      end
+    end
+
+    def log_response(response, uri)
+      if self.logger
+        logger.info("XeroGateway Response (#{response.code})")
+        logger.add(response.code.to_i == 200 ? Logger::DEBUG : Logger::INFO) {
+          "#{uri.request_uri}\n== Response Body\n\n#{response.plain_body}\n== End Response Body"
+        }
+      end
+    end
+
+    def sleep_for(seconds = 1)
+      sleep seconds
+    end
+
+    # unitdp query string parameter to be added to request params
+    # when the application option has been set and the model has line items
+    # https://developer.xero.com/documentation/api-guides/rounding-in-xero#unitamount
+    def unitdp_param(request_url)
+      models = [/Invoices/, /CreditNotes/, /BankTransactions/, /Receipts/, /Items/, /Overpayments/, /Prepayments/]
+      self.unitdp == 4 && models.any?{ |m| request_url =~ m } ? {:unitdp => 4} : {}
+    end
+
+  end
+end