Add support for finding single contacts by email address. (Now utiliz…

…e query params in collection_path.)

Only permit setting opt_in_source to ACTION_BY_CONTACT or ACTION_BY_CUSTOMER.
Updated README formatting and a couple of examples.

README.md

@@ -5,27 +5,28 @@ This is a very ActiveResource-like ruby wrapper to the Constant Contact API.  It
 See the [ActiveResource::Base docs](http://api.rubyonrails.org/classes/ActiveResource/Base.html) for more information on how to use this ActiveResource-based wrapper.
 
 Examples
-=======
+--------
 
-Find Lists
-======
+All examples require setting up either the specific class you'll be use or the Base object before use:
+
+    ConstantContact::Base.user = 'user'
+    ConstantContact::Base.api_key = 'api-key'
+    ConstantContact::Base.password = 'password'
 
 
+### Find Lists
+
     ConstantContact::List.find(1)
     ConstantContact::List.find :all
 
-Find Contact Example
-======
+### Find A Contact
 
-    ConstantContact::Base.user = 'user'
-    ConstantContact::Base.api_key = 'api-key'
-    ConstantContact::Base.password = 'password'
 
     ConstantContact::Contact.find(1)
     ConstantContact::Contact.find(:first, :params => {:email => 'jon@example.com'})
+    ConstantContact::Contact.find_by_email('jon@example.com') # => same as previous line
 
-Create a Contact (with rescue if it already exists)
-======
+### Create a Contact (with rescue if it already exists)
 
     ConstantContact::Base.user = 'user'
     ConstantContact::Base.api_key = 'api-key'
@@ -45,11 +46,10 @@ Create a Contact (with rescue if it already exists)
       puts e
     end
 
-Find a Contact By Email Address, Check if They're a Member of the Default List
-=====
+### Find a Contact By Email Address, Check if They're a Member of the Default List
 
-    c = ConstantContact::Contact.find(:first, :params => {:email => 'jon@example.com'.downcase})
-    @contact = ConstantContact::Contact.find(ConstantContact::Contact.parse_id(@contact.id))
+    c = ConstantContact::Contact.find_by_email('jon@example.com')
+    @contact = ConstantContact::Contact.find(@contact.int_id)
     puts 'In default contact list.' if @contact.contact_lists.include?(1) # contact_lists is an array of list ids
 
 

lib/constant_contact/base.rb

@@ -41,15 +41,37 @@ def connection(refresh = false)
 
       def collection_path(prefix_options = {}, query_options = nil)
         prefix_options, query_options = split_options(prefix_options) if query_options.nil?
-        "/ws/customers/#{self.user}#{prefix(prefix_options)}#{collection_name}"
+        "/ws/customers/#{self.user}#{prefix(prefix_options)}#{collection_name}#{query_string(query_options)}"
       end  
 
       def element_path(id, prefix_options = {}, query_options = nil)
         prefix_options, query_options = split_options(prefix_options) if query_options.nil?
         integer_id = parse_id(id)
         id_val = integer_id.zero? ? nil : "/#{integer_id}"
         "#{collection_path}#{id_val}#{query_string(query_options)}"
-      end      
+      end
+
+      # Slight modification to AR::Base.find_every to handle instances
+      # where a single element is returned. This enables calling
+      # <tt>find(:first, {:params => {:email => 'sample@example.com'}})
+      def find_every(options)
+        case from = options[:from]
+        when Symbol
+          instantiate_collection(get(from, options[:params]))
+        when String
+          path = "#{from}#{query_string(options[:params])}"
+          instantiate_collection(connection.get(path, headers) || [])
+        else
+          prefix_options, query_options = split_options(options[:params])
+          path = collection_path(prefix_options, query_options)
+          result = connection.get(path, headers)
+          case result.class.name
+          when 'Hash': instantiate_collection( [ result ], prefix_options )
+          else
+            instantiate_collection( (result || []), prefix_options )
+          end
+        end
+      end
     end
 
     # Slightly tweaked ARes::Base's implementation so all the

lib/constant_contact/contact.rb

@@ -29,6 +29,11 @@ def opt_in_source
       @opt_in_source ||= "ACTION_BY_CUSTOMER"
     end
 
+    # see http://developer.constantcontact.com/doc/manageContacts#create_contact for more info about the two values.
+    def opt_in_source=(val)
+      @opt_in_source = val if ['ACTION_BY_CONTACT','ACTION_BY_CUSTOMER'].include?(val)
+    end
+
     def list_url(id=nil)
       id ||= defined?(self.list_id) ? self.list_id : 1
       "http://api.constantcontact.com/ws/customers/#{self.class.user}/lists/#{id}"
@@ -62,6 +67,16 @@ def contact_lists
     def contact_lists=(val)
       @contact_lists = val.kind_of?(Array) ? val : [val]
     end
-
+
+    def self.find_by_email(email_address)
+      find :first, {:params => {:email => email_address.downcase}}
+    end
+
+    protected
+    def validate
+      # errors.add(:opt_in_source, 'must be either ACTION_BY_CONTACT or ACTION_BY_CUSTOMER') unless ['ACTION_BY_CONTACT','ACTION_BY_CUSTOMER'].include?(attributes['OptInSource'])
+      # errors.add(:email_address, 'cannot be blank') unless attributes.has_key?('EmailAddress')
+    end
+
   end
 end