textmagic 0.2.0 → 0.2.1

data/README.rdoc

@@ -1,8 +1,10 @@
 = 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.
++textmagic+ gem is a Ruby interface to the TextMagic's Bulk SMS Gateway.
+It can be used to send SMS messages and receive replies, check statuses
+of sent messages and retrieve account balance.
+You need to have a valid TextMagic[http://www.textmagic.com] account to use this gem. Sign up at
+http://www.textmagic.com to get one.
 
 == Installation
 
@@ -20,20 +22,74 @@ 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.
+and will use them in all requests to the SMS gateway.
+
+=== Account balance
 
 To retrieve your account's balance, run:
 
   api.account.balance
+  # => 314.15
+
+=== Sending messages
 
-To send a text message, run:
+To send a message to a single phone number, run:
 
-  api.send 'Hi Vilma!', '441234567890'
+  api.send 'Hi Vilma!', '999314159265'
 
 You can even specify multiple phone numbers:
 
-  api.send 'Hi Vilma!', '314159265358', '271828182845'
+  api.send 'Hi everybody!', '999314159265', '999271828182'
+
+Unicode messages are supported as well:
+
+  api.send 'Вильма Привет!', '999314159265'
+
+Long messages will be split to up to 3 parts. If you want to limit maximum number
+of parts, you can specify an optional +max_length+ parameter:
+
+  api.send 'Very long message...', '999314159265', :max_length => 2
+
+=== Checking sent message status
+
+If you want to check sent message status, you have to use +message_id+
+returned in respose to +send+ command.
+
+  api.send('Hi Vilma!', '999314159265').message_id
+  # => '141421'
+  api.message_status('141421').status
+  # => 'd'
+
+You can also supply several message_ids, in which case you'll get a hash with
+message_ids as keys:
+
+  api.send('Hi Vilma!', '999314159265', '999271828182').message_ids
+  # => ['141421', '173205']
+  statuses = api.message_status('141421', '173205')
+  statuses['141421'].status
+  # => 'r'
+
+=== Receiving replies
+
+To receive all available replies, run:
+
+  replies = api.receive.messages
+  # => [{ 'timestamp' => Fri May 22 12:12:55 +0200 2009, 'from' => '999314159265', 'text' => 'Hi Fred!', 'message_id' => '1780826' }]
+  replies.first.text
+  # => 'Hi Fred!'
+
+To prevent receiving old replies again, supply +last_retrieved_id+ argument:
+
+  replies = api.receive('1780826').messages
+  # => []
+
+=== Deleting retrieved replies
+
+After you retrieve replies, you can delete them from server by running:
 
+  message_ids = api.receive.message_ids
+  # => ['141421', '1780826']
+  api.delete_reply '141421', '1780826'
 
 == Copyright
 

data/VERSION.yml

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

data/lib/api.rb

@@ -88,6 +88,7 @@ module TextMagic
       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)
+      response
     end
 
     # Executes a message_status command and returns a hash with states of
@@ -116,10 +117,12 @@ module TextMagic
     #  response['141421'].created_time
     #  # => Fri May 22 10:10:18 +0200 2009
     def message_status(*ids)
+      single = ids.size == 1 && ids.first.is_a?(String)
       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)
+      single ? response[ids.first] : response
     end
 
     # Executes a receive command and returns a hash with unread messages

data/lib/response.rb

@@ -58,12 +58,12 @@ module TextMagic
       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']
+          return unless base.is_a?(Hash) && base['message_id']
+          base['message_ids'] = base['message_id'].keys.sort
+          base.merge! base.delete('message_id').invert
         end
 
-        %w(message_id_hash message_ids sent_text parts_count).each do |method|
+        %w(message_ids sent_text parts_count).each do |method|
           module_eval <<-EOS
           def #{method}
             self['#{method}']
@@ -72,7 +72,7 @@ module TextMagic
         end
 
         def message_id(phone = nil)
-          phone ? message_id_hash[phone] : message_ids.first
+          phone ? self[phone] : self['message_ids'].first
         end
       end
 
@@ -104,13 +104,14 @@ module TextMagic
 
         def self.extended(base)
           return unless base.is_a?(Hash) && base['messages']
+          base['message_ids'] = base['messages'].collect { |message| message['message_id'] }.sort
           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|
+        %w(messages message_ids unread).each do |method|
           module_eval <<-EOS, __FILE__, __LINE__ + 1
           def #{method}
             self['#{method}']

data/test/test_api.rb

@@ -111,12 +111,12 @@ class APITest < Test::Unit::TestCase
       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
+    should 'return a hash with 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['sent_text'].should == @text
       response['parts_count'].should == 1
     end
   end
@@ -126,12 +126,15 @@ class APITest < Test::Unit::TestCase
     setup do
       @username, @password = random_string, random_string
       @api = TextMagic::API.new(@username, @password)
+      @id = random_string
+      @status = { 'text' => 'Hi Vilma', 'status' => 'd' , 'created_time' => Time.now.to_i, 'reply_number' => '447624800500', 'completed_time' => nil, 'credits_cost' => 0.5 }
+      @response = { @id => @status }
+      TextMagic::API::Executor.stubs(:execute)
     end
 
     should 'call Executor execute with correct arguments' do
-      id = random_string
-      TextMagic::API::Executor.expects(:execute).with('message_status', @username, @password, :ids => id)
-      @api.message_status(id)
+      TextMagic::API::Executor.expects(:execute).with('message_status', @username, @password, :ids => @id).returns(@response)
+      @api.message_status(@id)
     end
 
     should 'join ids supplied as array' do
@@ -151,17 +154,43 @@ class APITest < Test::Unit::TestCase
       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)
+    should 'return a hash extended with TextMagic::API::Response::MessageStatus for an array of ids' do
+      TextMagic::API::Executor.expects(:execute).returns(@response)
+      response = @api.message_status([@id])
       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(random_string)
-      response['8659912'].should == {}
+    should 'return a hash with message ids as keys for an array of ids' do
+      TextMagic::API::Executor.expects(:execute).returns(@response)
+      response = @api.message_status([@id])
+      response[@id].should == @status
+    end
+
+    should 'return a hash extended with TextMagic::API::Response::MessageStatus for a list of ids' do
+      TextMagic::API::Executor.expects(:execute).returns(@response)
+      response = @api.message_status(@id, 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 for a list of ids' do
+      TextMagic::API::Executor.expects(:execute).returns(@response)
+      response = @api.message_status(@id, random_string)
+      response[@id].should == @status
+    end
+
+    should 'return a hash extended with TextMagic::API::Response::MessageStatus::Status for a single id' do
+      TextMagic::API::Executor.expects(:execute).returns(@response)
+      response = @api.message_status(@id)
+      response.class.should == Hash
+      response.is_a?(TextMagic::API::Response::MessageStatus::Status).should == true
+    end
+
+    should 'return a hash with message ids as keys for a single id' do
+      TextMagic::API::Executor.expects(:execute).returns(@response)
+      response = @api.message_status(@id)
+      response.should == @status
     end
   end
 

data/test/test_response.rb

@@ -32,17 +32,13 @@ class ResponseTest < Test::Unit::TestCase
       @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'
+      @response['999314159265'].should == '141421'
+      @response['999271828182'].should == '173205'
     end
 
     should 'allow access to sent_text' do
@@ -144,6 +140,10 @@ class ResponseTest < Test::Unit::TestCase
       @response.messages.should == @messages
     end
 
+    should 'allow access to message_ids array' do
+      @response.message_ids.should == ['141421', '173205']
+    end
+
     should 'allow access to message_id for all messages' do
       @response.messages.first.message_id.should == '141421'
     end

data/textmagic.gemspec

@@ -2,7 +2,7 @@
 
 Gem::Specification.new do |s|
   s.name = %q{textmagic}
-  s.version = "0.2.0"
+  s.version = "0.2.1"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Vladimir Bobes Tuzinsky"]

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: textmagic
 version: !ruby/object:Gem::Version 
-  version: 0.2.0
+  version: 0.2.1
 platform: ruby
 authors: 
 - Vladimir Bobes Tuzinsky