kapow 0.4.0

data/History.txt

@@ -0,0 +1,26 @@
+== 0.4.0 2009-10-21
+
+* Added additional options to the deliver sms method
+* More specs
+
+== 0.3.0 2008-08-12
+
+* Renamed Message class to SMS, as this identifies the class better
+
+== 0.2.0 2008-08-05
+
+* Fixed typo in :long_sms option
+* Added ability to send sms as flash message
+* Added a few more specs
+
+== 0.1.2 2008-07-29
+
+* Improved rdoc
+
+== 0.1.1 2008-07-28
+
+* Updated gemspec as gem was not building on Github
+
+== 0.1.0 2008-07-27
+ 
+* Initial release.

data/Rakefile

@@ -0,0 +1,49 @@
+%w(rubygems rake rake/rdoctask fileutils).each { |lib| require lib }
+
+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', 'kapow', 'version')
+ 
+AUTHOR = 'Kiean Johnson'
+EMAIL = "kieran[AT]invisiblelines.com"
+DESCRIPTION = "Ruby library for Kapow SMS gateway service."
+GEM_NAME = 'kapow'
+
+Rake::RDocTask.new('docs') do |rd|
+  rd.main = 'README.txt'
+  rd.rdoc_files.include('README', 'History.txt', 'License.txt', 'lib/**/*.rb')
+  rd.rdoc_dir = 'doc'
+  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/Readme.rdoc

@@ -0,0 +1,47 @@
+= Read Me
+
+Kapow - Ruby library for Kapow SMS gateway service
+
+  by Kieran Johnson
+  http://github.com/kieranj/kapow
+
+== Installation:
+
+  $ gem sources -a http://gems.github.com/ (you only need to do this once)
+  $ gem install kieranj-kapow
+
+== Usage:
+
+To use this library you first need to sign up for an account at www.kapow.com.
+
+The library wraps the HTTP POST service provided as this has the advantages of
+speed and an immediate response message.
+
+  require 'rubygems'
+  require 'kieranj-kapow'
+
+  # Create a new sms
+  msg = Kapow::SMS.new('username', 'password')
+  msg.deliver('mobile_no', 'sms')
+  
+All options supported by Kapow can be passed into the deliver method as a hash
+  
+  # Send sms as a flash
+  msg.deliver('mobile_no', 'sms', :flash => true)
+  
+  # Send sms with from_id (if enabled in account)
+  msg.deliver('mobile_no', 'sms', :from_id => 'from_id')
+  
+  # Send sms up to 1377 characters long
+  msg.deliver('mobile_no', 'sms', :long_sms => true)
+
+Responses provided by the Kapow SMS Gateway are:
+
+<tt>OK</tt>:: Message has been accepted for delivery.
+<tt>USERPASS</tt>:: Invalid username or password.
+<tt>NOCREDIT</tt>:: Account has no credits or credit limit has been reached.
+<tt>ERROR</tt>:: Any other error has occurred.
+
+The amount of remaining credit is included with the 'OK' response from the gateway. This is available as:
+
+  Kapow::Credit #=> 325

data/kapow.gemspec

@@ -0,0 +1,24 @@
+Gem::Specification.new do |s|
+  s.name     = "kapow"
+  s.version  = "0.4.0"
+  s.date     = "2009-10-21"
+  s.summary  = "Ruby library for Kapow SMS gateway service"
+  s.email    = "kieran[AT]invisiblelines.com"
+  s.homepage = "http://gemcutter.org/gems/kapow"
+  s.rubyforge_project = "kapow"
+  s.description = "Ruby library for sending SMS messages using the Kapow SMS gateway service."
+  s.has_rdoc = true
+  s.authors  = ["Kieran Johnson"]
+  s.files    = ["History.txt", 
+		"Readme.rdoc", 
+		"Rakefile",
+		"kapow.gemspec", 
+		"lib/kapow.rb",
+		"lib/kapow/sms.rb",
+		"lib/kapow/response.rb",
+		"lib/kapow/credit.rb",
+		"lib/kapow/version.rb"]
+	s.test_files       = ["spec/sms_spec.rb", "spec/response_spec.rb"]
+  s.rdoc_options     = ["--main", "Readme.rdoc"]
+  s.extra_rdoc_files = ["Readme.rdoc"]
+end

data/lib/kapow.rb

@@ -0,0 +1,22 @@
+# = Overview:
+# A simple library for sending sms messages using the Kapow sms gateway.
+# ---
+# = License:
+# Author:: Kieran Johnson
+# Copyright:: July, 2008
+# License:: Ruby License
+# ---
+# = Usage:
+#   require 'rubygems'
+#   require 'kieranj-kapow'
+# 
+#   msg = Kapow::SMS.new('username', 'password')
+#   msg.deliver('mobile_no', 'sms')
+
+module Kapow
+
+  %w(version response sms credit).each do |lib|
+    require File.join(File.dirname(__FILE__), 'kapow', lib)
+  end
+
+end

data/lib/kapow/credit.rb

@@ -0,0 +1,21 @@
+module Kapow
+  
+  # Module to access the amount of available credit.
+  
+  module Credit
+  
+    class << self
+    
+      attr_accessor :available
+      
+      # Returns the available credit
+      #
+      def to_s
+        available.to_s
+      end
+  
+    end
+  
+  end
+
+end

data/lib/kapow/response.rb

@@ -0,0 +1,43 @@
+module Kapow
+  
+  class NoCreditError < StandardError; end
+  class AuthenticationError < StandardError; end
+  class Error < StandardError; end
+  
+  # A small class for parsing the response from the sms gateway.
+  
+  class Response
+    
+    def initialize(sms, message)
+      @sms     = sms
+      @message = parse(message)
+    end
+    
+    attr_reader :message
+    
+    # Parses the response body. Raises the appropriate error or returns true.
+    # Also updates the amount of available credit.
+    #
+    def parse(message)
+      if message.is_a?(Net::HTTPSuccess || Net::HTTPRedirection)
+        case message.body
+        when "USERPASS"
+          raise AuthenticationError
+        when "NOCREDIT"
+          raise NoCreditError
+        when "ERROR"
+          raise Error
+        when /STATUS (.*)/ # This needs to change
+          $1
+        when /^OK (\d+)\s?(.*)?/
+          Kapow::Credit.available = $1.to_i
+          @sms.unique_id = $2 unless $2 == ""
+        end
+      else
+        raise message.error!
+      end
+    end
+        
+  end
+  
+end

data/lib/kapow/sms.rb

@@ -0,0 +1,74 @@
+%w(uri net/http).each { |lib| require lib }
+
+module Kapow
+  
+  # A class for creating and sending an sms message using the Kapow sms gateway.
+  
+  class SMS
+    
+    MESSAGE_URL   = "https://www.kapow.co.uk/scripts/sendsms.php"
+    
+    STATUS_URL    = "https://www.kapow.co.uk/scripts/chk_status.php"
+    
+    VALID_OPTIONS = [ :flash, :from_id, :long_sms, :returnid, :route, :url ]
+    
+    attr_accessor :unique_id
+    
+    # Required values are: username, password
+    # <tt>:username</tt>:: Your account username.
+    # <tt>:password</tt>:: Your account password.
+    #
+    def initialize(username, password)
+      @username = username
+      @password = password
+    end
+    
+    # Delivers the message
+    # <tt>:mobile</tt>:: Recipient number, or list of comma separated numbers.
+    # <tt>:sms</tt>:: Text for the message itself, truncated by gateway at 160 characters
+    #
+    # Optional parameters passed in as a hash
+    # <tt>:flash</tt>:: Boolean - Send SMS as a flash
+    # <tt>:from_id</tt>:: The message originator (if enabled for your account)
+    # <tt>:long_sms</tt>:: Boolean (if enabled in your account)
+    # <tt>:returnid</tt>:: Boolean - Returns unique id in response, so status can be tracked
+    # <tt>:route</tt>:: Your shortcode - Enables premium sms messages (reverse billed)
+    # <tt>:url</tt>:: URL to call after sending the request
+    #
+    def deliver(mobile, sms, options={})
+      options = options.reject { |k,v| !VALID_OPTIONS.include?(k) }
+      
+      sms = "FLASH#{sms}" if options.include?(:flash) && options[:flash] == true
+      
+      options[:returnid] = "TRUE" if options.include?(:returnid) && options[:returnid] == true
+      
+      sms_parameters = {
+        :username => @username,
+        :password => @password,
+        :mobile   => mobile,
+        :sms      => sms
+      }.merge(options)
+
+      response = Net::HTTP.post_form(URI.parse(MESSAGE_URL), sms_parameters)
+      Response.new(self, response).message
+    end
+    
+    # Returns the delivery status of a message
+    # <tt>:returnid</tt>:: The unique id received when sending a message with returnid=TRUE
+    #
+    def status(returnid)
+      response = Net::HTTP.post_form(URI.parse(STATUS_URL), { :username => @username, :returnid => returnid } )
+      Response.new(self, response).message
+    end
+    
+    protected
+    
+      def format_number(number)
+        number.sub!(/^\+/, "")
+        number.sub!(/^00/, "")
+        number
+      end
+    
+  end
+  
+end

data/lib/kapow/version.rb

@@ -0,0 +1,16 @@
+module Kapow
+  
+  module VERSION
+    MAJOR = 0
+    MINOR = 4
+    TINY = 0
+    
+    STRING = [MAJOR, MINOR, TINY].join('.')
+    
+    def self.to_s
+      STRING
+    end
+    
+  end
+  
+end

data/spec/response_spec.rb

@@ -0,0 +1,54 @@
+require File.dirname(__FILE__) + '/spec_helper'
+  
+describe Kapow::Response do
+  
+  before do
+    @sms           = Kapow::SMS.new("kieran", "secret")
+    @response_text = Net::HTTPSuccess.new('1.1', '200', 'OK')
+  end
+  
+  it "should raise Kapow::Authentication error if response is USERPASS" do
+    @response_text.stubs(:body).returns("USERPASS")
+    lambda { Kapow::Response.new(@sms, @response_text) }.should raise_error(Kapow::AuthenticationError)
+  end
+  
+  it "should raise Kapow::NoCreditError error if response is NOCREDIT" do
+    @response_text.stubs(:body).returns("NOCREDIT")
+    lambda { Kapow::Response.new(@sms, @response_text) }.should raise_error(Kapow::NoCreditError)
+  end
+  
+  it "should raise Kapow::Error error if response is ERROR" do
+    @response_text.stubs(:body).returns("ERROR")
+    lambda { Kapow::Response.new(@sms, @response_text) }.should raise_error(Kapow::Error)
+  end
+  
+  it "should return true if response is OK" do
+    @response_text.stubs(:body).returns("OK CREDITS")
+    lambda { Kapow::Response.new(@sms, @response_text) }.should_not raise_error
+  end
+  
+  it "should return the amount of credit available if response is OK" do
+    @response_text.stubs(:body).returns("OK 111")
+    Kapow::Response.new(@sms, @response_text)
+    Kapow::Credit.to_s.should == "111"
+  end
+  
+  it "should raise Kapow::Error if response is not success or redirection" do
+    error = Net::HTTPServerError.new("1.1", "500", "Error")
+    lambda { Kapow::Response.new(@sms, error) }.should raise_error
+  end
+  
+  # # response with unique_id
+  it "should return the unique_id if available" do
+    @response_text.stubs(:body).returns("OK 111 UNIQUEID")
+    Kapow::Response.new(@sms, @response_text)
+    @sms.unique_id.should == "UNIQUEID"
+  end
+  
+  # response for status
+  it "should return the status of the message" do
+    @response_text.stubs(:body).returns("STATUS SENT")
+    Kapow::Response.new(@sms, @response_text).message.should == "SENT"
+  end
+  
+end

data/spec/sms_spec.rb

@@ -0,0 +1,91 @@
+require File.dirname(__FILE__) + '/spec_helper'
+  
+describe Kapow::SMS do
+  
+  before do
+    @sms = Kapow::SMS.new("kieran", "secret")
+  end
+
+  describe "posting a message" do
+  
+    before do
+      @response = Net::HTTPSuccess.new("1.1", "200", "OK")
+      @response.stubs(:body).returns("OK")
+      Net::HTTP.stubs(:post_form).returns(@response)
+      @uri = URI.parse(Kapow::SMS::MESSAGE_URL)
+    end
+  
+    it "should send an sms" do
+      Net::HTTP.expects(:post_form).with(@uri, {:username => "kieran", :mobile => "4401234567890", :password => "secret", :sms => "Yo!"}).returns(@response)
+      lambda { @sms.deliver("4401234567890", "Yo!") }.should_not raise_error
+    end
+    
+    context "with flash" do
+    
+      it "should send an sms as a flash" do
+        Net::HTTP.expects(:post_form).with(@uri, {:flash => true, :username => "kieran", :mobile => "4401234567890", :password => "secret", :sms => "FLASHYo!"}).returns(@response)
+        lambda { @sms.deliver("4401234567890", "Yo!", :flash => true) }.should_not raise_error
+      end
+    
+    end
+    
+    context "with from_id" do
+    
+      it "should send an sms with a from_id" do
+        Net::HTTP.expects(:post_form).with(@uri, {:from_id => "Kieran_j", :username => "kieran", :mobile => "4401234567890", :password => "secret", :sms => "Yo!"}).returns(@response)
+        lambda { @sms.deliver("4401234567890", "Yo!", :from_id => "Kieran_j") }.should_not raise_error
+      end
+    
+    end
+    
+    context "with long_sms" do
+    
+      it "should send a long sms" do
+        msg = ""
+        4.times { msg << "The quick brown fox jumps over the lazy dog. " }
+        Net::HTTP.expects(:post_form).with(@uri, {:long_sms => true, :username => "kieran", :mobile => "4401234567890", :password => "secret", :sms => msg}).returns(@response)
+        lambda { @sms.deliver("4401234567890", msg, :long_sms => true) }.should_not raise_error
+      end
+    
+    end
+    
+    context "with returnid=TRUE" do
+      
+      it "should send an sms with returnid=TRUE" do
+        Net::HTTP.expects(:post_form).with(@uri, {:returnid => "TRUE", :mobile => "4401234567890", :username => "kieran", :sms => "Yo!", :password => "secret"}).returns(@response)
+        lambda { @sms.deliver("4401234567890", "Yo!", :returnid => true) }.should_not raise_error
+      end
+      
+    end
+    
+    context "with URL" do
+      
+      it "should send an sms with a callback URL" do
+        Net::HTTP.expects(:post_form).with(@uri, {:url => "http://my.callback.com", :mobile => "4401234567890", :username => "kieran", :sms => "Yo!", :password => "secret"}).returns(@response)
+        lambda { @sms.deliver("4401234567890", "Yo!", :url => "http://my.callback.com") }.should_not raise_error
+      end
+      
+    end
+    
+  end
+  
+  describe "returning a message status" do
+    
+    #
+    # The actual response needs to be inserted here.
+    #
+    before do
+      @response = Net::HTTPSuccess.new("1.1", "200", "OK")
+      @response.stubs(:body).returns("STATUS SENT") # status body response
+      Net::HTTP.stubs(:post_form).returns(@response)
+      @uri = URI.parse(Kapow::SMS::STATUS_URL)
+    end
+    
+    it "should return the status" do
+      Net::HTTP.expects(:post_form).with(@uri, {:username => "kieran", :returnid => "12345"}).returns(@response)
+      @sms.status("12345").should be_instance_of(String)
+    end
+    
+  end
+  
+end

metadata

@@ -0,0 +1,65 @@
+--- !ruby/object:Gem::Specification 
+name: kapow
+version: !ruby/object:Gem::Version 
+  version: 0.4.0
+platform: ruby
+authors: 
+- Kieran Johnson
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-10-21 00:00:00 +01:00
+default_executable: 
+dependencies: []
+
+description: Ruby library for sending SMS messages using the Kapow SMS gateway service.
+email: kieran[AT]invisiblelines.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- Readme.rdoc
+files: 
+- History.txt
+- Readme.rdoc
+- Rakefile
+- kapow.gemspec
+- lib/kapow.rb
+- lib/kapow/sms.rb
+- lib/kapow/response.rb
+- lib/kapow/credit.rb
+- lib/kapow/version.rb
+has_rdoc: true
+homepage: http://gemcutter.org/gems/kapow
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --main
+- Readme.rdoc
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: kapow
+rubygems_version: 1.3.5
+signing_key: 
+specification_version: 3
+summary: Ruby library for Kapow SMS gateway service
+test_files: 
+- spec/sms_spec.rb
+- spec/response_spec.rb