quickbooks 0.4.0 → 0.9.9

data/lib/quickbooks/adapters/spew_adapter.rb

@@ -0,0 +1,39 @@
+# This is a very simple adapter that just throws back your Qbxml Requests. You could use it if you want to
+# handle the sending and receiving of data asynchronously, such as with the Quickbooks Web Connector.
+module Quickbooks
+  module Adapters
+    module SpewAdapter
+      class Connection
+        def initialize(*args)
+        end
+
+        # Returns true if there is an open connection to Quickbooks, false if not. Use session? to determine an open session.
+        def connected?
+          @connected ||= false
+        end
+
+        def close
+        end
+
+        # Sends a request to Quickbooks. This request should be a valid QBXML request. Use Qbxml::Request to generate valid requests.
+        def send_xml(xml)
+          warn "Quickbooks Spew:\n#{xml}" if $DEBUG
+          throw :response, xml;
+        end
+
+        # Returns the active connection to Quickbooks, or creates a new one if none exists.
+        def connection
+          @connected = true
+        end
+
+        # We can support any version!
+        def qbxml_versions
+          ['1.0','1.1','2.0','2.1','3.0','4.0','4.1','5.0','6.0','7.0','8.0']
+        end
+        def latest_qbxml_version
+          @latest_qbxml_version ||= qbxml_versions.sort.last
+        end
+      end
+    end
+  end
+end

data/lib/quickbooks/adapters/tcp_adapter.rb

@@ -0,0 +1,71 @@
+require 'net/http'
+
+# THIS IS A LEGACY ADAPTER, ITS USE IS NOT RECOMMENDED! It is insecure and unstable.
+# This adapter sends QBXML via an HTTP connection which is kept open for each session, and expects intelligent real-time QB responses from the other end.
+module Quickbooks
+  module Adapters
+    module HttpAdapter
+      # Whatever we do here, we just have to be sure that decrypt(encrypt(data)) == data
+      module SimpleEncryption
+        def encrypt(data)
+          data
+        end
+
+        def decrypt(data)
+          data
+        end
+      end
+
+      class Connection
+        include SimpleEncryption
+        def initialize(ip, port, shared_key)
+          @ip = ip
+          @port = port
+          @shared_key = shared_key
+        end
+
+        # Returns true if there is an open connection to Quickbooks, false if not. Use session? to determine an open session.
+        def connected?
+          (@connection ||= new_connection).started?
+        end
+
+        def close
+          @connection.finish rescue nil
+        end
+
+        # Sends a request to Quickbooks. This request should be a valid QBXML request. Use Qbxml::Request to generate valid requests.
+        def send_xml(xml)
+          # TODO: request.basic_auth url.user, url.password
+          res = try_retry(1, EOFError, :before_retry => lambda {@connection.finish}) {
+            connection.post('/ProcessRequest', encrypt(xml), {'Content-Type' => 'application/xml'})
+          }
+          response = decrypt(res.body)
+          return response
+        # rescue => e
+          # Rescue from the error: I guess we have to return a pretend response that says the network failed.
+          # raise "Failsafe not yet implemented!: #{e.inspect}"
+        end
+
+        def qbxml_versions
+          res = try_retry(1, EOFError, :before_retry => lambda {@connection.finish}) { connection.get('/QBXMLVersionsForSession') }
+          response = decrypt(res.body)
+          return response.chomp.split(/,/)
+        end
+        def latest_qbxml_version
+          @latest_qbxml_version ||= qbxml_versions.sort.last
+        end
+
+        # Returns the active connection to Quickbooks, or creates a new one if none exists.
+        def connection
+          @connection.start unless connected?
+          @connection
+        end
+
+        private
+          def new_connection
+            Net::HTTP.new(@ip, @port)
+          end
+      end
+    end
+  end
+end

data/lib/quickbooks/adapters/test_adapter.rb

@@ -0,0 +1,62 @@
+require 'sha1'
+# This is a fake adapter simply for testing Qbxml Requests.
+module Quickbooks
+  module Adapters
+    module TestAdapter
+      class Connection
+        def initialize(*args)
+          @stored_responses = {}
+          @next_value = []
+          @next_block = []
+        end
+
+        def next_response(value, &block)
+          @next_value << value
+          @next_block << block
+        end
+
+        def clear_responses!
+          @next_value = []
+          @next_block = []
+        end
+
+        # Returns true if there is an open connection to Quickbooks, false if not. Use session? to determine an open session.
+        def connected?
+          @connected ||= false
+        end
+
+        def close
+        end
+
+        # Sends a request to Quickbooks. This request should be a valid QBXML request. Use Qbxml::Request to generate valid requests.
+        def send_xml(xml)
+          xml = xml.gsub(/ requestID=\"\d+\"/,'')
+          @next_block[0].call(xml) if @next_block[0]
+          cached_response = caching(xml, @next_value[0])
+          raise RuntimeError, "You must call next_response to set up the next response xml manually for the TestAdapter." unless cached_response
+          @next_value.shift
+          @next_block.shift
+          return cached_response
+        end
+
+        # Returns the active connection to Quickbooks, or creates a new one if none exists.
+        def connection
+          @connected = true
+        end
+
+        # We can support any version!
+        def qbxml_versions
+          ['1.0','1.1','2.0','2.1','3.0','4.0','4.1','5.0','6.0','7.0','8.0']
+        end
+        def latest_qbxml_version
+          @latest_qbxml_version ||= qbxml_versions.sort.last
+        end
+
+        private
+          def caching(key,value=nil)
+            @stored_responses[SHA1.hexdigest(key)] ||= value
+          end
+      end
+    end
+  end
+end

data/lib/quickbooks/element.rb

@@ -0,0 +1,385 @@
+require 'quickbooks/property'
+require 'quickbooks/option'
+module Quickbooks
+  module Elements
+    def self.singularize
+      Quickbooks::Element
+    end
+  end
+  # Element is the parent of all QBXML elements (tags) that have children. This includes the outer wrapping QBXML tag, request and response tags such as CustomerAddRq and AccountModRs, data return tags such as AccountRet, and any data fields inside them that also have children. If you don't know what those tags are, don't worry, Model takes care of knowing how to handle them for you.
+  # 
+  # Element acts a lot like a Model but without the record-handling parts, and also acts a little like a Property.
+  class Element
+    def self.pluralize
+      Quickbooks::Elements
+    end
+    class << self
+      attr_reader :properties, :options, :associations
+      attr_accessor :xsd
+      def xsd=(xsd_element)
+        @xsd = xsd_element
+        # Initialize the properties, options and associations
+        @properties = @xsd.children
+        @options = Options.from_xsd(xsd)
+        # TODO: Create the associations for Elements!
+        @associations = {}
+      end
+
+      def order(obj, a, b) #:nodoc:
+        c = (
+          obj.class.xsd.index(a.class.short_name) || obj.class.xsd.index(a.class.short_name + obj.send(:suffix))
+        ) <=> (
+          obj.class.xsd.index(b.class.short_name) || obj.class.xsd.index(b.class.short_name + obj.send(:suffix))
+        )
+        c == 0 ? a.instance_variable_get(:@collection_index).to_i <=> b.instance_variable_get(:@collection_index).to_i : c
+      end
+
+      # Provides the class equivalent to the current class but without the Ref suffix.
+      def unref
+        QB[short_name[0..-4]]
+      end
+
+      # This is usually used internally, but is safe to use if you need it for edge cases. It is meant to create a new Element object as if you just read it from Quickbooks -- marks it as not a new record. Call on an Element class, such as QB::Customer.instantiate(attributes).
+      def instantiate(obj_or_attrs={})
+        obj = allocate
+        if obj_or_attrs.is_a?(Hash)
+          obj_or_attrs.each do |key,value|
+            key = key.to_s
+            if options.include?(key)
+              obj[key] = value
+              next
+            end
+            next unless xsd.include?(key)
+            attr_klass = QB[key]
+            # Add the new value
+            if value.is_a?(ElementCollection)
+              value.each do |v|
+                obj.attributes << v
+              end
+            else
+              value = value.is_a?(attr_klass) ? value : attr_klass.new(value)
+              obj.attributes << value if xsd.index(value.class.short_name)
+            end
+          end
+        elsif obj_or_attrs.respond_to?(:to_element) && elem = obj_or_attrs.to_element && elem.is_a?(self)
+          return elem
+        else
+          raise ArgumentError, "must supply a hash of arguments or a model object"
+        end
+        # Sort the values to the proper order
+        suffix = short_name =~ /(Add|Mod|Ret)$/ ? $1 : ''
+        obj.attributes.sort! do |a,b|
+          begin
+            Quickbooks::Element.order(obj,a,b)
+          rescue => e
+            raise e, "-> Comparing #{a.class.short_name.inspect} <=> #{b.class.short_name.inspect} in #{obj.class.short_name} XSD"
+          end
+        end
+        obj.send(:clean!)
+        obj
+      end
+    end
+    
+    # Create a new Element object, such as Account.new or ItemInventory.new. Marks item as a new record, so .save will send a create command to Quickbooks.
+    def initialize(attrs={})
+      attrs = attrs.attributes if attrs.is_a?(Element)
+      attrs = attrs.attributes.values if attrs.is_a?(Model)
+      if attrs.is_a?(Array)
+        # Allows just passing an array of attributes in.
+        set_attrs = attrs.select {|a| self.class.xsd.index(a.class.short_name)}
+        reject_attrs = attrs - set_attrs
+        raise AttributeAssignmentError, "Attribute#{'s' if reject_attrs.length > 1} not available: #{reject_attrs.join(', ')}!\nAvailable attributes: #{self.class.xsd.children.collect {|i| i.name}.join(', ')}" unless reject_attrs.empty?
+        attributes.concat(set_attrs.sort! {|a,b| Quickbooks::Element.order(self,a,b) })
+      else
+        self.attributes = attrs
+      end
+    end
+    
+    # Validate all the necessary elements and attributes are included, using the object class's spec
+    def valid?
+      validate.perfect?
+    end
+
+    # Use this instead of valid? to get the Valean result instead of just a true or false value.
+    def validate
+      r = self.class.xsd.validate(self)
+      errors.replace(r.errors)
+      r
+    end
+
+    # Holds any errors from the last time valid? is run.
+    def errors
+      @errors ||= []
+    end
+    def add_error(msg) #:nodoc:
+      errors << [nil, msg]
+    end
+
+    def inspect #:nodoc:
+      "<#{self.class.short_name}:##{object_id}#{' ' + options.collect {|k,v| "#{k}=#{v.inspect}"}.join(' ')}#{" [#{@collection_index}]" if instance_variables.include?('@collection_index')}\n  #{attributes.collect {|a| a.inspect}.join("\n").gsub(/\n/, "\n  ")}>"
+    end
+    
+    # An array of attribute values. Each value is of course instantiated as its own type (some subclass of Element or Property). These attributes are automatically kept in order, and can be accessed somewhat like a hash using the #[] method.
+    def attributes
+      @attributes ||= []
+    end
+
+    # Sets whatever attributes you give it using []=. Does not remove attributes not given.
+    def attributes=(attrs)
+      attrs.each do |k,v|
+        if self.class.xsd.include?(k.to_s)
+          self[k.to_s] = v
+        else
+          raise AttributeAssignmentError, "Attribute not available: #{k.to_s}!\nAvailable attributes: #{self.class.xsd.children.collect {|i| i.name}.join(', ')}"
+        end
+      end
+    end
+    
+    # Access an attribute value by its type -- use a string, a symbol, or its Class constant.
+    def [](key)
+      return self.attributes = key if key.is_a?(Hash)
+      key = case key
+      when String
+        key
+      when Symbol
+        key.to_s
+      when Module
+        key.short_name
+      else
+        raise RuntimeError, "boy, that is a weird key (type:#{key.class.name})"
+      end
+      return get_associated(key) if self.class.associations.include?(key)
+      return options.has_key?(key) ? options[key] : self.class.options[key].default if self.class.options.include?(key)
+      vals = attributes.select {|a| a.class.short_name == key}
+      property_xsd = self.class.xsd.find(key.to_s)
+      property_xsd ? (self.class.xsd.repeatable?(key.to_s) ? vals : vals[0]) : nil
+    end
+    
+    # Set the value of an attribute. If key refers to an association, it associates the given value. If it is an option, it sets the option.
+    # Otherwise if it's a valid attribute, it sets the attribute value.
+    # 
+    # Note: If multiple of this attribute are allowed, you must send an array of values as the value.
+    def []=(key,value)
+      key = case key
+      when String
+        key
+      when Symbol
+        key.to_s
+      when Module
+        key.short_name
+      else
+        raise RuntimeError, "man is that a weird kind of key to use (type:#{key.class.name})!"
+      end
+      return associate(key, value) if self.class.associations.include?(key)
+      unless self.class.xsd.include?(key)
+        if self.class.short_name =~ /(Add|Mod|Ret)$/ && self.class.xsd.include?(key + $1)
+          key = key + $1
+        else
+          return options[key] = value if self.class.options.include?(key)
+          raise Quickbooks::InvalidAttributeError, "'#{key}' is not a valid property or option name for #{self.class.name}!"
+        end
+      end
+      # Instantiate the value into the attribute class, if necessary
+      attr_klass = Quickbooks.get_constant(key.to_s)
+      if self.class.xsd.repeatable?(key.to_s)
+        if value.is_a?(ElementCollection) || value.is_a?(Array)
+          attributes.reject! {|a| a.is_a?(attr_klass)}
+          value.each do |val|
+            val = attr_klass.new(val) unless val.is_a?(attr_klass)
+            val.send(:dirty!)
+            attributes << val
+          end
+        else
+          # If it *should* be an array element, it shouldn't be set here as a single value. This is just for safeguard, so that syntax
+          # always shows what is going on. For an array element, set it with: object.some_attr = [value]
+          raise RuntimeError, "You can't set a single value into a multi-value element to using equals(=). Use \"element[:#{key}] << value\" to append, or wrap the value in an array -- \"element[:#{key}] = [ value ]\" -- if you want to completely replace the current value set."
+        end
+      else
+        value = attr_klass.new(value) unless value.is_a?(attr_klass)
+        value.send(:dirty!)
+        # Remove the previous value
+        attributes.reject! {|a| a.is_a?(attr_klass)}
+        # Add the new value
+        attributes << value
+      end
+      # Sort the values to the proper order
+      attributes.sort! {|a,b| Quickbooks::Element.order(self, a, b) }
+    end
+    
+    # Remove an attribute from the object. Setting an attribute to nil will be an attribute set to nil, but if you remove the
+    # attribute completely, it won't be considered in create/update operations.
+    def delete(*keys)
+      keys.each do |key|
+        key = case key
+        when String
+          key
+        when Symbol
+          key.to_s
+        when Module
+          key.short_name
+        else
+          raise RuntimeError, "boy, that is a weird key (type:#{key.class.name})"
+        end
+        unless self.class.xsd.include?(key) || (self.class.short_name =~ /(Add|Mod|Ret)$/ && self.class.xsd.include?(key + $1))
+          return options.delete(key) if self.class.options.include?(key)
+          raise RuntimeError, "'#{key}' is not a valid property or option name for #{self.class.name}!"
+        end
+        # Instantiate the value into the attribute class, if necessary
+        attr_klass = Quickbooks.get_constant(key.to_s)
+    
+        attributes.reject! {|a| a.is_a?(attr_klass)}
+      end
+    end
+    
+    # The attributes that have been changed.
+    def dirty_attributes(include_required=false)
+      attr_hash = attributes_hash # (Speedier when we only do it once)
+      include_required ?
+        attributes.select {|a| a.dirty? || self.class.xsd.required?(a.class.short_name) || !self.class.xsd.validate(self.class.short_name => attr_hash.except(a.class.short_name))} :
+        attributes.select {|a| a.dirty?}
+    end
+    
+    # The attributes that have not been changed.
+    def clean_attributes
+      attributes.reject {|a| a.dirty?}
+    end
+    
+    # Has anything in this object (or its descendents) changed?
+    def dirty?
+      # Test for any dirty elements
+      @dirty || attributes.any? {|e| e.dirty?}
+    end
+    
+    # Returns self. Just a convenience method for interoperability with Model.
+    def to_element
+      self
+    end
+
+    # Attemps to get the Model object being referenced, if this is a Ref class.
+    def unref
+      @retrieve_full ||= begin
+        filter = {}
+        case
+        when self[:ListID]
+          filter[:ListID]   = [self[:ListID]]
+        when self[:TxnID]
+          filter[:TxnID]    = [self[:TxnID]]
+        when self[:FullName]
+          filter[:FullName] = [self[:FullName]]
+        end
+        self.class.unref.first(filter)
+      end
+    end
+        
+    # Converts the element to a model if it is an appropriate class type.
+    def to_model
+      # List clean attributes
+      clean_attrs = attributes_to_hash(clean_attributes).inject({}) {|h,(k,v)| h[k.gsub(/(Add|Mod|Ret)$/,'')] = v.respond_to?(:to_model) ? v.to_model : v; h}
+      # List dirty attributes
+      dirty_attrs = attributes_to_hash(dirty_attributes).inject({}) {|h,(k,v)| h[k.gsub(/(Add|Mod|Ret)$/,'')] = v.respond_to?(:to_model) ? v.to_model : v; h}
+      # Set up the corresponding element with corresponding properties
+      model = model_klass.instantiate(clean_attrs)
+      model.attributes = dirty_attrs
+      # Transfer the order index (for attribute sorting) from elements that were in a collection.
+      model.instance_variable_set(:@collection_index, @collection_index) if instance_variables.include?('@collection_index')
+      model
+    end
+    
+    def to_update_element
+      update_element = self.class.new
+      update_element.attributes.replace(dirty_attributes(true))
+      update_element
+    end
+    
+    # Dumps all data into QBXML.
+    def to_xml
+      '<' + self.class.short_name + [[nil] + options.collect {|k,v| "#{k}=#{v.inspect}"}].join(' ') + '>' +  ("\n" + attributes.collect {|a| a.to_xml}.join("\n")).gsub(/\n( *)</, "\n  \\1<") + "\n</" + self.class.short_name + '>'
+    end
+    
+    # Dumps only the changed data into QBXML. Useful for updating only specific attributes without touching the rest. Set include_required to true if you need valid qbxml to send.
+    def to_dirty_xml(include_required=false)
+      '<' + self.class.short_name + '>' +  ("\n" + dirty_attributes(include_required).collect {|a| a.to_dirty_xml(include_required)}.join("\n")).gsub(/\n( *)</, "\n  \\1<") + "\n</" + self.class.short_name + '>'
+    end
+
+    # Simply calls to_dirty_xml(true). Returns the minimal xml necessary to update the record in QuickBooks.
+    def update_xml
+      to_dirty_xml(true)
+    end
+    
+    def save_associations #:nodoc:
+      # first save any of my associated items that aren't already existing
+      self.class.associations.each_key do |association_name|
+        if instance_variable_get("@#{association_name}") && self[association_name].new_record?
+          self[association_name].save
+          self[association_name] = self[association_name] # re-assigns the associated Ref
+        end
+      end
+      # then save any of my children's associated items that aren't already existing
+      attributes.each { |attv| attv.save_associations if attv.respond_to?(:save_associations) }
+    end
+    
+    # I don't remember why this nil? had to be modified. If the need pops back up, CREATE A TEST to show the need!!
+    # def nil? #:nodoc:
+    #   if self.class.xsd.include?('FullName') && self.class.xsd.include?('ListID') || (self.class.xsd.include?('TxnID') && !self.class.xsd.name =~ /DataExt/)
+    #     self[:FullName].nil? && self[:ListID].nil? && self[:TxnID].nil?
+    #   else
+    #     super
+    #   end
+    # end
+
+    def new_record?
+      
+    end
+
+    private
+    
+    def model_klass
+      Quickbooks.get_constant(self.class.short_name.gsub(/(Add|Mod|Ret)$/,''))
+    end
+    
+    def clean!
+      @dirty = false
+      attributes.each {|e| e.send(:clean!)}
+    end
+    
+    def dirty!
+      @dirty = true
+    end
+    
+    def get_associated(association_name)
+      instance_variable_get("@#{association_name}") || begin
+        ref_klass = self.class.associations[association_name].to_constant
+        self[ref_klass].nil? ? nil : instance_variable_set("@#{association_name}", self[ref_klass].unref)
+      end
+    end
+    
+    def associate(association_name, value)
+      instance_variable_set("@#{association_name}", value)
+      ref = value.to_ref
+      ref_klass = self.class.associations[association_name].to_constant
+      !ref.nil? ?
+        self[ref_klass] = ref :
+        self.delete(ref_klass)
+    end
+    
+    def attributes_to_hash(some_attributes)
+      some_attributes.inject({}) do |h,att|
+        k = att.class.short_name
+        h[k] = self.class.xsd.repeatable?(k) ? ElementCollection.new(self,k,self[k]) : att
+        h
+      end
+    end
+
+    def attributes_hash
+      attributes_to_hash(attributes)
+    end
+    
+    def options
+      @options ||= self.class.options.defaults
+    end
+    
+    def suffix
+      self.class.short_name =~ /(Add|Mod|Ret)$/ ? $1 : ''
+    end
+  end
+end