xeroizer 0.1.3 → 0.2.0

data/README.md

@@ -1,4 +1,4 @@
-Xeroizer API Library
+Xeroizer API Library ![Project status](http://stillmaintained.com/waynerobinson/xeroizer.png)
 ====================
 
 **Homepage**: 		[http://waynerobinson.github.com/xeroizer](http://waynerobinson.github.com/xeroizer)		
@@ -420,3 +420,49 @@ that attribute. For example:
 
 If something goes really wrong and the particular validation isn't handled by the internal
 validators then the library may raise a `Xeroizer::ApiException`.
+
+Reports
+-------
+
+All Xero reports except GST report can be accessed through Xeroizer.
+
+Currently, only generic report access functionality exists. This will be extended
+to provide a more report-specific version of the data in the future (public submissions
+are welcome).
+
+Reports are accessed like the following example:
+
+	trial_balance = xero.TrialBalance.get(:date => '2011-03-21')
+	
+	# Array containing report headings.
+	trial_balance.header.cells.map { | cell | cell.value }
+	
+	# Report rows by section
+	trial_balance.sections.each do | section |
+		puts "Section Title: #{section.title}"
+		section.rows.each do | row |
+			puts "\t#{row.cells.map { | cell | cell.value }.join("\t")}"
+		end
+	end
+	
+	# Summary row (if only one on the report)
+	trial_balance.summary.cells.map { | cell | cell.value }
+	
+	# All report rows (including HeaderRow, SectionRow, Row and SummaryRow)
+	trial_balance.rows.each do | row |
+		case row
+			when Xeroizer::Report::HeaderRow
+				# do something with header
+				
+			when Xeroizer::Report::SectionRow
+				# do something with section, will need to step into the rows for this section
+				
+			when Xeroizer::Report::Row
+				# do something for standard report rows
+				
+			when Xeroizer::Report::SummaryRow
+				# do something for summary rows
+				
+		end
+	end
+	

data/VERSION

@@ -1 +1 @@
-0.1.3
+0.2.0

data/lib/xeroizer.rb

@@ -47,6 +47,8 @@ require 'xeroizer/models/tax_rate'
 require 'xeroizer/models/tracking_category'
 require 'xeroizer/models/tracking_category_child'
 
+require 'xeroizer/report/factory'
+
 require 'xeroizer/response'
 
 require 'xeroizer/generic_application'

data/lib/xeroizer/application_http_proxy.rb

@@ -0,0 +1,30 @@
+module Xeroizer
+  module ApplicationHttpProxy
+    
+    def self.included(base)
+      base.send :include, InstanceMethods
+    end
+    
+    module InstanceMethods
+      
+      # 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
+      
+    end
+    
+  end
+end

data/lib/xeroizer/generic_application.rb

@@ -25,6 +25,16 @@ module Xeroizer
     record :TaxRate
     record :TrackingCategory
     
+    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.

data/lib/xeroizer/record/application_helper.rb

@@ -17,6 +17,16 @@ module Xeroizer
         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_model.rb

@@ -92,43 +92,20 @@ module Xeroizer
           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)
+        def parse_response(response_xml, options = {})
+          Response.parse(response_xml, options) do | response, elements, response_model_name |
+            if model_name == response_model_name
+              parse_records(response, elements)
             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 = []
+        def parse_records(response, elements)
           elements.each do | element |
-            @response.response_items << model_class.build_from_node(element, self)
+            response.response_items << model_class.build_from_node(element, self)
           end
         end
         

data/lib/xeroizer/record/base_model_http_proxy.rb

@@ -1,32 +1,16 @@
+require 'xeroizer/application_http_proxy' 
+
 module Xeroizer
   module Record
     module BaseModelHttpProxy
       
       def self.included(base)
+        base.send :include, Xeroizer::ApplicationHttpProxy
         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.

data/lib/xeroizer/report/base.rb

@@ -0,0 +1,43 @@
+require 'xeroizer/report/base'
+require 'xeroizer/report/cell'
+require 'xeroizer/report/row/row'
+require 'xeroizer/report/row/header'
+require 'xeroizer/report/row/section'
+require 'xeroizer/report/row/summary'
+require 'xeroizer/report/xml_helper'
+
+module Xeroizer
+  module Report
+    class Base
+      
+      include XmlHelper
+      
+      attr_reader :factory
+      
+      attr_accessor :id
+      attr_accessor :name
+      attr_accessor :type
+      attr_accessor :titles
+      attr_accessor :date
+      attr_accessor :updated_at
+      
+      attr_accessor :rows
+      
+      attr_accessor :header
+      attr_accessor :summary
+      attr_accessor :sections
+            
+      public
+      
+        def initialize(factory)
+          @titles = []
+          @rows = []
+          @sections = []
+          @factory = factory
+        end
+      
+      protected
+                  
+    end
+  end
+end

data/lib/xeroizer/report/cell.rb

@@ -0,0 +1,32 @@
+require 'xeroizer/report/cell_xml_helper'
+
+module Xeroizer
+  module Report
+    class Cell
+      
+      include CellXmlHelper
+      
+      attr_accessor :value
+      attr_accessor :attributes
+      
+      public
+      
+        def initialize
+          @attributes = {}
+        end
+      
+        # Return first attribute's ID in the hash. Assumes there is only one as hashes get out of order.
+        # In all cases I've seen so far there is only one attribute returned.
+        def attribute_id
+          @attributes.each { | id, value | return id }
+        end
+        
+        # Return first attribute's value in the hash. Assumes there is only one as hashes get out of order.
+        # In all cases I've seen so far there is only one attribute returned.
+        def attribute_value
+          @attributes.each { | id, value | return value }
+        end
+      
+    end
+  end
+end

data/lib/xeroizer/report/cell_xml_helper.rb

@@ -0,0 +1,71 @@
+module Xeroizer
+  module Report
+    module CellXmlHelper
+    
+      def self.included(base)
+        base.extend(ClassMethods)
+        base.send :include, InstanceMethods
+      end
+    
+      module ClassMethods
+      
+        public
+      
+          # Create an instance of Cell from the node.
+          #
+          # Additionally, parse the attributes and return them as a hash to the 
+          # cell. If a cell's attributes look like:
+          #
+          #     <Attributes>
+          #       <Attribute>
+          #         <Value>1335b8b2-4d63-4af8-937f-04087ae2e36e</Value>
+          #         <Id>account</Id>
+          #       </Attribute>
+          #     </Attributes>
+          # 
+          # Return a hash like:
+          #
+          #     {
+          #       'account' => '1335b8b2-4d63-4af8-937f-04087ae2e36e'
+          #     }
+          def build_from_node(node)
+            cell = new
+            node.elements.each do | element |
+              case element.name.to_s
+                when 'Value' then cell.value = potentially_convert_to_number(element.text)
+                when 'Attributes'
+                  element.elements.each do | attribute_node |
+                    (id, value) = parse_attribute(attribute_node)
+                    cell.attributes[id] = value
+                  end
+              end
+            end
+            cell
+          end
+          
+        protected
+        
+          # If a cell's value is a valid number then return it is as BigDecimal.
+          def potentially_convert_to_number(value)
+            value =~ /^[-]?\d+(\.\d+)?$/ ? BigDecimal.new(value) : value
+          end
+          
+          def parse_attribute(attribute_node)
+            id = nil
+            value = nil
+            attribute_node.elements.each do | element |
+              case element.name.to_s
+                when 'Id'     then id = element.text
+                when 'Value'  then value = element.text
+              end
+            end
+            [id, value]
+          end
+      end
+    
+      module InstanceMethods
+      end
+    
+    end
+  end
+end

data/lib/xeroizer/report/factory.rb

@@ -0,0 +1,43 @@
+require 'xeroizer/application_http_proxy' 
+require 'xeroizer/report/base'
+
+module Xeroizer
+  module Report
+    class Factory
+      
+      include ApplicationHttpProxy
+
+      attr_reader :application
+      attr_reader :report_type
+      
+      public
+      
+        def initialize(application, report_type)
+          @application = application
+          @report_type = report_type
+        end
+      
+        # Retreive a report with the `options` as a hash containing
+        # valid query-string parameters to pass to the API.
+        def get(options = {})
+          response_xml = options[:cache_file] ? File.read(options[:cache_file]) : http_get(options)          
+          Response.parse(response_xml, options) do | response, elements |
+            parse_reports(response, elements)
+          end.first # there is is only one
+        end
+      
+        def api_controller_name
+          "Report/#{report_type}"
+        end
+
+      protected
+              
+        def parse_reports(response, elements)
+          elements.each do | element |
+            response.response_items << Base.build_from_node(element, self)
+          end
+        end
+        
+    end
+  end
+end

data/lib/xeroizer/report/row/header.rb

@@ -0,0 +1,7 @@
+module Xeroizer
+  module Report
+    class HeaderRow < Row
+            
+    end
+  end
+end

data/lib/xeroizer/report/row/row.rb

@@ -0,0 +1,43 @@
+require 'xeroizer/report/row/xml_helper'
+
+module Xeroizer
+  module Report
+    class Row
+      
+      include RowXmlHelper
+      
+      attr_reader :report
+      
+      attr_accessor :type
+      attr_accessor :title
+      attr_accessor :rows
+      attr_accessor :cells
+      
+      attr_accessor :parent
+      
+      attr_accessor :header
+      
+      public
+      
+        def initialize(report)
+          @rows = []
+          @cells = []
+          @report = report
+        end
+        
+        def header?;  @type == 'Header';      end
+        def summary?; @type == 'SummaryRow';  end
+        def section?; @type == 'Section';     end
+        def row?;     @type == 'Row';         end
+           
+        def child?
+          !parent.nil?
+        end
+        
+        def parent?
+          rows.size > 0
+        end
+        
+    end
+  end
+end