Class: Pigeon::Nuntium

Inherits:
Object
  • Object
show all
Includes:
Utils
Defined in:
lib/pigeon/nuntium.rb

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Utils

#delete, #get, #get_json, #handle_channel_error, #post, #put, #to_query, #with_indifferent_access

Constructor Details

#initialize(url, account, application, password) ⇒ Nuntium

Creates an application-authenticated Nuntium api access.



27
28
29
30
31
32
33
34
35
36
 
# File 'lib/pigeon/nuntium.rb', line 27

def initialize(url, , application, password)
  @url = url
  @account = 
  @application = application
  @options = {
    :user => "#{}/#{application}",
    :password => password,
    :headers => {:content_type => 'application/json'},
  }
end

Class Method Details

.error_class ⇒ Object 



16
17
18
 
# File 'lib/pigeon/nuntium.rb', line 16

def self.error_class
  Pigeon::NuntiumException
end

.from_config ⇒ Object 



20
21
22
23
24
 
# File 'lib/pigeon/nuntium.rb', line 20

def self.from_config
  config = Pigeon.config

  Nuntium.new config.nuntium_host, config., config.nuntium_app, config.nuntium_app_password
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 ::Pigeon::NuntiumException if something goes wrong.



157
158
159
 
# File 'lib/pigeon/nuntium.rb', line 157

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 ::Pigeon::NuntiumException if something goes wrong.



67
68
69
 
# File 'lib/pigeon/nuntium.rb', line 67

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 ::Pigeon::NuntiumException if something goes wrong.



56
57
58
59
60
61
62
 
# File 'lib/pigeon/nuntium.rb', line 56

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 ::Pigeon::NuntiumException if something goes wrong.



91
92
93
94
95
96
97
98
99
 
# File 'lib/pigeon/nuntium.rb', line 91

def channel(name)
  get("/api/channels/#{name}.json") do |response, error|
    raise ::Pigeon::NuntiumException.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 ::Pigeon::NuntiumException if something goes wrong.



75
76
77
78
79
80
81
82
83
84
85
86
 
# File 'lib/pigeon/nuntium.rb', line 75

def channels
  get "/api/channels.json" do |response, error|
    raise ::Pigeon::NuntiumException.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 ::Pigeon::NuntiumException if something goes wrong.



41
42
43
 
# File 'lib/pigeon/nuntium.rb', line 41

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 ::Pigeon::NuntiumException if something goes wrong.



48
49
50
 
# File 'lib/pigeon/nuntium.rb', line 48

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 ::Pigeon::NuntiumException if something goes wrong. You can access specific errors on properties via the properties accessor of the exception.



107
108
109
110
111
112
113
114
115
116
117
118
 
# File 'lib/pigeon/nuntium.rb', line 107

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 ::Pigeon::NuntiumException if something goes wrong.



144
145
146
147
148
149
150
 
# File 'lib/pigeon/nuntium.rb', line 144

def delete_channel(name)
  delete "/api/channels/#{name}" do |response, error|
    raise ::Pigeon::NuntiumException.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 ::Pigeon::NuntiumException if something goes wrong.



197
198
199
 
# File 'lib/pigeon/nuntium.rb', line 197

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 ::Pigeon::NuntiumException if something goes wrong.



204
205
206
 
# File 'lib/pigeon/nuntium.rb', line 204

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 ::Pigeon::NuntiumException if something goes wrong.



172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
 
# File 'lib/pigeon/nuntium.rb', line 172

def send_ao(messages)
  if messages.is_a? Array
    post "/#{@account}/#{@application}/send_ao.json", messages.to_json do |response, error|
      raise ::Pigeon::NuntiumException.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 ::Pigeon::NuntiumException.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 ::Pigeon::NuntiumException if something goes wrong.



211
212
213
214
215
216
217
 
# File 'lib/pigeon/nuntium.rb', line 211

def set_custom_attributes(address, attributes)
  post "/api/custom_attributes?address=#{address}", attributes.to_json do |response, error|
    raise ::Pigeon::NuntiumException.new error.message 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 ::Pigeon::NuntiumException if something goes wrong.



237
238
239
 
# File 'lib/pigeon/nuntium.rb', line 237

def twitter_authorize(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 ::Pigeon::NuntiumException if something goes wrong.



225
226
227
228
229
230
231
 
# File 'lib/pigeon/nuntium.rb', line 225

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 ::Pigeon::NuntiumException.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 ::Pigeon::NuntiumException if something goes wrong. You can access specific errors on properties via the properties accessor of the exception.



126
127
128
129
130
131
132
133
134
135
136
137
138
139
 
# File 'lib/pigeon/nuntium.rb', line 126

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 ::Pigeon::NuntiumException if something goes wrong.



244
245
246
247
248
249
250
 
# File 'lib/pigeon/nuntium.rb', line 244

def xmpp_add_contact(channel_name, jid)
  get("/api/channels/#{channel_name}/xmpp/add_contact?jid=#{CGI.escape jid}") do |response, error|
    raise ::Pigeon::NuntiumException.new error.message if error

    response
  end
end