hominid 2.0.1 → 2.0.2

data/README.textile

@@ -1,136 +1,92 @@
 h1. Hominid
 
-Hominid is a Ruby gem that provides a wrapper for interacting with the "Mailchimp":http://www.mailchimp.com email marketing service API ("version 1.2":http://www.mailchimp.com/api/1.2/).
+Hominid is a Ruby gem that provides a wrapper for interacting with the "Mailchimp":http://eepurl.com/ew8J email marketing service API ("version 1.2":http://www.mailchimp.com/api/1.2/).
 
 h2. Installation
 
-<pre><code>sudo gem install hominid, :version => '>= 2.0.1', :source => "http://gemcutter.org"</code></pre>
+<pre><code>sudo gem install hominid</code></pre>
 
 Hominid is hosted at "Gemcutter":http://gemcutter.org. Be sure that you have the Gemcutter gem installed if you are having trouble installing Hominid:
 
-<pre><code>sudo gem install gemcutter
-gem tumble</code></pre>
+<pre><code>sudo gem install gemcutter</code></pre>
 
-h2. Configuration
+h2. Requirements
 
-You will need to create a "Mailchimp":http://www.mailchimp.com/signup account and get your API key (available at http://admin.mailchimp.com/account/api/) in order to get started.
-
-If you are using Hominid inside a Rails application, you can create a config file at @/config/hominid.yml@ with your Mailchimp account information and basic configuration options:
-
-<pre><code>development:
- username: USERNAME
- password: PASSWORD
- api_key: API KEY
- send_goodbye: false
- send_notify: false
- double_opt: false
-
-...</code></pre>
-
-Run @rake hominid:config@ from within a Rails app to create an empty config file.
-Note: You will need to <pre><code>require 'hominid'</code></pre> in your @Rakefile@ to make this rake task available to your application.
+You will need a "Mailchimp":http://eepurl.com/ew8J account. Once you have your Mailchimp account set up, you will need to "generate an API key":http://admin.mailchimp.com/account/api/ in order to get started using Hominid.
 
 h2. Usage
 
-Not all API methods are supported (yet). Currently there are classes for working with lists (_Hominid::List_), campaigns (_Hominid::Campaign_) and accessing the helper methods (_Hominid::Helper_).
-
-h3. Working with Lists
-
-The _Hominid::List_ class is available for working finding lists and working with particular lists. See _Hominid::List_ for more information.
-
-h4. List Finder Methods
+Hominid is intended to be a complete Ruby wrapper for working with the Mailchimp API. As of release 2.0.2, all methods available from the Mailchimp API (Version 1.2) are available. Please note in order to use some methods you will need to have "A.I.M. Reports":https://admin.mailchimp.com/account/addons installed on your Mailchimp account.
 
-There are finder methods for working with lists. Refer to _Hominid::List_ to see the other finders availables.
+You will need to pass your Mailchimp API key to get started:
 
-<pre><code>lists = Hominid::List.all</code></pre>
+<pre><code>h = Hominid::Base.new({:api_key => API_KEY})</code></pre>
 
-<pre><code>list = Hominid::List.find_by_name("List Name")</code></pre>
+You can also pass in any other config options that you would like to change from the defaults. Take a look at @Hominid::Base@ to see what the default values are.
 
-<pre><code>list = Hominid::List.find(id_or_web_id)</code></pre>
+Once you have created a Hominid object, you can begin interacting with the Mailchimp account that your API key is associated with.
 
-h4. Subscribing
-
-To subscribe a person or persons to a Mailchimp list:
-
-<pre><code>list.subscribe("sample@emailaddress.com")</code></pre>
+h3. Working with Lists
 
-<pre><code>list.subscribe_many([{:EMAIL => 'sample@emailaddress.com', :EMAIL_TYPE => 'html'}, {:EMAIL => 'another@emailaddress.com', :EMAIL_TYPE => 'html'}])</code></pre>
+We have provided some finder methods to make working with your mailing lists easier:
 
-h4. Unsubscribing
+<pre><code>lists = h.lists
+list = h.find_list_by_name("Mailing List Name")
+list = h.find_list_by_id("List ID")
+list = h.find_list_by_web_id("List Web ID")</code></pre>
 
-To unsubscribe a person or persons from a Mailchimp list:
+There are also finders for easily getting at List ID's, which are required for nearly all the list methods:
 
-<pre><code>list.unsubscribe("sample@emailaddress.com")</code></pre>
+<pre><code>list_id = h.find_list_id_by_name("Mailing List Name")
+list_id_ = h.find_list_id_by_web_id("List Web ID")</code></pre>
 
-<pre><code>list.unsubscribe_many(['sample@emailaddress.com', 'another@emailaddress.com'])</code></pre>
+This means that you can _(for example)_ subscribe someone to a particular mailing list:
 
-h4. Updating
+<pre><code>h.subscribe(h.find_list_id_by_name("Mailing List Name"), "email@domain.com", {:FNAME => "Bob", :LNAME => "Smith"}, {:email_type => 'html'})</code></pre>
 
-In the following example, we will be changing a person's email address on the Mailchimp list from @sample@ to @another@:
+Or to update a subscriber to a particular list:
 
-<pre><code>list.update_member('sample@emailaddress.com', {:EMAIL => 'another@emailaddress.com'}, 'html')</code></pre>
+<pre><code>h.update_member(h.find_list_id_by_name("Mailing List Name"), "old_email@domain.com", {:EMAIL => "new_email_@domain.com"}, 'html')</code></pre>
 
-You can also updated other attributes by including the MERGE_VARS that you want to change, such as @EMAIL@, @FNAME@, @LNAME@ and @INTERESTS@. Get a list of merge tags for a particular list by running @list.merge_tags@.
+Take a look at @Hominid::List@ to see the methods that are available for interacting with your lists.
 
 h3. Working with Campaigns
 
-The _Hominid::Campaign_ class provides methods for working with a campaigns.
-
-h4. Campaign Finder Methods
+We have provided some finder methods to make working with your campaigns easier:
 
-There are finder methods for campaigns as well. Refer to _Hominid::Campaign_ to see the other finders available.
+<pre><code>campaigns = h.campaigns
+campaigns = h.find_campaigns_by_list_name("Mailing List Name")
+campaigns = h.find_campaigns_by_list_id("Mailing List ID")
+campaigns = h.find_campaigns_by_type("regular")
+campaign = h.find_campaign_by_id("Campaign ID")
+campaign = h.find_campaign_by_title("Campaign Title")</code></pre>
 
-<pre><code>campaigns = Hominid::Campaign.all</code></pre>
+To create a new campaign, use the @create_campaign@ method:
 
-<pre><code>campaigns = Hominid::Campaign.find_by_list_name("List Name")</code></pre>
+<pre><code>new_campaign = h.create_campaign(...)</code></pre>
 
-h4. Creating a Campaign
+Take a look at @Hominid::Campaign@ to see the methods that are available for interacting with your campaigns.
 
-You can create new campaigns using Hominid as well. Please refer to the documentation in _Hominid::Base_ for more information about the options available when creating a new campaign.
+h3. Mailchimp Helper Methods
 
-<pre><code>new_campaign = Hominid::Campaign.create('regular', options, content, segment_opts, type_opts)</code></pre>
+There are a series of helper methods that are also made available with the Hominid gem. For example, to retrieve information about the Mailchimp account associated with your API key, simply:
 
-h4. Schedule a Campaign
+<pre><code>account_details_ = h.account_details</code></pre>
 
-As an example of how to work with a particular campaign, use the _Hominid::Campaign_ class. Extending from the previous example, since the _#create_campaign_ method returns the ID of the created campaign, we can use it to instantiate the _Hominid::Campaign_ class and schedule our new campaign to go be delivered 2 days from now:
+In this case, the @account_details@ object can be accessed like:
 
-<pre><code>campaign = Hominid::Campaign.new(:id => new_campaign)</code></pre>
+<pre><code>account_details.contact.company
+account_details.orders</code></pre>
 
-<pre><code>campaign.schedule_campaign(2.days.from_now)</code></pre>
+Take a look at @Hominid::Helper@ to see the helper methods that are available.
 
-h3. Helper Methods
+h3. Mailchimp Security Methods
 
-The _Hominid::Helper_ class provides a way to access the helper methods for the Mailchimp API. For example, to create a new folder for filing campaigns:
+There are a couple of security methods that are also made available with the Hominid gem. These are primarily used for dealing with API keys, and require your Mailchimp account username and password:
 
-<pre><code>folder = Hominid::Helper.create_folder("Folder Name")</code></pre>
+<pre><code>h.api_keys('username', 'password')</code></pre>
 
-h2. Syncing Your Application
-
-If you are integrating an application with Mailchimp, Hominid will provide a way for your app to connect with your Mailchimp account. However, it does not provide a way for Mailchimp to connect to your application, which is why Mailchimp has implemented "web hooks":http://www.mailchimp.com/api/webhooks/.
-
-The _Hominid::Webhook_ class helps with receiving <tt>POST</tt> data from a Mailchimp webhook:
-
-<pre><code>hook = Hominid::Webhook.new(params)
-case hook.event
-when "subscribe"
-  user = User.find_by_email(hook.email)
-  user.opted_in = true
-  user.save
-when "unsubscribe"
-  user = User.find_by_email(hook.email)
-  user.opted_in = false
-  user.save
-when "profile"
-  user = User.find_by_email(hook.email)
-  user.first_name = hook.first_name
-  user.last_name = hook.last_name
-  user.email_type = hook.email_type
-  user.save
-when "upemail"
-  user = User.find_by_email(hook.old_email)
-  user.email = hook.new_email
-  user.save
-end</code></pre>
+Take a look at @Hominid::Security@ to see the security methods that are available.
 
 h2. Contributors
 
@@ -146,6 +102,8 @@ Hominid is maintained by "Brian Getting":http://terra-firma-design.com. A very s
 * "Matthew Carlson":http://mandarinsoda.com/
 * "Kelly Mahan":http://digimedia.com/
 * "C.G. Brown":http://www.projectlocker.com/
+* "Bill Abney":http://github.com/babney
+* "David Rice":http://github.com/davidjrice
 
 h2. Note on Patches/Pull Requests
 
@@ -157,5 +115,4 @@ h2. Note on Patches/Pull Requests
 
 h2. Copyright
 
-Copyright (c) 2009 Brian Getting. See LICENSE for details.
-
+Copyright (c) 2009 Brian Getting. See LICENSE for details.

data/Rakefile

@@ -10,7 +10,6 @@ begin
     gem.email = "brian@terra-firma-design.com"
     gem.homepage = "http://github.com/bgetting/hominid"
     gem.authors = ["Brian Getting", "Michael Strüder"]
-    gem.add_development_dependency "shoulda"
   end
   Jeweler::GemcutterTasks.new
 rescue LoadError

data/VERSION

@@ -1 +1 @@
-2.0.1
+2.0.2

data/hominid.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = %q{hominid}
-  s.version = "2.0.1"
+  s.version = "2.0.2"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Brian Getting", "Michael Str\303\274der"]
-  s.date = %q{2009-11-11}
+  s.date = %q{2009-12-17}
   s.description = %q{Hominid is a Ruby gem that provides a wrapper for interacting with the Mailchimp email marketing service API.}
   s.email = %q{brian@terra-firma-design.com}
   s.extra_rdoc_files = [
@@ -23,14 +23,12 @@ Gem::Specification.new do |s|
      "Rakefile",
      "VERSION",
      "hominid.gemspec",
-     "hominid.yml.tpl",
      "lib/hominid.rb",
      "lib/hominid/base.rb",
      "lib/hominid/campaign.rb",
      "lib/hominid/helper.rb",
      "lib/hominid/list.rb",
-     "lib/hominid/webhook.rb",
-     "tasks/rails/hominid.rake",
+     "lib/hominid/security.rb",
      "test/hominid_test.rb",
      "test/test_helper.rb"
   ]
@@ -49,12 +47,9 @@ Gem::Specification.new do |s|
     s.specification_version = 3
 
     if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
-      s.add_development_dependency(%q<shoulda>, [">= 0"])
     else
-      s.add_dependency(%q<shoulda>, [">= 0"])
     end
   else
-    s.add_dependency(%q<shoulda>, [">= 0"])
   end
 end
 

data/lib/hominid.rb

@@ -11,26 +11,17 @@ module Hominid
       super("<#{error.faultCode}> #{error.message}")
     end
   end
-
-  class ListError < APIError
-  end
-
-  class ListEmailError < ListError
-  end
-
-  class ListMergeError < ListError
-  end
-
-  class AlreadySubscribed < ListEmailError
+  
+  class CampaignError < APIError
   end
-
-  class AlreadyUnsubscribed < ListEmailError
+  
+  class ListError < APIError
   end
-
-  class NotExists < ListEmailError
+  
+  class UserError < APIError
   end
-
-  class NotSubscribed < ListEmailError
+  
+  class ValidationError < APIError
   end
 
   class CommunicationError < StandardError
@@ -38,17 +29,11 @@ module Hominid
       super(message)
     end
   end
+  
 end
 
-begin
-  # include the provided rake task
-  require 'rake'
-  unless Rake::Task.task_defined? "hominid:config"
-    load File.join(File.dirname(__FILE__), '..', 'tasks', 'rails', 'hominid.rake')
-  end
-rescue LoadError
-  # silently skip rake task inclusion unless the rake gem is installed
-end
-
+require 'hominid/campaign'
+require 'hominid/helper'
+require 'hominid/list'
+require 'hominid/security'
 require 'hominid/base'
-

data/lib/hominid/base.rb

@@ -1,76 +1,55 @@
 module Hominid
   class Base
-
+    include Hominid::Campaign
+    include Hominid::Helper
+    include Hominid::List
+    include Hominid::Security
+    
     # MailChimp API Documentation: http://www.mailchimp.com/api/1.2/
     MAILCHIMP_API_VERSION = "1.2"
 
     def initialize(config = {})
-      if defined?(Rails.root) && (!config || config.empty?)
-        config = YAML.load(File.open("#{Rails.root}/config/hominid.yml"))[Rails.env].symbolize_keys
-      end
-      api_endpoint = config[:api_key].split('-').last
-      config.merge(:username => config[:username].to_s, :password => config[:password].to_s)
-      defaults = {:send_welcome       => false,
-                  :double_opt_in      => false,
-                  :update_existing    => true,
-                  :replace_interests  => true,
-                  :merge_tags         => {},
-                  :secure             => false}
+      raise StandardError.new('Please provide your Mailchimp API key.') unless config[:api_key]
+      dc = config[:api_key].split('-').last
+      defaults = {
+        :double_opt_in      => false,
+        :merge_tags         => {},
+        :replace_interests  => true,
+        :secure             => false,
+        :send_goodbye       => false,
+        :send_notify        => false,
+        :send_welcome       => false,
+        :update_existing    => true
+      }
       @config = defaults.merge(config).freeze
       if config[:secure]
-        @chimpApi = XMLRPC::Client.new2("https://#{api_endpoint}.api.mailchimp.com/#{MAILCHIMP_API_VERSION}/")
+        @chimpApi = XMLRPC::Client.new2("https://#{dc}.api.mailchimp.com/#{MAILCHIMP_API_VERSION}/")
       else
-        @chimpApi = XMLRPC::Client.new2("http://#{api_endpoint}.api.mailchimp.com/#{MAILCHIMP_API_VERSION}/")
+        @chimpApi = XMLRPC::Client.new2("http://#{dc}.api.mailchimp.com/#{MAILCHIMP_API_VERSION}/")
       end
     end
-
-    # Security related methods
+    
     # --------------------------------
-
-    def add_api_key
-      @chimpApi.call("apikeyAdd", *@config.values_at(:username, :password, :api_key))
-    end
-
-    def expire_api_key
-      @chimpApi.call("apikeyExpire", *@config.values_at(:username, :password, :api_key))
-    end
-
-    def api_keys(include_expired = false)
-      username, password = *@config.values_at(:username, :password)
-      @chimpApi.call("apikeys", username, password, include_expired)
-    end
-
     # Used internally by Hominid
     # --------------------------------
 
-    # handle common cases for which the Mailchimp API would raise Exceptions
-    def clean_merge_tags(merge_tags)
-      return {} unless merge_tags.is_a? Hash
-      merge_tags.each do |key, value|
-        if merge_tags[key].is_a? String
-          merge_tags[key] = value.gsub("\v", '')
-        elsif merge_tags[key].nil?
-          merge_tags[key] = ''
-        end
-      end
-    end
-
     def apply_defaults_to(options)
       @config.merge(options)
     end
-
+    
     def call(method, *args)
       @chimpApi.call(method, @config[:api_key], *args)
     rescue XMLRPC::FaultException => error
+      # Handle common cases for which the Mailchimp API would raise Exceptions
       case error.faultCode
-      when 230
-        raise AlreadySubscribed.new(error)
-      when 231
-        raise AlreadyUnsubscribed.new(error)
-      when 232
-        raise NotExists.new(error)
-      when 233, 215
-        raise NotSubscribed.new(error)
+      when 100..199
+        raise UserError.new(error)
+      when 200..299
+        raise ListError.new(error)
+      when 300..399
+        raise CampaignError.new(error)
+      when 500..599
+        raise ValidationError.new(error)
       else
         raise APIError.new(error)
       end
@@ -85,6 +64,33 @@ module Hominid
     rescue Exception => error
       raise CommunicationError.new(error.message)
     end
-  end
-end
+    
+    def clean_merge_tags(merge_tags)
+      return {} unless merge_tags.is_a? Hash
+      merge_tags.each do |key, value|
+        if merge_tags[key].is_a? String
+          merge_tags[key] = value.gsub("\v", '')
+        elsif merge_tags[key].nil?
+          merge_tags[key] = ''
+        end
+      end
+    end
+    
+    def hash_to_object(object)
+      return case object
+      when Hash
+        object = object.clone
+        object.each do |key, value|
+          object[key.downcase] = hash_to_object(value)
+        end
+        OpenStruct.new(object)
+      when Array
+        object = object.clone
+        object.map! { |i| hash_to_object(i) }
+      else
+        object
+      end
+    end
 
+  end
+end