messagebird-rest 1.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 65e692932b82b38e07641c5787691f0dddc4330e
+  data.tar.gz: ae82199dc7751a50e772ba289fcdc712721fec88
+SHA512:
+  metadata.gz: 0ff89ec13b1720dfef137c1e26fca6d105bd6e2538c2e0cbf647b2924791aa81716f62a377100cebc0f4385cfaf953ef224044a853eef0aaa6059ca0d72d145d
+  data.tar.gz: 62078521b02b35ffd7a30dfd5c1f4226cc20b920d2cd006b118b1f8188ed868b756ba6ed2c78e0e084a28eb748316bffb80d7f49f26f6e98fe0ae9ba16c0d5d7

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2014, MessageBird
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer. 
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
+ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/README.md

@@ -0,0 +1,159 @@
+MessageBird's REST API for Ruby
+===============================
+This repository contains the open source Ruby client for MessageBird's REST API. Documentation can be found at: https://www.messagebird.com/developers/ruby.
+
+Requirements
+------------
+- [Sign up](https://www.messagebird.com/en/signup) for a free MessageBird account
+- Create a new access_key in the developers sections
+- MessageBird's API client for Ruby requires Ruby >= 1.9
+
+Installation
+------------
+You can either include the following line in your Gemfile:
+
+```ruby
+gem 'messagebird-rest', :require => 'messagebird'
+```
+
+Or you can just manually install it from the command line:
+```sh
+$ gem install messagebird-rest
+```
+
+Examples
+--------
+We have put some self-explanatory examples in the *examples* directory, but here is a quick breakdown on how it works. First, you need to create an instance of **MessageBird::Client**. Be sure to replace **YOUR_ACCESS_KEY** with something real in the bottom example.
+
+```ruby
+require 'pp'              # Only needed for this example
+require 'messagebird'
+
+client = MessageBird::Client.new(YOUR_ACCESS_KEY)
+```
+
+That's easy enough. Now we can query the server for information. 
+
+##### Balance
+Lets start with out with an overview of our balance.
+
+```ruby
+pp client.balance
+
+#<MessageBird::Balance:0x007f8d5c83f478
+ @amount=9,
+ @payment="prepaid",
+ @type="credits">
+```
+
+##### Messages
+Chances are that the most common use you'll have for this API client is the ability to send out text messages. For that purpose we have created the **message_create** method, which takes the required *originator*, one or more *recipients* and a *body* text for parameters.
+
+Optional parameters can be specified as a hash.
+
+```ruby
+pp client.message_create('FromMe', '31612345678', 'Hello World', :reference => 'MyReference')
+
+#<MessageBird::Message:0x007f8d5b883520
+ @body="Hello World",
+ @createdDatetime=2014-07-07 12:20:30 +0200,
+ @datacoding="plain",
+ @direction="mt",
+ @gateway=239,
+ @href=
+  "https://rest.messagebird.com/messages/211e6280453ba746e8eeff7b12582146",
+ @id="211e6280453ba746e8eeff7b12582146",
+ @mclass=1,
+ @originator="FromMe",
+ @recipient=
+  {"totalCount"=>1,
+   "totalSentCount"=>1,
+   "totalDeliveredCount"=>0,
+   "totalDeliveryFailedCount"=>0,
+   "items"=>
+    [#<MessageBird::Recipient:0x007f8d5c058c00
+      @recipient=31612345678,
+      @status="sent",
+      @statusDatetime=2014-07-07 12:20:30 +0200>]},
+ @reference="MyReference",
+ @scheduledDatetime=nil,
+ @type="sms",
+ @typeDetails={},
+ @validity=nil>
+```
+
+As a possible follow-up, you can use the **message** method with the above mentioned batch-id to query the status of the message that you just created. It will return a similar Message object.
+
+```ruby
+client.message('211e6280453ba746e8eeff7b12582146')
+```
+
+##### HLR
+To perform HLR lookups we have created the **hlr_create** method, which takes a number and a reference for parameters.
+
+```ruby
+pp client.hlr_create('31612345678', 'MyReference')
+
+#<MessageBird::HLR:0x007f8d5b8dafc8
+ @createdDatetime=2014-07-07 12:20:05 +0200,
+ @href="https://rest.messagebird.com/hlr/4933bed0453ba7455031712h16830892",
+ @id="4933bed0453ba7455031712h16830892",
+ @msisdn=31612345678,
+ @network=nil,
+ @reference="MyReference",
+ @status="sent",
+ @statusDatetime=2014-07-07 12:20:05 +0200>
+```
+
+Similar to the **message_create** and **message** methods, the **hlr_create** method has an accompanying **hlr** method to poll the HLR object.
+
+```ruby
+client.hlr('4933bed0453ba7455031712h16830892')
+```
+
+##### Voice Message
+MessageBird also offers the ability to send out a text message as a voice message, or text-to-speech. For that purpose we have created the **voice_message_create** method, which takes one or more required *recipients* and a *body* text for parameters.
+
+Optional parameters can be specified as a hash.
+
+```ruby
+pp client.voice_message_create('31612345678', 'Hello World', :reference => 'MyReference')
+
+#<MessageBird::VoiceMessage:0x000001030101b8
+ @body="Hello World",
+ @createdDatetime=2014-07-09 12:17:50 +0200,
+ @href=
+  "https://rest.messagebird.com/voicemessages/a08e51a0353bd16cea7f298a37405850",
+ @id="a08e51a0353bd16cea7f298a37405850",
+ @ifMachine="continue",
+ @language="en-gb",
+ @recipients=
+  {"totalCount"=>1,
+   "totalSentCount"=>1,
+   "totalDeliveredCount"=>0,
+   "totalDeliveryFailedCount"=>0,
+   "items"=>
+    [#<MessageBird::Recipient:0x000001011d3178
+      @recipient=31612345678,
+      @status="calling",
+      @statusDatetime=2014-07-09 12:17:50 +0200>]},
+ @reference="MyReference",
+ @repeat=1,
+ @scheduledDatetime=nil,
+ @voice="female">
+```
+
+Similar to regular messaging and HLR lookups, there is a method available to fetch the VoiceMessage object by using an *id*.
+
+```ruby
+client.voice_message('a08e51a0353bd16cea7f298a37405850')
+```
+
+Documentation
+-------------
+Complete documentation, instructions, and examples are available at:
+[https://www.messagebird.com/developers/ruby](https://www.messagebird.com/developers/ruby).
+
+License
+-------
+The MessageBird REST Client for Ruby is licensed under [The BSD 2-Clause License](http://opensource.org/licenses/BSD-2-Clause). Copyright (c) 2014, MessageBird

data/lib/messagebird.rb

@@ -0,0 +1,14 @@
+libdir = File.dirname(__FILE__)
+$:.unshift(libdir) unless $:.include?(libdir)
+
+module MessageBird
+  CLIENT_VERSION = '1.1.0'
+  ENDPOINT       = 'https://rest.messagebird.com'
+end
+
+require 'messagebird/balance'
+require 'messagebird/client'
+require 'messagebird/error'
+require 'messagebird/hlr'
+require 'messagebird/message'
+require 'messagebird/voicemessage'

data/lib/messagebird/balance.rb

@@ -0,0 +1,7 @@
+require 'messagebird/base'
+
+module MessageBird
+  class Balance < MessageBird::Base
+    attr_accessor :payment, :type, :amount
+  end
+end

data/lib/messagebird/base.rb

@@ -0,0 +1,20 @@
+require 'json'
+require 'time'
+
+module MessageBird
+  class Base
+    def initialize(json)
+      json.each do |k,v|
+        begin
+          send("#{k}=", v)
+        rescue NoMethodError
+          # Silently ignore parameters that are not supported.
+        end
+      end
+    end
+
+    def value_to_time(value)
+      value ? Time.parse(value) : nil
+    end
+  end
+end

data/lib/messagebird/client.rb

@@ -0,0 +1,117 @@
+require 'json'
+require 'net/https'
+require 'uri'
+
+require 'messagebird/balance'
+require 'messagebird/error'
+require 'messagebird/hlr'
+require 'messagebird/message'
+require 'messagebird/voicemessage'
+
+module MessageBird
+  class ErrorException < Exception
+    attr_reader :errors
+
+    def initialize(errors)
+      @errors = errors
+    end
+  end
+
+  class Client
+    attr_reader :access_key
+
+    def initialize(access_key)
+      @access_key = access_key
+    end
+
+    def request(method, path, params={})
+      uri = URI.join(ENDPOINT, '/', path)
+
+      # Set up the HTTP object.
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl     = true
+
+      # Construct the HTTP GET or POST request.
+      request = Net::HTTP::Get.new(uri.request_uri)  if method == :get
+      request = Net::HTTP::Post.new(uri.request_uri) if method == :post
+      request['Accept']        = 'application/json'
+      request['Authorization'] = "AccessKey #{@access_key}"
+      request['User-Agent']    = "MessageBird/ApiClient/#{CLIENT_VERSION} Ruby/#{RUBY_VERSION}"
+
+      # If present, add the HTTP POST parameters.
+      request.set_form_data(params) if method == :post && !params.empty?
+
+      # Execute the request and fetch the response.
+      response = http.request(request)
+
+      # Parse the HTTP response.
+      case response.code.to_i
+      when 200, 201, 204, 401, 404, 405, 422
+        json = JSON.parse(response.body)
+      else
+        raise Net::HTTPServerError.new 'Unknown response from server', response
+      end
+
+      # If the request returned errors, create Error objects and raise.
+      if json.has_key?('errors')
+        raise ErrorException, json['errors'].map { |e| Error.new(e) }
+      end
+
+      json
+    end
+
+    # Retrieve your balance.
+    def balance
+      Balance.new(request(:get, 'balance'))
+    end
+
+    # Retrieve the information of specific HLR.
+    def hlr(id)
+      HLR.new(request(:get, "hlr/#{id.to_s}"))
+    end
+
+    # Create a new HLR.
+    def hlr_create(msisdn, reference)
+      HLR.new(request(
+        :post,
+        'hlr',
+        :msisdn    => msisdn,
+        :reference => reference))
+    end
+
+    # Retrieve the information of specific message.
+    def message(id)
+      Message.new(request(:get, "messages/#{id.to_s}"))
+    end
+
+    # Create a new message.
+    def message_create(originator, recipients, body, params={})
+      # Convert an array of recipients to a comma-separated string.
+      recipients = recipients.join(',') if recipients.kind_of?(Array)
+
+      Message.new(request(
+        :post,
+        'messages',
+        params.merge({
+          :originator => originator.to_s,
+          :body       => body.to_s,
+          :recipients => recipients })))
+    end
+
+    # Retrieve the information of a specific voice message.
+    def voice_message(id)
+      VoiceMessage.new(request(:get, "voicemessages/#{id.to_s}"))
+    end
+
+    # Create a new voice message.
+    def voice_message_create(recipients, body, params={})
+      # Convert an array of recipients to a comma-separated string.
+      recipients = recipients.join(',') if recipients.kind_of?(Array)
+
+      VoiceMessage.new(request(
+        :post,
+        'voicemessages',
+        params.merge({ :recipients => recipients, :body => body.to_s })))
+    end
+  end
+end

data/lib/messagebird/error.rb

@@ -0,0 +1,7 @@
+require 'messagebird/base'
+
+module MessageBird
+  class Error < MessageBird::Base
+    attr_accessor :code, :description, :parameter
+  end
+end

data/lib/messagebird/hlr.rb

@@ -0,0 +1,18 @@
+require 'time'
+
+require 'messagebird/base'
+
+module MessageBird
+  class HLR < MessageBird::Base
+    attr_accessor :id, :href, :msisdn, :network, :reference, :status,
+                  :createdDatetime, :statusDatetime
+
+    def createdDatetime=(value)
+      @createdDatetime = value_to_time(value)
+    end
+
+    def statusDatetime=(value)
+      @statusDatetime = value_to_time(value)
+    end
+  end
+end

data/lib/messagebird/message.rb

@@ -0,0 +1,23 @@
+require 'messagebird/base'
+require 'messagebird/recipient'
+
+module MessageBird
+  class Message < MessageBird::Base
+    attr_accessor :id, :href, :direction, :type, :originator, :body,
+                  :reference, :validity, :gateway, :typeDetails, :datacoding,
+                  :mclass, :scheduledDatetime, :createdDatetime, :recipients
+
+    def scheduledDatetime=(value)
+      @scheduledDatetime = value_to_time(value)
+    end
+
+    def createdDatetime=(value)
+      @createdDatetime = value_to_time(value)
+    end
+
+    def recipients=(json)
+      json['items'] = json['items'].map { |r| Recipient.new(r) }
+      @recipients = json
+    end
+  end
+end

data/lib/messagebird/recipient.rb

@@ -0,0 +1,11 @@
+require 'messagebird/base'
+
+module MessageBird
+  class Recipient < MessageBird::Base
+    attr_accessor :recipient, :status, :statusDatetime
+
+    def statusDatetime=(value)
+      @statusDatetime = value_to_time(value)
+    end
+  end
+end

data/lib/messagebird/voicemessage.rb

@@ -0,0 +1,23 @@
+require 'messagebird/base'
+require 'messagebird/recipient'
+
+module MessageBird
+  class VoiceMessage < MessageBird::Base
+    attr_accessor :id, :href, :body, :reference, :language, :voice, :repeat,
+                  :ifMachine, :scheduledDatetime, :createdDatetime, :recipients
+
+
+    def scheduledDatetime=(value)
+      @scheduledDatetime = value_to_time(value)
+    end
+
+    def createdDatetime=(value)
+      @createdDatetime = value_to_time(value)
+    end
+
+    def recipients=(json)
+      json['items'] = json['items'].map { |r| Recipient.new(r) }
+      @recipients = json
+    end
+  end
+end

metadata

@@ -0,0 +1,54 @@
+--- !ruby/object:Gem::Specification
+name: messagebird-rest
+version: !ruby/object:Gem::Version
+  version: 1.1.0
+platform: ruby
+authors:
+- Maurice Nonnekes
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-07-10 00:00:00.000000000 Z
+dependencies: []
+description: A simple REST API for MessageBird in Ruby
+email: maurice@messagebird.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/messagebird.rb
+- lib/messagebird/balance.rb
+- lib/messagebird/base.rb
+- lib/messagebird/client.rb
+- lib/messagebird/error.rb
+- lib/messagebird/hlr.rb
+- lib/messagebird/message.rb
+- lib/messagebird/recipient.rb
+- lib/messagebird/voicemessage.rb
+homepage: https://github.com/messagebird/ruby-rest-api
+licenses:
+- BSD-2-Clause
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.2.2
+signing_key: 
+specification_version: 4
+summary: MessageBird's REST API
+test_files: []