qbfc 0.3.0

data/lib/qbfc/qb_collection.rb

@@ -0,0 +1,26 @@
+module QBFC
+
+  # A QBCollection object is used as an intermediate object when doing finds,
+  # for example, in <tt>qb_session.customers.find(:all)</tt>, +customers+
+  # returns a QBCollection instance which then is sent the find call.
+  # The instance sends the find method on to the appropriate Class.
+  # The reason for having this intermediate class is to be able to
+  # pass a reference to the Session to the find method
+  # (or other class method).
+  # 
+  # There's probably no reason to use this class directly.
+  class QBCollection
+    
+    # +sess+ is a QBFC::Session object, +class_name+ is the name of
+    # a class descended from QBFC::Base.
+    def initialize(sess, class_name)
+      @sess = sess
+      @klass = QBFC::const_get(class_name)
+    end
+  
+    # Send any missing methods to the class, along with the +Session+ object
+    def method_missing(symbol, *params) #:nodoc:
+      @klass.send(symbol, @sess, *params)
+    end
+  end
+end

data/lib/qbfc/qb_types.rb

@@ -0,0 +1,18 @@
+# This file sets up the classes for QuickBooks entities, transactions and
+# reports that are not setup elsewhere (at this point, this file is only used
+# for "weird" classes.
+
+# Very non-standard elements.  I haven't yet formed an approach to dealing
+# with these; I leave them here as a reminder.
+QBFC_NON_STANDARD_TYPES = %w{ DataExt DataExtDef DataEventRecoveryInfo ItemAssembliesCanBuild}
+
+# Query types support Query requests only and return an itemized list of some sort;
+# most of these may be integrated as special finders for their types.
+QBFC_QUERY_TYPES =  %w{BillToPay ListDeleted ReceivePaymentToDeposit Template TxnDeleted}
+
+module QBFC
+  # Create QBElement classes
+  (QBFC_NON_STANDARD_TYPES + QBFC_QUERY_TYPES).uniq.each do | qb_element_name |
+    const_set(qb_element_name, Class.new(Base))
+  end
+end

data/lib/qbfc/qbfc_const.rb

@@ -0,0 +1,14 @@
+# QBFC_CONST contains constants defined by QBFC6.QBSessionManager.
+# For example:
+# 
+#   QBFC_CONST::DmToday # => 1 (for DateMacro)
+#   
+# The constants defined in the SDK documents all begin with a lower case letter.
+# In contrast, WIN32OLE capitalizes the constants to follow Ruby naming conventions:
+# 
+#   QBFC_CONST::DmToday instead of QBFC_CONST::dmToday
+
+module QBFC_CONST
+end
+
+WIN32OLE.const_load(WIN32OLE.new('QBFC6.QBSessionManager'), QBFC_CONST)

data/lib/qbfc/report.rb

@@ -0,0 +1,95 @@
+module QBFC
+  # This class is EXPERIMENTAL!
+  # This is a first stab at working with Reports.
+  class Report < Base    
+    class << self
+      # Return the class that a report belongs to. Takes a string (or symbol) of
+      # the report name. I could see refactoring this to use constants, later.
+      def get_class(report_name)
+        report_name = report_name.to_s
+        CLASSES.find {|klass| klass::REPORTS.include?(report_name)}
+      end
+      
+      # Run a query to retrieve a report. Typically called by +new+. See +new+
+      # for arguments.
+      def query(sess, name, *args)  
+        # Setup q, options and base_options arguments (base_options is not used)
+        q, options, base_options = parse_find_args(*args)
+        q ||= create_query(sess)
+        q.apply_options(options)
+        q.send(qb_name + 'Type').
+            SetValue(QBFC_CONST::const_get(self::REPORT_TYPE_PREFIX + name))
+        q.response
+      end
+      
+      # The QuickBooks name for this Report.
+      # It typically matches the last part of class name, plus 'Report'
+      # Used in determining names of Requests and other OLE methods.
+      def qb_name
+        self.name.split('::').last + 'Report'
+      end
+    
+      # Get a new Report.
+      # This is roughly equivalent with QBFC::Element::find.
+      # - <tt>sess</tt>: An open QBFC::Session object that will recieve all requests.
+      # - <tt>name</tt>: The name of the report.
+      # - <tt>args</tt>: TODO.
+      def get(sess, name, *args)
+        klass = get_class(name)
+        klass.new(sess, klass.query(sess, name, *args))
+      end
+    end
+    
+    def rows
+      @rows ||= QBFC::Reports::Rows::parse(@ole.report_data)
+    end
+    
+    def data
+      rows[:data]
+    end
+    
+    def subtotals
+      rows[:subtotals]
+    end
+    
+    def totals
+      rows[:totals]
+    end
+    
+    def text_rows
+      rows[:text]
+    end
+    
+    def cell(row_name, col_name)
+      rows[:data][row_name][col_for(col_name)]
+    end
+    
+    def col_for(name)
+      @ole.col_descs.each do |col|
+        col.col_titles.each do |title|
+          if title.value
+            if (title.value.GetValue() == name)
+              return col.colID.GetValue().to_i - 1
+            end
+          end
+        end
+      end
+    end
+  end
+end
+
+# Require subclass files
+Dir.new(File.dirname(__FILE__) + '/reports').each do |file|
+  require('qbfc/reports/' + File.basename(file)) if File.extname(file) == ".rb"
+end
+
+module QBFC
+  class Report < Base
+    # Set up CLASSES constant now that the referenced classes are loaded.
+    CLASSES = [QBFC::Reports::Aging, QBFC::Reports::BudgetSummary,
+               QBFC::Reports::CustomDetail, QBFC::Reports::CustomSummary,
+               QBFC::Reports::GeneralDetail, QBFC::Reports::GeneralSummary,
+               QBFC::Reports::Job, QBFC::Reports::PayrollDetail,
+               QBFC::Reports::PayrollSummary, QBFC::Reports::Time]
+  end
+end

data/lib/qbfc/reports/aging.rb

@@ -0,0 +1,13 @@
+module QBFC
+  module Reports
+    class Aging < QBFC::Report
+      REPORT_TYPE_PREFIX = 'Art'
+      
+      REPORTS = %w{APAgingDetail
+                   APAgingSummary
+                   ARAgingDetail
+                   ARAgingSummary
+                   CollectionsReport}
+    end
+  end
+end

data/lib/qbfc/reports/budget_summary.rb

@@ -0,0 +1,13 @@
+module QBFC
+  module Reports
+    class BudgetSummary < QBFC::Report
+      REPORT_TYPE_PREFIX = 'Bsrt'
+      
+      REPORTS = %w{BalanceSheetBudgetOverview 
+                   BalanceSheetBudgetVsActual
+                   ProfitAndLossBudgetOverview
+                   ProfitAndLossBudgetPerformance
+                   ProfitAndLossBudgetVsActual}
+    end
+  end
+end

data/lib/qbfc/reports/custom_detail.rb

@@ -0,0 +1,9 @@
+module QBFC
+  module Reports
+    class CustomDetail < QBFC::Report
+      REPORT_TYPE_PREFIX = 'Cdrt'
+      
+      REPORTS = %w{CustomTxnDetail}
+    end
+  end
+end

data/lib/qbfc/reports/custom_summary.rb

@@ -0,0 +1,9 @@
+module QBFC
+  module Reports
+    class CustomSummary < QBFC::Report
+      REPORT_TYPE_PREFIX = 'Csrt'
+      
+      REPORTS = %w{CustomSummary}
+    end
+  end
+end

data/lib/qbfc/reports/general_detail.rb

@@ -0,0 +1,44 @@
+module QBFC
+  module Reports
+    class GeneralDetail < QBFC::Report
+      REPORT_TYPE_PREFIX = 'Gdrt'
+      
+      REPORTS = %w{1099Detail
+                   AuditTrail
+                   BalanceSheetDetail
+                   CheckDetail
+                   CustomerBalanceDetail
+                   DepositDetail
+                   EstimatesByJob
+                   ExpenseByVendorDetail
+                   GeneralLedger
+                   IncomeByCustomerDetail
+                   IncomeTaxDetail
+                   InventoryValuationDetail
+                   JobProgressInvoicesVsEstimates
+                   Journal
+                   MissingChecks
+                   OpenInvoices
+                   OpenPOs
+                   OpenPOsByJob
+                   OpenSalesOrderByCustomer
+                   OpenSalesOrderByItem
+                   PendingSales
+                   ProfitAndLossDetail
+                   PurchaseByItemDetail
+                   PurchaseByVendorDetail
+                   SalesByCustomerDetail
+                   SalesByItemDetail
+                   SalesByRepDetail
+                   TxnDetailByAccount
+                   TxnListByCustomer
+                   TxnListByDate
+                   TxnListByVendor
+                   UnpaidBillsDetail
+                   UnbilledCostsByJob
+                   VendorBalanceDetail}
+    end
+  end
+end
+
+                   

data/lib/qbfc/reports/general_summary.rb

@@ -0,0 +1,33 @@
+module QBFC
+  module Reports
+    class GeneralSummary < QBFC::Report
+      REPORT_TYPE_PREFIX = 'Gsrt'
+      
+      REPORTS = %w{BalanceSheetPrevYearComp
+                   BalanceSheetStandard
+                   BalanceSheetSummary
+                   CustomerBalanceSummary
+                   ExpenseByVendorSummary
+                   IncomeByCustomerSummary
+                   InventoryStockStatusByItem
+                   InventoryStockStatusByVendor
+                   IncomeTaxSummary
+                   InventoryValuationSummary
+                   PhysicalInventoryWorksheet
+                   ProfitAndLossByClass
+                   ProfitAndLossByJob
+                   ProfitAndLossPrevYearComp
+                   ProfitAndLossStandard
+                   ProfitAndLossYTDComp
+                   PurchaseByItemSummary
+                   PurchaseByVendorSummary
+                   SalesByCustomerSummary
+                   SalesByItemSummary
+                   SalesByRepSummary
+                   SalesTaxLiability
+                   SalesTaxRevenueSummary
+                   TrialBalance
+                   VendorBalanceSummary}
+    end
+  end
+end

data/lib/qbfc/reports/job.rb

@@ -0,0 +1,14 @@
+module QBFC
+  module Reports
+    class Job < QBFC::Report
+      REPORT_TYPE_PREFIX = 'Jrt'
+      
+      REPORTS = %w{ItemEstimatesVsActuals
+                   ItemProfitability
+                   JobEstimatesVsActualsDetail
+                   JobEstimatesVsActualsSummary
+                   JobProfitabilityDetail
+                   JobProfitabilitySummary}
+    end
+  end
+end

data/lib/qbfc/reports/payroll_detail.rb

@@ -0,0 +1,13 @@
+module QBFC
+  module Reports
+    class PayrollDetail < QBFC::Report
+      REPORT_TYPE_PREFIX = 'Pdrt'
+      
+      REPORTS = %w{EmployeeStateTaxesDetail
+                   PayrollItemDetail
+                   PayrollReviewDetail
+                   PayrollTransactionDetail
+                   PayrollTransactionsByPayee}
+    end
+  end
+end

data/lib/qbfc/reports/payroll_summary.rb

@@ -0,0 +1,13 @@
+module QBFC
+  module Reports
+    class PayrollSummary < QBFC::Report
+      REPORT_TYPE_PREFIX = 'Psrt'
+      
+      REPORTS = %w{EmployeeEarningsSummary
+                   PayrollLiabilityBalances
+                   PayrollSummary}
+    end
+  end
+end
+
+                   

data/lib/qbfc/reports/rows.rb

@@ -0,0 +1,51 @@
+module QBFC
+  module Reports
+    class Rows < Array
+      class << self
+        def get_row(cols)
+          ret = []
+          if cols
+            cols.each do |col|
+              ret << col.value.getValue
+            end
+          end
+          ret
+        end
+  
+        def parse(report_data)
+          data = []
+          subtotals = []
+          totals = []
+          text = []
+          
+          report_data.o_r_report_datas.each do |d|
+            if d.DataRow
+              data << get_row(d.DataRow.col_datas)
+            elsif d.TextRow
+              text << d.TextRow.value.getValue
+            elsif d.SubtotalRow
+              subtotals << get_row(d.SubtotalRow.col_datas)
+            elsif d.TotalRow
+              totals << get_row(d.TotalRow.col_datas)
+            end
+  
+          end
+          
+          return {:data => new(data), 
+                  :subtotals => new(subtotals),
+                  :text => text,
+                  :totals => new(totals)}
+        end 
+      end
+            
+      def [](value)
+        if value.kind_of? String
+          self.detect{ |entry| entry[0] == value }
+        else
+          super
+        end
+      end
+          
+    end
+  end
+end

data/lib/qbfc/reports/time.rb

@@ -0,0 +1,12 @@
+module QBFC
+  module Reports
+    class Time < QBFC::Report
+      REPORT_TYPE_PREFIX = 'Trt'
+      
+      REPORTS = %w{TimeByItem
+                   TimeByJobDetail
+                   TimeByJobSummary
+                   TimeByName}
+    end
+  end
+end

data/lib/qbfc/request.rb

@@ -0,0 +1,295 @@
+module QBFC
+  # A QBFC::Request handles creating and sending a Request, including creating
+  # the RequestSet. Most often, RubyQBFC classes create and execute the Request
+  # internally, however, the Base.find, for example, accepts a QBFC::Request
+  # object as an argument if greater control is needed.
+  # 
+  # The WIN32OLE Request object is wrapped in OLEWrapper, so Ruby-esque methods
+  # can be used.
+  # 
+  #   req = QBFC::Request.new(qb_session, "CustomerQuery").
+  #     or_customer_list_query.customer_list_filter.max_returned = 2
+  #   puts req.response
+  class Request 
+  
+    # <tt>session</tt> is a QBFC::Session object (or a Session object not created through Ruby QBFC)
+    # <tt>request_type</tt> is the name of the request, not including trailing 'Rq',
+    # e.g. 'CustomerQuery', 'CustomerMod'
+    def initialize(sess, request_type, country = 'US', major_version = 6, minor_version = 0)
+      @sess = sess
+      
+      begin
+        @request_set = sess.CreateMsgSetRequest(country, major_version, minor_version)
+      rescue WIN32OLERuntimeError => error
+        if error.to_s =~ /error code:8004030A/
+          raise QBFC::QBXMLVersionError, "Unsupported qbXML version"
+        else
+          raise
+        end
+      end
+      
+      begin
+        @name = request_type
+        @request = @request_set.send("Append#{request_type}Rq")
+      rescue WIN32OLERuntimeError => error
+        if error.to_s =~ /error code:0x80020006/
+          raise QBFC::UnknownRequestError, "Unknown request name '#{request_type}'"
+        else
+          raise
+        end
+      end
+    end
+    
+    # Submit the requests. This returns the full (not wrapped) response object.
+    def submit
+      @sess.DoRequests(@request_set)
+    end
+    
+    # Submit the Request and return the response Detail, wrapped in OLEWrapper (unless nil).
+    # The response does not include any MsgSetResponse attributes.
+    def response
+      submit.ResponseList.GetAt(0).Detail
+    end
+    
+    # Is this Query for a Report? The 'conditions' are treated differently
+    def for_report?
+      @name =~ /Report$/
+    end
+    
+    # Get the OR*Query object of the given Request
+    # For example, the ORListQuery
+    def query
+      query_name = @request.ole_methods.detect{|m| m.to_s =~ /Query\Z/}
+      return nil if query_name.nil?
+      @request.send(query_name.to_s.to_sym)
+    end
+    
+    # Get the *Filter object of the given Request
+    # For example, the ListFilter
+    def filter
+      q = self.query
+      return nil if q.nil?
+      filter_name = q.ole_methods.detect{|m| m.to_s =~ /Filter\Z/}
+      return nil if filter_name.nil?
+      q.send(filter_name.to_s.to_sym)
+    end
+    
+    # Returns where the filter is available for use. That is, that
+    # none of the query options other than filter have been used
+    def filter_available?
+      # -1 = unused, 2 = Filter used
+      self.query.ole_object.ortype == -1 ||
+        self.query.ole_object.ortype == 2
+    end
+       
+    # Applies options from a Hash. This method is generally used by find methods
+    # (see Element.find for details)
+    def apply_options(options)      
+      if options.kind_of? Hash
+        conditions = options.delete(:conditions) || {}
+        
+        conditions.each do | c_name, c_value |
+          c_name = c_name.to_s
+          
+          case c_name
+          when /list\Z/i
+            # List filters
+            list = query.__send__(c_name.camelize)
+            c_value = [c_value] unless c_value.kind_of?(Array)
+            c_value.each { |i| list.Add(i) }
+          when /range\Z/i
+            # Range filters
+            c_value = parse_range_value(c_value)
+            range_filter = filter_for(c_name)
+            range_name = c_name.match(/(.*)_range\Z/i)[1]
+            if range_name == 'modified_date'
+              # Modified Date Range use the IQBDateTimeType which requires a\
+              # boolean 'asDateOnly' value.
+              range_filter.__send__("from_#{range_name}=", c_value.first, true) if c_value.first
+              range_filter.__send__("to_#{range_name}=", c_value.last, true) if c_value.last
+            else
+              range_filter.__send__("from_#{range_name}=", c_value.first) if c_value.first
+              range_filter.__send__("to_#{range_name}=", c_value.last) if c_value.last
+            end
+          when /status\Z/i
+            # Status filters
+            filter.__send__("#{c_name}=", c_value)
+          else
+            # Reference filters - Only using FullNameList for now
+            ref_filter = filter_for(c_name)
+            c_value = [c_value] unless c_value.respond_to?(:each)
+            c_value.each do | val |
+              ref_filter.FullNameList.Add(val)
+            end
+          end
+        end
+          
+        add_owner_ids(options.delete(:owner_id))
+        add_limit(options.delete(:limit))
+        add_includes(options.delete(:include))
+
+        options.each do |key, value|
+          self.send(key.to_s.camelize).SetValue(value)
+        end
+      end
+    end    
+    
+    # Add one or more OwnerIDs to the Request. Used in retrieving
+    # custom fields (aka private data extensions).
+    # Argument should be a single ID or an Array of IDs.
+    def add_owner_ids(ids)
+      return if ids.nil?
+      
+      ids = [ids] unless ids.respond_to?(:each)
+      ids.each do | id |
+        @request.OwnerIDList.Add(id)
+      end
+    end
+    
+    # Set MaxReturned to limit the number of records returned.
+    def add_limit(limit)
+      filter.max_returned = limit if limit
+    end
+    
+    # add_includes accepts an Array of elements to include in the return of the
+    # Request. The array may include either or both of elements that are
+    # additional to normal returns (such as Line Items, Linked Transactions)
+    # or elements that are normally included (to be added to the
+    # IncludeRetElementList).
+    # 
+    # If elements are given that would be added to IncludeRetElementList, this
+    # limits the elements returned to *only* those included in the array.
+    # 
+    # Another option is to give :all as the argument, which will always return
+    # as many elements as possible.
+    # 
+    # add_includes is typically called by #apply_options, typically called
+    # from Element.find, as seen in the examples below:
+    # 
+    #   @sess.checks.find(:all, :include => [:linked_txns]) -> Include linked transactions
+    #   @sess.checks.find(:all, :include => [:txn_id]) -> Include +only+ TxnID
+    #   @sess.checks.find(:all, :include => :all) ->
+    #     Includes all elements, including LinkedTxns and LineItems.
+    def add_includes(inc)
+      return if inc.nil?
+      
+      inc = [inc] if (!inc.respond_to?(:each) || inc.kind_of?(String))
+      
+      if inc.include?(:all)
+        ole_methods.each do |m|
+          m = m.to_s
+          if m =~ /\AInclude/ && m != 'IncludeRetElementList'
+            @request.__send__("#{m.underscore}=", true)
+          end
+        end
+        return
+      end
+      
+      inc.each do |item|
+        cam_item = item.to_s.camelize.gsub(/Id/, "ID")
+        if @request.respond_to_ole?("Include#{cam_item}")
+          @request.__send__("include_#{item}=", true)
+        else
+          @request.IncludeRetElementList.Add(cam_item)
+        end
+      end
+    end
+    
+    # Parse a value for a range filter. This can be a Range, a one or more
+    # element Array or a single value. For a single value or one-element array
+    # value#last should return nil. The calling method (#apply_options) will
+    # call value#first and value#last to set the from and to values
+    # respectively.
+    def parse_range_value(value)
+      value << nil if value.kind_of?(Array) && value.length == 1
+      value = [value, nil] if (value.kind_of?(String) || !value.respond_to?(:first))
+      value
+    end
+    
+    # Determine and return the Filter object for the given filter name, dealing
+    # with OR's and other "weird" circumstances.
+    # NB: This method may well miss some situations. Hopefully, it will become
+    # more complete in time.
+    def filter_for(name)
+      name = name.camelize + "Filter"
+      f = nil
+      
+      # List queries place the modified_date_range directly in the filter
+      if name == 'ModifiedDateRangeFilter'
+        return filter if filter.respond_to_ole?('FromModifiedDate')
+      end
+      
+      # Report Periods are more or less special circumstance
+      if name =~ /^Report[Period|Date]/
+        return @request.ORReportPeriod.ReportPeriod
+      end
+      
+      # Try to get the filter directly
+      if filter.respond_to_ole?(name)
+        f = filter.send(name)
+      end
+
+      # Transaction Date Range Filters change name.
+      if name == 'TxnDateRangeFilter' &&
+          filter.respond_to_ole?('TransactionDateRangeFilter')
+        f = filter.send("TransactionDateRangeFilter").
+            send("ORTransactionDateRangeFilter").
+            send("TxnDateRange")
+      end
+      
+      # Check if this is within an 'OR'
+      if filter.respond_to_ole?("OR#{name}")
+        f = filter.send("OR#{name}").send(name)
+      elsif filter.respond_to_ole?("OR#{name.gsub(/Range/, '')}")
+        f = filter.send("OR#{name.gsub(/Range/, '')}").send(name)
+      end
+      
+      # DateRange OR's
+      if filter.respond_to_ole?("ORDateRangeFilter") && name =~ /DateRange/i
+        f = filter.send("ORDateRangeFilter").send(name)
+      end
+
+      # It might have a nested OR      
+      if f && f.respond_to_ole?("OR#{name}")
+        f = f.send("OR#{name}")
+      end
+      
+      # Ranges might have another step, with the 'Range' removed.
+      if f && f.respond_to_ole?(name.gsub(/Range/, ''))
+        f = f.send(name.gsub(/Range/, ''))
+      end
+      
+      return f
+    end
+    
+    private :parse_range_value, :filter_for
+    
+    # Send missing methods to @ole_object (OLEWrapper)
+    def method_missing(symbol, *params) #:nodoc:
+      @request.qbfc_method_missing(@sess, symbol, *params)
+    end
+    
+    # Return Array of ole_methods for request WIN32OLE object.
+    # This is mostly useful for debugging.
+    def ole_methods
+      @request.ole_methods
+    end
+
+    # Return XML for the request WIN32OLE object.
+    # This is mostly useful for debugging.
+    def to_xml
+      @request_set.ToXMLString
+    end
+
+    # Submit Request and return full response as XML.
+    # This is mostly useful for debugging.    
+    def response_xml
+      @sess.DoRequests(@request_set).ToXMLString
+    end
+    
+    # Return actual WIN32OLE object
+    def ole_object
+      @request.ole_object
+    end
+  end
+end