hominid 1.2.1

data/MIT-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,76 @@
+h1. Hominid
+
+Hominid is a Ruby gem for interacting with the "Mailchimp API":http://www.mailchimp.com/api/1.2/.
+
+h2. Installation
+
+Install the gem:
+
+<pre><code>sudo gem install hominid</code></pre>
+
+In your @environment.rb@ file:
+
+<pre><code>config.gem "hominid"</code></pre>
+
+You can also install Hominid as a Rails plugin:
+
+<pre><code>script/plugin install git://github.com/bgetting/hominid.git</code></pre>
+
+h2. Setup
+
+Hominid expects to find a config file at @/config/hominid.yml@ in a Rails application, but you can also pass a hash of config options when creating a new Hominid object (thanks to "ron":http://github.com/ron).
+
+You will also need to create a Mailchimp account to get your API key (available at "http://admin.mailchimp.com/account/api/":http://admin.mailchimp.com/account/api/) to configure a Hominid object. 
+
+h2. Example
+
+To interact with the Mailchimp API, simply create a new Hominid object:
+
+<pre><code>@hominid = Hominid.new</code></pre>
+
+_or_
+
+<pre><code>@hominid = Hominid.new({:username => 'USERNAME', :password => 'PASSWORD', :api_key => 'API_KEY', :send_goodbye => false, :send_notify => false, :double_opt => false})</code></pre>
+
+You will need to have the @list ID@ of the mailing list you want to work with. You can find the @list ID@ of a list by:
+
+<pre><code>
+def find_list_id(list_name)
+  mailing_lists = @hominid.lists
+  unless mailing_lists.nil?
+    @list_id = mailing_lists.find {|list| list["name"] == list_name}["id"]
+  end
+end
+</code></pre>
+
+To subscribe:
+
+<pre><code>@hominid.subscribe(@list_id, "email@example.com", :user_info => {:FNAME => 'Bob', :LNAME => 'Smith'}, :email_type => 'html')</code></pre>
+
+To unsubscribe:
+
+<pre><code>@hominid.unsubscribe(@list_id, "email@example.com")</code></pre>
+
+To update a member:
+
+<pre><code>@hominid.subscribe(@list_id, "email@example.com", :user_info => {:FNAME => 'Robert', :EMAIL => 'another@example.com'}, :email_type => 'html', :update_existing => true)</code></pre>
+
+_or_
+
+<pre><code>@hominid.update_member(@list_id, "email@example.com", {:FNAME => 'Robert', :EMAIL => 'another@example.com'})</code></pre>
+
+Campaign methods are also supported. You can get all the campaigns for a particular list by:
+
+<pre><code>@hominid.campaigns(@list_id)</code></pre>
+
+Leave the @@list_id@ out and it will return all the campaigns for your Mailchimp account.
+
+h2. Other Stuff
+
+For the most part, this whole thing was an attempt to optimize the acts_as_mailchimp plugin, and incorporates all the great work from "C.G. Brown":http://www.projectlocker.com/ and "Kelly Mahan":http://digimedia.com/, as well as "Matthew Carlson":http://mandarinsoda.com/, whose plugin inspired nearly all of this work. Recently, "ron":http://github.com/ron and "netguru":http://github.com/netguru have also provided useful changes as well.
+
+I encourage anyone using this gem to please fork it, improve it, and send me a pull request. I typically only use this gem in a minimal capacity, primarily for just managing whether or not a user is signed up for a mailing list. I do not intend to continue maintaining the "Acts As Mailchimp":http://github.com/bgetting/acts_as_mailchimp in the future, since I personally prefer to just use the Hominid gem.
+
+So please, help us to improve this gem!
+
+Copyright (c) 2009 Brian Getting, released under the MIT license.

data/Rakefile

@@ -0,0 +1,28 @@
+require 'rake'
+require 'rake/rdoctask'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |s|
+    s.name = "hominid"
+    s.summary = "Hominid is a Ruby gem for interacting with the Mailchimp API."
+    s.email = "brian@terra-firma-design.com"
+    s.homepage = "http://terra-firma-design.com"
+    s.description = "Use the hominid gem to easily integrate with the Mailchimp email marketing service API."
+    s.authors = ["Brian Getting"]
+  end
+  
+  Jeweler::GemcutterTasks.new
+  
+rescue LoadError
+  puts "Jeweler not available. Install it with: sudo gem install technicalpickles-jeweler -s http://gems.github.com"
+end
+
+desc 'Generate documentation for the hominid plugin.'
+Rake::RDocTask.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'Hominid'
+  rdoc.options << '--line-numbers' << '--inline-source'
+  rdoc.rdoc_files.include('README')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/VERSION.yml

@@ -0,0 +1,4 @@
+--- 
+:major: 1
+:minor: 2
+:patch: 1

data/hominid.gemspec

@@ -0,0 +1,53 @@
+# Generated by jeweler
+# DO NOT EDIT THIS FILE
+# Instead, edit Jeweler::Tasks in Rakefile, and run `rake gemspec`
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{hominid}
+  s.version = "1.2.1"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Brian Getting"]
+  s.date = %q{2009-10-13}
+  s.description = %q{Use the hominid gem to easily integrate with the Mailchimp email marketing service API.}
+  s.email = %q{brian@terra-firma-design.com}
+  s.extra_rdoc_files = [
+    "README.textile"
+  ]
+  s.files = [
+    "MIT-LICENSE",
+     "README.textile",
+     "Rakefile",
+     "VERSION.yml",
+     "hominid.gemspec",
+     "hominid.yml.tpl",
+     "init.rb",
+     "install.rb",
+     "lib/hominid.rb",
+     "pkg/hominid-1.2.1.gem",
+     "rails/init.rb",
+     "spec/hominid_spec.rb",
+     "spec/spec_helper.rb",
+     "uninstall.rb"
+  ]
+  s.homepage = %q{http://terra-firma-design.com}
+  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 = [
+    "spec/hominid_spec.rb",
+     "spec/spec_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
+    else
+    end
+  else
+  end
+end

data/hominid.yml.tpl

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

data/init.rb

@@ -0,0 +1 @@
+require File.dirname(__FILE__) + "/rails/init"

data/install.rb

@@ -0,0 +1,4 @@
+require 'fileutils'
+monkeyBrains = File.dirname(__FILE__) + '/../../../config/hominid.yml'
+FileUtils.cp File.dirname(__FILE__) + '/hominid.yml.tpl', monkeyBrains unless File.exist?(monkeyBrains)
+puts IO.read(File.join(File.dirname(__FILE__), 'README'))

data/lib/hominid.rb

@@ -0,0 +1,265 @@
+require 'xmlrpc/client'
+
+class HominidError < RuntimeError
+  def initialize(message)
+    super(message)
+  end
+end
+
+class HominidCommunicationError < HominidError
+  def initialize(message)
+    super(message)
+  end
+end
+
+class Hominid
+  
+  # MailChimp API Documentation: http://www.mailchimp.com/api/1.2/
+  MAILCHIMP_API = "http://api.mailchimp.com/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
+    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, :user_info => {}}
+    @config = defaults.merge(config).freeze
+    @chimpApi = XMLRPC::Client.new2(MAILCHIMP_API)
+  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
+  
+  ## Campaign related methods
+  
+  def campaign_stats(campaign_id)
+    # Get the stats of a campaign
+    call("campaignStats", campaign_id)
+  end
+  
+  def campaign_content(campaign_id, for_archive = true)
+    # Get the content of a campaign
+    #
+    # for_archive controls whether we return the Archive version (true) or the Raw version (false), defaults to true
+    call("campaignContent", campaign_id, for_archive)
+  end
+  
+  def campaigns(filters = {}, start = 0, limit = 50)
+    # Get the campaigns for this account
+    # API Version 1.2 requires that filters be sent as a hash
+    # Available options for the filters hash are:
+    #
+    #   :campaign_id    = (string)  The ID of the campaign you wish to return. 
+    #   :list_id        = (string)  Show only campaigns with this list_id. 
+    #   :folder_id      = (integer) Show only campaigns from this folder.
+    #   :from_name      = (string)  Show only campaigns with this from_name.
+    #   :from_email     = (string)  Show only campaigns with this from_email.
+    #   :title          = (string)  Show only campaigns with this title.
+    #   :subject        = (string)  Show only campaigns with this subject.
+    #   :sedtime_start  = (string)  Show campaigns sent after YYYY-MM-DD HH:mm:ss.
+    #   :sendtime_end   = (string)  Show campaigns sent before YYYY-MM-DD HH:mm:ss.
+    #   :subject        = (boolean) Filter by exact values, or search within content for filter values.
+    call("campaigns", filters, start, limit)
+  end
+
+  # Attach Ecommerce Order Information to a Campaign.
+  # The order hash should be structured as follows: 
+  #
+  #   :id             = (string)  the order id 
+  #   :campaign_id    = (string)  the campaign id to track the order (mc_cid query string). 
+  #   :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)
+  def campaign_ecomm_add_order(order)
+    call("campaignEcommAddOrder", order)
+  end
+
+  def create_campaign(type = 'regular', options = {}, content = {}, segment_options = {}, type_opts = {})
+    # Create a new campaign
+    call("campaignCreate", type, options, content, segment_options, type_opts)
+  end
+  
+  def delete_campaign(campaign_id)
+    # Delete a campaign
+    call("campaignDelete", campaign_id)
+  end
+  
+  def replicate_campaign(campaign_id)
+    # Replicate a campaign (returns ID of new campaign)
+    call("campaignReplicate", campaign_id)
+  end
+  
+  def schedule_campaign(campaign_id, 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(campaign_id)
+    # Send a campaign
+    call("campaignSendNow", campaign_id)
+  end
+  
+  def send_test(campaign_id, emails = {})
+    # Send a test of a campaign
+    call("campaignSendTest", campaign_id, emails)
+  end
+  
+  def templates
+    # Get the templates
+    call("campaignTemplates")
+  end
+  
+  def update_campaign(campaign_id, name, value)
+    # Update a campaign
+    call("campaignUpdate", campaign_id, name, value)
+  end
+  
+  def unschedule_campaign(campaign_id)
+    # Unschedule a campaign
+    call("campaignUnschedule", campaign_id)
+  end
+  
+  ## Helper methods
+  
+  def html_to_text(content)
+    # Convert HTML content to text
+    call("generateText", 'html', content)
+  end
+  
+  def convert_css_to_inline(html, strip_css = false)
+    # Convert CSS styles to inline styles and (optionally) remove original styles
+    call("inlineCss", html, strip_css)
+  end
+  
+  ## List related methods
+  
+  def lists
+    # Get all of the lists for this mailchimp account
+    call("lists")
+  end
+  
+  def create_group(list_id, group)
+    # Add an interest group to a list
+    call("listInterestGroupAdd", list_id, group)
+  end
+  
+  def create_tag(list_id, tag, name, required = false)
+    # Add a merge tag to a list
+    call("listMergeVarAdd", list_id, tag, name, required)
+  end
+  
+  def delete_group(list_id, group)
+    # Delete an interest group for a list
+    call("listInterestGroupDel", list_id, group)
+  end
+  
+  def delete_tag(list_id, tag)
+    # Delete a merge tag and all its members
+    call("listMergeVarDel", list_id, tag)
+  end
+  
+  def groups(list_id)
+    # Get the interest groups for a list
+    call("listInterestGroups", list_id)
+  end
+  
+  def member(list_id, email)
+    # Get a member of a list
+    call("listMemberInfo", list_id, email)
+  end
+  
+  def members(list_id, 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(list_id)
+    # Get the merge tags for a list
+    call("listMergeVars", list_id)
+  end
+  
+  def subscribe(list_id, email, options = {})
+    options = apply_defaults_to({:email_type => "html"}.merge(options))
+    # Subscribe a member
+    call("listSubscribe", list_id, email, *options.values_at(:user_info, :email_type, :double_opt_in, :update_existing, :replace_interests, :send_welcome))
+  end
+  
+  def subscribe_many(list_id, subscribers, options = {})
+    options = apply_defaults_to({:update_existing => true}.merge(options))
+    # Subscribe a batch of members
+    # subscribers = {:EMAIL => 'example@email.com', :EMAIL_TYPE => 'html'} 
+    call("listBatchSubscribe", list_id, subscribers, *options.values_at(:double_opt_in, :update_existing, :replace_interests))
+  end
+  
+  # Unsubscribe a user from a list
+  #
+  # Options
+  # :delete_member    Delete user form list instead of marking them as unsubscribed
+  # :send_goodbye     Send goodbye e-mail to user
+  # :send_notify      Send unsubscribe email to email in list settings
+  def unsubscribe(list_id, current_email, options = {})
+    options = apply_defaults_to({:delete_member => true}.merge(options))
+    # Unsubscribe a list member
+    call("listUnsubscribe", list_id, current_email, *options.values_at(:delete_member, :send_goodbye, :send_notify))
+  end
+  
+  def unsubscribe_many(list_id, emails, options = {})
+    options = apply_defaults_to({:delete_member => true}.merge(options))
+    # Unsubscribe an array of email addresses
+    # emails = ['first@email.com', 'second@email.com'] 
+    call("listBatchUnsubscribe", list_id, emails, *options.values_at(:delete_member, :send_goodbye, :send_notify))
+  end
+  
+  def update_member(list_id, current_email, user_info = {}, email_type = "")
+    # Update a member of this list
+    call("listUpdateMember", list_id, current_email, user_info, email_type, true)
+  end
+  
+  protected
+  def apply_defaults_to(options)
+    @config.merge(options)
+  end
+
+  def call(method, *args)
+    @chimpApi.call(method, @config[:api_key], *args)
+  rescue XMLRPC::FaultException => error
+    raise HominidError.new(error.message)
+  rescue Exception => error
+    raise HominidCommunicationError.new(error.message)
+  end
+end

data/rails/init.rb

@@ -0,0 +1 @@
+require 'hominid'

data/spec/hominid_spec.rb

@@ -0,0 +1,29 @@
+require 'spec/spec_helper'
+
+describe Hominid do
+  before do
+    api_key = ENV['MAIL_CHIMP_API_KEY']
+    raise "You must set the MAIL_CHIMP_API_KEY environment variable to test" if api_key.empty?
+    @hominid = Hominid.new(:api_key => api_key)
+    @list_id = ENV['MAIL_CHIMP_TEST_LIST_ID']
+    raise "You must set the MAIL_CHIMP_TEST_LIST_ID environment variable to test" if @list_id.empty?
+  end
+  
+  describe "#subscribe" do
+    context "when not supplying a double-opt-in argument" do
+      it "should not blow up" do
+        proc {
+          @hominid.subscribe(@list_id, Faker::Internet.email)
+        }.should_not raise_error
+      end
+    end
+  end
+
+  describe "#call" do
+    it "should raise HominidError on failure" do
+      proc {
+        Hominid.new.send(:call, 'bogusApi')
+      }.should raise_error(HominidError)
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,3 @@
+require 'rubygems'
+require 'faker'
+require 'lib/hominid'

data/uninstall.rb

@@ -0,0 +1 @@
+# Uninstall hook code here

metadata

@@ -0,0 +1,69 @@
+--- !ruby/object:Gem::Specification 
+name: hominid
+version: !ruby/object:Gem::Version 
+  version: 1.2.1
+platform: ruby
+authors: 
+- Brian Getting
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-10-13 00:00:00 -07:00
+default_executable: 
+dependencies: []
+
+description: Use the hominid gem to easily integrate with the Mailchimp email marketing service API.
+email: brian@terra-firma-design.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README.textile
+files: 
+- MIT-LICENSE
+- README.textile
+- Rakefile
+- VERSION.yml
+- hominid.gemspec
+- hominid.yml.tpl
+- init.rb
+- install.rb
+- lib/hominid.rb
+- pkg/hominid-1.2.1.gem
+- rails/init.rb
+- spec/hominid_spec.rb
+- spec/spec_helper.rb
+- uninstall.rb
+has_rdoc: true
+homepage: http://terra-firma-design.com
+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: 
+- spec/hominid_spec.rb
+- spec/spec_helper.rb