bobes-textmagic 0.2.3 → 0.3.0

data/README.rdoc

@@ -1,18 +1,21 @@
 = TextMagic
 
-Code[http://github.com/bobes/textmagic]
-|
-RDoc[http://textmagic.rubyforge.org]
++textmagic+ gem is a Ruby interface to the TextMagic's Bulk SMS Gateway.
+It can be used to easily integrate SMS features into your application.
+It supports sending messages, receiving replies and more. You need to have
+a valid TextMagic[http://www.textmagic.com] account to use this gem. You can
+get one at http://www.textmagic.com.
+
+To learn more about the TextMagic's Bulk
+SMS Gateway, visit the official {API documentation}[http://api.textmagic.com]
+or {Google group}[http://groups.google.com/group/textmagic-api].
+
+Links:
+Code[http://github.com/bobes/textmagic/tree/master]
 |
-Forum[http://groups.google.com/group/textmagic-api]
+Doc[http://bobes.github.com/textmagic/rdoc]
 |
-Issues[http://github.com/bobes/textmagic/issues]
-
-+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.
+Blame[http://bobes.github.com]
 
 
 == Installation
@@ -28,95 +31,105 @@ Use +sudo+ if required by your system.
 
 Start with requiring +textmagic+ library:
 
+  require 'rubygems'
   require 'textmagic'
 
-To create an API instance, run:
+Then create an API instance with your credentials:
 
   api = TextMagic::API.new(username, password)
 
-with your credentials. Created instance will remember the username and password
-and will use them in all requests to the SMS gateway.
+These credentials will be used in all requests to the SMS gateway.
 
 === Account balance
 
-To retrieve your account's balance, run:
+Check your account's balance:
 
   api.account.balance
   # => 314.15
 
+See TextMagic::API.account for more information on +account+ method.
+
 === Sending messages
 
 To send a message to a single phone number, run:
 
-  api.send 'Hi Vilma!', '999314159265'
+  api.send 'Hi Wilma!', '999314159265'
 
 You can even specify multiple phone numbers:
 
-  api.send 'Hi everybody!', '999314159265', '999271828182'
+  api.send 'Hello 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:
+Long messages will be split to up to 3 parts. To limit maximum number
+of parts, specify an optional +max_length+ parameter:
+
+  api.send 'Very very long message...', '999314159265', :max_length => 2
 
-  api.send 'Very long message...', '999314159265', :max_length => 2
+See TextMagic::API.send for more information on +send+ method.
 
 === Checking sent message status
 
 If you want to check sent message status, you have to use +message_id+
-returned in respose to +send+ command.
+returned in response to +send+ command.
 
-  api.send('Hi Vilma!', '999314159265').message_id
+  api.send('Hi Wilma!', '999314159265')
   # => '141421'
-  api.message_status('141421').status
+  status = api.message_status('141421')
   # => 'd'
+  status.completed_time
+  # => Fri May 22 10:10:18 +0200 2009
 
-You can also supply several message_ids, in which case you'll get a hash with
-message_ids as keys:
+You can also check statuses of several messages at once, in which case
+you'll get a hash with message ids as keys:
 
-  api.send('Hi Vilma!', '999314159265', '999271828182').message_ids
-  # => ['141421', '173205']
+  api.send('Hi Wilma!', '999314159265', '999271828182').message_id
+  # => { '999314159265' => '141421', '999271828182' => '173205' }
   statuses = api.message_status('141421', '173205')
-  statuses['141421'].status
-  # => 'r'
+  # => { '141421' => 'r', '173205' => 'd' }
+  statuses['173205'].created_time
+  # => Thu May 28 16:41:45 +0200 2009
+
+See TextMagic::API.message_status for more information on +message_status+ method.
+
+<b>It is strongly encouraged to setup callbacks to receive updates on message status
+instead of using this method.</b>
 
 === 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 = api.receive
+  # => ['999271828182: Hello Fred!', '999314159265: Good day!']
   replies.first.text
-  # => 'Hi Fred!'
+  # => 'Hello Fred!'
+  replies.last.from
+  # => '999314159265'
+  replies.last.message_id
+  # => '223606'
 
 To prevent receiving old replies again, supply +last_retrieved_id+ argument:
 
-  replies = api.receive('1780826').messages
+  api.receive('178082')
   # => []
 
-=== Deleting retrieved replies
+See TextMagic::API.receive for more information on +message_status+ method.
 
-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'
+<b>It is strongly encouraged to setup callbacks to receive replies instead of
+using this method.</b>
 
+=== Deleting retrieved replies
 
-== Links
+After you retrieve replies, you can delete them from server by running:
 
-The code is hosted at GitHub[http://github.com/bobes/textmagic] and released to
-RubyForge[http://rubyforge.org/projects/textmagic].
-You can find documentation for the gem at project's homepage[http://textmagic.rubyforge.org]
-at RubyForge.
+  api.delete_reply '141421', '178082'
+  # => true
 
-For general information on TextMagic's Bulk SMS Gateway, visit the
-official API documentation[http://api.textmagic.com] or
-Google group[http://groups.google.com/group/textmagic-api].
+See TextMagic::API.delete_reply for more information on +message_status+ method.
 
 
 == Copyright
 
-Copyright (c) 2009 Vladimir Bobes Tuzinsky. See LICENSE for details.
+Copyright (c) 2009 Vladimír Bobeš Tužinský. See LICENSE for details.

data/Rakefile

@@ -1,5 +1,6 @@
 require 'rubygems'
 require 'rake'
+require 'sdoc'
 
 begin
   require 'jeweler'
@@ -57,4 +58,35 @@ Rake::RDocTask.new do |rdoc|
   rdoc.title = "textmagic #{version}"
   rdoc.rdoc_files.include('README*')
   rdoc.rdoc_files.include('lib/**/*.rb')
+  rdoc.options << '--charset' << 'utf8'
+  rdoc.options << '--fmt' << 'shtml'
+  rdoc.template = 'direct'
+end
+
+desc "Build, commit and publish the RDOC files"
+task :doc => :rerdoc do
+  cmd = <<-EOS
+  echo 'Packing and deleting rdoc directory'
+  tar -cf rdoc.tar rdoc
+  rm -rf rdoc
+  echo 'Checking out gh-pages branch'
+  git checkout -m gh-pages
+  echo 'Replacing rdoc directory'
+  rm -rf rdoc
+  tar -xf rdoc.tar
+  rm rdoc.tar
+  echo 'Commiting'
+  git add rdoc
+  git commit -m 'Updated RDoc'
+  echo 'Pushing to origin'
+  git push origin gh-pages
+  EOS
+
+  system cmd.split(/\n\s*/).join(' && ')
+
+  system <<-EOS
+  echo 'Checking out master'
+  git checkout master
+  echo 'Done'
+  EOS
 end

data/VERSION.yml

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

data/lib/api.rb

@@ -6,68 +6,70 @@ module TextMagic
     extend Validation
 
     # Creates new API instance with specified credentials. These will be
-    # used in all requests to the TextMagic's HTTP gateway done through
+    # used in all requests to the TextMagic SMS 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')
+    #   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.
+    # Executes an account command by sending a request to the TextMagic's
+    # SMS gateway.
     #
-    # Example usage:
-    #
-    #  api.account
-    #  # => { 'balance' => 314.15 }
+    # This method returns an object with balance attribute.
+    # In case the request to the SMS gateway is not successful or the server
+    # returns an error response, an Error is raised.
     #
-    # Using custom reader:
+    # Example usage:
     #
     #  api.account.balance
     #  # => 314.15
     def account
-      response = Executor.execute('account', @username, @password)
-      response.extend(TextMagic::API::Response::Account)
+      hash = Executor.execute('account', @username, @password)
+      TextMagic::API::Response.account(hash)
     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 methods 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.
+    # Executes a send command by sending a request to the TextMagic's
+    # SMS gateway.
+    #
+    # If called with a single phone number, this method returns a string message id.
+    # If called with multiple phone numbers, it will return an hash of message ids
+    # with phone numbers as keys.
+    # In both cases the returned object is extended with +sent_text+ and +parts_count+
+    # attributes.
+    # In case the request to the SMS gateway is not successful or the server returns
+    # an error response, an Error is raised.
+    #
+    # The optional parameters you can specify in the options Hash are:
+    # * +unicode+: accepted values are +true+, +false+, +0+ and +1+. If not specified,
+    #   the method will determine the unicode value based on the characters in
+    #   the text.
+    # * +max_length+: accepted values are +nil+, +1+, +2+ and +3+, defaults to nil.
+    #   If not specified, the SMS gateway will apply its own default value.
     #
     # 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['999314159265']
+    #  api.send('Hi Wilma', '999314159265')
     #  # => '141421'
+    #  response = api.send('Hello everybody', '999314159265', '999271828182', :max_length => 2)
+    #  # => { '999314159265' => '141421', '999271828182' => '173205' }
     #  response.parts_count
     #  # => 1
+    #
+    # Multiple phone numbers can be supplied as an array or as a list of arguments:
+    #
+    #  api.send('Hello everybody', ['999314159265', '999271828182'])
+    #  api.send('Hello everybody', '999314159265', '999271828182')
+    #
+    # If you want to send a message to a single phone number but still
+    # want to get a hash response, put the phone number in an array:
+    #
+    #  api.send('Hi Barney', ['999271828182'])
     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 : {}
@@ -80,99 +82,111 @@ module TextMagic
       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)
+      single = args.size == 1 && args.first.is_a?(String)
       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)
-      response
+      hash = Executor.execute('send', @username, @password, options.merge(:text => text, :phone => phones.join(',')))
+      TextMagic::API::Response.send(hash, single)
     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 methods defined
-    # in Response module.
+    # Executes a message_status command by sending a request to the TextMagic's
+    # SMS gateway.
     #
-    # This method accepts any positive number of ids specified as an array
-    # or as a list of arguments
+    # If called with a single +id+, this method returns a single string value
+    # denoting the message status. This string is extended with custom attributes
+    # +text+, +status+, +created_time+, +completed_time+, +reply_number+ and
+    # +credits_cost+. If called with multiple ids, it returns a hash of such
+    # strings with message ids as keys.
+    # In case the request to the SMS gateway is not successful or the server returns
+    # an error response, an Error is raised.
     #
     # 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
+    #  status = api.message_status('141421')
     #  # => 'd'
-    #  response['141421'].created_time
+    #  status.completed_time
     #  # => Fri May 22 10:10:18 +0200 2009
+    #
+    # Example with multiple ids:
+    #
+    #  statuses = api.message_status('141421', '173205')
+    #  # => { '141421' => 'r', '173205' => 'd' }
+    #  statuses['141421'].text
+    #  # => 'Hi Wilma'
+    #  statuses['173205'].created_time
+    #  # => Thu May 28 16:41:45 +0200 2009
+    #
+    # Multiple ids can be supplied as an array or as a list of arguments:
+    #
+    #  api.send('Hello everybody', ['999314159265', '999271828182'])
+    #  api.send('Hello everybody', '999314159265', '999271828182')
+    #
+    # If you want to request status for a single message but still want to get
+    # a hash response, put the id in an array:
+    #
+    #  api.message_status(['141421'])
+    #
+    # <b>It is strongly encouraged to setup callbacks to receive updates on message status
+    # instead of using this method.</b>
     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
+      hash = Executor.execute('message_status', @username, @password, :ids => ids.join(','))
+      TextMagic::API::Response.message_status(hash, single)
     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 methods defined
-    # in Response module.
+    # Executes a receive command by sending a request to the TextMagic's
+    # SMS gateway.
     #
-    # This method accepts an optional +last_retrieved_id+ value.
+    # This method returnes an array with retrieved messages. Every member of
+    # the array is a string with +from+, +text+, +timestamp+ and +message_id+
+    # attributes. The value of every string contains a phone number and text.
+    # In case the request to the SMS gateway is not successful or the server returns
+    # an error response, an Error is raised.
     #
-    # 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'
+    # This method accepts an optional +last_retrieved_id+ value. If called
+    # with this argument, the gateway will only return replies newer than the
+    # one with specified id.
     #
-    # Using custom readers:
+    # Example usage:
     #
-    #  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
+    #  replies = api.receive
+    #  # => ['999271828182: Hello Fred', '999314159265: Good day']
+    #  replies.first.text
+    #  # => 'Hello Fred'
+    #  replies.first.from
+    #  # => '999314159265'
+    #  replies.last.message_id
+    #  # => '223606'
+    #  api.receive '223606'
+    #  # => []
+    #
+    # <b>It is strongly encouraged to setup callbacks to receive replies instead of
+    # using this method.</b>
     def receive(last_retrieved_id = nil)
-      response = Executor.execute('receive', @username, @password, :last_retrieved_id => last_retrieved_id)
-      response.extend(TextMagic::API::Response::Receive)
+      hash = Executor.execute('receive', @username, @password, :last_retrieved_id => last_retrieved_id)
+      TextMagic::API::Response.receive(hash)
     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 methods defined
-    # in Response module.
+    # Executes a delete_reply command by sending a request to the TextMagic's
+    # SMS gateway.
     #
-    # This method accepts any positive number of ids specified as an array
-    # or as a list of arguments.
+    # This method always returns true.
+    # In case the request to the SMS gateway is not successful or the server returns
+    # an error response, an Error is raised.
     #
     # 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']
+    #  api.delete_reply('173205', '223606')
+    #  api.delete_reply(['244948', '264575'])
     def delete_reply(*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('delete_reply', @username, @password, :ids => ids.join(','))
-      response.extend(TextMagic::API::Response::DeleteReply)
+      Executor.execute('delete_reply', @username, @password, :ids => ids.join(','))
+      true
     end
   end
 end