import-pojo 0.5.1

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2008 Mislav Marohnić
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.rdoc

@@ -0,0 +1,47 @@
+== Basic usage instructions
+
+Fetch users' contact lists from your web application without asking them to
+provide their passwords.
+
+First, register[http://code.google.com/apis/accounts/docs/RegistrationForWebAppsAuto.html]
+your application's domain. Then make users follow this URL:
+
+  Contacts::Google.authentication_url('http://mysite.com/invite')
+
+They will authenticate on Google and it will send them back to the URL
+provided. Google will add a token GET parameter to the query part of the URL.
+Use that token in the next step:
+
+  gmail = Contacts::Google.new('example@gmail.com', params[:token])
+  contacts = gmail.contacts
+  #-> [ ['Fitzgerald', 'fubar@gmail.com', 'fubar@example.com'],
+        ['William Paginate', 'will.paginate@gmail.com'], ...
+        ]
+
+Read more in Contacts::Google. I plan to support more APIs (Microsoft Live, for
+starters); feel free to contribute.
+
+Author: <b>Mislav Marohnić</b> (mislav.marohnic@gmail.com)
+
+== Documentation auto-generated from specifications
+
+Contacts::Google.authentication_url
+- generates a URL for target with default parameters
+- should handle boolean parameters
+- skips parameters that have nil value
+- should be able to exchange one-time for session token
+
+Contacts::Google
+- fetches contacts feed via HTTP GET
+- handles a normal response body
+- handles gzipped response
+- raises a FetchingError when something goes awry
+- parses the resulting feed into name/email pairs
+- parses a complex feed into name/email pairs
+- makes modification time available after parsing
+
+Contacts::Google GET query parameter handling
+- abstracts ugly parameters behind nicer ones
+- should have implicit :descending with :order
+- should have default :limit of 200
+- should skip nil values in parameters

data/Rakefile

@@ -0,0 +1,55 @@
+require 'spec/rake/spectask'
+require 'rake/rdoctask'
+
+task :default => :spec
+
+spec_opts = 'spec/spec.opts'
+spec_glob = FileList['spec/**/*_spec.rb']
+libs = ['lib', 'spec', 'vendor/fakeweb/lib']
+
+desc 'Run all specs in spec directory'
+Spec::Rake::SpecTask.new(:spec) do |t|
+  t.libs = libs
+  t.spec_opts = ['--options', spec_opts]
+  t.spec_files = spec_glob
+  # t.warning = true
+end
+
+namespace :spec do
+  desc 'Analyze spec coverage with RCov'
+  Spec::Rake::SpecTask.new(:rcov) do |t|
+    t.libs = libs
+    t.spec_files = spec_glob
+    t.spec_opts = ['--options', spec_opts]
+    t.rcov = true
+    t.rcov_opts = lambda do
+      IO.readlines('spec/rcov.opts').map { |l| l.chomp.split(" ") }.flatten
+    end
+  end
+  
+  desc 'Print Specdoc for all specs'
+  Spec::Rake::SpecTask.new(:doc) do |t|
+    t.libs = libs
+    t.spec_opts = ['--format', 'specdoc', '--dry-run']
+    t.spec_files = spec_glob
+  end
+  
+  desc 'Generate HTML report'
+  Spec::Rake::SpecTask.new(:html) do |t|
+    t.libs = libs
+    t.spec_opts = ['--format', 'html:doc/spec.html', '--diff']
+    t.spec_files = spec_glob
+    t.fail_on_error = false
+  end
+end
+
+desc 'Generate RDoc documentation'
+Rake::RDocTask.new(:rdoc) do |rdoc|
+  rdoc.rdoc_files.add ['README.rdoc', 'MIT-LICENSE', 'lib/**/*.rb']
+  rdoc.main = 'README.rdoc'
+  rdoc.title = 'Ruby Contacts library'
+  
+  rdoc.rdoc_dir = 'doc'
+  rdoc.options << '--inline-source'
+  rdoc.options << '--charset=UTF-8'
+end

data/lib/contacts.rb

@@ -0,0 +1,46 @@
+require 'contacts/version'
+
+module Contacts
+  
+  Identifier = 'Ruby Contacts v' + VERSION::STRING
+  
+  # An object that represents a single contact
+  class Contact
+    attr_reader :name, :username, :emails
+    
+    def initialize(email, name = nil, username = nil)
+      @emails = []
+      @emails << email if email
+      @name = name
+      @username = username
+    end
+    
+    def email
+      @emails.first
+    end
+    
+    def inspect
+      %!#<Contacts::Contact "#{name}"#{email ? " (#{email})" : ''}>!
+    end
+  end
+  
+  def self.verbose?
+    'irb' == $0
+  end
+  
+  class Error < StandardError
+  end
+  
+  class TooManyRedirects < Error
+    attr_reader :response, :location
+    
+    MAX_REDIRECTS = 2
+    
+    def initialize(response)
+      @response = response
+      @location = @response['Location']
+      super "exceeded maximum of #{MAX_REDIRECTS} redirects (Location: #{location})"
+    end
+  end
+  
+end

data/lib/contacts/flickr.rb

@@ -0,0 +1,133 @@
+require 'contacts'
+
+require 'rubygems'
+require 'hpricot'
+require 'md5'
+require 'cgi'
+require 'time'
+require 'zlib'
+require 'stringio'
+require 'net/http'
+
+module Contacts
+  
+  class Flickr
+    DOMAIN = 'api.flickr.com'
+    ServicesPath = '/services/rest/'
+
+    def self.frob_url(key, secret)
+      url_for(:api_key => key, :secret => secret, :method => 'flickr.auth.getFrob')
+    end
+    
+    def self.frob_from_response(response)
+      doc = Hpricot::XML response.body
+      doc.at('frob').inner_text
+    end
+    
+    def self.authentication_url_for_frob(frob, key, secret)
+      params = { :api_key => key, :secret => secret, :perms => 'read', :frob => frob }
+      'http://www.flickr.com/services/auth/?' + query_string(params)
+    end
+
+    def self.authentication_url(key, secret)
+      response = http_start do |flickr|
+        flickr.get(frob_url(key, secret))
+      end
+      authentication_url_for_frob(frob_from_response(response), key, secret)
+    end
+    
+    def self.token_url(key, secret, frob)
+      params = { :api_key => key, :secret => secret, :frob => frob, :method => 'flickr.auth.getToken' }
+      url_for(params)
+    end
+    
+    def self.get_token_from_frob(key, secret, frob)
+      response = http_start do |flickr|
+        flickr.get(token_url(key, secret, frob))
+      end
+      doc = Hpricot::XML response.body
+      doc.at('token').inner_text
+    end
+    
+    private
+      # Use the key-sorted version of the parameters to construct
+      # a string, to which the secret is prepended.
+      
+      def self.sort_params(params)
+        params.sort do |a,b|
+          a.to_s <=> b.to_s
+        end
+      end
+      
+      def self.string_to_sign(params, secret)
+        string_to_sign = secret + sort_params(params).inject('') do |str, pair|
+          key, value = pair
+          str + key.to_s + value.to_s
+        end
+      end
+
+      # Get the MD5 digest of the string to sign
+      def self.get_signature(params, secret)
+        ::Digest::MD5.hexdigest(string_to_sign(params, secret))
+      end
+      
+      def self.query_string(params)
+        secret = params.delete(:secret)
+        params[:api_sig] = get_signature(params, secret)
+        
+        params.inject([]) do |arr, pair|
+          key, value = pair
+          arr << "#{key}=#{value}"
+        end.join('&')
+      end
+      
+      def self.url_for(params)
+        ServicesPath + '?' + query_string(params)
+      end
+      
+      def self.http_start(ssl = false)
+        port = ssl ? Net::HTTP::https_default_port : Net::HTTP::http_default_port
+        http = Net::HTTP.new(DOMAIN, port)
+        redirects = 0
+        if ssl
+          http.use_ssl = true
+          http.verify_mode = OpenSSL::SSL::VERIFY_NONE
+        end
+        http.start
+
+        begin
+          response = yield(http)
+
+          loop do
+            inspect_response(response) if Contacts::verbose?
+
+            case response
+            when Net::HTTPSuccess
+              break response
+            when Net::HTTPRedirection
+              if redirects == TooManyRedirects::MAX_REDIRECTS
+                raise TooManyRedirects.new(response)
+              end
+              location = URI.parse response['Location']
+              puts "Redirected to #{location}"
+              response = http.get(location.path)
+              redirects += 1
+            else
+              response.error!
+            end
+          end
+        ensure
+          http.finish
+        end
+      end
+            
+      def self.inspect_response(response, out = $stderr)
+        out.puts response.inspect
+        for name, value in response
+          out.puts "#{name}: #{value}"
+        end
+        out.puts "----\n#{response.body}\n----" unless response.body.empty?
+      end
+  end
+  
+end

data/lib/contacts/google.rb

@@ -0,0 +1,308 @@
+require 'contacts'
+
+require 'rubygems'
+require 'hpricot'
+require 'cgi'
+require 'time'
+require 'zlib'
+require 'stringio'
+require 'net/http'
+require 'net/https'
+
+module Contacts
+  # == Fetching Google Contacts
+  # 
+  # First, get the user to follow the following URL:
+  # 
+  #   Contacts::Google.authentication_url('http://mysite.com/invite')
+  #
+  # After he authenticates successfully to Google, it will redirect him back to the target URL
+  # (specified as argument above) and provide the token GET parameter. Use it to create a
+  # new instance of this class and request the contact list:
+  #
+  #   gmail = Contacts::Google.new(params[:token])
+  #   contacts = gmail.contacts
+  #   #-> [ ['Fitzgerald', 'fubar@gmail.com', 'fubar@example.com'],
+  #         ['William Paginate', 'will.paginate@gmail.com'], ...
+  #         ]
+  #
+  # == Storing a session token
+  #
+  # The basic token that you will get after the user has authenticated on Google is valid
+  # for <b>only one request</b>. However, you can specify that you want a session token which
+  # doesn't expire:
+  # 
+  #   Contacts::Google.authentication_url('http://mysite.com/invite', :session => true)
+  #
+  # When the user authenticates, he will be redirected back with a token that can be exchanged
+  # for a session token with the following method:
+  #
+  #   token = Contacts::Google.sesion_token(params[:token])
+  #
+  # Now you have a permanent token. Store it with other user data so you can query the API
+  # on his behalf without him having to authenticate on Google each time.
+  class Google
+    DOMAIN      = 'www.google.com'
+    AuthSubPath = '/accounts/AuthSub' # all variants go over HTTPS
+    ClientLogin = '/accounts/ClientLogin'
+    FeedsPath   = '/m8/feeds/contacts/'
+    
+    # default options for #authentication_url
+    def self.authentication_url_options
+      @authentication_url_options ||= {
+        :scope => "http://#{DOMAIN}#{FeedsPath}",
+        :secure => false,
+        :session => false
+      }
+    end
+    
+    # default options for #client_login
+    def self.client_login_options
+      @client_login_options ||= {
+        :accountType => 'GOOGLE',
+        :service => 'cp',
+        :source => 'Contacts-Ruby'
+      }
+    end
+
+    # URL to Google site where user authenticates. Afterwards, Google redirects to your
+    # site with the URL specified as +target+.
+    #
+    # Options are:
+    # * <tt>:scope</tt> -- the AuthSub scope in which the resulting token is valid
+    #   (default: "http://www.google.com/m8/feeds/contacts/")
+    # * <tt>:secure</tt> -- boolean indicating whether the token will be secure. Only available
+    #   for registered domains.
+    #   (default: false)
+    # * <tt>:session</tt> -- boolean indicating if the token can be exchanged for a session token
+    #   (default: false)
+    def self.authentication_url(target, options = {})
+      params = authentication_url_options.merge(options)
+      params[:next] = target
+      query = query_string(params)
+      "https://#{DOMAIN}#{AuthSubPath}Request?#{query}"
+    end
+
+    # Makes an HTTPS request to exchange the given token with a session one. Session
+    # tokens never expire, so you can store them in the database alongside user info.
+    #
+    # Returns the new token as string or nil if the parameter couldn't be found in response
+    # body.
+    def self.session_token(token)
+      response = http_start do |google|
+        google.get(AuthSubPath + 'SessionToken', authorization_header(token))
+      end
+
+      pair = response.body.split(/\n/).detect { |p| p.index('Token=') == 0 }
+      pair.split('=').last if pair
+    end
+    
+    # Alternative to AuthSub: using email and password.
+    def self.client_login(email, password)
+      response = http_start do |google|
+        query = query_string(client_login_options.merge(:Email => email, :Passwd => password))
+        puts "posting #{query} to #{ClientLogin}" if Contacts::verbose?
+        google.post(ClientLogin, query)
+      end
+
+      pair = response.body.split(/\n/).detect { |p| p.index('Auth=') == 0 }
+      pair.split('=').last if pair
+    end
+    
+    attr_reader :user, :token, :headers
+    attr_accessor :projection
+
+    # A token is required here. By default, an AuthSub token from
+    # Google is one-time only, which means you can only make a single request with it.
+    def initialize(token, user_id = 'default', client = false)
+      @user    = user_id.to_s
+      @token   = token.to_s
+      @headers = {
+        'Accept-Encoding' => 'gzip',
+        'User-Agent' => Identifier + ' (gzip)'
+      }.update(self.class.authorization_header(@token, client))
+      @projection = 'thin'
+    end
+
+    def get(params) # :nodoc:
+      self.class.http_start(false) do |google|
+        path = FeedsPath + CGI.escape(@user)
+        google_params = translate_parameters(params)
+        query = self.class.query_string(google_params)
+        google.get("#{path}/#{@projection}?#{query}", @headers)
+      end
+    end
+
+    # Timestamp of last update. This value is available only after the XML
+    # document has been parsed; for instance after fetching the contact list.
+    def updated_at
+      @updated_at ||= Time.parse @updated_string if @updated_string
+    end
+
+    # Timestamp of last update as it appeared in the XML document
+    def updated_at_string
+      @updated_string
+    end
+
+    # Fetches, parses and returns the contact list.
+    #
+    # ==== Options
+    # * <tt>:limit</tt> -- use a large number to fetch a bigger contact list (default: 200)
+    # * <tt>:offset</tt> -- 0-based value, can be used for pagination
+    # * <tt>:order</tt> -- currently the only value support by Google is "lastmodified"
+    # * <tt>:descending</tt> -- boolean
+    # * <tt>:updated_after</tt> -- string or time-like object, use to only fetch contacts
+    #   that were updated after this date
+    def contacts(options = {})
+      params = { :limit => 200 }.update(options)
+      response = get(params)
+      parse_contacts response_body(response)
+    end
+    
+    # Fetches contacts using multiple API calls when necessary
+    def all_contacts(options = {}, chunk_size = 200)
+      in_chunks(options, :contacts, chunk_size)
+    end
+
+    protected
+    
+      def in_chunks(options, what, chunk_size)
+        returns = []
+        offset = 0
+        
+        begin
+          chunk = send(what, options.merge(:offset => offset, :limit => chunk_size))
+          returns.push(*chunk)
+          offset += chunk_size
+        end while chunk.size == chunk_size 
+        
+        returns
+      end
+      
+      def response_body(response)
+        unless response['Content-Encoding'] == 'gzip'
+          response.body
+        else
+          gzipped = StringIO.new(response.body)
+          Zlib::GzipReader.new(gzipped).read
+        end
+      end
+      
+      def parse_contacts(body)
+        doc = Hpricot::XML body
+        contacts_found = []
+        
+        if updated_node = doc.at('/feed/updated')
+          @updated_string = updated_node.inner_text
+        end
+        
+        (doc / '/feed/entry').each do |entry|
+          email_nodes = entry / 'gd:email[@address]'
+          
+          unless email_nodes.empty?
+            title_node = entry.at('/title')
+            name = title_node ? title_node.inner_text : nil
+            contact = Contact.new(nil, name)
+            contact.emails.concat email_nodes.map { |e| e['address'].to_s }
+            contacts_found << contact
+          end
+        end
+
+        contacts_found
+      end
+      
+      # Constructs a query string from a Hash object
+      def self.query_string(params)
+        params.inject([]) do |all, pair|
+          key, value = pair
+          unless value.nil?
+            value = case value
+              when TrueClass;  '1'
+              when FalseClass; '0'
+              else value
+              end
+
+            all << "#{CGI.escape(key.to_s)}=#{CGI.escape(value.to_s)}"
+          end
+          all
+        end.join('&')
+      end
+
+      def translate_parameters(params)
+        params.inject({}) do |all, pair|
+          key, value = pair
+          unless value.nil?
+            key = case key
+              when :limit
+                'max-results'
+              when :offset
+                value = value.to_i + 1
+                'start-index'
+              when :order
+                all['sortorder'] = 'descending' if params[:descending].nil?
+                'orderby'
+              when :descending
+                value = value ? 'descending' : 'ascending'
+                'sortorder'
+              when :updated_after
+                value = value.strftime("%Y-%m-%dT%H:%M:%S%Z") if value.respond_to? :strftime
+                'updated-min'
+              else key
+              end
+            
+            all[key] = value
+          end
+          all
+        end
+      end
+      
+      def self.authorization_header(token, client = false)
+        type = client ? 'GoogleLogin auth' : 'AuthSub token'
+        { 'Authorization' => %(#{type}="#{token}") }
+      end
+      
+      def self.http_start(ssl = true)
+        port = ssl ? Net::HTTP::https_default_port : Net::HTTP::http_default_port
+        http = Net::HTTP.new(DOMAIN, port)
+        redirects = 0
+        if ssl
+          http.use_ssl = true
+          http.verify_mode = OpenSSL::SSL::VERIFY_NONE
+        end
+        http.start
+
+        begin
+          response = yield(http)
+
+          loop do
+            inspect_response(response) if Contacts::verbose?
+
+            case response
+            when Net::HTTPSuccess
+              break response
+            when Net::HTTPRedirection
+              if redirects == TooManyRedirects::MAX_REDIRECTS
+                raise TooManyRedirects.new(response)
+              end
+              location = URI.parse response['Location']
+              puts "Redirected to #{location}"
+              response = http.get(location.path)
+              redirects += 1
+            else
+              response.error!
+            end
+          end
+        ensure
+          http.finish
+        end
+      end
+
+      def self.inspect_response(response, out = $stderr)
+        out.puts response.inspect
+        for name, value in response
+          out.puts "#{name}: #{value}"
+        end
+        out.puts "----\n#{response_body response}\n----" unless response.body.empty?
+      end
+  end
+end

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
+      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
+        new_contact = Contact.new(email, name)
+        contacts << new_contact
+      end
+
+      return contacts
+    end
+  end
+
+end

data/lib/contacts/yahoo.rb

@@ -0,0 +1,240 @@
+require 'contacts'
+
+require 'rubygems'
+require 'hpricot'
+require 'md5'
+require 'net/https'
+require 'uri'
+require 'yaml'
+require 'json' unless defined? ActiveSupport::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=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.
+    #
+    # ==== Parameters
+    # * json <String>:: A String of user's contacts in JSON format
+    #
+    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
+
+  end
+end

metadata

@@ -0,0 +1,73 @@
+--- !ruby/object:Gem::Specification 
+name: import-pojo
+version: !ruby/object:Gem::Version 
+  prerelease: false
+  segments: 
+  - 0
+  - 5
+  - 1
+  version: 0.5.1
+platform: ruby
+authors: 
+- Josiah Kiehl
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-03-15 00:00:00 -04:00
+default_executable: 
+dependencies: []
+
+description: |-
+  Lib to pull contacts from Gmail, Yahoo!, Windows Live, and Flickr.  This lib uses authentication tokens rather than requiring the user to enter their private credentials. This is a fork from rscarvalho/contacts (which is a fork of mislav/contacts).  
+  
+   I couldn't track down a published gem, so I made one.
+email: bluepojo+rubygems@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- lib/contacts/version.rb
+- lib/contacts/windows_live.rb
+- lib/contacts/yahoo.rb
+- lib/contacts/google.rb
+- lib/contacts/flickr.rb
+- lib/contacts.rb
+- Rakefile
+- README.rdoc
+- MIT-LICENSE
+has_rdoc: true
+homepage: http://github.com/bluepojo/contacts/
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.6
+signing_key: 
+specification_version: 3
+summary: Lib to pull contacts from Gmail, Yahoo!, Windows Live, and Flickr.
+test_files: []
+