nexmo 1.0.0 → 1.1.0

data/README.md

@@ -1,5 +1,5 @@
-A simple wrapper for the [Nexmo](http://nexmo.com/) API
-=======================================================
+A Ruby wrapper for the [Nexmo](http://nexmo.com/) API
+=====================================================
 
 
 Installation
@@ -8,32 +8,89 @@ Installation
     $ gem install nexmo
 
 
-Quick Start
------------
+Quick start (sending a message)
+-------------------------------
 
-Use the `send_message!` for a "fire and forget" approach to sending a message:
+First you need to load up the gem and construct a Nexmo::Client object
+with your API credentials, like this:
 
 ```ruby
 require 'nexmo'
 
 nexmo = Nexmo::Client.new('...API KEY...', '...API SECRET...')
+```
+
+Then you have a choice. For a "fire and forget" approach to sending a message,
+use the `send_message!` method, like this:
 
+```ruby
 nexmo.send_message!({:to => '...NUMBER...', :from => 'Ruby', :text => 'Hello world'})
 ```
 
 This method call returns the message id if the message was sent successfully,
-or raises an exception if there was an error. For more robust error handling
-use the `send_message` method instead. This returns the HTTP response wrapped
-in a `Nexmo::Response` object.
+or raises an exception if there was an error. If you need more robust error
+handling use the `send_message` method instead, like this:
+
+```ruby
+response = nexmo.send_message({:to => '...NUMBER...', :from => 'Ruby', :text => 'Hello world'})
+
+if response.ok?
+  # do something with response.object
+else
+  # handle the error
+end
+```
+
+This method call returns a `Nexmo::Response` object, which wraps the underlying
+Net::HTTP response and adds a few convenience methods. Additional methods are
+also provided for managing your account and messages.
+
+
+Authenticating with OAuth (beta)
+--------------------------------
+
+If you are building an app that needs access to Nexmo resources on behalf of
+other accounts then you will want to use OAuth to authenticate your requests.
+Authorizing access and fetching access tokens can be achieved using the
+[oauth gem](http://rubygems.org/gems/oauth) directly. You can then use an
+OAuth::AccessToken object together with a Nexmo::Client object to make calls
+to the API that are authenticated using OAuth. For example:
+
+```ruby
+require 'nexmo'
+require 'oauth'
+
+nexmo = Nexmo::Client.new
+nexmo.oauth_access_token = OAuth::AccessToken.new(consumer, token, secret)
+
+response = nexmo.get_balance
+
+if response.ok?
+  # do something with response.object
+else
+  # handle the error
+end
+```
+
+The OAuth::Consumer object should be pointed at `rest.nexmo.com` with the `:scheme` option set to `:header`, like this:
+
+```ruby
+OAuth::Consumer.new(consumer_key, consumer_secret, {
+  :site => 'https://rest.nexmo.com',
+  :scheme => :header
+})
+```
+
+Using the `:body` or `:query_string` authorization mechanisms is not supported.
 
 
-JSON Implementation
--------------------
+Switching JSON implementations
+------------------------------
 
-The "json" library is used by default. This is available in the Ruby 1.9
-standard library, and as a gem for Ruby 1.8. You can specify an alternate
-implementation that you wish to use explicitly when constructing a client
-object. For example, to use [multi_json](https://rubygems.org/gems/multi_json):
+By default the "json" library is used to encode request bodies and decode response
+bodies. This is available in the Ruby 1.9 standard library, and as a gem for Ruby 1.8.
+You can specify an alternate implementation that you wish to use explicitly when
+constructing a client object. For example, to use [multi_json](https://rubygems.org/gems/multi_json):
 
 ```ruby
 require 'nexmo'

data/lib/nexmo.rb

@@ -5,7 +5,7 @@ require 'cgi'
 
 module Nexmo
   class Client
-    def initialize(key, secret, options = {})
+    def initialize(key = ENV['NEXMO_API_KEY'], secret = ENV['NEXMO_API_SECRET'], options = {})
       @key, @secret = key, secret
 
       @json = options.fetch(:json) { JSON }
@@ -15,7 +15,7 @@ module Nexmo
       @http.use_ssl = true
     end
 
-    attr_accessor :key, :secret, :http
+    attr_accessor :key, :secret, :http, :oauth_access_token
 
     def send_message(params)
       post('/sms/json', params)
@@ -40,49 +40,57 @@ module Nexmo
     end
 
     def get_balance
-      get("/account/get-balance/#{key}/#{secret}")
+      get('/account/get-balance')
     end
 
     def get_country_pricing(country_code)
-      get("/account/get-pricing/outbound/#{key}/#{secret}/#{country_code}")
+      get('/account/get-pricing/outbound', {:country => country_code})
     end
 
     def get_prefix_pricing(prefix)
-      get("/account/get-prefix-pricing/outbound/#{key}/#{secret}/#{prefix}")
+      get('/account/get-prefix-pricing/outbound', {:prefix => prefix})
     end
 
     def get_account_numbers(params)
-      get("/account/numbers/#{key}/#{secret}", params)
+      get('/account/numbers', params)
     end
 
     def number_search(country_code, params = {})
-      get("/number/search/#{key}/#{secret}/#{country_code}", params)
+      get('/number/search', {:country => country_code}.merge(params))
     end
 
     def get_message(id)
-      get("/search/message/#{key}/#{secret}/#{id}")
+      get('/search/message', {:id => id})
     end
 
     def get_message_rejections(params)
-      get("/search/rejections/#{key}/#{secret}", params)
+      get('/search/rejections', params)
     end
 
     def search_messages(params)
-      get("/search/messages/#{key}/#{secret}", Hash === params ? params : {:ids => Array(params)})
+      get('/search/messages', Hash === params ? params : {:ids => Array(params)})
     end
 
     private
 
     def get(path, params = {})
-      Response.new(@http.get(request_uri(path, params)), :json => @json)
+      http_response = if oauth_access_token
+        oauth_access_token.get(request_uri(path, params))
+      else
+        @http.get(request_uri(path, params.merge(:api_key => @key, :api_secret => @secret)))
+      end
+
+      Response.new(http_response, :json => @json)
     end
 
     def post(path, params)
-      Response.new(@http.post(path, encode(params), {'Content-Type' => 'application/json'}), :json => @json)
-    end
+      http_response = if oauth_access_token
+        oauth_access_token.post(path, @json.dump(params), {'Content-Type' => 'application/json'})
+      else
+        @http.post(path, @json.dump(params.merge(:api_key => @key, :api_secret => @secret)), {'Content-Type' => 'application/json'})
+      end
 
-    def encode(params)
-      JSON.dump(params.merge(:username => @key, :password => @secret))
+      Response.new(http_response, :json => @json)
     end
 
     def request_uri(path, hash = {})

data/nexmo.gemspec

@@ -1,16 +1,17 @@
 Gem::Specification.new do |s|
   s.name = 'nexmo'
-  s.version = '1.0.0'
+  s.version = '1.1.0'
   s.platform = Gem::Platform::RUBY
   s.authors = ['Tim Craft']
   s.email = ['mail@timcraft.com']
   s.homepage = 'http://github.com/timcraft/nexmo'
-  s.description = 'A simple wrapper for the Nexmo API'
+  s.description = 'A Ruby wrapper for the Nexmo API'
   s.summary = 'See description'
   s.files = Dir.glob('{lib,spec}/**/*') + %w(README.md nexmo.gemspec)
   s.add_development_dependency('rake', '>= 0.9.3')
-  s.add_development_dependency('mocha', '~> 0.10.3')
+  s.add_development_dependency('mocha', '~> 0.13.2')
   s.add_development_dependency('multi_json', '~> 1.3.6')
+  s.add_development_dependency('oauth', '~> 0.4.7')
   s.require_path = 'lib'
 
   if RUBY_VERSION == '1.8.7'

data/spec/nexmo_spec.rb

@@ -1,53 +1,51 @@
 require 'minitest/autorun'
-require 'mocha'
+require 'mocha/setup'
 require 'multi_json'
 require 'nexmo'
+require 'oauth'
 
 describe 'Nexmo::Client' do
   before do
+    @json_encoded_body = regexp_matches(/\{".+?":".+?"(,".+?":".+?")+\}/)
+
+    @http_header_hash = has_entry('Content-Type', 'application/json')
+
+    @example_message_hash = {:from => 'ruby', :to => 'number', :text => 'Hey!'}
+
     @client = Nexmo::Client.new('key', 'secret')
   end
 
+  def expects_http_get(request_uri)
+    @client.http.expects(:get).with(has_equivalent_query_string(request_uri)).returns(stub)
+  end
+
   describe 'http method' do
     it 'returns a net http object that uses ssl' do
       @client.http.must_be_instance_of(Net::HTTP)
+
       @client.http.use_ssl?.must_equal(true)
     end
   end
 
   describe 'send_message method' do
     it 'posts to the sms json resource and returns a response object' do
-      data = regexp_matches(/\{".+?":".+?"(,".+?":".+?")+\}/)
+      @client.http.expects(:post).with('/sms/json', @json_encoded_body, @http_header_hash).returns(stub)
 
-      headers = has_entry('Content-Type', 'application/json')
-
-      params = {:from => 'ruby', :to => 'number', :text => 'Hey!'}
-
-      @client.http.expects(:post).with('/sms/json', data, headers).returns(stub)
-
-      @client.send_message(params).must_be_instance_of(Nexmo::Response)
+      @client.send_message(@example_message_hash).must_be_instance_of(Nexmo::Response)
     end
   end
 
   describe 'send_message bang method' do
     before do
-      @params = {:from => 'ruby', :to => 'number', :text => 'Hey!'}
-
-      @http_response = mock()
-      @http_response.stubs(:[]).with('Content-Type').returns('application/json;charset=utf-8')
-      @http_response.stubs(:code).returns('200')
+      @http_response = stub(:code => '200', :[] => 'application/json;charset=utf-8')
     end
 
     it 'posts to the sms json resource and returns the message id' do
-      data = regexp_matches(/\{".+?":".+?"(,".+?":".+?")+\}/)
-
-      headers = has_entry('Content-Type', 'application/json')
-
       @http_response.stubs(:body).returns('{"messages":[{"status":0,"message-id":"id"}]}')
 
-      @client.http.expects(:post).with('/sms/json', data, headers).returns(@http_response)
+      @client.http.expects(:post).with('/sms/json', @json_encoded_body, @http_header_hash).returns(@http_response)
 
-      @client.send_message!(@params).must_equal('id')
+      @client.send_message!(@example_message_hash).must_equal('id')
     end
 
     it 'raises an exception if the response code is not expected' do
@@ -55,7 +53,7 @@ describe 'Nexmo::Client' do
 
       @client.http.stubs(:post).returns(@http_response)
 
-      proc { @client.send_message!(@params) }.must_raise(Nexmo::Error)
+      proc { @client.send_message!(@example_message_hash) }.must_raise(Nexmo::Error)
     end
 
     it 'raises an exception if the response body contains an error' do
@@ -63,13 +61,13 @@ describe 'Nexmo::Client' do
 
       @client.http.stubs(:post).returns(@http_response)
 
-      proc { @client.send_message!(@params) }.must_raise(Nexmo::Error)
+      proc { @client.send_message!(@example_message_hash) }.must_raise(Nexmo::Error)
     end
   end
 
   describe 'get_balance method' do
     it 'fetches the account balance resource and returns a response object' do
-      @client.http.expects(:get).with('/account/get-balance/key/secret').returns(stub)
+      expects_http_get '/account/get-balance?api_key=key&api_secret=secret'
 
       @client.get_balance.must_be_instance_of(Nexmo::Response)
     end
@@ -77,7 +75,7 @@ describe 'Nexmo::Client' do
 
   describe 'get_country_pricing method' do
     it 'fetches the outbound pricing resource for the given country and returns a response object' do
-      @client.http.expects(:get).with('/account/get-pricing/outbound/key/secret/CA').returns(stub)
+      expects_http_get '/account/get-pricing/outbound?api_key=key&api_secret=secret&country=CA'
 
       @client.get_country_pricing(:CA).must_be_instance_of(Nexmo::Response)
     end
@@ -85,7 +83,7 @@ describe 'Nexmo::Client' do
 
   describe 'get_prefix_pricing method' do
     it 'fetches the outbound pricing resource for the given prefix and returns a response object' do
-      @client.http.expects(:get).with('/account/get-prefix-pricing/outbound/key/secret/44').returns(stub)
+      expects_http_get '/account/get-prefix-pricing/outbound?api_key=key&api_secret=secret&prefix=44'
 
       @client.get_prefix_pricing(44).must_be_instance_of(Nexmo::Response)
     end
@@ -93,7 +91,7 @@ describe 'Nexmo::Client' do
 
   describe 'get_account_numbers method' do
     it 'fetches the account numbers resource with the given parameters and returns a response object' do
-      @client.http.expects(:get).with(has_equivalent_query_string('/account/numbers/key/secret?size=25&pattern=33')).returns(stub)
+      expects_http_get '/account/numbers?api_key=key&api_secret=secret&size=25&pattern=33'
 
       @client.get_account_numbers(:size => 25, :pattern => 33).must_be_instance_of(Nexmo::Response)
     end
@@ -101,7 +99,7 @@ describe 'Nexmo::Client' do
 
   describe 'number_search method' do
     it 'fetches the number search resource for the given country with the given parameters and returns a response object' do
-      @client.http.expects(:get).with('/number/search/key/secret/CA?size=25').returns(stub)
+      expects_http_get '/number/search?api_key=key&api_secret=secret&country=CA&size=25'
 
       @client.number_search(:CA, :size => 25).must_be_instance_of(Nexmo::Response)
     end
@@ -109,7 +107,7 @@ describe 'Nexmo::Client' do
 
   describe 'get_message method' do
     it 'fetches the message search resource for the given message id and returns a response object' do
-      @client.http.expects(:get).with('/search/message/key/secret/00A0B0C0').returns(stub)
+      expects_http_get '/search/message?api_key=key&api_secret=secret&id=00A0B0C0'
 
       @client.get_message('00A0B0C0').must_be_instance_of(Nexmo::Response)
     end
@@ -117,7 +115,7 @@ describe 'Nexmo::Client' do
 
   describe 'get_message_rejections method' do
     it 'fetches the message rejections resource with the given parameters and returns a response object' do
-      @client.http.expects(:get).with('/search/rejections/key/secret?date=YYYY-MM-DD').returns(stub)
+      expects_http_get '/search/rejections?api_key=key&api_secret=secret&date=YYYY-MM-DD'
 
       @client.get_message_rejections(:date => 'YYYY-MM-DD').must_be_instance_of(Nexmo::Response)
     end
@@ -125,17 +123,59 @@ describe 'Nexmo::Client' do
 
   describe 'search_messages method' do
     it 'fetches the search messages resource with the given parameters and returns a response object' do
-      @client.http.expects(:get).with(has_equivalent_query_string('/search/messages/key/secret?date=YYYY-MM-DD&to=1234567890')).returns(stub)
+      expects_http_get '/search/messages?api_key=key&api_secret=secret&date=YYYY-MM-DD&to=1234567890'
 
       @client.search_messages(:date => 'YYYY-MM-DD', :to => 1234567890).must_be_instance_of(Nexmo::Response)
     end
 
     it 'should encode a non hash argument as a list of ids' do
-      @client.http.expects(:get).with(has_equivalent_query_string('/search/messages/key/secret?ids=id1&ids=id2')).returns(stub)
+      expects_http_get '/search/messages?api_key=key&api_secret=secret&ids=id1&ids=id2'
 
       @client.search_messages(%w(id1 id2))
     end
   end
+
+  describe 'when initialized with an oauth access token' do
+    before do
+      @oauth_consumer = OAuth::Consumer.new('key', 'secret', {:site => 'https://rest.nexmo.com', :scheme => :header})
+
+      @oauth_access_token = OAuth::AccessToken.new(@oauth_consumer, 'access_token', 'access_token_secret')
+
+      @client = Nexmo::Client.new
+
+      @client.oauth_access_token = @oauth_access_token
+
+      @client.http = mock()
+    end
+
+    it 'makes get requests through the access token and returns a response object' do
+      @oauth_access_token.expects(:get).with('/account/get-pricing/outbound?country=CA').returns(stub)
+
+      @client.get_country_pricing(:CA).must_be_instance_of(Nexmo::Response)
+    end
+
+    it 'makes post requests through the access token and returns a response object' do
+      @oauth_access_token.expects(:post).with('/sms/json', @json_encoded_body, @http_header_hash).returns(stub)
+
+      @client.send_message(@example_message_hash).must_be_instance_of(Nexmo::Response)
+    end
+  end
+
+  describe 'when initialized with a different json implementation' do
+    before do
+      @client = Nexmo::Client.new('key', 'secret', :json => MultiJson)
+    end
+
+    describe 'send_message method' do
+      it 'encodes the request body using the alternative json implementation' do
+        MultiJson.expects(:dump).with(instance_of(Hash))
+
+        @client.http.stubs(:post)
+
+        @client.send_message(@example_message_hash)
+      end
+    end
+  end
 end
 
 describe 'Nexmo::Response' do
@@ -187,20 +227,20 @@ describe 'Nexmo::Response' do
       @response.object.must_equal({'value' => 0})
     end
   end
-end
 
-describe 'Nexmo::Response initialized with a different json implementation' do
-  before do
-    @http_response = mock()
+  describe 'when initialized with a different json implementation' do
+    before do
+      @response = Nexmo::Response.new(@http_response, :json => MultiJson)
+    end
 
-    @response = Nexmo::Response.new(@http_response, :json => MultiJson)
-  end
+    describe 'object method' do
+      it 'decodes the response body using the alternative json implementation' do
+        MultiJson.expects(:load).with('{"value":0.0}')
 
-  describe 'object method' do
-    it 'decodes the response body as json and returns a hash' do
-      @http_response.expects(:body).returns('{"value":0.0}')
+        @http_response.stubs(:body).returns('{"value":0.0}')
 
-      @response.object.must_equal({'value' => 0})
+        @response.object
+      end
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: nexmo
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-11-16 00:00:00.000000000 Z
+date: 2013-02-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
@@ -34,7 +34,7 @@ dependencies:
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
-        version: 0.10.3
+        version: 0.13.2
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -42,7 +42,7 @@ dependencies:
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
-        version: 0.10.3
+        version: 0.13.2
 - !ruby/object:Gem::Dependency
   name: multi_json
   requirement: !ruby/object:Gem::Requirement
@@ -59,7 +59,23 @@ dependencies:
     - - ~>
       - !ruby/object:Gem::Version
         version: 1.3.6
-description: A simple wrapper for the Nexmo API
+- !ruby/object:Gem::Dependency
+  name: oauth
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.4.7
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.4.7
+description: A Ruby wrapper for the Nexmo API
 email:
 - mail@timcraft.com
 executables: []
@@ -95,4 +111,3 @@ signing_key:
 specification_version: 3
 summary: See description
 test_files: []
-has_rdoc: