gibbon 2.0.0 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 6f3bc3884010b6bc30397d25c746ca29f6b026cf
-  data.tar.gz: acf67934d1a27976e15324502773b0029978f3a9
+  metadata.gz: f67c204c24ccb1e88465da9491083990cda98d84
+  data.tar.gz: d7ee83c9782fdd6a9664a0e0e1095f82fa7d14cd
 SHA512:
-  metadata.gz: 72ddec2ab87bdb95d5bcb25f0728eeece2a70daaf49a990444c2dfd4b97c28e093c07b644a0538383684e05482977ec8eeb7c4d4210e7d5e25aa8bd2710a5835
-  data.tar.gz: a20ba104983c405b478dad32c3cc507521c80dd3b36e39cf1d208201bf526a1bc02eec889b370ad946b39a4f83988db648ed8de01f58e1a2dd9dd30d44ea7b72
+  metadata.gz: 4f298cdbe7fc035c0be9078e9ce9c0baa37f95d97ddaba121c55be7e3b9d5e95227f0fc228448aeb9e31417d7222a0ed4f91c1b4b1a0bfb06c2c33879c154ac1
+  data.tar.gz: b0c0012892ca2d80bb1f6ea012f03d7586510fa9ed6c965d1179a04f79cb17003469be6c5af71197ecb236659de7df57bce228b50e52753aeae20751c1f5a1cf

data/.travis.yml

@@ -1,6 +1,6 @@
 language: ruby
-before_install: gem install bundler -v 1.5.1
-install: bundle install --retry=3
+sudo: false
+cache: bundler
 rvm:
   - 2.0.0
   - 2.1.5

data/CHANGELOG.md

@@ -1,5 +1,8 @@
 ## [Unreleased][unreleased]
 
+## [2.1.0] - 2015-10-12
+- Upsert support
+
 ## [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

data/README.markdown

@@ -29,7 +29,7 @@ You can set an individual request's timeout like this:
     gibbon.timeout = 10
 
 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.
+are specified inline and a `CRUD` (`create`, `retrieve`, `update`, `upsert`, or `delete`) verb initiates the request. `upsert` lets you update a record, if it exists, or insert it otherwise where supported by MailChimp's API.
 
     gibbon.lists.retrieve
 
@@ -60,45 +60,80 @@ Assuming you've set an `api_key` on Gibbon, you can conveniently make API calls
 
 You can also set the environment variable `MAILCHIMP_API_KEY` and Gibbon will use it when you create an instance:
 
-    gb = Gibbon::Request.new
+    gibbon = Gibbon::Request.new
 
 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.
 
 ### Fetching Campaigns
 
-
     campaigns = gb.campaigns.retrieve
 
 ### Fetching Lists
 
 Similarly, to fetch your lists
 
-    lists = gb.lists.retrieve
+    lists = gibbon.lists.retrieve
 
 ### More Advanced Examples
 
 List subscribers for a list:
 
-    gb.lists(list_id).members.retrieve
+    gibbon.lists(list_id).members.retrieve
 
 Subscribe a member to a list:
 
-    gb.lists(list_id).members.create(body: {email_address: "email_address", status: "subscribed", merge_fields: {FNAME: "First Name", LNAME: "Last Name"}})
+    gibbon.lists(list_id).members.create(body: {email_address: "email_address", status: "subscribed", merge_fields: {FNAME: "First Name", LNAME: "Last Name"}})
+
+Note: You could call `upsert` instead of `create` in the example above to update the member if they already exist or subscribe them if they do not.
 
 You can also unsubscribe a member from a list:
 
-    gb.lists(list_id).members(member_id).update(body: { status: "unsubscribed" })
+    gibbon.lists(list_id).members(member_id).update(body: { status: "unsubscribed" })
 
 Fetch the number of opens for a campaign
 
-    email_stats = gb.reports("13e9a94053").retrieve["opens"]
+    email_stats = gibbon.reports(campaign_id).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::Request.api_endpoint = "https://us1.api.mailchimp.com"
     Gibbon::Request.api_key = your_access_token_or_api_key
 
+### Interests
+
+Interests are a little more complicated than other parts of the API, so here's an example of how you would set interests during at subscription time or update them later. The ID of the interests you want to opt in or out of must be known ahead of time so an example of how to find interest IDs is also included.
+
+Subscribing a member to a list with specific interests up front:
+
+    g.lists(list_id).members.create(body: {email_address: user_email_address, status: "subscribed", interests: {some_interest_id: true, another_interest_id: true}})
+
+Updating a list member's interests:
+
+    gibbon.lists(list_id).members(member_id).update(body: {interests: {some_interest_id: true, another_interest_id: false}})
+
+So how do we get the interest IDs? When you query the API for a specific list member's information:
+
+    g.lists(list_id).members(member_id).retrieve
+
+The response looks someting like this (unrelated things removed):
+
+    {"id"=>"...", "email_address"=>"...", ..., "interests"=>{"3def637141"=>true, "f7cc4ee841"=>false, "fcdc951b9f"=>false, "3daf3cf27d"=>true, "293a3703ed"=>false, "72370e0d1f"=>false, "d434d21a1c"=>false, "bdb1ff199f"=>false, "a54e78f203"=>false, "c4527fd018"=>false} ...}
+
+The API returns a map of interest ID to boolean value. Now we to get interest details so we know what these interest IDs map to. Looking at [this doc page](http://kb.mailchimp.com/api/resources/lists/interest-categories/interests/lists-interests-collection), we need to do this:
+
+    g.lists(list_id).interest_categories.retrieve
+
+To get a list of interest categories. That gives us something like:
+
+    {"list_id"=>"...", "categories"=>[{"list_id"=>"...", "id"=>"0ace7aa498", "title"=>"Food Preferences", ...}] ...}
+
+In this case, we're interested in the ID of the "Food Preferences" interest, which is `0ace7aa498`. Now we can fetch the details for this interest group:
+
+    g.lists(list_id).interest_categories("0ace7aa498").interests.retrieve
+
+That response gives the interest data, including the ID for the interests themselves, which we can use to update a list member's interests or set them when we call the API to subscribe her or him to a list.
+
 ### Error handling
 
 Gibbon raises an error when the API returns an error.
@@ -106,6 +141,52 @@ Gibbon raises an error when the API returns an error.
 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.
 
+### Migrating from Gibbon 1.x
+
+Gibbon 2.x has different syntax from version 1.x. This is because Gibbon maps to MailChimp's API and because version 3 of the API is quite different from version 2. First, the name of the primary class has changed from `API` to `Request`. And the way you pass an API key during initialization is different. A few examples below.
+
+#### Initialization
+
+Gibbon 1.x:
+
+    gibbon = Gibbon::API.new("your_api_key")
+    
+Gibbon 2.x:
+
+    gibbon = Gibbon::Request.new(api_key: "your_api_key")
+
+MailChimp API 3 is a RESTful API, so Gibbon's syntax now requires a trailing call to a verb, as described above.
+
+#### Fetching Lists
+
+Gibbon 1.x:
+
+    gibbon.lists.list
+    
+Gibbon 2.x:
+
+    gibbon.lists.retrieve
+
+#### Fetching List Members
+
+Gibbon 1.x:
+
+    gibbon.lists.members({:id => list_id})
+    
+Gibbon 2.x:
+
+    gibbon.lists(list_id).members.retrieve
+
+#### Subscribing a Member to a List
+
+Gibbon 1.x:
+
+    gibbon.lists.subscribe({:id => list_id, :email => {:email => "email_address"}, :merge_vars => {:FNAME => "Bob", :LNAME => "Smith"}})
+    
+Gibbon 2.x:
+
+    gibbon.lists(list_id).members.create(body: {email_address: "email_address", status: "subscribed", merge_fields: {FNAME: "Bob", LNAME: "Smith"}})
+
 ##Thanks
 
 Thanks to everyone who has [contributed](https://github.com/amro/gibbon/contributors) to Gibbon's development.

data/gibbon.gemspec

@@ -30,5 +30,6 @@ Gem::Specification.new do |s|
 
   s.add_development_dependency 'rake'
   s.add_development_dependency "rspec", "3.2.0"
+  s.add_development_dependency 'webmock', '~> 1.21.0'
 
 end

data/lib/gibbon/api_request.rb

@@ -29,6 +29,19 @@ module Gibbon
         handle_error(e)
       end
     end
+
+    def put(params: nil, headers: nil, body: nil)
+      validate_api_key
+
+      begin
+        response = self.rest_client.put 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

data/lib/gibbon/request.rb

@@ -36,6 +36,12 @@ module Gibbon
       reset
     end
 
+    def upsert(params: nil, headers: nil, body: nil)
+      APIRequest.new(builder: self).put(params: params, headers: headers, body: body)
+    ensure
+      reset
+    end
+
     def retrieve(params: nil, headers: nil)
       APIRequest.new(builder: self).get(params: params, headers: headers)
     ensure

data/lib/gibbon/version.rb

@@ -1,3 +1,3 @@
 module Gibbon
-  VERSION = "2.0.0"
+  VERSION = "2.1.0"
 end

data/spec/gibbon/upsert_spec.rb

@@ -0,0 +1,28 @@
+require 'spec_helper'
+require 'webmock/rspec'
+require 'digest/md5'
+
+describe Gibbon do
+  let(:api_key) { '1234-us1' }
+  let(:list_id) { 'testlist' }
+  let(:email) { 'john.doe@example.com' }
+  let(:member_id) { Digest::MD5.hexdigest(email) }
+
+  let(:request_body) do
+    {
+      email_address: email,
+      status: 'subscribed',
+      merge_fields: {FNAME: 'John', LNAME: 'Doe'}
+    }
+  end
+
+  it 'supports upsert request' do
+    stub_request(:put, "https://apikey:1234-us1@us1.api.mailchimp.com/3.0/lists/#{list_id}/members/#{member_id}")
+      .with(body: MultiJson.dump(request_body))
+      .to_return(status: 200)
+
+    Gibbon::Request.new(api_key: api_key)
+      .lists(list_id).members(member_id)
+      .upsert(body: request_body)
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: gibbon
 version: !ruby/object:Gem::Version
-  version: 2.0.0
+  version: 2.1.0
 platform: ruby
 authors:
 - Amro Mousa
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-07-29 00:00:00.000000000 Z
+date: 2015-10-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -66,6 +66,20 @@ dependencies:
     - - '='
       - !ruby/object:Gem::Version
         version: 3.2.0
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.21.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.21.0
 description: A wrapper for MailChimp API 3.0
 email:
 - amromousa@gmail.com
@@ -89,6 +103,7 @@ files:
 - lib/gibbon/request.rb
 - lib/gibbon/version.rb
 - spec/gibbon/gibbon_spec.rb
+- spec/gibbon/upsert_spec.rb
 - spec/spec_helper.rb
 homepage: http://github.com/amro/gibbon
 licenses:
@@ -119,4 +134,5 @@ specification_version: 4
 summary: A wrapper for MailChimp API 3.0
 test_files:
 - spec/gibbon/gibbon_spec.rb
+- spec/gibbon/upsert_spec.rb
 - spec/spec_helper.rb