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



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

def self.parse_contacts(json)
  contacts = []
  people = JSON.parse(json)
  people['contacts'].each do |contact|
    name = nil
    email = nil
    firstname = nil
    lastname = 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!
        lastname = field['last']
        firstname = field['first']
      end
    end
    yahoo_contact = Contact.new(email, name, nil, firstname, lastname)
    yahoo_contact.service_id = contact['cid']

    contacts.push yahoo_contact
  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.



195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
 
# File 'lib/contacts/yahoo.rb', line 195

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.



148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
 
# File 'lib/contacts/yahoo.rb', line 148

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(token) ⇒ 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
119
120
121
122
 
# File 'lib/contacts/yahoo.rb', line 108

def contacts(token)
  begin
    if token.is_a?(YahooToken)
      @token = token.token
    else
      validate_signature(token)
    end
    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.



167
168
169
170
171
172
173
174
175
176
177
178
 
# File 'lib/contacts/yahoo.rb', line 167

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



186
187
188
189
190
 
# File 'lib/contacts/yahoo.rb', line 186

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



132
133
134
135
136
137
138
139
140
141
142
143
144
 
# File 'lib/contacts/yahoo.rb', line 132

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