createsend 2.5.1 → 3.0.0

data/.travis.yml

@@ -1,6 +1,7 @@
 language: ruby
 rvm:
-  - 1.8.7
-  - 1.9.2
+  - 2.0.0
   - 1.9.3
+  - 1.9.2
+  - 1.8.7
   - ree

data/Gemfile.lock

@@ -1,37 +1,40 @@
 PATH
   remote: .
   specs:
-    createsend (2.5.1)
-      hashie (~> 1.0)
+    createsend (3.0.0)
+      hashie (>= 1.2, < 3)
       httparty (~> 0.10)
       json
 
 GEM
   remote: http://rubygems.org/
   specs:
-    activesupport (3.2.8)
+    activesupport (3.2.11)
       i18n (~> 0.6)
       multi_json (~> 1.0)
+    bourne (1.1.2)
+      mocha (= 0.10.5)
     fakeweb (1.3.0)
-    hashie (1.2.0)
+    hashie (2.0.3)
     httparty (0.10.2)
       multi_json (~> 1.0)
       multi_xml (>= 0.5.2)
     i18n (0.6.1)
     jnunemaker-matchy (0.4.0)
-    json (1.7.6)
+    json (1.7.7)
     metaclass (0.0.1)
-    mocha (0.13.2)
+    mocha (0.10.5)
       metaclass (~> 0.0.1)
-    multi_json (1.0.3)
-    multi_xml (0.5.2)
+    multi_json (1.5.0)
+    multi_xml (0.5.3)
     rake (10.0.3)
-    shoulda (3.3.0)
-      shoulda-context (~> 1.0)
-      shoulda-matchers (~> 1.4)
-    shoulda-context (1.0.0)
-    shoulda-matchers (1.4.0)
+    shoulda (3.3.2)
+      shoulda-context (~> 1.0.1)
+      shoulda-matchers (~> 1.4.1)
+    shoulda-context (1.0.2)
+    shoulda-matchers (1.4.2)
       activesupport (>= 3.0.0)
+      bourne (~> 1.1.2)
 
 PLATFORMS
   ruby
@@ -40,6 +43,5 @@ DEPENDENCIES
   createsend!
   fakeweb (~> 1.3)
   jnunemaker-matchy (~> 0.4)
-  mocha (~> 0.13)
   rake (~> 10.0)
   shoulda (~> 3.3)

data/HISTORY.md

@@ -1,13 +1,66 @@
 # createsend-ruby history
 
+## v3.0.0 - 25 Mar, 2013 (129ad0e)
+
+* Added support for authenticating using OAuth. See the [README](README.md#authenticating) for full usage instructions.
+* Refactored authentication so that it is _always_ done at the instance level. This introduces some breaking changes, which are clearly explained below.
+  * Authentication is now _always_ done at the instance level.
+
+      So when you _previously_ would have authenticated using an API key as follows:
+
+      ```ruby
+      CreateSend.api_key "your api key"
+      cs = CreateSend::CreateSend.new
+      cs.clients
+      ```
+
+      If you want to authenticate using an API key, you should _now_ do this:
+
+      ```ruby
+      auth = {:api_key => "your api key"}
+      cs = CreateSend::CreateSend.new auth
+      cs.clients
+      ```
+
+  * Instances of `CreateSend::CreateSend` (and all subclasses) are now _always_ created by passing an `auth` hash as the first argument.
+
+      So for example, when you _previously_ would have called `CreateSend::Client.new` like so:
+
+      ```ruby
+      CreateSend.api_key "your api key"
+      cl = CreateSend::Client.new "your client id"
+      ```
+
+      You _now_ call `CreateSend::Client.new` like so:
+
+      ```ruby
+      auth = {:api_key => "your api key"}
+      cl = CreateSend::Client.new auth, "your client id"
+      ```
+
+  * Any of the class methods on `CreateSend::CreateSend` (and all subclasses) are now _always_ called by passing an `auth` hash as the first argument.
+
+      So for example, when you _previously_ would have called `CreateSend::Subscriber.add` like so:
+
+      ```ruby
+      CreateSend.api_key "your api key"
+      sub = CreateSend::Subscriber.add "list id", "dave@example.com", "Dave", [], true
+      ```
+
+      You _now_ call `CreateSend::Subscriber.add` like so:
+
+      ```ruby
+      auth = {:api_key => "your api key"}
+      sub = CreateSend::Subscriber.add auth, "list id", "dave@example.com", "Dave", [], true
+      ```
+
 ## v2.5.1 - 4 Feb, 2013   (f0a35ae)
 
 * Updated dependencies in gemspec. Removed cane as a development dependency.
 
 ## v2.5.0 - 11 Dec, 2012   (3054885)
 
-* Added support for including from name, from email, and reply to email in
-drafts, scheduled, and sent campaigns.
+* Added support for including from name, from email, and reply to email in drafts, scheduled, and sent campaigns.
 * Added support for campaign text version urls.
 * Added support for transferring credits to/from a client.
 * Added support for getting account billing details as well as client credits.

data/LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2010-2012 James Dennes
+Copyright (c) 2010-2013 James Dennes
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.md

@@ -1,7 +1,7 @@
 # createsend
 [![Build Status](https://secure.travis-ci.org/campaignmonitor/createsend-ruby.png)][travis] [![Dependency Status](https://gemnasium.com/campaignmonitor/createsend-ruby.png)][gemnasium] [![Gem Version](https://badge.fury.io/rb/createsend.png)][gembadge]
 
-A ruby library which implements the complete functionality of v3 of the [Campaign Monitor API](http://www.campaignmonitor.com/api/).
+A ruby library which implements the complete functionality of the [Campaign Monitor API](http://www.campaignmonitor.com/api/).
 
 [travis]: http://travis-ci.org/campaignmonitor/createsend-ruby
 [gemnasium]: https://gemnasium.com/campaignmonitor/createsend-ruby
@@ -9,73 +9,191 @@ A ruby library which implements the complete functionality of v3 of the [Campaig
 
 ## Installation
 
-    gem install createsend
+To install:
 
-## Documentation
+```
+gem install createsend
+```
 
-Full documentation is hosted by [RubyDoc.info](http://rubydoc.info/gems/createsend/frames).
+Or, add a dependency to your `Gemfile` then `bundle install`.
 
-## Examples
+```ruby
+gem 'createsend'
+```
 
-### Basic usage
-This example of listing all your clients demonstrates basic usage of the library:
+## Authenticating
 
-    require 'createsend'
+The Campaign Monitor API supports authentication using either OAuth or an API key.
 
-    CreateSend.api_key 'your_api_key'
+### Using OAuth
 
-    cs = CreateSend::CreateSend.new
-    clients = cs.clients
-    
-    clients.each do |c|
-      puts "#{c.ClientID}: #{c.Name}"
-    end
+If you're developing a Rails or Rack based application, we recommend using [omniauth-createsend](https://github.com/jdennes/omniauth-createsend) to authenticate with the Campaign Monitor API. You might find this [example application](https://github.com/jdennes/createsendoauthtest) helpful.
 
-Running this example will result in something like:
+If you don't use [omniauth-createsend](https://github.com/jdennes/omniauth-createsend), you'll need to get access tokens for your users by following the instructions included in the Campaign Monitor API [documentation](http://www.campaignmonitor.com/api/getting-started/#authenticating_with_oauth). This gem provides functionality to help you do this, as described below. There's also another [example application](https://gist.github.com/jdennes/4945412) you may wish to reference, which doesn't depend on any OAuth libraries.
+
+The first thing your application should do is redirect your user to the Campaign Monitor authorization URL where they will have the opportunity to approve your application to access their Campaign Monitor account. You can get this authorization URL by using `CreateSend::CreateSend.authorize_url`, like so:
+
+```ruby
+require 'createsend'
+
+authorize_url = CreateSend::CreateSend.authorize_url(
+  'Client ID for your application',
+  'Redirect URI for your application',
+  'The permission level your application requires',
+  'Optional state data to be included'
+)
+# Redirect your users to authorize_url.
+```
+
+If your user approves your application, they will then be redirected to the `redirect_uri` you specified, which will include a `code` parameter, and optionally a `state` parameter in the query string. Your application should implement a handler which can exchange the code passed to it for an access token, using `CreateSend::CreateSend.exchange_token` like so:
+
+```ruby
+require 'createsend'
+
+access_token, expires_in, refresh_token = CreateSend::CreateSend.exchange_token(
+  'Client ID for your application',
+  'Client Secret for your application',
+  'Redirect URI for your application',
+  'A unique code for your user' # Get the code parameter from the query string
+)
+# Save access_token, expires_in, and refresh_token.
+```
+
+At this point you have an access token and refresh token for your user which you should store somewhere convenient so that your application can look up these values when your user wants to make future Campaign Monitor API calls.
+
+Once you have an access token and refresh token for your user, you can use the `createsend` gem to authenticate and make further API calls like so:
+
+```ruby
+require 'createsend'
 
-    4a397ccaaa55eb4e6aa1221e1e2d7122: Client One
-    a206def0582eec7dae47d937a4109cb2: Client Two
+auth = {
+  :access_token => 'your access token',
+  :refresh_token => 'your refresh token'
+}
+cs = CreateSend::CreateSend.new auth
+clients = cs.clients
+```
 
-### Handling errors
-If the Campaign Monitor API returns an error, an exception will be thrown. For example, if you attempt to create a campaign and enter empty values for subject etc:
+All OAuth tokens have an expiry time, and can be renewed with a corresponding refresh token. If your access token expires when attempting to make an API call, the `CreateSend::ExpiredOAuthToken` exception will be raised, so your code should handle this. Here's an example of how you could do this:
 
-    require 'createsend'
+```ruby
+require 'createsend'
 
-    CreateSend.api_key 'your_api_key'
+auth = {
+  :access_token => 'your access token',
+  :refresh_token => 'your refresh token'
+}
+cs = CreateSend::CreateSend.new auth
 
-    begin
-      cl = CreateSend::Client.new "4a397ccaaa55eb4e6aa1221e1e2d7122"
-      id = CreateSend::Campaign.create cl.client_id, "", "", "", "", "", "", "", [], []
-      puts "New campaign ID: #{id}"
-      rescue CreateSend::BadRequest => br
-        puts "Bad request error: #{br}"
-        puts "Error Code:    #{br.data.Code}"
-        puts "Error Message: #{br.data.Message}"
-      rescue Exception => e
-        puts "Error: #{e}"
-    end
+begin
+  tries ||= 2
+  clients = cs.clients
+  rescue CreateSend::ExpiredOAuthToken => eot
+    access_token, expires_in, refresh_token = cs.refresh_token
+    # Save your updated access token, expire in value, and refresh token
+    retry unless (tries -= 1).zero?
+    p "Error: #{eot}"
+  rescue Exception => e
+    p "Error: #{e}"
+end
+```
 
-Results in:
+### Using an API key
 
-    Bad request error: The CreateSend API responded with the following error - 304: Campaign Subject Required
-    Error Code:    304
-    Error Message: Campaign Subject Required
+```ruby
+require 'createsend'
+
+cs = CreateSend::CreateSend.new {:api_key => 'your api key'}
+clients = cs.clients
+```
+
+## Basic usage
+This example of listing all your clients and their campaigns demonstrates basic usage of the library and the data returned from the API:
+
+```ruby
+require 'createsend'
+
+auth = {
+  :access_token => 'your access token',
+  :refresh_token => 'your refresh token'
+}
+cs = CreateSend::CreateSend.new auth
+
+clients = cs.clients
+clients.each do |cl|
+  p "Client: #{cl.Name}"
+  client = CreateSend::Client.new auth, cl.ClientID
+  p "- Campaigns:"
+  client.campaigns.each do |cm|
+    p "  - #{cm.Subject}"
+  end
+end
+```
+
+Running this example will result in something like:
+
+```
+Client: First Client
+- Campaigns:
+  - Newsletter Number One
+  - Newsletter Number Two
+Client: Second Client
+- Campaigns:
+  - News for January 2013
+```
+
+## Handling errors
+If the Campaign Monitor API returns an error, an exception will be raised. For example, if you attempt to create a campaign and enter empty values for subject and other required fields:
+
+```ruby
+require 'createsend'
+
+auth = {
+  :access_token => 'your access token',
+  :refresh_token => 'your refresh token'
+}
+
+begin
+  id = CreateSend::Campaign.create auth, "4a397ccaaa55eb4e6aa1221e1e2d7122", "", "", "", "", "", "", "", [], []
+  p "New campaign ID: #{id}"
+  rescue CreateSend::BadRequest => br
+    p "Bad request error: #{br}"
+    p "Error Code:    #{br.data.Code}"
+    p "Error Message: #{br.data.Message}"
+  rescue Exception => e
+    p "Error: #{e}"
+end
+```
+
+Running this example will result in:
+
+```
+Bad request error: The CreateSend API responded with the following error - 304: Campaign Subject Required
+Error Code:    304
+Error Message: Campaign Subject Required
+```
 
 ### Expected input and output
 The best way of finding out the expected input and output of a particular method in a particular class is to use the unit tests as a reference.
 
 For example, if you wanted to find out how to call the CreateSend::Subscriber.add method, you would look at the file test/subscriber_test.rb
 
-    should "add a subscriber with custom fields" do
-      stub_post(@api_key, "subscribers/#{@list_id}.json", "add_subscriber.json")
-      custom_fields = [ { :Key => 'website', :Value => 'http://example.com/' } ]
-      email_address = CreateSend::Subscriber.add @list_id, "subscriber@example.com", "Subscriber", custom_fields, true
-      email_address.should == "subscriber@example.com"
-    end
+```ruby
+should "add a subscriber with custom fields" do
+  stub_post(@auth, "subscribers/#{@list_id}.json", "add_subscriber.json")
+  custom_fields = [ { :Key => 'website', :Value => 'http://example.com/' } ]
+  email_address = CreateSend::Subscriber.add @list_id, "subscriber@example.com", "Subscriber", custom_fields, true
+  email_address.should == "subscriber@example.com"
+end
+```
+
+## Documentation
+
+Full documentation is hosted by [RubyDoc.info](http://rubydoc.info/gems/createsend/frames).
 
 ## Contributing
 1. Fork the repository
 2. Make your changes, including tests for your changes.
-3. Ensure that the build passes, by running `bundle exec rake` (CI runs on: `1.8.7`, `1.9.2`, `1.9.3`, and `ree`)
+3. Ensure that the build passes, by running `bundle exec rake` (CI runs on: `2.0.0`, `1.9.3`, `1.9.2`, `1.8.7`, and `ree`)
 4. It should go without saying, but do not increment the version number in your commits.
 5. Submit a pull request.

data/createsend.gemspec

@@ -4,14 +4,13 @@ require 'bundler/version'
 require File.expand_path('lib/createsend/version')
 
 Gem::Specification.new do |s|
-  s.add_development_dependency('rake', '~> 10.0')
-  s.add_development_dependency('fakeweb', '~> 1.3')
-  s.add_development_dependency('jnunemaker-matchy', '~> 0.4')
-  s.add_development_dependency('mocha', '~> 0.13')
-  s.add_development_dependency('shoulda', '~> 3.3')
-  s.add_runtime_dependency('json', '>= 0')
-  s.add_runtime_dependency('hashie', '~> 1.0')
-  s.add_runtime_dependency('httparty', '~> 0.10')
+  s.add_development_dependency 'rake', '~> 10.0'
+  s.add_development_dependency 'fakeweb', '~> 1.3'
+  s.add_development_dependency 'jnunemaker-matchy', '~> 0.4'
+  s.add_development_dependency 'shoulda', '~> 3.3'
+  s.add_runtime_dependency 'json', '>= 0'
+  s.add_runtime_dependency 'hashie', ['>= 1.2', '< 3']
+  s.add_runtime_dependency 'httparty', '~> 0.10'
   s.name = "createsend"
   s.author = "James Dennes"
   s.description = %q{Implements the complete functionality of the Campaign Monitor API.}

data/lib/createsend.rb

@@ -1,12 +1,8 @@
-require 'cgi'
-require 'uri'
-require 'httparty'
-require 'hashie'
-
 libdir = File.dirname(__FILE__)
 $LOAD_PATH.unshift(libdir) unless $LOAD_PATH.include?(libdir)
 
 require 'createsend/version'
+require 'createsend/createsend'
 require 'createsend/client'
 require 'createsend/campaign'
 require 'createsend/list'
@@ -15,154 +11,3 @@ require 'createsend/subscriber'
 require 'createsend/template'
 require 'createsend/person'
 require 'createsend/administrator'
-
-module CreateSend
-
-  # Just allows callers to do CreateSend.api_key "..." rather than
-  # CreateSend::CreateSend.api_key "..." etc
-  class << self
-    def api_key(api_key=nil)
-      r = CreateSend.api_key api_key
-    end
-
-    def base_uri(uri)
-      r = CreateSend.base_uri uri
-    end
-  end
-
-  # Represents a CreateSend API error. Contains specific data about the error.
-  class CreateSendError < StandardError
-    attr_reader :data
-    def initialize(data)
-      @data = data
-      # @data should contain Code, Message and optionally ResultData
-      extra = @data.ResultData ? "\nExtra result data: #{@data.ResultData}" : ""
-      super "The CreateSend API responded with the following error"\
-            " - #{@data.Code}: #{@data.Message}#{extra}"
-    end
-  end
-
-  # Raised for HTTP response codes of 400...500
-  class ClientError < StandardError; end
-  # Raised for HTTP response codes of 500...600
-  class ServerError < StandardError; end
-  # Raised for HTTP response code of 400
-  class BadRequest < CreateSendError; end
-  # Raised for HTTP response code of 401
-  class Unauthorized < CreateSendError; end
-  # Raised for HTTP response code of 404
-  class NotFound < ClientError; end
-
-  # Provides high level CreateSend functionality/data you'll probably need.
-  class CreateSend
-    include HTTParty
-
-    # Deals with an unfortunate situation where responses aren't valid json.
-    class Parser::DealWithCreateSendInvalidJson < HTTParty::Parser
-      # The createsend API returns an ID as a string when a 201 Created
-      # response is returned. Unfortunately this is invalid json.
-      def parse
-        begin
-          super
-        rescue MultiJson::DecodeError => e
-          body[1..-2] # Strip surrounding quotes and return as is.
-        end
-      end
-    end
-    parser Parser::DealWithCreateSendInvalidJson
-    @@base_uri = "https://api.createsend.com/api/v3"
-    @@api_key = ""
-    headers({
-      'User-Agent' => "createsend-ruby-#{VERSION}",
-      'Content-Type' => 'application/json; charset=utf-8',
-      'Accept-Encoding' => 'gzip, deflate' })
-    base_uri @@base_uri
-    basic_auth @@api_key, 'x'
-
-    # Sets the API key which will be used to make calls to the CreateSend API.
-    def self.api_key(api_key=nil)
-      return @@api_key unless api_key
-      @@api_key = api_key
-      basic_auth @@api_key, 'x'
-    end
-
-    # Gets your CreateSend API key, given your site url, username and password.
-    def apikey(site_url, username, password)
-      site_url = CGI.escape(site_url)
-      self.class.basic_auth username, password
-      response = CreateSend.get("/apikey.json?SiteUrl=#{site_url}")
-      # Revert basic_auth to use @@api_key, 'x'
-      self.class.basic_auth @@api_key, 'x'
-      Hashie::Mash.new(response)
-    end
-
-    # Gets your clients.
-    def clients
-      response = CreateSend.get('/clients.json')
-      response.map{|item| Hashie::Mash.new(item)}
-    end
-
-    # Get your billing details.
-    def billing_details
-      response = CreateSend.get('/billingdetails.json')
-      Hashie::Mash.new(response)
-    end
-
-    # Gets valid countries.
-    def countries
-      response = CreateSend.get('/countries.json')
-      response.parsed_response
-    end
-
-    # Gets the current date in your account's timezone.
-    def systemdate
-      response = CreateSend.get('/systemdate.json')
-      Hashie::Mash.new(response)
-    end
-
-    # Gets valid timezones.
-    def timezones
-      response = CreateSend.get('/timezones.json')
-      response.parsed_response
-    end
-
-    # Gets the administrators
-    def administrators
-      response = CreateSend.get('/admins.json')
-      response.map{|item| Hashie::Mash.new(item)}
-    end
-
-    def get_primary_contact
-      response = CreateSend.get('/primarycontact.json')
-      Hashie::Mash.new(response)
-    end
-
-    def set_primary_contact(email)
-      options = { :query => { :email => email } }
-      response = CreateSend.put("/primarycontact.json", options)
-      Hashie::Mash.new(response)
-    end
-
-    def self.get(*args); handle_response super end
-    def self.post(*args); handle_response super end
-    def self.put(*args); handle_response super end
-    def self.delete(*args); handle_response super end
-
-    def self.handle_response(response) # :nodoc:
-      case response.code
-      when 400
-        raise BadRequest.new(Hashie::Mash.new response)
-      when 401
-        raise Unauthorized.new(Hashie::Mash.new response)
-      when 404
-        raise NotFound.new
-      when 400...500
-        raise ClientError.new
-      when 500...600
-        raise ServerError.new
-      else
-        response
-      end
-    end
-  end
-end