dimiro1-clickatell 0.7.0

data/History.txt

@@ -0,0 +1,51 @@
+== 0.7.0
+
+* Added support for sending SMS to multiple recipients.
+
+== 0.6.0
+
+* API host can now be customized (John Gibbons)
+* Fixed bug with the ampersands in messages, they are now escaped properly (John Brice)
+* Removed reliance on Object#blank? which was causing some compatibility issues (Greg Bell)
+* Added :callback option support (Greg Bell)
+* Added new test mode (Pivotal Labs)
+
+== 0.5.0
+
+* Added support for mobile originated flag (courtesy Dan Weinand)
+* Added support for WAP push (experimental, courtesy Zhao Lu)
+* Updated specs to use Mocha instead of the built-in RSpec mocking
+* Improved specs in general
+
+== 0.4.1
+
+* Custom alphanumeric sender would not always be supported by default unless it was explicitly enabled using the req_feat parameter.
+
+== 0.4.0
+
+* Added API debug mode and --debug option to sms utility
+* Restructured API classes into individual files
+* Refactored command execution into a separate object (CommandExecutor).
+* Major refactoring of API module - converted it to a class with API methods implemented as instance methods. Code is much cleaner and Connection class becomes redundant. See updated documentation.
+
+== 0.3.0
+
+* Display proper message status, not just the code
+* Make it possible to specify custom :from number/name using SMS utility
+* Added support for custom :from number/name when sending a message.
+* Added support for checking message status to sms utility
+* sms utility now returns the id of a successfully sent message.
+* Capture API KEY errors.
+* Make sure errors are handled when using sms utility to check balance.
+
+== 0.2.0 
+
+* Added Clickatell API error handling to API and sms utility.
+* Handle required/optional arguments for sms utility correctly
+* Added further sms utility usage information to website
+* Make sure sms utility gracefully handles missing recipient/message
+* Added balance query support to API and SMS utility (--check-balance).
+
+== 0.1.0 2007-08-17
+
+* Initial release.

data/License.txt

@@ -0,0 +1,21 @@
+Copyright (c) 2007 Luke Redpath
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+

data/RDOC_README.txt

@@ -0,0 +1,33 @@
+= Clickatell SMS Library
+
+To use this gem, you will need sign up for an account at www.clickatell.com. Once you are registered and logged into your account centre, you should add an HTTP API connection to your account. This will give you your API_ID.
+
+== Basic Usage
+
+You will need your API_ID as well as your account username and password.
+
+  require 'rubygems'
+  require 'clickatell'
+  
+  api = Clickatell::API.authenticate('your_api_id', 'your_username', 'your_password')
+  api.send_message('447771234567', 'Hello from clickatell')
+
+  
+== Command-line SMS Utility
+
+The Clickatell gem also comes with a command-line utility that will allow you to send an SMS directly from the command-line. 
+
+You will need to create a YAML configuration file in your home directory, in a file called .clickatell that resembles the following:
+
+  # ~/.clickatell
+  api_key: your_api_id
+  username: your_username
+  password: your_password
+  
+You can then use the sms utility to send a message to a single recipient:
+
+  sms 447771234567 'Hello from clickatell'
+  
+Alternatively, you can specify the username and password as a command line option. Run +sms+ without any arguments for a full list of options.
+
+See http://clickatell.rubyforge.org for further instructions.  

data/README.textile

@@ -0,0 +1,40 @@
+h1. Clickatell SMS Library
+
+To use this gem, you will need sign up for an account at www.clickatell.com. Once you are registered and logged into your account centre, you should add an HTTP API connection to your account. This will give you your API_ID.
+
+h2. Basic Usage
+
+You will need your API_ID as well as your account username and password.
+
+  require 'rubygems'
+  require 'clickatell'
+  
+  api = Clickatell::API.authenticate('your_api_id', 'your_username', 'your_password')
+  api.send_message('447771234567', 'Hello from clickatell')
+
+To send a message to multiple recipients, simply pass in an array of numbers.
+
+  api.send_message(['447771234567', '447771234568'], 'Hello from clickatell')
+  
+h2. Command-line SMS Utility
+
+The Clickatell gem also comes with a command-line utility that will allow you to send an SMS directly from the command-line. 
+
+You will need to create a YAML configuration file in your home directory, in a file called .clickatell that resembles the following:
+
+  # ~/.clickatell
+  api_key: your_api_id
+  username: your_username
+  password: your_password
+  
+You can then use the sms utility to send a message to a single recipient:
+
+  sms 447771234567 'Hello from clickatell'
+  
+Alternatively, you can specify the username and password as a command line option. Run +sms+ without any arguments for a full list of options.
+
+The sms utility also supports multiple, comma-separated recipients (up to 100).
+
+  sms 447771111111,447772222222 "Hello everyone"
+
+See http://clickatell.rubyforge.org for further instructions.  

data/bin/sms

@@ -0,0 +1,62 @@
+#!/usr/bin/env ruby
+
+local_libs = [
+ File.join(File.dirname(__FILE__), *%w[../lib/clickatell]),
+ File.join(File.dirname(__FILE__), *%w[../lib/clickatell/utility]) 
+]
+
+if File.exist?(local_libs.first)
+  local_libs.each { |lib| require lib }
+else
+  require 'rubygems'
+  require 'clickatell'
+  require 'clickatell/utility'
+end
+
+# parse command line options
+options = Clickatell::Utility::Options.parse(ARGV)
+
+# authenticate and load the API
+api = Clickatell::API.authenticate(options.api_key, options.username, options.password)
+
+begin
+  if options.show_balance
+    puts "Retrieving account balance..."
+    puts "You have #{api.account_balance} credits remaining."
+    exit 0
+  elsif options.show_status
+    puts "Getting status of message ##{options.message_id}."
+    status = api.message_status(options.message_id)
+    puts "Status: #{Clickatell::API::MessageStatus[status]} (##{status})."
+    exit 0
+  else
+    puts "Sending '#{options.message}' to #{[options.recipient].flatten.join(", ")}..."
+    additional_opts = {}
+    additional_opts[:from] = options.from if options.from
+    msg_id = api.send_message(options.recipient, options.message, additional_opts)
+    puts "Message sent successfully (message id: #{[msg_id].flatten.join(", ")})."
+    exit 0
+  end
+  
+rescue Clickatell::API::Error => e
+  case e.code
+  when '001', '002', '003', '005', '108'
+    puts "Authentication failed. Please check your username, password and API key and try again."
+    exit 1
+  when '004'
+    puts "Your account has been frozen. Please contact Clickatell support."
+    exit 1
+  when '007'
+    puts "Requests for this API key are not permitted from this IP address."
+    exit 1
+  else
+    puts "Unexpected error occurred. #{e.message} (error code: #{e.code})."
+    puts "Please contact the author (contact@lukeredpath.co.uk) with the above error."
+    exit 1
+  end
+  
+rescue Timeout::Error
+  puts "The connection the the Clickatell service timed out"
+  puts "Please check your network settings and try again."
+  exit 1
+end

data/lib/clickatell.rb

@@ -0,0 +1,10 @@
+module Clickatelll end
+
+%w( core-ext/hash
+    clickatell/version 
+    clickatell/api 
+    clickatell/response
+    
+).each do |lib|
+    require File.join(File.dirname(__FILE__), lib)
+end

data/lib/clickatell/api.rb

@@ -0,0 +1,148 @@
+module Clickatell
+  # This module provides the core implementation of the Clickatell
+  # HTTP service.
+  class API
+    attr_accessor :auth_options
+    
+    class << self
+      # Authenticates using the given credentials and returns an 
+      # API instance with the authentication options set to use the 
+      # resulting session_id.
+      def authenticate(api_id, username, password)
+        api = self.new
+        session_id = api.authenticate(api_id, username, password)
+        api.auth_options = { :session_id => session_id }
+        api
+      end
+      
+      # Set to true to enable debugging (off by default)
+      attr_accessor :debug_mode
+      
+      # Enable secure mode (SSL)
+      attr_accessor :secure_mode
+
+      # Allow customizing URL
+      attr_accessor :api_service_host
+
+      # Set to true to test message sending; this will not actually send 
+      # messages but will collect sent messages in a testable collection. 
+      # (off by default)
+      attr_accessor :test_mode
+    end
+    self.debug_mode = false
+    self.secure_mode = false
+    self.test_mode = false
+    
+    # Creates a new API instance using the specified +auth options+.
+    # +auth_options+ is a hash containing either a :session_id or 
+    # :username, :password and :api_key.
+    #
+    # Some API calls (authenticate, ping etc.) do not require any 
+    # +auth_options+. +auth_options+ can be updated using the accessor methods.
+    def initialize(auth_options={})
+      @auth_options = auth_options
+    end
+    
+    # Authenticates using the specified credentials. Returns
+    # a session_id if successful which can be used in subsequent
+    # API calls.
+    def authenticate(api_id, username, password)
+      response = execute_command('auth', 'http',
+        :api_id => api_id,
+        :user => username,
+        :password => password
+      )
+      parse_response(response)['OK']
+    end
+    
+    # Pings the service with the specified session_id to keep the
+    # session alive.
+    def ping(session_id)
+      execute_command('ping', 'http', :session_id => session_id)
+    end
+    
+    # Sends a message +message_text+ to +recipient+. Recipient
+    # number should have an international dialing prefix and
+    # no leading zeros (unless you have set a default prefix
+    # in your clickatell account centre).
+    #
+    # Additional options:
+    #    :from - the from number/name
+    #    :set_mobile_originated - mobile originated flag
+    #
+    # Returns a new message ID if successful.
+    def send_message(recipient, message_text, opts={})
+      valid_options = opts.only(:from, :mo, :callback, :cliMsgId)
+      valid_options.merge!(:req_feat => '48') if valid_options[:from]
+      valid_options.merge!(:mo => '1') if opts[:set_mobile_originated]
+      recipient = recipient.join(",")if recipient.is_a?(Array)
+      response = execute_command('sendmsg', 'http',
+        {:to => recipient, :text => message_text}.merge(valid_options)
+      ) 
+      response = parse_response(response)
+      response.is_a?(Array) ? response.map { |r| r['ID'] } : response['ID']
+    end
+
+    def send_wap_push(recipient, media_url, notification_text='', opts={})
+      valid_options = opts.only(:from)
+      valid_options.merge!(:req_feat => '48') if valid_options[:from]
+      response = execute_command('si_push', 'mms',
+        {:to => recipient, :si_url => media_url, :si_text => notification_text, :si_id => 'foo'}.merge(valid_options)
+      )
+      parse_response(response)['ID']
+    end
+    
+    # Returns the status of a message. Use message ID returned
+    # from original send_message call.
+    def message_status(message_id)
+      response = execute_command('querymsg', 'http', :apimsgid => message_id)
+      parse_response(response)['Status']
+    end
+    
+    # Returns the number of credits remaining as a float.
+    def account_balance
+      response = execute_command('getbalance', 'http')
+      parse_response(response)['Credit'].to_f
+    end
+    
+    def sms_requests
+      @sms_requests ||= []
+    end
+
+    protected      
+      def execute_command(command_name, service, parameters={}) #:nodoc:
+        executor = CommandExecutor.new(auth_hash, self.class.secure_mode, self.class.debug_mode, self.class.test_mode)
+        result = executor.execute(command_name, service, parameters)
+        
+        (sms_requests << executor.sms_requests).flatten! if self.class.test_mode
+        
+        result
+      end
+
+      def parse_response(raw_response) #:nodoc:
+        Clickatell::Response.parse(raw_response)
+      end
+      
+      def auth_hash #:nodoc:
+        if @auth_options[:session_id]
+          { :session_id => @auth_options[:session_id] }
+        elsif @auth_options[:api_id]
+          { :user => @auth_options[:username],
+            :password => @auth_options[:password],
+            :api_id => @auth_options[:api_key] }
+        else
+          {}
+        end
+      end
+    
+  end
+end
+
+%w( api/command
+    api/command_executor
+    api/error
+    api/message_status
+    
+).each do |lib|
+    require File.join(File.dirname(__FILE__), lib)
+end

data/lib/clickatell/api/command.rb

@@ -0,0 +1,31 @@
+require "cgi"
+module Clickatell
+  class API
+
+    # Represents a Clickatell HTTP gateway command in the form 
+    # of a complete URL (the raw, low-level request).
+    class Command
+      API_SERVICE_HOST = 'api.clickatell.com'
+
+      def initialize(command_name, service = 'http', opts={})
+        @command_name = command_name
+        @service = service
+        @options = { :secure => false }.merge(opts)
+      end
+  
+      # Returns a URL for the given parameters (a hash).
+      def with_params(param_hash)
+        param_string = '?' + param_hash.map { |key, value| "#{::CGI.escape(key.to_s)}=#{::CGI.escape(value.to_s)}" }.sort.join('&')
+        return URI.parse(File.join(api_service_uri, @command_name + param_string))
+      end
+
+      protected
+        def api_service_uri
+          protocol = @options[:secure] ? 'https' : 'http'
+          api_service_host = ((Clickatell::API.api_service_host.nil? || Clickatell::API.api_service_host.empty?) ? API_SERVICE_HOST : Clickatell::API.api_service_host)
+          return "#{protocol}://#{api_service_host}/#{@service}/"
+        end
+    end
+    
+  end
+end

data/lib/clickatell/api/command_executor.rb

@@ -0,0 +1,69 @@
+require 'net/http'
+require 'net/https'
+
+module Clickatell
+  class API
+   
+   class FakeHttpResponse
+     def body
+       "test"
+     end
+   end
+   
+    # Used to run commands agains the Clickatell gateway.
+    class CommandExecutor
+      def initialize(authentication_hash, secure=false, debug=false, test_mode=false)
+        @authentication_hash = authentication_hash
+        @debug = debug
+        @secure = secure
+        @test_mode = test_mode
+        
+        allow_request_recording if @test_mode
+      end
+      
+      def in_test_mode?
+        @test_mode
+      end
+      
+      # Builds a command object and sends it using HTTP GET. 
+      # Will output URLs as they are requested to stdout when 
+      # debugging is enabled.
+      def execute(command_name, service, parameters={})
+        request_uri = command(command_name, service, parameters)
+        puts "[debug] Sending request to #{request_uri}" if @debug
+        get_response(request_uri).first
+      end
+      
+      protected
+        def command(command_name, service, parameters) #:nodoc:
+          Command.new(command_name, service, :secure => @secure).with_params(
+            parameters.merge(@authentication_hash)
+          )
+        end
+        
+        def get_response(uri)
+          if in_test_mode?
+            sms_requests << uri
+            [FakeHttpResponse.new]
+          else
+            http = Net::HTTP.new(uri.host, uri.port)
+            http.use_ssl = (uri.scheme == 'https')
+            http.start do |http|
+              resp, body = http.get([uri.path, uri.query].join('?'))
+            end
+          end
+        end
+        
+      private
+      
+      def allow_request_recording
+        class << self
+          define_method :sms_requests do
+            @sms_requests ||= []
+          end
+        end
+      end
+    end 
+  
+  end
+end

data/lib/clickatell/api/error.rb

@@ -0,0 +1,25 @@
+module Clickatell
+  class API
+  
+    # Clickatell API Error exception.
+    class Error < StandardError
+      attr_reader :code, :message
+      
+      def initialize(code, message)
+        @code, @message = code, message
+      end
+      
+      # Creates a new Error from a Clickatell HTTP response string
+      # e.g.:
+      #
+      #  Error.parse("ERR: 001, Authentication error")
+      #  # =>  #<Clickatell::API::Error code='001' message='Authentication error'>
+      def self.parse(error_string)
+        error_details = error_string.split(':').last.strip
+        code, message = error_details.split(',').map { |s| s.strip }
+        self.new(code, message)
+      end
+    end
+  
+  end
+end

data/lib/clickatell/api/message_status.rb

@@ -0,0 +1,26 @@
+module Clickatell
+  class API
+   
+    class MessageStatus
+      STATUS_MAP = {
+        1  => 'Message unknown',
+        2  => 'Message queued',
+        3  => 'Delivered to gateway',
+        4  => 'Received by recipient',
+        5  => 'Error with message',
+        6  => 'User cancelled messaged delivery',
+        7  => 'Error delivering message',
+        8  => 'OK',
+        9  => 'Routing error',
+        10 => 'Message expired',
+        11 => 'Message queued for later delivery',
+        12 => 'Out of credit'
+      }
+      
+      def self.[](code)
+        STATUS_MAP[code]
+      end
+    end 
+  
+  end
+end

data/lib/clickatell/response.rb

@@ -0,0 +1,32 @@
+require 'yaml'
+
+module Clickatell
+  
+  # Used to parse HTTP responses returned from Clickatell API calls.
+  class Response
+
+    class << self
+      PARSE_REGEX = /[A-Za-z0-9]+:.*?(?:(?=[A-Za-z0-9]+:)|$)/
+      
+      # Returns the HTTP response body data as a hash.
+      def parse(http_response)
+        return { 'OK' => 'session_id' } if API.test_mode
+        
+        if http_response.body.scan(/ERR/).any?
+          raise Clickatell::API::Error.parse(http_response.body)
+        end
+        results = http_response.body.split("\n").map do |line|
+          # YAML.load converts integer strings that have leading zeroes into integers
+          # using octal rather than decimal.  This isn't what we want, so we'll strip out any
+          # leading zeroes in numbers here.
+          response_fields = line.scan(PARSE_REGEX)
+          response_fields = response_fields.collect { |field| field.gsub(/\b0+(\d+)\b/, '\1') }
+          YAML.load(response_fields.join("\n"))
+        end
+        results.length == 1 ? results.first : results
+      end
+      
+    end
+
+  end
+end

data/lib/clickatell/utility.rb

@@ -0,0 +1,6 @@
+module Clickatell
+  module Utility
+  end
+end
+
+require File.join(File.dirname(__FILE__), *%w[utility/options])

data/lib/clickatell/utility/options.rb

@@ -0,0 +1,110 @@
+require 'optparse'
+require 'ostruct'
+
+module Clickatell
+  module Utility
+    class Options #:nodoc:
+      class << self
+        
+        def parse(args)
+          @options = self.default_options
+          parser = OptionParser.new do |opts|
+            opts.banner = "Usage: sms [options] recipient(s) message"
+            opts.separator "  Recipients can be a comma-separated list, up to 100 max."
+            opts.separator ""
+            opts.separator "Specific options:"
+          
+            opts.on('-u', '--username USERNAME',
+              "Specify the clickatell username (overrides ~/.clickatell setting)") do |username|
+               @options.username = username 
+            end
+          
+            opts.on('-p', '--password PASSWORD',
+              "Specify the clickatell password (overrides ~/.clickatell setting)") do |password|
+               @options.password = password
+            end
+          
+            opts.on('-k', '--apikey API_KEY',
+              "Specify the clickatell API key (overrides ~/.clickatell setting)") do |key|
+               @options.api_key = key
+            end
+            
+            opts.on('-f', '--from NAME_OR_NUMBER',
+              "Specify the name or number that the SMS will appear from") do |from|
+               @options.from = from 
+            end
+          
+            opts.on('-b', '--show-balance',
+               "Shows the total number of credits remaining on your account") do
+               @options.show_balance = true
+            end
+          
+            opts.on('-s', '--status MESSAGE_ID',
+               "Displays the status of the specified message.") do |message_id|
+               @options.message_id = message_id
+               @options.show_status = true  
+            end
+            
+            opts.on('-S', '--secure',
+                "Sends request using HTTPS") do
+                Clickatell::API.secure_mode = true
+              end
+            
+            opts.on('-d', '--debug') do
+               Clickatell::API.debug_mode = true
+            end
+          
+            opts.on_tail('-h', '--help', "Show this message") do
+              puts opts
+              exit
+            end
+          
+            opts.on_tail('-v', '--version') do
+              puts "Ruby Clickatell SMS Utility #{Clickatell::VERSION}"
+              exit
+            end
+          end
+        
+          parser.parse!(args)
+          @options.recipient = ARGV[-2]
+          @options.message   = ARGV[-1]
+        
+          if (@options.message.nil? || @options.recipient.nil?) && send_message?
+            puts "You must specify a recipient and message!"
+            puts parser
+            exit
+          end
+          
+          @options.recipient = @options.recipient.split(",")
+
+          return @options
+        
+        rescue OptionParser::MissingArgument => e
+          switch_given = e.message.split(':').last.strip
+          puts "The #{switch_given} option requires an argument."
+          puts parser
+          exit
+        end
+      
+        def default_options
+          options = OpenStruct.new
+          config_file = File.open(File.join(ENV['HOME'], '.clickatell'))
+          config = YAML.load(config_file)
+          options.username = config['username']
+          options.password = config['password']
+          options.api_key  = config['api_key']
+          options.from     = config['from']
+          return options
+        rescue Errno::ENOENT
+          return options
+        end
+        
+        def send_message?
+          (@options.show_status.nil? &&
+           @options.show_balance.nil?)
+        end
+        
+      end
+    end
+  end
+end

data/lib/clickatell/version.rb

@@ -0,0 +1,13 @@
+module Clickatell #:nodoc:
+  module VERSION #:nodoc:
+    MAJOR = 0
+    MINOR = 7
+    TINY  = 0
+
+    STRING = [MAJOR, MINOR, TINY].join('.')
+    
+    def self.to_s
+      STRING
+    end
+  end
+end

data/lib/core-ext/hash.rb

@@ -0,0 +1,15 @@
+class Hash
+  # Returns a new hash containing only the keys specified
+  # that exist in the current hash.
+  #
+  #  {:a => '1', :b => '2', :c => '3'}.only(:a, :c)
+  #  # => {:a => '1', :c => '3'}
+  #
+  # Keys that do not exist in the original hash are ignored.
+  def only(*keys)
+    inject( {} ) do |new_hash, (key, value)|
+      new_hash[key] = value if keys.include?(key)
+      new_hash
+    end
+  end
+end

data/spec/api_spec.rb

@@ -0,0 +1,239 @@
+require File.dirname(__FILE__) + '/spec_helper'
+require File.dirname(__FILE__) + '/../lib/clickatell'
+
+class FakeHttp
+  def start(&block)
+    yield self
+  end
+end
+
+module Clickatell
+  
+  describe "API Command" do
+    before do
+      @command = API::Command.new('cmdname')
+    end
+    
+    after do
+      Clickatell::API.api_service_host = nil
+    end
+    
+    it "should return encoded URL for the specified command and parameters" do
+      url = @command.with_params(:param_one => 'abc', :param_two => '123')
+      url.should == URI.parse("http://api.clickatell.com/http/cmdname?param_one=abc&param_two=123")
+    end
+    
+    it "should URL encode any special characters in parameters" do
+      url = @command.with_params(:param_one => 'abc', :param_two => 'hello world & goodbye cruel world <grin>')
+      url.should == URI.parse("http://api.clickatell.com/http/cmdname?param_one=abc&param_two=hello+world+%26+goodbye+cruel+world+%3Cgrin%3E")
+    end
+    
+    it "should use a custom host when constructing command URLs if specified" do
+      Clickatell::API.api_service_host = 'api.clickatell-custom.co.uk'
+      url = @command.with_params(:param_one => 'abc', :param_two => '123')
+      url.should == URI.parse("http://api.clickatell-custom.co.uk/http/cmdname?param_one=abc&param_two=123")
+    end
+    
+    it "should use the default host if specified custom host is nil" do
+      Clickatell::API.api_service_host = nil
+      url = @command.with_params(:param_one => 'abc', :param_two => '123')
+      url.should == URI.parse("http://api.clickatell.com/http/cmdname?param_one=abc&param_two=123")
+    end
+    
+    it "should use the default host if specified custom host is an empty string" do
+      Clickatell::API.api_service_host = ''
+      url = @command.with_params(:param_one => 'abc', :param_two => '123')
+      url.should == URI.parse("http://api.clickatell.com/http/cmdname?param_one=abc&param_two=123")
+    end
+  end
+  
+  describe "Secure API Command" do
+    before do
+      @command = API::Command.new('cmdname', 'http', :secure => true)
+    end
+    
+    it "should use HTTPS" do
+      url = @command.with_params(:param_one => 'abc', :param_two => '123')
+      url.should == URI.parse("https://api.clickatell.com/http/cmdname?param_one=abc&param_two=123")
+    end
+  end
+    
+  describe "Command executor" do
+    it "should create an API command with the given params" do
+      executor = API::CommandExecutor.new(:session_id => '12345')
+      executor.stubs(:get_response).returns([])
+      API::Command.expects(:new).with('cmdname', 'http', :secure => false).returns(command = stub('Command'))
+      command.expects(:with_params).with(:param_one => 'foo', :session_id => '12345').returns(stub_everything('URI'))
+      executor.execute('cmdname', 'http', :param_one => 'foo')
+    end
+    
+    it "should send the URI generated by the created command via HTTP get and return the response" do
+      executor = API::CommandExecutor.new(:session_id => '12345')
+      command_uri = URI.parse('http://clickatell.com:8080/path?foo=bar')
+      API::Command.stubs(:new).returns(command = stub('Command', :with_params => command_uri))
+      Net::HTTP.stubs(:new).with(command_uri.host, command_uri.port).returns(http = FakeHttp.new)
+      http.stubs(:use_ssl=)
+      http.stubs(:get).with('/path?foo=bar').returns([response = stub('HTTP Response'), 'response body'])
+      executor.execute('cmdname', 'http').should == response
+    end
+    
+    it "should send the command over a secure HTTPS connection if :secure option is set to true" do
+      executor = API::CommandExecutor.new({:session_id => '12345'}, secure = true)
+      Net::HTTP.stubs(:new).returns(http = mock('HTTP'))
+      http.expects(:use_ssl=).with(true)
+      http.stubs(:start).returns([])
+      executor.execute('cmdname', 'http')
+    end
+  end
+  
+  describe "API" do
+    before do
+      API.debug_mode = false
+      API.secure_mode = false
+      API.test_mode = false
+      
+      @executor = mock('command executor')
+      @api = API.new(:session_id => '1234')
+      API::CommandExecutor.stubs(:new).with({:session_id => '1234'}, false, false, false).returns(@executor)
+    end
+    
+    it "should use the api_id, username and password to authenticate and return the new session id" do
+      @executor.expects(:execute).with('auth', 'http', 
+        :api_id => '1234',
+        :user => 'joebloggs',
+        :password => 'superpass'
+      ).returns(response = stub('response'))
+      Response.stubs(:parse).with(response).returns('OK' => 'new_session_id')        
+      @api.authenticate('1234', 'joebloggs', 'superpass').should == 'new_session_id'
+    end
+    
+    it "should support ping, using the current session_id" do
+      @executor.expects(:execute).with('ping', 'http', :session_id => 'abcdefg').returns(response = stub('response'))
+      @api.ping('abcdefg').should == response
+    end
+    
+    it "should support sending messages to a specified number, returning the message id" do
+      @executor.expects(:execute).with('sendmsg', 'http', 
+        :to => '4477791234567',
+        :text => 'hello world & goodbye'
+      ).returns(response = stub('response'))
+      Response.stubs(:parse).with(response).returns('ID' => 'message_id')      
+      @api.send_message('4477791234567', 'hello world & goodbye').should == 'message_id'
+    end
+    
+    it "should support sending messages to a multiple numbers, returning the message ids" do
+      @executor.expects(:execute).with('sendmsg', 'http', 
+        :to => '4477791234567,447779999999',
+        :text => 'hello world & goodbye'
+      ).returns(response = stub('response'))
+      Response.stubs(:parse).with(response).returns([{'ID' => 'message_1_id'}, {'ID' => 'message_2_id'}])
+      @api.send_message(['4477791234567', '447779999999'], 'hello world & goodbye').should == ['message_1_id', 'message_2_id']
+    end
+    
+    it "should set the :from parameter and set the :req_feat to 48 when using a custom from string when sending a message" do
+      @executor.expects(:execute).with('sendmsg', 'http', has_entries(:from => 'LUKE', :req_feat => '48')).returns(response = stub('response'))
+      Response.stubs(:parse).with(response).returns('ID' => 'message_id')
+      @api.send_message('4477791234567', 'hello world', :from => 'LUKE')
+    end
+    
+    it "should set the :mo flag to 1 when :set_mobile_originated is true when sending a message" do
+      @executor.expects(:execute).with('sendmsg', 'http', has_entry(:mo => '1')).returns(response=mock('response'))
+      Response.stubs(:parse).with(response).returns('ID' => 'message_id')
+      @api.send_message('4477791234567', 'hello world', :set_mobile_originated => true)
+    end
+    
+    it "should set the callback flag to the number passed in the options hash" do
+      @executor.expects(:execute).with('sendmsg', 'http', has_entry(:callback => 1)).returns(response=mock('response'))
+      Response.stubs(:parse).with(response).returns('ID' => 'message_id')
+      @api.send_message('4477791234567', 'hello world', :callback => 1)
+    end
+    
+    it "should ignore any invalid parameters when sending a message" do
+      @executor.expects(:execute).with('sendmsg', 'http', Not(has_key(:any_old_param))).returns(response = stub('response'))
+      Response.stubs(:parse).returns('ID' => 'foo')
+      @api.send_message('4477791234567', 'hello world', :from => 'LUKE', :any_old_param => 'test')
+    end
+    
+    it "should support message status query for a given message id, returning the message status" do
+      @executor.expects(:execute).with('querymsg', 'http', :apimsgid => 'messageid').returns(response = stub('response'))
+      Response.expects(:parse).with(response).returns('ID' => 'message_id', 'Status' => 'message_status')
+      @api.message_status('messageid').should == 'message_status'
+    end
+    
+    it "should support balance query, returning number of credits as a float" do
+      @executor.expects(:execute).with('getbalance', 'http', {}).returns(response=mock('response'))
+      Response.stubs(:parse).with(response).returns('Credit' => '10.0')
+      @api.account_balance.should == 10.0
+    end
+    
+    it "should raise an API::Error if the response parser raises" do
+      @executor.stubs(:execute)
+      Response.stubs(:parse).raises(Clickatell::API::Error.new('', ''))
+      proc { @api.account_balance }.should raise_error(Clickatell::API::Error)
+    end
+  end
+  
+  describe API, ' when authenticating' do
+    it "should authenticate to retrieve a session_id and return a new API instance using that session id" do
+      API.stubs(:new).returns(api = mock('api'))
+      api.stubs(:authenticate).with('my_api_key', 'joebloggs', 'mypassword').returns('new_session_id')
+      api.expects(:auth_options=).with(:session_id => 'new_session_id')
+      API.authenticate('my_api_key', 'joebloggs', 'mypassword')
+    end
+  end
+  
+  describe API, ' with no authentication options set' do
+    it "should build commands with no authentication options" do
+      api = API.new
+      API::CommandExecutor.stubs(:new).with({}, false, false, false).returns(executor = stub('command executor'))
+      executor.stubs(:execute)
+      api.ping('1234')
+    end
+  end
+  
+  describe API, ' in secure mode' do
+    it "should execute commands securely" do
+      API.secure_mode = true
+      api = API.new
+      API::CommandExecutor.expects(:new).with({}, true, false, false).returns(executor = stub('command executor'))
+      executor.stubs(:execute)
+      api.ping('1234')
+    end
+  end
+  
+  describe "API Error" do
+    it "should parse http response string to create error" do
+      response_string = "ERR: 001, Authentication error"
+      error = Clickatell::API::Error.parse(response_string)
+      error.code.should == '001'
+      error.message.should == 'Authentication error'
+    end
+  end
+  
+  describe API, "#test_mode" do
+    before(:each) do
+      API.secure_mode = false
+      API.test_mode = true
+      @api = API.new
+    end
+    
+    it "should create a new CommandExecutor with test_mode parameter set to true" do
+      API::CommandExecutor.expects(:new).with({}, false, false, true).once.returns(executor = mock('command executor'))
+      executor.stubs(:execute)
+      executor.stubs(:sms_requests).returns([])
+      @api.ping('1234')
+    end
+    
+    it "should record all commands" do
+      @api.ping('1234')
+      @api.sms_requests.should_not be_empty
+    end
+    
+    it "should return the recorded commands in a flattened array" do
+      @api.ping('1234')
+      @api.sms_requests.size.should == 1
+      @api.sms_requests.first.should_not be_instance_of(Array)
+    end
+  end
+  
+end

data/spec/command_executor_spec.rb

@@ -0,0 +1,75 @@
+require File.dirname(__FILE__) + '/spec_helper'
+require File.dirname(__FILE__) + '/../lib/clickatell'
+
+module Clickatell
+  describe "API::CommandExecutor" do
+    it "should have test mode" do
+      executor = API::CommandExecutor.new({}, false, false, :test_mode)
+      executor.should be_in_test_mode
+    end
+    
+    it "should default to not test mode" do
+      executor = API::CommandExecutor.new({})
+      executor.should_not be_in_test_mode
+    end
+
+    describe "#execute" do
+      describe "in non-test mode" do
+        before(:each) do
+          @executor = API::CommandExecutor.new({})
+        end
+        
+        it "should not record requests" do
+          @executor.should_not respond_to(:sms_requests)
+        end
+      end
+      
+      describe "in test mode" do
+        before(:each) do
+          @params = {:foo => 1, :bar => 2}
+          @executor = API::CommandExecutor.new(@params, false, false, :test_mode)
+        end
+        
+        it "should not make any network calls" do
+          Net::HTTP.expects(:new).never
+          @executor.execute("foo", "http")
+        end
+        
+        it "should start with an empty request collection" do
+          @executor.sms_requests.should be_empty
+        end
+        
+        it "should record sms requests" do
+          @executor.execute("bar", "http")
+          @executor.sms_requests.should_not be_empty
+        end
+        
+        it "should record a request for each call" do
+          @executor.execute("wibble", "http")
+          @executor.sms_requests.size.should == 1
+          @executor.execute("foozle", "http")
+          @executor.sms_requests.size.should == 2
+        end
+        
+        it "should return a response that approximates a true Net::HttpResponse" do
+          response = @executor.execute("throat-warbler", "http")
+          response.body.should == "test"
+        end
+        
+        describe "each recorded request" do
+          it "should return the command information" do
+            command = "rum_tum_tum"
+            @executor.execute(command, "http")
+            
+            uri = @executor.sms_requests.first
+            uri.host.should == "api.clickatell.com"
+            uri.path.should include(command)
+            @params.collect { |k, v| "#{k}=#{v}"}.each do |query_parameter|
+              uri.query.should include(query_parameter)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/spec/hash_ext_spec.rb

@@ -0,0 +1,14 @@
+require File.dirname(__FILE__) + '/spec_helper'
+require File.dirname(__FILE__) + '/../lib/clickatell'
+
+describe Hash do
+  it "should return only the keys specified" do
+    hash = {:a => 'foo', :b => 'bar', :c => 'baz'}
+    hash.only(:a, :b).should == {:a => 'foo', :b => 'bar'}
+  end
+  
+  it "should return only the keys specified, ignoring keys that do not exist" do
+    hash = {:a => 'foo', :b => 'bar', :c => 'baz'}
+    hash.only(:a, :d).should == {:a => 'foo'}
+  end
+end

data/spec/response_spec.rb

@@ -0,0 +1,48 @@
+require File.dirname(__FILE__) + '/spec_helper'
+require File.dirname(__FILE__) + '/../lib/clickatell'
+
+module Clickatell
+
+  describe "Response parser" do
+    before do
+      Clickatell::API::Error.stubs(:parse).returns(Clickatell::API::Error.new('', ''))
+    end
+    
+    before(:each) do
+      API.test_mode = false
+    end
+    
+    it "should return hash for one-line success response" do
+      Response.parse(stub('response', :body => 'k1: foo k2: bar')).should == {'k1' => 'foo', 'k2' => 'bar'}
+    end
+    
+    it "should return array of hashes for multi-line success response" do
+      Response.parse(stub('response', :body => "k1: foo\nk2: bar")).should == [{'k1' => 'foo'}, {'k2' => 'bar'}]
+    end
+    
+    it "should raise API::Error if response contains an error message" do
+      proc { Response.parse(stub('response', :body => 'ERR: 001, Authentication failed')) }.should raise_error(Clickatell::API::Error)
+    end
+
+    {
+      '001' => 1, '002' => 2,  '003' => 3,  '004' => 4,
+      '005' => 5, '006' => 6,  '007' => 7,  '008' => 8,
+      '009' => 9, '010' => 10, '011' => 11, '012' => 12
+    }.each do |status_str, status_int|
+      it "should parse a message status code of #{status_int} when the response body contains a status code of #{status_str}" do
+        Response.parse(stub('response', :body => "ID: 0d1d7dda17d5a24edf1555dc0b679d0e Status: #{status_str}")).should == {'ID' => '0d1d7dda17d5a24edf1555dc0b679d0e', 'Status' => status_int}
+      end
+    end
+    
+    describe "in test mode" do
+      before(:each) do
+        API.test_mode = true
+      end
+      
+      it "should return something approximating a session_id" do
+      Response.parse("pretty much anything").should == { 'OK' => 'session_id' }
+      end
+    end
+  end
+  
+end

data/spec/spec.opts

@@ -0,0 +1 @@
+--colour

data/spec/spec_helper.rb

@@ -0,0 +1,8 @@
+require 'rubygems'
+require 'spec'
+require 'mocha'
+require 'test/unit'
+
+Spec::Runner.configure do |config|
+  config.mock_with :mocha
+end

metadata

@@ -0,0 +1,88 @@
+--- !ruby/object:Gem::Specification 
+name: dimiro1-clickatell
+version: !ruby/object:Gem::Version 
+  version: 0.7.0
+platform: ruby
+authors: 
+- Luke Redpath
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-10-07 00:00:00 -03:00
+default_executable: sms
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: rspec
+  type: :development
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+    version: 
+description: 
+email: luke@lukeredpath.co.uk
+executables: 
+- sms
+extensions: []
+
+extra_rdoc_files: 
+- RDOC_README.txt
+- History.txt
+- License.txt
+files: 
+- History.txt
+- License.txt
+- RDOC_README.txt
+- README.textile
+- bin/sms
+- spec/api_spec.rb
+- spec/command_executor_spec.rb
+- spec/hash_ext_spec.rb
+- spec/response_spec.rb
+- spec/spec.opts
+- spec/spec_helper.rb
+- lib/clickatell/api/command.rb
+- lib/clickatell/api/command_executor.rb
+- lib/clickatell/api/error.rb
+- lib/clickatell/api/message_status.rb
+- lib/clickatell/api.rb
+- lib/clickatell/response.rb
+- lib/clickatell/utility/options.rb
+- lib/clickatell/utility.rb
+- lib/clickatell/version.rb
+- lib/clickatell.rb
+- lib/core-ext/hash.rb
+has_rdoc: true
+homepage: http://clickatell.rubyforge.org
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --main
+- RDOC_README.txt
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: clickatell
+rubygems_version: 1.3.5
+signing_key: 
+specification_version: 2
+summary: Ruby interface to the Clickatell SMS gateway service.
+test_files: []
+