clickatell 0.2.0 → 0.3.0

data/History.txt

@@ -1,13 +1,19 @@
+== 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

data/Manifest.txt

@@ -11,10 +11,12 @@ lib/clickatell/response.rb
 lib/clickatell/utility.rb
 lib/clickatell/utility/options.rb
 lib/clickatell/version.rb
+lib/core-ext/hash.rb
 scripts/txt2html
 setup.rb
 spec/api_spec.rb
 spec/connection_spec.rb
+spec/hash_ext_spec.rb
 spec/response_spec.rb
 spec/spec.opts
 spec/spec_helper.rb

data/README.txt

@@ -33,4 +33,8 @@ file called .clickatell that resembles the following:
   
 You can then use the sms utility to send a message to a single recipient:
 
-  sms 447771234567 'Hello from clickatell'
+  sms 447771234567 'Hello from clickatell'
+  
+Run +sms+ without any arguments for a full list of options.
+
+See http://clickatell.rubyforge.org for further instructions.

data/Rakefile

@@ -129,7 +129,7 @@ end
 
 Rake::RDocTask.new('docs') do |rd|
   rd.main = 'README.txt'
-  rd.rdoc_files.include('README.txt', 'License.txt', 'lib/**/*.rb')
+  rd.rdoc_files.include('README.txt', 'History.txt', 'License.txt', 'lib/**/*.rb')
   rd.rdoc_dir = 'doc'
   rd.options << '--style=http://clickatell.rubyforge.org/stylesheets/rdoc.css'
   rd.options << '--tab-width=2'

data/bin/sms

@@ -16,31 +16,39 @@ end
 options = Clickatell::Utility::Options.parse(ARGV)
 connection = Clickatell::Connection.new(options.api_key, options.username, options.password)
 
-if options.show_balance
-  puts "Retrieving account balance..."
-  puts "You have #{connection.account_balance} credits remaining."
-  exit 0
-else
-  begin
+begin
+  if options.show_balance
+    puts "Retrieving account balance..."
+    puts "You have #{connection.account_balance} credits remaining."
+    exit 0
+  elsif options.show_status
+    puts "Getting status of message ##{options.message_id}."
+    status = connection.message_status(options.message_id)
+    puts "Status: #{Clickatell::API::MessageStatus[status]} (##{status})."
+    exit 0
+  else
     puts "Sending '#{options.message}' to #{options.recipient}..."
-    connection.send_message(options.recipient, options.message)
-    puts "Done."
+    additional_opts = {}
+    additional_opts[:from] = options.from if options.from
+    msg_id = connection.send_message(options.recipient, options.message, additional_opts)
+    puts "Message sent successfully (message id: #{msg_id})."
     exit 0
-  rescue Clickatell::API::Error => e
-    case e.code
-    when '001', '002', '003', '005'
-      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
+  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
 end

data/lib/clickatell.rb

@@ -1,6 +1,7 @@
 module Clickatell
 end
 
+require File.join(File.dirname(__FILE__), *%w[core-ext/hash])
 require File.join(File.dirname(__FILE__), *%w[clickatell/version])
 require File.join(File.dirname(__FILE__), *%w[clickatell/api])
 require File.join(File.dirname(__FILE__), *%w[clickatell/response])

data/lib/clickatell/api.rb

@@ -30,16 +30,20 @@ module Clickatell
       # no leading zeros (unless you have set a default prefix
       # in your clickatell account centre).
       #
-      # +auth_options+: a hash of credentials to be used in this
+      # Takes a hash of auth_options to be used in this
       # API call. Either api_id/username/password or session_id
       # for an existing authenticated session.
       #
+      # Additional options:
+      #    :from - the from number/name
+      #
       # Returns a new message ID if successful.
-      def send_message(recipient, message_text, auth_options)
+      def send_message(recipient, message_text, auth_options, opts={})
+        valid_options = opts.only(:from)
         response = execute_command('sendmsg', {
           :to => recipient,
           :text => message_text
-        }.merge( auth_hash(auth_options) )) 
+        }.merge(auth_hash(auth_options)).merge(valid_options)) 
         parse_response(response)['ID']
       end
       
@@ -131,5 +135,26 @@ module Clickatell
       end
     end
     
+    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/connection.rb

@@ -36,8 +36,9 @@ module Clickatell
     protected
       # Executes the given +api_method+ by delegating to the API 
       # module, using the current session_id for authentication.
-      def execute_api_call(api_method, params)
+      def execute_api_call(api_method, params, additional_options)
         params << {:session_id => current_session_id}
+        params << additional_options if additional_options
         API.send(api_method, *params)
       end
       
@@ -50,7 +51,8 @@ module Clickatell
       # Dispatch any API methods to the API module.
       def method_missing(method, *args, &block)
         if API.respond_to?(method)
-          execute_api_call(method, args)
+          additional_options = args.pop if args.last.is_a?(Hash)
+          execute_api_call(method, args, additional_options)
         else
           super(method, args, &block)
         end

data/lib/clickatell/utility/options.rb

@@ -4,73 +4,94 @@ require 'ostruct'
 module Clickatell
   module Utility
     class Options #:nodoc:
-      def self.parse(args)
-        options = self.default_options
-        parser = OptionParser.new do |opts|
-          opts.banner = "Usage: sms [options] recipient message"
-          opts.separator ""
-          opts.separator "Specific options:"
+      class << self
+        
+        def parse(args)
+          @options = self.default_options
+          parser = OptionParser.new do |opts|
+            opts.banner = "Usage: sms [options] recipient message"
+            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('-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('-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('-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('-b', '--show-balance',
+               "Shows the total number of credits remaining on your account") do
+               @options.show_balance = true
+            end
           
-          opts.on_tail('-h', '--help', "Show this message") do
-            puts opts
-            exit
-          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_tail('-v', '--version') do
-            puts "Ruby Clickatell SMS Utility #{Clickatell::VERSION}"
-            exit
+            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
-        end
         
-        parser.parse!(args)
-        options.recipient = ARGV[-2]
-        options.message   = ARGV[-1]
+          parser.parse!(args)
+          @options.recipient = ARGV[-2]
+          @options.message   = ARGV[-1]
         
-        if (options.message.nil? || options.recipient.nil?) && !options.show_balance
-          puts "You must specify a recipient and message!"
+          if (@options.message.nil? || @options.recipient.nil?) && send_message?
+            puts "You must specify a recipient and message!"
+            puts parser
+            exit
+          end
+
+          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
-
-        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 self.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']
-        return options
-      rescue Errno::ENOENT
-        return options
+        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

data/lib/clickatell/version.rb

@@ -1,7 +1,7 @@
 module Clickatell #:nodoc:
   module VERSION #:nodoc:
     MAJOR = 0
-    MINOR = 2
+    MINOR = 3
     TINY  = 0
 
     STRING = [MAJOR, MINOR, TINY].join('.')

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)
+    self.inject({}) do |new_hash, (key, value)|
+      new_hash[key] = value if keys.include?(key)
+      new_hash
+    end
+  end
+end

data/spec/api_spec.rb

@@ -4,21 +4,28 @@ require File.dirname(__FILE__) + '/../lib/clickatell'
 module Clickatell
   
   describe "API Command" do
+    before do
+      @command = API::Command.new('cmdname')
+    end
+    
     it "should return encoded URL for the specified command and parameters" do
-      command = API::Command.new('cmdname')
-      url = command.with_params(:param_one => 'abc', :param_two => '123')
+      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
-      command = API::Command.new('cmdname')
-      url = command.with_params(:param_one => 'abc', :param_two => 'hello world')
+      url = @command.with_params(:param_one => 'abc', :param_two => 'hello world')
       url.should == URI.parse("http://api.clickatell.com/http/cmdname?param_one=abc&param_two=hello%20world")
     end
+  end
+  
+  describe "Secure API Command" do
+    before do
+      @command = API::Command.new('cmdname', :secure => true)
+    end
     
-    it "should support non-secure api commands" do
-      command = API::Command.new('cmdname', :secure => true)
-      url = command.with_params(:param_one => 'abc', :param_two => '123')
+    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
@@ -72,6 +79,28 @@ module Clickatell
       API.send_message('4477791234567', 'hello world', :session_id => 'abcde').should == 'message_id'
     end
     
+    it "should support sending messages with custom from number, returning the message id" do
+      API.should_receive(:execute_command).with('sendmsg',
+        :session_id => 'abcde',
+        :to => '4477791234567',
+        :text => 'hello world',
+        :from => 'LUKE'
+      ).and_return(response=mock('response'))
+      Response.should_receive(:parse).with(response).and_return('ID' => 'message_id')
+      API.send_message('4477791234567', 'hello world', {:session_id => 'abcde'}, :from => 'LUKE')
+    end
+    
+    it "should ignore any invalid parameters when sending message" do
+      API.should_receive(:execute_command).with('sendmsg',
+        :session_id => 'abcde',
+        :to => '4477791234567',
+        :text => 'hello world',
+        :from => 'LUKE'
+      ).and_return(response=mock('response'))
+      Response.stub!(:parse).and_return('ID' => 'foo')
+       API.send_message('4477791234567', 'hello world', {:session_id => 'abcde'}, :from => 'LUKE', :any_old_param => 'test')
+    end
+    
     it "should support message status query with authentication, returning message status" do
       API.should_receive(:execute_command).with('querymsg',
         :api_id => '1234',
@@ -84,7 +113,7 @@ module Clickatell
         :username => 'joebloggs', :password => 'superpass', :api_key => '1234'
       ).should == 'message_status'
     end
-    
+      
     it "should support message status query with pre-auth" do
       API.should_receive(:execute_command).with('querymsg',
         :session_id => 'abcde',

data/spec/connection_spec.rb

@@ -13,12 +13,20 @@ module Clickatell
   end
   
   describe Connection, ' when authenticated' do
+    before do
+      @connection = Connection.new('my_api_key', 'myusername', 'mypassword')
+      @connection.stub!(:session_id).and_return('session_id')
+    end
+    
     it "should send command with session_id without re-authenticating" do
-      connection = Connection.new('my_api_key', 'myusername', 'mypassword')
-      connection.stub!(:session_id).and_return('session_id')
       API.should_receive(:authenticate).never
       API.should_receive(:send_message).with('4477791234567', 'hello world', :session_id => 'session_id')
-      connection.send_message('4477791234567', 'hello world')
+      @connection.send_message('4477791234567', 'hello world')
+    end
+    
+    it "should support API calls with additional opts, passing them after auth options" do
+      API.should_receive(:send_message).with('4477791234567', 'hello world', {:session_id => 'session_id'}, :from => 'LUKE')
+      @connection.send_message('4477791234567', 'hello world', {:from => 'LUKE'})
     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

@@ -5,19 +5,18 @@ module Clickatell
 
   describe "Response parser" do
     before do
+      @raw_response = stub('response')
       Clickatell::API::Error.stub!(:parse).and_return(Clickatell::API::Error.new('', ''))
     end
     
     it "should return hash for one-line success response" do
-      raw_response = stub('response')
-      raw_response.stub!(:body).and_return('k1: foo k2: bar')
-      Response.parse(raw_response).should == {'k1' => 'foo', 'k2' => 'bar'}
+      @raw_response.stub!(:body).and_return('k1: foo k2: bar')
+      Response.parse(@raw_response).should == {'k1' => 'foo', 'k2' => 'bar'}
     end
     
     it "should raise API::Error if response contains an error message" do
-      raw_response = stub('response')
-      raw_response.stub!(:body).and_return('ERR: 001, Authentication failed')
-      proc { Response.parse(raw_response) }.should raise_error(Clickatell::API::Error)
+      @raw_response.stub!(:body).and_return('ERR: 001, Authentication failed')
+      proc { Response.parse(@raw_response) }.should raise_error(Clickatell::API::Error)
     end
   end
   

data/website/index.html

@@ -16,7 +16,7 @@
   
   <div id="header">
     
-    <h1>Clickatell Ruby API <span class="version">0.2.0</span>
+    <h1>Clickatell Ruby API <span class="version">0.3.0</span>
     <span class="tagline">gem install clickatell</span></h1>
     
   </div>
@@ -101,6 +101,16 @@ $ sms -u your_username -p your_password -k your_api_key 447771234567 'Hello from
 	<p>These values will take presedence over any values in your ~/.clickatell file.</p>
 
 
+	<p>You can also specify the name or number that will appear in the &#8220;From&#8221; label on the recipients phone. You can either add a &#8220;from&#8221; key to your .clickatell file or manually using the&#8212;from option:</p>
+
+
+<pre><code>
+$ sms --from 'Luke Redpath' 447771234567 'Hello from clickatell'
+</code></pre>
+
+	<p>The &#8220;from&#8221; option can either be a 16 digit number or an 11 character alpha-numeric string.</p>
+
+
 	<p>You can also use the <ins>sms</ins> utility to check your Clickatell account balance:</p>
 
 
@@ -108,6 +118,16 @@ $ sms -u your_username -p your_password -k your_api_key 447771234567 'Hello from
 $ sms --show-balance
 </code></pre>
 
+	<p>Whenever you send a message with the <ins>sms</ins> utility, it will return an alpha-numeric message ID. You can use this message ID to retrieve the message&#8217;s current status using the&#8212;status option:</p>
+
+
+<pre><code>
+$ sms --status 30b7d15bffb38695ba26e77c9c20f4ec
+</code></pre>
+
+	<p>This will return a message status and message status code.</p>
+
+
 	<p>Run <ins>sms</ins> without any arguments for a full list of options.</p>
 
 
@@ -129,7 +149,7 @@ $ sms --show-balance
   	<div id="footer">
   	  <p class="copyright">
         <a href="http://rubyforge.org/projects/clickatell">Rubyforge Project Page</a> | 
-        <a href="http://rubyforge.org/frs/?group_id=4295&amp;release_id=13922">Download latest version (0.2.0)</a> | 
+        <a href="http://rubyforge.org/frs/?group_id=4295&amp;release_id=13922">Download latest version (0.3.0)</a> | 
         <a href="rdoc/">RDoc</a>
       </p>
   	</div>

data/website/index.txt

@@ -64,12 +64,28 @@ $ sms -u your_username -p your_password -k your_api_key 447771234567 'Hello from
 
 These values will take presedence over any values in your ~/.clickatell file.
 
+You can also specify the name or number that will appear in the "From" label on the recipients phone. You can either add a "from" key to your .clickatell file or manually using the --from option:
+
+<pre><code>
+$ sms --from 'Luke Redpath' 447771234567 'Hello from clickatell'
+</code></pre>
+
+The "from" option can either be a 16 digit number or an 11 character alpha-numeric string.
+
 You can also use the +sms+ utility to check your Clickatell account balance:
 
 <pre><code>
 $ sms --show-balance
 </code></pre>
 
+Whenever you send a message with the +sms+ utility, it will return an alpha-numeric message ID. You can use this message ID to retrieve the message's current status using the --status option:
+
+<pre><code>
+$ sms --status 30b7d15bffb38695ba26e77c9c20f4ec
+</code></pre>
+
+This will return a message status and message status code.
+
 Run +sms+ without any arguments for a full list of options.
 
 h3. License

metadata

@@ -3,8 +3,8 @@ rubygems_version: 0.9.2
 specification_version: 1
 name: clickatell
 version: !ruby/object:Gem::Version 
-  version: 0.2.0
-date: 2007-08-21 00:00:00 +01:00
+  version: 0.3.0
+date: 2007-08-23 00:00:00 +01:00
 summary: Ruby interface to the Clickatell SMS gateway service.
 require_paths: 
 - lib
@@ -42,10 +42,12 @@ files:
 - lib/clickatell/utility.rb
 - lib/clickatell/utility/options.rb
 - lib/clickatell/version.rb
+- lib/core-ext/hash.rb
 - scripts/txt2html
 - setup.rb
 - spec/api_spec.rb
 - spec/connection_spec.rb
+- spec/hash_ext_spec.rb
 - spec/response_spec.rb
 - spec/spec.opts
 - spec/spec_helper.rb