gibbon 0.4.6 → 0.5.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: d877b249bb882f814168716848be16e5304b2db8
+  data.tar.gz: 0fe273859157553a5871637df736b144a00da7c1
+SHA512:
+  metadata.gz: 4e3b5dce4a2f0e2da5da2e0e0c0ece8330d5347d5162ec8fb2f8469bd46362ae3b9cae42037d1b6ae24261e306eb51cf46db044d7bb23c0277f145e7276620dd
+  data.tar.gz: cc1109531c71356394808a777474ecaf90aba07eefd4828e931177f347b3888704d553c467b5920fac23dcd098aca29f7fde345a89cff960280f1fbba53f2451

data/.travis.yml

@@ -1 +1,4 @@
-rvm: 1.9.3
+language: ruby
+rvm:
+  - 1.9.3
+  - 2.0.0

data/README.markdown

@@ -1,16 +1,18 @@
 # gibbon
 
-Gibbon is a simple wrapper for MailChimp's [Primary and Export APIs](http://www.mailchimp.com/api).
+Gibbon is an API wrapper for MailChimp's [Primary and Export APIs](http://www.mailchimp.com/api).
 
 [![Build Status](https://secure.travis-ci.org/amro/gibbon.png)](http://travis-ci.org/amro/gibbon)
 
-##Important Notes About Version 0.4.0+
+##Important Notes About Version 0.5.0+
+### (It's different!)
 
-* Ruby 1.9.x+
-* Errors are now raised by default
+Gibbon now targets MailChimp API 2.0, which is substantially different from API 1.3. Please use Gibbon 0.4.6 if you need to use API 1.3.
+
+* Supports MailChimp API 2.0 and Export API 1.0
+* Errors are raised by default since 0.4.x
 * Timeouts can be specified per request during initialization
-* The environment variable 'MC_API_KEY' no longer works. Please use 'MAILCHIMP_API_KEY' instead.
-* The code has been cleaned up a bit and a few more comments have been added
+* Ruby 1.9.x+ for now. A future version may be Ruby 2.0 only to take advantage of lazy iteration when using the Export API.
 
 ##Installation
 
@@ -26,103 +28,108 @@ There are a few ways to use Gibbon:
 
 You can create an instance of the API wrapper:
 
-    gb = Gibbon.new("your_api_key")
+    gb = Gibbon::API.new("your_api_key")
 
 You can set `api_key`, `timeout` and `throws_exceptions` globally:
 
-    Gibbon.api_key = "your_api_key"
-    Gibbon.timeout = 15
-    Gibbon.throws_exceptions = false
+    Gibbon::API.api_key = "your_api_key"
+    Gibbon::API.timeout = 15
+    Gibbon::API.throws_exceptions = false
 		
+similarly
+
+    Gibbon::Export.api_key = "your_api_key"
+    Gibbon::Export.timeout = 15
+    Gibbon::Export.throws_exceptions = false
+    
 For example, you could set the values above in an `initializer` file in your `Rails` app (e.g. your\_app/config/initializers/gibbon.rb).
 
 Assuming you've set an `api_key` on Gibbon, you can conveniently make API calls on the class itself:
 
-    Gibbon.lists
+    Gibbon::API.lists.list
 
 You can also set the environment variable `MAILCHIMP_API_KEY` and Gibbon will use it when you create an instance:
 
-    u = Gibbon.new
+    gb = Gibbon::API.new
 
 > Note: In an effort to simplify Gibbon, the environment variable 'MC_API_KEY' is no longer available as of version 0.4.0. Please use 'MAILCHIMP_API_KEY' instead.
 
 Fetching data is as simple as calling API methods directly on the wrapper
-object.  The API calls may be made with either camelcase or  underscore
+object with a given category (e.g. campaigns.list).  The API calls may be made with either camelcase or  underscore
 separated formatting as you see in the "More Advanced Examples" section below.
 
-Check the API [documentation](http://apidocs.mailchimp.com/api/1.3/) for details.
+Check the API [documentation](http://apidocs.mailchimp.com/api/2.0/) for details.
 
 ### Fetching Campaigns
 
 For example, to fetch your first 100 campaigns (page 0):
 
-    campaigns = gb.campaigns({:start => 0, :limit => 100})
+    campaigns = gb.campaigns.list({:start => 0, :limit => 100})
 
 ### Fetching Lists
 
 Similarly, to fetch your first 100 lists:
 
-    lists = gb.lists({:start => 0, :limit=> 100})
+    lists = gb.lists.list({:start => 0, :limit=> 100})
 
 Or, to fetch a list by name:
 
-    list = gb.lists({:filters => {:list_name => list_name}})
+    list = gb.lists.list({:filters => {:list_name => list_name}})
 
 ### More Advanced Examples
 
 Getting batch member information for subscribers looks like this:
 
-    info = gb.list_member_info({:id => list_id, :email_address => email_array})
-
-or
-
-    info = gb.listMemberInfo({:id => list_id, :email_address => email_array})
+    info = gb.lists.member_info({:id => list_id, :email_address => email_array})
 
 List subscribers for a list:
 
-    gb.list_members({:id => list_id})
+    gb.lists.members({:id => list_id})
 
 or
 
 List unsubscribed members for a list
 
-    gb.list_members({:id => list_id, :status => "unsubscribed"})
+    gb.lists.members({:id => list_id, :status => "unsubscribed"})
 
 Subscribe a member to a list:
 
-    gb.list_subscribe({:id => list_id, :email_address => "email_address", :merge_vars => {:FNAME => "First Name", :LNAME => "Last Name"}})
+    gb.lists.subscribe({:id => list_id, :email => {:email => 'email_address'}, :merge_vars => {:FNAME => 'First Name', :LNAME => 'Last Name'}, :double_optin => false})
+
 > Note: This will send a welcome email to the new subscriber
 
 or
 
 Batch subscribe members to a list:
 
-    gb.list_batch_subscribe(:id => list_id, :batch => [{:EMAIL => "email1", :FNAME => "FirstName1", :LNAME => "LastName1"},{:EMAIL => "email2", :FNAME => "FirstName2", :LNAME => "LastName2"}])
+    gb.lists.batch_subscribe(:id => list_id, :batch => [{:EMAIL => "email1", :FNAME => "FirstName1", :LNAME => "LastName1"},{:EMAIL => "email2", :FNAME => "FirstName2", :LNAME => "LastName2"}])
 
 > Note: This will send welcome emails to the new subscribers
 
-Fetch open and click detail for recipients of a particular campaign:
+Fetch recipients who opened particular campaign:
 
-    email_stats = gb.campaign_email_stats_aim({:cid => campaign_id, :email_address => email_array})
+    email_stats = gb.reports.opened({:cid => campaign_id})
 
 or
 
-    email_stats = gb.campaignEmailStatsAIM({:cid => campaign_id, :email_address => email_array})
+Create a campaign:
+
+    gb.campaigns.create({type: "regular", options: {list_id: list_id, subject: "Gibbon is cool", from_email: "you@example.com", from_name: "Darth Vader", generate_text: true}, content: {html: "<html><head></head><body><h1>Foo</h1><p>Bar</p></body></html>"}})
 
 Overriding Gibbon's API endpoint (i.e. if using an access token from OAuth and have the `api_endpoint` from the [metadata](http://apidocs.mailchimp.com/oauth2/)):
 
-    Gibbon.api_endpoint = "https://us1.api.mailchimp.com"
-    Gibbon.api_key = your_access_token_or_api_key
+    Gibbon::API.api_endpoint = "https://us1.api.mailchimp.com"
+    Gibbon::API.api_key = your_access_token_or_api_key
 
 ### Setting timeouts
 
 Gibbon defaults to a 30 second timeout. You can optionally set your own timeout (in seconds) like so:
 
-    gb = Gibbon.new("your_api_key", {:timeout => 5})
+    gb = Gibbon::API.new("your_api_key", {:timeout => 5})
 
 or
 
-		gb.timeout = 5
+    gb.timeout = 5
 
 ### Error handling
 
@@ -134,7 +141,8 @@ APIs will return a Hash with two keys "errors", a string containing some textual
 information about the error, and "code", the numeric code of the error.
 
 If you rescue Gibbon::MailChimpError, you are provided with the error message itself as well as
-a `code` attribute that you can map onto the API's [error code list](http://apidocs.mailchimp.com/api/rtfm/exceptions.field.php).
+a `code` attribute that you can map onto the API's error list. The API docs list possible errors
+at the bottom of each page.
 
 > Note: In an effort to make Gibbon easier to use, errors are raised automatically as of version 0.4.0.
 
@@ -142,21 +150,25 @@ a `code` attribute that you can map onto the API's [error code list](http://apid
 
 In addition to the primary API, you can make calls to the [Export API](http://apidocs.mailchimp.com/export/1.0/) using an instance of GibbonExport.  Given an existing instance of Gibbon, you can request a new GibbonExporter object:
 
-    g = Gibbon.new("your_api_key")
+    g = Gibbon::API.new("your_api_key")
     gibbon_export = g.get_exporter
 
 or you can construct a new object directly:
 
-    gibbon_export = GibbonExport.new("your_api_key")
+    gibbon_export = Gibbon::Export.new("your_api_key")
 
-Calling Export API functions is identical to making standard API calls but the
+Making calls to Export API endpoints is similar to making standard API calls but the
 return value is an Enumerator which loops over the lines returned from the
-Export API.  This is because the data returned from the Export API is a stream
+Export API. This is because the data returned from the Export API is a stream
 of JSON objects rather than a single JSON array.
 
+For example, dumping list members via the "list" method works like this:
+
+    gibbon_export.list({id => list_id})
+
 ##Thanks
 
-Thanks to everyone who's [contributed](https://github.com/amro/gibbon/contributors) to Gibbon's development.
+Thanks to everyone who's [contributed](https://github.com/amro/gibbon/contributors) to Gibbon's development. Major props to Jesse at MailChimp for adding nice stuff in API 2.0 that makes it easier to develop against.
 
 ##Copyright
 

data/Rakefile

@@ -1,10 +1,11 @@
-require 'rake/testtask'
+require 'rubygems'
+require 'rspec/core/rake_task'
+require 'rubygems/specification'
 require 'bundler/gem_tasks'
 
-Rake::TestTask.new(:test) do |test|
-  test.libs << 'lib' << 'test'
-  test.pattern = 'test/test_*.rb'
-  test.verbose = true
-end
-
-task default: [:test]
+task :default => :spec
+desc "Run specs"
+RSpec::Core::RakeTask.new do |t|
+  t.pattern = FileList['spec/**/*_spec.rb']
+  t.rspec_opts = %w(-fs --color)
+end

data/gibbon.gemspec

@@ -3,18 +3,18 @@ $:.push File.expand_path("../lib", __FILE__)
 
 Gem::Specification.new do |s|
   s.name        = "gibbon"
-  s.version     = "0.4.6"
+  s.version     = "0.5.0"
   s.authors     = ["Amro Mousa"]
   s.email       = ["amromousa@gmail.com"]
   s.homepage    = "http://github.com/amro/gibbon"
 
-  s.summary     = %q{A simple wrapper for MailChimp's primary and export APIs}
-  s.description = %q{A simple wrapper for MailChimp's primary and export APIs}
+  s.summary     = %q{A wrapper for MailChimp API 2.0 and Export API 1.0}
+  s.description = %q{A wrapper for MailChimp API 2.0 and Export API 1.0}
   s.license     = "MIT"
 
-  s.post_install_message = "Warning: Gibbon versions 0.4.0 and newer include breaking changes like throwing exceptions by default!\n" +
-                           "Please read more at http://github.com/amro/gibbon before upgrading from 0.3.x!"
-  
+  s.post_install_message = "IMPORTANT: Gibbon now targets MailChimp API 2.0, which is substantially different from API 1.3.\n \
+                            Please use Gibbon 0.4.6 if you need to use API 1.3.\nIf you're upgrading from <0.5.0 your code WILL break."
+
   s.rubyforge_project = "gibbon"
 
   s.files         = `git ls-files`.split("\n")
@@ -25,8 +25,7 @@ Gem::Specification.new do |s|
   s.add_dependency('httparty')
   s.add_dependency('multi_json', '>= 1.3.4')
 
-  s.add_development_dependency('rake')
-  s.add_development_dependency('debugger')
-  s.add_development_dependency('shoulda')
-  s.add_development_dependency('mocha')
+  s.add_development_dependency 'rake'
+  s.add_development_dependency "rspec", "~> 2.13.0"
+
 end

data/lib/gibbon.rb

@@ -2,142 +2,10 @@ require 'httparty'
 require 'multi_json'
 require 'cgi'
 
-class Gibbon
-  include HTTParty
-  format :plain
-  default_timeout 30
+require 'gibbon/mailchimp_error'
+require 'gibbon/api_category'
+require 'gibbon/api'
+require 'gibbon/export'
 
-  attr_accessor :api_key, :api_endpoint, :timeout, :throws_exceptions
-
-  def initialize(api_key = nil, default_parameters = {})
-    @api_key = api_key || self.class.api_key || ENV['MAILCHIMP_API_KEY']
-    @api_key = @api_key.strip if @api_key
-
-    @api_endpoint = default_parameters.delete(:api_endpoint)
-    @timeout = default_parameters.delete(:timeout)
-    @throws_exceptions = default_parameters.delete(:throws_exceptions)
-  
-    @default_params = {apikey: @api_key}.merge(default_parameters)
-    
-    set_instance_defaults
-  end
-  
-  def api_key=(value)
-    @api_key = value.strip if value
-    @default_params = @default_params.merge({apikey: @api_key})
-  end
-
-  def get_exporter
-    GibbonExport.new(@api_key, @default_params)
-  end
-
-  protected
-
-  def call(method, params = {})
-    api_url = base_api_url + method
-    params = @default_params.merge(params)
-    response = self.class.post(api_url, body: CGI::escape(MultiJson.dump(params)), timeout: @timeout)
-
-    # MailChimp API sometimes returns JSON fragments (e.g. true from listSubscribe)
-    # so we parse after adding brackets to create a JSON array so 
-    # parsing succeeds. This also handles the case of an empty response
-    parsed_response = MultiJson.load("[#{response.body}]").first
-
-    if should_raise_for_response?(parsed_response)
-      error = MailChimpError.new("MailChimp API Error: #{parsed_response["error"]} (code #{parsed_response["code"]})")
-      error.code = parsed_response["code"]
-      raise error
-    end
-
-    parsed_response
-  end
-  
-  def method_missing(method, *args)
-    # To support underscores, we camelize the method name
-
-    # Thanks for the camelize gsub, Rails
-    method = method.to_s.gsub(/\/(.?)/) { "::#{$1.upcase}" }.gsub(/(?:^|_)(.)/) { $1.upcase }
-
-    # We need to downcase the first letter of every API method
-    # and MailChimp has a few of API methods that end in "AIM," which
-    # must be upcased (See "Campaign Report Data Methods" in their API docs).
-    method = method[0].chr.downcase + method[1..-1].gsub(/aim$/i, 'AIM')
-
-    call(method, *args)
-  end
-  
-  def set_instance_defaults
-    @timeout = (self.class.timeout || 30) if @timeout.nil?
-    @api_endpoint = self.class.api_endpoint if @api_endpoint.nil?
-    # Two lines because the class variable could be false and (false || true) is always true
-    @throws_exceptions = self.class.throws_exceptions if @throws_exceptions.nil?
-    @throws_exceptions = true if @throws_exceptions.nil?
-  end
-
-  def should_raise_for_response?(response)
-    @throws_exceptions && response.is_a?(Hash) && response["error"]
-  end
-
-  def base_api_url
-    "#{@api_endpoint || get_api_endpoint}/1.3/?method="
-  end
-
-  def get_api_endpoint
-    "https://#{get_data_center_from_api_key}api.mailchimp.com"
-  end
-
-  class << self
-    attr_accessor :api_key, :timeout, :throws_exceptions, :api_endpoint
-
-    def method_missing(sym, *args, &block)
-      new(self.api_key, {api_endpoint: self.api_endpoint, timeout: self.timeout, throws_exceptions: self.throws_exceptions}).send(sym, *args, &block)
-    end
-  end
-
-  def get_data_center_from_api_key
-    # Return an empty string for invalid API keys so Gibbon hits the main endpoint
-    data_center = ""
-
-    if (@api_key && @api_key["-"])
-      # Add a period since the data_center is a subdomain and it keeps things dry
-      data_center = "#{@api_key.split('-').last}."
-    end
-
-    data_center
-  end
-  
-  class MailChimpError < StandardError
-    attr_accessor :code
-  end
-end
-  
-class GibbonExport < Gibbon
-  def initialize(api_key = nil, default_parameters = {})
-    super(api_key, default_parameters)
-  end
-
-  protected
-
-  def export_api_url
-    "http://#{get_data_center_from_api_key}api.mailchimp.com/export/1.0/"
-  end
-
-  def call(method, params = {})
-    api_url = export_api_url + method + "/"
-    params = @default_params.merge(params)
-    response = self.class.post(api_url, body: CGI::escape(MultiJson.dump(params)), timeout: @timeout)
-
-    lines = response.body.lines
-    if @throws_exceptions
-      first_line = MultiJson.load(lines.first) if lines.first
-      
-      if should_raise_for_response?(first_line)
-        error = MailChimpError.new("MailChimp Export API Error: #{first_line["error"]} (code #{first_line["code"]})")
-        error.code = first_line["code"]
-        raise error
-      end
-    end
-
-    lines
-  end
-end
+module Gibbon
+end

data/lib/gibbon/api.rb

@@ -0,0 +1,34 @@
+module Gibbon
+  class API
+    attr_accessor :api_key, :api_endpoint, :timeout, :throws_exceptions
+  
+    def initialize(api_key = nil, default_parameters = {})
+      @api_key = api_key || self.class.api_key || ENV['MAILCHIMP_API_KEY']
+      @api_key = @api_key.strip if @api_key
+
+      @api_endpoint = default_parameters.delete(:api_endpoint) || self.class.api_endpoint
+      @timeout = default_parameters.delete(:timeout) || self.class.timeout
+      @throws_exceptions = default_parameters.delete(:throws_exceptions) || self.class.throws_exceptions
+  
+      @default_params = {apikey: @api_key}.merge(default_parameters)
+    end
+    
+    def get_exporter
+      Export.new(@api_key, @default_params)
+    end
+    
+    def method_missing(method, *args)
+      api = APICategory.new(method.to_s, @api_key, @timeout, @throws_exceptions, @api_endpoint, @default_params)
+      api.api_endpoint = @api_endpoint if @api_endpoint
+      api
+    end
+
+    class << self
+      attr_accessor :api_key, :timeout, :throws_exceptions, :api_endpoint
+
+      def method_missing(sym, *args, &block)
+        new(self.api_key, {api_endpoint: self.api_endpoint, timeout: self.timeout, throws_exceptions: self.throws_exceptions}).send(sym, *args, &block)
+      end
+    end
+  end
+end