commonthread-clickatell 0.5.1

data/History.txt

@@ -0,0 +1,37 @@
+== 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,20 @@
+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/Manifest.txt

@@ -0,0 +1,36 @@
+History.txt
+License.txt
+Manifest.txt
+RDOC_README.txt
+README.textile
+Rakefile
+bin/sms
+lib/clickatell.rb
+lib/clickatell/api.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/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/hash_ext_spec.rb
+spec/response_spec.rb
+spec/spec.opts
+spec/spec_helper.rb
+website/images/footer_bg.gif
+website/index.html
+website/index.txt
+website/javascripts/codehighlighter/code_highlighter.js
+website/javascripts/codehighlighter/ruby.js
+website/javascripts/rounded_corners_lite.inc.js
+website/specs.html
+website/stylesheets/limechoc.css
+website/stylesheets/rdoc.css
+website/stylesheets/screen.css
+website/template.rhtml

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,33 @@
+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')
+
+  
+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.
+
+See http://clickatell.rubyforge.org for further instructions.  

data/Rakefile

@@ -0,0 +1,160 @@
+require 'rubygems'
+require 'rake'
+require 'rake/clean'
+require 'rake/testtask'
+require 'rake/packagetask'
+require 'rake/gempackagetask'
+require 'rake/rdoctask'
+require 'rake/contrib/rubyforgepublisher'
+require 'fileutils'
+require 'hoe'
+begin
+  require 'spec/rake/spectask'
+rescue LoadError
+  puts 'To use rspec for testing you must install rspec gem:'
+  puts '$ sudo gem install rspec'
+  exit
+end
+
+include FileUtils
+require File.join(File.dirname(__FILE__), 'lib', 'clickatell', 'version')
+
+AUTHOR = 'Luke Redpath'
+EMAIL = "contact[AT]lukeredpath.co.uk"
+DESCRIPTION = "Ruby interface to the Clickatell SMS gateway service."
+GEM_NAME = 'clickatell'
+
+@config_file = "~/.rubyforge/user-config.yml"
+@config = nil
+def rubyforge_username
+  unless @config
+    begin
+      @config = YAML.load(File.read(File.expand_path(@config_file)))
+    rescue
+      puts <<-EOS
+ERROR: No rubyforge config file found: #{@config_file}"
+Run 'rubyforge setup' to prepare your env for access to Rubyforge
+ - See http://newgem.rubyforge.org/rubyforge.html for more details
+      EOS
+      exit
+    end
+  end
+  @rubyforge_username ||= @config["username"]
+end
+
+RUBYFORGE_PROJECT = 'clickatell' # The unix name for your project
+HOMEPATH = "http://#{RUBYFORGE_PROJECT}.rubyforge.org"
+DOWNLOAD_PATH = "http://rubyforge.org/projects/#{RUBYFORGE_PROJECT}"
+
+NAME = "clickatell"
+REV = nil 
+VERS = Clickatell::VERSION::STRING + (REV ? ".#{REV}" : "")
+CLEAN.include ['**/.*.sw?', '*.gem', '.config', '**/.DS_Store']
+RDOC_OPTS = ['--quiet', '--title', 'clickatell documentation',
+    "--opname", "index.html",
+    "--line-numbers", 
+    "--main", "RDOC_README.txt",
+    "--inline-source"]
+
+class Hoe
+  def extra_deps 
+    @extra_deps.reject { |x| Array(x).first == 'hoe' } 
+  end 
+end
+
+# Generate all the Rake tasks
+# Run 'rake -T' to see list of generated tasks (from gem root directory)
+hoe = Hoe.new(GEM_NAME, VERS) do |p|
+  p.author = AUTHOR 
+  p.description = DESCRIPTION
+  p.email = EMAIL
+  p.summary = DESCRIPTION
+  p.url = HOMEPATH
+  p.rubyforge_name = RUBYFORGE_PROJECT if RUBYFORGE_PROJECT
+  p.test_globs = ["test/**/test_*.rb"]
+  p.clean_globs |= CLEAN  #An array of file patterns to delete on clean.
+  
+  # == Optional
+  p.changes = p.paragraphs_of("History.txt", 0..1).join("\n\n")
+  #p.extra_deps = []     # An array of rubygem dependencies [name, version], e.g. [ ['active_support', '>= 1.3.1'] ]
+  #p.spec_extras = {}    # A hash of extra values to set in the gemspec.
+end
+
+CHANGES = hoe.paragraphs_of('History.txt', 0..1).join("\n\n")
+PATH    = (RUBYFORGE_PROJECT == GEM_NAME) ? RUBYFORGE_PROJECT : "#{RUBYFORGE_PROJECT}/#{GEM_NAME}"
+hoe.remote_rdoc_dir = File.join(PATH.gsub(/^#{RUBYFORGE_PROJECT}\/?/,''), 'rdoc')
+
+desc 'Generate website files'
+task :website_generate do
+  Dir['website/**/*.txt'].each do |txt|
+    sh %{ ruby scripts/txt2html #{txt} > #{txt.gsub(/txt$/,'html')} }
+  end
+  sh "rake -s spec:html > website/specs.html"
+end
+
+desc 'Upload website files to rubyforge'
+task :website_upload do
+  host = "#{rubyforge_username}@rubyforge.org"
+  remote_dir = "/var/www/gforge-projects/#{PATH}/"
+  local_dir = 'website'
+  sh %{rsync -aCv #{local_dir}/ #{host}:#{remote_dir}}
+end
+
+desc 'Generate and upload website files'
+task :website => [:website_generate, :website_upload, :publish_docs]
+
+desc 'Release the website and new gem version'
+task :deploy => [:check_version, :website, :release] do
+  puts "Remember to create SVN tag:"
+  puts "svn copy svn+ssh://#{rubyforge_username}@rubyforge.org/var/svn/#{PATH}/trunk " +
+    "svn+ssh://#{rubyforge_username}@rubyforge.org/var/svn/#{PATH}/tags/REL-#{VERS} "
+  puts "Suggested comment:"
+  puts "Tagging release #{CHANGES}"
+end
+
+desc 'Runs tasks website_generate and install_gem as a local deployment of the gem'
+task :local_deploy => [:website_generate, :install_gem]
+
+task :check_version do
+  unless ENV['VERSION']
+    puts 'Must pass a VERSION=x.y.z release version'
+    exit
+  end
+  unless ENV['VERSION'] == VERS
+    puts "Please update your version.rb to match the release version, currently #{VERS}"
+    exit
+  end
+end
+
+Rake::RDocTask.new('docs') do |rd|
+  rd.main = 'RDOC_README.txt'
+  rd.rdoc_files.include('RDOC_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'
+  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|
+    t.spec_opts = ['--options', "spec/spec.opts"]
+    t.spec_files = FileList['spec/*_spec.rb']
+  end
+  
+  desc "Run the specs under spec in specdoc format"
+  Spec::Rake::SpecTask.new('doc') do |t|
+    t.spec_opts = ['--format', "specdoc"]
+    t.spec_files = FileList['spec/*_spec.rb']
+  end
+  
+  desc "Run the specs in HTML format"
+  Spec::Rake::SpecTask.new('html') do |t|
+    t.spec_files = FileList['spec/*_spec.rb']
+    t.spec_opts = ['--format', "html:website/specs.html"]
+  end
+end
+
+desc "Default task is to run specs"
+task :default => 'spec:all'

data/clickatell.gemspec

@@ -0,0 +1,33 @@
+Gem::Specification.new do |s|
+  s.name     = "clickatell"
+  s.version  = "0.5.1"
+  s.date     = "2009-03-03"
+  s.summary  = "Ruby interface to the Clickatell SMS Gateway API"
+  s.email    = "ben@commonthread.com"
+  s.homepage = "http://clickatell.rubyforge.org"
+  s.description = "Ruby interface to the Clickatell SMS Gateway API"
+  s.has_rdoc = true
+  s.authors  = ["Luke Redpath", "Ben Wyrosdick", "Anthony Crumley"]
+  s.files    = ["README.textile",
+                "RDOC_README.txt",
+		"License.txt",
+                "Manifest.txt",
+		"Rakefile",
+                "History.txt",
+		"clickatell.gemspec",
+                "setup.rb",
+                "lib/clickatell.rb",
+		"lib/clickatell/api.rb",
+		"lib/clickatell/response.rb",
+		"lib/clickatell/utility.rb",
+		"lib/clickatell/version.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/utility/options.rb",
+                "lib/clickatell/core-ext/hash.rb",
+                "lib/clickatell/core-ext/object.rb"]
+  s.rdoc_options = ["--main", "RDOC_README.txt"]
+  s.extra_rdoc_files = ["RDOC_README.txt"]
+end

data/lib/clickatell/api/command.rb

@@ -0,0 +1,30 @@
+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| "#{key}=#{CGI.escape(value)}" }.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.blank? ? 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,41 @@
+require 'net/http'
+require 'net/https'
+
+module Clickatell
+  class API
+   
+    # Used to run commands agains the Clickatell gateway.
+    class CommandExecutor
+      def initialize(authentication_hash, secure=false, debug=false)
+        @authentication_hash = authentication_hash
+        @debug = debug
+        @secure = secure
+      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)
+          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 
+  
+  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/api.rb

@@ -0,0 +1,129 @@
+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
+    end
+    
+    # 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)
+      valid_options.merge!(:req_feat => '48') if valid_options[:from]
+      valid_options.merge!(:mo => '1') if opts[:set_mobile_originated]
+      response = execute_command('sendmsg', 'http',
+        {:to => recipient, :text => message_text}.merge(valid_options)
+      ) 
+      parse_response(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
+
+    protected
+      def execute_command(command_name, service, parameters={}) #:nodoc:
+        CommandExecutor.new(auth_hash, self.class.secure_mode, self.class.debug_mode).execute(command_name, service, parameters)
+      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/response.rb

@@ -0,0 +1,22 @@
+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)
+        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
+      
+    end
+
+  end
+end