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

data/lib/xeroizer/private_application.rb

@@ -0,0 +1,26 @@
+module Xeroizer
+  class PrivateApplication < GenericApplication
+
+    extend Forwardable
+    def_delegators :client, :authorize_from_access
+
+    public
+
+      # Private applications are defined in the Xero API website and can be accessed in the
+      # background without ever requiring a redirect to the Xero website for authorisation.
+      #
+      # @param [String] consumer_key consumer key/token from application developer (found at http://api.xero.com for your application).
+      # @param [String] consumer_secret consumer secret from application developer (found at http://api.xero.com for your application).
+      # @param [String] path_to_private_key application's private key for message signing (uploaded to http://api.xero.com)
+      # @param [Hash] options other options to pass to the GenericApplication constructor
+      # @return [PrivateApplication] instance of PrivateApplication
+      def initialize(consumer_key, consumer_secret, path_to_private_key, options = {})
+        options[:signature_method] = 'RSA-SHA1'
+        options[:private_key_file] = path_to_private_key
+        client = OAuth.new(consumer_key, consumer_secret, options)
+        super(client, options)
+        @client.authorize_from_access(consumer_key, consumer_secret)
+      end
+
+  end
+end

data/lib/xeroizer/public_application.rb

@@ -0,0 +1,22 @@
+module Xeroizer
+  class PublicApplication < GenericApplication
+
+    extend Forwardable
+    def_delegators :client, :request_token, :authorize_from_request, :authorize_from_access
+
+    public
+
+      # Public appliations are authenticated via the Xero website via OAuth. AccessTokens are valid for 30 minutes
+      # after authentication. To extend this time you must redirect the user to Xero's OAuth server again.
+      #
+      # @param [String] consumer_key consumer key/token from application developer (found at http://api.xero.com for your application)
+      # @param [String] consumer_secret consumer secret from application developer (found at http://api.xero.com for your application)
+      # @param [Hash] options other options to pass to the GenericApplication constructor
+      # @return [PublicApplication] instance of PrivateApplication
+      def initialize(consumer_key, consumer_secret, options = {})
+        client = OAuth.new(consumer_key, consumer_secret, options)
+        super(client, options)
+      end
+
+  end
+end

data/lib/xeroizer/record/application_helper.rb

@@ -0,0 +1,32 @@
+module Xeroizer
+  module Record
+    module ApplicationHelper
+      
+      # Factory for new BaseModel instances with the class name `record_type`.
+      # Only creates the instance if one doesn't already exist.
+      #
+      # @param [Symbol] record_type Symbol of the record type (e.g. :Invoice)
+      # @return [BaseModel] instance of BaseModel subclass matching `record_type`
+      def record(record_type)
+        define_method record_type do
+          var_name = "@#{record_type}_cache".to_sym
+          unless instance_variable_defined?(var_name)
+            instance_variable_set(var_name, Xeroizer::Record.const_get("#{record_type}Model".to_sym).new(self, record_type.to_s))
+          end
+          instance_variable_get(var_name)
+        end  
+      end
+      
+      def report(report_type)
+        define_method report_type do
+          var_name = "@#{report_type}_cache".to_sym
+          unless instance_variable_defined?(var_name)
+            instance_variable_set(var_name, Xeroizer::Report::Factory.new(self, report_type.to_s))
+          end
+          instance_variable_get(var_name)
+        end
+      end
+      
+    end
+  end
+end

data/lib/xeroizer/record/base.rb

@@ -0,0 +1,203 @@
+require 'xeroizer/record/model_definition_helper'
+require 'xeroizer/record/record_association_helper'
+require 'xeroizer/record/validation_helper'
+require 'xeroizer/record/xml_helper'
+require 'xeroizer/logging'
+
+module Xeroizer
+  module Record
+
+    class Base
+
+      include ClassLevelInheritableAttributes
+      class_inheritable_attributes :fields, :possible_primary_keys, :primary_key_name, :summary_only, :validators
+
+      attr_reader :attributes
+      attr_reader :parent
+      attr_reader :model
+      attr_accessor :errors
+      attr_accessor :complete_record_downloaded
+      attr_accessor :paged_record_downloaded
+
+      include ModelDefinitionHelper
+      include RecordAssociationHelper
+      include ValidationHelper
+      include XmlHelper
+
+      class << self
+
+        # Build a record with attributes set to the value of attributes.
+        def build(attributes, parent)
+          record = new(parent)
+          attributes.each do | key, value |
+            attr = record.respond_to?("#{key}=") || record.class.fields[key].nil? ? key : record.class.fields[key][:internal_name]
+            record.send("#{attr}=", value)
+          end
+          record
+        end
+
+      end
+
+      public
+
+        def initialize(parent)
+          @parent = parent
+          @model = new_model_class(self.class.name.demodulize)
+          @attributes = {}
+        end
+
+        def new_model_class(model_name)
+          Xeroizer::Record.const_get("#{model_name}Model".to_sym).new(parent.try(:application), model_name.to_s)
+        end
+
+        def [](attribute)
+          self.send(attribute)
+        end
+
+        def []=(attribute, value)
+          parent.mark_dirty(self) if parent
+          self.send("#{attribute}=".to_sym, value)
+        end
+
+        def non_calculated_attributes
+          attributes.reject {|name| self.class.fields[name][:calculated] }
+        end
+
+        def attributes=(new_attributes)
+          return unless new_attributes.is_a?(Hash)
+          parent.mark_dirty(self) if parent
+          new_attributes.each do | key, value |
+            attr = respond_to?("#{key}=") ? key : self.class.fields[key][:internal_name]
+            self.send("#{attr}=", value)
+          end
+        end
+
+        def update_attributes(attributes)
+          self.attributes = attributes
+          save
+        end
+
+        def new_record?
+          id.nil?
+        end
+
+        # Check to see if the complete record is downloaded.
+        def complete_record_downloaded?
+          if !!self.class.list_contains_summary_only?
+            !!complete_record_downloaded
+          else
+            true
+          end
+        end
+
+
+        def paged_record_downloaded?
+          !!paged_record_downloaded
+        end
+
+        # Downloads the complete record if we only have a summary of the record.
+        def download_complete_record!
+          record = self.parent.find(self.id)
+          @attributes = record.attributes if record
+          @complete_record_downloaded = true
+          parent.mark_clean(self)
+          self
+        end
+
+        def save
+          save!
+          true
+        rescue XeroizerError => e
+          log "[ERROR SAVING] (#{__FILE__}:#{__LINE__}) - #{e.message}"
+          false
+        end
+
+        def save!
+          raise RecordInvalid unless valid?
+          if new_record?
+            create
+          else
+            update
+          end
+
+          saved!
+        end
+
+        def saved!
+          @complete_record_downloaded = true
+          parent.mark_clean(self)
+          true
+        end
+
+        def to_json(*args)
+          to_h.to_json(*args)
+        end
+
+        # Deprecated
+        def as_json(options = {})
+          to_h.to_json
+        end
+
+        def to_h
+          attrs = self.attributes.reject {|k, v| k == :parent }.map do |k, v|
+            [k, v.kind_of?(Array) ? v.map(&:to_h) : (v.respond_to?(:to_h) ? v.to_h : v)]
+          end
+          Hash[attrs]
+        end
+
+        def inspect
+          attribute_string = self.attributes.collect do |attr, value|
+            "#{attr.inspect}: #{value.inspect}"
+          end.join(", ")
+          "#<#{self.class} #{attribute_string}>"
+        end
+
+      protected
+
+        # Attempt to create a new record.
+        def create
+          request = to_xml
+          log "[CREATE SENT] (#{__FILE__}:#{__LINE__}) #{request}"
+
+          response = parent.send(parent.create_method, request)
+
+          log "[CREATE RECEIVED] (#{__FILE__}:#{__LINE__}) #{response}"
+
+          parse_save_response(response)
+        end
+
+        # Attempt to update an existing record.
+        def update
+          if self.class.possible_primary_keys && self.class.possible_primary_keys.all? { | possible_key | self[possible_key].nil? }
+            raise RecordKeyMustBeDefined.new(self.class.possible_primary_keys)
+          end
+
+          request = to_xml
+
+          log "[UPDATE SENT] (#{__FILE__}:#{__LINE__}) \r\n#{request}"
+
+          response = parent.http_post(request)
+
+          log "[UPDATE RECEIVED] (#{__FILE__}:#{__LINE__}) \r\n#{response}"
+
+          parse_save_response(response)
+        end
+
+        # Parse the response from a create/update request.
+        def parse_save_response(response_xml)
+          response = parent.parse_response(response_xml)
+          record = response.response_items.first if response.response_items.is_a?(Array)
+          if record && record.is_a?(self.class)
+            @attributes = record.attributes
+          end
+          self
+        end
+
+        def log(what)
+          Xeroizer::Logging::Log.info what
+        end
+
+    end
+
+  end
+end

data/lib/xeroizer/record/base_model.rb

@@ -0,0 +1,253 @@
+require 'xeroizer/record/base_model_http_proxy'
+
+module Xeroizer
+  module Record
+
+    class BaseModel
+
+      include ClassLevelInheritableAttributes
+      class_inheritable_attributes :api_controller_name
+
+      module InvaidPermissionError; end
+      class InvalidPermissionError < XeroizerError
+        include InvaidPermissionError
+      end
+      ALLOWED_PERMISSIONS = [:read, :write, :update]
+      class_inheritable_attributes :permissions
+
+      class_inheritable_attributes :xml_root_name
+      class_inheritable_attributes :optional_xml_root_name
+      class_inheritable_attributes :xml_node_name
+
+      DEFAULT_RECORDS_PER_BATCH_SAVE = 50
+
+      include BaseModelHttpProxy
+
+      attr_reader :application
+      attr_reader :model_name
+      attr_writer :model_class
+      attr_reader :response
+
+      class << self
+
+        # Method to allow override of the default controller name used
+        # in the API URLs.
+        #
+        # Default: pluaralized model name (e.g. if the controller name is
+        # Invoice then the default is Invoices.
+        def set_api_controller_name(controller_name)
+          self.api_controller_name = controller_name
+        end
+
+        # Set the permissions allowed for this class type.
+        # There are no permissions set by default.
+        # Valid permissions are :read, :write, :update.
+        def set_permissions(*args)
+          self.permissions = {}
+          args.each do | permission |
+            raise InvalidPermissionError.new("Permission #{permission} is invalid.") unless ALLOWED_PERMISSIONS.include?(permission)
+            self.permissions[permission] = true
+          end
+        end
+
+        # Method to allow override of the default XML node name.
+        #
+        # Default: singularized model name in camel-case.
+        def set_xml_node_name(node_name)
+          self.xml_node_name = node_name
+        end
+
+        # Method to allow override of the default XML root name to use
+        # in has_many associations.
+        def set_xml_root_name(root_name)
+          self.xml_root_name = root_name
+        end
+
+        # Method to add an extra top-level node to use in has_many associations.
+        def set_optional_xml_root_name(optional_root_name)
+          self.optional_xml_root_name = optional_root_name
+        end
+
+      end
+
+      public
+
+      def initialize(application, model_name)
+        @application = application
+        @model_name = model_name
+        @allow_batch_operations = false
+        @objects = {}
+      end
+
+      # Retrieve the controller name.
+      #
+      # Default: pluaralized model name (e.g. if the controller name is
+      # Invoice then the default is Invoices.
+      def api_controller_name
+        self.class.api_controller_name || model_name.pluralize
+      end
+
+      def model_class
+        @model_class ||= Xeroizer::Record.const_get(model_name.to_sym)
+      end
+
+      # Build a record with attributes set to the value of attributes.
+      def build(attributes = {})
+        model_class.build(attributes, self).tap do |resource|
+          mark_dirty(resource)
+        end
+      end
+
+      def mark_dirty(resource)
+        if @allow_batch_operations
+          @objects[model_class] ||= {}
+          @objects[model_class][resource.object_id] ||= resource
+        end
+      end
+
+      def mark_clean(resource)
+        if @objects and @objects[model_class]
+          @objects[model_class].delete(resource.object_id)
+        end
+      end
+
+      # Create (build and save) a record with attributes set to the value of attributes.
+      def create(attributes = {})
+        build(attributes).tap { |resource| resource.save }
+      end
+
+      # Retrieve full record list for this model.
+      def all(options = {})
+        raise MethodNotAllowed.new(self, :all) unless self.class.permissions[:read]
+        response_xml = http_get(parse_params(options))
+        response = parse_response(response_xml, options)
+        response.response_items || []
+      end
+
+      # allow invoices to be process in batches of 100 as per xero documentation
+      # https://developer.xero.com/documentation/api/invoices/
+      def find_in_batches(options = {}, &block)
+        options[:page] ||= 1
+        while results = all(options)
+          if results.any?
+            yield results
+            options[:page] += 1
+          else
+            break
+          end
+        end
+      end
+
+      # Helper method to retrieve just the first element from
+      # the full record list.
+      def first(options = {})
+        raise MethodNotAllowed.new(self, :all) unless self.class.permissions[:read]
+        result = all(options)
+        result.first if result.is_a?(Array)
+      end
+
+      # Retrieve record matching the passed in ID.
+      def find(id, options = {})
+        raise MethodNotAllowed.new(self, :all) unless self.class.permissions[:read]
+        response_xml = @application.http_get(@application.client, "#{url}/#{CGI.escape(id)}", options)
+        response = parse_response(response_xml, options)
+        result = response.response_items.first if response.response_items.is_a?(Array)
+        result.complete_record_downloaded = true if result
+        result
+      end
+
+      def save_records(records, chunk_size = DEFAULT_RECORDS_PER_BATCH_SAVE)
+        no_errors = true
+        return false unless records.all?(&:valid?)
+
+        actions = records.group_by {|o| o.new_record? ? create_method : :http_post }
+        actions.each_pair do |http_method, records_for_method|
+          records_for_method.each_slice(chunk_size) do |some_records|
+            request = to_bulk_xml(some_records)
+            response = parse_response(self.send(http_method, request, {:summarizeErrors => false}))
+            response.response_items.each_with_index do |record, i|
+              if record and record.is_a?(model_class)
+                some_records[i].attributes = record.non_calculated_attributes
+                some_records[i].errors = record.errors
+                no_errors = record.errors.nil? || record.errors.empty? if no_errors
+                some_records[i].saved!
+              end
+            end
+          end
+        end
+
+        no_errors
+      end
+
+      def batch_save(chunk_size = DEFAULT_RECORDS_PER_BATCH_SAVE)
+        @objects = {}
+        @allow_batch_operations = true
+
+        begin
+          yield
+
+          if @objects[model_class]
+            objects = @objects[model_class].values.compact
+            save_records(objects, chunk_size)
+          end
+        ensure
+          @objects = {}
+          @allow_batch_operations = false
+        end
+      end
+
+      def parse_response(response_xml, options = {})
+        Response.parse(response_xml, options) do | response, elements, response_model_name |
+          if model_name == response_model_name
+            @response = response
+            parse_records(response, elements, paged_records_requested?(options), (options[:base_module] || Xeroizer::Record))
+          end
+        end
+      end
+
+      def create_method
+        :http_put
+      end
+
+      protected
+
+
+      def paged_records_requested?(options)
+        options.has_key?(:page) and options[:page].to_i >= 0
+      end
+
+      # Parse the records part of the XML response and builds model instances as necessary.
+      def parse_records(response, elements, paged_results, base_module)
+        elements.each do | element |
+          new_record = model_class.build_from_node(element, self, base_module)
+          if element.attribute('status').try(:value) == 'ERROR'
+            new_record.errors = []
+            element.xpath('.//ValidationError').each do |err|
+              new_record.errors << err.text.gsub(/^\s+/, '').gsub(/\s+$/, '')
+            end
+          end
+          new_record.paged_record_downloaded = paged_results
+          response.response_items << new_record
+        end
+      end
+
+      def to_bulk_xml(records, builder = Builder::XmlMarkup.new(:indent => 2))
+        tag = (self.class.optional_xml_root_name || model_name).pluralize
+        builder.tag!(tag) do
+          records.each {|r| r.to_xml(builder) }
+        end
+      end
+
+      # Parse the response from a create/update request.
+      def parse_save_response(response_xml)
+        response = parse_response(response_xml)
+        record = response.response_items.first if response.response_items.is_a?(Array)
+        if record && record.is_a?(self.class)
+          @attributes = record.attributes
+        end
+        self
+      end
+    end
+
+  end
+end