xeroizer 0.1.0

data/lib/xeroizer/record/application_helper.rb

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

data/lib/xeroizer/record/base.rb

@@ -0,0 +1,116 @@
+require 'xeroizer/record/model_definition_helper'
+require 'xeroizer/record/record_association_helper'
+require 'xeroizer/record/validation_helper'
+require 'xeroizer/record/xml_helper'
+
+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_accessor :errors
+      attr_accessor :complete_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 |
+            record.send("#{key}=".to_sym, value)
+          end
+          record
+        end
+        
+      end
+      
+      public
+      
+        def initialize(parent)
+          @parent = parent
+          @attributes = {}
+        end
+        
+        def new_model_class(model_name)
+          Xeroizer::Record.const_get("#{model_name}Model".to_sym).new(parent.application, model_name.to_s)
+        end
+        
+        def [](attribute)
+          self.send(attribute)
+        end
+        
+        def []=(attribute, value)
+          self.send("#{attribute}=", value)
+        end
+        
+        def new_record?
+          self.class.possible_primary_keys.all? { | key | @attributes[key].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
+        
+        # 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
+          self
+        end
+        
+        def save
+          return false unless valid?
+          if new_record?
+            create
+          else
+            update
+          end
+          true
+        end
+                
+      protected
+      
+        # Attempt to create a new record.
+        def create
+          parse_save_response(parent.http_put(to_xml))
+        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
+          
+          parse_save_response(parent.http_post(to_xml))
+        end
+        
+        # Parse the response from a create/update request.
+        def parse_save_response(response_xml)
+          record = parent.parse_response(response_xml)
+          record = record.first if record.is_a?(Array)
+          if record && record.is_a?(self.class)
+            @attributes = record.attributes
+          end
+          self
+        end
+                     
+    end
+    
+  end
+end

data/lib/xeroizer/record/base_model.rb

@@ -0,0 +1,138 @@
+require 'xeroizer/record/base_model_http_proxy'
+
+module Xeroizer
+  module Record
+    
+    class BaseModel
+      
+      include ClassLevelInheritableAttributes
+      class_inheritable_attributes :api_controller_name
+      
+      class InvaidPermissionError < StandardError; end
+      ALLOWED_PERMISSIONS = [:read, :write, :update]
+      class_inheritable_attributes :permissions
+      
+      include BaseModelHttpProxy
+
+      attr_reader :application
+      attr_reader :model_name
+      attr :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 InvaidPermissionError.new("Permission #{permission} is invalid.") unless ALLOWED_PERMISSIONS.include?(permission)
+            self.permissions[permission] = true
+          end
+        end
+        
+      end
+            
+      public
+        
+        def initialize(application, model_name)
+          @application = application
+          @model_name = model_name
+        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)
+        end
+        
+        # Retreive 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))
+          parse_response(response_xml, options) || []
+        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)
+          result = parse_response(response_xml, options)
+          result = result.first if result.is_a?(Array)
+          result.complete_record_downloaded = true if result
+          result
+        end
+        
+        # Parse the response retreived during any request.
+        def parse_response(raw_response, request = {}, options = {})
+          @response = Xeroizer::Response.new
+          @response.response_xml = raw_response
+          
+          doc = Nokogiri::XML(raw_response) { | cfg | cfg.noblanks }
+          
+          # check for responses we don't understand
+          raise Xeroizer::UnparseableResponse.new(doc.root.name) unless doc.root.name == 'Response'
+          
+          doc.root.elements.each do | element |
+                        
+            # Text element
+            if element.children && element.children.size == 1 && element.children.first.text?
+              case element.name
+                when 'Id'           then @response.id = element.text
+                when 'Status'       then @response.status = element.text
+                when 'ProviderName' then @response.provider = element.text
+                when 'DateTimeUTC'  then @response.date_time = Time.parse(element.text)
+              end
+              
+            # Records in response
+            elsif element.children && element.children.size > 0 && element.children.first.name == model_name
+              parse_records(element.children)
+            end
+          end
+          
+          @response.response_items
+        end
+        
+      protected
+        
+        # Parse the records part of the XML response and builds model instances as necessary.
+        def parse_records(elements)
+          @response.response_items = []
+          elements.each do | element |
+            @response.response_items << model_class.build_from_node(element, self)
+          end
+        end
+        
+    end
+    
+  end
+end

data/lib/xeroizer/record/base_model_http_proxy.rb

@@ -0,0 +1,134 @@
+module Xeroizer
+  module Record
+    module BaseModelHttpProxy
+      
+      def self.included(base)
+        base.send :include, InstanceMethods
+      end
+      
+      module InstanceMethods
+        
+        public
+
+          # URL end-point for this model.
+          def url
+            @application.xero_url + '/' + api_controller_name
+          end
+
+          def http_get(extra_params = {})
+            application.http_get(application.client, url, extra_params)
+          end
+
+          def http_put(xml, extra_params = {})
+            application.http_put(application.client, url, xml, extra_params)
+          end
+
+          def http_post(xml, extra_params = {})
+            application.http_post(application.client, url, xml, extra_params)
+          end
+        
+        protected
+        
+          # Parse parameters for GET requests.
+          def parse_params(options)
+            params = {}
+            params[:ModifiedAfter]  = options[:modified_since] if options[:modified_since]          
+            params[:OrderBy]        = options[:order] if options[:order]
+            if options[:where]
+              params[:where] =  case options[:where]
+                                  when String   then options[:where] 
+                                  when Hash     then parse_where_hash(options[:where])
+                                end
+            end
+            params[:offset] = options[:offset] if options[:offset]
+            params
+          end
+        
+          # Parse the :where part of the options for GET parameters and construct a valid
+          # .Net version of the criteria to pass to Xero.
+          #
+          # Attribute names can be modified as follows to change the expression used:
+          #   {attribute_name}_is_greater_than or {attribute_name}> uses '>'
+          #   {attribute_name}_is_greater_than_or_equal_to or {attribute_name}>= uses '>='
+          #   {attribute_name}_is_less_than or {attribute_name}< uses '<'
+          #   {attribute_name}_is_less_than_or_equal_to or {attribute_name}< uses '<='
+          #   DEFAULT: '=='
+          def parse_where_hash(where)
+            conditions = []
+            where.each do | key, value |
+              (attribute_name, expression) = extract_expression_from_attribute_name(key)
+              (field_name, field) = model_class.fields.find { | k, v | v[:internal_name] == attribute_name }
+              if field
+                conditions << where_condition_part(field, expression, value)                
+              else
+                raise InvalidAttributeInWhere.new(model_name, attribute_name)
+              end
+            end
+            escaped_where = CGI.escape(conditions.map { | (attr, expression, value) | "#{attr}#{expression}#{value}"}.join('&&'))
+            escaped_where
+          end
+        
+          # Extract the attribute name and expression from the attribute.
+          #
+          # @return [Array] containing [actual_attribute_name, expression]
+          def extract_expression_from_attribute_name(key)
+            case key.to_s
+              when /(_is_not|\<\>)$/
+                [
+                  key.to_s.gsub(/(_is_not|\<\>)$/, '').to_sym,
+                  '<>'
+                ]
+              
+              when /(_is_greater_than|\>)$/
+                [
+                  key.to_s.gsub(/(_is_greater_than|\>)$/, '').to_sym,
+                  '>'
+                ]
+              
+              when /(_is_greater_than_or_equal_to|\>\=)$/
+                [
+                  key.to_s.gsub(/(_is_greater_than_or_equal_to|\>\=)$/, '').to_sym,
+                  '>='
+                ]
+              
+              when /(_is_less_than|\<)$/
+                [
+                  key.to_s.gsub(/(_is_less_than|\<)$/, '').to_sym,
+                  '<'
+                ]
+              
+              when /(_is_less_than_or_equal_to|\<\=)$/
+                [
+                  key.to_s.gsub(/(_is_less_than_or_equal_to|\<\=)$/, '').to_sym,
+                  '<='
+                ]
+                              
+              else
+                [key, '==']
+              
+            end
+          end
+        
+          # Creates a condition part array containing the:
+          #   * Field's API name
+          #   * Expression
+          #   * .Net formatted value.
+          def where_condition_part(field, expression, value)
+            case field[:type]
+              when :guid        then ["#{field[:api_name]}.ToString()", expression, "\"#{value}\""]
+              when :string      then [field[:api_name], expression, "\"#{value}\""]
+              when :boolean     then [field[:api_name], expression, value ? 'true' : 'false']
+              when :integer     then [field[:api_name], expression, value.to_s]
+              when :decimal     then [field[:api_name], expression, value.to_s]
+              when :date        then [field[:api_name], expression, "DateTime.Parse(\"#{value.strftime("%Y-%m-%d")}\")"]
+              when :datetime    then [field[:api_name], expression, "DateTime.Parse(\"#{value.utc.strftime("%Y-%m-%dT%H:%M:%S")}\")"]
+              when :belongs_to  then
+              when :has_many    then
+            end
+          end
+
+      end
+    
+    end
+  end
+end

data/lib/xeroizer/record/model_definition_helper.rb

@@ -0,0 +1,94 @@
+module Xeroizer
+  module Record
+    module ModelDefinitionHelper
+      
+      def self.included(base)
+        base.extend(ClassMethods)
+        base.send :include, InstanceMethods
+      end
+      
+      module ClassMethods
+
+        # Possible primary keys. At least one of these must exist before attempting to update a record.
+        def set_possible_primary_keys(*args)
+          args = [args] unless args.is_a?(Array)
+          self.possible_primary_keys = args
+        end
+        
+        # Set the actual Xero primary key for this record.
+        def set_primary_key(primary_key_name)
+          self.primary_key_name = primary_key_name
+        end
+        
+        # Whether this record type's list results contain summary data only.
+        #
+        # Records like invoices, when returning a list, only show summary data for
+        # certain types of associations (like the contact record) and do not return
+        # any data for line items.
+        #
+        # Default: false
+        def list_contains_summary_only(status)
+          self.summary_only = status
+        end
+        
+        def list_contains_summary_only?
+          !!summary_only
+        end
+              
+        # Helper methods used to define the fields this model has.
+        def string(field_name, options = {});     define_simple_attribute(field_name, :string, options); end
+        def boolean(field_name, options = {});    define_simple_attribute(field_name, :boolean, options); end
+        def integer(field_name, options = {});    define_simple_attribute(field_name, :integer, options, 0); end
+        def decimal(field_name, options = {});    define_simple_attribute(field_name, :decimal, options, 0.0); end
+        def date(field_name, options = {});       define_simple_attribute(field_name, :date, options); end
+        def datetime(field_name, options = {});   define_simple_attribute(field_name, :datetime, options); end
+        
+        def guid(field_name, options = {})
+          # Ensure all automated Id conversions are changed to ID.
+          options[:api_name] ||= field_name.to_s.camelize.gsub(/Id/, 'ID')
+          define_simple_attribute(field_name, :guid, options)
+        end
+              
+        # Helper method to simplify field definition. 
+        # Creates an accessor and reader for the field.
+        # Options:
+        #   :internal_name => allows the specification of an internal field name differing from the API's field name.
+        #   :api_name => allows the API name to be specified if it can't be properly converted from camelize.
+        #   :model_name => allows class used for children to be different from it's ndoe name in the XML.
+        #   :type => type of field
+        def define_simple_attribute(field_name, field_type, options, value_if_nil = nil)
+          self.fields ||= {}
+          
+          internal_field_name = options[:internal_name] || field_name
+          self.fields[field_name] = options.merge({
+            :internal_name  => internal_field_name, 
+            :api_name       => options[:api_name] || field_name.to_s.camelize,
+            :type           => field_type
+          })
+          define_method internal_field_name do 
+            @attributes[field_name] || value_if_nil
+          end
+          define_method "#{internal_field_name}=".to_sym do | value | 
+            @attributes[field_name] = value
+          end
+        end
+        
+      end
+      
+      module InstanceMethods
+        
+        # Returns the value of the Xero primary key for this record if it exists.
+        def id
+          self[self.class.primary_key_name]
+        end
+
+        # Sets the value of the Xero primary key for this record if it exists.
+        def id=(new_id)
+          self[self.class.primary_key_name] = new_id
+        end
+        
+      end
+      
+    end
+  end
+end