Class: Nuntium
- Inherits:
-
Object
- Object
- Nuntium
- Defined in:
- lib/nuntium.rb,
lib/nuntium/exception.rb
Overview
Provides access to the Nuntium Public API.
Defined Under Namespace
Classes: Exception
Instance Method Summary collapse
-
#candidate_channels_for_ao(message) ⇒ Object
Returns the list of candidate channels when simulating routing the given AO message.
-
#carrier(guid) ⇒ Object
Gets a carrier as a hash given its guid, or nil if a carrier with that guid does not exist.
-
#carriers(country_id = nil) ⇒ Object
Gets the list of carriers known to Nuntium that belong to a country as an array of hashes, given its iso2 or iso3 code.
-
#channel(name) ⇒ Object
Returns a channel given its name.
-
#channels ⇒ Object
Returns the list of channels belonging to the application or that don’t belong to any application, as an array of hashes.
-
#countries ⇒ Object
Gets the list of countries known to Nuntium as an array of hashes.
-
#country(iso) ⇒ Object
Gets a country as a hash given its iso2 or iso3 code, or nil if a country with that iso does not exist.
-
#create_channel(channel) ⇒ Object
Creates a channel.
-
#delete_channel(name) ⇒ Object
Deletes a chnanel given its name.
-
#get_ao(token) ⇒ Object
Gets AO messages that have the given token.
-
#get_custom_attributes(address) ⇒ Object
Gets the custom attributes specified for a given address.
-
#initialize(url, account, application, password) ⇒ Nuntium
constructor
Creates an application-authenticated Nuntium api access.
-
#send_ao(messages) ⇒ Object
Sends one or many AO messages.
-
#set_custom_attributes(address, attributes) ⇒ Object
Sets custom attributes of a given address.
-
#twitter_authorize(channel_name, callback) ⇒ Object
Returns a URL to authorize the given twitter channel, which will eventually redirect to the given callback URL.
-
#twitter_friendship_create(channel_name, user, follow = true) ⇒ Object
Creates a friendship between the channel’s twitter account and the given user.
-
#update_channel(channel) ⇒ Object
Updates a channel.
-
#xmpp_add_contact(channel_name, jid) ⇒ Object
Adds an xmpp conact to the xmpp account associated to the given channel.
Constructor Details
#initialize(url, account, application, password) ⇒ Nuntium
Creates an application-authenticated Nuntium api access.
62 63 64 65 66 67 68 69 70 71 |
# File 'lib/nuntium.rb', line 62 def initialize(url, account, application, password) @url = url @account = account @application = application @options = { :user => "#{account}/#{application}", :password => password, :headers => {:content_type => 'application/json'}, } end |
Instance Method Details
#candidate_channels_for_ao(message) ⇒ Object
Returns the list of candidate channels when simulating routing the given AO message.
candidate_channels_for_ao :from => 'sms://1', :to => 'sms://2', :subject => 'hello', :body => 'hi!'
Raises Nuntium::Exception if something goes wrong.
192 193 194 |
# File 'lib/nuntium.rb', line 192 def candidate_channels_for_ao() get_channels "/api/candidate/channels.json?#{to_query }" end |
#carrier(guid) ⇒ Object
Gets a carrier as a hash given its guid, or nil if a carrier with that guid does not exist.
Raises Nuntium::Exception if something goes wrong.
102 103 104 |
# File 'lib/nuntium.rb', line 102 def carrier(guid) get_json "/api/carriers/#{guid}.json" end |
#carriers(country_id = nil) ⇒ Object
Gets the list of carriers known to Nuntium that belong to a country as an array of hashes, given its iso2 or iso3 code. Gets all carriers as an array of hashes if no country is specified.
Raises Nuntium::Exception if something goes wrong.
91 92 93 94 95 96 97 |
# File 'lib/nuntium.rb', line 91 def carriers(country_id = nil) if country_id get_json "/api/carriers.json?country_id=#{country_id}" else get_json "/api/carriers.json" end end |
#channel(name) ⇒ Object
Returns a channel given its name. Raises when the channel does not exist.
Raises Nuntium::Exception if something goes wrong.
126 127 128 129 130 131 132 133 134 |
# File 'lib/nuntium.rb', line 126 def channel(name) get("/api/channels/#{name}.json") do |response, error| raise Nuntium::Exception.new error. if error channel = JSON.parse response.body read_configuration channel with_indifferent_access channel end end |
#channels ⇒ Object
Returns the list of channels belonging to the application or that don’t belong to any application, as an array of hashes.
Raises Nuntium::Exception if something goes wrong.
110 111 112 113 114 115 116 117 118 119 120 121 |
# File 'lib/nuntium.rb', line 110 def channels get "/api/channels.json" do |response, error| raise Nuntium::Exception.new error. if error channels = JSON.parse response.body channels.map! do |channel| read_configuration channel with_indifferent_access channel end channels end end |
#countries ⇒ Object
Gets the list of countries known to Nuntium as an array of hashes.
Raises Nuntium::Exception if something goes wrong.
76 77 78 |
# File 'lib/nuntium.rb', line 76 def countries get_json "/api/countries.json" end |
#country(iso) ⇒ Object
Gets a country as a hash given its iso2 or iso3 code, or nil if a country with that iso does not exist.
Raises Nuntium::Exception if something goes wrong.
83 84 85 |
# File 'lib/nuntium.rb', line 83 def country(iso) get_json "/api/countries/#{iso}.json" end |
#create_channel(channel) ⇒ Object
Creates a channel.
create_channel :name => 'foo', :kind => 'qst_server', :protocol => 'sms', :configuration => {:password => 'bar'}
Raises Nuntium::Exception if something goes wrong. You can access specific errors on properties via the properties accessor of the exception.
142 143 144 145 146 147 148 149 150 151 152 153 |
# File 'lib/nuntium.rb', line 142 def create_channel(channel) channel = channel.dup write_configuration channel post "/api/channels.json", channel.to_json do |response, error| handle_channel_error error if error channel = JSON.parse response.body read_configuration channel with_indifferent_access channel end end |
#delete_channel(name) ⇒ Object
Deletes a chnanel given its name.
Raises Nuntium::Exception if something goes wrong.
179 180 181 182 183 184 185 |
# File 'lib/nuntium.rb', line 179 def delete_channel(name) delete "/api/channels/#{name}" do |response, error| raise Nuntium::Exception.new error. if error response end end |
#get_ao(token) ⇒ Object
Gets AO messages that have the given token. The response is an array of hashes with the messages’ attributes.
Raises Nuntium::Exception if something goes wrong.
232 233 234 |
# File 'lib/nuntium.rb', line 232 def get_ao(token) get_json "/#{@account}/#{@application}/get_ao.json?token=#{token}" end |
#get_custom_attributes(address) ⇒ Object
Gets the custom attributes specified for a given address. Returns a hash with the attributes
Raises Nuntium::Exception if something goes wrong.
239 240 241 |
# File 'lib/nuntium.rb', line 239 def get_custom_attributes(address) get_json "/api/custom_attributes?address=#{address}" end |
#send_ao(messages) ⇒ Object
Sends one or many AO messages.
To send a token, just include it in the message as :token => ‘my_token’
send_ao :from => 'sms://1', :to => 'sms://2', :subject => 'hello', :body => 'hi!'
send_ao [{:from => 'sms://1', :to => 'sms://2', :subject => 'hello', :body => 'hi!'}, {...}]
Returns a hash with :id, :guid and :token keys if a single message was sent, otherwise returns a hash with a :token key.
Raises Nuntium::Exception if something goes wrong.
207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 |
# File 'lib/nuntium.rb', line 207 def send_ao() if .is_a? Array post "/#{@account}/#{@application}/send_ao.json", .to_json do |response, error| raise Nuntium::Exception.new error. if error with_indifferent_access({:token => response.headers[:x_nuntium_token]}) end else get "/#{@account}/#{@application}/send_ao?#{to_query }" do |response, error| raise Nuntium::Exception.new error. if error with_indifferent_access( { :id => response.headers[:x_nuntium_id], :guid => response.headers[:x_nuntium_guid], :token => response.headers[:x_nuntium_token], } ) end end end |
#set_custom_attributes(address, attributes) ⇒ Object
Sets custom attributes of a given address.
Raises Nuntium::Exception if something goes wrong.
246 247 248 249 250 251 252 |
# File 'lib/nuntium.rb', line 246 def set_custom_attributes(address, attributes) post "/api/custom_attributes?address=#{address}", attributes.to_json do |response, error| raise Nuntium::Exception.new error. if error nil end end |
#twitter_authorize(channel_name, callback) ⇒ Object
Returns a URL to authorize the given twitter channel, which will eventually redirect to the given callback URL.
Raises Nuntium::Exception if something goes wrong.
272 273 274 |
# File 'lib/nuntium.rb', line 272 def (channel_name, callback) get_text("/api/channels/#{channel_name}/twitter/authorize?callback=#{CGI.escape callback}") end |
#twitter_friendship_create(channel_name, user, follow = true) ⇒ Object
Creates a friendship between the channel’s twitter account and the given user. Returns the response from twitter. Refer to Twitter’s documentation: dev.twitter.com/docs/api/1/post/friendships/create
Raises Nuntium::Exception if something goes wrong.
260 261 262 263 264 265 266 |
# File 'lib/nuntium.rb', line 260 def twitter_friendship_create(channel_name, user, follow = true) get("/api/channels/#{channel_name}/twitter/friendships/create?user=#{CGI.escape user}&follow=#{follow}") do |response, error| raise Nuntium::Exception.new error. if error response end end |
#update_channel(channel) ⇒ Object
Updates a channel.
update_channel :name => 'foo', :kind => 'qst_server', :protocol => 'sms', :configuration => {:password => 'bar'}
Raises Nuntium::Exception if something goes wrong. You can access specific errors on properties via the properties accessor of the exception.
161 162 163 164 165 166 167 168 169 170 171 172 173 174 |
# File 'lib/nuntium.rb', line 161 def update_channel(channel) channel = channel.dup write_configuration channel channel_name = channel['name'] || channel[:name] put "/api/channels/#{channel_name}.json", channel.to_json do |response, error| handle_channel_error error if error channel = JSON.parse response.body read_configuration channel with_indifferent_access channel end end |
#xmpp_add_contact(channel_name, jid) ⇒ Object
Adds an xmpp conact to the xmpp account associated to the given channel.
Raises Nuntium::Exception if something goes wrong.
279 280 281 282 283 284 285 |
# File 'lib/nuntium.rb', line 279 def xmpp_add_contact(channel_name, jid) get("/api/channels/#{channel_name}/xmpp/add_contact?jid=#{CGI.escape jid}") do |response, error| raise Nuntium::Exception.new error. if error response end end |