qbfc 0.3.0

data/lib/qbfc/session.rb

@@ -0,0 +1,147 @@
+module QBFC
+  class QuickbooksClosedError < RuntimeError #:nodoc:
+  end
+  class SetValueMissing < RuntimeError#:nodoc:
+  end
+  class QBXMLVersionError < RuntimeError#:nodoc:
+  end
+  class UnknownRequestError < RuntimeError#:nodoc:
+  end
+  class BaseClassNewError < RuntimeError#:nodoc:
+  end
+  class NotSavableError < RuntimeError#:nodoc:
+  end
+
+  # Encapsulates a QBFC session.
+  # 
+  #   QBFC::Session.open(:app_name => 'Test Application') do |qb|
+  #     qb.customers.find(:all).each do |customer|
+  #       puts customer.full_name
+  #     end
+  #   end
+  # 
+  #   qb = QBFC::Session.new(:app_name => 'Test Application')
+  #   qb.customers.find(:all).each do |customer|
+  #     puts customer.full_name
+  #   end
+  #   qb.close
+  # 
+  # A QBFC::Session abstracts the ole_methods so that more conventional Ruby method names are used,
+  # e.g. <tt>full_name</tt> instead of <tt>FullName.GetValue()</tt>.
+  # 
+  # This also allows a shortcut for setting up Quickbooks objects:
+  # 
+  # - session.customers.find(:all) instead of QBFC::Customer.find(session, :all)
+  # - session.customer('CustomerFullName') instead of QBFC::Customer.find(session, 'CustomerFullName')
+  # - session.customer instead of QBFC::Customer.find(session, :first)
+  class Session
+    class << self
+      
+      # Open a QBFC session. Takes options as a hash, and an optional block. Options are:
+      # 
+      # - +app_name+: Name that the application sends to Quickbooks (used for allowing/denying access)
+      #   (defaults to 'Ruby QBFC Application'
+      # - +app_id+: Per the Quickbooks SDK (QBFC Language Reference):
+      #   'Normally not assigned. Use an empty string for appID.' An empty string is passed by default.
+      # - +conn_type+: QBFC_CONST::CtUnknown, CtLocalQBD, CtRemoteQBD, CtLocalQBDLaunchUI, or CtRemoteQBOE.
+      #   Default is QBFC_CONST::CtLocalQBD (1)
+      # - +filename+: The full path to the Quickbooks file; leave blank to connect to the currently
+      #   open company file. Default is an empty string (Quickbooks should be running).
+      # - +open_mode+: The desired access mode. It can be one of three values:
+      #     - QBFC_CONST::OmSingleUser (specifies single-user mode)
+      #     - QBFC_CONST::OmMultiUser (specifies multi-user mode)
+      #     - QBFC_CONST::OmDontCare (accept whatever mode is currently in effect, or single-user mode if no other mode is in effect)
+      #   Default is QBFC_CONST::OmDontCare
+      #   
+      # If given a block, it yields the Session object and closes the Session and Connection
+      # when the block closes.
+      # 
+      # Otherwise, it returns the new Session object.
+  
+      def open(*options, &block)
+        qb = new(*options)
+        if block_given?
+          begin
+            yield qb
+          ensure
+            qb.close
+          end
+        else
+          qb
+        end
+      end
+      
+    end
+    
+    # See Session.open for initialization options.
+    def initialize(options = {})
+      ole_object = WIN32OLE.new("QBFC6.QBSessionManager")
+  
+      ole_object.OpenConnection2(options[:app_id].to_s,
+                                  (options[:app_name] || "Ruby QBFC Application"),
+                                  (options[:conn_type] || QBFC_CONST::CtLocalQBD))
+  
+      begin
+        ole_object.BeginSession(options[:filename].to_s,
+                                 (options[:open_mode] || QBFC_CONST::OmDontCare))
+      rescue WIN32OLERuntimeError
+        ole_object.CloseConnection
+        ole_object = nil
+        raise(QBFC::QuickbooksClosedError,
+            "BeginSession failed: Quickbooks must be open or a valid filename specified.\n\n#{$!}")
+      end
+      
+      @ole_object = QBFC::OLEWrapper.new(ole_object)
+    end
+    
+    # Close the session with Quickbooks. If this is ommitted, Quickbooks will not close.
+    # Using a block with Session.open ensures the session is closed.
+    def close
+      @ole_object.EndSession
+      @ole_object.CloseConnection
+      @ole_object = nil
+    end
+    
+    # Generate a report with the given +name+ and +args+.
+    # (See QBFC::Report.get for details).
+    def report(name, *args)
+      Report.get(self, name, *args)
+    end
+    
+    # The classes method allows using <tt>session.classes.find</tt> instead of
+    # <tt>session.q_b_classes.find</tt>, for finds on QBClass.
+    def classes
+      QBFC::QBCollection.new(self, :QBClass)
+    end
+    
+    # Responsible for the conversion of ole_method name to more convential Ruby method names.
+    # This specifies the methods for setting up an Entity, such as a Customer, directly, which is
+    # not included in OLEWrapper (setting up entities that are children of another entity is).
+    # Send other missing methods on to OLE Wrapper
+    def method_missing(symbol, *params) #:nodoc:
+      if (('a'..'z') === symbol.to_s[0].chr && symbol.to_s[-1].chr != '=')
+        camelized_method = symbol.to_s.camelize.to_sym
+        if camelized_method.to_s =~ /Terms\Z/
+          single_camelized_method = camelized_method
+        else
+          single_camelized_method = symbol.to_s.singularize.camelize.to_sym 
+        end
+        if QBFC.const_defined?(camelized_method) && camelized_method.to_s !~ /Terms\Z/
+          if params[0]
+            return QBFC::const_get(camelized_method).find_by_unique_id(self, params[0])
+          else
+            return QBFC::const_get(camelized_method).find(self, :first)
+          end
+        elsif QBFC.const_defined?(single_camelized_method)
+          return  QBFC::QBCollection.new(self, single_camelized_method)
+        end
+      end
+      
+      # Don't want to pass an OLEWrapper to a WIN32OLE method.
+      params = params.collect{ |p| p.respond_to?(:ole_object) ? p.ole_object : p }
+      
+      @ole_object.qbfc_method_missing(self, symbol, *params)
+    end
+    
+  end
+end

data/lib/qbfc/terms.rb

@@ -0,0 +1,10 @@
+module QBFC
+  class Terms < List
+    is_base_class
+  end
+end
+
+# Require subclass files
+Dir.new(File.dirname(__FILE__) + '/terms').each do |file|
+  require('qbfc/terms/' + File.basename(file)) if File.extname(file) == ".rb"
+end

data/lib/qbfc/terms/generated.rb

@@ -0,0 +1,10 @@
+module QBFC
+  
+  # Generated Terms Types (Inherit from List)
+  TERMS_TYPES = %w{DateDrivenTerms StandardTerms}
+  
+  # Generate Terms subclasses
+  # NB: All Terms are Modifiable
+  generate(TERMS_TYPES, Terms)
+  
+end

data/lib/qbfc/transaction.rb

@@ -0,0 +1,110 @@
+require 'qbfc/voidable'
+
+module QBFC
+  class Transaction < Element
+    is_base_class
+    ID_NAME = "TxnID"
+    
+    class << self
+      
+      # Find by Reference Number of the Transaction record.
+      # +options+ are the same as those for in +find+.
+      def find_by_ref(sess, ref, options = {})
+        q = create_query(sess)
+        q.query.RefNumberList.Add(ref)
+        find(sess, :first, q, options)
+      end
+      
+      # Find by TxnID of List record.
+      # +options+ are the same as those for in +find+.      
+      def find_by_id(sess, id, options = {})
+        q = create_query(sess)
+        q.query.TxnIDList.Add(id)
+        find(sess, :first, q, options)
+      end
+      
+      # Find by either ref or id. Tries id first, then ref.
+      def find_by_ref_or_id(*args)
+        find_by_id(*args) || find_by_ref(*args)
+      end
+      
+      alias_method :find_by_unique_id, :find_by_ref_or_id
+      
+      def base_class_find(sess, what, q, options)
+        q.IncludeRetElementList.Add(self::ID_NAME)
+        q.IncludeRetElementList.Add('TxnType')
+        list = q.response
+        
+        if list.nil?
+          (what == :all) ? [] : nil
+        else
+          ary = (0..(list.Count - 1)).collect { |i|
+            element = list.GetAt(i)
+            ret_class_name = element.TxnType.GetAsString
+            if QBFC::const_defined?(ret_class_name)
+              ret_class = QBFC::const_get(ret_class_name)
+              ret_class.find(sess, element.send(ret_class::ID_NAME).GetValue, options.dup)
+            else
+              find(sess, element.send(Transaction::ID_NAME).GetValue, options.dup.merge(:ignore_base_class => true))
+            end
+          }
+          
+          if what == :all
+            ary
+          else
+            ary[0]
+          end
+        end
+      end
+      
+    end
+    
+    # Alias of TxnID for this record.
+    def id
+      @ole.txn_id
+    end
+    
+    # Delete this Transaction
+    def delete
+      req = QBFC::Request.new(@sess, "TxnDel")
+      req.txn_del_type = QBFC_CONST::const_get("Tdt#{qb_name}")
+      req.txn_id = id
+      req.submit
+      return true
+    end
+    
+    # Change cleared status of transaction
+    # status can be one of:
+    # - QBFC::CsCleared (or true)
+    # - QBFC::CsNotCleared (or false)
+    # - QBFC::CsPending
+    def cleared_status=(status)
+      req = QBFC::Request.new(@sess, "ClearedStatusMod")
+      req.txn_id = id
+      status = QBFC_CONST::CsCleared if status === true
+      status = QBFC_CONST::CsNotCleared if status === false
+      req.cleared_status = status
+      req.submit
+      return status
+    end
+    
+    # Display the Transaction add (for new records) or edit dialog box
+    def display
+      if new_record?
+        req = QBFC::Request.new(@sess, "TxnDisplayAdd")
+        req.txn_display_add_type = QBFC_CONST::const_get("Tdat#{qb_name}")
+      else
+        req = QBFC::Request.new(@sess, "TxnDisplayMod")
+        req.txn_display_mod_type = QBFC_CONST::const_get("Tdmt#{qb_name}")
+        req.txn_id = id
+      end
+      req.submit
+      return true
+    end
+  end
+end
+
+# Require subclass files
+Dir.new(File.dirname(__FILE__) + '/transactions').each do |file|
+  require('qbfc/transactions/' + File.basename(file)) if File.extname(file) == ".rb"
+end

data/lib/qbfc/transactions/generated.rb

@@ -0,0 +1,25 @@
+module QBFC
+
+  # Generated Transaction types
+  TXN_TYPES = %w{ARRefundCreditCard Bill BillPaymentCheck BillPaymentCreditCard
+      BuildAssembly Charge Check CreditCardCharge CreditCardCredit CreditMemo
+      Deposit Estimate InventoryAdjustment Invoice ItemReceipt JournalEntry
+      PurchaseOrder ReceivePayment SalesOrder SalesReceipt SalesTaxPaymentCheck 
+      TimeTracking VehicleMileage VendorCredit}
+
+  # Generated Transaction types that support TxnVoid Request
+  TXN_VOIDABLE_TYPES = %w{ARRefundCreditCard Bill BillPaymentCheck
+      BillPaymentCreditCard Charge Check CreditCardCharge CreditCardCredit
+      CreditMemo Deposit InventoryAdjustment Invoice ItemReceipt JournalEntry
+      SalesReceipt VendorCredit}
+  
+  # Generated Transaction types that don't support Mod Requests
+  TXN_NO_MOD_TYPES = %w{ARRefundCreditCard BillPaymentCreditCard Deposit
+    InventoryAdjustment VehicleMileage VendorCredit }
+  
+  # Generate Transaction subclasses
+  generate(TXN_TYPES, Transaction,
+    { Modifiable => (TXN_TYPES - TXN_NO_MOD_TYPES),
+      Voidable => TXN_VOIDABLE_TYPES })
+  
+end

data/lib/qbfc/voidable.rb

@@ -0,0 +1,11 @@
+module QBFC
+  module Voidable
+    def void
+      req = QBFC::Request.new(@sess, "TxnVoid")
+      req.txn_void_type = QBFC_CONST::const_get("Tvt#{qb_name}")
+      req.txn_id = id
+      req.submit
+      return true
+    end
+  end
+end

data/qbfc.gemspec

@@ -0,0 +1,166 @@
+# Generated by jeweler
+# DO NOT EDIT THIS FILE
+# Instead, edit Jeweler::Tasks in Rakefile, and run `rake gemspec`
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{qbfc}
+  s.version = "0.3.0"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Jared Morgan"]
+  s.date = %q{2009-10-11}
+  s.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.}
+  s.email = %q{jmorgan@morgancreative.net}
+  s.extra_rdoc_files = [
+    "README.rdoc"
+  ]
+  s.files = [
+    ".gitignore",
+     "MIT-LICENSE",
+     "README.rdoc",
+     "Rakefile",
+     "VERSION",
+     "lib/qbfc.rb",
+     "lib/qbfc/base.rb",
+     "lib/qbfc/element.rb",
+     "lib/qbfc/entities/generated.rb",
+     "lib/qbfc/entity.rb",
+     "lib/qbfc/info.rb",
+     "lib/qbfc/infos/generated.rb",
+     "lib/qbfc/item.rb",
+     "lib/qbfc/items/generated.rb",
+     "lib/qbfc/list.rb",
+     "lib/qbfc/lists/account.rb",
+     "lib/qbfc/lists/generated.rb",
+     "lib/qbfc/lists/qb_class.rb",
+     "lib/qbfc/modifiable.rb",
+     "lib/qbfc/ole_wrapper.rb",
+     "lib/qbfc/qb_collection.rb",
+     "lib/qbfc/qb_types.rb",
+     "lib/qbfc/qbfc_const.rb",
+     "lib/qbfc/report.rb",
+     "lib/qbfc/reports/aging.rb",
+     "lib/qbfc/reports/budget_summary.rb",
+     "lib/qbfc/reports/custom_detail.rb",
+     "lib/qbfc/reports/custom_summary.rb",
+     "lib/qbfc/reports/general_detail.rb",
+     "lib/qbfc/reports/general_summary.rb",
+     "lib/qbfc/reports/job.rb",
+     "lib/qbfc/reports/payroll_detail.rb",
+     "lib/qbfc/reports/payroll_summary.rb",
+     "lib/qbfc/reports/rows.rb",
+     "lib/qbfc/reports/time.rb",
+     "lib/qbfc/request.rb",
+     "lib/qbfc/session.rb",
+     "lib/qbfc/terms.rb",
+     "lib/qbfc/terms/generated.rb",
+     "lib/qbfc/transaction.rb",
+     "lib/qbfc/transactions/generated.rb",
+     "lib/qbfc/voidable.rb",
+     "qbfc.gemspec",
+     "spec/fixtures/test.lgb",
+     "spec/fixtures/test.qbw",
+     "spec/fixtures/test.qbw.TLG",
+     "spec/integration/add_spec.rb",
+     "spec/integration/base_spec.rb",
+     "spec/integration/belongs_to_spec.rb",
+     "spec/integration/company_spec.rb",
+     "spec/integration/conditions_spec.rb",
+     "spec/integration/customer_spec.rb",
+     "spec/integration/element_finders_spec.rb",
+     "spec/integration/quick_test.rb",
+     "spec/integration/request_options_spec.rb",
+     "spec/rcov.opts",
+     "spec/spec.opts",
+     "spec/spec_helper.rb",
+     "spec/unit/base_spec.rb",
+     "spec/unit/element_finder_spec.rb",
+     "spec/unit/element_spec.rb",
+     "spec/unit/entities/generated_spec.rb",
+     "spec/unit/entity_spec.rb",
+     "spec/unit/info/generated_spec.rb",
+     "spec/unit/info_spec.rb",
+     "spec/unit/item_spec.rb",
+     "spec/unit/items/generated_spec.rb",
+     "spec/unit/list_finders_spec.rb",
+     "spec/unit/list_spec.rb",
+     "spec/unit/lists/account_spec.rb",
+     "spec/unit/lists/generated_spec.rb",
+     "spec/unit/lists/qb_class_spec.rb",
+     "spec/unit/modifiable_spec.rb",
+     "spec/unit/ole_wrapper_spec.rb",
+     "spec/unit/qb_collection_spec.rb",
+     "spec/unit/qbfc_const_spec.rb",
+     "spec/unit/qbfc_spec.rb",
+     "spec/unit/report_spec.rb",
+     "spec/unit/request_query_survey.txt",
+     "spec/unit/request_spec.rb",
+     "spec/unit/session_spec.rb",
+     "spec/unit/terms/generated_spec.rb",
+     "spec/unit/terms_spec.rb",
+     "spec/unit/transaction_finders_spec.rb",
+     "spec/unit/transaction_spec.rb",
+     "spec/unit/transactions/generated_spec.rb",
+     "spec/unit/voidable_spec.rb",
+     "tasks/qbfc_tasks.rake"
+  ]
+  s.homepage = %q{http://rubyforge.org/projects/qbfc/}
+  s.rdoc_options = ["--charset=UTF-8"]
+  s.require_paths = ["lib"]
+  s.rubyforge_project = %q{qbfc}
+  s.rubygems_version = %q{1.3.5}
+  s.summary = %q{A wrapper around the QBFC COM object of the Quickbooks SDK}
+  s.test_files = [
+    "spec/integration/add_spec.rb",
+     "spec/integration/base_spec.rb",
+     "spec/integration/belongs_to_spec.rb",
+     "spec/integration/company_spec.rb",
+     "spec/integration/conditions_spec.rb",
+     "spec/integration/customer_spec.rb",
+     "spec/integration/element_finders_spec.rb",
+     "spec/integration/quick_test.rb",
+     "spec/integration/request_options_spec.rb",
+     "spec/spec_helper.rb",
+     "spec/unit/transactions/generated_spec.rb",
+     "spec/unit/transaction_finders_spec.rb",
+     "spec/unit/transaction_spec.rb",
+     "spec/unit/voidable_spec.rb",
+     "spec/unit/base_spec.rb",
+     "spec/unit/element_finder_spec.rb",
+     "spec/unit/element_spec.rb",
+     "spec/unit/entities/generated_spec.rb",
+     "spec/unit/entity_spec.rb",
+     "spec/unit/info/generated_spec.rb",
+     "spec/unit/info_spec.rb",
+     "spec/unit/items/generated_spec.rb",
+     "spec/unit/item_spec.rb",
+     "spec/unit/lists/account_spec.rb",
+     "spec/unit/lists/generated_spec.rb",
+     "spec/unit/lists/qb_class_spec.rb",
+     "spec/unit/list_finders_spec.rb",
+     "spec/unit/list_spec.rb",
+     "spec/unit/modifiable_spec.rb",
+     "spec/unit/ole_wrapper_spec.rb",
+     "spec/unit/qbfc_const_spec.rb",
+     "spec/unit/qbfc_spec.rb",
+     "spec/unit/qb_collection_spec.rb",
+     "spec/unit/report_spec.rb",
+     "spec/unit/request_spec.rb",
+     "spec/unit/session_spec.rb",
+     "spec/unit/terms/generated_spec.rb",
+     "spec/unit/terms_spec.rb"
+  ]
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
+    else
+    end
+  else
+  end
+end