clickatell 0.1.0 → 0.2.0

data/History.txt

@@ -1,4 +1,15 @@
+== 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
 
-* 1 major enhancement:
-  * Initial release
+* Initial release.

data/Manifest.txt

@@ -25,5 +25,6 @@ website/javascripts/codehighlighter/code_highlighter.js
 website/javascripts/codehighlighter/ruby.js
 website/javascripts/rounded_corners_lite.inc.js
 website/stylesheets/limechoc.css
+website/stylesheets/rdoc.css
 website/stylesheets/screen.css
 website/template.rhtml

data/Rakefile

@@ -127,6 +127,16 @@ task :check_version do
   end
 end
 
+Rake::RDocTask.new('docs') do |rd|
+  rd.main = 'README.txt'
+  rd.rdoc_files.include('README.txt', 'License.txt', 'lib/**/*.rb')
+  rd.rdoc_dir = 'doc'
+  rd.options << '--style=http://clickatell.rubyforge.org/stylesheets/rdoc.css'
+  rd.options << '--tab-width=2'
+  rd.options << '--inline-source'
+  rd.options << '--line-numbers'
+end
+
 namespace :spec do
   desc "Run the specs under spec"
   Spec::Rake::SpecTask.new('all') do |t|

data/bin/sms

@@ -1,5 +1,4 @@
 #!/usr/bin/env ruby
-require 'pp'
 
 local_libs = [
  File.join(File.dirname(__FILE__), *%w[../lib/clickatell]),
@@ -17,7 +16,31 @@ end
 options = Clickatell::Utility::Options.parse(ARGV)
 connection = Clickatell::Connection.new(options.api_key, options.username, options.password)
 
-puts "Sending '#{options.message}' to #{options.recipient}."
-connection.send_message(options.recipient, options.message)
-puts "Done."
-exit 0
+if options.show_balance
+  puts "Retrieving account balance..."
+  puts "You have #{connection.account_balance} credits remaining."
+  exit 0
+else
+  begin
+    puts "Sending '#{options.message}' to #{options.recipient}..."
+    connection.send_message(options.recipient, options.message)
+    puts "Done."
+    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
+end

data/lib/clickatell/api.rb

@@ -52,6 +52,13 @@ module Clickatell
         }.merge( auth_hash(auth_options) ))
         parse_response(response)['Status']
       end
+      
+      # Returns the number of credits remaining as a float. 
+      # See send_message() for auth_options.
+      def account_balance(auth_options)
+        response = execute_command('getbalance', auth_hash(auth_options))
+        parse_response(response)['Credit'].to_f
+      end
 
       protected
         # Builds a command and sends it via HTTP GET.
@@ -104,5 +111,25 @@ module Clickatell
         end
     end
     
+    # 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/response.rb

@@ -10,6 +10,9 @@ module Clickatell
       
       # Returns the HTTP response body data as a hash.
       def parse(http_response)
+        if http_response.body.scan(/ERR/).any?
+          raise Clickatell::API::Error.parse(http_response.body)
+        end
         YAML.load(http_response.body.scan(PARSE_REGEX).join("\n"))
       end
       

data/lib/clickatell/utility/options.rb

@@ -7,25 +7,30 @@ module Clickatell
       def self.parse(args)
         options = self.default_options
         parser = OptionParser.new do |opts|
-          opts.banner = "Usage: sms [options] recipient_number message"
+          opts.banner = "Usage: sms [options] recipient message"
           opts.separator ""
           opts.separator "Specific options:"
           
-          opts.on('-u', '--username [USERNAME]',
+          opts.on('-u', '--username USERNAME',
             "Specify the clickatell username (overrides ~/.clickatell setting)") do |username|
              options.username = username 
           end
           
-          opts.on('-p', '--password [PASSWORD]',
+          opts.on('-p', '--password PASSWORD',
             "Specify the clickatell password (overrides ~/.clickatell setting)") do |password|
              options.password = password
           end
           
-          opts.on('-k', '--apikey [API_KEY]',
+          opts.on('-k', '--apikey API_KEY',
             "Specify the clickatell API key (overrides ~/.clickatell setting)") do |key|
              options.api_key = key
           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
@@ -40,7 +45,20 @@ module Clickatell
         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!"
+          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

data/lib/clickatell/version.rb

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

data/spec/api_spec.rb

@@ -24,7 +24,7 @@ module Clickatell
   end
   
   describe "Command executor" do
-    it "should create an API command and send it via HTTP get" do
+    it "should create an API command and send it via HTTP get, returning the raw http response" do
       API::Command.should_receive(:new).with('cmdname').and_return(cmd=mock('command'))
       cmd.should_receive(:with_params).with(:param_one => 'foo').and_return(uri=mock('uri'))
       Net::HTTP.should_receive(:get_response).with(uri).and_return(raw_response=mock('http response'))
@@ -93,6 +93,39 @@ module Clickatell
       Response.should_receive(:parse).with(response).and_return('ID' => 'message_id', 'Status' => 'message_status')
       API.message_status('messageid', :session_id => 'abcde').should == 'message_status'
     end
+    
+    it "should support balance query with authentication, returning number of credits as a float" do
+      API.should_receive(:execute_command).with('getbalance',
+        :api_id => '1234',
+        :user => 'joebloggs',
+        :password => 'superpass'
+      ).and_return(response=mock('response'))
+      Response.should_receive(:parse).with(response).and_return('Credit' => '10.0')
+      API.account_balance(:username => 'joebloggs', :password => 'superpass', :api_key => '1234').should == 10.0
+    end
+    
+    it "should support balance query with pre-auth, returning number of credits as a float" do
+      API.should_receive(:execute_command).with('getbalance',
+        :session_id => 'abcde'
+      ).and_return(response=mock('response'))
+      Response.should_receive(:parse).with(response).and_return('Credit' => '10.0')
+      API.account_balance(:session_id => 'abcde').should == 10.0
+    end
+    
+    it "should raise an API::Error if the response parser raises" do
+      API.stub!(:execute_command)
+      Response.stub!(:parse).and_raise(Clickatell::API::Error.new('', ''))
+      proc { API.account_balance({}) }.should raise_error(Clickatell::API::Error)
+    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
   
 end

data/spec/response_spec.rb

@@ -4,11 +4,21 @@ require File.dirname(__FILE__) + '/../lib/clickatell'
 module Clickatell
 
   describe "Response parser" do
+    before do
+      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'}
     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)
+    end
   end
   
 end

data/website/index.html

@@ -16,7 +16,7 @@
   
   <div id="header">
     
-    <h1>Clickatell Ruby API 0.1.0
+    <h1>Clickatell Ruby API <span class="version">0.2.0</span>
     <span class="tagline">gem install clickatell</span></h1>
     
   </div>
@@ -31,10 +31,15 @@
 	<h3>Installing</h3>
 
 
-<p>Download the <a href="http://rubyforge.org/projects/clickatell">latest version of gem</a> or install using RubyGems</p>
+<p>Download the <a href="http://rubyforge.org/projects/clickatell">latest version of gem</a> or install using RubyGems.</p>
 
 <pre><code>$ sudo gem install clickatell</code></pre>
 
+	<p>Getting the latest version from Subversion:</p>
+
+
+<pre><code>&#38; svn co svn://lukeredpath.co.uk/var/svn/opensource/clickatell/trunk clickatell-trunk</code></pre>
+
 	<h3>The basics</h3>
 
 
@@ -58,6 +63,9 @@ connection = Clickatell::Connection.new('your_api_id', 'your_username', 'your_pa
 connection.send_message('447771234567', 'Hello from clickatell')
 </code></pre>
 
+	<p>Full documentation for the <span class="caps">API</span> is available in the <a href="rdoc/">RDocs</a>.</p>
+
+
 	<h4>Command-line <span class="caps">SMS</span> Utility</h4>
 
 
@@ -76,13 +84,33 @@ username: your_username
 password: your_password
 </code></pre>
 
-	<p>You can then use the sms utility to send a message to a single recipient:</p>
+	<p>You can then use the <ins>sms</ins> utility to send a message to a single recipient:</p>
 
 
 <pre><code>
 $ sms 447771234567 'Hello from clickatell'
 </code></pre>
 
+	<p>Alternatively, you can specify your authentication details manually by passing in options to the <ins>sms</ins> command.</p>
+
+
+<pre><code>
+$ sms -u your_username -p your_password -k your_api_key 447771234567 'Hello from clickatell'
+</code></pre>
+
+	<p>These values will take presedence over any values in your ~/.clickatell file.</p>
+
+
+	<p>You can also use the <ins>sms</ins> utility to check your Clickatell account balance:</p>
+
+
+<pre><code>
+$ sms --show-balance
+</code></pre>
+
+	<p>Run <ins>sms</ins> without any arguments for a full list of options.</p>
+
+
 	<h3>License</h3>
 
 
@@ -101,7 +129,8 @@ $ sms 447771234567 'Hello from clickatell'
   	<div id="footer">
   	  <p class="copyright">
         <a href="http://rubyforge.org/projects/clickatell">Rubyforge Project Page</a> | 
-        <a href="http://rubyforge.org/projects/clickatell">Download latest version (0.1.0)</a>
+        <a href="http://rubyforge.org/frs/?group_id=4295&amp;release_id=13922">Download latest version (0.2.0)</a> | 
+        <a href="rdoc/">RDoc</a>
       </p>
   	</div>
   </div>

data/website/index.txt

@@ -6,10 +6,14 @@ A Ruby interface to the "Clickatell":http://www.clickatell.com SMS gateway API.
 
 h3. Installing
 
-<p>Download the <a href="http://rubyforge.org/projects/clickatell">latest version of gem</a> or install using RubyGems</p>
+<p>Download the <a href="http://rubyforge.org/projects/clickatell">latest version of gem</a> or install using RubyGems.</p>
 
 <pre><code>$ sudo gem install clickatell</code></pre>
 
+Getting the latest version from Subversion:
+
+<pre><code>& svn co svn://lukeredpath.co.uk/var/svn/opensource/clickatell/trunk clickatell-trunk</code></pre>
+
 h3. The basics
 
 To use this gem, you will need sign up for an account at "the Clickatell website":http://www.clickatell.com. 
@@ -28,6 +32,8 @@ require 'clickatell'
 connection = Clickatell::Connection.new('your_api_id', 'your_username', 'your_password')
 connection.send_message('447771234567', 'Hello from clickatell')
 </code></pre>
+
+Full documentation for the API is available in the <a href="rdoc/">RDocs</a>.
   
 h4. Command-line SMS Utility
 
@@ -44,12 +50,28 @@ username: your_username
 password: your_password
 </code></pre>
 
-You can then use the sms utility to send a message to a single recipient:
+You can then use the +sms+ utility to send a message to a single recipient:
 
 <pre><code>
 $ sms 447771234567 'Hello from clickatell'
 </code></pre>
 
+Alternatively, you can specify your authentication details manually by passing in options to the +sms+ command.
+
+<pre><code>
+$ sms -u your_username -p your_password -k your_api_key 447771234567 'Hello from clickatell'
+</code></pre>
+
+These values will take presedence over any values in your ~/.clickatell file.
+
+You can also use the +sms+ utility to check your Clickatell account balance:
+
+<pre><code>
+$ sms --show-balance
+</code></pre>
+
+Run +sms+ without any arguments for a full list of options.
+
 h3. License
 
 This code is free to use under the terms of the MIT license. 

data/website/stylesheets/rdoc.css

@@ -0,0 +1,208 @@
+
+body {
+    font-family: Verdana,Arial,Helvetica,sans-serif;
+    font-size:   90%;
+    margin: 0;
+    margin-left: 40px;
+    padding: 0;
+    background: white;
+}
+
+h1,h2,h3,h4 { margin: 0; color: #efefef; background: transparent; }
+h1 { font-size: 150%; }
+h2,h3,h4 { margin-top: 1em; }
+
+a { background: #eef; color: #039; text-decoration: none; }
+a:hover { background: #039; color: #eef; }
+
+/* Override the base stylesheet's Anchor inside a table cell */
+td > a {
+  background: transparent;
+  color: #039;
+  text-decoration: none;
+}
+
+/* and inside a section title */
+.section-title > a {
+  background: transparent;
+  color: #eee;
+  text-decoration: none;
+}
+
+/* === Structural elements =================================== */
+
+div#index {
+    margin: 0;
+    margin-left: -40px;
+    padding: 0;
+    font-size: 90%;
+}
+
+
+div#index a {
+    margin-left: 0.7em;
+}
+
+div#index .section-bar {
+   margin-left: 0px;
+   padding-left: 0.7em;
+   background: #ccc;
+   font-size: small;
+}
+
+
+div#classHeader, div#fileHeader {
+    width: auto;
+    color: white;
+    padding: 0.5em 1.5em 0.5em 1.5em;
+    margin: 0;
+    margin-left: -40px;
+    border-bottom: 3px solid #006;
+}
+
+div#classHeader a, div#fileHeader a {
+    background: inherit;
+    color: white;
+}
+
+div#classHeader td, div#fileHeader td {
+    background: inherit;
+    color: white;
+}
+
+
+div#fileHeader {
+    background: #057;
+}
+
+div#classHeader {
+    background: #048;
+}
+
+
+.class-name-in-header {
+  font-size:  180%;
+  font-weight: bold;
+}
+
+
+div#bodyContent {
+    padding: 0 1.5em 0 1.5em;
+}
+
+div#description {
+    padding: 0.5em 1.5em;
+    background: #efefef;
+    border: 1px dotted #999;
+}
+
+div#description h1,h2,h3,h4,h5,h6 {
+    color: #125;;
+    background: transparent;
+}
+
+div#validator-badges {
+    text-align: center;
+}
+div#validator-badges img { border: 0; }
+
+div#copyright {
+    color: #333;
+    background: #efefef;
+    font: 0.75em sans-serif;
+    margin-top: 5em;
+    margin-bottom: 0;
+    padding: 0.5em 2em;
+}
+
+
+/* === Classes =================================== */
+
+table.header-table {
+    color: white;
+    font-size: small;
+}
+
+.type-note {
+    font-size: small;
+    color: #DEDEDE;
+}
+
+.xxsection-bar {
+    background: #eee;
+    color: #333;
+    padding: 3px;
+}
+
+.section-bar {
+   color: #333;
+   border-bottom: 1px solid #999;
+    margin-left: -20px;
+}
+
+
+.section-title {
+    background: #79a;
+    color: #eee;
+    padding: 3px;
+    margin-top: 2em;
+    margin-left: -30px;
+    border: 1px solid #999;
+}
+
+.top-aligned-row {  vertical-align: top }
+.bottom-aligned-row { vertical-align: bottom }
+
+/* --- Context section classes ----------------------- */
+
+.context-row { }
+.context-item-name { font-family: monospace; font-weight: bold; color: black; }
+.context-item-value { font-size: small; color: #448; }
+.context-item-desc { color: #333; padding-left: 2em; }
+
+/* --- Method classes -------------------------- */
+.method-detail {
+    background: #efefef;
+    padding: 0;
+    margin-top: 0.5em;
+    margin-bottom: 1em;
+    border: 1px dotted #ccc;
+}
+.method-heading {
+  color: black;
+  background: #ccc;
+  border-bottom: 1px solid #666;
+  padding: 0.2em 0.5em 0 0.5em;
+}
+.method-signature { color: black; background: inherit; }
+.method-name { font-weight: bold; }
+.method-args { font-style: italic; }
+.method-description { padding: 0 0.5em 0 0.5em; }
+
+/* --- Source code sections -------------------- */
+
+a.source-toggle { font-size: 90%; }
+div.method-source-code {
+    background: #262626;
+    color: #ffdead;
+    margin: 1em;
+    padding: 0.5em;
+    border: 1px dashed #999;
+    overflow: hidden;
+}
+
+div.method-source-code pre { color: #ffdead; overflow: hidden; }
+
+/* --- Ruby keyword styles --------------------- */
+
+.standalone-code { background: #221111; color: #ffdead; overflow: hidden; }
+
+.ruby-constant  { color: #7fffd4; background: transparent; }
+.ruby-keyword { color: #00ffff; background: transparent; }
+.ruby-ivar    { color: #eedd82; background: transparent; }
+.ruby-operator  { color: #00ffee; background: transparent; }
+.ruby-identifier { color: #ffdead; background: transparent; }
+.ruby-node    { color: #ffa07a; background: transparent; }
+.ruby-comment { color: #b22222; font-weight: bold; background: transparent; }
+.ruby-regexp  { color: #ffa07a; background: transparent; }
+.ruby-value   { color: #7fffd4; background: transparent; }

data/website/stylesheets/screen.css

@@ -89,6 +89,10 @@ h1 {
 	margin: 0 0 .5em; padding: 0;
 }
 
+h1 span.version {
+  letter-spacing: 0px;
+}
+
 h1 a:link,
 h1 a:visited,
 h1 a:hover {

data/website/template.rhtml

@@ -16,7 +16,7 @@
   
   <div id="header">
     
-    <h1><%= title %> <%= version %>
+    <h1><%= title %> <span class="version"><%= version %></span>
     <span class="tagline">gem install clickatell</span></h1>
     
   </div>
@@ -31,7 +31,8 @@
   	<div id="footer">
   	  <p class="copyright">
         <a href="http://rubyforge.org/projects/clickatell">Rubyforge Project Page</a> | 
-        <a href="<%= download %>">Download latest version (<%= version %>)</a>
+        <a href="http://rubyforge.org/frs/?group_id=4295&amp;release_id=13922">Download latest version (<%= version %>)</a> | 
+        <a href="rdoc/">RDoc</a>
       </p>
   	</div>
   </div>

metadata

@@ -3,7 +3,7 @@ rubygems_version: 0.9.2
 specification_version: 1
 name: clickatell
 version: !ruby/object:Gem::Version 
-  version: 0.1.0
+  version: 0.2.0
 date: 2007-08-21 00:00:00 +01:00
 summary: Ruby interface to the Clickatell SMS gateway service.
 require_paths: 
@@ -56,6 +56,7 @@ files:
 - website/javascripts/codehighlighter/ruby.js
 - website/javascripts/rounded_corners_lite.inc.js
 - website/stylesheets/limechoc.css
+- website/stylesheets/rdoc.css
 - website/stylesheets/screen.css
 - website/template.rhtml
 test_files: []