jm81-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/spec/integration/add_spec.rb

@@ -0,0 +1,31 @@
+require 'spec_helper'
+
+describe "QBFC::Customer.new" do
+    
+  before(:each) do 
+    @integration = QBFC::Integration.new
+    @sess = @integration.session
+  end
+  
+  after(:each) do 
+    @integration.close
+  end
+  
+  it "should create a new customer" do
+    old_count = @sess.customers.find(:all).length
+
+    c = @sess.customers.new
+    c.name = "Cranky Customer"
+    c.is_active = true
+    c.last_name = "McCustomer"
+    c.save
+    
+    n = @sess.customers.find("Cranky Customer")
+    n.name.should == "Cranky Customer"
+    n.is_active.should be(true)
+    n.last_name.should == "McCustomer"
+    
+    @sess.customers.find(:all).length.should == old_count + 1
+  end
+  
+end

data/spec/integration/base_spec.rb

@@ -0,0 +1,18 @@
+require 'spec_helper'
+
+describe QBFC::Base do
+
+  before(:each) do 
+    @integration = QBFC::Integration::reader
+    @sess = @integration.session
+  end
+  
+  after(:each) do 
+    @integration.close
+  end
+  
+  it "should do nothing" do
+    true.should be_true
+  end
+  
+end

data/spec/integration/belongs_to_spec.rb

@@ -0,0 +1,64 @@
+require 'spec_helper'
+
+# This spec describes "belong to" style relationships,
+# that is where QuickBooks specifies a Ref to another object.
+
+describe "belongs to: " do
+
+  before(:each) do 
+    @integration = QBFC::Integration::reader
+    @sess = @integration.session
+  end
+  
+  after(:each) do 
+    @integration.close
+  end
+  
+  describe "Bob Customer" do
+    before(:each) do
+      @customer = @sess.customers.find("Bob Customer")
+    end
+  
+    it "has terms" do
+      @customer.terms.should be_kind_of(QBFC::Terms)
+      @customer.terms.id.should == @sess.terms.find("Net 30").id
+    end
+    
+    it "should not have a sales rep" do
+      @customer.sales_rep.should be_nil
+    end
+  end
+  
+  describe "Check to ABC Supplies" do
+    before(:each) do
+      @check = @sess.checks.find_by_ref("1000")
+    end
+  
+    it "has a payee" do
+      @check.payee.should be_kind_of(QBFC::Vendor)
+      @check.payee.id.should == @sess.vendors.find("ABC Supplies").id
+    end
+    
+    it "has an account" do
+      @check.account.should be_kind_of(QBFC::Account)
+      @check.account.id.should == @sess.accounts.find("Checking").id
+    end
+  end
+  
+  describe "Invoice to Customer Bob" do
+    before(:each) do
+      @invoice = @sess.invoices.find_by_ref("1")
+    end
+  
+    it "has a template" do
+      @invoice.template.should be_kind_of(QBFC::Template)
+      @invoice.template.id.should == @sess.templates.find("Intuit Service Invoice").id
+    end
+    
+    it "has a Customer" do
+      @invoice.customer.should be_kind_of(QBFC::Customer)
+      @invoice.customer.id.should == @sess.customers.find("Bob Customer").id
+    end
+  end
+  
+end