babney-hominid 2.0.1

data/.gitignore

@@ -0,0 +1,4 @@
+.DS_Store
+pkg/*
+pkg/*.*
+.svn

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 Brian Getting
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.textile

@@ -0,0 +1,161 @@
+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/).
+
+h2. Installation
+
+<pre><code>sudo gem install hominid, :version => '>= 2.0.1', :source => "http://gemcutter.org"</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>
+
+h2. Configuration
+
+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.
+
+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
+
+There are finder methods for working with lists. Refer to _Hominid::List_ to see the other finders availables.
+
+<pre><code>lists = Hominid::List.all</code></pre>
+
+<pre><code>list = Hominid::List.find_by_name("List Name")</code></pre>
+
+<pre><code>list = Hominid::List.find(id_or_web_id)</code></pre>
+
+h4. Subscribing
+
+To subscribe a person or persons to a Mailchimp list:
+
+<pre><code>list.subscribe("sample@emailaddress.com")</code></pre>
+
+<pre><code>list.subscribe_many([{:EMAIL => 'sample@emailaddress.com', :EMAIL_TYPE => 'html'}, {:EMAIL => 'another@emailaddress.com', :EMAIL_TYPE => 'html'}])</code></pre>
+
+h4. Unsubscribing
+
+To unsubscribe a person or persons from a Mailchimp list:
+
+<pre><code>list.unsubscribe("sample@emailaddress.com")</code></pre>
+
+<pre><code>list.unsubscribe_many(['sample@emailaddress.com', 'another@emailaddress.com'])</code></pre>
+
+h4. Updating
+
+In the following example, we will be changing a person's email address on the Mailchimp list from @sample@ to @another@:
+
+<pre><code>list.update_member('sample@emailaddress.com', {:EMAIL => 'another@emailaddress.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@.
+
+h3. Working with Campaigns
+
+The _Hominid::Campaign_ class provides methods for working with a campaigns.
+
+h4. Campaign Finder Methods
+
+There are finder methods for campaigns as well. Refer to _Hominid::Campaign_ to see the other finders available.
+
+<pre><code>campaigns = Hominid::Campaign.all</code></pre>
+
+<pre><code>campaigns = Hominid::Campaign.find_by_list_name("List Name")</code></pre>
+
+h4. Creating a Campaign
+
+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.
+
+<pre><code>new_campaign = Hominid::Campaign.create('regular', options, content, segment_opts, type_opts)</code></pre>
+
+h4. Schedule a Campaign
+
+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:
+
+<pre><code>campaign = Hominid::Campaign.new(:id => new_campaign)</code></pre>
+
+<pre><code>campaign.schedule_campaign(2.days.from_now)</code></pre>
+
+h3. Helper 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:
+
+<pre><code>folder = Hominid::Helper.create_folder("Folder Name")</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>
+
+h2. Contributors
+
+Hominid is maintained by "Brian Getting":http://terra-firma-design.com. A very special thank-you to "Michael Strüder":http://github.com/mikezter for all of his hard work. Also, Hominid wouldn't be anywhere near as awesome as it is today without fantastic contributions and inspiration from:
+
+* "Alan Harper":http://github.com/aussiegeek
+* "Will":http://github.com/willinfront
+* "Ben Woosley":http://github.com/Empact
+* "banker":http://github.com/banker
+* "Kristoffer Renholm":http://github.com/renholm
+* "Wiktor Schmidt":http://github.com/netguru
+* "ron":http://github.com/ron
+* "Matthew Carlson":http://mandarinsoda.com/
+* "Kelly Mahan":http://digimedia.com/
+* "C.G. Brown":http://www.projectlocker.com/
+
+h2. Note on Patches/Pull Requests
+
+# Fork the project.
+# Make your feature addition or bug fix.
+# Add tests for it. This is important so I don't break it in a future version unintentionally.
+# Commit, do not mess with rakefile, version, or history. (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
+# Send me a pull request. Bonus points for topic branches.
+
+h2. Copyright
+
+Copyright (c) 2009 Brian Getting. See LICENSE for details.
+

data/Rakefile

@@ -0,0 +1,57 @@
+require 'rubygems'
+require 'rake'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "babney-hominid"
+    gem.summary = %Q{Hominid is a Ruby gem for interacting with the Mailchimp API.}
+    gem.description = %Q{Hominid is a Ruby gem that provides a wrapper for interacting with the Mailchimp email marketing service API.}
+    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
+  puts "Jeweler (or a dependency) not available. Install it with: sudo gem install jeweler"
+end
+
+require 'rake/testtask'
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'lib' << 'test'
+  test.pattern = 'test/**/*_test.rb'
+  test.verbose = true
+end
+
+begin
+  require 'rcov/rcovtask'
+  Rcov::RcovTask.new do |test|
+    test.libs << 'test'
+    test.pattern = 'test/**/*_test.rb'
+    test.verbose = true
+  end
+rescue LoadError
+  task :rcov do
+    abort "RCov is not available. In order to run rcov, you must: sudo gem install spicycode-rcov"
+  end
+end
+
+task :test => :check_dependencies
+
+task :default => :test
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  if File.exist?('VERSION')
+    version = File.read('VERSION')
+  else
+    version = ""
+  end
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "hominid #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+

data/VERSION

@@ -0,0 +1 @@
+2.0.1

data/hominid.gemspec

@@ -0,0 +1,60 @@
+# Generated by jeweler
+# DO NOT EDIT THIS FILE DIRECTLY
+# Instead, edit Jeweler::Tasks in Rakefile, and run the gemspec command
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{hominid}
+  s.version = "2.0.1"
+
+  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.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 = [
+    "LICENSE",
+     "README.textile"
+  ]
+  s.files = [
+    ".gitignore",
+     "LICENSE",
+     "README.textile",
+     "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",
+     "test/hominid_test.rb",
+     "test/test_helper.rb"
+  ]
+  s.homepage = %q{http://github.com/bgetting/hominid}
+  s.rdoc_options = ["--charset=UTF-8"]
+  s.require_paths = ["lib"]
+  s.rubygems_version = %q{1.3.5}
+  s.summary = %q{Hominid is a Ruby gem for interacting with the Mailchimp API.}
+  s.test_files = [
+    "test/hominid_test.rb",
+     "test/test_helper.rb"
+  ]
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    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/hominid.yml.tpl

@@ -0,0 +1,25 @@
+# Get your API key at http://admin.mailchimp.com/account/api/
+
+development:
+  username:
+  password: 
+  api_key: 
+  send_goodbye: false
+  send_notify: false
+  double_opt_in: false
+
+test:
+  username:
+  password:
+  api_key: 
+  send_goodbye: false
+  send_notify: false
+  double_opt_in: false
+
+production:
+  username:
+  password:
+  api_key: 
+  send_goodbye: false
+  send_notify: false
+  double_opt_in: false

data/lib/hominid.rb

@@ -0,0 +1,54 @@
+require 'xmlrpc/client'
+require 'ostruct'
+
+module Hominid
+
+  class StandardError < ::StandardError
+  end
+
+  class APIError < StandardError
+    def initialize(error)
+      super("<#{error.faultCode}> #{error.message}")
+    end
+  end
+
+  class ListError < APIError
+  end
+
+  class ListEmailError < ListError
+  end
+
+  class ListMergeError < ListError
+  end
+
+  class AlreadySubscribed < ListEmailError
+  end
+
+  class AlreadyUnsubscribed < ListEmailError
+  end
+
+  class NotExists < ListEmailError
+  end
+
+  class NotSubscribed < ListEmailError
+  end
+
+  class CommunicationError < StandardError
+    def initialize(message)
+      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/base'
+

data/lib/hominid/base.rb

@@ -0,0 +1,90 @@
+module Hominid
+  class Base
+
+    # 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}
+      @config = defaults.merge(config).freeze
+      if config[:secure]
+        @chimpApi = XMLRPC::Client.new2("https://#{api_endpoint}.api.mailchimp.com/#{MAILCHIMP_API_VERSION}/")
+      else
+        @chimpApi = XMLRPC::Client.new2("http://#{api_endpoint}.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
+      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)
+      else
+        raise APIError.new(error)
+      end
+    rescue RuntimeError => error
+      if error.message =~ /Wrong type NilClass\. Not allowed!/
+        hashes = args.select{|a| a.is_a? Hash}
+        errors = hashes.select{|k, v| v.nil? }.collect{ |k, v| "#{k} is Nil." }.join(' ')
+        raise CommunicationError.new(errors)
+      else
+        raise error
+      end
+    rescue Exception => error
+      raise CommunicationError.new(error.message)
+    end
+  end
+end
+

data/lib/hominid/campaign.rb

@@ -0,0 +1,172 @@
+module Hominid
+
+  class Campaign < Base
+
+    # Campaign related methods
+    # --------------------------------
+
+    attr_reader :campaign_id
+    attr_reader :attributes
+
+    def initialize(*args)
+      options = args.last.is_a?(Hash) ? args.last : {}
+      raise StandardError.new('Please provide a Campaign ID.') unless options[:id]
+      @campaign_id = options.delete(:id)
+      @attributes = options.delete(:attributes)
+      super(options)
+    end
+
+    def self.all
+      # Get all campaigns for this mailchimp account
+      new(:id => 0).call("campaigns").to_a.collect { |c| Campaign.new(:id => c.delete('id'), :attributes => c) }
+    end
+
+    def self.find_by_list_name(list_name)
+      new(:id => 0).call("campaigns", {:list_id => List.find_by_name(list_name).list_id}).to_a.collect { |c| Campaign.new(:id=> c.delete('id'), :attributes => c) }
+    end
+
+    def self.find_by_list_id(list_id)
+      # Find all campaigns for the given list
+      new(:id => 0).call("campaigns", {:list_id => list_id}).to_a.collect { |c| Campaign.new(:id=> c.delete('id'), :attributes => c) }
+    end
+
+    def self.find_by_title(title)
+      # Find campaign by title
+      all.find { |c| c.attributes['title'] =~ /#{title}/ }
+    end
+
+    def self.find_by_type(type)
+      # Find campaign by type. Possible choices are:
+      #   'regular'
+      #   'plaintext'
+      #   'absplit'
+      #   'rss'
+      #   'inspection'
+      #   'trans'
+      #   'auto'
+      all.find { |campaign| campaign.attributes['type'] =~ /#{type}/ }
+    end
+
+    def self.find_by_web_id(web_id)
+      # Find campaigns by web_id
+      all.find { |campaign| campaign.attributes['web_id'] == web_id.to_i }
+    end
+
+    def self.find_by_id(id)
+      # Find campaign by id
+      all.find { |campaign| (campaign.campaign_id == id.to_s) }
+    end
+
+    def self.find(id_or_web_id)
+      # Campaign finder method
+      all = self.all
+      campaign = self.find_by_id(id_or_web_id.to_s).to_a + self.find_by_web_id(id_or_web_id.to_i).to_a
+      return campaign.blank? ? nil : campaign.first
+    end
+
+    def self.create(type = 'regular', options = {}, content = {}, segment_options = {}, type_opts = {})
+      # Create a new campaign
+      # The options hash should be structured as follows:
+      #
+      #   :list_id        = (string)  The ID of the list to send this campaign to.
+      #   :subject        = (string)  The subject of the campaign.
+      #   :from_email     = (string)  The email address this campaign will come from.
+      #   :from_name      = (string)  The name that this campaign will come from.
+      #   :to_email       = (string)  The To: name recipients will see.
+      #   :template_id    = (integer) The ID of the template to use for this campaign (optional).
+      #   :folder_id      = (integer) The ID of the folder to file this campaign in (optional).
+      #   :tracking       = (array)   What to track for this campaign (optional).
+      #   :title          = (string)  Internal title for this campaign (optional).
+      #   :authenticate   = (boolean) Set to true to authenticate campaign (optional).
+      #   :analytics      = (array)   Google analytics tags (optional).
+      #   :auto_footer    = (boolean) Auto-generate the footer (optional)?
+      #   :inline_css     = (boolean) Inline the CSS styles (optional)?
+      #   :generate_text  = (boolean) Auto-generate text from HTML email (optional)?
+      #
+      # Visit http://www.mailchimp.com/api/1.2/campaigncreate.func.php for more information about creating
+      # campaigns via the API.
+      #
+      new(:id => 0).call("campaignCreate", type, options, content, segment_options, type_opts)
+      ## TODO: Return the new campaign with the ID returned from the API
+    end
+
+    def self.templates
+      # Get the templates for this account
+      new(:id => 0).call("campaignTemplates")
+    end
+
+    def add_order(order)
+      # Attach Ecommerce Order Information to a campaign.
+      # The order hash should be structured as follows:
+      #
+      #   :id             = (string)  the order id
+      #   :email_id       = (string)  email id of the subscriber (mc_eid query string)
+      #   :total          = (double)  Show only campaigns with this from_name.
+      #   :shipping       = (string)  *optional - the total paid for shipping fees.
+      #   :tax            = (string)  *optional - the total tax paid.
+      #   :store_id       = (string)  a unique id for the store sending the order in
+      #   :store_name     = (string)  *optional - A readable name for the store, typicaly the hostname.
+      #   :plugin_id      = (string)  the MailChimp-assigned Plugin Id. Using 1214 for the moment.
+      #   :items          = (array)   the individual line items for an order, using the following keys:
+      #
+      #     :line_num      = (integer) *optional - line number of the item on the order
+      #     :product_id    = (integer) internal product id
+      #     :product_name  = (string)  the name for the product_id associated with the item
+      #     :category_id   = (integer) internal id for the (main) category associated with product
+      #     :category_name = (string)  the category name for the category id
+      #     :qty           = (double)  the quantity of items ordered
+      #     :cost          = (double)  the cost of a single item (i.e., not the extended cost of the line)
+      order = order.merge(:campaign_id => @campaign_id)
+      call("campaignEcommAddOrder", order)
+    end
+
+    def campaign_stats()
+      # Get the stats of a campaign
+      call("campaignStats", @campaign_id)
+    end
+
+    # Get the HTML & text content for a campaign
+    # :for_archive        = (boolean) default true, true returns the content as it would appear in the archive, false returns the raw HTML/text
+    def campaign_content(for_archive = true)
+      # Get the content of a campaign
+      call("campaignContent", @campaign_id, for_archive)
+    end
+
+    def delete_campaign()
+      # Delete a campaign
+      call("campaignDelete", @campaign_id)
+    end
+
+    def replicate_campaign()
+      # Replicate a campaign (returns ID of new campaign)
+      call("campaignReplicate", @campaign_id)
+    end
+
+    def schedule_campaign(time = "#{1.day.from_now}")
+      # Schedule a campaign
+      ## TODO: Add support for A/B Split scheduling
+      call("campaignSchedule", @campaign_id, time)
+    end
+
+    def send_now()
+      # Send a campaign
+      call("campaignSendNow", @campaign_id)
+    end
+
+    # Send a test of a campaign
+    def send_test(emails = {})
+      call("campaignSendTest", @campaign_id, emails)
+    end
+
+    def update(name, value)
+      # Update a campaign
+      call("campaignUpdate", @campaign_id, name, value)
+    end
+
+    def unschedule()
+      # Unschedule a campaign
+      call("campaignUnschedule", @campaign_id)
+    end
+  end
+end
+

data/lib/hominid/helper.rb

@@ -0,0 +1,45 @@
+module Hominid
+
+  class Helper < Base
+    
+    # Helper methods
+    # --------------------------------
+    
+    def self.account_details(options = {})
+      # Get details for this account.
+      new(options).call("getAccountDetails")
+    end
+    
+    def self.convert_css_to_inline(html, strip_css = false, options = {})
+      # Convert CSS styles to inline styles and (optionally) remove original styles
+      new.call("inlineCss", html, strip_css)
+    end
+    
+    def self.create_folder(name, options = {})
+      # Create a new folder to file campaigns in
+      new(options).call("createFolder", name)
+    end
+    
+    def self.generate_text(type, content, options = {})
+      # Have HTML content auto-converted to a text-only format.
+      # The options for text type are:
+      #   'html'      => Expects a string of HTML(default).
+      #   'template'  => Expects an array.
+      #   'url'       => Expects a valid and public URL.
+      #   'cid'       => Expects a campaign ID.
+      #   'tid'       => Expects a template ID.
+      new(options).call("generateText", type, content)
+    end
+    
+    def self.html_to_text(content, options = {})
+      # Convert HTML content to text
+      new(options).call("generateText", 'html', content)
+    end
+    
+    def self.ping(options = {})
+      # Ping the Mailchimp API
+      new(options).call("ping")
+    end
+    
+  end
+end

data/lib/hominid/list.rb

@@ -0,0 +1,150 @@
+module Hominid
+
+  class List < Base
+
+    # List related methods
+    # --------------------------------
+
+    attr_reader :list_id
+    attr_reader :attributes
+
+    def initialize(*args)
+      options = args.last.is_a?(Hash) ? args.last : {}
+      raise StandardError.new('Please provide a List ID.') unless options[:id]
+      @list_id = options.delete(:id)
+      @attributes = options.delete(:attributes)
+      super(options)
+    end
+
+    def self.all
+      # Get all lists for this mailchimp account
+      new(:id => 0).call("lists").to_a.collect { |list| List.new(:id => list.delete('id'), :attributes => list) }
+    end
+
+    def self.find_by_name(name)
+      # Find list by name
+      all.find { |list| list.attributes['name'] =~ /#{name}/ }
+    end
+
+    def self.find_by_web_id(web_id)
+      # Find list by name
+      all.find { |list| (list.attributes['web_id'] == web_id.to_i) }
+    end
+
+    def self.find_by_id(id)
+      # Find list by id
+      all.find { |list| (list.list_id == id.to_s) }
+    end
+
+    def self.find(id_or_web_id)
+      # List finder method
+      all = self.all
+      list = self.find_by_id(id_or_web_id.to_s).to_a + self.find_by_web_id(id_or_web_id.to_i).to_a
+      return list.blank? ? nil : list.first
+    end
+
+    def create_group(group)
+      # Add an interest group to a list
+      call("listInterestGroupAdd", @list_id, group)
+    end
+    alias :interest_group_add :create_group
+
+    def create_tag(tag, name, required = false)
+      # Add a merge tag to a list
+      call("listMergeVarAdd", @list_id, tag, name, required)
+    end
+    alias :merge_var_add :create_tag
+
+    def delete_group(group)
+      # Delete an interest group for a list
+      call("listInterestGroupDel", @list_id, group)
+    end
+    alias :interest_group_del :delete_group
+
+    def delete_tag(tag)
+      # Delete a merge tag and all its members
+      call("listMergeVarDel", @list_id, tag)
+    end
+    alias :merge_var_del :delete_tag
+
+    def groups()
+      # Get the interest groups for a list
+      call("listInterestGroups", @list_id)
+    end
+    alias :interest_groups :groups
+
+
+    def member_info(email)
+      # Get a member of a list
+      call("listMemberInfo", @list_id, email)
+    end
+
+    def members(status = "subscribed", since = "2000-01-01 00:00:00", start = 0, limit = 100)
+      # Get members of a list based on status
+      # Select members based on one of the following statuses:
+      #   'subscribed'
+      #   'unsubscribed'
+      #   'cleaned'
+      #   'updated'
+      #
+      # Select members that have updated their status or profile by providing
+      # a "since" date in the format of YYYY-MM-DD HH:MM:SS
+      call("listMembers", @list_id, status, since, start, limit)
+    end
+
+    def merge_tags()
+      # Get the merge tags for a list
+      call("listMergeVars", @list_id)
+    end
+    alias :merge_vars :merge_tags
+
+    def subscribe(email, options = {})
+      # Subscribe a member to this list
+      merge_tags = clean_merge_tags options[:merge_tags]
+      options = apply_defaults_to({:email_type => "html"}.merge(options))
+      call(
+        "listSubscribe",
+        @list_id,
+        email,
+        merge_tags,
+        *options.values_at(
+          :email_type,
+          :double_opt_in,
+          :update_existing,
+          :replace_interests,
+          :send_welcome
+        )
+      )
+    end
+
+    def subscribe_many(subscribers, options = {})
+      # Subscribe an array of email addresses
+      # subscribers(array) = [{:EMAIL => 'example@email.com', :EMAIL_TYPE => 'html'}]
+      subscribers = subscribers.collect { |subscriber| clean_merge_tags(subscriber) }
+      options = apply_defaults_to({:update_existing => true}.merge(options))
+      call("listBatchSubscribe", @list_id, subscribers, *options.values_at(:double_opt_in, :update_existing, :replace_interests))
+    end
+    alias :batch_subscribe :subscribe_many
+
+    def unsubscribe(current_email, options = {})
+      # Unsubscribe a list member
+      options = apply_defaults_to({:delete_member => true}.merge(options))
+      call("listUnsubscribe", @list_id, current_email, *options.values_at(:delete_member, :send_goodbye, :send_notify))
+    end
+
+    def unsubscribe_many(emails, options = {})
+      # Unsubscribe an array of email addresses
+      # emails(array) = ['first@email.com', 'second@email.com']
+      options = apply_defaults_to({:delete_member => true}.merge(options))
+      call("listBatchUnsubscribe", @list_id, emails, *options.values_at(:delete_member, :send_goodbye, :send_notify))
+    end
+    alias :batch_unsubscribe :unsubscribe_many
+
+    def update_member(current_email, merge_tags = {}, email_type = "html", replace_interests = true)
+      # Update a member of this list
+      call("listUpdateMember", @list_id, current_email, merge_tags, email_type, replace_interests)
+    end
+
+  end
+end
+

data/lib/hominid/webhook.rb

@@ -0,0 +1,131 @@
+module Hominid
+
+  class Webhook < Base
+    # Expects a hash of POST data generated from Mailchimp:
+    #
+    # "type": "unsubscribe", 
+    # "fired_at": "2009-03-26 21:54:00", 
+    # "data[email]": "sample@emailaddress.com"
+    #
+    # Simple Usage:
+    #
+    # h = Hominid::Webhook.new(params)
+    #
+    # Sample params from Mailchimp webhook:
+    # params => { "type" => "subscribe",
+    #             "fired_at" => "2009-03-26 21:35:57",
+    #             "data" => { "id" => "8a25ff1d98",
+    #                         "list_id" => "8a25ff1d98",
+    #                         "email" => "api@mailchimp.com",
+    #                         "email_type" => "html",
+    #                         "merges" => {"EMAIL" => "api@mailchimp.com",
+    #                                     "FNAME" => "Brian",
+    #                                     "LNAME" => "Getting",
+    #                                     "INTERESTS" => "Group1,Group2"},
+    #                         "ip_opt" => "10.20.10.30",
+    #                         "ip_signup" => "10.20.10.30" }}
+    #
+    # Returns an object with the following methods (NOTE: Not all methods are available
+    # for all event types. Refer to http://www.mailchimp.com/api/webhooks/ for information
+    # on what data will be available for each event):
+    # 
+    # h.event               <= (String)     The event that fired the request. Possible events are:
+    #                                       "subscribe", "unsubscribe", "profile", "upemail", "cleaned"
+    # h.fired_at            <= (Datetime)   When the webhook request was fired.
+    # h.id                  <= (String)     The ID of the webhook request.
+    # h.list_id             <= (String)     The ID of the list that generated the request.
+    # h.email               <= (String)     The email address of the subscriber that generated the request.
+    # h.email_type          <= (String)     The email type of the subscriber that generated the request.
+    # h.first_name          <= (String)     The first name of the subscriber (if available).
+    # h.last_name           <= (String)     The first name of the subscriber (if available).
+    # h.interests           <= (Array)      An array of the interest groups.
+    # h.ip_opt              <= (String)     The opt in IP address.
+    # h.ip_signup           <= (String)     The signup IP address.
+    #
+    
+    attr_reader :request
+    
+    def initialize(*args)
+      post_data = args.last
+      raise HominidError.new('Please provide the POST data from a Mailchimp webhook request.') unless post_data.is_a?(Hash)
+      post_data.merge!({"event" => "#{post_data.delete('type')}"})
+      @request = hash_to_object(post_data)
+    end
+    
+    
+    def email
+      self.request.data.email if self.request.data.email
+    end
+    
+    def email_type
+      self.request.data.email_type if self.request.data.email_type
+    end
+    
+    def event
+      self.request.event if self.request.event
+    end
+    
+    def fired_at
+      self.request.fired_at.to_datetime if self.request.fired_at
+    end
+    
+    def first_name
+      self.request.data.merges.fname if self.request.data.merges.fname
+    end
+    
+    def last_name
+      self.request.data.merges.lname if self.request.data.merges.lname
+    end
+    
+    def id
+      self.request.data.id if self.request.data.id
+    end
+    
+    def interests
+      self.request.data.merges.interests.split(',') if self.request.data.merges.interests
+    end
+    
+    def ip_opt
+      self.request.data.ip_opt if self.request.data.ip_opt
+    end
+    
+    def ip_signup
+      self.request.data.ip_signup if self.request.data.ip_signup
+    end
+    
+    def list_id
+      self.request.data.list_id if self.request.data.list_id
+    end
+    
+    def new_email
+      self.request.data.new_email if self.request.data.new_email
+    end
+    
+    def old_email
+      self.request.data.old_email if self.request.data.old_email
+    end
+    
+    def reason
+      self.request.data.reason if self.request.data.reason
+    end
+    
+    private
+
+    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

data/tasks/rails/hominid.rake

@@ -0,0 +1,22 @@
+require 'rake'
+namespace :hominid do
+  # Task to create the config file
+  desc "Generate a Hominid config file"
+  task :config => :environment do |t|
+    require 'fileutils'
+    if defined?(Rails.root)
+      config_file = File.join(Rails.root, 'config', 'hominid.yml')
+      template_file = File.join(File.dirname(__FILE__), '..', '..', 'hominid.yml.tpl')
+      unless File.exists? config_file
+        FileUtils.cp(
+          File.join(File.dirname(__FILE__), '..', '..', 'hominid.yml.tpl'),
+          File.join(Rails.root, 'config', 'hominid.yml')
+        )
+        puts 'Please edit config/hominid.yml to your needs.'
+      else
+        puts 'We left your existing config/hominid.yml untouched.'
+      end
+    end
+  end
+end
+

data/test/hominid_test.rb

@@ -0,0 +1,7 @@
+require 'test_helper'
+
+class HominidTest < Test::Unit::TestCase
+  should "probably rename this file and start testing for real" do
+    flunk "hey buddy, you should probably rename this file and start testing for real"
+  end
+end

data/test/test_helper.rb

@@ -0,0 +1,10 @@
+require 'rubygems'
+require 'test/unit'
+require 'shoulda'
+
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+$LOAD_PATH.unshift(File.dirname(__FILE__))
+require 'hominid'
+
+class Test::Unit::TestCase
+end

metadata

@@ -0,0 +1,82 @@
+--- !ruby/object:Gem::Specification 
+name: babney-hominid
+version: !ruby/object:Gem::Version 
+  version: 2.0.1
+platform: ruby
+authors: 
+- Brian Getting
+- "Michael Str\xC3\xBCder"
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-11-18 00:00:00 -08:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: shoulda
+  type: :development
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+    version: 
+description: Hominid is a Ruby gem that provides a wrapper for interacting with the Mailchimp email marketing service API.
+email: brian@terra-firma-design.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- LICENSE
+- README.textile
+files: 
+- .gitignore
+- LICENSE
+- README.textile
+- 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
+- test/hominid_test.rb
+- test/test_helper.rb
+has_rdoc: true
+homepage: http://github.com/bgetting/hominid
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --charset=UTF-8
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.5
+signing_key: 
+specification_version: 3
+summary: Hominid is a Ruby gem for interacting with the Mailchimp API.
+test_files: 
+- test/hominid_test.rb
+- test/test_helper.rb