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

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



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

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.



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

def appid
  @appid
end

#cookie ⇒ Object (readonly)

Returns the value of attribute cookie.



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

def cookie
  @cookie
end

#secret ⇒ Object (readonly)

Returns the value of attribute secret.



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

def secret
  @secret
end

#token ⇒ Object (readonly)

Returns the value of attribute token.



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

def token
  @token
end

#wssid ⇒ Object (readonly)

Returns the value of attribute wssid.



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

def wssid
  @wssid
end

Class Method Details

.parse_contacts(json) ⇒ 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



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

def self.parse_contacts(json)
  contacts = []
  people = if defined? ActiveSupport::JSON
    ActiveSupport::JSON.decode(json)
  else
    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.



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

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.



144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
 
# File 'lib/contacts/yahoo.rb', line 144

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) ⇒ 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



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

def contacts(path)
  begin
    validate_signature(path)
    credentials = access_user_credentials()
    parse_credentials(credentials)
    contacts_json = access_address_book_api()
    Yahoo.parse_contacts(contacts_json)
  rescue Exception => e
    "Error #{e.class}: #{e.message}."
  end
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.



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

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.



163
164
165
166
167
168
169
170
171
172
173
174
 
# File 'lib/contacts/yahoo.rb', line 163

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

This method parses the user’s credentials to generate the WSSID and Coookie that are needed to give you access to user’s address book.

Paramaters

  • xml <String>

    A String containing the user’s credentials



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

def parse_credentials(xml)
  doc = Hpricot::XML(xml)
  @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



128
129
130
131
132
133
134
135
136
137
138
139
140
 
# File 'lib/contacts/yahoo.rb', line 128

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