bobes-textmagic 0.1.0 → 0.2.0

data/README.rdoc

@@ -1,6 +1,39 @@
-= textmagic
+= 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'
 
-Documentation will come soon.
 
 == Copyright
 

data/VERSION.yml

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

data/lib/api.rb

@@ -2,33 +2,178 @@ 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['balance'] = response['balance'].to_f
-      response
+      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 : {}
-      phones = args.flatten.join(',')
-      Executor.execute('send', @username, @password, options.merge(:text => text, :phone => phones))
+      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)
-      Executor.execute('message_status', @username, @password, :ids => ids.flatten.join(','))
+      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
 
-    def receive
-      Executor.execute('receive', @username, @password)
+    # 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)
-      Executor.execute('delete_reply', @username, @password, :ids => ids.flatten.join(','))
+      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

@@ -6,8 +6,17 @@ module TextMagic
 
       attr_reader :code, :message
 
-      def initialize(response)
-        @code, @message = response[:error_code], response[:error_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

data/lib/executor.rb

@@ -5,12 +5,28 @@ module TextMagic
     class Executor
 
       include HTTParty
-      base_uri "https://www.textmagic.com/app"
+      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['error_code']
+        raise Error.new(response) if response && response['error_code']
         response
       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

data/lib/textmagic.rb

@@ -1,9 +1,12 @@
 require 'rubygems'
 gem 'httparty'
 require 'httparty'
+require 'charset'
+require 'validation'
 require 'api'
+require 'response'
 require 'executor'
 require 'error'
 
-module TextMagic
+module TextMagic #:nodoc:
 end

data/lib/validation.rb

@@ -0,0 +1,34 @@
+module TextMagic
+
+  class API
+
+    module Validation
+
+      MAX_LENGTH_GSM = [160, 306, 459]
+      MAX_LENGTH_UNICODE = [70, 134, 201]
+
+      # Validates message text length. Returns +true+ if the text length is
+      # within the limits for the unicode/parts combination, otherwise it
+      # returns +false+.
+      #
+      # Note: <em>Maximum lengths for 1, 2 and 3-part GSM 03.38 messages are
+      # 160, 306 and 459 respectively.
+      # Maximum lengths for 1, 2 and 3-part unicode messages are
+      # 70, 134 and 201 respectively.</em>
+      def validate_text_length(text, unicode, parts = 3)
+        max_text_length = (unicode ? MAX_LENGTH_UNICODE : MAX_LENGTH_GSM)[parts - 1]
+        text.size <= max_text_length
+      end
+
+      # Validates a list of phone numbers. Returns +true+ if the list is not empty
+      # and all phone numbers are digit-only strings of maximum length of 15,
+      # otherwise it returns +false+.
+      def validate_phones(*phones)
+        phones.flatten!
+        return false if phones.empty?
+        phones.each { |phone| return false unless phone =~ /^\d{1,15}$/ }
+        true
+      end
+    end
+  end
+end

data/test/test_api.rb

@@ -2,19 +2,10 @@ require 'test_helper'
 
 class APITest < Test::Unit::TestCase
 
-  def prepare_api(command, raw_response, options = {})
-    FakeWeb.allow_net_connect = false
-
-    @username, @password = random_string, random_string
-    uri = build_uri(command, @username, @password, options)
-    FakeWeb.register_uri(:get, uri, :string => raw_response)
-    TextMagic::API.new(@username, @password)
-  end
-
   context 'Initialization' do
 
     should 'require username and password' do
-      lambda { TextMagic::API.new }.should raise_error
+      lambda { TextMagic::API.new }.should raise_error(ArgumentError)
       TextMagic::API.new(random_string, random_string)
     end
   end
@@ -22,6 +13,7 @@ class APITest < Test::Unit::TestCase
   context 'Account command' do
 
     setup do
+      @balance = 0.01 * rand(1e4)
       @username, @password = random_string, random_string
       @api = TextMagic::API.new(@username, @password)
     end
@@ -31,11 +23,17 @@ class APITest < Test::Unit::TestCase
       @api.account
     end
 
-    should 'return a hash with numeric balance value' do
-      TextMagic::API::Executor.expects(:execute).returns({ 'balance' => '3.14' })
+    should 'return a hash extended with TextMagic::API::Response::Account' do
+      TextMagic::API::Executor.expects(:execute).returns({ 'balance' => @balance.to_s })
       response = @api.account
       response.class.should == Hash
-      response['balance'].should == 3.14
+      response.is_a?(TextMagic::API::Response::Account).should == true
+    end
+
+    should 'return a hash with balance value' do
+      TextMagic::API::Executor.expects(:execute).returns({ 'balance' => @balance.to_s })
+      response = @api.account
+      response['balance'].should be_close(@balance, 1e-10)
     end
   end
 
@@ -45,31 +43,80 @@ class APITest < Test::Unit::TestCase
       @username, @password = random_string, random_string
       @text, @phone = random_string, random_phone
       @api = TextMagic::API.new(@username, @password)
+      TextMagic::API::Executor.stubs(:execute)
     end
 
     should 'call Executor execute with correct arguments' do
-      TextMagic::API::Executor.expects(:execute).with('send', @username, @password, :text => @text, :phone => @phone)
+      TextMagic::API::Executor.expects(:execute).with('send', @username, @password, :text => @text, :phone => @phone, :unicode => 0)
       @api.send(@text, @phone)
     end
 
     should 'join multiple phone numbers supplied as an array' do
       phones = Array.new(3) { random_phone }
-      TextMagic::API::Executor.expects(:execute).with('send', @username, @password, :text => @text, :phone => phones.join(','))
+      TextMagic::API::Executor.expects(:execute).with('send', @username, @password, :text => @text, :phone => phones.join(','), :unicode => 0)
       @api.send(@text, phones)
     end
 
     should 'join multiple phone numbers supplied as arguments' do
       phones = Array.new(3) { random_phone }
-      TextMagic::API::Executor.expects(:execute).with('send', @username, @password, :text => @text, :phone => phones.join(','))
+      TextMagic::API::Executor.expects(:execute).with('send', @username, @password, :text => @text, :phone => phones.join(','), :unicode => 0)
       @api.send(@text, *phones)
     end
 
-    should 'return a hash with message_id, sent_text and parts_count' do
+    should 'replace true with 1 for unicode' do
+      TextMagic::API::Executor.expects(:execute).with('send', @username, @password, :text => @text, :phone => @phone, :unicode => 1)
+      @api.send(@text, @phone, :unicode => true)
+    end
+
+    should 'set unicode value to 0 if it is not set to by user and text contains only characters from GSM 03.38 charset' do
+      TextMagic::API::Executor.expects(:execute).with('send', @username, @password, :text => @text, :phone => @phone, :unicode => 0).times(2)
+      @api.send(@text, @phone)
+      @api.send(@text, @phone, :unicode => false)
+    end
+
+    should 'raise an error if unicode is set to 0 and text contains characters outside of GSM 03.38 charset' do
+      text = 'Вильма Привет'
+      lambda { @api.send(text, @phone, :unicode => false) }.should raise_error(TextMagic::API::Error)
+    end
+
+    should 'raise an error if unicode value is not valid' do
+      lambda { @api.send(@text, @phone, :unicode => 2 + rand(10)) }.should raise_error(TextMagic::API::Error)
+      lambda { @api.send(@text, @phone, :unicode => random_string) }.should raise_error(TextMagic::API::Error)
+    end
+
+    should 'raise an error if no phone numbers are specified' do
+      lambda { @api.send(@text) }.should raise_error(TextMagic::API::Error)
+      lambda { @api.send(@text, []) }.should raise_error(TextMagic::API::Error)
+    end
+
+    should 'raise an error if format of any of the specified phone numbers is invalid' do
+      TextMagic::API.expects(:validate_phones).returns(false)
+      lambda { @api.send(@text, random_string) }.should raise_error(TextMagic::API::Error)
+    end
+
+    should 'raise an error if text is empty' do
+      lambda { @api.send('', @phone) }.should raise_error(TextMagic::API::Error)
+    end
+
+    should 'raise an error if text is too long' do
+      TextMagic::API.expects(:validate_text_length).returns(false)
+      lambda { @api.send(@text, @phone) }.should raise_error(TextMagic::API::Error)
+    end
+
+    should 'return a hash extended with TextMagic::API::Response::Send' do
       message_id = random_string
       TextMagic::API::Executor.expects(:execute).returns({ 'message_id' => { message_id => @phone }, 'sent_text' => @text, 'parts_count' => 1 })
       response = @api.send(@text, @phone)
-      response['message_id'].should == { message_id => @phone }
-      response['sent_text'].should == @text
+      response.class.should == Hash
+      response.is_a?(TextMagic::API::Response::Send).should == true
+    end
+
+    should 'return a hash with message_id_hash, message_ids, sent_text and parts_count values' do
+      message_id = random_string
+      TextMagic::API::Executor.expects(:execute).returns({ 'message_id' => { message_id => @phone }, 'sent_text' => @text, 'parts_count' => 1 })
+      response = @api.send(@text, @phone)
+      response['message_id_hash'].should == { @phone => message_id }
+      response['message_ids'].should == [message_id]
       response['parts_count'].should == 1
     end
   end
@@ -99,9 +146,21 @@ class APITest < Test::Unit::TestCase
       @api.message_status(*ids)
     end
 
+    should 'not call execute and should raise an exception if no ids are specified' do
+      TextMagic::API::Executor.expects(:execute).never
+      lambda { @api.message_status }.should raise_error(TextMagic::API::Error)
+    end
+
+    should 'return a hash extended with TextMagic::API::Response::MessageStatus' do
+      TextMagic::API::Executor.expects(:execute).returns({ '8659912' => {} })
+      response = @api.message_status(random_string)
+      response.class.should == Hash
+      response.is_a?(TextMagic::API::Response::MessageStatus).should == true
+    end
+
     should 'return a hash with message ids as keys' do
       TextMagic::API::Executor.expects(:execute).returns({ '8659912' => {} })
-      response = @api.message_status
+      response = @api.message_status(random_string)
       response['8659912'].should == {}
     end
   end
@@ -114,11 +173,24 @@ class APITest < Test::Unit::TestCase
     end
 
     should 'call Executor execute with correct arguments' do
-      TextMagic::API::Executor.expects(:execute).with('receive', @username, @password)
+      TextMagic::API::Executor.expects(:execute).with('receive', @username, @password, :last_retrieved_id => nil)
       @api.receive
     end
 
-    should 'return a hash with messages and number of unread messages' do
+    should 'accept last_retrieved_id optional value' do
+      last_retrieved_id = rand(1e10)
+      TextMagic::API::Executor.expects(:execute).with('receive', @username, @password, :last_retrieved_id => last_retrieved_id)
+      @api.receive(last_retrieved_id)
+    end
+
+    should 'return a hash extended with TextMagic::API::Response::Receive' do
+      TextMagic::API::Executor.expects(:execute).returns({ 'messages' => [], 'unread' => 0 })
+      response = @api.receive
+      response.class.should == Hash
+      response.is_a?(TextMagic::API::Response::Receive).should == true
+    end
+
+    should 'return a hash with unread and messages values' do
       TextMagic::API::Executor.expects(:execute).returns({ 'messages' => [], 'unread' => 0 })
       response = @api.receive
       response['unread'].should == 0
@@ -151,42 +223,24 @@ class APITest < Test::Unit::TestCase
       @api.delete_reply(*ids)
     end
 
-    should 'return a hash with deleted ids' do
+    should 'not call execute and should raise an exception if no ids are specified' do
+      TextMagic::API::Executor.expects(:execute).never
+      lambda { @api.delete_reply }.should raise_error(TextMagic::API::Error)
+    end
+
+    should 'return a hash extended with TextMagic::API::Response::DeleteReply' do
       ids = Array.new(3) { random_string }
       TextMagic::API::Executor.expects(:execute).returns({ 'deleted' => ids })
-      response = @api.receive
-      response['deleted'].should == ids
+      response = @api.delete_reply(ids)
+      response.class.should == Hash
+      response.is_a?(TextMagic::API::Response::DeleteReply).should == true
+    end
+
+    should 'return a hash with deleted value' do
+      ids = Array.new(3) { random_string }
+      TextMagic::API::Executor.expects(:execute).returns({ 'deleted' => ids })
+      response = @api.delete_reply(ids)
+      response.deleted.should == ids
     end
   end
 end
-
-__END__
-
-Example responses
-
-account:
-{"balance":"100"}
-
-send:
-{"message_id":{"1234567":"444444123456"},"sent_text":"test","parts_count":1}
-
-message_status:
-{"8659912":{"text":"test","status":"d","created_time":"1242979818","reply_number":"447624800500","completed_time":null,"credits_cost":"0.5"},"8659914":{"text":"test","status":"d","created_time":"1242979839","reply_number":"447624800500","completed_time":null,"credits_cost":"0.5"}}
-
-receive (empty):
-{"messages":[],"unread":0}
-
-empty message:
-{"error_code":1,"error_message":"Messages text is empty"}
-
-insufficient parameters:
-{"error_code":4,"error_message":"Insufficient parameters"}
-
-invalid credentials:
-{"error_code":5,"error_message":"Invalid username & password combination"}
-
-invalid phone number format:
-{"error_code":9,"error_message":"Wrong phone number format"}
-
-invalid message_id:
-{"error_code":14,"error_message":"Message with id 8659913 does not exist"}

data/test/test_charset.rb

@@ -0,0 +1,28 @@
+require 'test_helper'
+require 'json'
+
+class CharsetTest < Test::Unit::TestCase
+
+  context 'is_gsm method' do
+
+    should 'return true if all characters are in GSM 03.38 charset' do
+      TextMagic::API.is_gsm(('a'..'z').to_a.join).should == true
+      TextMagic::API.is_gsm(('A'..'Z').to_a.join).should == true
+      TextMagic::API.is_gsm(('0'..'9').to_a.join).should == true
+      TextMagic::API.is_gsm("@£$¥€").should == true
+      TextMagic::API.is_gsm("\n\r\e\f\\\"").should == true
+      TextMagic::API.is_gsm("èéùìòÇØøÅåÉÆæß").should == true
+      TextMagic::API.is_gsm("ΔΦΓΛΩΠΨΣΘΞ").should == true
+      TextMagic::API.is_gsm("^{}[~]| !#¤%&'()").should == true
+      TextMagic::API.is_gsm("*+,-./_:;<=>?¡¿§").should == true
+      TextMagic::API.is_gsm("ÖÑÜöñüàäÄ").should == true
+    end
+
+    should 'return false if some characters are outside of GSM 03.38 charset' do
+      TextMagic::API.is_gsm('Arabic: مرحبا فيلما').should == false
+      TextMagic::API.is_gsm('Chinese: 您好').should == false
+      TextMagic::API.is_gsm('Cyrilic: Вильма Привет').should == false
+      TextMagic::API.is_gsm('Thai: สวัสดี').should == false
+    end
+  end
+end

data/test/test_error.rb

@@ -0,0 +1,24 @@
+require 'test_helper'
+
+class ErrorTest < Test::Unit::TestCase
+
+  context 'Initialization' do
+
+    setup do
+      @code = rand(1e3)
+      @message = random_string
+    end
+
+    should 'accept a hash with error_code and error_message' do
+      e = TextMagic::API::Error.new('error_code' => @code, 'error_message' => @message)
+      e.code.should == @code
+      e.message.should == @message
+    end
+
+    should 'accept error_code and error_message' do
+      e = TextMagic::API::Error.new(@code, @message)
+      e.code.should == @code
+      e.message.should == @message
+    end
+  end
+end

data/test/test_executor.rb

@@ -13,12 +13,45 @@ class ExecutorTest < Test::Unit::TestCase
       @uri = build_uri(@command, @username, @password, @options)
     end
 
+    should 'not send HTTP request without command' do
+      TextMagic::API::Executor.expects(:get).never
+      lambda {
+        TextMagic::API::Executor.execute(nil, @username, @password, @options)
+      }.should raise_error(TextMagic::API::Error)
+    end
+
+    should 'not send HTTP request without username' do
+      TextMagic::API::Executor.expects(:get).never
+      lambda {
+        TextMagic::API::Executor.execute(@command, nil, @password, @options)
+      }.should raise_error(TextMagic::API::Error)
+    end
+
+    should 'not send HTTP request without password' do
+      TextMagic::API::Executor.expects(:get).never
+      lambda {
+        TextMagic::API::Executor.execute(@command, @username, nil, @options)
+      }.should raise_error(TextMagic::API::Error)
+    end
+
     should 'send a GET request to proper uri' do
       response = random_string
       FakeWeb.register_uri(:get, @uri, :string => response)
       TextMagic::API::Executor.execute(@command, @username, @password, @options)
     end
 
+    should 'not send parameters with empty keys' do
+      options_with_empty_values = @options.merge(nil => random_string, '' => random_string)
+      TextMagic::API::Executor.expects(:get).with('/api', :query => @options, :format => :json)
+      TextMagic::API::Executor.execute(@command, @username, @password, options_with_empty_values)
+    end
+
+    should 'not send parameters with empty values' do
+      options_with_empty_values = @options.merge(random_string => nil, random_string => '')
+      TextMagic::API::Executor.expects(:get).with('/api', :query => @options, :format => :json)
+      TextMagic::API::Executor.execute(@command, @username, @password, options_with_empty_values)
+    end
+
     should 'raise an error if the response contains error_code' do
       response = "{error_code:#{1 + rand(10)}}"
       FakeWeb.register_uri(:get, @uri, :string => response)
@@ -27,7 +60,7 @@ class ExecutorTest < Test::Unit::TestCase
       }.should raise_error(TextMagic::API::Error)
     end
 
-    should 'return a hash with values in the response' do
+    should 'return a hash with values from the response' do
       hash = random_hash
       FakeWeb.register_uri(:get, @uri, :string => hash.to_json)
       response = TextMagic::API::Executor.execute(@command, @username, @password, @options)

data/test/test_helper.rb

@@ -14,7 +14,7 @@ class Test::Unit::TestCase
 end
 
 def random_string(legth = 5)
-  rand(36 ** legth).to_s(36)
+  Array.new(legth) { rand(36).to_s(36) }.join
 end
 
 def random_phone
@@ -29,7 +29,7 @@ end
 
 def build_uri(command, username, password, options = {})
   options.merge!(:cmd => command, :username => username, :password => password)
-  uri = "https://www.textmagic.com:443/app/api?"
+  uri = "http://www.textmagic.com/app/api?"
   uri << options.collect { |key, value| "#{key}=#{value}"}.join('&')
 end
 

data/test/test_response.rb

@@ -0,0 +1,176 @@
+require 'test_helper'
+
+class ResponseTest < Test::Unit::TestCase
+
+  context 'Account response' do
+
+    setup do
+      @balance = 0.1 * rand(1e4)
+      @response = { 'balance' => @balance.to_s }
+      @response.extend TextMagic::API::Response::Account
+    end
+
+    should 'allow access to balance' do
+      @response.balance.should be_close(@balance, 1e-10)
+    end
+  end
+
+  context 'Send response' do
+
+    setup do
+      @message_id = {
+        '141421' => '999314159265',
+        '173205' => '999271828182'
+      }
+      @text = random_string
+      @parts_count = rand(10)
+      @response = {
+        'message_id' => @message_id,
+        'sent_text' => @text,
+        'parts_count' => @parts_count
+      }
+      @response.extend TextMagic::API::Response::Send
+    end
+
+    should 'allow access to inverted message_id hash' do
+      @response.message_id_hash.should == @message_id.invert
+    end
+
+    should 'allow access to message_ids array' do
+      @response.message_ids.should == ['141421', '173205']
+    end
+
+    should 'allow access to message_id for a given phone number' do
+      @response.message_id('999314159265').should == '141421'
+      @response.message_id('999271828182').should == '173205'
+    end
+
+    should 'allow access to sent_text' do
+      @response.sent_text.should == @text
+    end
+
+    should 'allow access to parts_count' do
+      @response.parts_count.should == @parts_count
+    end
+  end
+
+  context 'MessageStatus response' do
+
+    setup do
+      @text = random_string
+      @reply_number = random_phone
+      @created_time = (Time.now - 30).to_i
+      @completed_time = (Time.now - 20).to_i
+      @credits_cost = 0.01 * rand(300)
+      @response = {
+        '141421' => {
+          'text' => @text,
+          'status' => 'd',
+          'created_time' => @created_time,
+          'reply_number' => @reply_number,
+          'completed_time' => @completed_time,
+          'credits_cost' => @credits_cost
+        },
+        '173205' => {
+          'text' => 'test',
+          'status' => 'r',
+          'created_time' => '1242979839',
+          'reply_number' => '447624800500',
+          'completed_time' => nil,
+          'credits_cost' => 0.5
+        }
+      }
+      @response.extend TextMagic::API::Response::MessageStatus
+    end
+
+    should 'allow access to text for all statuses' do
+      @response['141421'].text.should == @text
+      @response['173205'].text.should == 'test'
+    end
+
+    should 'allow access to status for a given message_id' do
+      @response['141421'].status.should == 'd'
+      @response['173205'].status.should == 'r'
+    end
+
+    should 'allow access to reply_number for a given message_id' do
+      @response['141421'].reply_number.should == @reply_number
+      @response['173205'].reply_number.should == '447624800500'
+    end
+
+    should 'allow access to created_time for a given message_id' do
+      @response['141421'].created_time.should == Time.at(@created_time)
+      @response['173205'].created_time.should == Time.at(1242979839)
+    end
+
+    should 'allow access to completed_time for a given message_id' do
+      @response['141421'].completed_time.should == Time.at(@completed_time)
+      @response['173205'].completed_time.should == nil
+    end
+
+    should 'allow access to credits_cost for a given message_id' do
+      @response['141421'].credits_cost.should be_close(@credits_cost, 1e-10)
+      @response['173205'].credits_cost.should be_close(0.5, 1e-10)
+    end
+  end
+
+  context 'Receive response' do
+
+    setup do
+      @timestamp = (Time.now - 30).to_i
+      @message1 = {
+        'timestamp' => @timestamp,
+        'from' => '999314159265',
+        'text' => 'Hi Fred',
+        'message_id' => '141421'
+      }
+      @message2 = {
+        'timestamp' => 1243244148,
+        'from' => '999271828182',
+        'text' => 'Hello buddy',
+        'message_id' => '173205'
+      }
+      @messages = [@message1, @message2]
+      @unread = rand(1e4)
+      @response = { 'unread' => @unread, 'messages' => @messages }
+      @response.extend TextMagic::API::Response::Receive
+    end
+
+    should 'allow access to unread' do
+      @response.unread.should == @unread
+    end
+
+    should 'allow access to messages array' do
+      @response.messages.should == @messages
+    end
+
+    should 'allow access to message_id for all messages' do
+      @response.messages.first.message_id.should == '141421'
+    end
+
+    should 'allow access to timestamp for all messages' do
+      @response.messages.first.timestamp.should == Time.at(@timestamp)
+    end
+
+    should 'allow access to from for all messages' do
+      @response.messages.first.from.should == '999314159265'
+    end
+
+    should 'allow access to text for all messages' do
+      @response.messages.first.text.should == 'Hi Fred'
+    end
+  end
+
+  context 'DeleteReply response' do
+
+    setup do
+      @ids = ['141421', '1780826']
+      @response = { 'deleted' => @ids }
+      @response.extend TextMagic::API::Response::DeleteReply
+    end
+
+    should 'allow access to deleted' do
+      @response.deleted.should == @ids
+    end
+  end
+end

data/test/test_validation.rb

@@ -0,0 +1,99 @@
+require 'test_helper'
+require 'json'
+
+class ValidationTest < Test::Unit::TestCase
+
+  context 'validate_text_length method for non-unicode texts' do
+
+    should 'return true if parts limit is set to 1 and text length is less than or equal to 160' do
+      TextMagic::API.validate_text_length(random_string(160), false, 1).should == true
+    end
+
+    should 'return false if parts limit is set to 1 and text length is greater than 160' do
+      TextMagic::API.validate_text_length(random_string(161), false, 1).should == false
+    end
+
+    should 'return true if parts limit is set to 2 and text length is less than or equal to 306' do
+      TextMagic::API.validate_text_length(random_string(306), false, 2).should == true
+    end
+
+    should 'return false if parts limit is set to 2 and text length is greater than 306' do
+      TextMagic::API.validate_text_length(random_string(307), false, 2).should == false
+    end
+
+    should 'return true if parts limit is set to 3 or is not specified and text length is less than or equal to 459' do
+      TextMagic::API.validate_text_length(random_string(459), false).should == true
+      TextMagic::API.validate_text_length(random_string(459), false, 3).should == true
+    end
+
+    should 'return false if parts limit is set to 3 or is not specified and text length is greater than 459' do
+      TextMagic::API.validate_text_length(random_string(460), false).should == false
+      TextMagic::API.validate_text_length(random_string(460), false, 3).should == false
+    end
+  end
+
+  context 'validate_text_length method for unicode texts' do
+
+    should 'return true if parts limit is set to 1 and text length is less than or equal to 70' do
+      TextMagic::API.validate_text_length(random_string(70), true, 1).should == true
+    end
+
+    should 'return false if parts limit is set to 1 and text length is greater than 70' do
+      TextMagic::API.validate_text_length(random_string(71), true, 1).should == false
+    end
+
+    should 'return true if parts limit is set to 2 and text length is less than or equal to 134' do
+      TextMagic::API.validate_text_length(random_string(134), true, 2).should == true
+    end
+
+    should 'return false if parts limit is set to 2 and text length is greater than 134' do
+      TextMagic::API.validate_text_length(random_string(135), true, 2).should == false
+    end
+
+    should 'return true if parts limit is set to 3 or is not specified and text length is less than or equal to 201' do
+      TextMagic::API.validate_text_length(random_string(201), true).should == true
+      TextMagic::API.validate_text_length(random_string(201), true, 3).should == true
+    end
+
+    should 'return false if parts limit is set to 3 or is not specified and text length is greater than 201' do
+      TextMagic::API.validate_text_length(random_string(202), true).should == false
+      TextMagic::API.validate_text_length(random_string(202), true, 3).should == false
+    end
+  end
+
+  context 'validate_phones method' do
+
+    should 'return true if phone number consists of up to 15 digits' do
+      TextMagic::API.validate_phones(rand(10 ** 15).to_s).should == true
+    end
+
+    should 'return false if phone number is longer than 15 digits' do
+      TextMagic::API.validate_phones((10 ** 16 + rand(10 ** 15)).to_s).should == false
+    end
+
+    should 'return false if phone number contains non-digits' do
+      TextMagic::API.validate_phones(random_string).should == false
+    end
+
+    should 'return false if phone number is empty' do
+      TextMagic::API.validate_phones('').should == false
+    end
+
+    should 'return true if all phone numbers in a list are valid' do
+      phone1, phone2 = rand(10 ** 15).to_s, rand(10 ** 15).to_s
+      TextMagic::API.validate_phones(phone1, phone2).should == true
+      TextMagic::API.validate_phones([phone1, phone2]).should == true
+    end
+
+    should 'return false if phone numbers list is empty' do
+      TextMagic::API.validate_phones().should == false
+    end
+
+    should 'return false if format of any of phone numbers in a list is invalid' do
+      phone1 = rand(10 ** 15).to_s, rand(10 ** 15).to_s
+      phone2 = random_string
+      TextMagic::API.validate_phones(phone1, phone2).should == false
+      TextMagic::API.validate_phones([phone1, phone2]).should == false
+    end
+  end
+end

data/textmagic.gemspec

@@ -2,11 +2,11 @@
 
 Gem::Specification.new do |s|
   s.name = %q{textmagic}
-  s.version = "0.1.0"
+  s.version = "0.2.0"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Vladimir Bobes Tuzinsky"]
-  s.date = %q{2009-05-22}
+  s.date = %q{2009-05-25}
   s.email = %q{vladimir.tuzinsky@gmail.com}
   s.extra_rdoc_files = [
     "LICENSE",
@@ -20,13 +20,19 @@ Gem::Specification.new do |s|
      "Rakefile",
      "VERSION.yml",
      "lib/api.rb",
+     "lib/charset.rb",
      "lib/error.rb",
      "lib/executor.rb",
+     "lib/response.rb",
      "lib/textmagic.rb",
+     "lib/validation.rb",
      "test/test_api.rb",
+     "test/test_charset.rb",
+     "test/test_error.rb",
      "test/test_executor.rb",
      "test/test_helper.rb",
-     "test/test_textmagic.rb",
+     "test/test_response.rb",
+     "test/test_validation.rb",
      "textmagic.gemspec"
   ]
   s.has_rdoc = true
@@ -38,9 +44,12 @@ Gem::Specification.new do |s|
   s.summary = %q{Ruby interface to the TextMagic's SMS gateway}
   s.test_files = [
     "test/test_api.rb",
+     "test/test_charset.rb",
+     "test/test_error.rb",
      "test/test_executor.rb",
      "test/test_helper.rb",
-     "test/test_textmagic.rb"
+     "test/test_response.rb",
+     "test/test_validation.rb"
   ]
 
   if s.respond_to? :specification_version then

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: bobes-textmagic
 version: !ruby/object:Gem::Version 
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors: 
 - Vladimir Bobes Tuzinsky
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-05-22 00:00:00 -07:00
+date: 2009-05-25 00:00:00 -07:00
 default_executable: 
 dependencies: []
 
@@ -30,13 +30,19 @@ files:
 - Rakefile
 - VERSION.yml
 - lib/api.rb
+- lib/charset.rb
 - lib/error.rb
 - lib/executor.rb
+- lib/response.rb
 - lib/textmagic.rb
+- lib/validation.rb
 - test/test_api.rb
+- test/test_charset.rb
+- test/test_error.rb
 - test/test_executor.rb
 - test/test_helper.rb
-- test/test_textmagic.rb
+- test/test_response.rb
+- test/test_validation.rb
 - textmagic.gemspec
 has_rdoc: true
 homepage: http://github.com/bobes/textmagic
@@ -66,6 +72,9 @@ specification_version: 2
 summary: Ruby interface to the TextMagic's SMS gateway
 test_files: 
 - test/test_api.rb
+- test/test_charset.rb
+- test/test_error.rb
 - test/test_executor.rb
 - test/test_helper.rb
-- test/test_textmagic.rb
+- test/test_response.rb
+- test/test_validation.rb

data/test/test_textmagic.rb

@@ -1,4 +0,0 @@
-require 'test_helper'
-
-# class TextmagicTest < Test::Unit::TestCase
-# end