hominid 2.2.0 → 3.0.1

data/Gemfile

@@ -0,0 +1,13 @@
+source "http://rubygems.org"
+# Add dependencies required to use your gem here.
+#gem "json"
+
+# Add dependencies to develop your gem here.
+# Include everything needed to run rake, tests, features, etc.
+group :development do
+	gem "bundler", "~> 1.0.0"
+  gem "jeweler", "~> 1.5.2"
+	gem "mocha", ">= 0.9.10"
+  gem "rcov", ">= 0.9.9"
+	gem "shoulda", ">= 2.11.3"
+end

data/Gemfile.lock

@@ -0,0 +1,23 @@
+GEM
+  remote: http://rubygems.org/
+  specs:
+    git (1.2.5)
+    jeweler (1.5.2)
+      bundler (~> 1.0.0)
+      git (>= 1.2.5)
+      rake
+    mocha (0.9.10)
+      rake
+    rake (0.8.7)
+    rcov (0.9.9)
+    shoulda (2.11.3)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  bundler (~> 1.0.0)
+  jeweler (~> 1.5.2)
+  mocha (>= 0.9.10)
+  rcov (>= 0.9.9)
+  shoulda (>= 2.11.3)

data/{LICENSE → LICENSE.txt}

@@ -1,4 +1,4 @@
-Copyright (c) 2009 Brian Getting
+Copyright (c) 2010 Brian Getting
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/README.rdoc

@@ -1,114 +1,55 @@
 = Hominid
 
-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/]).
-
-== Installation
-
-  sudo gem install hominid
+Hominid is a Ruby gem that provides a wrapper for interacting with the Mailchimp[http://eepurl.com/ew8J] API.
 
 == Requirements
 
-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.
-
-== Usage
-
-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.
-
-You will need to pass your Mailchimp API key to get started:
-
-  h = Hominid::Base.new({:api_key => API_KEY})
-
-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.
-
-Once you have created a Hominid object, you can begin interacting with the Mailchimp account that your API key is associated with.
-
-=== Working with Lists
-
-We have provided some finder methods to make working with your mailing lists easier:
-
-  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>
-
-There are also finders for easily getting at List ID's, which are required for nearly all the list methods:
-
-  list_id = h.find_list_id_by_name("Mailing List Name")
-  list_id_ = h.find_list_id_by_web_id("List Web ID")
-
-This means that you can _(for example)_ subscribe someone to a particular mailing list:
+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.
 
-  h.subscribe(h.find_list_id_by_name("Mailing List Name"), "email@domain.com", {:FNAME => "Bob", :LNAME => "Smith"}, {:email_type => 'html'})
-
-Or to update a subscriber to a particular list:
-
-  h.update_member(h.find_list_id_by_name("Mailing List Name"), "old_email@domain.com", {:EMAIL => "new_email_@domain.com"}, 'html')
-
-Take a look at Hominid::List to see the methods that are available for interacting with your lists.
-
-=== Working with Campaigns
-
-We have provided some finder methods to make working with your campaigns easier:
-
-  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")
-
-To create a new campaign, use the +create_campaign+ method:
-
-  new_campaign = h.create_campaign(...)
-
-Take a look at Hominid::Campaign to see the methods that are available for interacting with your campaigns.
-
-=== Mailchimp Helper Methods
-
-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:
-
-  account_details_ = h.account_details
+== Installation
 
-In this case, the +account_details+ object can be accessed like:
+  (sudo) gem install hominid
 
-  account_details.contact.company
-  account_details.orders
+== Usage
 
-Take a look at Hominid::Helper to see the helper methods that are available.
+Please refer to the {Mailchimp API Documentation}[http://www.mailchimp.com/api/1.3/] for information about what methods are available, the arguments that can be passed to each method, and the output that the API will return. Start by creating a Hominid object:
 
-=== Mailchimp Security Methods
+  h = Hominid::API.new('your_api_key')
 
-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:
+You can then run any of the methods that you find in the {Mailchimp API Documentation}[http://www.mailchimp.com/api/1.3/] against it. Simply convert the names to the more Ruby-like underscored versions. You do not need to pass your api_key to each method, as that is done automatically for you:
 
-  h.api_keys('username', 'password')
+  h.get_account_details
+  h.lists
+  h.campaign_create('regular', {:list_id => 'list_id', ...}, {:html => 'Campaign HTML content', ...})
+  h.template_add('template_name', 'Template HTML Code')
+	
+The {Mailchimp API}[http://www.mailchimp.com/api/1.3/] now supports pagination for some methods, so certain methods will have the following response:
 
-Take a look at Hominid::Security to see the security methods that are available.
+  h.lists['total']        => 4
+  h.lists['data']         => outputs an array of your mailing lists
+  h.lists['data'].first   => {"id" => "XXXXXXX", "web_id" => 1234567, "name" => "My Mailing List", ...}
 
-== Contributors
+Please note that as of version 3.0.0 Hominid no longer includes support for the {Mailchimp Export API}[http://www.mailchimp.com/api/export/].
 
-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:
+== Examples
 
-* {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/]
-* {Bill Abney}[http://github.com/babney]
-* {David Rice}[http://github.com/davidjrice]
+Hominid includes some finder methods for campaigns (see Hominid::Campaign) and lists (see Hominid::List) to help with finding each of these resources:
 
-== Note on Patches/Pull Requests
+  h.find_list_by_name('my_mailing_list')
+  h.find_list_id_by_name('my_mailing_list')
+  h.find_campaigns_by_list_name('my_mailing_list')
 
-1. Fork the project.
-2. Make your feature addition or bug fix.
-3. Add tests for it. This is important so I don't break it in a future version unintentionally.
-4. 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)
-5. Send me a pull request. Bonus points for topic branches.
+== Contributing to hominid
+ 
+* Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet
+* Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it
+* Fork the project
+* Start a feature/bugfix branch
+* Commit and push until you are happy with your contribution
+* Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.
+* Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.
 
 == Copyright
 
-Copyright (c) 2009 Brian Getting. See LICENSE for details.
+Copyright (c) 2010 Brian Getting. See LICENSE.txt for further details.
+

data/Rakefile

@@ -1,59 +1,49 @@
 require 'rubygems'
+require 'bundler'
+begin
+  Bundler.setup(:default, :development)
+rescue Bundler::BundlerError => e
+  $stderr.puts e.message
+  $stderr.puts "Run `bundle install` to install missing gems"
+  exit e.status_code
+end
 require 'rake'
 
-begin
-  require 'jeweler'
-  Jeweler::Tasks.new do |gem|
-    gem.name = "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_dependency 'json', '>=1.2.0'
-    gem.add_development_dependency 'jeweler'
-    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"
+require 'jeweler'
+Jeweler::Tasks.new do |gem|
+  # gem is a Gem::Specification... see http://docs.rubygems.org/read/chapter/20 for more options
+  gem.name = "hominid"
+  gem.homepage = "http://github.com/bgetting/hominid"
+  gem.license = "MIT"
+  gem.summary = %Q{Hominid is a Ruby wrapper for 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.authors = ["Brian Getting"]
 end
+Jeweler::RubygemsDotOrgTasks.new
 
 require 'rake/testtask'
 Rake::TestTask.new(:test) do |test|
   test.libs << 'lib' << 'test'
-  test.pattern = 'test/**/*_test.rb'
+  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
+require 'rcov/rcovtask'
+Rcov::RcovTask.new do |test|
+  test.libs << 'test'
+  test.pattern = 'test/**/test_*.rb'
+  test.verbose = true
 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
+  version = File.exist?('VERSION') ? File.read('VERSION') : ""
 
   rdoc.rdoc_dir = 'rdoc'
   rdoc.title = "hominid #{version}"
   rdoc.rdoc_files.include('README*')
   rdoc.rdoc_files.include('lib/**/*.rb')
 end
-

data/VERSION

@@ -1 +1 @@
-2.2.0
+3.0.1

data/hominid.gemspec

@@ -1,45 +1,44 @@
 # Generated by jeweler
 # DO NOT EDIT THIS FILE DIRECTLY
-# Instead, edit Jeweler::Tasks in Rakefile, and run the gemspec command
+# Instead, edit Jeweler::Tasks in Rakefile, and run 'rake gemspec'
 # -*- encoding: utf-8 -*-
 
 Gem::Specification.new do |s|
   s.name = %q{hominid}
-  s.version = "2.2.0"
+  s.version = "3.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{2010-09-28}
+  s.authors = ["Brian Getting"]
+  s.date = %q{2010-12-20}
   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.rdoc"
+    "LICENSE.txt",
+    "README.rdoc"
   ]
   s.files = [
-    ".gitignore",
-     "LICENSE",
-     "README.rdoc",
-     "Rakefile",
-     "VERSION",
-     "hominid.gemspec",
-     "lib/hominid.rb",
-     "lib/hominid/base.rb",
-     "lib/hominid/campaign.rb",
-     "lib/hominid/helper.rb",
-     "lib/hominid/list.rb",
-     "lib/hominid/security.rb",
-     "test/hominid_test.rb",
-     "test/test_helper.rb"
+    "Gemfile",
+    "Gemfile.lock",
+    "LICENSE.txt",
+    "README.rdoc",
+    "Rakefile",
+    "VERSION",
+    "hominid.gemspec",
+    "lib/hominid.rb",
+    "lib/hominid/campaign.rb",
+    "lib/hominid/list.rb",
+    "lib/hominid/security.rb",
+    "test/helper.rb",
+    "test/test_hominid.rb"
   ]
   s.homepage = %q{http://github.com/bgetting/hominid}
-  s.rdoc_options = ["--charset=UTF-8"]
+  s.licenses = ["MIT"]
   s.require_paths = ["lib"]
   s.rubygems_version = %q{1.3.7}
-  s.summary = %q{Hominid is a Ruby gem for interacting with the Mailchimp API.}
+  s.summary = %q{Hominid is a Ruby wrapper for the Mailchimp API}
   s.test_files = [
-    "test/hominid_test.rb",
-     "test/test_helper.rb"
+    "test/helper.rb",
+    "test/test_hominid.rb"
   ]
 
   if s.respond_to? :specification_version then
@@ -47,18 +46,24 @@ Gem::Specification.new do |s|
     s.specification_version = 3
 
     if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
-      s.add_runtime_dependency(%q<json>, [">= 1.2.0"])
-      s.add_development_dependency(%q<jeweler>, [">= 0"])
-      s.add_development_dependency(%q<shoulda>, [">= 0"])
+      s.add_development_dependency(%q<bundler>, ["~> 1.0.0"])
+      s.add_development_dependency(%q<jeweler>, ["~> 1.5.2"])
+      s.add_development_dependency(%q<mocha>, [">= 0.9.10"])
+      s.add_development_dependency(%q<rcov>, [">= 0.9.9"])
+      s.add_development_dependency(%q<shoulda>, [">= 2.11.3"])
     else
-      s.add_dependency(%q<json>, [">= 1.2.0"])
-      s.add_dependency(%q<jeweler>, [">= 0"])
-      s.add_dependency(%q<shoulda>, [">= 0"])
+      s.add_dependency(%q<bundler>, ["~> 1.0.0"])
+      s.add_dependency(%q<jeweler>, ["~> 1.5.2"])
+      s.add_dependency(%q<mocha>, [">= 0.9.10"])
+      s.add_dependency(%q<rcov>, [">= 0.9.9"])
+      s.add_dependency(%q<shoulda>, [">= 2.11.3"])
     end
   else
-    s.add_dependency(%q<json>, [">= 1.2.0"])
-    s.add_dependency(%q<jeweler>, [">= 0"])
-    s.add_dependency(%q<shoulda>, [">= 0"])
+    s.add_dependency(%q<bundler>, ["~> 1.0.0"])
+    s.add_dependency(%q<jeweler>, ["~> 1.5.2"])
+    s.add_dependency(%q<mocha>, [">= 0.9.10"])
+    s.add_dependency(%q<rcov>, [">= 0.9.9"])
+    s.add_dependency(%q<shoulda>, [">= 2.11.3"])
   end
 end
 

data/lib/hominid.rb

@@ -1,40 +1,65 @@
-require 'json'
+# TODO: Write tests (include mocks for API calls) -- refer to Koala testing for mocks.
+require 'openssl'
 require 'xmlrpc/client'
-require 'ostruct'
+
+require 'hominid/campaign'
+require 'hominid/list'
+require 'hominid/security'
 
 module Hominid
+  class API
+    # Blank Slate
+    instance_methods.each do |m|
+      undef_method m unless m.to_s =~ /^__|object_id|method_missing|respond_to?|to_s|inspect/
+    end
+    
+    include Hominid::Campaign
+    include Hominid::List
+    include Hominid::Security
+    
+    # MailChimp API Documentation: http://www.mailchimp.com/api/1.3/
+    MAILCHIMP_API_VERSION = "1.3"
 
-  class StandardError < ::StandardError
-  end
+    # Initialize with an API key and config options
+    def initialize(api_key, config = {})
+      raise ArgumentError.new('Your Mailchimp API key appears to be malformed') unless api_key.include?('-')
+      dc = api_key.split('-').last
+      defaults = {
+        :api_version        => MAILCHIMP_API_VERSION,
+        :secure             => false,
+        :timeout            => nil
+      }
+      @config = defaults.merge(config).freeze
+      protocol = @config[:secure] ? 'https' : 'http'
+      @api_key = api_key
+      @chimpApi = XMLRPC::Client.new2("#{protocol}://#{dc}.api.mailchimp.com/#{MAILCHIMP_API_VERSION}/", nil, config[:timeout])
+    end
 
+    def method_missing(api_method, *args) # :nodoc:
+      @chimpApi.call(api_method.to_s.camelize_api_method_name, @api_key, *args)
+    rescue XMLRPC::FaultException => error
+      super if error.faultCode == -32601
+      raise APIError.new(error)
+    end
+    
+    def respond_to?(api_method)
+      @chimpApi.call(api_method, @api_key)
+    rescue XMLRPC::FaultException => error
+      error.faultCode == -32601 ? false : true 
+    end
+
+  end
+  
   class APIError < StandardError
     def initialize(error)
       super("<#{error.faultCode}> #{error.message}")
     end
   end
-  
-  class CampaignError < APIError
-  end
-  
-  class ListError < APIError
-  end
-  
-  class UserError < APIError
-  end
-  
-  class ValidationError < APIError
-  end
 
-  class CommunicationError < StandardError
-    def initialize(message)
-      super(message)
-    end
-  end
-  
 end
 
-require 'hominid/campaign'
-require 'hominid/helper'
-require 'hominid/list'
-require 'hominid/security'
-require 'hominid/base'
+class String
+  def camelize_api_method_name
+    self.to_s[0].chr.downcase + self.gsub(/(?:^|_)(.)/) { $1.upcase }[1..self.size]
+  end
+end