Class: Pingfm::Client

Inherits:
Object
  • Object
show all
Defined in:
lib/pingfm/client.rb

Overview

TODO: The status_ok and status_fail methods need a little thought.

Constant Summary collapse

API_KEY =

The registered API key for the Ping.fm Ruby library client.

'5fcb8b7041d5c32c7e1e60dc076989ba'
API_URL =

MUST NOT end with a trailing slash, as this string is interpolated like this: “#API_URL/user.services” FIXME: This should be handled better; not so brittle as to break on a trailing slash.

'http://api.ping.fm/v1'

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(user_app_key, options = {}) ⇒ Client

You can pass an options hash:

debug

Boolean used when testing to avoid actually posting a message.

decode_body

If true, the ‘body’ of appropriate elements will be Base64 decoded; default is false.



23
24
25
26
27
28
29
30
 
# File 'lib/pingfm/client.rb', line 23

def initialize(user_app_key, options = {})
  @user_app_key = user_app_key
  @options = {
    # Defaults:
    :debug => false,
    :decode_body => false,
  }.merge(options)
end

Instance Attribute Details

#options ⇒ Object (readonly)

Returns the value of attribute options.



18
19
20
 
# File 'lib/pingfm/client.rb', line 18

def options
  @options
end

#user_app_key ⇒ Object (readonly)

Returns the value of attribute user_app_key.



17
18
19
 
# File 'lib/pingfm/client.rb', line 17

def user_app_key
  @user_app_key
end

Instance Method Details

#latest(limit = 25, order = 'DESC') ⇒ Object

Returns the last limit messages a user has posted through Ping.fm.

Optional arguments:

limit

Limit the results returned; default is 25.

order

Which direction to order the returned results by date; default is ‘DESC’.

If successful returns:

{'status' => 'OK', 'messages' => [{'id' => 'messageid', 'method' => 'messsagemethod', 'rfc' => 'date', 'unix' => 'date', 'title' => 'messagetitle', 'body' => 'messagebody', 'services' => [{'id' => 'serviceid', 'name' => 'servicename'}, ...]}, ...]}

If unsuccessful returns:

{'status' => 'FAIL', 'message' => 'message what went wrong'}



42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
 
# File 'lib/pingfm/client.rb', line 42

def latest(limit = 25, order = 'DESC')
  response = get_response('user.latest', 'limit' => limit, 'order' => order)
  if response.elements['rsp'].attributes['status'] == 'OK'
    latest = status_ok
    latest['messages'] = []
    response.elements.each('rsp/messages/message') do |message|
      latest['messages'].push({})
      latest['messages'].last['id'] = message.attributes['id']
      latest['messages'].last['method'] = message.attributes['method']
      latest['messages'].last['rfc'] = message.elements['date'].attributes['rfc']
      latest['messages'].last['unix'] = message.elements['date'].attributes['unix']

      if message.elements['*/title'] != nil
        latest['messages'].last['title'] = message.elements['*/title'].text
      else
        latest['messages'].last['title'] = ''
      end
      if message.elements['location'] != nil
        latest['messages'].last['location'] = message.elements['location'].text
      else
        latest['messages'].last['location'] = ''
      end
      encoded_body = message.elements['*/body'].text
      latest['messages'].last['body'] = @options[:decode_body] ? Base64.decode64(encoded_body) : encoded_body
      latest['messages'].last['services'] = []
      message.elements.each('services/service') do |service|
        latest['messages'].last['services'].push({'id' => service.attributes['id'], 'name' => service.attributes['name']})
      end
    end
    return latest
  else
    return status_fail(response)
  end
end

#links(limit = 25, order = 'DESC') ⇒ Object

Returns the last limit number of links the user has shortened and posted through Ping.fm.

Optional arguments:

limit

Limit the results returned; default is 25.

order

The sort order of the results; default is ‘DESC’.

If successful returns:

{'status' => 'OK', 'links' => [{ 'short' => 'http://ping.fm/}, ...]}



85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
 
# File 'lib/pingfm/client.rb', line 85

def links(limit = 25, order = 'DESC')
  response = get_response('user.links', 'limit' => limit, 'order' => order)
  if response.elements['rsp'].attributes['status'] == 'OK'
    links = []
    response.elements.each('rsp/links/link') do |link|
      links << {
        'date'  => link.elements['date'].attributes['rfc'],
        'short' => link.elements['short'].text,
        'long'  => link.elements['long'].text,
      }
    end
    status_ok('links' => links)
  else
    status_fail(response)
  end
end

#post(body, opts = { :title => '', :post_method => 'default', :service => '' }) ⇒ Object

Posts a message to the user’s Ping.fm services.

Arguments:

body

Message body.

Optional opts:

title

Title of the posted message; title is required for ‘blog’ post method.

post_method

Posting method; either ‘default’, ‘blog’, ‘microblog’ or ‘status’.

service

A single service to post to.

If successful returns:

{'status' => 'OK'}

If unsuccessful returns:

{'status' => 'FAIL', 'message' => 'message what went wrong'}



122
123
124
125
126
127
128
129
130
131
132
133
 
# File 'lib/pingfm/client.rb', line 122

def post(body, opts = { :title => '', :post_method => 'default', :service => '' })
  response = get_response('user.post',
                          'body' => body, 'title' => opts[:title],
                          'post_method' => opts[:post_method], 'service' => opts[:service],
                          'debug' => (@options[:debug] ? 1 : 0))

  if response.elements['rsp'].attributes['status'] == 'OK'
    return status_ok
  else
    return status_fail(response)
  end
end

#services ⇒ Object

Returns a list of services the user has set up through Ping.fm.

If successful returns:

{'status' => 'OK', 'services' => [{'id' => 'serviceid', 'name' => 'servicename', 'trigger' => 'servicetrigger', 'url' => 'serviceurl', 'icon' => 'serviceicon', 'methods' => 'status,blog'}, ...]}

If unsuccessful returns:

{'status' => 'FAIL', 'message' => 'message what went wrong'}



141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
 
# File 'lib/pingfm/client.rb', line 141

def services
  response = get_response('user.services')
  if response.elements['rsp'].attributes['status'] == 'OK'
    services = status_ok
    services['services'] = []
    response.elements.each('rsp/services/service') do |service|
      services['services'].push({'id' => service.attributes['id'],
                    'name' => service.attributes['name'],
                    'trigger' => service.elements['trigger'].text,
                    'url' => service.elements['url'].text,
                    'icon' => service.elements['icon'].text,
                    'methods' => service.elements['methods'].text})
    end
    return services
  else
    return status_fail(response)
  end
end

#system_services ⇒ Object

Return a complete list of supported services.

If successful returns:

{'status' => 'OK', 'services' => [{'id' => 'serviceid', 'name' => 'servicename', 'trigger' => 'servicetrigger', 'url' => 'serviceurl', 'icon' => 'serviceicon'}, ...]}

If unsuccessful returns:

{'status' => 'FAIL', 'message' => 'message what went wrong'}



166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
 
# File 'lib/pingfm/client.rb', line 166

def system_services
  response = get_response('system.services')
  if response.elements['rsp'].attributes['status'] == 'OK'
    services = status_ok
    services['services'] = []
    response.elements.each('rsp/services/service') do |service|
      services['services'].push({'id'      => service.attributes['id'],
                                 'name'    => service.attributes['name'],
                                 'trigger' => service.elements['trigger'].text,
                                 'url'     => service.elements['url'].text,
                                 'icon'    => service.elements['icon'].text})
    end
    return services
  else
    return status_fail(response)
  end
end

#tpost(body, trigger, opts = { :title => '' }) ⇒ Object

Posts a message to the user’s Ping.fm services using one of their custom triggers.

Arguments:

body

Message body.

trigger

Custom trigger the user has defined from the Ping.fm website.

Optional opts:

title

Title of the posted message; title is required for ‘blog’ post method.

If successful returns:

{'status' => 'OK'}

If unsuccessful returns:

{'status' => 'FAIL', 'message' => 'message what went wrong'}



197
198
199
200
201
202
203
204
205
206
 
# File 'lib/pingfm/client.rb', line 197

def tpost(body, trigger, opts = { :title => '' })
  response = get_response('user.tpost',
                          'body' => body, 'title' => opts[:title],
                          'trigger' => trigger, 'debug' => (@options[:debug] ? 1 : 0))
  if response.elements['rsp'].attributes['status'] == 'OK'
    return status_ok
  else
    return status_fail(response)
  end
end

#triggers ⇒ Object

Returns a user’s custom triggers.

If successful returns:

{'status' => 'OK', 'triggers' => [{'id' => 'triggerid', 'method' => 'triggermethod', 'services' => [{'id' => 'serviceid', 'name' => 'servicename'}, ...]}, ...]}

If unsuccessful returns:

{'status' => 'FAIL', 'message' => 'message what went wrong'}



214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
 
# File 'lib/pingfm/client.rb', line 214

def triggers
  response = get_response('user.triggers')
  if response.elements['rsp'].attributes['status'] == 'OK'
    triggers = status_ok
    triggers['triggers'] = []
    response.elements.each('rsp/triggers/trigger') do |trigger|
      triggers['triggers'].push({'id' => trigger.attributes['id'], 'method' => trigger.attributes['method'], 'services' => []})

      trigger.elements.each('services/service') do |service|
        triggers['triggers'].last['services'].push({'id' => service.attributes['id'], 'name' => service.attributes['name']})
      end
    end
    return triggers
  else
    return status_fail(response)
  end
end

#url_create ⇒ Object 



102
103
 
# File 'lib/pingfm/client.rb', line 102

def url_create
end

#url_resolve ⇒ Object 



105
106
 
# File 'lib/pingfm/client.rb', line 105

def url_resolve
end

#user_key(mobile_key) ⇒ Object

Returns the full user app key from the provided mobile_key.



233
234
235
236
237
238
239
240
241
 
# File 'lib/pingfm/client.rb', line 233

def user_key(mobile_key)
  response = get_response('user.key', 'mobile_key' => mobile_key)
  if response.elements['rsp'].attributes['status'] == 'OK'
    app_key = response.elements['rsp'].elements['key'].text
    status_ok('app_key' => app_key)
  else
    status_fail(response)
  end
end

#validate ⇒ Object

Validates the API key and user APP key.

If successful returns:

{'status' => 'OK'}

If unsuccessful returns:

{'status' => 'FAIL', 'message' => 'message what went wrong'}



249
250
251
252
253
254
255
256
 
# File 'lib/pingfm/client.rb', line 249

def validate
  response = get_response('user.validate')
  if response.elements['rsp'].attributes['status'] == 'OK'
    return status_ok
  else
    return status_fail(response)
  end
end