lookout-clickatell 0.8.3

data/.gitignore

@@ -0,0 +1,8 @@
+doc/*
+website/*
+*.gem
+.bundle
+Gemfile.lock
+pkg/*
+.specification
+rdoc

data/Gemfile

@@ -0,0 +1,11 @@
+source :gemcutter
+
+gem 'rake'
+
+# Specify your gem's dependencies in clickatell.gemspec
+gemspec
+
+group :test do
+  gem "rspec"
+  gem "mocha"
+end

data/History.txt

@@ -0,0 +1,71 @@
+== 0.9
+* Added message concatenation support. Messages over 160 characters will be split in to multiple messages and the API concat parameter will be set; the concat parameter can also be set manually (Joshua Sierles, Martin Westin)
+
+== 0.8.2
+* Allow numbers to have a leading + when using the CLI
+
+== 0.8.1
+* Updated the sms utility error message
+
+== 0.8
+
+* Added fix for Ruby 1.9 (Ahmed Al Hafoudh)
+* Fixed a bug handling error codes above 008 (Sean Kibler)
+* Added HTTP proxy support (Josh Bassett)
+
+
+== 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,73 @@
+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.
+
+<pre>
+<code>
+  require 'rubygems'
+  require 'clickatell'
+
+  api = Clickatell::API.authenticate('your_api_id', 'your_username', 'your_password')
+  api.send_message('447771234567', 'Hello from clickatell')
+</code>
+</pre>
+
+To send a message to multiple recipients, simply pass in an array of numbers.
+
+<pre>
+<code>
+  api.send_message(['447771234567', '447771234568'], 'Hello from clickatell')
+</code>
+</pre>
+
+h2. HTTP Proxy
+
+You can configure the library to use a HTTP proxy when communicating with Clickatell.
+
+<pre>
+<code>
+  Clickatell::API.proxy_host     = 'my.proxy.com'
+  Clickatell::API.proxy_port     = 1234
+  Clickatell::API.proxy_username = 'joeschlub'
+  Clickatell::API.proxy_password = 'secret'
+</code>
+</pre>
+
+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:
+
+<pre>
+<code>
+  # ~/.clickatell
+  api_key: your_api_id
+  username: your_username
+  password: your_password
+</code>
+</pre>
+
+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 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).
+
+<pre>
+<code>
+  sms 447771111111,447772222222 "Hello everyone"
+</code>
+</pre>
+
+See http://clickatell.rubyforge.org for further instructions.

data/Rakefile

@@ -0,0 +1,11 @@
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec) do |spec|
+end
+
+task :test do
+  puts "No-op for now"
+end
+
+task :default => [:spec, :build]

data/bin/sms

@@ -0,0 +1,63 @@
+#!/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 file any bugs on GitHub (http://github.com/lukeredpath/clickatell/issues)."
+    puts "A list of Clickatell error codes can be found in their API documentation (http://is.gd/egeS7)."
+    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,19 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "clickatell/version"
+
+Gem::Specification.new do |s|
+  s.name        = "lookout-clickatell"
+  s.version     = Clickatell::VERSION
+  s.platform    = Gem::Platform::RUBY
+  s.authors     = ["Luke Redpath", 'Kyle Barton', 'R. Tyler Croy']
+  s.email       = ["luke@lukeredpath.co.uk", ]
+  s.homepage    = "https://github.com/lookout/clickatell"
+  s.summary     = %q{Ruby interface to the Clickatell SMS gateway service.}
+  s.description = %q{Ruby interface to the Clickatell SMS gateway service.}
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+end

data/lib/clickatell.rb

@@ -0,0 +1,9 @@
+module Clickatelll end
+
+%w( core-ext/hash
+    clickatell/api 
+    clickatell/response
+    
+).each do |lib|
+    require File.join(File.dirname(__FILE__), lib)
+end

data/lib/clickatell/api.rb

@@ -0,0 +1,169 @@
+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, :ca_file, :ca_path
+
+      # Allow customizing URL
+      attr_accessor :api_service_host
+
+      # Set to your HTTP proxy details (off by default)
+      attr_accessor :proxy_host, :proxy_port, :proxy_username, :proxy_password
+
+      # 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.ca_path = "/etc/ssl/certs"
+    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).
+    #
+    # Messages over 160 characters are split into multiple messages automatically,
+    # and the :concat option will be set, overwriting any manual value of this option.
+    #
+    # You normally wouldn't need to set :concat manually and can rely on the automatica
+    # splitting behaviour.
+    #
+    # Additional options:
+    #    :from - the from number/name
+    #    :set_mobile_originated - mobile originated flag
+    #    :client_message_id - user specified message id that can be used in place of Clickatell issued API message ID for querying message
+    #    :concat - number of concatenations allowed. I.E. how long is a message allowed to be.
+    # Returns a new message ID if successful.
+    def send_message(recipient, message_text, opts={})
+      valid_options = opts.only(:from, :mo, :callback, :climsgid, :concat)
+      valid_options.merge!(:req_feat => '48') if valid_options[:from]
+      valid_options.merge!(:mo => '1') if opts[:set_mobile_originated]
+      valid_options.merge!(:climsgid => opts[:client_message_id]) if opts[:client_message_id]
+      if message_text.length > 160
+        valid_options.merge!(:concat => (message_text.length.to_f / 160).ceil)
+      end
+      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)
+        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