clickatell-ruby19 0.7.1

data/.gitignore

@@ -0,0 +1,6 @@
+doc/*
+website/*
+pkg/*
+.specification
+pkg
+rdoc

data/History.txt

@@ -0,0 +1,55 @@
+== 0.7.1
+
+* Fixed broken -b (balance) command
+
+== 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,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/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/Rakefile

@@ -0,0 +1,95 @@
+require "rubygems"
+require "rake/rdoctask"
+require File.join(File.dirname(__FILE__), *%w[lib clickatell version])
+
+begin
+  require 'jeweler'
+  
+  Jeweler::Tasks.new do |gemspec|
+    gemspec.name = "clickatell-ruby19"
+    gemspec.summary = "Ruby interface to the Clickatell SMS gateway service."
+    gemspec.email = "luke@lukeredpath.co.uk"
+    gemspec.homepage = "http://clickatell.rubyforge.org"
+    gemspec.authors = ["Luke Redpath", "Ahmed Al Hafoudh"]
+    gemspec.executables = %w{sms}
+    gemspec.extra_rdoc_files = %w{RDOC_README.txt History.txt License.txt}
+    gemspec.has_rdoc = true
+    gemspec.rdoc_options = %w{--main RDOC_README.txt}
+    gemspec.version = Clickatell::VERSION
+  end
+  
+  Jeweler::GemcutterTasks.new
+  
+rescue LoadError
+  puts "Jeweler not available. Install it with: gem install jeweler"
+end
+
+task :default => :spec
+
+require "spec"
+require "spec/rake/spectask"
+
+Spec::Rake::SpecTask.new do |t|
+  t.spec_opts = %w(--format specdoc --colour)
+  t.libs = ["spec"]
+end
+
+Spec::Rake::SpecTask.new("spec_html") do |t|
+  t.spec_opts = %w(--format html)
+  t.libs = ["spec"]
+end
+
+# Rake::RDocTask.new do |rd|
+#   rd.main = "RDOC_README.txt"
+#   rd.rdoc_files.include("lib/**/*.rb", *$gemspec.extra_rdoc_files)
+#   rd.rdoc_dir = "rdoc"
+# end
+
+desc 'Generate website files'
+task :website 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 'Clear out RDoc and generated packages'
+task :clean => [:clobber_rdoc, :clobber_package]
+
+begin
+  require "rake/contrib/sshpublisher"
+  namespace :rubyforge do
+    
+    desc "Release gem and RDoc documentation to RubyForge"
+    task :release => ["rubyforge:release:gem", "rubyforge:release:docs"]
+    
+    namespace :release do
+      desc "Release a new version of this gem"
+      task :gem => [:package] do
+        require 'rubyforge'
+        rubyforge = RubyForge.new
+        rubyforge.configure
+        rubyforge.login
+        rubyforge.userconfig['release_notes'] = $gemspec.summary
+        path_to_gem = File.join(File.dirname(__FILE__), "pkg", "#{$gemspec.name}-#{$gemspec.version}.gem")
+        puts "Publishing #{$gemspec.name}-#{$gemspec.version.to_s} to Rubyforge..."
+        rubyforge.add_release($gemspec.rubyforge_project, $gemspec.name, $gemspec.version.to_s, path_to_gem)
+      end
+    
+      desc "Publish RDoc to RubyForge."
+      task :docs => [:rdoc, :website] do
+        config = YAML.load(
+            File.read(File.expand_path('~/.rubyforge/user-config.yml'))
+        )
+ 
+        host = "#{config['username']}@rubyforge.org"
+        remote_dir = "/var/www/gforge-projects/clickatell/" 
+ 
+        Rake::SshDirPublisher.new(host, remote_dir, 'website').upload
+        Rake::SshDirPublisher.new(host, File.join(remote_dir, 'rdoc'), 'rdoc').upload
+      end
+    end
+  end
+rescue LoadError
+  puts "Rake SshDirPublisher is unavailable or your rubyforge environment is not configured."
+end

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/clickatell.gemspec

@@ -0,0 +1,82 @@
+# Generated by jeweler
+# DO NOT EDIT THIS FILE DIRECTLY
+# Instead, edit Jeweler::Tasks in Rakefile, and run the gemspec command
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{clickatell-ruby19}
+  s.version = "0.7.1.1"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Luke Redpath","Ahmed Al Hafoudh"]
+  s.date = %q{2009-12-01}
+  s.default_executable = %q{sms}
+  s.email = %q{luke@lukeredpath.co.uk}
+  s.executables = ["sms"]
+  s.extra_rdoc_files = [
+    "History.txt",
+     "License.txt",
+     "RDOC_README.txt"
+  ]
+  s.files = [
+    ".gitignore",
+     "History.txt",
+     "License.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",
+     "spec/api_spec.rb",
+     "spec/cli_options_test.rb",
+     "spec/command_executor_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.txt",
+     "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"
+  ]
+  s.homepage = %q{http://clickatell.rubyforge.org}
+  s.rdoc_options = ["--main", "RDOC_README.txt"]
+  s.require_paths = ["lib"]
+  s.rubygems_version = %q{1.3.5}
+  s.summary = %q{Ruby 1.9 compatible interface to the Clickatell SMS gateway service. }
+  s.test_files = [
+    "spec/api_spec.rb",
+     "spec/cli_options_test.rb",
+     "spec/command_executor_spec.rb",
+     "spec/hash_ext_spec.rb",
+     "spec/response_spec.rb",
+     "spec/spec_helper.rb"
+  ]
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
+    else
+    end
+  else
+  end
+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,153 @@
+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)
+      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
+
+    def message_charge(message_id)
+      response = execute_command('getmsgcharge', 'http', :apimsgid => message_id)
+      parse_response(response)['charge'].to_f
+    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