Class: Contacts::Yahoo

Inherits:
Object
  • Object
show all
Defined in:
lib/contacts/yahoo.rb

Overview

How I can fetch Yahoo Contacts?

To gain access to a Yahoo user’s data in the Yahoo Address Book Service, a third-party developer first must ask the owner for permission. You must do that through Yahoo Browser Based Authentication (BBAuth).

This library give you access to Yahoo BBAuth and Yahoo Address Book API. Just follow the steps below and be happy!

Registering your app

First of all, follow the steps in this page to register your app. If you need some help with that form, you can get it here. Just two tips: inside Required access scopes in that registration form, choose Yahoo! Address Book with Read Only access. Inside Authentication method choose Browser Based Authentication.

Configuring your Yahoo YAML

After registering your app, you will have an application id and a shared secret. Use their values to fill in the config/contacts.yml file.

Authenticating your user and fetching his contacts

yahoo = Contacts::Yahoo.new
auth_url = yahoo.get_authentication_url

Use that auth_url to redirect your user to Yahoo BBAuth. He will authenticate there and Yahoo will redirect to your application entrypoint URL (that you provided while registering your app with Yahoo). You have to get the path of that redirect, let’s call it path (if you’re using Rails, you can get it through request.request_uri, in the context of an action inside ActionController)

Now, to fetch his contacts, just do this:

contacts = wl.contacts(path)
#-> [ ['Fitzgerald', '[email protected]', '[email protected]'],
      ['William Paginate', '[email protected]'], ...
    ]

– This class has two responsibilities:

  1. Access the Yahoo Address Book API through Delegated Authentication

  2. Import contacts from Yahoo Mail and deliver it inside an Array

Defined Under Namespace

Classes: XMLParseError

Constant Summary collapse

AUTH_DOMAIN = 
"https://api.login.yahoo.com"
AUTH_PATH = 
"/WSLogin/V1/wslogin?appid=#appid&ts=#ts"
CREDENTIAL_PATH = 
"/WSLogin/V1/wspwtoken_login?appid=#appid&ts=#ts&token=#token"
ADDRESS_BOOK_DOMAIN = 
"address.yahooapis.com"
ADDRESS_BOOK_PATH = 
"/v1/searchContacts?format=json&fields=name,email&appid=#appid&WSSID=#wssid"
CONFIG_FILE = 
File.dirname(__FILE__) + '/../config/contacts.yml'

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(config_file = CONFIG_FILE) ⇒ Yahoo

Initialize a new Yahoo object.

Paramaters

  • config_file <String>

    The contacts YAML config file name

– You can check an example of a config file inside config/ directory



72
73
74
75
76
 
# File 'lib/contacts/yahoo.rb', line 72

def initialize(config_file=CONFIG_FILE)
  confs = YAML.load_file(config_file)['yahoo']
  @appid = confs['appid']
  @secret = confs['secret']
end

Instance Attribute Details

#appid ⇒ Object (readonly)

Returns the value of attribute appid.



63
64
65
 
# File 'lib/contacts/yahoo.rb', line 63

def appid
  @appid
end

#cookie ⇒ Object (readonly)

Returns the value of attribute cookie.



63
64
65
 
# File 'lib/contacts/yahoo.rb', line 63

def cookie
  @cookie
end

#secret ⇒ Object (readonly)

Returns the value of attribute secret.



63
64
65
 
# File 'lib/contacts/yahoo.rb', line 63

def secret
  @secret
end

#token ⇒ Object (readonly)

Returns the value of attribute token.



63
64
65
 
# File 'lib/contacts/yahoo.rb', line 63

def token
  @token
end

#wssid ⇒ Object (readonly)

Returns the value of attribute wssid.



63
64
65
 
# File 'lib/contacts/yahoo.rb', line 63

def wssid
  @wssid
end

Class Method Details

.parse_contacts(json, force_json_gem = false) ⇒ Object

This method parses the JSON contacts document and returns an array contaning all the user’s contacts.

Parameters

  • json <String>

    A String of user’s contacts in JSON format



214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
 
# File 'lib/contacts/yahoo.rb', line 214

def self.parse_contacts(json, force_json_gem=false)
  contacts = []
  people = if !force_json_gem && defined? ActiveSupport::JSON
    ActiveSupport::JSON.decode(json)
  else
    require 'json'
    JSON.parse(json)
  end

  people['contacts'].each do |contact|
    name = nil
    email = nil
    contact['fields'].each do |field|
      case field['type']
      when 'email'
        email = field['data']
        email.strip!
      when 'name'
        name = "#{field['first']} #{field['last']}"
        name.strip!
      end
    end
    contacts.push Contact.new(email, name)
  end
  return contacts
end

Instance Method Details

#access_address_book_api ⇒ Object

This method accesses the Yahoo Address Book API and retrieves the user’s contacts in JSON.



192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
 
# File 'lib/contacts/yahoo.rb', line 192

def access_address_book_api
  http = http = Net::HTTP.new(ADDRESS_BOOK_DOMAIN, 80)

  response = nil
  http.start do |http|
     path = ADDRESS_BOOK_PATH.clone
     path.sub!(/#appid/, @appid)
     path.sub!(/#wssid/, @wssid)

     request = Net::HTTP::Get.new(path, {'Cookie' => @cookie})
     response = http.request(request)
  end

  return response.body
end

#access_user_credentials ⇒ Object

This method accesses Yahoo to retrieve the user’s credentials.



139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
 
# File 'lib/contacts/yahoo.rb', line 139

def access_user_credentials
  url = get_credential_url()
  uri = URI.parse(url)

  http = http = Net::HTTP.new(uri.host, uri.port)
  http.use_ssl = true

  response = nil
  http.start do |http|
     request = Net::HTTP::Get.new("#{uri.path}?#{uri.query}")
     response = http.request(request)
  end

  return response.body
end

#contacts(path, force_json_gem = false) ⇒ Object

This method return the user’s contacts inside an Array in the following format:

[ 
  ['Brad Fitzgerald', '[email protected]'],
  [nil, '[email protected]'],
  ['William Paginate', '[email protected]']  ...
]

Paramaters

  • path <String>

    The path of the redirect request that Yahoo sent to you

after authenticating the user



107
108
109
110
111
112
113
 
# File 'lib/contacts/yahoo.rb', line 107

def contacts(path, force_json_gem=false)
  validate_signature(path)
  credentials = access_user_credentials()
  parse_credentials(credentials)
  contacts_json = access_address_book_api()
  Yahoo.parse_contacts(contacts_json, force_json_gem)
end

#get_authentication_url ⇒ Object

Yahoo Address Book API need to authenticate the user that is giving you access to his contacts. To do that, you must give him a URL. This method generates that URL. The user must access that URL, and after he has done authentication, hi will be redirected to your application.



83
84
85
86
87
88
89
90
91
92
 
# File 'lib/contacts/yahoo.rb', line 83

def get_authentication_url
  path = AUTH_PATH.clone
  path.sub!(/#appid/, @appid)

  timestamp = Time.now.utc.to_i
  path.sub!(/#ts/, timestamp.to_s)
  
  signature = MD5.hexdigest(path + @secret)
  return AUTH_DOMAIN + "#{path}&sig=#{signature}"
end

#get_credential_url ⇒ Object

This method generates the URL that you must access to get user’s credentials.



158
159
160
161
162
163
164
165
166
167
168
169
 
# File 'lib/contacts/yahoo.rb', line 158

def get_credential_url
  path = CREDENTIAL_PATH.clone
  path.sub!(/#appid/, @appid)

  path.sub!(/#token/, @token)

  timestamp = Time.now.utc.to_i
  path.sub!(/#ts/, timestamp.to_s)

  signature = MD5.hexdigest(path + @secret)
  return AUTH_DOMAIN + "#{path}&sig=#{signature}"
end

#parse_credentials(xml) ⇒ Object

Raises:



181
182
183
184
185
186
187
 
# File 'lib/contacts/yahoo.rb', line 181

def parse_credentials(xml)
  doc = Hpricot::XML(xml)
  node = doc.at('/BBAuthTokenLoginResponse/Success/WSSID')
  raise XMLParseError, xml.to_s if !node
  @wssid = doc.at('/BBAuthTokenLoginResponse/Success/WSSID').inner_text.strip
  @cookie = doc.at('/BBAuthTokenLoginResponse/Success/Cookie').inner_text.strip
end

#validate_signature(path) ⇒ Object

This method processes and validates the redirect request that Yahoo send to you. Validation is done to verify that the request was really made by Yahoo. Processing is done to get the token.

Paramaters

  • path <String>

    The path of the redirect request that Yahoo sent to you

after authenticating the user



123
124
125
126
127
128
129
130
131
132
133
134
135
 
# File 'lib/contacts/yahoo.rb', line 123

def validate_signature(path)
  path.match(/^(.+)&sig=(\w{32})$/)
  path_without_sig = $1
  sig = $2

  if sig == MD5.hexdigest(path_without_sig + @secret)
    path.match(/token=(.+?)&/)
    @token = $1
    return true
  else
    raise 'Signature not valid. This request may not have been sent from Yahoo.'
  end
end