gibbon 1.2.1 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 84f76dfa6df5af8fe5113bc40b2636c1785a444f
-  data.tar.gz: 1972be9d4e48fa14dfc2b9f36e4a50f89d5ca113
+  metadata.gz: 6f3bc3884010b6bc30397d25c746ca29f6b026cf
+  data.tar.gz: acf67934d1a27976e15324502773b0029978f3a9
 SHA512:
-  metadata.gz: c74ace9fe34feed80a88bfa4aebf22579864a19a11688cf78fa554ffac9dc7ed08b38eb8606f7329fd897aac611eeeb36b3a38d8b7bf8723920b942f801db199
-  data.tar.gz: 3156a79ab00e9f224a188644d0b2f8d49529a35bd99e63cd4fe5cf478b291a83d151966d5909eac09f3a24352e8fdcabf1ae1c08f7749ff615159397fc8e0e00
+  metadata.gz: 72ddec2ab87bdb95d5bcb25f0728eeece2a70daaf49a990444c2dfd4b97c28e093c07b644a0538383684e05482977ec8eeb7c4d4210e7d5e25aa8bd2710a5835
+  data.tar.gz: a20ba104983c405b478dad32c3cc507521c80dd3b36e39cf1d208201bf526a1bc02eec889b370ad946b39a4f83988db648ed8de01f58e1a2dd9dd30d44ea7b72

data/.travis.yml

@@ -2,9 +2,7 @@ language: ruby
 before_install: gem install bundler -v 1.5.1
 install: bundle install --retry=3
 rvm:
-  - 1.9.3
   - 2.0.0
   - 2.1.5
   - 2.2.0
-  - jruby-19mode
   - rbx-2

data/CHANGELOG.md

@@ -1,7 +1,10 @@
 ## [Unreleased][unreleased]
--
-## [1.2.1] - 2015-07-30
-- Fix lack of newline issue (contributed by @michaeldawson)
+
+## [2.0.0] - 2015-7-28
+- Support for API 3.0. Usage syntax has changed. Please check out the readme.
+- Update MultiJSON dependency to 1.11.0
+- Switch to Faraday
+- Fix: Handle empty response payloads on delete
 
 ## [1.2.0] - 2015-07-16
 - Same as 1.1.6 but rereleased because it's a breaking change
@@ -18,7 +21,8 @@
 ## [1.1.4] - 2012-11-04
 - Fix JSON::ParserError on export calls that return blank results
 
-[1.2.1]: https://github.com/amro/gibbon/compare/v1.2.0...v1.2.1
-[1.2.0]: https://github.com/amro/gibbon/compare/v1.1.4...v1.2.0
+[unreleased]: https://github.com/amro/gibbon/compare/v2.0.0...HEAD
+[2.0.0]: https://github.com/amro/gibbon/compare/v1.2.0...v2.0.0
+[1.2.0]: https://github.com/amro/gibbon/compare/v1.1.5...v1.2.0
+[1.1.5]: https://github.com/amro/gibbon/compare/v1.1.5...v1.1.4
 [1.1.4]: https://github.com/amro/gibbon/compare/v1.1.3...v1.1.4
-[1.1.5]: https://github.com/amro/gibbon/compare/v1.1.4...v1.1.5

data/README.markdown

@@ -1,16 +1,14 @@
 # gibbon
 
-Gibbon is an API wrapper for MailChimp's [Primary and Export APIs](http://www.mailchimp.com/api).
+Gibbon is an API wrapper for MailChimp's [API](http://kb.mailchimp.com/api/).
 
 [![Build Status](https://secure.travis-ci.org/amro/gibbon.png)](http://travis-ci.org/amro/gibbon)
 [![Dependency Status](https://gemnasium.com/amro/gibbon.png)](https://gemnasium.com/amro/gibbon)
 ##Important Notes
 
-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.
+Gibbon now targets MailChimp API 3.0, which is substantially different from the previous API. Please use Gibbon 1.1.x if you need to use API 2.0.
 
-* Supports MailChimp API 2.0 and Export API 1.0
-* Errors are raised by default
-* Timeouts can be specified per request during initialization
+Please read MailChimp's [Getting Started Guide](http://kb.mailchimp.com/api/article/api-3-overview).
 
 ##Installation
 
@@ -22,197 +20,95 @@ A MailChimp account and API key. You can see your API keys [here](http://admin.m
 
 ##Usage
 
-There are a few ways to use Gibbon:
+First, create an instance Gibbon::Request:
 
-You can create an instance of the API wrapper:
+    gibbon = Gibbon::Request.new(api_key: "your_api_key")
 
-    gb = Gibbon::API.new("your_api_key")
+You can set an individual request's timeout like this:
 
-You can set `api_key`, `timeout` and `throws_exceptions` globally:
+    gibbon.timeout = 10
 
-    Gibbon::API.api_key = "your_api_key"
-    Gibbon::API.timeout = 15
-    Gibbon::API.throws_exceptions = false
+Now you can make requests using the resources defined in [MailChimp's docs](http://kb.mailchimp.com/api/resources). Resource IDs
+are specified inline and a `CRUD` (`create`, `retrieve`, `update`, or `delete`) verb initiates the request.
 
-similarly
+    gibbon.lists.retrieve
 
-    Gibbon::Export.api_key = "your_api_key"
-    Gibbon::Export.timeout = 15
-    Gibbon::Export.throws_exceptions = false
+Retrieving a specific list looks like:
 
-For example, you could set the values above in an `initializer` file in your `Rails` app (e.g. your\_app/config/initializers/gibbon.rb).
+    gibbon.lists(list_id).retrieve
 
-Assuming you've set an `api_key` on Gibbon, you can conveniently make API calls on the class itself:
+Retrieving a specific list's members looks like:
 
-    Gibbon::API.lists.list
+    gibbon.lists(list_id).members.retrieve
 
-You can also set the environment variable `MAILCHIMP_API_KEY` and Gibbon will use it when you create an instance:
+You can also specify `headers`, `params`, and `body` when calling a `CRUD` method. For example:
 
-    gb = Gibbon::API.new
+    gibbon.lists.retrieve(headers: {"SomeHeader": "SomeHeaderValue"}, params: {"query_param": "query_param_value"})
 
-> 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.
+Of course, `body` is only supported on `create` and `update` calls. Those map to HTTP `POST` and `PATCH` verbs.
 
-Fetching data is as simple as calling API methods directly on the wrapper
-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.
+You can set `api_key` and `timeout` globally:
 
-Check the API [documentation](http://apidocs.mailchimp.com/api/2.0/) for details.
+    Gibbon::Request.api_key = "your_api_key"
+    Gibbon::Request.timeout = 15
 
-### Fetching Campaigns
+For example, you could set the values above in an `initializer` file in your `Rails` app (e.g. your\_app/config/initializers/gibbon.rb).
 
-For example, to fetch your first 100 campaigns (page 0):
+Assuming you've set an `api_key` on Gibbon, you can conveniently make API calls on the class itself:
 
-    campaigns = gb.campaigns.list({:start => 0, :limit => 100})
+    Gibbon::Request.lists.retrieve
 
-### Fetching Lists
-
-Similarly, to fetch your first 100 lists:
+You can also set the environment variable `MAILCHIMP_API_KEY` and Gibbon will use it when you create an instance:
 
-    lists = gb.lists.list({:start => 0, :limit=> 100})
+    gb = Gibbon::Request.new
 
-Or, to fetch a list by name:
+MailChimp's [resource documentation](http://kb.mailchimp.com/api/resources) is a list of available resources. Substitute an underscore if
+a resource name contains a hyphen.
 
-    list = gb.lists.list({:filters => {:list_name => list_name}})
+### Fetching Campaigns
 
-### More Advanced Examples
 
-Getting batch member information for subscribers looks like this:
+    campaigns = gb.campaigns.retrieve
 
-    info = gb.lists.member_info({:id => list_id, :emails => [{:email => email_1}, {:email => email_2}]})
+### Fetching Lists
 
-List subscribers for a list:
+Similarly, to fetch your lists
 
-    gb.lists.members({:id => list_id})
+    lists = gb.lists.retrieve
 
-or
+### More Advanced Examples
 
-List unsubscribed members for a list
+List subscribers for a list:
 
-    gb.lists.members({:id => list_id, :status => "unsubscribed"})
+    gb.lists(list_id).members.retrieve
 
 Subscribe a member to a list:
 
-    gb.lists.subscribe({:id => list_id, :email => {:email => 'email_address'}, :merge_vars => {:FNAME => 'First Name', :LNAME => 'Last Name'}, :double_optin => false})
-
-Here's an example showing pagination. The following code fetches the first page of 100 members subscribed to your list:
-
-    gb.lists.members({:id => list_id, :opts => {:start => 0, :limit => 100}})
-
-or
-
-Batch subscribe members to a list:
-
-    gb.lists.batch_subscribe(:id => list_id, :batch => [{:email => {:email => "email1"}, :merge_vars => {:FNAME => "FirstName1", :LNAME => "LastName1"}},{:email => {:email =>"email2"}, :merge_vars => {:FNAME => "FirstName2", :LNAME => "LastName2"}}])
-
-> Note: This will send welcome emails to the new subscribers
-
-If you want to update the existing members you need to send the boolean update_existing in true
-
-    gb.lists.batch_subscribe(:id => list_id, :batch => [{:email => {:email => "email1"}, :merge_vars => {:FNAME => "FirstName1", :LNAME => "LastName1"}}], :update_existing => true)
-
-> Note: The `email` hash can also accept either a unique email id or a list email id. Please see the [lists/batch-subscribe](http://apidocs.mailchimp.com/api/2.0/lists/batch-subscribe.php) documentation for more information.
+    gb.lists(list_id).members.create(body: {email_address: "email_address", status: "subscribed", merge_fields: {FNAME: "First Name", LNAME: "Last Name"}})
 
 You can also unsubscribe a member from a list:
 
-    gb.lists.unsubscribe(:id => list_id, :email => {:email => "user_email"}, :delete_member => true, :send_notify => true)
-
-> Note: :delete_member defaults to false, meaning the member stays on your mailchimp list as "unsubscribed".  See [Api Docs](http://apidocs.mailchimp.com/api/2.0/lists/unsubscribe.php) for details of options.
+    gb.lists(list_id).members(member_id).update(body: { status: "unsubscribed" })
 
-Fetch recipients who opened particular campaign:
+Fetch the number of opens for a campaign
 
-    email_stats = gb.reports.opened({:cid => campaign_id})
-
-or
-
-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>"}})
+    email_stats = gb.reports("13e9a94053").retrieve["opens"]
 
 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.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::API.new("your_api_key", {:timeout => 5})
-
-or
-
-    gb.timeout = 5
+    Gibbon::Request.api_endpoint = "https://us1.api.mailchimp.com"
+    Gibbon::Request.api_key = your_access_token_or_api_key
 
 ### Error handling
 
-By default Gibbon will attempt to raise errors returned by the API automatically.
-
-If you set the `throws_exceptions` boolean attribute to false, for a given instance,
-then Gibbon will not raise exceptions. This allows you to handle errors manually. The
-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 list. The API docs list possible errors
-at the bottom of each page. Here's how you might do that:
-
-    begin
-      g.lists.subscribe(...)
-    rescue Gibbon::MailChimpError => e
-      # do something with e.message here
-      # do something wiht e.code here
-    end
-
-Some API endpoints, like `[lists/batch-subscribe](http://apidocs.mailchimp.com/api/2.0/lists/batch-subscribe.php)`
-return errors to let you know that some of your actions failed, but some suceeded. Gibbon will not
-raise Gibbon::MailChimpError for these endpoints because the key for the success count varies from endpoint to endpoint.
-This makes it difficult to determine whether all of your actions failed in a generic way. **Because of this, you're responsible
-for checking the response body for the `errors` array in these cases.**
-
-> Note: In an effort to make Gibbon easier to use, errors are raised automatically as of version 0.4.0.
-
-### Export API usage
-
-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::API.new("your_api_key")
-    gibbon_export = g.get_exporter
-
-or you can construct a new object directly:
-
-    gibbon_export = Gibbon::Export.new("your_api_key")
-
-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
-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*})
-
-One can also use this in a streaming fashion, where each row is parsed on it comes in like this:
-
-    gibbon_export.list({:id => *list_id*}) { |row| *do_sth_with* row }
-
-For the streaming functionality, it is important to supply an explicit block / procedure to the export functions, not an implicit one. So, the preceding and following one will work. Please note this method also includes a counter (*i*, starting at 0) telling which row of data you're receiving:
-```
-    method = Proc.new do |row, i|
-        *do_sth_with* row
-    end
-    gibbon_export.list(params, &method)
-```
+Gibbon raises an error when the API returns an error.
 
-Please note, the following example gives a block that is outside of the function and therefore **won't** work:
-```
-    gibbon_export.list({:id => *list_id*}) do |row|
-        *do_sth_with* row
-    end
-```
+Gibbon::MailChimpError has the following attributes: `title`, `detail`, `body`, `raw_body`, `status_code`. Some or all of these may not be
+available depending on the nature of the error.
 
 ##Thanks
 
-Thanks to everyone who's [contributed](https://github.com/amro/gibbon/contributors) to Gibbon's development. Major props to The Viking for making MailChimp API 2.0 great.
+Thanks to everyone who has [contributed](https://github.com/amro/gibbon/contributors) to Gibbon's development.
 
 ##Copyright
 

data/gibbon.gemspec

@@ -9,12 +9,13 @@ Gem::Specification.new do |s|
   s.email       = ["amromousa@gmail.com"]
   s.homepage    = "http://github.com/amro/gibbon"
 
-  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.summary     = %q{A wrapper for MailChimp API 3.0}
+  s.description = %q{A wrapper for MailChimp API 3.0}
   s.license     = "MIT"
 
-  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.post_install_message = "IMPORTANT: Gibbon now targets MailChimp API 3.0, which is very different from API 2.0.\n \
+                            Please install Gibbon 1.2.0 if you need to use API 2.0.\nGibbon's API has changed substantially \
+                            between versions 1.x and 2.x."
 
   s.rubyforge_project = "gibbon"
 
@@ -22,11 +23,12 @@ Gem::Specification.new do |s|
   s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
   s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
   s.require_paths = ["lib"]
+  s.required_ruby_version = '>= 2.0.0'
 
-  s.add_dependency('httparty')
-  s.add_dependency('multi_json', '>= 1.9.0')
+  s.add_dependency('faraday', '>= 0.9.1')
+  s.add_dependency('multi_json', '>= 1.11.0')
 
   s.add_development_dependency 'rake'
-  s.add_development_dependency "rspec", "3.1.0"
+  s.add_development_dependency "rspec", "3.2.0"
 
 end

data/lib/gibbon.rb

@@ -1,12 +1,11 @@
-require 'httparty'
+require 'faraday'
 require 'multi_json'
 require 'cgi'
 
 require 'gibbon/gibbon_error'
 require 'gibbon/mailchimp_error'
-require 'gibbon/api_category'
-require 'gibbon/api'
-require 'gibbon/export'
+require 'gibbon/request'
+require 'gibbon/api_request'
 
 module Gibbon
 end

data/lib/gibbon/api_request.rb

@@ -0,0 +1,167 @@
+module Gibbon
+  class APIRequest
+    def initialize(builder: nil)
+      @request_builder = builder
+    end
+
+    def post(params: nil, headers: nil, body: nil)
+      validate_api_key
+
+      begin
+        response = self.rest_client.post do |request|
+          configure_request(request: request, params: params, headers: headers, body: MultiJson.dump(body))
+        end
+        parse_response(response.body)
+      rescue => e
+        handle_error(e)
+      end
+    end
+    
+    def patch(params: nil, headers: nil, body: nil)
+      validate_api_key
+
+      begin
+        response = self.rest_client.patch do |request|
+          configure_request(request: request, params: params, headers: headers, body: MultiJson.dump(body))
+        end
+        parse_response(response.body)
+      rescue => e
+        handle_error(e)
+      end
+    end
+    
+    def get(params: nil, headers: nil)
+      validate_api_key
+
+      begin
+        response = self.rest_client.get do |request|
+          configure_request(request: request, params: params, headers: headers)
+        end
+        parse_response(response.body)
+      rescue => e
+        handle_error(e)
+      end
+    end
+    
+    def delete(params: nil, headers: nil)
+      validate_api_key
+
+      begin
+        response = self.rest_client.delete do |request|
+          configure_request(request: request, params: params, headers: headers)
+        end
+        parse_response(response.body)
+      rescue => e
+        handle_error(e)
+      end
+    end
+
+    protected
+    
+    # Convenience accessors
+  
+    def api_key
+      @request_builder.api_key
+    end
+    
+    def api_endpoint
+      @request_builder.api_endpoint
+    end
+    
+    def timeout
+      @request_builder.timeout
+    end
+
+    # Helpers
+
+    def handle_error(error)
+      error_to_raise = nil
+
+      begin
+        error_to_raise = MailChimpError.new(error.message)
+
+        if error.is_a?(Faraday::Error::ClientError) && error.response
+          parsed_response = MultiJson.load(error.response[:body])
+
+          if parsed_response
+            error_to_raise.body = parsed_response
+            error_to_raise.title = parsed_response["title"] if parsed_response["title"]
+            error_to_raise.detail = parsed_response["detail"] if parsed_response["detail"]
+          end
+
+          error_to_raise.status_code = error.response[:status]
+          error_to_raise.raw_body = error.response[:body]
+        end
+      rescue MultiJson::ParseError
+        error_to_raise.message = error.message
+        error_to_raise.status_code = error.response[:status]
+      end
+
+      raise error_to_raise
+    end
+
+    def configure_request(request: nil, params: nil, headers: nil, body: nil)
+      if request
+        request.params.merge!(params) if params
+        request.headers['Content-Type'] = 'application/json'
+        request.headers.merge!(headers) if headers
+        request.body = body if body
+        request.options.timeout = self.timeout
+      end
+    end
+
+    def rest_client
+      client = Faraday.new(url: self.api_url) do |faraday|
+        faraday.response :raise_error
+        faraday.adapter Faraday.default_adapter
+      end
+      client.basic_auth('apikey', self.api_key)
+      client
+    end
+
+    def parse_response(response_body)
+      parsed_response = nil
+
+      if response_body && !response_body.empty?
+        begin
+          parsed_response = MultiJson.load(response_body)
+        rescue MultiJson::ParseError
+          error = MailChimpError.new("Unparseable response: #{response_body}")
+          error.title = "UNPARSEABLE_RESPONSE"
+          error.status_code = 500
+          raise error
+        end
+      end
+
+      parsed_response
+    end
+
+    def validate_api_key
+      api_key = self.api_key
+      unless api_key && (api_key["-"] || self.api_endpoint)
+        raise Gibbon::GibbonError, "You must set an api_key prior to making a call"
+      end
+    end
+
+    def api_url
+      base_api_url + @request_builder.path
+    end
+
+    def base_api_url
+      computed_api_endpoint = "https://#{get_data_center_from_api_key}api.mailchimp.com"
+      "#{self.api_endpoint || computed_api_endpoint}/3.0/"
+    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 self.api_key && self.api_key["-"]
+        # Add a period since the data_center is a subdomain and it keeps things dry
+        data_center = "#{self.api_key.split('-').last}."
+      end
+
+      data_center
+    end
+  end
+end