quickbooks 0.0.3 → 0.0.5

data/lib/quickbooks/connection.rb

@@ -42,7 +42,6 @@ module Quickbooks
       @quickbooks = Ole.new('QBXMLRP2.RequestProcessor', 'QBXMLRP2 1.0 Type Library')
       @connection_type = @quickbooks.get_variable(connection_type)
       @connection_mode = @quickbooks.get_variable('qbFileOpen'+connection_mode)
-      connection # Just to make it fail now instead of later if it can't connect properly.
     end
 
     # Returns true if there is an open connection to Quickbooks, false if not. Use session? to determine an open session.
@@ -57,7 +56,7 @@ module Quickbooks
 
     # Sends a request to Quickbooks. This request should be a valid QBXML request. Use Quickbooks::Qbxml::Request to generate valid requests.
     def send_xml(xml)
-      connection.ProcessRequest(session, xml)
+      @quickbooks.ProcessRequest(session, xml)
     rescue => e
       warn "ERROR processing request:\n#{xml}"
       raise # Reraises the original error, only this way we got the xml output
@@ -95,7 +94,7 @@ module Quickbooks
     # Close the connection to Quickbooks. Automatically ends the session, if there is one.
     def close
       end_session
-      if connected? && connection.CloseConnection(@session)
+      if connected? && connection.CloseConnection
         @connected = false
         @connection = nil
         Quickbooks::Connection.connections = Quickbooks::Connection.connections - [self]

data/lib/quickbooks/model.rb

@@ -0,0 +1,176 @@
+require 'quickbooks/ruby_magic'
+module Quickbooks
+  CAMELIZE_EXCEPTIONS = {'list_id' => 'ListID', 'txn_id' => 'TxnID', 'owner_id' => 'OwnerID'}
+  # These were all created from the info in qbxmlops70.xml, found in the docs in the QBSDK package.
+  class Model
+    class << self
+
+      def inherited(klass)
+        def klass.valid_filters
+          superclass.valid_filters + (@valid_filters ||= [])
+        end
+        def klass.filter_aliases
+          superclass.filter_aliases.merge(@filter_aliases ||= {})
+        end
+        klass.instance_variable_set('@object_properties', {})
+      end
+      
+      def valid_filters=(v)
+        @valid_filters = v.stringify_values!
+      end
+      def valid_filters
+        @valid_filters ||= []
+      end
+      def filter_aliases=(v)
+        @filter_aliases = v.stringify_keys!.stringify_values!
+      end
+      def filter_aliases
+        @filter_aliases ||= {}
+      end
+      def camelized_valid_filters
+        valid_filters.camelize_values(Quickbooks::CAMELIZE_EXCEPTIONS)
+      end
+      
+      # Register multiple read/writable properties at once. For example:
+      #   read_write :first_name, :last_name, :phone, :alt_phone
+      # For reference attributes (like parent_ref), use ParentRef - a class constant for that object.
+      # _read_write_ will set the property setter and accessor accordingly.
+      def read_write(*args)
+        if args.blank?
+          @read_write || (@read_write = [])
+        else
+          args.each do |prop|
+            if prop.is_a?(Symbol)
+              read_write << prop
+              attr_accessor prop
+            else
+              @object_properties[prop.class_leaf_name.underscore.to_sym] = prop
+              read_write << prop.class_leaf_name.underscore.to_sym
+              class_eval "def #{prop.class_leaf_name.underscore}=(v); @#{prop.class_leaf_name.underscore} = #{prop.name}.new(v); end
+                def #{prop.class_leaf_name.underscore}; @#{prop.class_leaf_name.underscore}; end"
+            end
+          end
+        end
+      end
+
+      # Read-only attributes: These are attributes, but not modifiable in Quickbooks
+      def read_only(*args)
+        if args.blank?
+          @read_only || (@read_only = [])
+        else
+          args.each do |prop|
+            if prop.is_a?(Symbol)
+              read_only << prop
+              attr_accessor prop
+            else
+              @object_properties[prop.class_leaf_name.underscore.to_sym] = prop
+              read_only << prop.class_leaf_name.underscore.to_sym
+              class_eval "def #{prop.class_leaf_name.underscore}=(v); @#{prop.class_leaf_name.underscore} = #{prop.name}.new(v); end
+                def #{prop.class_leaf_name.underscore}; @#{prop.class_leaf_name.underscore}; end"
+            end
+          end
+        end
+      end
+
+      def properties
+        read_only + read_write
+      end
+    end
+
+    self.valid_filters = [:max_returned]
+
+    # The default for all subclasses is simply to apply the attributes given, and mark the object as a new_record?
+    def initialize(args={})
+      self.attributes = args
+    end
+
+    # Returns a hash that represents all this object's attributes.
+    def attributes(include_read_only=false)
+      attrs = {}
+      (include_read_only ? self.class.read_only + self.class.read_write : self.class.read_write).each do |column|
+        attrs[column.to_s] = instance_variable_get('@' + column.to_s)
+      end
+      attrs
+    end
+    # Updates all attributes included in _attrs_ to the values given. The object will now be dirty?.
+    def attributes=(attrs)
+      raise ArgumentError, "attributes can only be set to a hash of attributes" unless attrs.is_a?(Hash)
+      attrs.each do |key,value|
+        if self.respond_to?(key.to_s.underscore+'=')
+          self.send(key.to_s.underscore+'=', value)
+        end
+      end
+    end
+
+    # Keeps track of the original values the object had when it was instantiated from a quickbooks response. dirty? and dirty_attributes compare the current values with these ones.
+    def original_values
+      @original_values || (@original_values = {})
+    end
+
+    # Returns true if any attributes have changed since the object was last loaded or updated from Quickbooks.
+    def dirty?
+      # Concept: For each column that the current model includes, has the value been changed?
+      self.class.read_write.any? do |column|
+        self.instance_variable_get('@' + column.to_s) != original_values[column.to_s]
+      end
+    end
+
+    # Returns a hash of the attributes and their (new) values that have been changed since the object was last loaded or updated from Quickbooks.
+    # If you send in some attributes, it will compare to those given instead of original_attributes.
+    def dirty_attributes(compare={})
+      compare = original_values if compare.blank?
+      pairs = {}
+      self.class.read_write.each do |column|
+        value = instance_variable_get('@' + column.to_s)
+        if value != compare[column.to_s]
+          pairs[column.to_s] = value
+        end
+      end
+      pairs
+    end
+
+    def to_dirty_hash
+      hsh = {}
+      self.dirty_attributes.each do |key,value|
+        if value.is_a?(Quickbooks::Model)
+          h = value.to_dirty_hash
+          hsh[key] = h unless h.blank?
+        else
+          hsh[key] = value
+        end
+      end
+      hsh.order!(self.class.read_write.stringify_values)
+      hsh
+    end
+
+    def to_hash(include_read_only=false)
+      hsh = {}
+      self.attributes(include_read_only).each do |key,value|
+        if value.is_a?(Quickbooks::Model)
+          h = value.to_hash(include_read_only)
+          hsh[key] = h unless h.blank?
+        else
+          hsh[key] = value
+        end
+      end
+      hsh.order!((include_read_only ? self.class.read_only + self.class.read_write : self.class.read_write).stringify_values)
+      hsh
+    end
+
+    def ==(other)
+      return false unless other.is_a?(self.class)
+      !self.class.read_write.any? do |column|
+        self.instance_variable_get('@' + column.to_s) != other.instance_variable_get('@' + column.to_s)
+      end
+    end
+
+    def ===(other)
+      # other could be a hash
+      if other.is_a?(Hash)
+        self == self.class.new(other)
+      else
+        self == other
+      end
+    end
+  end
+end

data/lib/quickbooks/models/common/address.rb

@@ -0,0 +1,14 @@
+module Quickbooks
+  class Address < Model
+    def self.inherited(klass)
+      super
+      klass.read_write :addr1, :addr2, :addr3, :addr4, :addr5, :city, :state, :postal_code, :country, :note
+    end
+  end
+
+  class BillAddress < Address
+  end
+
+  class ShipAddress < Address
+  end
+end

data/lib/quickbooks/models/common/all_refs.rb

@@ -0,0 +1,36 @@
+module Quickbooks
+  class Ref < Model
+    def self.inherited(klass)
+      klass.read_only :list_id, :full_name
+    end
+
+    # Put in here the connector code for 'association' calls
+  end
+  
+  class ParentRef < Ref
+  end
+  
+  class CustomerTypeRef < Ref
+  end
+  
+  class TermsRef < Ref
+  end
+  
+  class SalesRepRef < Ref
+  end
+  
+  class SalesTaxCodeRef < Ref
+  end
+  
+  class ItemSalesTaxRef < Ref
+  end
+  
+  class PreferredPaymentMethodRef < Ref
+  end
+  
+  class JobTypeRef < Ref
+  end
+  
+  class PriceLevelRef < Ref
+  end
+end

data/lib/quickbooks/models/customer.rb

@@ -1,56 +1,55 @@
+require 'quickbooks/models/common/all_refs'
+require 'quickbooks/models/common/address'
+require 'quickbooks/models/customer/credit_card_info'
+
 module Quickbooks
   class Customer < ListItem
-    properties  :parent_ref,
-                :sublevel,
+    self.valid_filters = [:active_status, :from_modified_date, :to_modified_date, :name_filter, :name_range_filter, :total_balance_filter]
 
-                :name,
+    # Properties are in the order required by QBXML
+    read_write  :name,
+                :is_active,
+                ParentRef,
+                :company_name,
                 :salutation,
                 :first_name,
                 :middle_name,
                 :last_name,
                 :suffix,
-                :company_name,
-
+                BillAddress,
+                ShipAddress,
+                :print_as,
                 :phone,
-                :mobile,
-                :alt_phone,
+                # :mobile, # only in QBOE
                 :pager,
+                :alt_phone,
                 :fax,
                 :email,
                 :contact,
                 :alt_contact,
-                :bill_address,
-                :ship_address,
-
-                :notes,
-
+                CustomerTypeRef,
+                TermsRef,
+                SalesRepRef,
+                # :open_balance,
+                # :open_balance_date,
+                SalesTaxCodeRef,
+                ItemSalesTaxRef,
+                :sales_tax_country,
+                :resale_nmber,
                 :account_number,
-                :credit_card_info,
                 :credit_limit,
-                :balance,
-                :open_balance,
-                :open_balance_date,
-                :total_balance,
-                :preferred_payment_method_ref,
-
+                PreferredPaymentMethodRef,
+                CreditCardInfo,
                 :job_status,
                 :job_start_date,
                 :job_projected_end_date,
                 :job_end_date,
                 :job_desc,
-                :job_type_ref,
-
-                :print_as,
-                :customer_type_ref,
-                :delivery_method,
-                :price_level_ref,
-                :terms_ref,
-                :sales_rep_ref,
-                :sales_tax_code_ref,
-                :item_sales_tax_ref,
-                :resale_nmber,
+                JobTypeRef,
+                :notes,
                 :is_statement_with_parent,
-                :data_ext_ref
+                :delivery_method,
+                PriceLevelRef
 
     # def initialize
     #   @parent_ref = ListItem.new

data/lib/quickbooks/models/customer/credit_card_info.rb

@@ -0,0 +1,5 @@
+module Quickbooks
+  class CreditCardInfo < Model
+    read_write :credit_card_number, :expiration_month, :expiration_year, :name_on_card, :credit_card_address, :credit_card_postal_code
+  end
+end

data/lib/quickbooks/models/list_item.rb

@@ -1,22 +1,33 @@
 class Quickbooks::ListItem < Quickbooks::Base
-  attr_accessor :list_id, :full_name, :edit_sequence, :time_created, :time_modified, :is_active
+
+  self.valid_filters = [:list_id, :full_name]
+  self.filter_aliases = {:modified_after => :from_modified_date, :modified_before => :to_modified_date}
+
+  def self.inherited(klass)
+    super
+    klass.read_only :list_id, :full_name, :edit_sequence, :time_created, :time_modified
+  end
 
   class << self
-    def child_types
-      [ "Account", "Account List", "BillingRate",
-        "Class", "Currency", "Customer",
-        "CustomerMessage", "CustomerType",
-        "DateDrivenTerms", "Employee", "ItemDiscount",
-        "ItemFixedAsset", "ItemGroup", "ItemInventory",
-        "ItemInventoryAssembly", "ItemNonInventory",
-        "ItemOtherCharge", "ItemPayment", "ItemSalesTax",
-        "ItemSalesTaxGroup", "ItemService", "ItemSubtotal",
-        "JobType", "OtherName", "PaymentMethod",
-        "PayrollItemNonWage", "PayrollItemWage", "PriceLevel",
-        "SalesRep", "SalesTaxCode", "ShipMethod",
-        "StandardTerms", "TaxCode", "Template", "ToDo",
-        "Vehicle", "Vendor", "VendorType"
-      ]
+    def ListOrTxn
+      'List'
     end
+
+    # def child_types
+    #   [ "Account", "Account List", "BillingRate",
+    #     "Class", "Currency", "Customer",
+    #     "CustomerMessage", "CustomerType",
+    #     "DateDrivenTerms", "Employee", "ItemDiscount",
+    #     "ItemFixedAsset", "ItemGroup", "ItemInventory",
+    #     "ItemInventoryAssembly", "ItemNonInventory",
+    #     "ItemOtherCharge", "ItemPayment", "ItemSalesTax",
+    #     "ItemSalesTaxGroup", "ItemService", "ItemSubtotal",
+    #     "JobType", "OtherName", "PaymentMethod",
+    #     "PayrollItemNonWage", "PayrollItemWage", "PriceLevel",
+    #     "SalesRep", "SalesTaxCode", "ShipMethod",
+    #     "StandardTerms", "TaxCode", "Template", "ToDo",
+    #     "Vehicle", "Vendor", "VendorType"
+    #   ]
+    # end
   end
 end

data/lib/quickbooks/models/transaction.rb

@@ -1,6 +1,11 @@
 class Quickbooks::Transaction < Quickbooks::Base
-  # attr_accessor :id, :ref_number
-  attr_accessor :list_id, :full_name, :edit_sequence, :time_created, :time_modified, :is_active
+
+  self.valid_filters = [:txn_id]
+
+  def self.inherited(klass)
+    super
+    klass.read_only :txn_id, :full_name, :edit_sequence, :time_created, :time_modified
+  end
 
   # Currently, the following transaction types can be modified: 
   # • Bill
@@ -25,16 +30,20 @@ class Quickbooks::Transaction < Quickbooks::Base
   # • TimeTracking
 
   class << self
-    def child_types
-      [ "Bill", "BillPaymentCheck", "BillPaymentCreditCard",
-        "BuildAssembly", "Charge", "Check", "CreditCardCharge",
-        "CreditCardCredit", "CreditCardRefund", "CreditMemo",
-        "Deposit", "Estimate", "InventoryAdjustment",
-        "Invoice", "ItemReceipt", "JournalEntry",
-        "PurchaseOrder", "ReceivePayment", "SalesOrder",
-        "SalesReceipt", "SalesTaxPaymentCheck", "TimeTracking",
-        "VehicleMileage", "VendorCredit"
-      ]
+    def ListOrTxn
+      'Txn'
     end
+
+    # def child_types
+    #   [ "Bill", "BillPaymentCheck", "BillPaymentCreditCard",
+    #     "BuildAssembly", "Charge", "Check", "CreditCardCharge",
+    #     "CreditCardCredit", "CreditCardRefund", "CreditMemo",
+    #     "Deposit", "Estimate", "InventoryAdjustment",
+    #     "Invoice", "ItemReceipt", "JournalEntry",
+    #     "PurchaseOrder", "ReceivePayment", "SalesOrder",
+    #     "SalesReceipt", "SalesTaxPaymentCheck", "TimeTracking",
+    #     "VehicleMileage", "VendorCredit"
+    #   ]
+    # end
   end
 end

data/lib/quickbooks/qbxml.rb

@@ -0,0 +1,2 @@
+require 'quickbooks/qbxml/request'
+require 'quickbooks/qbxml/response'

data/lib/quickbooks/qbxml/request.rb

@@ -48,57 +48,96 @@ thequickbooks_qbxmlrequestsetxml
     end
 
     class Request
-      # @type = there are four types of queries...
-        # 1) List queries (:query)
-        # 2) Object-specific transaction query (:transaction)
-        # 3) Generic transaction query (:any_transaction)
-        # 4) Reports (:report)
-      # ...and then there are Mod requests...
-      # # 1) Mod request (:mod)
-      def initialize(object, type, options={})
+      # 1. List queries (:query)
+      #   Request.new(object, :query) # <= will return the record matching the object supplied (automatically searches by list_id or txn_id)
+      #   Request.new(Customer, :query, :limit => 1) # <= will return the first customer
+      #   Request.new(Customer, :query, /some match/) # <= will return all customers matching the regexp
+      # 2. Object-specific transaction query (:transaction)
+      #   Request.new(Transaction, :query) # <= will return the transaction matching the object supplied
+      # 3. Mod requests (:mod)
+      #   Request.new(object, :mod) # <= will update the object
+      # 4. Delete requests (:delete)
+      #   Request.new(object, :delete) # <= will delete the object
+      # We want the attributes of the object when we are updating, but no other time.
+      def initialize(object, type, options_or_regexp={})
+        options = options_or_regexp.is_a?(Regexp) ? {:matches => options_or_regexp} : options_or_regexp
         @type = type
         raise ArgumentError, "Quickbooks::Qbxml::Requests can only be of one of the following types: :query, :transaction, :any_transaction, :mod, :add, :delete, or :report" unless @type.is_one_of?(:query, :transaction, :any_transaction, :mod, :report, :add, :delete)
+        @klass = object.is_a?(Class) ? object : object.class
         @object = object
-        @filters = options if @type.is_one_of?(:query, :transaction, :any_transaction, :report)
-        @attributes = options.stringify_keys! if @type.is_one_of?(:mod, :add, :delete)
-        # puts self.inspect
+        @options = options
+
+        # Return only specific properties: Request.new(Customer, :query, :only => [:list_id, :full_name]); Quickbooks::Customer.first(:only => :list_id)
+        @ret_elements = @options.delete(:only).to_a.only(@klass.properties).order!(@klass.properties).stringify_values.camelize_values!(Quickbooks::CAMELIZE_EXCEPTIONS) if @options.has_key?(:only)
+
+        # Includes only valid filters + aliases for valid filters, then transforms aliased filters to real filters, then camelizes keys to prepare for writing to XML, lastly orders the keys to a valid filter order.
+# You may optionally have ListID OR FullName OR ( MaxReturned AND ActiveStatus AND FromModifiedDate AND ToModifiedDate AND ( NameFilter OR NameRangeFilter ) )
+        @filters = options.stringify_keys.only(@klass.valid_filters + @klass.filter_aliases.keys).transform_keys!(@klass.filter_aliases).camelize_keys!(Quickbooks::CAMELIZE_EXCEPTIONS).order!(@klass.camelized_valid_filters)
+
+        # Complain if:
+        #   1) type is :mod or :delete, and object supplied is not a valid model
+        raise ArgumentError, "A Quickbooks record object must be supplied to perform an add, mod or del action" if @type.is_one_of?(:add, :mod, :delete) && !@object.is_a?(Quickbooks::Base)
       end
 
       def self.next_request_id
-        @request_id ||= 5000
+        @request_id ||= 0
         @request_id += 1
       end
 
-      # This is where the magic happens to convert a request object into xml worthy of sending off to quickbooks.
+      # This is where the magic happens to convert a request object into xml worthy of quickbooks.
       def to_xml(as_set=true)
         return (RequestSet.new(self)).to_xml if as_set # Simple call yields xml as a single request in a request set. However, if the xml for the lone request is required, pass false.
         req = Builder::XmlMarkup.new(:indent => 2)
-        case
+        request_root, container = case
         when @type.is_one_of?(:query)
-          request_root = "#{@object}QueryRq"
-          container = nil
-        when @type == :mod
-          request_root = "#{@object}ModRq"
-          container = "#{@object}Mod"
+          ["#{@klass.class_leaf_name}QueryRq", nil]
         when @type == :add
-          request_root = "#{@object}AddRq"
-          container = "#{@object}Add"
+          ["#{@klass.class_leaf_name}AddRq", "#{@klass.class_leaf_name}Add"]
+        when @type == :mod
+          ["#{@klass.class_leaf_name}ModRq", "#{@klass.class_leaf_name}Mod"]
         when @type == :delete
-          # request_root = "#{@object}DelRq"
-          request_root = Quickbooks::ListItem.child_types.include?(@object) ? 'ListDelRq' : 'TxnDelRq'
-          container = nil
-          # container = Quickbooks::ListItem.child_types.include?(@object) ? 'ListDelType' : 'TxnDelType'
-          @attributes.merge!((Quickbooks::ListItem.child_types.include?(@object) ? 'ListDelType' : 'TxnDelType') => @object)
+          ["#{@klass.ListOrTxn}DelRq", nil]
         else
           raise RuntimeError, "Could not convert this request to qbxml!\n#{self.inspect}"
         end
         inner_stuff = lambda {
-          ['ListDelType', 'TxnDelType', 'ListID', 'TxnID', 'EditSequence'].each do |key|
-            req.tag!(key, @attributes.delete(key)) if @attributes.has_key?(key)
-          end if @attributes
-          (@filters || @attributes).each do |key,value|
-            req.tag!(key, value)
+          deep_tag = lambda {|k,v|
+            if v.is_a?(Hash)
+              if k == ''
+                v.each { |k,v|
+                  deep_tag.call(k,v)
+                }
+              else
+                req.tag!(k.camelcase) { v.each { |k,v| deep_tag.call(k,v) } }
+              end
+            else
+              req.tag!(k.camelcase,uncast(v))
+            end
+          }
+
+          # Add the specific elements for the respective request type
+          if @type.is_one_of?(:add, :mod)
+            if @type == :mod
+              # First the ObjectId:
+              req.tag!(@klass.ListOrTxn + 'ID', @object.send("#{@klass.ListOrTxn}Id".underscore))
+              # Second the EditSequence
+              req.tag!('EditSequence', @object.send(:edit_sequence))
+            end
+            # Then, all the dirty_attributes
+            deep_tag.call('',@object.to_dirty_hash) # (this is an hash statically ordered to the model's qbxml attribute order)
+          elsif @type == :query && @object.class == @klass
+            # Sent an instance object for a query - we should include the ListId/TxnId (then other filters?)
+            req.tag!(@klass.ListOrTxn + 'ID', @object.send("#{@klass.ListOrTxn}Id".underscore))
+            deep_tag.call('', @filters)
+          elsif @type == :delete
+            req.tag!(@klass.ListOrTxn + 'DelType', @klass.class_leaf_name)
+            req.tag!(@klass.ListOrTxn + 'ID', @object.send("#{@klass.ListOrTxn}Id".underscore))
+          else
+            # just filters
+            deep_tag.call('', @filters)
           end
+          # Lastly, specify the fields to return, if desired
+          @ret_elements.each { |r| req.tag!('IncludeRetElement', r) } if !@ret_elements.blank?
         }
         req.tag!(request_root, :requestID => self.class.next_request_id) {
           if container
@@ -112,6 +151,16 @@ thequickbooks_qbxmlrequestsetxml
         # puts req.target!
         req.target!
       end
+
+      private
+        def uncast(v)
+          case
+          when v.is_a?(Time)
+            v.xmlschema
+          else
+            v
+          end
+        end
     end
 
     module RequestSetArrayExt