Class: Nuntium

Inherits:
Object
  • Object
show all
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

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, , application, password)
  @url = url
  @account = 
  @application = application
  @options = {
    :user => "#{}/#{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(message)
  get_channels "/api/candidate/channels.json?#{to_query message}"
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.message 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.message 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.message 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(messages)
  if messages.is_a? Array
    post "/#{@account}/#{@application}/send_ao.json", messages.to_json do |response, error|
      raise Nuntium::Exception.new error.message if error

      with_indifferent_access({:token => response.headers[:x_nuntium_token]})
    end
  else
    get "/#{@account}/#{@application}/send_ao?#{to_query messages}" do |response, error|
      raise Nuntium::Exception.new error.message 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.message if error

    nil
  end
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.message 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.



271
272
273
274
275
276
277
 
# File 'lib/nuntium.rb', line 271

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.message if error

    response
  end
end