clickatell-ruby19 0.7.1

data/lib/clickatell/api/command.rb

@@ -0,0 +1,31 @@
+require "cgi"
+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| "#{::CGI.escape(key.to_s)}=#{::CGI.escape(value.to_s)}" }.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.nil? || Clickatell::API.api_service_host.empty?) ? 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,69 @@
+require 'net/http'
+require 'net/https'
+
+module Clickatell
+  class API
+   
+   class FakeHttpResponse
+     def body
+       "test"
+     end
+   end
+   
+    # Used to run commands agains the Clickatell gateway.
+    class CommandExecutor
+      def initialize(authentication_hash, secure=false, debug=false, test_mode=false)
+        @authentication_hash = authentication_hash
+        @debug = debug
+        @secure = secure
+        @test_mode = test_mode
+        
+        allow_request_recording if @test_mode
+      end
+      
+      def in_test_mode?
+        @test_mode
+      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)
+      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)
+          if in_test_mode?
+            sms_requests << uri
+            [FakeHttpResponse.new]
+          else
+            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
+        
+      private
+      
+      def allow_request_recording
+        class << self
+          define_method :sms_requests do
+            @sms_requests ||= []
+          end
+        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/response.rb

@@ -0,0 +1,32 @@
+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)
+        return { 'OK' => 'session_id' } if API.test_mode
+        
+        if http_response.body.scan(/ERR/).any?
+          raise Clickatell::API::Error.parse(http_response.body)
+        end
+        results = http_response.body.split("\n").map do |line|
+          # YAML.load converts integer strings that have leading zeroes into integers
+          # using octal rather than decimal.  This isn't what we want, so we'll strip out any
+          # leading zeroes in numbers here.
+          response_fields = line.scan(PARSE_REGEX)
+          response_fields = response_fields.collect { |field| field.gsub(/\b0+(\d+)\b/, '\1') }
+          YAML.load(response_fields.join("\n"))
+        end
+        results.length == 1 ? results.first : results
+      end
+      
+    end
+
+  end
+end

data/lib/clickatell/utility.rb

@@ -0,0 +1,6 @@
+module Clickatell
+  module Utility
+  end
+end
+
+require File.join(File.dirname(__FILE__), *%w[utility/options])

data/lib/clickatell/utility/options.rb

@@ -0,0 +1,109 @@
+require 'optparse'
+require 'ostruct'
+
+module Clickatell
+  module Utility
+    class Options #:nodoc:
+      class << self
+        
+        def parse(args)          
+          @options = self.default_options
+          parser = OptionParser.new do |opts|
+            opts.banner = "Usage: sms [options] recipient(s) message"
+            opts.separator "  Recipients can be a comma-separated list, up to 100 max."
+            opts.separator ""
+            opts.separator "Specific options:"
+          
+            opts.on('-u', '--username USERNAME',
+              "Specify the clickatell username (overrides ~/.clickatell setting)") do |username|
+               @options.username = username 
+            end
+          
+            opts.on('-p', '--password PASSWORD',
+              "Specify the clickatell password (overrides ~/.clickatell setting)") do |password|
+               @options.password = password
+            end
+          
+            opts.on('-k', '--apikey API_KEY',
+              "Specify the clickatell API key (overrides ~/.clickatell setting)") do |key|
+               @options.api_key = key
+            end
+            
+            opts.on('-f', '--from NAME_OR_NUMBER',
+              "Specify the name or number that the SMS will appear from") do |from|
+               @options.from = from 
+            end
+          
+            opts.on('-b', '--show-balance',
+               "Shows the total number of credits remaining on your account") do
+               @options.show_balance = true
+            end
+          
+            opts.on('-s', '--status MESSAGE_ID',
+               "Displays the status of the specified message.") do |message_id|
+               @options.message_id = message_id
+               @options.show_status = true  
+            end
+            
+            opts.on('-S', '--secure',
+                "Sends request using HTTPS") do
+                Clickatell::API.secure_mode = true
+              end
+            
+            opts.on('-d', '--debug') do
+               Clickatell::API.debug_mode = true
+            end
+          
+            opts.on_tail('-h', '--help', "Show this message") do
+              puts opts
+              exit
+            end
+          
+            opts.on_tail('-v', '--version') do
+              puts "Ruby Clickatell SMS Utility #{Clickatell::VERSION}"
+              exit
+            end
+          end
+          
+          @options.recipient = args[-2].split(',') rescue nil
+          @options.message   = args[-1]
+          
+          parser.parse!(args)
+        
+          if (@options.message.nil? || @options.recipient.nil?) && send_message?
+            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 default_options
+          options = OpenStruct.new
+          config_file = File.open(File.join(ENV['HOME'], '.clickatell'))
+          config = YAML.load(config_file)
+          options.username = config['username']
+          options.password = config['password']
+          options.api_key  = config['api_key']
+          options.from     = config['from']
+          return options
+        rescue Errno::ENOENT
+          return options
+        end
+        
+        def send_message?
+          (@options.show_status.nil? &&
+           @options.show_balance.nil?)
+        end
+        
+      end
+    end
+  end
+end

data/lib/clickatell/version.rb

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

data/lib/core-ext/hash.rb

@@ -0,0 +1,15 @@
+class Hash
+  # Returns a new hash containing only the keys specified
+  # that exist in the current hash.
+  #
+  #  {:a => '1', :b => '2', :c => '3'}.only(:a, :c)
+  #  # => {:a => '1', :c => '3'}
+  #
+  # Keys that do not exist in the original hash are ignored.
+  def only(*keys)
+    inject( {} ) do |new_hash, (key, value)|
+      new_hash[key] = value if keys.include?(key)
+      new_hash
+    end
+  end
+end

data/scripts/txt2html

@@ -0,0 +1,67 @@
+#!/usr/bin/env ruby
+
+require 'rubygems'
+require 'redcloth'
+require 'syntax/convertors/html'
+require 'erb'
+require File.dirname(__FILE__) + '/../lib/clickatell/version.rb'
+
+version  = Clickatell::VERSION::STRING
+download = 'http://rubyforge.org/projects/clickatell'
+
+class Fixnum
+  def ordinal
+    # teens
+    return 'th' if (10..19).include?(self % 100)
+    # others
+    case self % 10
+    when 1: return 'st'
+    when 2: return 'nd'
+    when 3: return 'rd'
+    else    return 'th'
+    end
+  end
+end
+
+class Time
+  def pretty
+    return "#{mday}#{mday.ordinal} #{strftime('%B')} #{year}"
+  end
+end
+
+def convert_syntax(syntax, source)
+  return Syntax::Convertors::HTML.for_syntax(syntax).convert(source).gsub(%r!^<pre>|</pre>$!,'')
+end
+
+if ARGV.length >= 1
+  src, template = ARGV
+  template ||= File.dirname(__FILE__) + '/../website/template.rhtml'
+  
+else
+  puts("Usage: #{File.split($0).last} source.txt [template.rhtml] > output.html")
+  exit!
+end
+
+template = ERB.new(File.open(template).read)
+
+title = nil
+body = nil
+File.open(src) do |fsrc|
+  title_text = fsrc.readline
+  body_text = fsrc.read
+  syntax_items = []
+  body_text.gsub!(%r!<(pre|code)[^>]*?syntax=['"]([^'"]+)[^>]*>(.*?)</
>!m){
+    ident = syntax_items.length
+    element, syntax, source = $1, $2, $3
+    syntax_items << "<#{element} class='syntax'>#{convert_syntax(syntax, source)}</#{element}>"
+    "syntax-temp-#{ident}"
+  }
+  title = RedCloth.new(title_text).to_html.gsub(%r!<.*?>!,'').strip
+  body = RedCloth.new(body_text).to_html
+  body.gsub!(%r!(?:<pre><code>)?syntax-temp-(d+)(?:</code></pre>)?!){ syntax_items[$1.to_i] }
+end
+stat = File.stat(src)
+created = stat.ctime
+modified = stat.mtime
+
+$stdout << template.result(binding)

data/spec/api_spec.rb

@@ -0,0 +1,239 @@
+require File.dirname(__FILE__) + '/spec_helper'
+require File.dirname(__FILE__) + '/../lib/clickatell'
+
+class FakeHttp
+  def start(&block)
+    yield self
+  end
+end
+
+module Clickatell
+  
+  describe "API Command" do
+    before do
+      @command = API::Command.new('cmdname')
+    end
+    
+    after do
+      Clickatell::API.api_service_host = nil
+    end
+    
+    it "should return encoded URL for the specified command and parameters" do
+      url = @command.with_params(:param_one => 'abc', :param_two => '123')
+      url.should == URI.parse("http://api.clickatell.com/http/cmdname?param_one=abc&param_two=123")
+    end
+    
+    it "should URL encode any special characters in parameters" do
+      url = @command.with_params(:param_one => 'abc', :param_two => 'hello world & goodbye cruel world <grin>')
+      url.should == URI.parse("http://api.clickatell.com/http/cmdname?param_one=abc&param_two=hello+world+%26+goodbye+cruel+world+%3Cgrin%3E")
+    end
+    
+    it "should use a custom host when constructing command URLs if specified" do
+      Clickatell::API.api_service_host = 'api.clickatell-custom.co.uk'
+      url = @command.with_params(:param_one => 'abc', :param_two => '123')
+      url.should == URI.parse("http://api.clickatell-custom.co.uk/http/cmdname?param_one=abc&param_two=123")
+    end
+    
+    it "should use the default host if specified custom host is nil" do
+      Clickatell::API.api_service_host = nil
+      url = @command.with_params(:param_one => 'abc', :param_two => '123')
+      url.should == URI.parse("http://api.clickatell.com/http/cmdname?param_one=abc&param_two=123")
+    end
+    
+    it "should use the default host if specified custom host is an empty string" do
+      Clickatell::API.api_service_host = ''
+      url = @command.with_params(:param_one => 'abc', :param_two => '123')
+      url.should == URI.parse("http://api.clickatell.com/http/cmdname?param_one=abc&param_two=123")
+    end
+  end
+  
+  describe "Secure API Command" do
+    before do
+      @command = API::Command.new('cmdname', 'http', :secure => true)
+    end
+    
+    it "should use HTTPS" do
+      url = @command.with_params(:param_one => 'abc', :param_two => '123')
+      url.should == URI.parse("https://api.clickatell.com/http/cmdname?param_one=abc&param_two=123")
+    end
+  end
+    
+  describe "Command executor" do
+    it "should create an API command with the given params" do
+      executor = API::CommandExecutor.new(:session_id => '12345')
+      executor.stubs(:get_response).returns([])
+      API::Command.expects(:new).with('cmdname', 'http', :secure => false).returns(command = stub('Command'))
+      command.expects(:with_params).with(:param_one => 'foo', :session_id => '12345').returns(stub_everything('URI'))
+      executor.execute('cmdname', 'http', :param_one => 'foo')
+    end
+    
+    it "should send the URI generated by the created command via HTTP get and return the response" do
+      executor = API::CommandExecutor.new(:session_id => '12345')
+      command_uri = URI.parse('http://clickatell.com:8080/path?foo=bar')
+      API::Command.stubs(:new).returns(command = stub('Command', :with_params => command_uri))
+      Net::HTTP.stubs(:new).with(command_uri.host, command_uri.port).returns(http = FakeHttp.new)
+      http.stubs(:use_ssl=)
+      http.stubs(:get).with('/path?foo=bar').returns([response = stub('HTTP Response'), 'response body'])
+      executor.execute('cmdname', 'http').should == response
+    end
+    
+    it "should send the command over a secure HTTPS connection if :secure option is set to true" do
+      executor = API::CommandExecutor.new({:session_id => '12345'}, secure = true)
+      Net::HTTP.stubs(:new).returns(http = mock('HTTP'))
+      http.expects(:use_ssl=).with(true)
+      http.stubs(:start).returns([])
+      executor.execute('cmdname', 'http')
+    end
+  end
+  
+  describe "API" do
+    before do
+      API.debug_mode = false
+      API.secure_mode = false
+      API.test_mode = false
+      
+      @executor = mock('command executor')
+      @api = API.new(:session_id => '1234')
+      API::CommandExecutor.stubs(:new).with({:session_id => '1234'}, false, false, false).returns(@executor)
+    end
+    
+    it "should use the api_id, username and password to authenticate and return the new session id" do
+      @executor.expects(:execute).with('auth', 'http', 
+        :api_id => '1234',
+        :user => 'joebloggs',
+        :password => 'superpass'
+      ).returns(response = stub('response'))
+      Response.stubs(:parse).with(response).returns('OK' => 'new_session_id')        
+      @api.authenticate('1234', 'joebloggs', 'superpass').should == 'new_session_id'
+    end
+    
+    it "should support ping, using the current session_id" do
+      @executor.expects(:execute).with('ping', 'http', :session_id => 'abcdefg').returns(response = stub('response'))
+      @api.ping('abcdefg').should == response
+    end
+    
+    it "should support sending messages to a specified number, returning the message id" do
+      @executor.expects(:execute).with('sendmsg', 'http', 
+        :to => '4477791234567',
+        :text => 'hello world & goodbye'
+      ).returns(response = stub('response'))
+      Response.stubs(:parse).with(response).returns('ID' => 'message_id')      
+      @api.send_message('4477791234567', 'hello world & goodbye').should == 'message_id'
+    end
+    
+    it "should support sending messages to a multiple numbers, returning the message ids" do
+      @executor.expects(:execute).with('sendmsg', 'http', 
+        :to => '4477791234567,447779999999',
+        :text => 'hello world & goodbye'
+      ).returns(response = stub('response'))
+      Response.stubs(:parse).with(response).returns([{'ID' => 'message_1_id'}, {'ID' => 'message_2_id'}])
+      @api.send_message(['4477791234567', '447779999999'], 'hello world & goodbye').should == ['message_1_id', 'message_2_id']
+    end
+    
+    it "should set the :from parameter and set the :req_feat to 48 when using a custom from string when sending a message" do
+      @executor.expects(:execute).with('sendmsg', 'http', has_entries(:from => 'LUKE', :req_feat => '48')).returns(response = stub('response'))
+      Response.stubs(:parse).with(response).returns('ID' => 'message_id')
+      @api.send_message('4477791234567', 'hello world', :from => 'LUKE')
+    end
+    
+    it "should set the :mo flag to 1 when :set_mobile_originated is true when sending a message" do
+      @executor.expects(:execute).with('sendmsg', 'http', has_entry(:mo => '1')).returns(response=mock('response'))
+      Response.stubs(:parse).with(response).returns('ID' => 'message_id')
+      @api.send_message('4477791234567', 'hello world', :set_mobile_originated => true)
+    end
+    
+    it "should set the callback flag to the number passed in the options hash" do
+      @executor.expects(:execute).with('sendmsg', 'http', has_entry(:callback => 1)).returns(response=mock('response'))
+      Response.stubs(:parse).with(response).returns('ID' => 'message_id')
+      @api.send_message('4477791234567', 'hello world', :callback => 1)
+    end
+    
+    it "should ignore any invalid parameters when sending a message" do
+      @executor.expects(:execute).with('sendmsg', 'http', Not(has_key(:any_old_param))).returns(response = stub('response'))
+      Response.stubs(:parse).returns('ID' => 'foo')
+      @api.send_message('4477791234567', 'hello world', :from => 'LUKE', :any_old_param => 'test')
+    end
+    
+    it "should support message status query for a given message id, returning the message status" do
+      @executor.expects(:execute).with('querymsg', 'http', :apimsgid => 'messageid').returns(response = stub('response'))
+      Response.expects(:parse).with(response).returns('ID' => 'message_id', 'Status' => 'message_status')
+      @api.message_status('messageid').should == 'message_status'
+    end
+    
+    it "should support balance query, returning number of credits as a float" do
+      @executor.expects(:execute).with('getbalance', 'http', {}).returns(response=mock('response'))
+      Response.stubs(:parse).with(response).returns('Credit' => '10.0')
+      @api.account_balance.should == 10.0
+    end
+    
+    it "should raise an API::Error if the response parser raises" do
+      @executor.stubs(:execute)
+      Response.stubs(:parse).raises(Clickatell::API::Error.new('', ''))
+      proc { @api.account_balance }.should raise_error(Clickatell::API::Error)
+    end
+  end
+  
+  describe API, ' when authenticating' do
+    it "should authenticate to retrieve a session_id and return a new API instance using that session id" do
+      API.stubs(:new).returns(api = mock('api'))
+      api.stubs(:authenticate).with('my_api_key', 'joebloggs', 'mypassword').returns('new_session_id')
+      api.expects(:auth_options=).with(:session_id => 'new_session_id')
+      API.authenticate('my_api_key', 'joebloggs', 'mypassword')
+    end
+  end
+  
+  describe API, ' with no authentication options set' do
+    it "should build commands with no authentication options" do
+      api = API.new
+      API::CommandExecutor.stubs(:new).with({}, false, false, false).returns(executor = stub('command executor'))
+      executor.stubs(:execute)
+      api.ping('1234')
+    end
+  end
+  
+  describe API, ' in secure mode' do
+    it "should execute commands securely" do
+      API.secure_mode = true
+      api = API.new
+      API::CommandExecutor.expects(:new).with({}, true, false, false).returns(executor = stub('command executor'))
+      executor.stubs(:execute)
+      api.ping('1234')
+    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
+  
+  describe API, "#test_mode" do
+    before(:each) do
+      API.secure_mode = false
+      API.test_mode = true
+      @api = API.new
+    end
+    
+    it "should create a new CommandExecutor with test_mode parameter set to true" do
+      API::CommandExecutor.expects(:new).with({}, false, false, true).once.returns(executor = mock('command executor'))
+      executor.stubs(:execute)
+      executor.stubs(:sms_requests).returns([])
+      @api.ping('1234')
+    end
+    
+    it "should record all commands" do
+      @api.ping('1234')
+      @api.sms_requests.should_not be_empty
+    end
+    
+    it "should return the recorded commands in a flattened array" do
+      @api.ping('1234')
+      @api.sms_requests.size.should == 1
+      @api.sms_requests.first.should_not be_instance_of(Array)
+    end
+  end
+  
+end