action_sms_gateways 0.0.6 → 0.0.7

data/README.markdown

@@ -1,22 +1,157 @@
 # action_sms_gateways
+
 A collection of SMS Gateway Adapters for [action_sms](http://github.com/dwilkie/action_sms)
 
 ## Current SMS Adapters
+
 * [SMSGlobal](http://www.smsglobal.com)
+* [Tropo](http://www.tropo.com)
+
+## Configuration
+
+* [SMSGlobal](http://github.com/dwilkie/action_sms_gateways/wiki/SMSGlobal)
+* [Tropo](http://github.com/dwilkie/action_sms_gateways/wiki/Tropo)
+
+## Usage
+
+### Send an SMS and check if it was successful
+
+    class SMS
+      def recipient
+        "617198378843"
+      end
+
+      def body
+        "Hello world"
+      end
+
+      def from
+      end
+    end
+
+    sms_gateway = ActionSms::Base.connection
+    response = sms_gateway.deliver(SMS.new)
+    success = sms_gateway.delivery_request_successful?(response)
+
+### Receive an SMS
+
+    # Assume 'params' has the data posted back to your server
+
+    sms_gateway = ActionSms::Base.connection
+
+    # get sender
+    sender = sms_gateway.sender(params)
+
+    # get message text
+    message_text = sms_gateway.message_text(params)
+
+### Delivery receipts
+
+    # Assume 'receipt' has the data posted back to your server as the delivery receipt
+
+    sms_gateway = ActionSms::Base.connection
+
+    # get status
+    status = sms_gateway.status(receipt)
+
+    # get message id
+    message_id = sms_gateway.message_id(receipt)
+
+### Authentication
+
+    ActionSms::Base.establish_connection(
+      :authentication_key => "my secret",
+      :use_ssl => true
+    )
+
+If you set up an: `authentication_key` in the configuration, your key will be passed back to your listener url. Using an authentication key in conjunction with a secure connection `use_ssl => true` helps protect you against someone faking incoming messages to your server. You can authenticate an incoming message as follows:
 
-## Creating your own SMS Gateway Adapter
-Take a look at the source under `lib/action_sms_gateways/connection_adapters/sms_global.rb` and use it as a template for your own adapter. Then why not share it for all to use...
+    # Assume 'params' has the data posted back to your server
 
-## Contributing
-* Fork the project.
-* Make your SMS Gateway Adapter.
-* Add tests for it. This is important so I don’t break it in a future version unintentionally.
-* Commit, do not mess with rakefile, version, or history.
-* Send me a pull request.
+    sms_gateway = ActionSms::Base.connection
+
+    # Removes the authentication key from 'params' and returns true or false
+    sms_gateway.authenticate(params)
+
+### Service url
+
+    # gets the gateway's api url
+    # ActionSms::Base.connection.service_url
+
+## Testing
+
+When you set: `:environment => "test"` in your configuration, you get some additional test helpers.
+
+    ActionSms::Base.establish_connection(
+      :environment => "test"
+    )
+
+    sms_gateway = ActionSms::Base.connection
+
+    # get sample incoming SMS params
+    sms_gateway.sample_incoming_sms
+
+    # get customized sample incoming SMS
+    sms_gateway.sample_incoming_sms(
+      :message => "hello",
+      :to => "6128392323",
+      :from => "61289339432",
+      :date => Time.now,
+      :authentic => false     # see configuration
+    )
+
+    # get sample delivery response
+    sms_gateway.sample_delivery_response
+
+    # get sample delivery response (failed)
+    sms_gateway.sample_delivery_response(:failed => true)
+
+    # get sample message id
+    sms_gateway.sample_message_id
+
+    # get sample delivery receipt
+    sms_gateway.sample_delivery_receipt
+
+    # get customized sample delivery receipt
+    sms_gateway.sample_delivery_receipt(
+      :message_id => "12345",
+      :status => "delivered",
+      :error => "some error",
+      :date => Time.now
+    )
+
+## Creating your own adapter
+
+To create your own adapter all you need to do is open up the ActionSms::Base class
+and add a class method named: `my_adapter_connection` which takes a single hash argument of configuration details and returns an instance of your adapter class. For example, let's create an adapter for clickatell:
+
+    # clickatell.rb
+    require 'action_sms/connection_adapters/abstract_adapter'
+
+    module ActionSms
+      class Base
+        def self.clickatell_connection(config)
+          ConnectionAdapters::ClickatellAdapter.new(config)
+        end
+      end
+    end
+
+    module ConnectionAdapters
+      class ClickatellAdapter < AbstractAdapter
+        # define your adapter here ...
+        def initialize(config)
+        end
+      end
+    end
+
+Take a look at the [source](http://github.com/dwilkie/action_sms_gateways/tree/master/lib/action_sms_gateways/connection_adapters/) for more details
 
 ## Installation
+
     gem install action_sms_gateways
+
 ### Rails
+
 Place the following in your Gemfile:
 
     gem action_sms_gateways

data/Rakefile

@@ -22,6 +22,7 @@ begin
     gemspec.email = "dwilkie@gmail.com"
     gemspec.homepage = "http://github.com/dwilkie/action_sms_gateways"
     gemspec.authors = ["David Wilkie"]
+    gemspec.add_runtime_dependency "tropo_message", ">=0.0.4"
   end
 rescue LoadError
   puts "Jeweler not available. Install it with: gem install jeweler"

data/VERSION

@@ -1 +1 @@
-0.0.6
+0.0.7

data/action_sms_gateways.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = %q{action_sms_gateways}
-  s.version = "0.0.6"
+  s.version = "0.0.7"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["David Wilkie"]
-  s.date = %q{2010-10-03}
+  s.date = %q{2010-10-14}
   s.email = %q{dwilkie@gmail.com}
   s.extra_rdoc_files = [
     "README.markdown"
@@ -24,6 +24,9 @@ Gem::Specification.new do |s|
      "lib/action_sms_gateways.rb",
      "lib/action_sms_gateways/connection_adapters.rb",
      "lib/action_sms_gateways/connection_adapters/sms_global.rb",
+     "lib/action_sms_gateways/connection_adapters/test_helpers/sms_global.rb",
+     "lib/action_sms_gateways/connection_adapters/test_helpers/tropo.rb",
+     "lib/action_sms_gateways/connection_adapters/tropo.rb",
      "todo"
   ]
   s.homepage = %q{http://github.com/dwilkie/action_sms_gateways}
@@ -37,9 +40,12 @@ Gem::Specification.new do |s|
     s.specification_version = 3
 
     if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
+      s.add_runtime_dependency(%q<tropo_message>, [">= 0.0.4"])
     else
+      s.add_dependency(%q<tropo_message>, [">= 0.0.4"])
     end
   else
+    s.add_dependency(%q<tropo_message>, [">= 0.0.4"])
   end
 end
 

data/lib/action_sms_gateways/connection_adapters/sms_global.rb

@@ -1,10 +1,18 @@
 require 'action_sms/connection_adapters/abstract_adapter'
-require 'uri'
 
 module ActionSms
   class Base
     def self.sms_global_connection(config) #:nodoc:
-      return ConnectionAdapters::SMSGlobalAdapter.new(logger, config)
+      if config[:environment].to_s == "test"
+        test_helper = File.expand_path(File.dirname(__FILE__) + '/test_helpers/sms_global')
+        if File.exists?("#{test_helper}.rb")
+          require test_helper
+          ConnectionAdapters::SMSGlobalAdapter.class_eval do
+            include TestHelpers::SMSGlobal
+          end
+        end
+      end
+      ConnectionAdapters::SMSGlobalAdapter.new(config)
     end
   end
 
@@ -13,14 +21,18 @@ module ActionSms
     # class.  You can use this interface directly by borrowing the gateway
     # connection from the Base with Base.connection.
     class SMSGlobalAdapter < AbstractAdapter
+      require 'uri'
+
       SERVICE_HOST = "http://smsglobal.com.au"
       SERVICE_PATH = "http-api.php"
 
-      def initialize(logger = nil, config = {}) #:nodoc:
-        super(logger)
+      attr_reader :service_url
+
+      def initialize(config = {}) #:nodoc:
         @config = config.dup
-        @service_url = URI.join(SERVICE_HOST, SERVICE_PATH)
-        @service_url.scheme = config[:use_ssl] ? "https" : "http"
+        service_uri = URI.join(SERVICE_HOST, SERVICE_PATH)
+        service_uri.scheme = config[:use_ssl] ? "https" : "http"
+        @service_url = service_uri.to_s
       end
 
       def message_id(data)
@@ -72,7 +84,7 @@ module ActionSms
         params.merge!(
           :userfield => userfield
         ) if userfield
-        send_http_request(@service_url.to_s, params)
+        send_http_request(@service_url, params)
       end
     end
   end

data/lib/action_sms_gateways/connection_adapters/test_helpers/sms_global.rb

@@ -0,0 +1,40 @@
+module TestHelpers
+  module SMSGlobal
+    def sample_incoming_sms(options = {})
+      options[:message] ||= "Endia kasdf ofeao"
+      options[:to]      ||= "61447100308"
+      options[:from]    ||= "61447100399"
+      options[:date]    ||= "2010-05-13 23:59:11"
+      params = {
+        "to" => options[:to],
+        "from" => options[:from],
+        "msg"=> options[:message],
+        "date" => options[:date]
+      }
+      params.merge!("userfield" => @config[:authentication_key]) unless options[:authentic] == false
+      params
+    end
+
+    def sample_delivery_response(options = {})
+      options[:failed] ? "ERROR: No action requested" : "OK: 0; Sent queued message ID: 86b1a945370734f4 SMSGlobalMsgID:6942744494999745"
+    end
+
+    def sample_message_id
+      "SMSGlobalMsgID:6942744494999745"
+    end
+
+    def sample_delivery_receipt(options = {})
+      options[:message_id] ||= "6942744494999745"
+      options[:status] ||= "DELIVRD"
+      options[:error] ||= "000"
+      options[:date] ||= "1005132312"
+      {
+        "msgid"=> options[:message_id],
+        "dlrstatus"=> options[:status],
+        "dlr_err"=> options[:error],
+        "donedate"=> options[:date]
+      }
+    end
+  end
+end
+

data/lib/action_sms_gateways/connection_adapters/test_helpers/tropo.rb

@@ -0,0 +1,68 @@
+module TestHelpers
+  module Tropo
+    def sample_incoming_sms(options = {})
+      options[:message] ||= "Endia kasdf ofeao"
+      options[:to]      ||= "61447100308"
+      options[:from]    ||= "61447100399"
+      options[:date]    ||= "Mon Oct 11 09:21:38 UTC 2010"
+      params = {
+        "session" => {
+          "id"=>"12349516546e59746d6a89a990466789",
+          "account_id"=>"12345",
+          "timestamp"=> options[:date],
+          "user_type"=>"HUMAN",
+          "initial_text"=> options[:message],
+          "call_id"=>"123e71195545ad204bdd99f2070a7d86",
+          "to"=>{
+            "id"=> options[:to],
+            "name"=>"unknown",
+            "channel"=>"TEXT",
+            "network"=>"SMS"
+          },
+          "from" => {
+            "id"=> options[:from],
+            "name"=>"unknown",
+            "channel"=>"TEXT",
+            "network"=>"SMS"
+          },
+          "headers" => {
+            "_max-_forwards"=>"70",
+            "_content-_length"=>"124",
+            "_contact"=>"<sip:11.8.93.101:5066;transport=udp>",
+            "_to"=>"<sip:1231454582@10.6.69.203:5061;to=#{options[:to]}>",
+            "_c_seq"=>"1 INVITE",
+            "_via"=>"SIP/2.0/UDP 11.8.93.101:5066;branch=h0hG4bKk5sy1e",
+            "_call-_i_d"=>"ieeg18",
+            "_content-_type"=>"application/sdp",
+
+      "_from"=>"<sip:15EB6BAB-99DF-44C2-871DFBA75C319776@11.8.93.201;channel=private;user=#{options[:to]};msg=#{options[:message]};network=SMS;step=1>;tag=zm13kt"
+          }
+        }
+      }
+      params.merge!("authentication_key" => @config[:authentication_key]) unless options[:authentic] == false
+      params
+    end
+
+    def sample_delivery_response(options = {})
+      options[:failure] ? "<session><success>false</success><token></token><reason>FAILED TO ROUTE TOKEN</reason></session>" : "<session><success>true</success></session>"
+    end
+
+    def sample_message_id
+      "123e71195545ad204bdd99f2070a7d86"
+    end
+
+    # This is here simply so the current tests pass
+    # Tropo does not *yet* send delivery receipts
+    def sample_delivery_receipt(options = {})
+      options[:message_id] ||= "123e71195545ad204bdd99f2070a7d86"
+      options[:status] ||= "delivered"
+      options[:date]   ||= "Mon Oct 11 09:21:38 UTC 2010"
+      {
+        "message_id"=> options[:message_id],
+        "status"=> options[:status],
+        "delivered_at"=> options[:date]
+      }
+    end
+  end
+end
+

data/lib/action_sms_gateways/connection_adapters/tropo.rb

@@ -0,0 +1,82 @@
+require 'action_sms/connection_adapters/abstract_adapter'
+
+module ActionSms
+  class Base
+    def self.tropo_connection(config) #:nodoc:
+      if config[:environment].to_s == "test"
+        test_helper = File.expand_path(File.dirname(__FILE__) + '/test_helpers/tropo')
+        if File.exists?("#{test_helper}.rb")
+          require test_helper
+          ConnectionAdapters::TropoAdapter.class_eval do
+            include TestHelpers::Tropo
+          end
+        end
+      end
+      ConnectionAdapters::TropoAdapter.new(config)
+    end
+  end
+
+  module ConnectionAdapters
+    # All the concrete gateway adapters follow the interface laid down in this
+    # class.  You can use this interface directly by borrowing the gateway
+    # connection from the Base with Base.connection.
+    class TropoAdapter < AbstractAdapter
+      require 'uri'
+      require 'tropo_message'
+
+      attr_reader :service_url
+
+      SERVICE_HOST = "http://api.tropo.com/1.0"
+      SERVICE_PATH = "sessions"
+
+      def initialize(config = {}) #:nodoc:
+        @config = config.dup
+        service_uri = URI.join(SERVICE_HOST, SERVICE_PATH)
+        service_uri.scheme = config[:use_ssl] ? "https" : "http"
+        @service_url = service_uri.to_s
+      end
+
+      # message_id and status are for text message delivery receipts only
+      # Tropo does not *yet* send text message delivery receipts, so these
+      # two methods are here for testing purposes
+      def message_id(data)
+        data.is_a?(Hash) ? data["message_id"] : data
+      end
+
+      def status(delivery_receipt)
+        delivery_receipt["status"]
+      end
+
+      def delivery_request_successful?(gateway_response)
+        gateway_response =~ /\<success\>true\<\/success\>/
+      end
+
+      def message_text(params)
+        session(params)["initial_text"]
+      end
+
+      def sender(params)
+        session(params)["from"]["id"]
+      end
+
+      def authenticate(params)
+        params.delete("authentication_key") == @config[:authentication_key]
+      end
+
+      def deliver(sms)
+        tropo_message = Tropo::Message.new
+        tropo_message.to = sms.recipient
+        tropo_message.text = sms.body || ""
+        tropo_message.from = sms.from if sms.respond_to?(:from)
+        tropo_message.token = @config[:outgoing_token]
+        send_http_request(@service_url, tropo_message.request_xml)
+      end
+
+      private
+        def session(params)
+          params["session"]
+        end
+    end
+  end
+end
+

metadata

@@ -5,8 +5,8 @@ version: !ruby/object:Gem::Version
   segments: 
   - 0
   - 0
-  - 6
-  version: 0.0.6
+  - 7
+  version: 0.0.7
 platform: ruby
 authors: 
 - David Wilkie
@@ -14,10 +14,24 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-10-03 00:00:00 +07:00
+date: 2010-10-14 00:00:00 +07:00
 default_executable: 
-dependencies: []
-
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: tropo_message
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 0
+        - 0
+        - 4
+        version: 0.0.4
+  type: :runtime
+  version_requirements: *id001
 description: 
 email: dwilkie@gmail.com
 executables: []
@@ -36,6 +50,9 @@ files:
 - lib/action_sms_gateways.rb
 - lib/action_sms_gateways/connection_adapters.rb
 - lib/action_sms_gateways/connection_adapters/sms_global.rb
+- lib/action_sms_gateways/connection_adapters/test_helpers/sms_global.rb
+- lib/action_sms_gateways/connection_adapters/test_helpers/tropo.rb
+- lib/action_sms_gateways/connection_adapters/tropo.rb
 - todo
 has_rdoc: true
 homepage: http://github.com/dwilkie/action_sms_gateways