qbfc 0.3.0

data/lib/qbfc/entities/generated.rb

@@ -0,0 +1,8 @@
+module QBFC
+  # Generated Entity Types (Inherit from List)
+  ENTITY_TYPES = %w{Customer Employee OtherName Vendor}
+  
+  # Generate Entity subclasses
+  # NB: All Entities are Modifiable
+  generate(ENTITY_TYPES, Entity, {Modifiable => ENTITY_TYPES})
+end

data/lib/qbfc/entity.rb

@@ -0,0 +1,11 @@
+module QBFC
+  # Entity objects are Customers, Employees, Vendors and OtherNames
+  class Entity < List
+    is_base_class
+  end
+end
+
+# Require subclass files
+Dir.new(File.dirname(__FILE__) + '/entities').each do |file|
+  require('qbfc/entities/' + File.basename(file)) if File.extname(file) == ".rb"
+end

data/lib/qbfc/info.rb

@@ -0,0 +1,42 @@
+module QBFC
+  # Info objects are those which have only one instance within Quickbooks,
+  # which are: Company, CompanyActivity, Host and Preferences.
+  # 
+  # Access through QBFC for these objects is read-only.
+  # 
+  # QBFC::Info can be accessed via session::company, for example, or
+  # through QBFC::Company::get(session).
+  class Info < Base
+    class << self
+      
+      # Get the Info object for the given session.
+      # session.[qb_name] aliases this functionality.
+      # For example QBFC::Company.get(session) and
+      # session.company are equivalent.
+      # 
+      # It accepts the follow options as a hash:
+      # - <tt>:owner_id</tt>: One or more OwnerIDs, used in accessing
+      #   custom fields (aka private data extensions).
+      def get(sess, *args)
+        # Setup q, options and base_options arguments
+        q, options, base_options = parse_find_args(*args)
+        q ||= create_query(sess)
+        q.apply_options(options)
+        
+        new(sess, q.response)
+      end
+      
+      # This is a convenience alias for +get+.
+      # It exists solely so that I don't have to modify
+      # Session#method_missing.
+      def find(sess, what, *args) #:nodoc:
+        get(sess, *args)
+      end
+    end
+  end
+end
+
+# Require subclass files
+Dir.new(File.dirname(__FILE__) + '/infos').each do |file|
+  require('qbfc/infos/' + File.basename(file)) if File.extname(file) == ".rb"
+end

data/lib/qbfc/infos/generated.rb

@@ -0,0 +1,9 @@
+module QBFC
+
+  # Generated Info types
+  INFO_TYPES = %w{Company CompanyActivity Host Preferences}
+  
+  # Generate List subclasses
+  generate(INFO_TYPES, Info)
+  
+end

data/lib/qbfc/item.rb

@@ -0,0 +1,29 @@
+module QBFC
+  class Item < List
+    is_base_class
+    
+    class << self
+      
+      # Adds a SpecialItem.
+      # 
+      # +item_type+ should be a constent, for example:
+      # 
+      #   Account.add_special(sess, QBFC_CONST::SitFinanceCharge)
+      #   
+      # See SDK docs for SpecialItemAdd for more details.
+      def add_special(sess, item_type)
+        rq = QBFC::Request.new(sess, "SpecialItemAdd")
+        rq.special_item_type = item_type
+        
+        # Insofar as I never actually plan to use this method, just return
+        # response.
+        return rq.response
+      end
+    end
+  end
+end
+
+# Require subclass files
+Dir.new(File.dirname(__FILE__) + '/items').each do |file|
+  require('qbfc/items/' + File.basename(file)) if File.extname(file) == ".rb"
+end

data/lib/qbfc/items/generated.rb

@@ -0,0 +1,11 @@
+module QBFC
+  
+  # Generated Item Types (Inherit from List)
+  ITEM_TYPES = %w{ItemService ItemNonInventory ItemOtherCharge ItemInventory ItemInventoryAssembly ItemFixedAsset
+      ItemSubtotal ItemDiscount ItemPayment ItemSalesTax ItemSalesTaxGroup ItemGroup}
+  
+  # Generate Item subclasses
+  # NB: All Items are Modifiable
+  generate(ITEM_TYPES, Item, {Modifiable => ITEM_TYPES})
+  
+end

data/lib/qbfc/list.rb

@@ -0,0 +1,84 @@
+module QBFC
+  # List objects are those with names, such as Accounts, Entities, and Items.
+  # 
+  # Note on the name: it doesn't make sense since a List is actually a single object,
+  # but it fits with the SDK's naming scheme, and I couldn't think of a better one.
+  class List < Element
+    is_base_class
+    ID_NAME = "ListID"
+    
+    class << self
+      
+      # Find by name (actually, FullName) of List record.
+      # +options+ are the same as those for in +find+.
+      def find_by_name(sess, full_name, options = {})
+        q = create_query(sess)
+        q.query.FullNameList.Add(full_name)
+        find(sess, :first, q, options)
+      end
+      
+      alias_method :find_by_full_name, :find_by_name
+
+      # Find by ListID 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.ListIDList.Add(id)
+        find(sess, :first, q, options)
+      end
+      
+      # Find by either name or id. Tries id first, then name.
+      def find_by_name_or_id(*args)
+        find_by_id(*args) || find_by_name(*args)
+      end
+      
+      alias_method :find_by_unique_id, :find_by_name_or_id
+      
+    end
+    
+    # Alias of ListID for this record. This is a unique within each type of List.
+    def id
+      @ole.list_id
+    end
+    
+    # If an entity has a Name field but not a FullName field,
+    # use Name (which, by implication, is the FullName)
+    def full_name
+      respond_to_ole?("FullName") ?
+        @ole.full_name :
+        @ole.name
+    end
+    
+    # Delete this List record.
+    def delete
+      req = QBFC::Request.new(@sess, "ListDel")
+      req.list_del_type = QBFC_CONST::const_get("Ldt#{qb_name}")
+      req.list_id = id
+      req.submit
+      return true
+    end
+    
+    # Display the Transaction add (for new records) or edit dialog box
+    def display
+      if new_record?
+        req = QBFC::Request.new(@sess, "ListDisplayAdd")
+        req.list_display_add_type = QBFC_CONST::const_get("Ldat#{qb_name}")
+      else
+        req = QBFC::Request.new(@sess, "ListDisplayMod")
+        req.list_display_mod_type = QBFC_CONST::const_get("Ldmt#{qb_name}")
+        req.list_id = id
+      end
+      req.submit
+      return true
+    end
+  end
+end
+
+# Require subclass files
+%w{ entity item terms }.each do |file|
+  require 'qbfc/' + file
+end
+
+Dir.new(File.dirname(__FILE__) + '/lists').each do |file|
+  require('qbfc/lists/' + File.basename(file)) if File.extname(file) == ".rb"
+end

data/lib/qbfc/lists/account.rb

@@ -0,0 +1,24 @@
+module QBFC
+  class Account < List
+    include Modifiable
+    
+    class << self
+      
+      # Adds a SpecialAccount, per SDK documentation:
+      # "An account normally created automatically as needed within the 
+      # QuickBooks UI, or in the SDK via the SpecialAccountAdd request."
+      # 
+      # +account_type+ should be a constent, for example:
+      # 
+      #   Account.add_special(sess, QBFC_CONST::SatAccountsPayable)
+      #   
+      # See SDK docs for SpecialAccountAdd for more details.
+      def add_special(sess, account_type)
+        rq = QBFC::Request.new(sess, "SpecialAccountAdd")
+        rq.special_account_type = account_type
+        
+        new(sess, rq.response)
+      end
+    end
+  end
+end

data/lib/qbfc/lists/generated.rb

@@ -0,0 +1,15 @@
+module QBFC
+
+  # Generated List types that will inherit directly from QBFC::List
+  LIST_TYPES = %w{ BillingRate CustomerMsg CustomerType JobType  PaymentMethod
+      PayrollItemNonWage PayrollItemWage PriceLevel SalesRep SalesTaxCode
+      ShipMethod ToDo Vehicle VendorType}
+  
+  # Generated List types that do accept Mod Requests
+  # (most direct subclasses of List do not)
+  LIST_MOD_TYPES = %w{ PriceLevel SalesRep Vehicle }
+  
+  # Generate List subclasses
+  generate(LIST_TYPES, List, {Modifiable => LIST_MOD_TYPES})
+  
+end

data/lib/qbfc/lists/qb_class.rb

@@ -0,0 +1,25 @@
+module QBFC
+  # QBClass objects represent QuickBooks SDK's <tt>Class</tt> objects.
+  # As naming this Class <tt>Class</tt> would be impractical, it is
+  # instead called QBClass. It is otherwise similar to the other List
+  # classes.
+  # 
+  # From QBFC6 SDK docs:
+  # 
+  # Classes can be used to separate transactions into meaningful categories.
+  # (For example, transactions could be classified according to department,
+  # business location, or type of work.) In QuickBooks, class tracking is
+  # off by default.
+  class QBClass < List
+    class << self
+      
+      # The QuickBooks SDK class is called 'Class'.
+      # Calling this class QBClass avoids making ruby
+      # very angry; the qb_name method ensures that calls
+      # to QBFC use the correct name.
+      def qb_name
+        "Class"
+      end
+    end
+  end
+end

data/lib/qbfc/modifiable.rb

@@ -0,0 +1,31 @@
+module QBFC
+  module Modifiable
+
+    # Extend initialize of including classes to set up a Mod Request
+    # if the record is existing.
+    def initialize(*args)
+      super
+
+      unless @new_record
+        setup_mod_request
+      end
+    end
+
+    # Setup a Mod Request for this object and attach it
+    # to the ole object.
+    def setup_mod_request
+      @setter = QBFC::Request.new(@sess, "#{self.qb_name}Mod")
+        
+      if self.kind_of?(List)
+        @setter.list_id = id
+      else # Transaction
+        @setter.txn_id = id
+      end
+
+      @setter.edit_sequence = @ole.edit_sequence
+      @ole.setter = @setter.ole_object    
+    end
+    
+    private :setup_mod_request
+  end
+end

data/lib/qbfc/ole_wrapper.rb

@@ -0,0 +1,201 @@
+module QBFC
+
+  # OLEWrapper is more or less the centerpiece of RubyQBFC. (Nearly) every
+  # WIN32OLE object accessed within the library is wrapped in this class, which
+  # is responsible for allowing Ruby-esque methods in place of the OLE methods.
+  # 
+  #   customer.full_name # => Customer.FullName.GetValue
+  #   customer.full_name=(val) # => Customer.FullName.SetValue(val)
+  #   
+  # It also creates referenced objects when accessed.
+  # 
+  #   check.payee # => Entity.find_by_list_id(check.PayeeEntityRef.ListID.GetValue)
+  #   check.account # => Account.find_by_list_id(check.AccountRef.ListID.GetValue)
+  # 
+  # When an OLE method called via OLEWrapper returns a WIN32OLE object, a new
+  # OLEWrapper object is created with the WIN32OLE object and returned.
+  # 
+  # Now, the fun (and +really+ hackish) part. In many cases within the QBFC
+  # library, the wrapper is actually wrapping two WIN32OLE objects, the additional
+  # being a 'setter' object. This object is used when creating a ModRequest. In
+  # such cases, a method ending in '=' is always sent to both the primary and the
+  # setter objects. To facilitate this, traversing child ole_objects also
+  # traverses the child setter objects.
+  class OLEWrapper
+    attr_reader :ole_object
+    attr_accessor :setter
+  
+    # Set up wrapped object, by passing a WIN32OLE object
+    # (or a String with the name of a WIN32OLE server)
+    # Optionally, pass a +setter+ WIN32OLE object.
+    def initialize(ole_object, setter = nil)
+      ole_object = WIN32OLE.new(ole_object) if ole_object.kind_of?(String)
+      @ole_object = ole_object
+      @setter = setter
+    end
+    
+    # Return Array of ole_methods for request WIN32OLE object.
+    def ole_methods
+      @ole_object.ole_methods
+    end
+    
+    # Does this OLE object respond to the given ole method?
+    def respond_to_ole?(symbol)
+      detect_ole_method?(@ole_object, symbol)
+    end
+    
+    # Use [idx] syntax for objects that respond to <tt>GetAt(idx)</tt>
+    def [](idx)
+      if idx.kind_of? Integer
+        self.class.new(@ole_object.GetAt(idx))
+      else
+        @ole_object[idx]
+      end
+    end
+  
+    # Called by #method_missing of other classes. Initiates the OLEWrapper#method_missing
+    # method which is responsible for the various method conversions.
+    # +sess+ argument is a QBFC::Session.
+    def qbfc_method_missing(sess, symbol, *params)
+      @sess = sess
+      method_missing(symbol, *params)
+    end
+  
+    # If the method name is capitalized, send directly to ole_object; if
+    # a WIN32OLE is returned, wrap it.
+    # If the method name starts with a lower-case letter, send to +lower_method_missing+
+    # for conversion.
+    def method_missing(symbol, *params) #:nodoc:
+      if (('a'..'z') === symbol.to_s[0].chr)
+        lower_case_method_missing(symbol, *params)
+      else
+        resp = @ole_object.send(symbol, *params)
+        return( resp.kind_of?(WIN32OLE) ?
+          self.class.new(resp) :
+          resp )
+      end
+    end
+    
+    private
+
+    # Decide which conversion method needs to handle this method and send.
+    def lower_case_method_missing(symbol, *params)
+      if '=' == symbol.to_s[-1].chr
+        set_value(symbol.to_s[0..-2], *params)
+      elsif symbol.to_s =~ /\A(\w+)_(full_name|id)\Z/ && ref_name($1)
+        get_ref_name_or_id(ref_name($1), $2)
+      elsif detect_ole_method?(@ole_object, ole_sym(symbol))
+        get_value(symbol, *params)
+      elsif detect_ole_method?(@ole_object, (s = symbol.to_s.singularize.camelize + "RetList"))
+        setup_array(s)
+      elsif detect_ole_method?(@ole_object, (s = "OR" + symbol.to_s.singularize.camelize + "RetList"))
+        setup_array(s, true)
+      elsif detect_ole_method?(@ole_object, (s = symbol.to_s.singularize.camelize + "List"))
+        setup_array(s)
+      elsif detect_ole_method?(@ole_object, (s = "OR" + symbol.to_s.singularize.camelize + "List"))
+        setup_array(s, true)
+      elsif ref_name(symbol)
+        create_ref(ref_name(symbol), *params)
+      elsif detect_ole_method?(@ole_object, symbol)
+        # Occassionally, QBFC uses a lower case method
+        @ole_object.send(symbol, *params)
+      else
+        raise NoMethodError, symbol.to_s
+      end 
+    end
+    
+    # Sets a value by calling OLEMethodName.SetValue(*params)
+    def set_value(ole_method_name, *params)
+      ole_method_name = ole_sym(ole_method_name)
+      obj = @ole_object.send(ole_method_name)
+
+      if detect_ole_method?(obj, "SetValue")
+        params[0] = params[0].strftime("%Y-%m-%d") if params[0].kind_of?(Date)
+        obj.SetValue(*params)
+        if @setter && detect_ole_method?(@setter, ole_method_name)
+          @setter.send(ole_method_name).SetValue(*params)
+        end
+      else
+        raise SetValueMissing, "SetValue is expected, but missing, for #{ole_method_name}"
+      end
+    end
+    
+    # Gets a value by calling OLEMethodName.GetValue
+    def get_value(ole_method_name, *params)
+      ole_method_name = ole_sym(ole_method_name)
+      obj = @ole_object.send(ole_method_name, *params)
+      if detect_ole_method?(obj, "GetValue")
+        if ole_method_name =~ /date/i || ole_method_name.to_s =~ /time/i 
+          Time.parse(obj.GetValue)
+        else
+          obj.GetValue
+        end
+      else
+        if obj.kind_of?(WIN32OLE)
+          if @setter && detect_ole_method?(@setter, ole_method_name)
+            self.class.new(obj, @setter.send(ole_method_name, *params))
+          else
+            self.class.new(obj)
+          end
+        else
+          obj
+        end
+      end
+    end
+
+    # Sets up an array to return if the return of OLEMethodName appears
+    # to be a list structure.
+    # <tt>is_OR_list</tt> indicates the list is an OR*RetList which
+    # is structured differently.
+    def setup_array(ole_method_name, is_OR_list = false)
+      list = @ole_object.send(ole_method_name)
+      ary = []
+      0.upto(list.Count - 1) do |i|
+        if is_OR_list
+          ary << self.class.new(list.GetAt(i)).send(ole_method_name.match(/\AOR(.*)List\Z/)[1])
+        else
+          ary << self.class.new(list.GetAt(i))
+        end
+      end
+      return ary
+    end
+    
+    def ref_name(symbol)
+      if detect_ole_method?(@ole_object, symbol.to_s.camelize + "Ref")
+        symbol.to_s.camelize + "Ref"
+      elsif detect_ole_method?(@ole_object, symbol.to_s.camelize + "EntityRef")
+        symbol.to_s.camelize + "EntityRef"
+      else
+        nil
+      end
+    end
+    
+    # Creates a QBFC::Base inherited object if the return of
+    # OLEMethodName appears to be a reference to such an object.
+    def create_ref(ref_ole_name, *options)
+      ref_ole_object = @ole_object.send(ref_ole_name)
+      if ref_ole_object
+        ref_ole_name =~ /EntityRef/ ?
+          QBFC::Entity.find_by_id(@sess, ref_ole_object.ListID.GetValue(), *options) :
+          QBFC::const_get(ref_ole_name.gsub(/Ref/,"")).find_by_id(@sess, ref_ole_object.ListID.GetValue(), *options)
+      else
+        return nil
+      end
+    end
+    
+    def get_ref_name_or_id(symbol, field)
+      field = (field == "id" ? "ListID" : "FullName")
+      @ole_object.send(symbol).send(field).GetValue()
+    end
+    
+    # Check if the obj has an ole_method matching the symbol.
+    def detect_ole_method?(obj, symbol)
+      obj && obj.respond_to?(:ole_methods) && obj.ole_methods.detect{|m| m.to_s == symbol.to_s}
+    end
+    
+    # Helper method to convert 'Ruby-ish' method name to WIN32OLE method name
+    def ole_sym(symbol)
+      symbol.to_s.camelize.gsub(/Id/, 'ID')
+    end
+  end
+end