pezra-contacts 0.1.0

data/lib/contacts/version.rb

@@ -0,0 +1,9 @@
+module Contacts
+  module VERSION #:nodoc:
+    MAJOR = 0
+    MINOR = 2
+    TINY  = 5
+
+    STRING = [MAJOR, MINOR, TINY].join('.')
+  end
+end

data/lib/contacts/windows_live.rb

@@ -0,0 +1,164 @@
+require 'contacts'
+require File.join(File.dirname(__FILE__), %w{.. .. vendor windowslivelogin})
+
+require 'rubygems'
+require 'hpricot'
+require 'uri'
+require 'yaml'
+
+module Contacts
+  # = How I can fetch Windows Live Contacts?
+  # To gain access to a Windows Live user's data in the Live Contacts service, 
+  # a third-party developer first must ask the owner for permission. You must
+  # do that through Windows Live Delegated Authentication.
+  # 
+  # This library give you access to Windows Live Delegated Authentication System
+  # and Windows Live Contacts API. Just follow the steps below and be happy!
+  # 
+  # === Registering your app
+  # First of all, follow the steps in this 
+  # page[http://msdn.microsoft.com/en-us/library/cc287659.aspx] to register your
+  # app.
+  # 
+  # === Configuring your Windows Live YAML
+  # After registering your app, you will have an *appid*, a <b>secret key</b> and
+  # a <b>return URL</b>. Use their values to fill in the config/contacts.yml file.
+  # The policy URL field inside the YAML config file must contain the URL 
+  # of the privacy policy of your Web site for Delegated Authentication.
+  # 
+  # === Authenticating your user and fetching his contacts
+  # 
+  #   wl = Contacts::WindowsLive.new
+  #   auth_url = wl.get_authentication_url
+  # 
+  # Use that *auth_url* to redirect your user to Windows Live. He will authenticate
+  # there and Windows Live will POST to your return URL. You have to get the
+  # body of that POST, let's call it post_body. (if you're using Rails, you can 
+  # get the POST body through request.raw_post, in the context of an action inside
+  # ActionController)
+  #
+  # Now, to fetch his contacts, just do this:
+  #
+  #   contacts = wl.contacts(post_body)
+  #   #-> [ ['Fitzgerald', 'fubar@gmail.com', 'fubar@example.com'],
+  #         ['William Paginate', 'will.paginate@gmail.com'], ...
+  #       ]
+  #--
+  # This class has two responsibilities:
+  # 1. Access the Windows Live Contacts API through Delegated Authentication
+  # 2. Import contacts from Windows Live and deliver it inside an Array
+  #
+  class WindowsLive
+    CONFIG_FILE = File.dirname(__FILE__) + '/../config/contacts.yml'
+
+    # Initialize a new WindowsLive object.
+    #    
+    # ==== Paramaters
+    # * config_file <String>:: The contacts YAML config file name
+    #--
+    # You can check an example of a config file inside config/ directory
+    #
+    def initialize(config_file=CONFIG_FILE)
+      confs = YAML.load_file(config_file)['windows_live']
+      @wll = WindowsLiveLogin.new(confs['appid'], confs['secret'], confs['security_algorithm'],
+                                  nil, confs['policy_url'], confs['return_url'])
+    end
+
+
+    # Windows Live Contacts API need to authenticate the user that is giving you
+    # access to his contacts. To do that, you must give him a URL. That method
+    # generates that URL. The user must access that URL, and after he has done
+    # authentication, hi will be redirected to your application.
+    #
+    def get_authentication_url
+      @wll.getConsentUrl("Contacts.Invite")
+    end
+    
+    # After the user has been authenticaded, Windows Live Delegated Authencation
+    # Service redirects to your application, through a POST HTTP method. Along
+    # with the POST, Windows Live send to you a Consent that you must process
+    # to access the user's contacts. This method process the Consent 
+    # to you.
+    #
+    # ==== Paramaters
+    # * consent <String>:: A string containing the Consent given to you inside
+    # the redirection POST from Windows Live
+    #
+    def process_consent(consent)
+      consent.strip!
+      consent = URI.unescape(consent)
+      @consent_token = @wll.processConsent(consent)
+    end
+    
+    # This method return the user's contacts inside an Array in the following
+    # format:
+    #
+    #   [ 
+    #     ['Brad Fitzgerald', 'fubar@gmail.com'],
+    #     [nil, 'nagios@hotmail.com'],
+    #     ['William Paginate', 'will.paginate@yahoo.com']  ...
+    #   ]
+    #
+    # ==== Paramaters
+    # * consent <String>:: A string containing the Consent given to you inside 
+    # the redirection POST from Windows Live
+    #
+    def contacts(consent)
+      process_consent(consent)
+      contacts_xml = access_live_contacts_api()
+      contacts_list = WindowsLive.parse_xml(contacts_xml)
+    end
+
+    # This method access the Windows Live Contacts API Web Service to get
+    # the XML contacts document
+    #
+    def access_live_contacts_api
+      Net::HTTP.version_1_1
+      http = http = Net::HTTP.new('livecontacts.services.live.com', 443)
+      http.use_ssl = true
+
+      response = nil
+      http.start do |http|
+         request = Net::HTTP::Get.new("/users/@L@#{@consent_token.locationid}/rest/invitationsbyemail", {"Authorization" => "DelegatedToken dt=\"#{@consent_token.delegationtoken}\""})
+         response = http.request(request)
+      end
+
+      return response.body
+    end
+    
+    # This method parses the XML Contacts document and returns the contacts
+    # inside an Array
+    #
+    # ==== Paramaters
+    # * xml <String>:: A string containing the XML contacts document
+    #
+    def self.parse_xml(xml)
+      doc = Hpricot::XML(xml)
+
+      contacts = []
+      doc.search('/livecontacts/contacts/contact').each do |contact|
+        email = contact.at('/preferredemail').inner_text
+        email.strip!
+
+        first_name = last_name = nil
+        if first_name = contact.at('/profiles/personal/firstname')
+          first_name = first_name.inner_text.strip
+        end
+
+        if last_name = contact.at('/profiles/personal/lastname')
+          last_name = last_name.inner_text.strip
+        end
+        
+        name = nil
+        if !first_name.nil? || !last_name.nil?
+          name = "#{first_name} #{last_name}"
+          name.strip!
+        end
+        contacts.push([name, email])
+      end
+
+      return contacts
+    end
+  end
+
+end

data/lib/contacts/yahoo.rb

@@ -0,0 +1,236 @@
+require 'contacts'
+
+require 'rubygems'
+require 'hpricot'
+require 'md5'
+require 'net/https'
+require 'uri'
+require 'json'
+require 'yaml'
+
+module Contacts
+  # = 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[http://developer.yahoo.com/wsregapp/] to register your app. If you need
+  # some help with that form, you can get it
+  # here[http://developer.yahoo.com/auth/appreg.html]. Just two tips: inside
+  # <b>Required access scopes</b> in that registration form, choose
+  # <b>Yahoo! Address Book with Read Only access</b>. Inside 
+  # <b>Authentication method</b> choose <b>Browser Based Authentication</b>.
+  #
+  # === Configuring your Yahoo YAML
+  # After registering your app, you will have an <b>application id</b> and a
+  # <b>shared secret</b>. 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', 'fubar@gmail.com', 'fubar@example.com'],
+  #         ['William Paginate', 'will.paginate@gmail.com'], ...
+  #       ]
+  #--
+  # 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
+  #
+  class Yahoo
+    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'
+
+    attr_reader :appid, :secret, :token, :wssid, :cookie
+    
+    # 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
+    #
+    def initialize(config_file=CONFIG_FILE)
+      confs = YAML.load_file(config_file)['yahoo']
+      @appid = confs['appid']
+      @secret = confs['secret']
+    end
+
+    # 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.
+    #
+    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
+
+    # This method return the user's contacts inside an Array in the following
+    # format:
+    #
+    #   [ 
+    #     ['Brad Fitzgerald', 'fubar@gmail.com'],
+    #     [nil, 'nagios@hotmail.com'],
+    #     ['William Paginate', 'will.paginate@yahoo.com']  ...
+    #   ]
+    #
+    # ==== Paramaters
+    # * path <String>:: The path of the redirect request that Yahoo sent to you
+    # after authenticating the user
+    #
+    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
+
+    # 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
+    #
+    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
+
+    # This method accesses Yahoo to retrieve the user's credentials.
+    #
+    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
+
+    # This method generates the URL that you must access to get user's
+    # credentials.
+    #
+    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
+
+    # 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
+    #
+    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
+
+    # This method accesses the Yahoo Address Book API and retrieves the user's
+    # contacts in JSON.
+    #
+    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
+    
+    # This method parses the JSON contacts document and returns an array
+    # contaning all the user's contacts.
+    #
+    # ==== Paramaters
+    # * json <String>:: A String the user's contacts ni JSON format
+    #
+    def self.parse_contacts(json)
+      people = JSON.parse(json)
+      contacts = []
+
+      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([name, email])
+      end
+      return contacts
+    end
+
+  end
+end

data/spec/contact_spec.rb

@@ -0,0 +1,38 @@
+require 'spec_helper'
+require 'contacts'
+
+describe Contacts::Contact do
+  describe 'instance' do
+    before do
+      @contact = Contacts::Contact.new('max@example.com', 'Max Power', 'maxpower')
+    end
+    
+    it "should have email" do
+      @contact.email.should == 'max@example.com'
+    end
+    
+    it "should have name" do
+      @contact.name.should == 'Max Power'
+    end
+    
+    it "should support multiple emails" do
+      @contact.emails << 'maxpower@example.com'
+      @contact.email.should == 'max@example.com'
+      @contact.emails.should == ['max@example.com', 'maxpower@example.com']
+    end
+    
+    it "should have username" do
+      @contact.username.should == 'maxpower'
+    end
+    
+    it "should have nice inspect" do
+      @contact.inspect.should == '#<Contacts::Contact "Max Power" (max@example.com)>'
+    end
+  end
+  
+  it "should fail without first argument (email)" do
+    lambda {
+      Contacts::Contact.new()
+    }.should raise_error(ArgumentError)
+  end
+end