etapper 0.0.0

data/lib/etapper/classes/account.rb

@@ -0,0 +1,119 @@
+require 'etapper/classes/etap_abstract'
+
+module Etapper
+  class Account < EtapAbstract
+    
+    DONOR_RECOGNITION_TYPES = [
+      :donor_name,
+      :do_not_recognize,
+      :anonymous,
+      :recognition_name
+      ]
+    
+    ACCOUNT_ROLE_TYPES = [
+      :donor,
+      :tribute,
+      :user
+      ]
+        
+    etap_read_only :id,
+                   :ref,
+                   :userRoleRef,
+                   :donorRoleRef,
+                   :tributeRoleRef,
+                   :accountRef,
+                   :personaTypes
+    
+    # Returns an Account object retrieved from eTapestry using the supplied parameter.
+    # The exact method used varies by the query parameter type:
+    # * INTEGER: getAccountById()
+    # * ACCOUNT REF (dot-separated number string): getAccount()
+    # * E-MAIL ADDRESS: getDuplicateAccount
+    # * HASH: getAccountRef() with defined value, then getAccount() (only the first hash value is used)
+    def self.find(query)
+      case query
+      when Integer
+        a = Etapper::client.getAccountById(query)
+      when /\d+\.\d+\.\d+/  # "4310.0.2276679"
+        a = Etapper::client.getAccount(query)
+      when /\S+@\S+\.\S+/  # very simplistic e-mail checking but suffices for this purpose
+        s = DuplicateAccountSearch.new(:email => query)
+        a = Etapper::client.getDuplicateAccount(s.base)
+      when Hash
+        v = DefinedValue.new(query)
+        a = Etapper::client.getAccountByUniqueDefinedValue(v.base)
+      end
+      Account.new(a) if a
+    end
+       
+    
+    def phones
+      @base.phones ||= Etapper::API::ArrayOfPhone.new
+      @phones ||= Etapper::PhoneHash.new(base.phones)
+    end
+    
+
+    def phone
+      phones[:voice] || phones[:business] || phones[:mobile] || phones[:home]
+    end
+    
+    def phone=(val)
+      phones[:voice] = val
+    end
+    
+    def fax
+      phones[:fax]
+    end
+    
+    def fax=(val)
+      phones[:fax] = val
+    end
+    
+    def personaDefinedValues
+      @base.personaDefinedValues ||= Etapper::API::ArrayOfDefinedValue.new
+      @personaDefinedValues ||= Etapper::DefinedValueHash.new(base.personaDefinedValues)
+    end
+    
+    def accountDefinedValues
+      @base.accountDefinedValues ||= Etapper::API::ArrayOfDefinedValue.new
+      @accountDefinedValues ||= Etapper::DefinedValueHash.new(base.accountDefinedValues)
+    end
+    
+    def definedValues
+      @definedValues = accountDefinedValues.merge(personaDefinedValues).freeze
+    end
+    
+    def donorRecognitionType
+      DONOR_RECOGNITION_TYPES[@base.donorRecognitionType]
+    end
+
+    def donorRecognitionType=(val)
+      @base.donorRecognitionType = DONOR_RECOGNITION_TYPES.index(val)
+    end
+    
+    def accountRoleType
+      ACCOUNT_ROLE_TYPES[@base.accountRoleType]
+    end
+    
+    def accountRoleType=(val)
+      @base.accountRoleType = ACCOUNT_ROLE_TYPES.index(val)
+    end
+    
+    # Retrieves all Gift journal entries for the account. 
+    def gifts
+      @gifts ||= Gift.findByAccount(self)
+    end
+     
+    # Retrieves all Contact journal entries for the account.
+    def contacts
+      @contacts ||= Contact.findByAccount(self)
+    end
+    
+    # Return the eTapestry account ID
+    def id
+      base.id
+    end
+    
+      
+  end
+end

data/lib/etapper/classes/contact.rb

@@ -0,0 +1,13 @@
+require 'etapper/classes/journal_entry'
+
+module Etapper
+  class Contact < JournalEntry
+        
+    # Returns the base method -- must declare explicitly because of the
+    # Object#method method. Yrrr.
+    def method
+      @base.method
+    end
+    
+  end
+end

data/lib/etapper/classes/defined_value.rb

@@ -0,0 +1,77 @@
+require 'etapper/classes/hashable'
+module Etapper
+  # Wraps the eTapestry API "DefinedValue" complex type with something easier to use.
+  class DefinedValue
+    extend Forwardable
+    include Hashable
+    
+    DATA_TYPE = {
+      :text => 0,
+      :date => 1,
+      :month_and_day => 2,
+      :number => 3,
+      :currency => 4
+    }
+    
+    DISPLAY_TYPE = {
+      :text => 0,
+      :single_select => 1,
+      :multi_select => 2,
+      :text_area => 3
+    }
+
+    def_delegators :@base, 
+                   :dataType,:dataType=,
+                   :displayType,:displayType=,
+                   :fieldName, :fieldName=,
+                   :fieldRef,
+                   :value,:value=,
+                   :valueRef
+
+# Takes a hash specifying a field name and its value.  Also allows :data_type and :display_type as hash keys.
+    def initialize(params = {})
+      # Order of parameters from API:
+      # {etapestryAPI/service}DefinedValue
+      #   dataType - SOAP::SOAPInt
+      #   displayType - SOAP::SOAPInt
+      #   fieldName - SOAP::SOAPString
+      #   fieldRef - SOAP::SOAPString
+      #   value - SOAP::SOAPString
+      #   valueRef - SOAP::SOAPString
+      if params.kind_of?(Etapper::API::DefinedValue)
+        @base = params
+      else
+        display_type = DISPLAY_TYPE[params.delete(:display_type)] || 0
+        data_type = DATA_TYPE[params.delete(:data_type)] || 0
+        fieldname = params.delete(:fieldName)
+        fieldref = params.delete(:fieldRef)
+        value = params.delete(:value)
+        valueRef = params.delete(:valueRef)
+        
+        unless (fieldname and value)
+          if params.size == 1
+            fieldname = params.keys.first
+            value = params[fieldname]
+          else
+            raise Etapper::BadValueError, "Only one field value can be provided; instead got #{params.size} (#{params.to_s})"
+          end
+        end
+        fieldname = fieldname.titleize if fieldname.is_a?(Symbol)          
+        @base = Etapper::API::DefinedValue.new(data_type, display_type, fieldname, nil, value, nil)
+      end
+    end
+    
+    def base
+      @base
+    end
+    
+    def key
+      fieldName.symbolize
+    end
+    
+    def key=(val)
+      fieldName = val.titleize
+    end
+    
+  end
+end

data/lib/etapper/classes/defined_value_hash.rb

@@ -0,0 +1,48 @@
+require 'etapper/classes/etap_hash'
+
+module Etapper
+  class DefinedValueHash < EtapHash
+    def initialize(array_from_api)
+       super(array_from_api, DefinedValue, :fieldName, :value)
+    end
+    
+    def []=(key, val)
+      add_or_append(key, val)
+      # update_base(key, val)
+      # hash_assign(key, val)
+    end
+    
+    
+    def add_or_append(key, val)
+      if self.has_key?(key)
+        arr = Array(self[key]) << val
+        self.update_base(key, arr)
+        self.hash_assign(key, arr)
+      else
+        self.update_base(key, val)
+        self.hash_assign(key, val)
+      end
+    end
+  
+  protected
+    def add_to_self(obj)
+      key, value = obj.key, obj.value
+      if self.has_key?(key)
+        arr = Array(self[key]) << value
+        self.hash_assign(key, arr)
+      else
+        self.hash_assign(key, value)
+      end
+    end
+    
+    def add_to_detailed(obj)
+      key = obj.key
+      if @detailed.has_key?(key)
+        arr = Array(@detailed[key]) << obj
+        @detailed[key] = arr
+      else
+        @detailed[key] = obj 
+      end
+    end
+  end
+end

data/lib/etapper/classes/duplicate_account_search.rb

@@ -0,0 +1,49 @@
+module Etapper
+  # Wraps the eTapestry API "DuplicateAccountSearch" complex type with something easier to use.
+  class DuplicateAccountSearch
+    extend Forwardable
+    
+    ACCOUNT_ROLE_TYPES = {
+      :donors_and_tributes => 0,
+      :donors_only => 1,
+      :tributes_only => 2
+    }
+    
+    def_delegators :@base, 
+                   :name,
+                   :address,
+                   :email,
+                   :phoneNumber,
+                   :accountRoleTypes,
+                   :allowEmailOnlyMatch
+    
+    # Takes a hash specifying values. At least one of :name, :address, :email or :phone must be provided.
+    # allowEmailOnlyMatch defaults to true if an email is given; false otherwise.
+    # accountRoleTypes defaults to :donors_only if not provided.
+    def initialize(params = {})
+      name, address, phone, email = params.values_at(:name, :address, :phone, :email)
+      if params.has_key?(:allow_email_only_match)
+        emailOnly = params[:allow_email_only_match]
+      else
+        emailOnly = !!email
+      end
+      roleTypes = ACCOUNT_ROLE_TYPES[params[:account_role_types]] || ACCOUNT_ROLE_TYPES[:donors_only]
+      
+      # Check our parameters
+      raise Etapper::BadValueError, "You must supply at least one search field!" unless (name || address || phone || email)
+      
+      # {etapestryAPI/service}DuplicateAccountSearch
+      #   accountRoleTypes - SOAP::SOAPInt
+      #   address - SOAP::SOAPString
+      #   allowEmailOnlyMatch - SOAP::SOAPBoolean
+      #   email - SOAP::SOAPString
+      #   name - SOAP::SOAPString
+      #   phoneNumber - SOAP::SOAPString
+      @base = Etapper::API::DuplicateAccountSearch.new(roleTypes, address, emailOnly, email, name, phone)
+    end 
+    
+    def base
+      @base
+    end
+  end
+end

data/lib/etapper/classes/etap_abstract.rb

@@ -0,0 +1,59 @@
+module Etapper
+  class EtapAbstract 
+    def self.cname
+      self.name.gsub /^(.*::)/,''
+    end
+    
+    def initialize(base = nil)
+      @new = !base
+      @base = base || eval("Etapper::API::#{self.class.cname}.new")
+    end
+    
+    def base
+      @base
+    end
+    
+    # Creates a method that throws an Etapper::ReadOnlyError on attempts to assign that attribute
+    def self.etap_read_only(*attributes)
+      attributes.each do |attribute|
+        att = attribute.to_s
+        class_eval <<-ENDDEF
+        def #{att}=(val)
+          raise Etapper::ReadOnlyError, "#{self.cname} #{att} is read-only!"
+        end
+        ENDDEF
+      end
+    end
+    
+    def method_missing(attribute, *args)
+      # Try to get it from the defined values hash first, if one exists
+      return definedValues[attribute] if respond_to?(:definedValues) and definedValues.has_key?(attribute)
+      
+      # Look in the base class next
+      return base.send(attribute, *args) if base.respond_to?(attribute)
+
+      # Finally, bubble up
+      super(attribute, *args)
+    end
+       
+    def new?
+      @new
+    end
+    
+    def save
+      if new?
+        method = ("add" + self.class.cname).to_sym        
+      else
+        method = ("update" + self.class.cname).to_sym        
+      end
+      Client.instance.send(method, base, true)
+    end
+    
+    # Two eTapper classes are the same if they have the same base object
+    def ==(val)
+      val.base == base
+    end
+       
+      
+  end
+end

data/lib/etapper/classes/etap_hash.rb

@@ -0,0 +1,47 @@
+module Etapper
+  # This is a virtual base class for specialized representations of eTapestry API arrays 
+  # such as PhoneHash, DefinedValueHash, etc.  It _should not_ be invoked on its own.  It
+  # needs the following constants defined in subclasses to work:
+  class EtapHash < Hash
+    attr_reader :base, :detailed, :etapper_class
+    alias_method :hash_assign, :[]=
+    
+    def initialize(array_from_api, etapper_class, key_symbol, value_symbol)
+      @base, @etapper_class, @key_symbol, @value_symbol = array_from_api, etapper_class, key_symbol, value_symbol
+      @detailed = Hash.new
+      @base.each do |element|
+        friendly = etapper_class.new(element)
+        add_to_self(friendly)
+        add_to_detailed(friendly)  # So we can easily find our objects later
+      end
+    end
+    
+    def []=(key, val)
+      update_base(key, val)
+      hash_assign(key, val)
+    end
+    
+  protected
+  
+    def update_base(key, val)
+      if @detailed.has_key?(key)
+        friendly = @detailed[key]
+        friendly.value = val
+      else # New object, so create it and push to base
+        friendly = @etapper_class.new(@key_symbol => key, @value_symbol => val)
+        friendly.value = val
+        @detailed[key] = friendly
+        @base << friendly.base
+      end
+    end
+  
+    def add_to_self(obj)
+      self.hash_assign(obj.key, obj.value)
+    end
+    
+    def add_to_detailed(obj)
+      @detailed[obj.key] = obj  # So we can easily find our objects later
+    end
+  end
+  
+end

data/lib/etapper/classes/gift.rb

@@ -0,0 +1,22 @@
+require 'etapper/classes/journal_entry'
+
+module Etapper
+  class Gift < JournalEntry
+    
+    etap_read_only :offsettingRef, :tributeAccountRef, :tributeAccountName, :segmentedTransactionRef,
+                   :originalAccountName, :originalAccountRef, :originalTransactionRef
+    
+    def self.find(query)
+      case query
+      when /\d+\.\d+\.\d+/  # "4310.0.2276679"
+        g = client.getGift(query)
+        Gift.new(g) if g
+      when Hash
+        a = Account.find(query[:account])
+        findByAccount(a)
+      end
+    end
+    
+
+  end
+end

data/lib/etapper/classes/hashable.rb

@@ -0,0 +1,20 @@
+module Etapper
+  
+  # Abstract utility methods for maintaining useful hashes from collections of complex types
+  module Hashable
+    def to_hash
+      {key => value}
+    end
+    
+    def append_to_hash(hash)
+      hash ||= Hash.new
+      if hash.has_key?(key)
+        arr = Array(hash[key])
+        hash[key] = arr.push(value)
+        hash
+      else
+        hash.merge(self.to_hash)
+      end
+    end
+  end
+end