bobes-textmagic 0.2.3 → 0.3.0

Sign up to get free protection for your applications and to get access to all the features.
data/README.rdoc CHANGED
@@ -1,18 +1,21 @@
1
1
  = TextMagic
2
2
 
3
- Code[http://github.com/bobes/textmagic]
4
- |
5
- RDoc[http://textmagic.rubyforge.org]
3
+ +textmagic+ gem is a Ruby interface to the TextMagic's Bulk SMS Gateway.
4
+ It can be used to easily integrate SMS features into your application.
5
+ It supports sending messages, receiving replies and more. You need to have
6
+ a valid TextMagic[http://www.textmagic.com] account to use this gem. You can
7
+ get one at http://www.textmagic.com.
8
+
9
+ To learn more about the TextMagic's Bulk
10
+ SMS Gateway, visit the official {API documentation}[http://api.textmagic.com]
11
+ or {Google group}[http://groups.google.com/group/textmagic-api].
12
+
13
+ Links:
14
+ Code[http://github.com/bobes/textmagic/tree/master]
6
15
  |
7
- Forum[http://groups.google.com/group/textmagic-api]
16
+ Doc[http://bobes.github.com/textmagic/rdoc]
8
17
  |
9
- Issues[http://github.com/bobes/textmagic/issues]
10
-
11
- +textmagic+ gem is a Ruby interface to the TextMagic's Bulk SMS Gateway.
12
- It can be used to send SMS messages and receive replies, check statuses
13
- of sent messages and retrieve account balance.
14
- You need to have a valid TextMagic[http://www.textmagic.com] account to use this gem. Sign up at
15
- http://www.textmagic.com to get one.
18
+ Blame[http://bobes.github.com]
16
19
 
17
20
 
18
21
  == Installation
@@ -28,95 +31,105 @@ Use +sudo+ if required by your system.
28
31
 
29
32
  Start with requiring +textmagic+ library:
30
33
 
34
+ require 'rubygems'
31
35
  require 'textmagic'
32
36
 
33
- To create an API instance, run:
37
+ Then create an API instance with your credentials:
34
38
 
35
39
  api = TextMagic::API.new(username, password)
36
40
 
37
- with your credentials. Created instance will remember the username and password
38
- and will use them in all requests to the SMS gateway.
41
+ These credentials will be used in all requests to the SMS gateway.
39
42
 
40
43
  === Account balance
41
44
 
42
- To retrieve your account's balance, run:
45
+ Check your account's balance:
43
46
 
44
47
  api.account.balance
45
48
  # => 314.15
46
49
 
50
+ See TextMagic::API.account for more information on +account+ method.
51
+
47
52
  === Sending messages
48
53
 
49
54
  To send a message to a single phone number, run:
50
55
 
51
- api.send 'Hi Vilma!', '999314159265'
56
+ api.send 'Hi Wilma!', '999314159265'
52
57
 
53
58
  You can even specify multiple phone numbers:
54
59
 
55
- api.send 'Hi everybody!', '999314159265', '999271828182'
60
+ api.send 'Hello everybody', '999314159265', '999271828182'
56
61
 
57
62
  Unicode messages are supported as well:
58
63
 
59
64
  api.send 'Вильма Привет!', '999314159265'
60
65
 
61
- Long messages will be split to up to 3 parts. If you want to limit maximum number
62
- of parts, you can specify an optional +max_length+ parameter:
66
+ Long messages will be split to up to 3 parts. To limit maximum number
67
+ of parts, specify an optional +max_length+ parameter:
68
+
69
+ api.send 'Very very long message...', '999314159265', :max_length => 2
63
70
 
64
- api.send 'Very long message...', '999314159265', :max_length => 2
71
+ See TextMagic::API.send for more information on +send+ method.
65
72
 
66
73
  === Checking sent message status
67
74
 
68
75
  If you want to check sent message status, you have to use +message_id+
69
- returned in respose to +send+ command.
76
+ returned in response to +send+ command.
70
77
 
71
- api.send('Hi Vilma!', '999314159265').message_id
78
+ api.send('Hi Wilma!', '999314159265')
72
79
  # => '141421'
73
- api.message_status('141421').status
80
+ status = api.message_status('141421')
74
81
  # => 'd'
82
+ status.completed_time
83
+ # => Fri May 22 10:10:18 +0200 2009
75
84
 
76
- You can also supply several message_ids, in which case you'll get a hash with
77
- message_ids as keys:
85
+ You can also check statuses of several messages at once, in which case
86
+ you'll get a hash with message ids as keys:
78
87
 
79
- api.send('Hi Vilma!', '999314159265', '999271828182').message_ids
80
- # => ['141421', '173205']
88
+ api.send('Hi Wilma!', '999314159265', '999271828182').message_id
89
+ # => { '999314159265' => '141421', '999271828182' => '173205' }
81
90
  statuses = api.message_status('141421', '173205')
82
- statuses['141421'].status
83
- # => 'r'
91
+ # => { '141421' => 'r', '173205' => 'd' }
92
+ statuses['173205'].created_time
93
+ # => Thu May 28 16:41:45 +0200 2009
94
+
95
+ See TextMagic::API.message_status for more information on +message_status+ method.
96
+
97
+ <b>It is strongly encouraged to setup callbacks to receive updates on message status
98
+ instead of using this method.</b>
84
99
 
85
100
  === Receiving replies
86
101
 
87
102
  To receive all available replies, run:
88
103
 
89
- replies = api.receive.messages
90
- # => [{ 'timestamp' => Fri May 22 12:12:55 +0200 2009, 'from' => '999314159265', 'text' => 'Hi Fred!', 'message_id' => '1780826' }]
104
+ replies = api.receive
105
+ # => ['999271828182: Hello Fred!', '999314159265: Good day!']
91
106
  replies.first.text
92
- # => 'Hi Fred!'
107
+ # => 'Hello Fred!'
108
+ replies.last.from
109
+ # => '999314159265'
110
+ replies.last.message_id
111
+ # => '223606'
93
112
 
94
113
  To prevent receiving old replies again, supply +last_retrieved_id+ argument:
95
114
 
96
- replies = api.receive('1780826').messages
115
+ api.receive('178082')
97
116
  # => []
98
117
 
99
- === Deleting retrieved replies
118
+ See TextMagic::API.receive for more information on +message_status+ method.
100
119
 
101
- After you retrieve replies, you can delete them from server by running:
102
-
103
- message_ids = api.receive.message_ids
104
- # => ['141421', '1780826']
105
- api.delete_reply '141421', '1780826'
120
+ <b>It is strongly encouraged to setup callbacks to receive replies instead of
121
+ using this method.</b>
106
122
 
123
+ === Deleting retrieved replies
107
124
 
108
- == Links
125
+ After you retrieve replies, you can delete them from server by running:
109
126
 
110
- The code is hosted at GitHub[http://github.com/bobes/textmagic] and released to
111
- RubyForge[http://rubyforge.org/projects/textmagic].
112
- You can find documentation for the gem at project's homepage[http://textmagic.rubyforge.org]
113
- at RubyForge.
127
+ api.delete_reply '141421', '178082'
128
+ # => true
114
129
 
115
- For general information on TextMagic's Bulk SMS Gateway, visit the
116
- official API documentation[http://api.textmagic.com] or
117
- Google group[http://groups.google.com/group/textmagic-api].
130
+ See TextMagic::API.delete_reply for more information on +message_status+ method.
118
131
 
119
132
 
120
133
  == Copyright
121
134
 
122
- Copyright (c) 2009 Vladimir Bobes Tuzinsky. See LICENSE for details.
135
+ Copyright (c) 2009 Vladimír Bobeš Tužinský. See LICENSE for details.
data/Rakefile CHANGED
@@ -1,5 +1,6 @@
1
1
  require 'rubygems'
2
2
  require 'rake'
3
+ require 'sdoc'
3
4
 
4
5
  begin
5
6
  require 'jeweler'
@@ -57,4 +58,35 @@ Rake::RDocTask.new do |rdoc|
57
58
  rdoc.title = "textmagic #{version}"
58
59
  rdoc.rdoc_files.include('README*')
59
60
  rdoc.rdoc_files.include('lib/**/*.rb')
61
+ rdoc.options << '--charset' << 'utf8'
62
+ rdoc.options << '--fmt' << 'shtml'
63
+ rdoc.template = 'direct'
64
+ end
65
+
66
+ desc "Build, commit and publish the RDOC files"
67
+ task :doc => :rerdoc do
68
+ cmd = <<-EOS
69
+ echo 'Packing and deleting rdoc directory'
70
+ tar -cf rdoc.tar rdoc
71
+ rm -rf rdoc
72
+ echo 'Checking out gh-pages branch'
73
+ git checkout -m gh-pages
74
+ echo 'Replacing rdoc directory'
75
+ rm -rf rdoc
76
+ tar -xf rdoc.tar
77
+ rm rdoc.tar
78
+ echo 'Commiting'
79
+ git add rdoc
80
+ git commit -m 'Updated RDoc'
81
+ echo 'Pushing to origin'
82
+ git push origin gh-pages
83
+ EOS
84
+
85
+ system cmd.split(/\n\s*/).join(' && ')
86
+
87
+ system <<-EOS
88
+ echo 'Checking out master'
89
+ git checkout master
90
+ echo 'Done'
91
+ EOS
60
92
  end
data/VERSION.yml CHANGED
@@ -1,4 +1,4 @@
1
1
  ---
2
2
  :major: 0
3
- :minor: 2
4
- :patch: 3
3
+ :minor: 3
4
+ :patch: 0
data/lib/api.rb CHANGED
@@ -6,68 +6,70 @@ module TextMagic
6
6
  extend Validation
7
7
 
8
8
  # Creates new API instance with specified credentials. These will be
9
- # used in all requests to the TextMagic's HTTP gateway done through
9
+ # used in all requests to the TextMagic SMS gateway done through
10
10
  # this instance. Multiple instances with different credentials can
11
11
  # be used at the same time.
12
12
  #
13
13
  # Example usage:
14
14
  #
15
- # api = TextMagic::API.new('fred', 'secret')
15
+ # api = TextMagic::API.new('fred', 'secret')
16
16
  def initialize(username, password)
17
17
  @username = username
18
18
  @password = password
19
19
  end
20
20
 
21
- # Executes an account command and returns a hash with account's balance
22
- # if successful, otherwise it raises an Error.
23
- # The returned hash will be extended with custom reader method defined
24
- # in Response module.
21
+ # Executes an account command by sending a request to the TextMagic's
22
+ # SMS gateway.
25
23
  #
26
- # Example usage:
27
- #
28
- # api.account
29
- # # => { 'balance' => 314.15 }
24
+ # This method returns an object with balance attribute.
25
+ # In case the request to the SMS gateway is not successful or the server
26
+ # returns an error response, an Error is raised.
30
27
  #
31
- # Using custom reader:
28
+ # Example usage:
32
29
  #
33
30
  # api.account.balance
34
31
  # # => 314.15
35
32
  def account
36
- response = Executor.execute('account', @username, @password)
37
- response.extend(TextMagic::API::Response::Account)
33
+ hash = Executor.execute('account', @username, @password)
34
+ TextMagic::API::Response.account(hash)
38
35
  end
39
36
 
40
- # Executes a send command and returns a hash with message ids, sent text and
41
- # number of parts if successful, otherwise it raises an Error.
42
- # The returned hash will be extended with custom reader methods defined
43
- # in Response module.
44
- #
45
- # This method accepts any positive number of phone numbers and an additional
46
- # options hash.
47
- #
48
- # The optional parameters you can specify in the options hash are:
49
- # * +unicode+: accepted values are true, false, 0 and 1
50
- # * +max_length+: accepted values are nil, 1, 2 and 3, defaults to nil
51
- # If not specified, the method will determine the unicode value based on the
52
- # characters in the text.
37
+ # Executes a send command by sending a request to the TextMagic's
38
+ # SMS gateway.
39
+ #
40
+ # If called with a single phone number, this method returns a string message id.
41
+ # If called with multiple phone numbers, it will return an hash of message ids
42
+ # with phone numbers as keys.
43
+ # In both cases the returned object is extended with +sent_text+ and +parts_count+
44
+ # attributes.
45
+ # In case the request to the SMS gateway is not successful or the server returns
46
+ # an error response, an Error is raised.
47
+ #
48
+ # The optional parameters you can specify in the options Hash are:
49
+ # * +unicode+: accepted values are +true+, +false+, +0+ and +1+. If not specified,
50
+ # the method will determine the unicode value based on the characters in
51
+ # the text.
52
+ # * +max_length+: accepted values are +nil+, +1+, +2+ and +3+, defaults to nil.
53
+ # If not specified, the SMS gateway will apply its own default value.
53
54
  #
54
55
  # Example usage:
55
56
  #
56
- # api.send('Hi Vilma', '999314159265')
57
- # # => { 'message_ids' => [141421], 'message_id_hash' => { '999314159265' => '141421' }, 'sent_text' => 'Hi Vilma', 'parts_count' => 1 }
58
- # api.send(text, phone, :unicode => true)
59
- # api.send(text, phone1, phone2, :max_length => 2)
60
- # api.send(text, [phone1, phone2])
61
- #
62
- # Using custom readers:
63
- #
64
- # response = api.send('Hi Vilma', '999314159265', '999271828182')
65
- # response.message_ids
66
- # # => ['141421', '173205']
67
- # response['999314159265']
57
+ # api.send('Hi Wilma', '999314159265')
68
58
  # # => '141421'
59
+ # response = api.send('Hello everybody', '999314159265', '999271828182', :max_length => 2)
60
+ # # => { '999314159265' => '141421', '999271828182' => '173205' }
69
61
  # response.parts_count
70
62
  # # => 1
63
+ #
64
+ # Multiple phone numbers can be supplied as an array or as a list of arguments:
65
+ #
66
+ # api.send('Hello everybody', ['999314159265', '999271828182'])
67
+ # api.send('Hello everybody', '999314159265', '999271828182')
68
+ #
69
+ # If you want to send a message to a single phone number but still
70
+ # want to get a hash response, put the phone number in an array:
71
+ #
72
+ # api.send('Hi Barney', ['999271828182'])
71
73
  def send(text, *args)
72
74
  raise Error.new(1, 'Message text is empty') if text.nil? || text.blank?
73
75
  options = args.last.is_a?(Hash) ? args.pop : {}
@@ -80,99 +82,111 @@ module TextMagic
80
82
  end
81
83
  raise Error.new(6, 'Message contains invalid characters') if unicode && options[:unicode] == 0
82
84
  raise Error.new(7, 'Message too long') unless API.validate_text_length(text, unicode)
85
+ single = args.size == 1 && args.first.is_a?(String)
83
86
  phones = args.flatten
84
87
  raise Error.new(9, 'Invalid phone number format') unless API.validate_phones(phones)
85
- response = Executor.execute('send', @username, @password, options.merge(:text => text, :phone => phones.join(',')))
86
- response.extend(TextMagic::API::Response::Send)
87
- response
88
+ hash = Executor.execute('send', @username, @password, options.merge(:text => text, :phone => phones.join(',')))
89
+ TextMagic::API::Response.send(hash, single)
88
90
  end
89
91
 
90
- # Executes a message_status command and returns a hash with states of
91
- # messages for specified ids if successful, otherwise it raises a
92
- # TextMagic::API::Error.
93
- # The returned hash will be extended with custom reader methods defined
94
- # in Response module.
92
+ # Executes a message_status command by sending a request to the TextMagic's
93
+ # SMS gateway.
95
94
  #
96
- # This method accepts any positive number of ids specified as an array
97
- # or as a list of arguments
95
+ # If called with a single +id+, this method returns a single string value
96
+ # denoting the message status. This string is extended with custom attributes
97
+ # +text+, +status+, +created_time+, +completed_time+, +reply_number+ and
98
+ # +credits_cost+. If called with multiple ids, it returns a hash of such
99
+ # strings with message ids as keys.
100
+ # In case the request to the SMS gateway is not successful or the server returns
101
+ # an error response, an Error is raised.
98
102
  #
99
103
  # Example usage:
100
104
  #
101
- # api.message_status('141421')
102
- # # => { '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 } }
103
- # api.message_status('141421', '173205')
104
- # api.message_status(['141421', '173205'])
105
- #
106
- # Using custom readers:
107
- #
108
- # response = api.message_status('141421', '173205')
109
- # response['141421'].text
110
- # # => 'Hi Vilma'
111
- # response['141421'].status
105
+ # status = api.message_status('141421')
112
106
  # # => 'd'
113
- # response['141421'].created_time
107
+ # status.completed_time
114
108
  # # => Fri May 22 10:10:18 +0200 2009
109
+ #
110
+ # Example with multiple ids:
111
+ #
112
+ # statuses = api.message_status('141421', '173205')
113
+ # # => { '141421' => 'r', '173205' => 'd' }
114
+ # statuses['141421'].text
115
+ # # => 'Hi Wilma'
116
+ # statuses['173205'].created_time
117
+ # # => Thu May 28 16:41:45 +0200 2009
118
+ #
119
+ # Multiple ids can be supplied as an array or as a list of arguments:
120
+ #
121
+ # api.send('Hello everybody', ['999314159265', '999271828182'])
122
+ # api.send('Hello everybody', '999314159265', '999271828182')
123
+ #
124
+ # If you want to request status for a single message but still want to get
125
+ # a hash response, put the id in an array:
126
+ #
127
+ # api.message_status(['141421'])
128
+ #
129
+ # <b>It is strongly encouraged to setup callbacks to receive updates on message status
130
+ # instead of using this method.</b>
115
131
  def message_status(*ids)
116
132
  single = ids.size == 1 && ids.first.is_a?(String)
117
133
  ids.flatten!
118
134
  raise TextMagic::API::Error.new(4, 'Insufficient parameters') if ids.empty?
119
- response = Executor.execute('message_status', @username, @password, :ids => ids.join(','))
120
- response.extend(TextMagic::API::Response::MessageStatus)
121
- single ? response[ids.first] : response
135
+ hash = Executor.execute('message_status', @username, @password, :ids => ids.join(','))
136
+ TextMagic::API::Response.message_status(hash, single)
122
137
  end
123
138
 
124
- # Executes a receive command and returns a hash with unread messages
125
- # if successful, otherwise it raises an Error.
126
- # The returned hash will be extended with custom reader methods defined
127
- # in Response module.
139
+ # Executes a receive command by sending a request to the TextMagic's
140
+ # SMS gateway.
128
141
  #
129
- # This method accepts an optional +last_retrieved_id+ value.
142
+ # This method returnes an array with retrieved messages. Every member of
143
+ # the array is a string with +from+, +text+, +timestamp+ and +message_id+
144
+ # attributes. The value of every string contains a phone number and text.
145
+ # In case the request to the SMS gateway is not successful or the server returns
146
+ # an error response, an Error is raised.
130
147
  #
131
- # Example usage:
132
- #
133
- # api.receive
134
- # # => { 'messages' => [{ 'message_id' => '141421', 'from' => '999314159265', 'timestamp' => Fri May 22 12:12:55 +0200 2009, 'text' => 'Hi Fred!' }], 'unread' => 0 }
135
- # api.receive '141421'
148
+ # This method accepts an optional +last_retrieved_id+ value. If called
149
+ # with this argument, the gateway will only return replies newer than the
150
+ # one with specified id.
136
151
  #
137
- # Using custom readers:
152
+ # Example usage:
138
153
  #
139
- # response = api.receive
140
- # response.messages
141
- # # => [{ 'timestamp' => Fri May 22 12:12:55 +0200 2009, 'from' => '999314159265', 'text' => 'Hi Fred', 'message_id' => '141421' }]
142
- # response.unread
143
- # # => 0
144
- # response.messages[0].timestamp
145
- # # => Fri May 22 12:12:55 +0200 2009
154
+ # replies = api.receive
155
+ # # => ['999271828182: Hello Fred', '999314159265: Good day']
156
+ # replies.first.text
157
+ # # => 'Hello Fred'
158
+ # replies.first.from
159
+ # # => '999314159265'
160
+ # replies.last.message_id
161
+ # # => '223606'
162
+ # api.receive '223606'
163
+ # # => []
164
+ #
165
+ # <b>It is strongly encouraged to setup callbacks to receive replies instead of
166
+ # using this method.</b>
146
167
  def receive(last_retrieved_id = nil)
147
- response = Executor.execute('receive', @username, @password, :last_retrieved_id => last_retrieved_id)
148
- response.extend(TextMagic::API::Response::Receive)
168
+ hash = Executor.execute('receive', @username, @password, :last_retrieved_id => last_retrieved_id)
169
+ TextMagic::API::Response.receive(hash)
149
170
  end
150
171
 
151
- # Executes a delete_reply command and returns a hash with a list of deleted
152
- # message ids if successful, otherwise it raises an Error.
153
- # The returned hash will be extended with custom reader methods defined
154
- # in Response module.
172
+ # Executes a delete_reply command by sending a request to the TextMagic's
173
+ # SMS gateway.
155
174
  #
156
- # This method accepts any positive number of ids specified as an array
157
- # or as a list of arguments.
175
+ # This method always returns true.
176
+ # In case the request to the SMS gateway is not successful or the server returns
177
+ # an error response, an Error is raised.
158
178
  #
159
179
  # Example usage:
160
180
  #
161
181
  # api.delete_reply('141421')
162
- # # => { 'deleted' => ['141421'] }
163
- # api.delete_reply('141421', '173205')
164
- # api.delete_reply(['141421', '173205'])
165
- #
166
- # Using custom readers:
167
- #
168
- # response = api.delete_reply('141421', '173205')
169
- # response.deleted
170
- # # => ['141421', '173205']
182
+ # api.delete_reply('173205', '223606')
183
+ # api.delete_reply(['244948', '264575'])
171
184
  def delete_reply(*ids)
185
+ single = ids.size == 1 && ids.first.is_a?(String)
172
186
  ids.flatten!
173
187
  raise TextMagic::API::Error.new(4, 'Insufficient parameters') if ids.empty?
174
- response = Executor.execute('delete_reply', @username, @password, :ids => ids.join(','))
175
- response.extend(TextMagic::API::Response::DeleteReply)
188
+ Executor.execute('delete_reply', @username, @password, :ids => ids.join(','))
189
+ true
176
190
  end
177
191
  end
178
192
  end