smsinabox 0.2.0

data/.gitignore

@@ -0,0 +1,4 @@
+nbproject
+*.log
+*.gem
+*.swp

data/History.txt

@@ -0,0 +1,13 @@
+== 0.2.0 (Not released yet)
+
+* Upgraded to V5 of mymobileapi.com API
+* Cleaned up internals
+* Better specs
+* New delivery report class
+* Sub-classed message class for supporting VCARD and other formats later
+* Basic support for pulling sent messages and replies
+
+== 0.0.1 2008-09-25
+
+* 1 major enhancement:
+  * Initial release

data/PostInstall.txt

@@ -0,0 +1,10 @@
+
+For more information on smsinabox, see http://www.opensourcery.co.za/smsinabox
+
+Setup your account by running sms-setup now. You can then use the following
+commands to interact with SMS in a Box:
+
+sms-send: Send SMS messages
+sms-credit: Quick overview of the credit available
+sms-replies: Quick access to your replies
+sms-setup: To change the account details

data/README.rdoc

@@ -0,0 +1,47 @@
+= smsinabox
+
+* http://www.opensourcery.co.za/smsinabox
+* http://www.smsinabox.co.za/
+
+== DESCRIPTION:
+
+A Ruby wrapper for the SMS in a Box HTTP API, as well as command line tools for
+sending SMS's and checking account balances
+
+== FEATURES/PROBLEMS:
+
+* Ruby module 'Smsinabox' for using in your own code
+* sms-setup, sms-send, sms-credit & sms-replies CLI apps
+
+== REQUIREMENTS:
+
+* Developed and tested on Ruby 1.8.6
+
+== INSTALL:
+
+* sudo gem install smsinabox
+
+== LICENSE:
+
+(The MIT License)
+
+Copyright (c) 2008 Kenneth Kalmer & SMS in a Box
+
+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/Rakefile

@@ -0,0 +1,29 @@
+require './lib/smsinabox'
+
+Dir['tasks/**/*.rake'].each { |t| load t }
+
+# TODO - want other tests/tasks run by default? Add them to the list
+# remove_task :default
+# task :default => [:spec, :features]
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gemspec|
+    gemspec.name = 'smsinabox'
+    gemspec.version = Smsinabox::VERSION
+    gemspec.summary = 'Ruby API for sending text messages via http://www.smsinabox.co.za'
+    gemspec.description = 'Ruby API for sending text messages via http://www.smsinabox.co.za'
+    gemspec.email = 'kenneth.kalmer@gmail.com'
+    gemspec.homepage = 'http://github.com/kennethkalmer/smsinabox'
+    gemspec.authors = ['kenneth.kalmer@gmail.com']
+    gemspec.post_install_message = IO.read('PostInstall.txt')
+    gemspec.extra_rdoc_files.include '*.txt'
+
+    gemspec.add_dependency 'nokogiri', '>= 1.3.3'
+    gemspec.add_development_dependency 'rspec'
+    gemspec.add_development_dependency 'cucumber'
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler not available. Install it with 'gem install jeweler'"
+end

data/TODO.txt

@@ -0,0 +1,14 @@
+SMS in a BOX TODO
+=================
+
+Lets call this the builtin LightHouse :)
+
+* Send bulk SMS messages
+* Identify and handle invalid credentials
+* Better exception generation and handling throughout the code
+* Smsinabox::Message.to_xml
+* Reply script
+* Highline dependencies for better input
+* SMS body input via STDIN
+* Multiple accounts support
+* Options to stay quite during operation

data/bin/sms-credit

@@ -0,0 +1,38 @@
+#!/usr/bin/env ruby
+#
+#  Created on 2008-9-25.
+#  Copyright (c) 2008. All rights reserved.
+
+begin
+  require 'rubygems'
+rescue LoadError
+  # no rubygems to load, so we fail silently
+end
+
+require 'smsinabox'
+require 'optparse'
+
+OPTIONS = {
+  :config => nil
+}
+
+parser = OptionParser.new do |opts|
+  opts.banner = <<BANNER
+Retrieve the number of credits in the account
+
+Usage: #{File.basename($0)} [options]
+
+Options are:
+BANNER
+  opts.separator ""
+  opts.on("-c", "--config=path/to/config", String,
+          "Path to alternate config file (defaults to ~/.smsinabox)") { |m| OPTIONS[:config] = m }
+  opts.on("-h", "--help",
+          "Show this help message.") { puts opts; exit }
+  opts.parse!(ARGV)
+
+end
+
+Smsinabox.configure!( OPTIONS[:config] )
+
+puts "Credits left: #{Smsinabox.credits}"

data/bin/sms-send

@@ -0,0 +1,76 @@
+#!/usr/bin/env ruby
+#
+#  Created on 2008-9-25.
+#  Copyright (c) 2008. All rights reserved.
+
+begin
+  require 'rubygems'
+rescue LoadError
+  # no rubygems to load, so we fail silently
+end
+
+require 'smsinabox'
+require 'optparse'
+
+OPTIONS = {
+  :recipient => nil,
+  :message => nil,
+  :pipe => false,
+  :config => nil
+}
+MANDATORY_OPTIONS = %w( recipient )
+
+parser = OptionParser.new do |opts|
+  opts.banner = <<BANNER
+Send a single SMS message to the specified recipient
+
+Usage: #{File.basename($0)} [options]
+
+Options are:
+BANNER
+  opts.separator ""
+  opts.on("-r", "--recipient=RECIPIENT", String,
+          "The recipient of the SMS") { |r| OPTIONS[:recipient] = r }
+  opts.on("-m", "--message=MESSAGE", String,
+          "The body of the message (wrap in quotes)") { |m| OPTIONS[:message] = m }
+  opts.on("-c", "--config=path/to/config", String,
+          "Path to alternate config file (defaults to ~/.smsinabox)") { |m| OPTIONS[:config] = m }
+  opts.on("-p", "--pipe",
+          "Read message text from STDIN") { OPTIONS[:pipe] = true }
+  opts.on("-h", "--help",
+          "Show this help message.") { puts opts; exit }
+  opts.parse!(ARGV)
+
+  if MANDATORY_OPTIONS && MANDATORY_OPTIONS.find { |option| OPTIONS[option.to_sym].nil? }
+    puts opts; exit 1
+  end
+
+  if OPTIONS[:message].nil? && !OPTIONS[:pipe]
+    puts opts; exit 1
+  end
+end
+
+# Figure out our message
+message = if !OPTIONS[:message].nil?
+  OPTIONS[:message]
+else
+  require 'fcntl'
+  if STDIN.fcntl(Fcntl::F_GETFL, 0) == 0
+    STDIN.read
+  else
+    puts "Nothing to read from STDIN!"
+    exit 1
+  end
+end
+
+Smsinabox.configure!( OPTIONS[:config] )
+id = Smsinabox.send(
+  Smsinabox::Message.new( 
+    :recipient => OPTIONS[:recipient], :body => message
+  )
+)
+
+puts "Message sent"
+puts "Reference: #{id}"
+puts "Recipient: #{OPTIONS[:recipient]}"
+puts "Message:   #{message}"

data/bin/sms-setup

@@ -0,0 +1,54 @@
+#!/usr/bin/env ruby
+#
+#  Created on 2008-9-25.
+#  Copyright (c) 2008. All rights reserved.
+
+begin
+  require 'rubygems'
+rescue LoadError
+  # no rubygems to load, so we fail silently
+end
+
+require 'smsinabox'
+require 'optparse'
+
+OPTIONS = {
+  :username     => nil,
+  :password     => nil,
+  :config       => nil
+}
+MANDATORY_OPTIONS = %w( username password )
+
+parser = OptionParser.new do |opts|
+  opts.banner = <<BANNER
+Configure your local SMS in a Box commands to use the supplied details.
+
+The configuration file is located at ~/.smsinabox and will have permissions of
+0600. It contains your password information in plain text, so be careful.
+
+Usage: #{File.basename($0)} [options]
+
+Options are:
+BANNER
+  opts.separator ""
+  opts.on("-u", "--username=USERNAME", String,
+          "Username to use") { |u| OPTIONS[:username] = u }
+  opts.on("-p", "--password=PASSWORD", String,
+          "Password to use") { |p| OPTIONS[:password] = p }
+  opts.on("-c", "--config=path/to/config", String,
+          "Path to alternate config file (defaults to ~/.smsinabox)") { |m| OPTIONS[:config] = m }
+  opts.on("-h", "--help",
+          "Show this help message.") { puts opts; exit }
+  opts.parse!(ARGV)
+
+  if MANDATORY_OPTIONS && MANDATORY_OPTIONS.find { |option| OPTIONS[option.to_sym].nil? }
+    puts opts; exit
+  end
+end
+
+config = Smsinabox::Configuration.new( OPTIONS[:config] )
+config[:username] = OPTIONS[:username]
+config[:password] = OPTIONS[:password]
+config.save
+
+puts 'Configuration file updated.'

data/lib/smsinabox.rb

@@ -0,0 +1,143 @@
+$:.unshift(File.dirname(__FILE__)) unless
+  $:.include?(File.dirname(__FILE__)) || $:.include?(File.expand_path(File.dirname(__FILE__)))
+
+require 'net/http'
+require 'uri'
+begin
+  require 'nokogiri'
+rescue LoadError
+  require 'rubygems'
+  require 'nokogiri'
+end
+
+module Smsinabox
+
+  VERSION = '0.2.0'
+
+  autoload :Exceptions,     'smsinabox/exceptions'
+  autoload :Message,        'smsinabox/message'
+  autoload :Configuration,  'smsinabox/configuration'
+  autoload :DeliveryReport, 'smsinabox/delivery_report'
+  autoload :SMS,            'smsinabox/sms'
+  autoload :Reply,          'smsinabox/reply'
+  autoload :SentMessage,    'smsinabox/sent_message'
+
+  class << self
+
+    # Username for the SMS in a Box service
+    attr_accessor :username
+
+    # Password for the SMS in a Box service
+    attr_accessor :password
+
+    def uri
+      @uri ||= URI.parse('http://www.mymobileapi.com/api5/http5.aspx')
+    end
+
+    # Return the number of available credits
+    def credit_remaining
+      perform_request( 'Type' => 'credits' ) do |xml|
+        xml.xpath('/api_result/data/credits/text()').to_s.to_i
+      end
+    end
+
+    # Send a #Messages and returns a #DelieryReport
+    def deliver( message )
+      raise MessageInvalid unless message.valid?
+
+      perform_request(
+        'Type' => 'sendparam',
+        'return_credits' => 'True',
+        'return_msgs_success_count' => 'True',
+        'return_msgs_failed_count' => 'True',
+        'return_entries_success_status' => 'True',
+        'return_entries_failed_status' => 'True',
+        'numto' => message.recipient,
+        'data1' => message.body
+      ) do |response|
+        DeliveryReport.from_response( response )
+      end
+    end
+
+    # Fetch replies from the gateway and then return a collection of replies or
+    # yield each reply if a block is given
+    def replies( last_id = 0, &block )
+      data = [
+      "<reply>",
+      "<settings>",
+      "<id>#{last_id}</id>",
+      "<max_recs>100</max_recs>",
+      "<cols_returned>eventid,numfrom,receiveddata,received,sentid,sentdata,sentdatetime,sentcustomerid</cols_returned>",
+      "</settings>",
+      "</reply>"
+      ]
+      perform_request(
+        'Type' => 'replies',
+        'XMLData' => data.join
+      ) do |response|
+        replies = []
+        response.xpath('/api_result/data').each do |reply|
+          replies << Smsinabox::Reply.from_response( reply )
+        end
+
+        replies.each { |r| yield r } if block_given?
+        
+        replies
+      end
+    end
+
+    def sent( last_id = 0, &block )
+      data = [
+      "<sent>",
+      "<settings>",
+      "<id>#{last_id}</id>",
+      "<max_recs>100</max_recs>",
+      "<cols_returned>sentid,eventid,smstype,numto,data,flash,customerid,status,statusdate</cols_returned>",
+      "</settings>",
+      "</sent>"
+      ]
+
+      perform_request(
+        'Type' => 'sent',
+        'XMLData' => data.join
+      ) do |response|
+        messages = []
+        response.xpath('/api_result/data').each do |msg|
+          messages << Smsinabox::SentMessage.from_response( msg )
+        end
+
+        messages.each { |m| yield m } if block_given?
+
+        messages
+      end
+    end
+
+    # Set our username and password from #Smsinabox::Configuration
+    def configure!( config_file = nil )
+      c = Configuration.new( config_file )
+      @username = c["username"]
+      @password = c["password"]
+      nil
+    end
+
+    private
+
+    def perform_request( params = {}, &block )
+      raise MissingCredentialException if @username.nil? || @password.nil?
+      params.merge!( 'Username' => @username, 'Password' => @password )
+
+      req = Net::HTTP::Post.new( uri.path )
+      req.set_form_data( params )
+      req['user-agent'] = 'SMS in a Box/' + Smsinabox::VERSION
+      res = Net::HTTP.new( uri.host, uri.port ).start { |http| http.request( req ) }
+      case res
+      when Net::HTTPSuccess
+        yield Nokogiri::XML( res.body )
+      else
+        raise "Could not complete request"
+      end
+    end
+
+  end
+
+end

data/lib/smsinabox/configuration.rb

@@ -0,0 +1,55 @@
+require 'yaml'
+
+module Smsinabox
+  
+  # Wrapper around our YAML configuration file, which lives in ~/.smsinabox by
+  # default
+  class Configuration
+    
+    def initialize( config_file = nil )
+      @config_file = config_file
+      
+      check_file!
+      load_config
+    end
+    
+    def []( key )
+      @configuration[key.to_s]
+    end
+    
+    def []=( key, value )
+      @configuration[ key.to_s ] = value
+    end
+    
+    def save
+      File.open( config_name, 'w' ) do |f|
+        YAML::dump( @configuration , f )
+      end
+      nil
+    end
+    
+    private
+    
+    def load_config
+      begin
+        @configuration = File.open( config_name, 'r' ) do |f|
+          YAML::load( f )
+        end
+      rescue
+      end
+      
+      @configuration ||= {}
+    end
+    
+    def check_file!
+      unless File.exist?( config_name )
+        File.open( config_name, 'w+' ) { |f| f.write('') }
+        File.chmod( 0600, config_name )
+      end
+    end
+    
+    def config_name
+      @config_file || File.expand_path( File.join('~', '.smsinabox') )
+    end
+  end
+end