action_sms 0.0.3 → 0.1.0

data/.gitignore

@@ -1,3 +1,3 @@
-*~
-rerun.txt
-
+pkg/*
+*.gem
+.bundle

data/Gemfile

@@ -0,0 +1,4 @@
+source "http://rubygems.org"
+
+# Specify your gem's dependencies in action_sms.gemspec
+gemspec

data/README.markdown

@@ -1,26 +1,159 @@
 # action_sms
 
-action_sms allows you to use existing or custom SMS Gateway Adapters and switch between them effortlessly without modifying your application or test code. By keeping SMS Gateway configuration out of your code you can be more adaptable to change.
+action_sms allows you to switch between SMS Gateways effortlessly without modifying your application or test code. By keeping SMS Gateway configuration out of your code you can be more adaptable to change.
+
+## Current SMS Gateway Adapters
+
+* [SMSGlobal](http://www.smsglobal.com)
+* [Tropo](http://www.tropo.com)
+
+## Adapter Specific Configuration
+
+* [SMSGlobal](http://github.com/dwilkie/action_sms/wiki/SMSGlobal)
+* [Tropo](http://github.com/dwilkie/action_sms/wiki/Tropo)
 
 ## Usage
 
+### Configuration
+
 Establish a connection to your SMS Gateway Adapter:
 
     ActionSms::Base.establish_connection(
       :adapter => 'your_adapter',
       # the remaining options are specific to the SMS Gateway Adapter
-      :username => '[username]',
-      :password => '[password]'
+      :username => 'username',
+      :password => 'password'
     )
 The only required option is `:adapter`. This specifies the SMS Gateway adapter you want to use. The remaining options are specific to the adapter.
 
-Now from your application or test code you can call methods on the adapter by calling:
+### Send an SMS and check if it was successful
+
+    class SMS
+      def recipient
+        "617198378843"
+      end
+
+      def body
+        "Hello world"
+      end
+
+      def from
+      end
+    end
+
+    response = ActionSms::Base.deliver(SMS.new)
+    success = ActionSms::Base.delivery_request_successful?(response)
+
+### Receive an SMS
+
+    # Assume 'params' has the data posted back to your server
+
+    # get sender
+    sender = ActionSms::Base.sender(params)
+
+    # get message text
+    message_text = ActionSms::Base.message_text(params)
+
+### Delivery receipts
+
+    # Assume 'receipt' has the data posted back to your server as the delivery receipt
+
+    # get status
+    status = ActionSms::Base.status(receipt)
+
+    # get message id
+    message_id = ActionSms::Base.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:
+
+    # Assume 'params' has the data posted back to your server
+
+    # Removes the authentication key from 'params' and returns true or false
+    ActionSms::Base.authenticate(params)
+
+### Service url
+
+    # gets the gateway's api url
+    # ActionSms::Base.service_url
+
+## Testing
+
+When you set: `:environment => "test"` in your configuration, you get some additional test helpers.
+
+    ActionSms::Base.establish_connection(
+      :environment => "test"
+    )
+
+    # get sample configuration
+    ActionSms::Base.sample_configuration
+
+    # get sample incoming SMS params
+    ActionSms::Base.sample_incoming_sms
+
+    # get customized sample incoming SMS
+    ActionSms::Base.sample_incoming_sms(
+      :message => "hello",
+      :to => "6128392323",
+      :from => "61289339432",
+      :date => Time.now,
+      :authentic => false     # see configuration
+    )
+
+    # get sample delivery response
+    ActionSms::Base.sample_delivery_response
+
+    # get sample delivery response (failed)
+    ActionSms::Base.sample_delivery_response(:failed => true)
+
+    # get a sample delivery response with a message id
+    ActionSms::Base.sample_delivery_response_with_message_id("12345")
+
+    # get sample message id
+    ActionSms::Base.sample_message_id
+
+    # get sample delivery receipt
+    ActionSms::Base.sample_delivery_receipt
+
+    # get customized sample delivery receipt
+    ActionSms::Base.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_adapter.rb
+    require 'action_sms/connection_adapters/abstract_adapter'
 
-    ActionSms::Base.connection
+    module ActionSms
+      class Base
+        def self.clickatell_connection(config)
+          ConnectionAdapters::ClickatellAdapter.new(config)
+        end
+      end
+    end
 
-## Adapters
+    module ConnectionAdapters
+      class ClickatellAdapter < AbstractAdapter
+        # define your adapter here ...
+        def initialize(config)
+        end
+      end
+    end
 
-See [action_sms_gateways](http://github.com/dwilkie/action_sms_gateways) for existing adapters and information on how to create your own.
+Take a look at the [source](http://github.com/dwilkie/action_sms/tree/master/lib/action_sms/connection_adapters/) for more details
 
 ## Rails
 
@@ -28,7 +161,7 @@ For convenience there is a generator that can be used if you are using action_sm
 
     rails g action_sms:initializer
 
-Generates an initializer under config/initializers with the `establish_connection` code described above.
+Generates an initializer including example configuration for built-in adapters
 
 ## Installation
 

data/Rakefile

@@ -1,38 +1,2 @@
-require 'rake'
-require 'rake/testtask'
-require 'rake/rdoctask'
-
-desc 'Default: run unit tests.'
-task :default => :test
-
-desc 'Test the ActionSMS plugin.'
-Rake::TestTask.new(:test) do |t|
-  t.libs << 'lib'
-  t.libs << 'spec'
-  t.libs << 'features'
-  t.pattern = 'spec/**/*_spec.rb'
-  t.verbose = true
-end
-
-begin
-  require 'jeweler'
-  Jeweler::Tasks.new do |gemspec|
-    gemspec.name = "action_sms"
-    gemspec.summary = "Lightweight SMS wrapper which can use any gateway"
-    gemspec.email = "dwilkie@gmail.com"
-    gemspec.homepage = "http://github.com/dwilkie/action_sms"
-    gemspec.authors = ["David Wilkie"]
-  end
-rescue LoadError
-  puts "Jeweler not available. Install it with: gem install jeweler"
-end
-
-desc 'Generate documentation for the ActionSMS plugin.'
-Rake::RDocTask.new(:rdoc) do |rdoc|
-  rdoc.rdoc_dir = 'rdoc'
-  rdoc.title    = 'ActionSMS'
-  rdoc.options << '--line-numbers' << '--inline-source'
-  rdoc.rdoc_files.include('README')
-  rdoc.rdoc_files.include('lib/**/*.rb')
-end
-
+require 'bundler'
+Bundler::GemHelper.install_tasks

data/action_sms.gemspec

@@ -1,50 +1,24 @@
-# Generated by jeweler
-# DO NOT EDIT THIS FILE DIRECTLY
-# Instead, edit Jeweler::Tasks in Rakefile, and run the gemspec command
 # -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "action_sms/version"
 
 Gem::Specification.new do |s|
-  s.name = %q{action_sms}
-  s.version = "0.0.3"
+  s.name        = "action_sms"
+  s.version     = ActionSms::VERSION
+  s.platform    = Gem::Platform::RUBY
+  s.authors     = ["David Wilkie"]
+  s.email       = ["dwilkie@gmail.com"]
+  s.homepage    = "http://github.com/dwilkie/action_sms"
+  s.summary     = %q{Effortlessly switch between SMS Gateways}
+  s.description = %q{Switch between SMS Gateways at a whim without modifying your application code or tests}
 
-  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
-  s.authors = ["David Wilkie"]
-  s.date = %q{2010-10-14}
-  s.email = %q{dwilkie@gmail.com}
-  s.extra_rdoc_files = [
-    "README.markdown"
-  ]
-  s.files = [
-    ".gitignore",
-     "MIT-LICENSE",
-     "README.markdown",
-     "Rakefile",
-     "VERSION",
-     "action_sms.gemspec",
-     "lib/action_sms.rb",
-     "lib/action_sms/base.rb",
-     "lib/action_sms/connection_adapters.rb",
-     "lib/action_sms/connection_adapters/abstract_adapter.rb",
-     "lib/action_sms/exceptions.rb",
-     "lib/generators/action_sms/initializer/USAGE",
-     "lib/generators/action_sms/initializer/initializer_generator.rb",
-     "lib/generators/action_sms/initializer/templates/action_sms.rb",
-     "todo"
-  ]
-  s.homepage = %q{http://github.com/dwilkie/action_sms}
-  s.rdoc_options = ["--charset=UTF-8"]
-  s.require_paths = ["lib"]
-  s.rubygems_version = %q{1.3.7}
-  s.summary = %q{Lightweight SMS wrapper which can use any gateway}
+  s.rubyforge_project = "action_sms"
 
-  if s.respond_to? :specification_version then
-    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
-    s.specification_version = 3
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
 
-    if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
-    else
-    end
-  else
-  end
+  s.add_runtime_dependency "tropo_message"
 end
 

data/lib/action_sms/base.rb

@@ -4,6 +4,22 @@ module ActionSms #:nodoc#
     @@connection = nil
 
     class << self
+      # Returns all adapters that respond to the given method
+      def adapters(adapter_method, config = {})
+        config = connection.configuration if config.empty? && connected?
+        adapters = []
+        methods.each do |method|
+          if method.to_s =~ /\_connection$/
+            begin
+              adapter = send(method, config)
+            rescue
+            end
+            adapters << adapter if adapter && adapter.respond_to?(adapter_method)
+          end
+        end
+        adapters
+      end
+
       # Returns true if a connection that's accessible to this class has already
       # been opened.
       def connected?
@@ -24,7 +40,7 @@ module ActionSms #:nodoc#
         @@connection = spec
       end
 
-      # Establishes the connection to the SMS gateway.  Accepts a hash as input
+      # Establishes the connection to the SMS gateway. Accepts a hash as input
       # where the :adapter key must be specified with the name of a gateway
       # adapter (in lower-case)
       #
@@ -35,8 +51,6 @@ module ActionSms #:nodoc#
       #     :api_id   => "myapiid"
       #   )
       #
-      # Also accepts keys as strings (for parsing from YAML, for example).
-      #
       # The exceptions AdapterNotSpecified, AdapterNotFound, and ArgumentError
       # may be returned.
       def establish_connection(config)
@@ -50,6 +64,102 @@ module ActionSms #:nodoc#
         end
         self.connection = self.send(adapter_method, config)
       end
+
+      # Adapter Helper Methods
+
+      def authenticate(params)
+        adapter_method_result(:authenticate, params)
+      end
+
+      def authentication_key
+        connection.authentication_key
+      end
+
+      def authentication_key=(value)
+        connection.authentication_key = value
+      end
+
+      def deliver(sms, options = {})
+        connection.deliver(sms, options)
+      end
+
+      def delivery_request_successful?(delivery_request)
+        connection.delivery_request_successful?(delivery_request)
+      end
+
+      def message_id(data)
+        adapter_method_result(:message_id, data)
+      end
+
+      def message_text(params)
+        adapter_method_result(:message_text, params)
+      end
+
+      def sender(params)
+        adapter_method_result(:sender, params)
+      end
+
+      def service_url
+        connection.service_url
+      end
+
+      def status(params)
+        adapter_method_result(:status, params)
+      end
+
+      def use_ssl
+        connection.use_ssl
+      end
+
+      def use_ssl=(value)
+        connection.use_ssl = value
+      end
+
+      # Test Helper Methods
+
+      def sample_configuration(options = {})
+        connection.sample_configuration(options)
+      end
+
+      def sample_delivery_receipt(options = {})
+        adapter_method_result(:sample_delivery_receipt, options)
+      end
+
+      def sample_delivery_response(options = {})
+        connection.sample_delivery_response(options)
+      end
+
+      def sample_delivery_response_with_message_id(message_id, options = {})
+        adapter_method_result(
+          :sample_delivery_response_with_message_id, message_id, options
+        )
+      end
+
+      def sample_incoming_sms(options = {})
+        adapter_method_result(:sample_incoming_sms, options)
+      end
+
+      def sample_message_id(options = {})
+        adapter_method_result(:sample_message_id, options)
+      end
+
+      private
+        def adapter_method_result(adapter_method, *args)
+          result = connection.send(
+            adapter_method, *args
+          ) if connection.respond_to?(adapter_method)
+          unless result
+            gateway_adapters = adapters(adapter_method)
+            i = 0
+            adapter = nil
+            begin
+              adapter = gateway_adapters[i]
+              result = adapter.send(adapter_method, *args) if adapter
+              i += 1
+            end until result || adapter.nil?
+          end
+          result
+        end
     end
   end
 end

data/lib/action_sms/connection_adapters.rb

@@ -1,2 +1,5 @@
-require 'action_sms/connection_adapters/abstract_adapter'
+# Load each available adapter
+Dir["#{File.dirname(__FILE__)}/connection_adapters/*.rb"].sort.each do |path|
+  require "action_sms/connection_adapters/#{File.basename(path)}"
+end