clickatell 0.1.0

data/History.txt

@@ -0,0 +1,4 @@
+== 0.1.0 2007-08-17
+
+* 1 major enhancement:
+  * 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,29 @@
+History.txt
+License.txt
+Manifest.txt
+README.txt
+Rakefile
+bin/sms
+lib/clickatell.rb
+lib/clickatell/api.rb
+lib/clickatell/connection.rb
+lib/clickatell/response.rb
+lib/clickatell/utility.rb
+lib/clickatell/utility/options.rb
+lib/clickatell/version.rb
+scripts/txt2html
+setup.rb
+spec/api_spec.rb
+spec/connection_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/stylesheets/limechoc.css
+website/stylesheets/screen.css
+website/template.rhtml

data/README.txt

@@ -0,0 +1,36 @@
+== Basic Usage
+
+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.
+
+You can now use the library directly. You will need your API_ID as well as your
+account username and password.
+
+  require 'rubygems'
+  require 'clickatell'
+  
+  connection = Clickatell::Connection.new(
+    'your_api_id',
+    'your_username',
+    'your_password'
+  )
+  connection.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'

data/Rakefile

@@ -0,0 +1,145 @@
+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 
+# UNCOMMENT IF REQUIRED: 
+# REV = `svn info`.each {|line| if line =~ /^Revision:/ then k,v = line.split(': '); break v.chomp; else next; end} rescue 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", "README",
+    "--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
+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
+
+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
+end
+
+desc "Default task is to run specs"
+task :default => 'spec:all'

data/bin/sms

@@ -0,0 +1,23 @@
+#!/usr/bin/env ruby
+require 'pp'
+
+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
+
+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

data/lib/clickatell.rb

@@ -0,0 +1,7 @@
+module Clickatell
+end
+
+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])
+require File.join(File.dirname(__FILE__), *%w[clickatell/connection])

data/lib/clickatell/api.rb

@@ -0,0 +1,108 @@
+require 'net/http'
+
+module Clickatell
+  # This module provides the core implementation of the Clickatell 
+  # HTTP service.
+  module API
+    
+    class << self
+      
+      # 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',
+          :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', :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).
+      #
+      # +auth_options+: a hash of credentials to be used in this
+      # API call. Either api_id/username/password or session_id
+      # for an existing authenticated session.
+      #
+      # Returns a new message ID if successful.
+      def send_message(recipient, message_text, auth_options)
+        response = execute_command('sendmsg', {
+          :to => recipient,
+          :text => message_text
+        }.merge( auth_hash(auth_options) )) 
+        parse_response(response)['ID']
+      end
+      
+      # Returns the status of a message. Use message ID returned
+      # from original send_message call. See send_message() for
+      # auth_options.
+      def message_status(message_id, auth_options)
+        response = execute_command('querymsg', {
+          :apimsgid => message_id 
+        }.merge( auth_hash(auth_options) ))
+        parse_response(response)['Status']
+      end
+
+      protected
+        # Builds a command and sends it via HTTP GET.
+        def execute_command(command_name, parameters)
+          Net::HTTP.get_response(
+            Command.new(command_name).with_params(parameters)
+          )
+        end
+        
+        def parse_response(raw_response) #:nodoc:
+          Clickatell::Response.parse(raw_response)
+        end
+        
+        def auth_hash(options) #:nodoc:
+          if options[:session_id]
+            return {
+              :session_id => options[:session_id]
+            }
+          else
+            return {
+              :user => options[:username],
+              :password => options[:password],
+              :api_id => options[:api_key]
+            }
+          end
+      end
+      
+    end
+    
+    # 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, opts={})
+        @command_name = command_name
+        @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}=#{value}" }.sort.join('&')
+        return URI.parse(File.join(api_service_uri, @command_name + URI.encode(param_string)))
+      end
+
+      protected
+        def api_service_uri
+          protocol = @options[:secure] ? 'https' : 'http'
+          return "#{protocol}://#{API_SERVICE_HOST}/http/"
+        end
+    end
+    
+  end
+end

data/lib/clickatell/connection.rb

@@ -0,0 +1,60 @@
+module Clickatell
+  
+  # The Connection object provides a high-level interface to the
+  # Clickatell API, handling authentication across multiple API
+  # requests.
+  #
+  # Example:
+  #   conn = Clickatell::Connection.new('your_api_key', 'joebloggs', 'secret')
+  #   message_id = conn.send_message('44777123456', 'This is a test message')
+  #   status = conn.message_status(message_id)
+  #
+  # The Connection object provides all of the public methods implemented in 
+  # Clickatell::API but handles the passing of authentication options 
+  # automatically so it is not required to pass any authentication_option hashes
+  # into API methods that require them.
+  class Connection
+    
+    # Returns the current Clickatell session ID.
+    attr_reader :session_id
+    
+    # +api_key+: Your Clickatell API ID/key.
+    # +username+: Your Clickatell account username.
+    # +password+: Your Clickatell account password.
+    def initialize(api_key, username, password)
+      @api_key = api_key
+      @username = username
+      @password = password
+    end
+    
+    # Manual authentication. Will create a new Clickatell session 
+    # and store the session ID.
+    def authenticate!
+      @session_id = API.authenticate(@api_key, @username, @password)
+    end
+    
+    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)
+        params << {:session_id => current_session_id}
+        API.send(api_method, *params)
+      end
+      
+      # Returns the current_session_id, authenticating if one doesn't exist
+      def current_session_id
+        authenticate! if session_id.nil?
+        session_id
+      end
+    
+      # Dispatch any API methods to the API module.
+      def method_missing(method, *args, &block)
+        if API.respond_to?(method)
+          execute_api_call(method, args)
+        else
+          super(method, args, &block)
+        end
+      end
+  end
+    
+end

data/lib/clickatell/response.rb

@@ -0,0 +1,19 @@
+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)
+        YAML.load(http_response.body.scan(PARSE_REGEX).join("\n"))
+      end
+      
+    end
+
+  end
+end