qbfc 0.3.0

data/.gitignore

@@ -0,0 +1,11 @@
+*.sw?
+.DS_Store
+coverage
+rdoc
+pkg
+.project
+.loadpath
+*qt_temp*
+*~
+*.qbw.nd
+spec/tmp

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2008 Jared E Morgan
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.rdoc

@@ -0,0 +1,85 @@
+==QBFC-Ruby
+
+QBFC-Ruby provides a wrapper around QuickBooks' QBFC COM object, while
+allowing more or less direct access to the actual COM object.
+
+Obviously, test before using on your production data...
+
+==Find
+
+QBFC-Ruby supports +find+ queries with options, which utitilize QBFC's Query
+Requests. See QBFC::Element.find for details and options.
+
+  QBFC::session do | qb |
+    checks = qb.checks.find(:first, :conditions => {:entity => 'ABC Supplies'})
+  end
+
+==Relationships
+
+QBFC-Ruby supports loading of related records. These are records
+represented by "*Ref" in the QBFC documentation. For example, a Check
+has, among others, a PayeeEntityRef and an AccountRef. These can be
+accessed via, respectively, <tt>check.payee</tt> and <tt>check.account</tt>.
+
+<tt>check.payee.name</tt> returns the name of the payee.
+
+You can also access the *ID and Name fields of referenced records.
+Example: for the payee of a Check, <tt>check.payee_id</tt> and
+<tt>check.payee_name</tt>.
+
+==General Examples
+
+  # A very simple example, finding a single Customer by name
+  QBFC::session do | qb |
+    puts qb.customer('Customer Name').full_name
+  end
+  
+  # Find all Customer, then return the first in the Array
+  # Next, find the first Customer only
+  QBFC::session do | qb |
+    customers = qb.customers.find(:all)
+    puts customers[0].full_name
+    puts qb.customers.find(:first).full_name
+  end
+
+  # Same as previous, but not using a block  
+  sess = QBFC::Session.new
+  customers = QBFC::Customer.find(sess, :all)
+  puts customers[0].full_name
+  puts QBFC::Customer.find(sess, :first).full_name
+  sess.close
+
+  # Use a QBFC::Session object, but access the COM object
+  # more directly.
+  QBFC::session do | qb |
+    request_set = qb.CreateMsgSetRequest("US", 6, 0)
+    customer_query = request_set.AppendCustomerQueryRq	
+    response = qb.DoRequests(request_set)
+    customer_set = response.ResponseList[0]
+    first_customer = customer_set.Detail[0]
+    puts first_customer.full_name
+  end
+  
+==Alternatives
+
+[QuickBooks for Ruby]
+  (docs: http://quickbooks.rubyforge.org,
+  homepage: http://rubyforge.org/projects/quickbooks)
+
+  This is a project with similar goals to QBFC-Ruby. I believe the approach
+  is creating Ruby classes that mirror the QuickBooks types and generate / parse
+  qbXML. In my opinion, this approach is more stable and flexible than what I'm
+  doing with QBFC-Ruby, but at the cost of slower development. (As in, QBFC-Ruby
+  was intended as a collection of quick and dirty shortcuts; QuickBooks for Ruby
+  seems to be intended as a much more *complete* project)
+
+[QBFC/qbXML COM Objects]
+  Using the SDK directly is an option. Unless you need to use QBWC (QuickBooks
+  Web Connector) or have some other reason for *wanting* to us qbXML, I suggest
+  using QBFC. The SDK documents (see http://developer.intuit.com/ ) are pretty
+  easy to use and navigate.
+
+There are some other libraries on rubyforge in early stages which I haven't
+really explored.
+
+Copyright (c) 2008 Jared E. Morgan, released under the MIT license

data/Rakefile

@@ -0,0 +1,84 @@
+require 'rubygems'
+require 'rake'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "qbfc"
+    gem.rubyforge_project = "qbfc"
+    gem.summary = "A wrapper around the QBFC COM object of the Quickbooks SDK"
+    gem.description = %q{QBFC-Ruby wraps the QBFC COM object of the QuickBooks 
+SDK, providing ease-of-use improvements, such as lower-case method names, 
+and find, save, delete, void, and create operations.}
+    gem.email = "jmorgan@morgancreative.net"
+    gem.homepage = "http://rubyforge.org/projects/qbfc/"
+    gem.authors = ["Jared Morgan"]
+    # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
+  end
+  
+  rf = Jeweler::RubyforgeTasks.new
+  rf.remote_doc_path = ''
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: sudo gem install jeweler"
+end
+
+require 'spec/rake/spectask'
+
+QBFC_ROOT = File.dirname(__FILE__)
+
+desc "Run all specs in spec/unit directory"
+Spec::Rake::SpecTask.new(:spec) do |spec|
+  spec.libs << 'lib' << 'spec'
+  spec.pattern = 'spec/unit/**/*_spec.rb'
+  spec.spec_opts = ['--options', "\"#{QBFC_ROOT}/spec/spec.opts\""]
+end
+
+namespace :spec do
+  desc "Run all specs in spec/unit directory with RCov"
+  Spec::Rake::SpecTask.new(:rcov) do |spec|
+    spec.libs << 'lib' << 'spec'
+    spec.pattern = 'spec/unit/**/*_spec.rb'
+    spec.spec_opts = ['--options', "\"#{QBFC_ROOT}/spec/spec.opts\""]
+    spec.rcov = true
+    spec.rcov_opts = lambda do
+      IO.readlines("#{QBFC_ROOT}/spec/rcov.opts").map {|l| l.chomp.split " "}.flatten
+    end
+  end
+  
+  desc "Run all specs in spec/integration directory"
+  Spec::Rake::SpecTask.new(:integration) do |spec|
+    spec.libs << 'lib' << 'spec'
+    spec.pattern = 'spec/integration/**/*_spec.rb'
+    spec.spec_opts = ['--options', "\"#{QBFC_ROOT}/spec/spec.opts\""]
+  end
+  
+  desc "Run all specs in spec/integration directory with RCov"
+  Spec::Rake::SpecTask.new(:integration_rcov) do |spec|
+    spec.libs << 'lib' << 'spec'
+    spec.pattern = 'spec/unit/**/*_spec.rb'
+    spec.spec_opts = ['--options', "\"#{QBFC_ROOT}/spec/spec.opts\""]
+    spec.rcov = true
+    spec.rcov_opts = lambda do
+      IO.readlines("#{QBFC_ROOT}/spec/rcov.opts").map {|l| l.chomp.split " "}.flatten
+    end
+  end
+
+end
+
+task :default => :spec
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  if File.exist?('VERSION')
+    version = File.read('VERSION')
+  else
+    version = ""
+  end
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "QBFC-Ruby #{version}"
+  rdoc.options << '--line-numbers' << '--inline-source'
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/VERSION

@@ -0,0 +1 @@
+0.3.0

data/lib/qbfc.rb

@@ -0,0 +1,41 @@
+require 'win32ole'
+require 'time'
+
+# ActiveSupport is used for camelize, singularize and similar String inflectors.
+unless Object.const_defined?(:ActiveSupport)
+  gem 'activesupport'
+  require 'active_support'
+end
+
+module QBFC
+  VERSION = '0.3.0'
+  
+  class << self
+  
+    # Opens and yields a QBFC::Session
+    def session(*args, &block)
+      QBFC::Session::open(*args, &block)
+    end
+  
+    # Generate classes.
+    # - +names+: Array of class names.
+    # - +superclass+: Superclass of classes to be generated.
+    # - +includes+: hash of Module => names of classes to include this module.
+    def generate(names, superclass, include_modules = {})
+      names.each do | class_name |
+        const_set(class_name, Class.new(superclass))
+      end
+      
+      include_modules.each do | mod, classes |
+        classes.each do | class_name |
+          const_get(class_name).__send__(:include, mod)
+        end
+      end
+    end
+    
+  end
+end
+
+%w{ ole_wrapper qbfc_const session request base element info report qb_collection qb_types }.each do |file|
+  require 'qbfc/' + file
+end

data/lib/qbfc/base.rb

@@ -0,0 +1,82 @@
+module QBFC
+  # Base is the...um..."base" class from which Element, Info, and
+  # Report inherit. It defines methods that the three share.
+  class Base
+    class << self
+        
+      # is_base_class? is used by Element and subclasses. It is included
+      # in Base because some Base methods may check for it.
+      def is_base_class? #:nodoc:
+        false
+      end
+      
+      # Element::find and Info::get receive optional arguments which can include
+      # a Request object and/or an options Hash. <tt>parse_find_args</tt>
+      # gets these arguments into a set that is easier to deal with.
+      def parse_find_args(*args)
+        request = args[0].kind_of?(QBFC::Request) ? args[0].dup : nil
+        options = args[-1].kind_of?(Hash) ? args[-1].dup : {}
+        
+        # base classes will need to pass a subset of options to
+        # the ChildClass.find . Also, the actually options to the
+        # BaseClass.find Request cannot include owner_id.
+        if is_base_class?
+          base_options = options.dup 
+          base_options.delete(:conditions)
+          options.delete(:owner_id)
+        else
+          base_options = nil
+        end
+        
+        return request, options, base_options
+      end
+      
+      # A convenience method for creating and returning
+      # a Query Request for this class.
+      def create_query(sess)
+        QBFC::Request.new(sess, "#{qb_name}Query")
+      end
+      
+      protected :parse_find_args, :create_query
+    
+      # The QuickBooks name for this Element or Report.
+      # It typically matches the last part of class name.
+      # Used in determining names of Requests and other
+      # OLE methods.
+      def qb_name
+        self.name.split('::').last
+      end
+    end
+    
+    # Create an instance of this Element or Report.
+    # - <tt>sess</tt>: An open QBFC::Session object that will recieve all requests
+    # - <tt>ole</tt>: An optional QBFC::OLEWrapper object representing
+    #   a response to a QueryRq. It is unlikely that this will be used directly.
+    def initialize(sess, ole = nil)
+      @sess, @ole = sess, ole    
+      @ole = QBFC::OLEWrapper.new(@ole) if @ole.kind_of?(WIN32OLE)    
+    end
+    
+    # List the methods of the OLE object
+    def ole_methods
+      @ole.ole_methods
+    end
+    
+    # Check if the OLE object responds to a given method
+    def respond_to_ole?(symbol)
+      @ole.respond_to_ole?(symbol)
+    end
+    
+    # Pass missing methods to OLEWrapper#qbfc_method_missing
+    # to handle checking if there is a related OLE method to run.
+    def method_missing(symbol, *params)
+      @ole.qbfc_method_missing(@sess, symbol, *params)
+    end
+    
+    # Name of the QuickBooks Element or Query represented by this class.
+    def qb_name
+      self.class.qb_name
+    end
+  end
+end
+

data/lib/qbfc/element.rb

@@ -0,0 +1,243 @@
+require 'qbfc/modifiable'
+
+module QBFC
+
+  # An Element is a Transaction or a List; that is any QuickBooks objects that can
+  # be created, edited (possibly), deleted and read. Contrast to a Report or Info
+  # which are read-only.
+  # 
+  # Inheritance from Element implies a set of shared methods, such as find, but the
+  # only shared implementation defined here is #custom, for getting custom field information.
+  class Element < Base
+
+    class << self
+      # Set that this is a "base class", one which is inherited,
+      # such as List, Transaction, Entity, or Terms.
+      # Base classes do not accept Add Requests, and their finders
+      # will return an instance of an inherited class.
+      def is_base_class
+        @is_base_class = true
+      end
+      
+      # Check if this is a "base class" (see is_base_class)
+      def is_base_class?
+        @is_base_class ? true : false
+      end
+      
+      # Find a QuickBooks record for the given session. 
+      # 
+      # session.[qb_name] aliases this functionality. The following
+      # pairs are equivalent:
+      # 
+      #   QBFC::Vendor.find(session, :first) <-> session.vendor
+      #   QBFC::Vendor.find(session, "Supply Shop") <-> session.vendor("Supply Shop")
+      #   QBFC::Vendor.find(session, :all) <-> session.vendors.find(:all)
+      # 
+      # Find requires a +session+ (representing a QBFC::Session) and
+      # a +what+ argument. +what+ can be one of:
+      # - <tt>:first</tt> - finds the first record fitting any given conditions.
+      # - <tt>:finds</tt> - finds all records fitting any given conditions.
+      # - An unique identifier, such as a ListID, FullName, RefNumber or TxnID
+      # 
+      # .find can also receive a optional Request object followed 
+      # by an optional options Hash. Valid argument sets are:
+      # 
+      #   QBFC::Vendor.find(session, :first)
+      #   QBFC::Vendor.find(session, :first, request)
+      #   QBFC::Vendor.find(session, :first, request, options)
+      #   QBFC::Vendor.find(session, :first, options)
+      # 
+      # The options hash accepts the following:
+      # - <tt>:owner_id</tt>: One or more OwnerIDs, used in accessing
+      #   custom fields (aka private data extensions).
+      # - <tt>:limit</tt>: The maximum number of records to be returned.
+      # - <tt>:include</tt>: Elements to include (see below for details)
+      # - <tt>:conditions</tt>: A hash of conditions (generally 'Filters' in
+      #   QuickBooks SDK. See below:
+      # 
+      # Additional options are planned, but not really supported in this version.
+      # Passing a Request object is the current recommended way of applying
+      # unsupported conditions (Filters) or other options to the Query Request.
+      # 
+      # ==Include
+      # 
+      # The :include option accepts an Array of elements to include in the
+      # return of the Query. 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.
+      # 
+      #   @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.
+      #     
+      # ==Conditions
+      # 
+      # Conditions are dependent on the particular Request. See the QuickBooks
+      # SDK documentation for applicable filters for each Query Request. Note
+      # that not all Filters are supported.
+      # 
+      # Typically the condition is given as :filter_name => value where
+      # +filter_name+ is the name of the filter less the word 'Filter' (see
+      # examples below).
+      # 
+      # Here are some general rules:
+      # 
+      # [List filters]
+      #   These are filters that end in List. They take an Array of values.
+      #   
+      #     :ref_number_list => ["1001", "1003", "1003a"]
+      #     :txn_id_list => ["123-456"]
+      # 
+      # [Range Filters]
+      #   Filters which take a range of values. These accept any
+      #   object which responds to +first+ and +last+, such as a Range or Array.
+      #   +first+ is used to set the From value, +last+ sets the To value. If a
+      #   scalar value is given (or a single element Array), To is set and From
+      #   is left empty. nil can also be given for either value.
+      # 
+      #     :txn_date_range => ['2008-01', nil]
+      #     :txn_date_range => ['2008-01']
+      #     :txn_date_range => '2008-01'
+      #     
+      #     :ref_number_range => "1001".."1003"
+      #     :ref_number_range => ["1001", "1003"]
+      #   
+      # [Reference Filters]
+      #   Filters which reference another object (belongs to
+      #   filters). These current only accept Name arguments, as a single value
+      #   or an Array.
+      # 
+      #     :account => 'Checking'
+      #     :entity => ['ABC Supplies', 'CompuStuff']
+      # 
+      def find(sess, what, *args)       
+        if what.kind_of?(String) # Single FullName or ListID
+          return find_by_unique_id(sess, what, *args)
+        end
+        
+        # Setup q, options and base_options arguments
+        q, options, base_options = parse_find_args(*args)
+        q ||= create_query(sess)
+        ignore_base_class = options.kind_of?(Hash) ? options.delete(:ignore_base_class) : false
+        
+        q.apply_options(options)
+        
+        # QuickBooks only needs to return one record if .find is
+        # only returning a single record.
+        if what == :first && q.filter_available?
+          q.add_limit(1)
+        end
+        
+        # Send the query so far to base_class_find if this is
+        # a base class to handle special base class functionality.
+        if is_base_class? && !ignore_base_class
+          return base_class_find(sess, what, q, base_options)
+        end
+        
+        # Get response and return an Array, a QBFC::Element-inherited
+        # object, or nil, depending on <tt>what</tt> argument and whether
+        # the query returned any records.
+        list = q.response
+        
+        if list.nil?
+          (what == :all) ? [] : nil
+        elsif what == :all
+          (0..(list.Count - 1)).collect { |i|
+            new(sess, list.GetAt(i))
+          }
+        else
+          new(sess, list.GetAt(0))
+        end
+      end
+      
+      # Base classes can be used to find members of any of their
+      # inherited classes. Since QuickBooks has limited options
+      # for these type of queries (in particular, no custom fields
+      # are returned), an initial query is run which retrieves
+      # only IDs and the class type and then individual subsequent
+      # queries are run for each returned object.
+      def base_class_find(sess, what, q, options)
+        q.IncludeRetElementList.Add(self::ID_NAME)
+        list = q.response
+        
+        if list.nil?
+          (what == :all) ? [] : nil
+        else
+          ary = (0..(list.Count - 1)).collect { |i|
+            element = list.GetAt(i)
+            ret_name = element.ole_methods.detect { |m|
+              m.to_s =~ /(.*)Ret\Z/ && element.send(m.to_s)
+            }.to_s
+            ret_class = QBFC::const_get($1)
+            ret_class.find(sess, element.send(ret_name).send(ret_class::ID_NAME).GetValue, options.dup)
+          }
+          
+          if what == :all
+            ary
+          else
+            ary[0]
+          end
+        end
+      end
+      
+      private :base_class_find, :is_base_class
+
+    end
+    
+    is_base_class
+    
+    # Extends Base#initialize to allow for an Add Request if
+    # .new is called directly (instead of by .find)
+    def initialize(sess, ole_object = nil)
+      super
+      
+      if @ole.nil?
+        add_rq = QBFC::Request.new(sess, "#{qb_name}Add")
+        @ole = QBFC::OLEWrapper.new(add_rq.ole_object)
+        @new_record = true
+        @setter = add_rq
+      end
+    end
+    
+    # Is this a new record, i.e. are we doing an Add Request?
+    def new_record?
+      @new_record ? true : false
+    end
+  
+    # Access information from a custom field.
+    def custom(field_name, owner_id = '0')
+      if @ole.DataExtRetList
+        @ole.data_ext.each do |field|
+          if field.data_ext_name == field_name && field.owner_id == owner_id.to_s
+            return field.data_ext_value
+          end
+        end
+      end
+      
+      return nil
+    end
+    
+    # Save (create or update) this record
+    def save
+      if @setter
+        @setter.submit
+      else
+        raise NotSavableError, "This record cannot be saved (Probably because it does not support Mod Requests)."
+      end
+    end
+    
+  end
+end
+
+# Require subclass files
+%w{ list transaction }.each do |file|
+  require 'qbfc/' + file
+end