nexmo 0.5.0 → 1.0.0

data/README.md

@@ -2,50 +2,55 @@ A simple wrapper for the [Nexmo](http://nexmo.com/) API
 =======================================================
 
 
-Requirements
-------------
-
-Ruby 1.9; Ruby 1.8 is not currently supported.
-
-
 Installation
 ------------
 
-    gem install nexmo
+    $ gem install nexmo
 
 
 Quick Start
 -----------
 
+Use the `send_message!` for a "fire and forget" approach to sending a message:
+
 ```ruby
 require 'nexmo'
 
 nexmo = Nexmo::Client.new('...API KEY...', '...API SECRET...')
 
-response = nexmo.send_message({
-  from: 'RUBY',
-  to: '...NUMBER...',
-  text: 'Hello world'
-})
-
-if response.success?
-  puts "Sent message: #{response.message_id}"
-elsif response.failure?
-  raise response.error
-end
+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.
+
+
+JSON Implementation
+-------------------
+
+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):
+
+```ruby
+require 'nexmo'
+require 'multi_json'
+
+nexmo = Nexmo::Client.new('...API KEY...', '...API SECRET...', :json => MultiJson)
 ```
 
+Ditto for anything that is compatible with the default implementation.
+
 
 Troubleshooting
 ---------------
 
-Phone numbers should be specified in international format.
+Remember that phone numbers should be specified in international format.
 
 The Nexmo documentation contains a [list of error codes](http://nexmo.com/documentation/index.html#response_code)
 which may be useful if you have problems sending a message.
 
-
-Bugs/Issues
------------
-
 Please report all bugs/issues via the GitHub issue tracker.

data/lib/nexmo.rb

@@ -1,6 +1,6 @@
 require 'net/http'
+require 'net/https' if RUBY_VERSION == '1.8.7'
 require 'json'
-require 'uri'
 require 'cgi'
 
 module Nexmo
@@ -10,34 +10,32 @@ module Nexmo
 
       @json = options.fetch(:json) { JSON }
 
-      @headers = {'Content-Type' => 'application/x-www-form-urlencoded'}
-
-      @http = Net::HTTP.new('rest.nexmo.com', 443)
+      @http = Net::HTTP.new('rest.nexmo.com', Net::HTTP.https_default_port)
 
       @http.use_ssl = true
     end
 
-    attr_accessor :key, :secret, :http, :headers
+    attr_accessor :key, :secret, :http
+
+    def send_message(params)
+      post('/sms/json', params)
+    end
 
-    def send_message(data)
-      response = @http.post('/sms/json', encode(data), headers)
+    def send_message!(params)
+      response = send_message(params)
 
-      if response.code.to_i == 200 && response['Content-Type'].split(?;).first == 'application/json'
-        object = @json.load(response.body)['messages'].first
+      if response.ok? && response.json?
+        item = response.object['messages'].first
 
-        status = object['status'].to_i
+        status = item['status'].to_i
 
         if status == 0
-          Success.new(object['message-id'])
+          item['message-id']
         else
-          error = Error.new("#{object['error-text']} (status=#{status})")
-
-          Failure.new(error, response, status)
+          raise Error, "#{item['error-text']} (status=#{status})"
         end
       else
-        error = Error.new("Unexpected HTTP response (code=#{response.code})")
-
-        Failure.new(error, response)
+        raise Error, "Unexpected HTTP response (code=#{response.code})"
       end
     end
 
@@ -70,17 +68,21 @@ module Nexmo
     end
 
     def search_messages(params)
-      get("/search/messages/#{key}/#{secret}", Hash === params ? params : {ids: Array(params)})
+      get("/search/messages/#{key}/#{secret}", Hash === params ? params : {:ids => Array(params)})
     end
 
     private
 
     def get(path, params = {})
-      Response.new(@http.get(request_uri(path, params)), json: @json)
+      Response.new(@http.get(request_uri(path, params)), :json => @json)
     end
 
-    def encode(data)
-      URI.encode_www_form data.merge(:username => @key, :password => @secret)
+    def post(path, params)
+      Response.new(@http.post(path, encode(params), {'Content-Type' => 'application/json'}), :json => @json)
+    end
+
+    def encode(params)
+      JSON.dump(params.merge(:username => @key, :password => @secret))
     end
 
     def request_uri(path, hash = {})
@@ -91,7 +93,7 @@ module Nexmo
           Array(values).map { |value| "#{escape(key)}=#{escape(value)}" }
         end
 
-        path + '?' + query_params.flatten.join(?&)
+        path + '?' + query_params.flatten.join('&')
       end
     end
 
@@ -107,6 +109,10 @@ module Nexmo
       @json = options.fetch(:json) { JSON }
     end
 
+    def respond_to_missing?(name, include_private = false)
+      @http_response.respond_to?(name)
+    end
+
     def method_missing(name, *args, &block)
       @http_response.send(name, *args, &block)
     end
@@ -116,7 +122,7 @@ module Nexmo
     end
 
     def json?
-      self['Content-Type'].split(?;).first == 'application/json'
+      self['Content-Type'].split(';').first == 'application/json'
     end
 
     def object
@@ -124,26 +130,6 @@ module Nexmo
     end
   end
 
-  class Success < Struct.new(:message_id)
-    def success?
-      true
-    end
-
-    def failure?
-      false
-    end
-  end
-
-  class Failure < Struct.new(:error, :http, :status)
-    def success?
-      false
-    end
-
-    def failure?
-      true
-    end
-  end
-
   class Error < StandardError
   end
 end

data/nexmo.gemspec

@@ -1,6 +1,6 @@
 Gem::Specification.new do |s|
   s.name = 'nexmo'
-  s.version = '0.5.0'
+  s.version = '1.0.0'
   s.platform = Gem::Platform::RUBY
   s.authors = ['Tim Craft']
   s.email = ['mail@timcraft.com']
@@ -8,7 +8,13 @@ Gem::Specification.new do |s|
   s.description = 'A simple wrapper for the Nexmo API'
   s.summary = 'See description'
   s.files = Dir.glob('{lib,spec}/**/*') + %w(README.md nexmo.gemspec)
-  s.add_development_dependency('mocha', '~> 0.9.12')
-  s.add_development_dependency('oj', '~> 1.3.7')
+  s.add_development_dependency('rake', '>= 0.9.3')
+  s.add_development_dependency('mocha', '~> 0.10.3')
+  s.add_development_dependency('multi_json', '~> 1.3.6')
   s.require_path = 'lib'
+
+  if RUBY_VERSION == '1.8.7'
+    s.add_development_dependency('minitest', '>= 4.2.0')
+    s.add_development_dependency('json', '>= 1.6.5')
+  end
 end

data/spec/nexmo_spec.rb

@@ -1,8 +1,7 @@
 require 'minitest/autorun'
 require 'mocha'
-require 'oj'
-
-require_relative '../lib/nexmo'
+require 'multi_json'
+require 'nexmo'
 
 describe 'Nexmo::Client' do
   before do
@@ -16,67 +15,55 @@ describe 'Nexmo::Client' do
     end
   end
 
-  describe 'headers method' do
-    it 'returns a hash' do
-      @client.headers.must_be_kind_of(Hash)
-    end
-  end
-
   describe 'send_message method' do
-    it 'posts to the sms resource' do
-      http_response = stub(code: '200', body: '{"messages":[{"status":0,"message-id":"id"}]}')
-      http_response.expects(:[]).with('Content-Type').returns('application/json;charset=utf-8')
+    it 'posts to the sms json resource and returns a response object' do
+      data = regexp_matches(/\{".+?":".+?"(,".+?":".+?")+\}/)
 
-      data = 'from=ruby&to=number&text=Hey%21&username=key&password=secret'
+      headers = has_entry('Content-Type', 'application/json')
 
-      headers = {'Content-Type' => 'application/x-www-form-urlencoded'}
+      params = {:from => 'ruby', :to => 'number', :text => 'Hey!'}
 
-      @client.http.expects(:post).with('/sms/json', data, headers).returns(http_response)
+      @client.http.expects(:post).with('/sms/json', data, headers).returns(stub)
 
-      @client.send_message({from: 'ruby', to: 'number', text: 'Hey!'})
+      @client.send_message(params).must_be_instance_of(Nexmo::Response)
     end
+  end
 
-    describe 'when the first message status equals 0' do
-      it 'returns a success object' do
-        http_response = stub(code: '200', body: '{"messages":[{"status":0,"message-id":"id"}]}')
-        http_response.expects(:[]).with('Content-Type').returns('application/json;charset=utf-8')
-
-        @client.http.stubs(:post).returns(http_response)
+  describe 'send_message bang method' do
+    before do
+      @params = {:from => 'ruby', :to => 'number', :text => 'Hey!'}
 
-        response = @client.send_message({from: 'ruby', to: 'number', text: 'Hey!'})
-        response.success?.must_equal(true)
-        response.failure?.must_equal(false)
-        response.message_id.must_equal('id')
-      end
+      @http_response = mock()
+      @http_response.stubs(:[]).with('Content-Type').returns('application/json;charset=utf-8')
+      @http_response.stubs(:code).returns('200')
     end
 
-    describe 'when the first message status does not equal 0' do
-      it 'returns a failure object' do
-        http_response = stub(code: '200', body: '{"messages":[{"status":2,"error-text":"Missing from param"}]}')
-        http_response.expects(:[]).with('Content-Type').returns('application/json')
+    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.send_message!(@params).must_equal('id')
+    end
 
-        @client.http.stubs(:post).returns(http_response)
+    it 'raises an exception if the response code is not expected' do
+      @http_response.stubs(:code).returns('500')
 
-        response = @client.send_message({to: 'number', text: 'Hey!'})
+      @client.http.stubs(:post).returns(@http_response)
 
-        response.success?.must_equal(false)
-        response.failure?.must_equal(true)
-        response.error.to_s.must_equal('Missing from param (status=2)')
-        response.http.wont_be_nil
-      end
+      proc { @client.send_message!(@params) }.must_raise(Nexmo::Error)
     end
 
-    describe 'when the server returns an unexpected http response' do
-      it 'returns a failure object' do
-        @client.http.stubs(:post).returns(stub(code: '503'))
+    it 'raises an exception if the response body contains an error' do
+      @http_response.stubs(:body).returns('{"messages":[{"status":2,"error-text":"Missing from param"}]}')
 
-        response = @client.send_message({from: 'ruby', to: 'number', text: 'Hey!'})
+      @client.http.stubs(:post).returns(@http_response)
 
-        response.success?.must_equal(false)
-        response.failure?.must_equal(true)
-        response.error.to_s.must_equal('Unexpected HTTP response (code=503)')
-        response.http.wont_be_nil
-      end
+      proc { @client.send_message!(@params) }.must_raise(Nexmo::Error)
     end
   end
 
@@ -106,9 +93,9 @@ 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('/account/numbers/key/secret?size=25&pattern=33').returns(stub)
+      @client.http.expects(:get).with(has_equivalent_query_string('/account/numbers/key/secret?size=25&pattern=33')).returns(stub)
 
-      @client.get_account_numbers(size: 25, pattern: 33).must_be_instance_of(Nexmo::Response)
+      @client.get_account_numbers(:size => 25, :pattern => 33).must_be_instance_of(Nexmo::Response)
     end
   end
 
@@ -116,7 +103,7 @@ describe 'Nexmo::Client' 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)
 
-      @client.number_search(:CA, size: 25).must_be_instance_of(Nexmo::Response)
+      @client.number_search(:CA, :size => 25).must_be_instance_of(Nexmo::Response)
     end
   end
 
@@ -132,19 +119,19 @@ describe 'Nexmo::Client' 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)
 
-      @client.get_message_rejections(date: 'YYYY-MM-DD').must_be_instance_of(Nexmo::Response)
+      @client.get_message_rejections(:date => 'YYYY-MM-DD').must_be_instance_of(Nexmo::Response)
     end
   end
 
   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('/search/messages/key/secret?date=YYYY-MM-DD&to=1234567890').returns(stub)
+      @client.http.expects(:get).with(has_equivalent_query_string('/search/messages/key/secret?date=YYYY-MM-DD&to=1234567890')).returns(stub)
 
-      @client.search_messages(date: 'YYYY-MM-DD', to: 1234567890).must_be_instance_of(Nexmo::Response)
+      @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('/search/messages/key/secret?ids=id1&ids=id2').returns(stub)
+      @client.http.expects(:get).with(has_equivalent_query_string('/search/messages/key/secret?ids=id1&ids=id2')).returns(stub)
 
       @client.search_messages(%w(id1 id2))
     end
@@ -161,6 +148,7 @@ describe 'Nexmo::Response' do
   it 'delegates to the underlying http response' do
     @http_response.expects(:code).returns('200')
 
+    @response.must_respond_to(:code) unless RUBY_VERSION == '1.8.7'
     @response.code.must_equal('200')
   end
 
@@ -205,7 +193,7 @@ describe 'Nexmo::Response initialized with a different json implementation' do
   before do
     @http_response = mock()
 
-    @response = Nexmo::Response.new(@http_response, json: Oj)
+    @response = Nexmo::Response.new(@http_response, :json => MultiJson)
   end
 
   describe 'object method' do

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: nexmo
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 1.0.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,8 +9,24 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-11-08 00:00:00.000000000 Z
+date: 2012-11-16 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 0.9.3
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 0.9.3
 - !ruby/object:Gem::Dependency
   name: mocha
   requirement: !ruby/object:Gem::Requirement
@@ -18,7 +34,7 @@ dependencies:
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
-        version: 0.9.12
+        version: 0.10.3
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -26,15 +42,15 @@ dependencies:
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
-        version: 0.9.12
+        version: 0.10.3
 - !ruby/object:Gem::Dependency
-  name: oj
+  name: multi_json
   requirement: !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
-        version: 1.3.7
+        version: 1.3.6
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -42,7 +58,7 @@ dependencies:
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
-        version: 1.3.7
+        version: 1.3.6
 description: A simple wrapper for the Nexmo API
 email:
 - mail@timcraft.com