textmagic 0.2.0

data/.document

@@ -0,0 +1,5 @@
+README.rdoc
+lib/**/*.rb
+bin/*
+features/**/*.feature
+LICENSE

data/.gitignore

@@ -0,0 +1,5 @@
+*.sw?
+.DS_Store
+coverage
+rdoc
+pkg

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 Vladimir Bobes Tuzinsky
+
+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/README.rdoc

@@ -0,0 +1,40 @@
+= TextMagic
+
+TextMagic is a Ruby interface to the TextMagic's HTTP API. You need to have
+a valid TextMagic account to use this gem. Sign up at http://www.textmagic.com
+to get one.
+
+== Installation
+
+Run
+
+  gem install textmagic
+
+Use +sudo+ if required by your system.
+
+
+== Basic usage
+
+To create an API instance, run:
+
+  api = TextMagic::API.new(username, password)
+
+with your credentials. Created instance will remember the username and password
+and will use it for all commands.
+
+To retrieve your account's balance, run:
+
+  api.account.balance
+
+To send a text message, run:
+
+  api.send 'Hi Vilma!', '441234567890'
+
+You can even specify multiple phone numbers:
+
+  api.send 'Hi Vilma!', '314159265358', '271828182845'
+
+
+== Copyright
+
+Copyright (c) 2009 Vladimir Bobes Tuzinsky. See LICENSE for details.

data/Rakefile

@@ -0,0 +1,57 @@
+require 'rubygems'
+require 'rake'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "textmagic"
+    gem.summary = %Q{Ruby interface to the TextMagic's SMS gateway}
+    gem.email = "vladimir.tuzinsky@gmail.com"
+    gem.homepage = "http://github.com/bobes/textmagic"
+    gem.authors = ["Vladimir Bobes Tuzinsky"]
+    gem.rubyforge_project = "textmagic"
+  end
+
+  Jeweler::RubyforgeTasks.new
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: sudo gem install jeweler"
+end
+
+require 'rake/testtask'
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'lib' << 'test'
+  test.pattern = 'test/**/*_test.rb'
+  test.verbose = true
+end
+
+begin
+  require 'rcov/rcovtask'
+  Rcov::RcovTask.new do |test|
+    test.libs << 'test'
+    test.pattern = 'test/**/*_test.rb'
+    test.verbose = true
+  end
+rescue LoadError
+  task :rcov do
+    abort "RCov is not available. In order to run rcov, you must: sudo gem install spicycode-rcov"
+  end
+end
+
+
+task :default => :test
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  if File.exist?('VERSION.yml')
+    config = YAML.load(File.read('VERSION.yml'))
+    version = "#{config[:major]}.#{config[:minor]}.#{config[:patch]}"
+  else
+    version = ""
+  end
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "textmagic #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+

data/VERSION.yml

@@ -0,0 +1,4 @@
+--- 
+:major: 0
+:minor: 2
+:patch: 0

data/lib/api.rb

@@ -0,0 +1,179 @@
+module TextMagic
+
+  class API
+
+    extend Charset
+    extend Validation
+
+    # Creates new API instance with specified credentials. These will be
+    # used in all requests to the TextMagic's HTTP gateway done through
+    # this instance. Multiple instances with different credentials can
+    # be used at the same time.
+    #
+    # Example usage:
+    #
+    #  api = TextMagic::API.new('fred', 'secret')
+    def initialize(username, password)
+      @username = username
+      @password = password
+    end
+
+    # Executes an account command and returns a hash with account's balance
+    # if successful, otherwise it raises an Error.
+    # The returned hash will be extended with custom reader method defined
+    # in Response module.
+    #
+    # Example usage:
+    #
+    #  api.account
+    #  # => { 'balance' => 314.15 }
+    #
+    # Using custom reader:
+    #
+    #  api.account.balance
+    #  # => 314.15
+    def account
+      response = Executor.execute('account', @username, @password)
+      response.extend(TextMagic::API::Response::Account)
+    end
+
+    # Executes a send command and returns a hash with message ids, sent text and
+    # number of parts if successful, otherwise it raises an Error.
+    # The returned hash will be extended with custom reader method defined
+    # in Response module.
+    #
+    # This method accepts any positive number of phone numbers and an additional
+    # options hash.
+    #
+    # The optional parameters you can specify in the options hash are:
+    # * +unicode+: accepted values are true, false, 0 and 1
+    # * +max_length+: accepted values are nil, 1, 2 and 3, defaults to nil
+    # If not specified, the method will determine the unicode value based on the
+    # characters in the text.
+    #
+    # Example usage:
+    #
+    #  api.send('Hi Vilma', '999314159265')
+    #  # => { 'message_ids' => [141421], 'message_id_hash' => { '999314159265' => '141421' }, 'sent_text' => 'Hi Vilma', 'parts_count' => 1 }
+    #  api.send(text, phone, :unicode => true)
+    #  api.send(text, phone1, phone2, :max_length => 2)
+    #  api.send(text, [phone1, phone2])
+    #
+    # Using custom readers:
+    #
+    #  response = api.send('Hi Vilma', '999314159265', '999271828182')
+    #  response.message_ids
+    #  # => ['141421', '173205']
+    #  response.message_id_hash
+    #  # => { '999314159265' => '141421', '999271828182' => '173205' }
+    #  response.message_id
+    #  # => '141421'
+    #  response.message_id('999271828182')
+    #  # => '173205'
+    #  response.parts_count
+    #  # => 1
+    def send(text, *args)
+      raise Error.new(1, 'Message text is empty') if text.nil? || text.blank?
+      options = args.last.is_a?(Hash) ? args.pop : {}
+      unicode = API.is_unicode(text)
+      options[:unicode] = case options[:unicode]
+      when 1, true: 1
+      when 0, false: 0
+      when nil: unicode ? 1 : 0
+      else raise Error.new(10, "Wrong parameter value #{options[:unicode]} for parameter unicode")
+      end
+      raise Error.new(6, 'Message contains invalid characters') if unicode && options[:unicode] == 0
+      raise Error.new(7, 'Message too long') unless API.validate_text_length(text, unicode)
+      phones = args.flatten
+      raise Error.new(9, 'Invalid phone number format') unless API.validate_phones(phones)
+      response = Executor.execute('send', @username, @password, options.merge(:text => text, :phone => phones.join(',')))
+      response.extend(TextMagic::API::Response::Send)
+    end
+
+    # Executes a message_status command and returns a hash with states of
+    # messages for specified ids if successful, otherwise it raises a
+    # TextMagic::API::Error.
+    # The returned hash will be extended with custom reader method defined
+    # in Response module.
+    #
+    # This method accepts any positive number of ids specified as an array
+    # or as a list of arguments
+    #
+    # Example usage:
+    #
+    #  api.message_status('141421')
+    #  # => { '141421' => { 'text' => 'Hi Vilma', 'status' => 'd' , 'created_time' => Mon May 25 16:42:30 +0200 2009, 'reply_number' => '447624800500', 'completed_time' => nil, 'credits_cost' => 0.5 } }
+    #  api.message_status('141421', '173205')
+    #  api.message_status(['141421', '173205'])
+    #
+    # Using custom readers:
+    #
+    #  response = api.message_status('141421', '173205')
+    #  response['141421'].text
+    #  # => 'Hi Vilma'
+    #  response['141421'].status
+    #  # => 'd'
+    #  response['141421'].created_time
+    #  # => Fri May 22 10:10:18 +0200 2009
+    def message_status(*ids)
+      ids.flatten!
+      raise TextMagic::API::Error.new(4, 'Insufficient parameters') if ids.empty?
+      response = Executor.execute('message_status', @username, @password, :ids => ids.join(','))
+      response.extend(TextMagic::API::Response::MessageStatus)
+    end
+
+    # Executes a receive command and returns a hash with unread messages
+    # if successful, otherwise it raises an Error.
+    # The returned hash will be extended with custom reader method defined
+    # in Response module.
+    #
+    # This method accepts an optional +last_retrieved_id+ value.
+    #
+    # Example usage:
+    #
+    #  api.receive
+    #  # => { 'messages' => [{ 'message_id' => '141421', 'from' => '999314159265', 'timestamp' => Fri May 22 12:12:55 +0200 2009, 'text' => 'Hi Fred!' }], 'unread' => 0 }
+    #  api.receive '141421'
+    #
+    # Using custom readers:
+    #
+    #  response = api.receive
+    #  response.messages
+    #  # => [{ 'timestamp' => Fri May 22 12:12:55 +0200 2009, 'from' => '999314159265', 'text' => 'Hi Fred', 'message_id' => '141421' }]
+    #  response.unread
+    #  # => 0
+    #  response.messages[0].timestamp
+    #  # => Fri May 22 12:12:55 +0200 2009
+    def receive(last_retrieved_id = nil)
+      response = Executor.execute('receive', @username, @password, :last_retrieved_id => last_retrieved_id)
+      response.extend(TextMagic::API::Response::Receive)
+    end
+
+    # Executes a delete_reply command and returns a hash with a list of deleted
+    # message ids if successful, otherwise it raises an Error.
+    # The returned hash will be extended with custom reader method defined
+    # in Response module.
+    #
+    # This method accepts any positive number of ids specified as an array
+    # or as a list of arguments.
+    #
+    # Example usage:
+    #
+    #  api.delete_reply('141421')
+    #  # => { 'deleted' => ['141421'] }
+    #  api.delete_reply('141421', '173205')
+    #  api.delete_reply(['141421', '173205'])
+    #
+    # Using custom readers:
+    #
+    #  response = api.delete_reply('141421', '173205')
+    #  response.deleted
+    #  # => ['141421', '173205']
+    def delete_reply(*ids)
+      ids.flatten!
+      raise TextMagic::API::Error.new(4, 'Insufficient parameters') if ids.empty?
+      response = Executor.execute('delete_reply', @username, @password, :ids => ids.join(','))
+      response.extend(TextMagic::API::Response::DeleteReply)
+    end
+  end
+end

data/lib/charset.rb

@@ -0,0 +1,23 @@
+module TextMagic
+
+  class API
+
+    module Charset
+
+      GSM_CHARSET = "@£$¥èéùìòÇ\nØø\rÅåΔ_ΦΓΛΩΠΨΣΘΞ\e\f^{}\\[~]|€ÆæßÉ !\"#¤%&'()*+,-./0123456789:;<=>?¡ABCDEFGHIJKLMNOPQRSTUVWXYZÄÖÑܧ¿abcdefghijklmnopqrstuvwxyzäöñüà".scan(/./u)
+
+      # Returns +true+ if the supplied text contains only characters from
+      # GSM 03.38 charset, otherwise it returns +false+.
+      def is_gsm(text)
+        text.scan(/./u).each { |c| return false unless GSM_CHARSET.include?(c) }
+        true
+      end
+
+      # Returns +true+ if the supplied text contains characters outside of
+      # GSM 03.38 charset, otherwise it returns +false+.
+      def is_unicode(text)
+        !is_gsm(text)
+      end
+    end
+  end
+end

data/lib/error.rb

@@ -0,0 +1,27 @@
+module TextMagic
+
+  class API
+
+    class Error < StandardError
+
+      attr_reader :code, :message
+
+      # Creates an instance of TextMagic::API::Error. Error code and message
+      # can be supplied as arguments or as a response hash.
+      #
+      #  TextMagic::API::Error.new(code, message)
+      #  TextMagic::API::Error.new('error_code' => code, 'error_message' => message)
+      def initialize(*args)
+        if args.first.is_a?(Hash)
+          @code, @message = args.first['error_code'], args.first['error_message']
+        else
+          @code, @message = args
+        end
+      end
+
+      def to_s
+        "#{@message} (#{@code})"
+      end
+    end
+  end
+end

data/lib/executor.rb

@@ -0,0 +1,34 @@
+module TextMagic
+
+  class API
+
+    class Executor
+
+      include HTTParty
+      base_uri "http://www.textmagic.com/app"
+
+      # Executes a command by sending a request to the TextMagic's HTTP
+      # gateway. This is a low-level generic method used by methods in
+      # TextMagic::API class. You should never need to use this method
+      # directly.
+      #
+      # Parameters specified in the +options+ hash will be added to the
+      # HTTP request's URI.
+      #
+      # Returns a hash with values parsed from the server's response if
+      # the command was successfully executed. In case the server replies
+      # with error, this method raises a TextMagic::API::Error.
+      def self.execute(command, username, password, options = {})
+        raise TextMagic::API::Error.new(3, 'Command is undefined') if command.nil? || command.blank?
+        if username.nil? || username.blank? || password.nil? || password.blank?
+          raise TextMagic::API::Error.new(5, 'Invalid username & password combination')
+        end
+        options.merge!(:username => username, :password => password, :cmd => command)
+        options.delete_if { |key, value| key.nil? || key.to_s.blank? || value.nil? || value.to_s.blank? }
+        response = self.get('/api', :query => options, :format => :json)
+        raise Error.new(response) if response && response['error_code']
+        response
+      end
+    end
+  end
+end

data/lib/response.rb

@@ -0,0 +1,141 @@
+module TextMagic
+
+  class API
+
+    # Used to cleanup response hash and extend it with custom reader methods.
+    #
+    # === Account response hash
+    #
+    # When extended, it
+    # * converts the +balance+ value to +float+ and
+    # * adds a reader method +balance+.
+    #
+    # === Send response hash
+    #
+    # When extended, it
+    # * inverts the +message_id+ hash and puts it in +message_id_hash+,
+    # * adds an array of ids to +message_ids+,
+    # * adds reader methods +message_id_hash+, +message_ids+, +sent_text+ and
+    #   +parts_count+ to the hash.
+    # * adds a reader method +message_id+, which returns a +message_id+ for
+    #   a given phone number, or the first message_id if no phone number
+    #   is specified.
+    #
+    # === Message status response hash
+    #
+    # When extended, it
+    # * converts the +credits_cost+ value to +float+,
+    # * converts the +created_time+ and +completed_time+ values to +Time+,
+    # * adds reader methods +text+, +status+, +reply_number+, +credits_cost+,
+    #   +created_time+ and +completed_time+ to all values of the hash.
+    #
+    # === Receive status response hash
+    #
+    # When extended, it
+    # * converts the +timestamp+ value to +Time+,
+    # * adds reader methods +messages+ and +unread+ to the hash
+    # * adds reader methods +message_id+, +timestamp+, +text+ and +from+
+    #   to all members of the +messages+ array.
+    #
+    # === Delete reply response hash
+    #
+    # When extended, it
+    # * adds a reader method +deleted+.
+    module Response
+
+      module Account #:nodoc: all
+
+        def self.extended(base)
+          return unless base.is_a?(Hash)
+          base['balance'] = base['balance'].to_f if base['balance']
+        end
+
+        def balance
+          self['balance']
+        end
+      end
+
+      module Send #:nodoc: all
+
+        def self.extended(base)
+          return unless base.is_a?(Hash)
+          base['message_id_hash'] = base.delete('message_id').invert if base['message_id']
+          base['message_ids'] = base['message_id_hash'].values.sort if base['message_id_hash']
+        end
+
+        %w(message_id_hash message_ids sent_text parts_count).each do |method|
+          module_eval <<-EOS
+          def #{method}
+            self['#{method}']
+          end
+          EOS
+        end
+
+        def message_id(phone = nil)
+          phone ? message_id_hash[phone] : message_ids.first
+        end
+      end
+
+      module MessageStatus #:nodoc: all
+
+        def self.extended(base)
+          return unless base.is_a?(Hash)
+          base.values.each do |status|
+            status['credits_cost'] = status['credits_cost'].to_f if status['credits_cost']
+            status['created_time'] = Time.at(status['created_time'].to_i) if status['created_time']
+            status['completed_time'] = Time.at(status['completed_time'].to_i) if status['completed_time']
+            status.extend Status
+          end
+        end
+
+        module Status
+
+          %w(text status reply_number credits_cost created_time completed_time).each do |method|
+            module_eval <<-EOS
+            def #{method}
+              self['#{method}']
+            end
+            EOS
+          end
+        end
+      end
+
+      module Receive #:nodoc: all
+
+        def self.extended(base)
+          return unless base.is_a?(Hash) && base['messages']
+          base['messages'].each do |message|
+            message['timestamp'] = Time.at(message['timestamp'].to_i) if message['timestamp']
+            message.extend Message
+          end
+        end
+
+        %w(messages unread).each do |method|
+          module_eval <<-EOS, __FILE__, __LINE__ + 1
+          def #{method}
+            self['#{method}']
+          end
+          EOS
+        end
+
+        module Message
+
+          %w(message_id timestamp text from).each do |method|
+            module_eval <<-EOS
+            def #{method}
+              self['#{method}']
+            end
+            EOS
+          end
+        end
+      end
+
+      module DeleteReply #:nodoc: all
+
+        def deleted
+          self['deleted']
+        end
+      end
+    end
+  end
+end