aurelian-contacts 0.3.1

data/lib/contacts/google_oauth.rb

@@ -0,0 +1,91 @@
+require 'oauth'
+require 'contacts/google'
+
+# An extension to the standard OAuth library so we can nicely use Google APIs
+module GoogleOAuth
+  class RequestToken < OAuth::RequestToken
+    def authorize_url(params={})
+      params.merge! :oauth_token => token
+      params = params.map { |k,v| "%s=%s" % [CGI.escape(k.to_s), CGI.escape(v)] }
+      consumer.authorize_url + "?" + params.join("&")
+    end
+  end
+  
+  class Consumer < OAuth::Consumer
+    def initialize(consumer_key, consumer_secret)
+      super(consumer_key,
+            consumer_secret,
+            {:site => "https://www.google.com",
+             :request_token_path => "/accounts/OAuthGetRequestToken",
+             :access_token_path => "/accounts/OAuthGetAccessToken",
+             :authorize_path => "/accounts/OAuthAuthorizeToken"})
+    end
+    
+    def marshal_load(data)
+      initialize(data[:key], data[:secret])
+    end
+    
+    def marshal_dump
+      {:key => self.key, :secret => self.secret}
+    end
+    
+    def get_request_token(params={})
+      params_str = params.map { |k,v| "%s=%s" % [CGI.escape(k.to_s), CGI.escape(v)] }.join("&")
+      uri = URI.parse(request_token_url? ? request_token_url : request_token_path)
+      if !uri.query || uri.query == ''
+        uri.query = params_str
+      else
+        uri.query = uri.query + "&" + params_str
+      end
+      
+      response=token_request(http_method, uri.to_s, nil, {})
+      GoogleOAuth::RequestToken.new(self, response[:oauth_token], response[:oauth_token_secret])
+    end
+  end
+end
+
+module Contacts
+  class GoogleOAuth < Google
+    def initialize(consumer_key, consumer_secret, user_id = 'default')
+      @consumer = ::GoogleOAuth::Consumer.new(consumer_key, consumer_secret)
+      @request_token = @consumer.get_request_token :scope => "https://www.google.com/m8/feeds/"
+      @projection = 'thin'
+      @user = user_id.to_s
+    end
+    
+    def marshal_load(data)
+      @consumer = data[:consumer]
+      @request_token = data[:request_token]
+      @projection = 'thin'
+      @user = data[:user]
+    end
+    
+    def marshal_dump
+      {:consumer => @consumer,
+       :request_token => @request_token,
+       :user => @user}
+    end
+    
+    # Available parameters:
+    # - hd: Google Apps domain that should be requested (default nil)
+    # - oauth_callback: The URL that the user should be redirected to when he successfully authorized us.
+    def authentication_url(params={})
+      @request_token.authorize_url params
+    end
+    
+    def access_token
+      return @access_token if @access_token
+      begin
+        @access_token = @request_token.get_access_token
+      rescue Net::HTTPServerException
+      end
+    end
+    
+    def get(params={})
+      path = FeedsPath + CGI.escape(@user)
+      google_params = translate_parameters(params)
+      query = self.class.query_string(google_params)
+      access_token.get("#{path}/#{@projection}?#{query}")
+    end
+  end
+end

data/lib/contacts/version.rb

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

data/lib/contacts/windows_live.rb

@@ -0,0 +1,186 @@
+require 'contacts'
+
+require File.join(File.dirname(__FILE__), %w{.. .. vendor windowslivelogin})
+require 'hpricot'
+require 'uri'
+
+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
+    
+    attr_accessor :wll
+    # 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)
+      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(context=nil)
+      @wll.getConsentUrl("Contacts.View", context)
+    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
+    
+    def process_consent_token(consent_token)
+      @wll.processConsentToken consent_token
+    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)
+      if consent.is_a? WindowsLiveLogin::ConsentToken
+        @consent_token = consent
+      else
+        process_consent(consent)
+      end
+      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
+      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/LiveContacts", {"Authorization" => "DelegatedToken dt=\"#{@consent_token.delegationtoken}\""})
+         response = http.request(request)
+      end
+      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') do |contact|
+        
+          contact_id = text_value contact, "ID"
+          
+          first_name = text_value contact, "Profiles/Personal/FirstName"
+          last_name  = text_value contact, "Profiles/Personal/LastName"
+          name = "#{first_name} #{last_name}".strip
+          emails     = contact.search('Emails/Email').collect {|e| text_value e, "Address"}
+          
+          phones     = contact.search('Phones/Phone').collect do |e| 
+            type=convert_type(text_value(e, "PhoneType"))
+            { "type" => type, "value" => (text_value e, "Number") }
+          end
+          
+          addresses = contact.search('Locations/Location').collect do |e|
+            street       = text_value(e, "StreetLine")
+            postal_code  = text_value(e, "PostalCode")
+            sub_division = text_value(e, "Subdivision")
+            city         = text_value(e, "PrimaryCity")
+            country_code = text_value(e, "CountryRegion")
+            formatted    = [street, city, sub_division, postal_code, country_code].compact.join(", ")
+            type         = convert_type(text_value(e, "LocationType"))
+            { "formatted" => formatted, "type" => type, "streetAddress" => street, "locality" => city, "region" => sub_division, "postalCode" => postal_code, "country" => country_code}
+          end
+
+          new_contact = Contact.new(nil, name, nil, first_name, last_name)
+          new_contact.emails      = emails
+          new_contact.phones      = phones
+          new_contact.addresses   = addresses
+          new_contact.service_id  = contact_id
+          contacts << new_contact
+      end  
+      return contacts
+    end
+    
+    def self.text_value(elem,path)
+      elem.at(path).inner_text rescue nil
+    end
+    
+    def self.convert_type(t)
+      {"personal" => "home", "business" => "work"}[t.downcase] || "other"
+    end
+  end
+
+end

data/lib/contacts/yahoo.rb

@@ -0,0 +1,331 @@
+require 'contacts'
+
+require 'hpricot'
+require 'md5'
+require 'net/https'
+require 'uri'
+require 'json'
+
+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=all&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(appdata= nil)
+      path = AUTH_PATH.clone
+      path.sub!(/#appid/, @appid)
+
+      timestamp = Time.now.utc.to_i
+      path.sub!(/#ts/, timestamp.to_s)
+
+      path<< "&appdata=#{appdata}" unless appdata.nil?
+      
+      signature = MD5.hexdigest(path + @secret)
+      "#{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(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
+
+    # 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
+
+      response.body
+    end
+    
+    # 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
+    # "fields": [
+    #    {
+    #        "type": "phone",
+    #        "data": "808 123 1234",
+    #        "home": true,
+    #    },
+    #    {
+    #        "type": "email",
+    #        "data": "martin.berner@mail.com",
+    #    },
+    #    
+    #    {
+    #        "type": "otherid",
+    #        "data": "windowslive@msn.com",
+    #        "msn":  true,
+    #    }
+    #  ]
+    #  
+    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=Yahoo.array_to_hash contact['fields']
+
+        emails    = (contact_fields['email'] || []).collect {|e| e['data']}
+        ims       = (contact_fields['otherid'] || []).collect { |im| get_type_value(im) }
+        phones    = (contact_fields['phone'] || []).collect { |phone| get_type_value(phone) }
+        addresses = (contact_fields['address'] || []).collect do |address| 
+          type=get_type(address)
+          type = {"home" => "home", "work" => "work"}[type.downcase] || "other"
+          value = [address['street'], address['city'], address['state'], address['zip'], address['country']].compact.join(", ")
+          {"type" => type, "value" => value}
+        end
+        
+        name_field=(contact_fields['name'] || [])
+        
+        # if name is blank, try go for the yahoo id, and if that's blank too, ignore the record altogether (probably a mailing list)
+        if (name_field.empty?)
+          if contact_fields['yahooid']
+            name = contact_fields['yahooid'][0]['data']
+          else
+            next
+          end
+        else
+          name_field = name_field[0]
+          name = "#{name_field['first']} #{name_field['last']}"
+          name.strip!
+          lastname = name_field['last']
+          firstname = name_field['first']
+        end
+        
+        yahoo_contact            = Contact.new(nil, name, nil, firstname, lastname)
+        yahoo_contact.emails     = emails
+        yahoo_contact.ims        = ims
+        yahoo_contact.phones     = phones
+        yahoo_contact.addresses  = addresses
+        yahoo_contact.service_id = contact['cid']
+
+        contacts.push yahoo_contact
+      end
+      contacts
+    end
+    
+    #
+    # grab the type field from each array item 
+    #   and turn it into a "email"=>{}, "phone"=>{} array
+    #
+    private 
+    def self.array_to_hash(a)
+      (a || []).inject({}) {|x,y|
+        x[y['type']] ||= []
+        x[y['type']] << y
+        x
+      }
+    end
+
+    #
+    # return type/value from a datastructure like
+    # {
+    #   "data": "808 456 7890",
+    #   "mobile": true
+    # }
+    # -----> "type"=>"mobile", "value"=>"808 456 7890"
+    #
+    def self.get_type_value(hash)
+      type_field = hash.find{ |x| x[1] == true }
+      type = type_field  ? type_field[0] : nil
+      {"type" => type, "value" => hash["data"]}
+    end
+    
+    #
+    # return just the type from a datastructure like
+    # {
+    #   "data": "808 456 7890",
+    #   "mobile": true
+    # }
+    # -----> "mobile"
+    #
+    def self.get_type(hash)
+      type_field = hash.find{ |x| x[1] == true }
+      type = type_field  ? type_field[0] : nil
+    end
+
+  end
+  class YahooToken
+    attr_reader :token
+    def initialize(token)
+      @token = token
+    end
+  end
+end