bgetting-hominid 1.1.12 → 1.2.0

data/README.textile

@@ -1,26 +1,27 @@
 h1. Hominid
 
-Hominid is a GemPlugin wrapper to the "Mailchimp API":http://www.mailchimp.com/api/1.2/.
+Hominid is a Ruby gem for interacting with the "Mailchimp API":http://www.mailchimp.com/api/1.2/.
 
 h2. Installation
 
-Install as a Rails plugin:
+Install the gem:
 
-<pre><code>script/plugin install git://github.com/bgetting/hominid.git</code></pre>
+<pre><code>gem sources -a http://gems.github.com
+sudo gem install bgetting-hominid</code></pre>
 
-Clone from the Github repository:
+In your @environment.rb@ file:
 
-<pre><code>git clone git://github.com/bgetting/hominid.git</code></pre>
+<pre><code>config.gem "bgetting-hominid", :lib => 'hominid', :source => "http://gems.github.com"</code></pre>
 
-Use the GemPlugin:
+You can also install Hominid as a Rails plugin:
 
-<pre><code>config.gem "bgetting-hominid", :lib => 'hominid', :source => "http://gems.github.com"</code></pre>
+<pre><code>script/plugin install git://github.com/bgetting/hominid.git</code></pre>
 
-h2. Configuration
+h2. Setup
 
-You can either use a master config file, which Hominid expects to find at @/config/hominid.yml@ or (thanks to "ron":http://github.com/ron) you can pass a hash of config options when calling Hominid. _If you are using Hominid as a Rails plugin, the config file will be created for you. If you are using Hominid as a gem, you will need to create the config file._
+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/) for configuration. 
+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
 
@@ -43,17 +44,17 @@ def find_list_id(list_name)
 end
 </code></pre>
 
-To subscribe someone:
+To subscribe:
 
-<pre><code>@hominid.subscribe(@list_id, "email@example.com", {:FNAME => 'Bob', :LNAME => 'Smith'}, 'html')</code></pre>
+<pre><code>@hominid.subscribe(@list_id, "email@example.com", :user_info => {:FNAME => 'Bob', :LNAME => 'Smith'}, :email_type => 'html')</code></pre>
 
-To unsubscribe someone:
+To unsubscribe:
 
 <pre><code>@hominid.unsubscribe(@list_id, "email@example.com")</code></pre>
 
-To update a list member:
+To update a member:
 
-<pre><code>@hominid.subscribe(@list_id, "email@example.com", {:FNAME => 'Robert', :EMAIL => 'another@example.com'}, 'html', true)</code></pre>
+<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_
 

data/Rakefile

@@ -1,5 +1,4 @@
 require 'rake'
-require 'rake/testtask'
 require 'rake/rdoctask'
 
 begin
@@ -16,17 +15,6 @@ rescue LoadError
   puts "Jeweler not available. Install it with: sudo gem install technicalpickles-jeweler -s http://gems.github.com"
 end
 
-desc 'Default: run unit tests.'
-task :default => :test
-
-desc 'Test the hominid plugin.'
-Rake::TestTask.new(:test) do |t|
-  t.libs << 'lib'
-  t.libs << 'test'
-  t.pattern = 'test/**/*_test.rb'
-  t.verbose = true
-end
-
 desc 'Generate documentation for the hominid plugin.'
 Rake::RDocTask.new(:rdoc) do |rdoc|
   rdoc.rdoc_dir = 'rdoc'

data/VERSION.yml

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

data/hominid.gemspec

@@ -2,11 +2,11 @@
 
 Gem::Specification.new do |s|
   s.name = %q{hominid}
-  s.version = "1.1.12"
+  s.version = "1.2.0"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Brian Getting"]
-  s.date = %q{2009-08-11}
+  s.date = %q{2009-09-24}
   s.description = %q{Hominid is a Rails GemPlugin for interacting with the Mailchimp API}
   s.email = %q{brian@terra-firma-design.com}
   s.extra_rdoc_files = [
@@ -23,8 +23,8 @@ Gem::Specification.new do |s|
      "install.rb",
      "lib/hominid.rb",
      "rails/init.rb",
-     "test/hominid_test.rb",
-     "test/test_helper.rb",
+     "spec/hominid_spec.rb",
+     "spec/spec_helper.rb",
      "uninstall.rb"
   ]
   s.homepage = %q{http://github.com/bgetting/hominid}
@@ -33,8 +33,8 @@ Gem::Specification.new do |s|
   s.rubygems_version = %q{1.3.4}
   s.summary = %q{Hominid is a Rails GemPlugin for interacting with the Mailchimp API}
   s.test_files = [
-    "test/hominid_test.rb",
-     "test/test_helper.rb"
+    "spec/hominid_spec.rb",
+     "spec/spec_helper.rb"
   ]
 
   if s.respond_to? :specification_version then

data/lib/hominid.rb

@@ -17,55 +17,36 @@ class Hominid
   # MailChimp API Documentation: http://www.mailchimp.com/api/1.2/
   MAILCHIMP_API = "http://api.mailchimp.com/1.2/"
 
-  def initialize(config = nil)
-    load_monkey_brains(config)
-    @chimpApi ||= XMLRPC::Client.new2(MAILCHIMP_API)
+  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
 
-  def load_monkey_brains(config)
-    config = YAML.load(File.open("#{RAILS_ROOT}/config/hominid.yml"))[RAILS_ENV].symbolize_keys unless config
-    @chimpUsername  = config[:username].to_s
-    @chimpPassword  = config[:password].to_s
-    @api_key        = config[:api_key]
-    @send_goodbye   = config[:send_goodbye]
-    @send_notify    = config[:send_notify]
-    @double_opt     = config[:double_opt]
-  end
-  
   ## Security related methods
   
   def add_api_key
-    begin
-      @chimpApi ||= XMLRPC::Client.new2(MAILCHIMP_API)
-      @chimpApi.call("apikeyAdd", @chimpUsername, @chimpPassword, @api_key)
-    rescue
-      false
-    end
+    @chimpApi.call("apikeyAdd", *@config.values_at(:username, :password, :api_key))
   end
   
   def expire_api_key
-    begin
-      @chimpApi ||= XMLRPC::Client.new2(MAILCHIMP_API)
-      @chimpApi.call("apikeyExpire", @chimpUsername, @chimpPassword, @api_key)
-    rescue
-      false
-    end
+    @chimpApi.call("apikeyExpire", *@config.values_at(:username, :password, :api_key))
   end
   
   def api_keys(include_expired = false)
-    begin
-      @chimpApi ||= XMLRPC::Client.new2(MAILCHIMP_API)
-      @api_keys = @chimpApi.call("apikeys", @chimpUsername, @chimpPassword, include_expired)
-    rescue
-      return nil
-    end
+    username, password = *@config.values_at(:username, :password)
+    @chimpApi.call("apikeys", username, password, include_expired)
   end
   
   ## Campaign related methods
   
   def campaign_content(campaign_id)
     # Get the content of a campaign
-    @content = call("campaignContent", campaign_id)
+    call("campaignContent", campaign_id)
   end
   
   def campaigns(filters = {}, start = 0, limit = 50)
@@ -83,7 +64,7 @@ class Hominid
     #   :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.
-    @campaigns = call("campaigns", filters, start, limit)
+    call("campaigns", filters, start, limit)
   end
 
   # Attach Ecommerce Order Information to a Campaign.
@@ -108,22 +89,22 @@ class Hominid
   #     :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)
-    @campaign = call("campaignEcommAddOrder", order)
+    call("campaignEcommAddOrder", order)
   end
 
   def create_campaign(type = 'regular', options = {}, content = {}, segment_options = {}, type_opts = {})
     # Create a new campaign
-    @campaign = call("campaignCreate", type, options, content, segment_options, type_opts)
+    call("campaignCreate", type, options, content, segment_options, type_opts)
   end
   
   def delete_campaign(campaign_id)
     # Delete a campaign
-    @campaign = call("campaignDelete", campaign_id)
+    call("campaignDelete", campaign_id)
   end
   
   def replicate_campaign(campaign_id)
     # Replicate a campaign (returns ID of new campaign)
-    @campaign = call("campaignReplicate", campaign_id)
+    call("campaignReplicate", campaign_id)
   end
   
   def schedule_campaign(campaign_id, time = "#{1.day.from_now}")
@@ -144,7 +125,7 @@ class Hominid
   
   def templates
     # Get the templates
-    @templates = call("campaignTemplates", @api_key)
+    call("campaignTemplates")
   end
   
   def update_campaign(campaign_id, name, value)
@@ -161,19 +142,19 @@ class Hominid
   
   def html_to_text(content)
     # Convert HTML content to text
-    @html_to_text = call("generateText", 'html', content)
+    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
-    @html_to_text = call("inlineCss", html, strip_css)
+    call("inlineCss", html, strip_css)
   end
   
   ## List related methods
   
   def lists
     # Get all of the lists for this mailchimp account
-    @lists = call("lists", @api_key)
+    call("lists")
   end
   
   def create_group(list_id, group)
@@ -198,12 +179,12 @@ class Hominid
   
   def groups(list_id)
     # Get the interest groups for a list
-    @groups = call("listInterestGroups", list_id)
+    call("listInterestGroups", list_id)
   end
   
   def member(list_id, email)
     # Get a member of a list
-    @member = call("listMemberInfo", list_id, email)
+    call("listMemberInfo", list_id, email)
   end
   
   def members(list_id, status = "subscribed", since = "2000-01-01 00:00:00", start = 0, limit = 100)
@@ -217,34 +198,38 @@ class Hominid
     # Select members that have updated their status or profile by providing
     # a "since" date in the format of YYYY-MM-DD HH:MM:SS
     # 
-    @members = call("listMembers", list_id, status, since, start, limit)
+    call("listMembers", list_id, status, since, start, limit)
   end
   
   def merge_tags(list_id)
     # Get the merge tags for a list
-    @merge_tags = call("listMergeVars", list_id)
+    call("listMergeVars", list_id)
   end
   
-  def subscribe(list_id, email, user_info = {}, email_type = "html", update_existing = true, replace_interests = true, double_opt_in = nil)
+  def subscribe(list_id, email, options = {})
+    options = apply_defaults_to({:email_type => "html"}.merge(options))
     # Subscribe a member
-    call("listSubscribe", list_id, email, user_info, email_type, double_opt_in || @double_opt, update_existing, replace_interests)
+    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)
+  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, @double_opt, true)
+    call("listBatchSubscribe", list_id, subscribers, *options.values_at(:double_opt_in, :update_existing, :replace_interests))
   end
   
-  def unsubscribe(list_id, current_email)
+  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, true, @send_goodbye, @send_notify)
+    call("listUnsubscribe", list_id, current_email, *options.values_at(:delete_member, :send_goodbye, :send_notify))
   end
   
-  def unsubscribe_many(list_id, emails)
+  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, true, @send_goodbye, @send_notify)
+    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 = "")
@@ -253,8 +238,12 @@ class Hominid
   end
   
   protected
+  def apply_defaults_to(options)
+    @config.merge(options)
+  end
+
   def call(method, *args)
-    @chimpApi.call(method, @api_key, *args)
+    @chimpApi.call(method, @config[:api_key], *args)
   rescue XMLRPC::FaultException => error
     raise HominidError.new(error.message)
   rescue Exception => error

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'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: bgetting-hominid
 version: !ruby/object:Gem::Version 
-  version: 1.1.12
+  version: 1.2.0
 platform: ruby
 authors: 
 - Brian Getting
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-08-11 00:00:00 -07:00
+date: 2009-09-24 00:00:00 -07:00
 default_executable: 
 dependencies: []
 
@@ -32,8 +32,8 @@ files:
 - install.rb
 - lib/hominid.rb
 - rails/init.rb
-- test/hominid_test.rb
-- test/test_helper.rb
+- spec/hominid_spec.rb
+- spec/spec_helper.rb
 - uninstall.rb
 has_rdoc: false
 homepage: http://github.com/bgetting/hominid
@@ -63,5 +63,5 @@ signing_key:
 specification_version: 3
 summary: Hominid is a Rails GemPlugin for interacting with the Mailchimp API
 test_files: 
-- test/hominid_test.rb
-- test/test_helper.rb
+- spec/hominid_spec.rb
+- spec/spec_helper.rb

data/test/hominid_test.rb

@@ -1,11 +0,0 @@
-require 'test_helper'
-
-class HominidTest < ActiveSupport::TestCase
-  # Replace this with your real tests.
-  test "the truth" do
-    assert true
-  end
-  
-  ## TODO: Write tests to verify each method
-  
-end

data/test/test_helper.rb

@@ -1,3 +0,0 @@
-require 'rubygems'
-require 'active_support'
-require 'active_support/test_case'