esendex 0.2.3 → 0.3.0

data/app/controllers/esendex/application_controller.rb

@@ -0,0 +1,4 @@
+module Esendex
+  class ApplicationController < ActionController::Base
+  end
+end

data/app/controllers/esendex/inbound_messages_controller.rb

@@ -0,0 +1,12 @@
+module Esendex
+  class InboundMessagesController < ApplicationController
+    include PushNotificationHandler
+
+    def create
+      process_notification :inbound_message, request.body
+      render text: "OK"
+    rescue => e
+      render_error e
+    end
+  end
+end

data/app/controllers/esendex/message_delivered_events_controller.rb

@@ -0,0 +1,12 @@
+module Esendex
+  class MessageDeliveredEventsController < ApplicationController
+    include PushNotificationHandler
+
+    def create
+      process_notification :message_delivered_event, request.body
+      render text: "OK"
+    rescue => e
+      render_error e
+    end
+  end
+end

data/app/controllers/esendex/message_failed_events_controller.rb

@@ -0,0 +1,12 @@
+module Esendex
+  class MessageFailedEventsController < ApplicationController
+    include PushNotificationHandler
+
+    def create
+      process_notification :message_failed_event, request.body
+      render text: "OK"
+    rescue => e
+      render_error e
+    end
+  end
+end

data/app/controllers/esendex/push_notification_handler.rb

@@ -0,0 +1,42 @@
+# Common behaviour for all push notification controllers
+# 
+module Esendex
+  module PushNotificationHandler
+
+    # Used by controllers to handle incoming push notification
+    # 
+    # type        - Symbol indicating type
+    # source      - String request body of the notification
+    # 
+    # Returns nothing
+    def process_notification(type, source)
+       
+      if handler = Esendex.send("#{type}_handler")
+        notification_class = Esendex.const_get(type.to_s.camelize)
+        notification = notification_class.from_xml source
+        handler.call notification
+      else
+        logger.info "Received #{type} push notification but no handler configured" if defined?(logger)
+      end
+
+    end
+
+    def render_error(error)
+      lines = []
+      lines << "Path: #{request.path}"
+      request.body.rewind
+      lines << "Notification XML:\r\n#{request.body.read}"
+      lines << "Error: #{error.class.name} #{error.message}"
+      if Esendex.suppress_error_backtrace
+        lines << "[backtrace suppressed]"
+      else
+        lines << error.backtrace.join("\r\n")
+      end
+      lines << "---"
+      lines << "Ruby #{RUBY_VERSION}"
+      lines << "Rails #{Rails::VERSION::STRING}"
+      lines << Esendex.user_agent
+      render text: lines.join("\r\n"), status: 500
+    end
+  end
+end

data/config/routes.rb

@@ -0,0 +1,5 @@
+Esendex::Engine.routes.draw do
+  resources :message_delivered_events, only: [:create]
+  resources :message_failed_events, only: [:create]
+  resources :inbound_messages, only: [:create]
+end

data/lib/esendex.rb

@@ -1,32 +1,48 @@
 module Esendex
   require_relative 'esendex/version'
+  require_relative 'esendex/exceptions'
   require_relative 'esendex/api_connection'
+  require_relative 'esendex/hash_serialisation'
+  
   require_relative 'esendex/account'
+  require_relative 'esendex/inbound_message'
   require_relative 'esendex/message'
-  require_relative 'esendex/exceptions'
   require_relative 'esendex/message_batch_submission'
+  require_relative 'esendex/message_delivered_event'
+  require_relative 'esendex/message_failed_event'
   
-  require_relative 'esendex/railtie' if defined?(Rails)
+  # Load Rails extensions if Rails present
+  if defined?(Rails)
+    require_relative 'esendex/railtie' 
+    require_relative 'esendex/engine'
+  end
 
   API_NAMESPACE = 'http://api.esendex.com/ns/'
   API_HOST = 'https://api.esendex.com'
   API_VERSION = 'v1.0'
 
+  # Public - used to configure the gem prior to use
+  # 
+  #   Esendex.configure do |config|
+  #     config.username = 'username'
+  #     config.password = 'password'
+  #     config.account_reference = 'account reference'
+  #   end
+  # 
   def self.configure
     yield self if block_given?
-
-    unless Esendex.username
-      raise StandardError.new("username required. Either set Esendex.username or set environment variable ESENDEX_USERNAME")
-    end
-
-    unless Esendex.password
-      raise StandardError.new("password required. Either set Esendex.password or set environment variable ESENDEX_PASSWORD")
-    end
   end
 
   class << self
+    # credentials for authentication
     attr_writer :account_reference, :username, :password
 
+    # lambdas for handling push notifications
+    attr_accessor :message_delivered_event_handler, :message_failed_event_handler, :inbound_message_handler
+
+    # behaviour config
+    attr_accessor :suppress_error_backtrace
+    
     def account_reference
       @account_reference ||= ENV['ESENDEX_ACCOUNT']
     end

data/lib/esendex/engine.rb

@@ -0,0 +1,5 @@
+module Esendex
+  class Engine < Rails::Engine
+    isolate_namespace Esendex
+  end
+end

data/lib/esendex/hash_serialisation.rb

@@ -0,0 +1,24 @@
+# Handles serialisation and deserialisation of object as a hash
+# 
+module Esendex
+  module HashSerialisation
+    def initialize(attrs={})
+      attrs.each_pair do |k, v|
+        raise ArgumentError.new("#{k} not an attribute of #{self.class.name}") unless respond_to?("#{k}=")
+        send("#{k}=", v)
+      end
+    end
+
+    def to_hash
+      attrs = {}
+      public_methods
+        .select { |m| m =~ /\w\=$/ }
+        .select { |m| respond_to?(m.to_s.chop) }
+        .collect { |m| m.to_s.chop.to_sym }
+        .each do |method| 
+          attrs[method] = send(method)
+        end
+      attrs
+    end
+  end
+end

data/lib/esendex/inbound_message.rb

@@ -0,0 +1,31 @@
+require 'nokogiri'
+
+# <InboundMessage>
+#  <Id>{guid-of-push-notification}</Id>
+#  <MessageId>{guid-of-inbound-message}</MessageId>
+#  <AccountId>{guid-of-esendex-account-for-message}</AccountId>
+#  <MessageText>{Message text of inbound message}</MessageText>
+#  <From>{phone number of sender of the message}</From>
+#  <To>{phone number for the Virtual Mobile Number of your Account}</To>
+# </InboundMessage>
+
+module Esendex
+  class InboundMessage
+    include HashSerialisation
+    
+    attr_accessor :id, :message_id, :account_id, :message_text, :from, :to
+
+    def self.from_xml(source)
+      doc = Nokogiri::XML source
+      event = InboundMessage.new
+      event.id = doc.at_xpath("/InboundMessage/Id").content
+      event.message_id = doc.at_xpath("/InboundMessage/MessageId").content
+      event.account_id = doc.at_xpath("/InboundMessage/AccountId").content
+      event.message_text = doc.at_xpath("/InboundMessage/MessageText").content
+      event.from = doc.at_xpath("/InboundMessage/From").content
+      event.to = doc.at_xpath("/InboundMessage/To").content
+      event
+    end
+
+  end
+end

data/lib/esendex/message_delivered_event.rb

@@ -0,0 +1,30 @@
+require 'nokogiri'
+
+# <MessageDelivered>
+#  <Id>{guid-of-push-notification}</Id>
+#  <MessageId>{guid-of-inbound-message}</MessageId>
+#  <AccountId>{guid-of-esendex-account-for-message}</AccountId>
+#  <OccurredAt>
+#   {the UTC DateTime (yyyy-MM-ddThh:mm:ss) the message was delivered}
+#  </OccurredAt>
+# </MessageDelivered>
+
+module Esendex
+  class MessageDeliveredEvent
+    include HashSerialisation
+    
+    attr_accessor :id, :message_id, :account_id, :occurred_at
+
+    def self.from_xml(source)
+      doc = Nokogiri::XML source
+      event = MessageDeliveredEvent.new
+      event.id = doc.at_xpath("/MessageDelivered/Id").content
+      event.message_id = doc.at_xpath("/MessageDelivered/MessageId").content
+      event.account_id = doc.at_xpath("/MessageDelivered/AccountId").content
+      occurred_at_s = doc.at_xpath("/MessageDelivered/OccurredAt").content
+      event.occurred_at = DateTime.strptime(occurred_at_s, "%Y-%m-%dT%H:%M:%S").to_time
+      event
+    end
+
+  end
+end

data/lib/esendex/message_failed_event.rb

@@ -0,0 +1,30 @@
+require 'nokogiri'
+
+# <MessageFailed>
+#  <Id>{guid-of-push-notification}</Id>
+#  <MessageId>{guid-of-inbound-message}</MessageId>
+#  <AccountId>{guid-of-esendex-account-for-message}</AccountId>
+#  <OccurredAt>
+#   {the UTC DateTime (yyyy-MM-ddThh:mm:ss) the message failed}
+#  </OccurredAt>
+# </MessageDelivered>
+
+module Esendex
+  class MessageFailedEvent
+    include HashSerialisation
+
+    attr_accessor :id, :message_id, :account_id, :occurred_at
+
+    def self.from_xml(source)
+      doc = Nokogiri::XML source
+      event = MessageFailedEvent.new
+      event.id = doc.at_xpath("/MessageFailed/Id").content
+      event.message_id = doc.at_xpath("/MessageFailed/MessageId").content
+      event.account_id = doc.at_xpath("/MessageFailed/AccountId").content
+      occurred_at_s = doc.at_xpath("/MessageFailed/OccurredAt").content
+      event.occurred_at = DateTime.strptime(occurred_at_s, "%Y-%m-%dT%H:%M:%S").to_time
+      event
+    end
+
+  end
+end

data/lib/esendex/version.rb

@@ -1,3 +1,3 @@
 module Esendex
-  VERSION = "0.2.3"
+  VERSION = "0.3.0"
 end

data/licence.txt

@@ -0,0 +1,24 @@
+Copyright (c) 2013, Esendex Ltd.
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+    * Redistributions of source code must retain the above copyright
+      notice, this list of conditions and the following disclaimer.
+    * 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.
+    * Neither the name of Esendex nor the
+      names of its contributors may be used to endorse or promote products
+      derived from this software without specific prior written permission.
+
+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 ESENDEX LTD 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

@@ -1,8 +1,8 @@
-# Esendex
+# Esendex Ruby SDK
 
 Ruby Gem for interacting with the Esendex API
 
-This is in very early stages of development but supports sending one or multiple messages using your account details
+This is in early stages of development but supports the primary requirements around sending and receiving messages.
 
 ## Usage
 
@@ -45,7 +45,7 @@ You can specify a different account to the default by passing the reference in a
 account = Account.new('EX23847')
 ```
 
-Multiple messages are sent by passing an array of `Messages` to the send_messages method
+Multiple messages are sent by passing an array of `Messages` to the `send_messages` method
 	
 ```ruby
 batch_id = account.send_messages([Message.new("07777111222", "Hello"), Message.new("07777111333", "Hi")])
@@ -68,17 +68,109 @@ You will need to set the credentials as enviroment variables which can also be d
     rake esendex:send_message["<mobile_number>","<message_body>"] ESENDEX_USERNAME=<username> ESENDEX_PASSWORD=<password> ESENDEX_ACCOUNT=<account_reference>
 
 
-### Testing
+## Push Notifications
+
+You can configure your Esendex account to send Push Notifications when the following occur
+
++ MessageDeliveredEvent
++ MessageFailedEvent
++ InboundMessage
+
+While it is possible to poll our API to check the status of outbound messages and to check for new inbound messages, the recommended approach is to allow the Esendex Platform to notify your system when these events occur.
+
+To do this you need to setup web accessible end points to accept the notifications. These end points are configured in [Esendex Developer Tools](https://www.esendex.com/developertools).
+
+Classes are provided in the gem for deserialising the notifications: `MessageDeliveredEvent`, `MessageFailedEvent` and `InboundMessage`. They all expose a `.from_xml` method to support this.
+
+```ruby
+message = InboundMessage.from_xml request.body
+```
+
+### Rails 3
+
+In order to simplify receipt of push notifications for Rails 3 users, the gem ships with mountable Rails controllers to handle the receipt of these notifications.
+
+To mount the end points, add this to `routes.rb`
+
+```ruby
+RailsApp::Application.routes.draw do
+  ...
+  mount Esendex::Engine => "/esendex"
+end
+```
+
+To configure the behaviour in response to a notification, you need to configure a lambda to use.
+
+```ruby
+Esendex.message_delivered_event_handler = lambda { |notification| 
+  # process the notification
+}
+```
+
+Please be kind to us and don't perform anything potentially long running in this call back as our notifier may timeout the request and pass the notififation to the retry queue. 
+
+If you need to perform processing that may run for a longer time then using an async task system like [Resque](https://github.com/defunkt/resque) is recommended.
+
+All notification classes expose a `.to_hash` method and can be initialised from the hash for serialisatiion and deserialisation.
+
+For example:
+
+```ruby
+
+Esendex.inbound_message_handler = lambda { |notification| 
+  Resque.enqueue InboundMessageProcessor, notification.to_hash
+}
+
+class InboundMessageProcessor
+
+  def self.perform(notification)
+    message = Esendex::InboundMessage.new notification
+    # do some processing of the message here
+  end
+
+end
+``` 
+
+The handlers are defined as follows:
+
+| End Point| Config Setting | Notification Class | Developer Tools |
+| -------- | -------------- | ------------------ | --------------- |
+| /esendex/inbound_messages | Esendex.inbound_message_handler | InboundMessage | SMS received |
+| /esendex/message_delivered_events | Esendex.message_delivered_event_handler | MessageDeliveredEvent | SMS delivered |
+| /esendex/message_failed_events | Esendex.message_failed_event_handler | MessageFailedEvent | SMS failed |
+
+#### Errors
+
+When an error occur in the handler lambdas then the controller returns a `500` status along with some error information back to the the Esendex Platform. This information is emailed to the technical notifications contact for the account.
+
+The notification then enters the retry cycle. 
+
+Included by default is the backtrace for the error to assist you in identifying the issue. You can suppress backtrace with the following config option.
+
+```ruby
+Esendex.configure do |config|
+  config.suppress_error_backtrace = true
+end
+```
+
+## Testing
+
+    bundle exec rspec
+  
+Will run specs. The spec folder contains a dummy Rails project for testing the Rails Engine.
+
+This project also ships with a `Guardfile` so you can run tests continuously.
+
+    bundle exec guard
 
-		bundle exec rspec
-	
-will run specs, ie those in the root of the test folder
 
 ## Contributing
 
-Please fork as you see fit and let us know when you have something that should be part of the gem.
+We really welcome any thoughts or guidance on how this gem could best provide the hooks you need to consume our services in your applicaiton. Please fork and raise pull requests for any features you would like us to add or raise an [issue]((https://github.com/esendex/esendex.gem/issues)
+
+Customers with more pressing issues should contact our support teams via the usual local phone number or by email: [support@esendex.com](mailto:support@esendex.com).
 
 ## Copyright
 
-Copyright (c) 2011-13 Esendex Ltd. See LICENSE.txt for further details.
+Copyright (c) 2011-13 Esendex Ltd. See licence.txt for further details.