nullstyle-contacts 0.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,49 @@
+require 'spec/rake/spectask'
+require 'rake/rdoctask'
+
+task :default => :spec
+
+spec_opts = 'spec/spec.opts'
+spec_glob = FileList['spec/**/*_spec.rb']
+
+desc 'Run all specs in spec directory'
+Spec::Rake::SpecTask.new(:spec) do |t|
+  t.spec_opts = ['--options', spec_opts]
+  t.spec_files = spec_glob
+end
+
+namespace :spec do
+  desc 'Run all specs in spec directory with RCov'
+  Spec::Rake::SpecTask.new(:rcov) do |t|
+    t.spec_opts = ['--options', spec_opts]
+    t.spec_files = spec_glob
+    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.spec_opts = ['--format', 'specdoc', '--dry-run']
+    t.spec_files = spec_glob
+  end
+  
+  desc 'Generate HTML report'
+  Spec::Rake::SpecTask.new(:html) do |t|
+    t.spec_opts = ['--format', 'html:doc/spec_results.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 = 'Google Contacts API'
+  
+  rdoc.rdoc_dir = 'doc'
+  rdoc.options << '--inline-source'
+  rdoc.options << '--charset=UTF-8'
+end

data/contacts.gemspec

@@ -0,0 +1,30 @@
+Gem::Specification.new do |s|
+  s.name = "contacts"
+  s.version = "0.1"
+  s.date = "2008-04-29"
+  s.summary = "import contacts from google Contacts API"
+  s.email = "mislav.marohnic@gmail.com"
+  s.homepage = "http://test-spec.rubyforge.org"
+  
+  s.description = <<EOF
+  Fetch users' contact lists from your web application without asking them to
+  provide their passwords.
+EOF
+
+  s.has_rdoc = true
+  s.authors = ["Mislav Marohnić", "Scott Fleckenstein"]
+  
+  s.files = [
+    "README.rdoc",
+    "MIT-LICENSE",
+    "Rakefile", 
+    "contacts.gemspec", 
+    "lib/contacts/google.rb",
+    "lib/contacts.rb",
+  ]
+  
+  s.test_files = []
+  
+  s.rdoc_options = ["--main", "README.rdoc"]
+  s.extra_rdoc_files = ["README.rdoc"]
+end

data/lib/contacts.rb

@@ -0,0 +1,10 @@
+module Contacts
+  class FetchingError < RuntimeError
+    attr_reader :response
+    
+    def initialize(response)
+      @response = response
+      super "expected HTTPSuccess, got #{response.class} (#{response.code} #{response.message})"
+    end
+  end
+end

data/lib/contacts/google.rb

@@ -0,0 +1,213 @@
+require 'contacts'
+require 'cgi'
+require 'net/http'
+require 'net/https'
+require 'rubygems'
+require 'hpricot'
+require 'time'
+require 'zlib'
+require 'stringio'
+
+module Contacts
+  # == Fetching Google Contacts
+  # 
+  # Web applications should use
+  # AuthSub[http://code.google.com/apis/contacts/developers_guide_protocol.html#auth_sub]
+  # proxy authentication to get an authentication token for a Google account.
+  # 
+  # First, get the user to follow the following URL:
+  # 
+  #   Contacts::Google.authentication_url('http://mysite.com/invite')
+  #
+  # After he authenticates successfully, Google 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('example@gmail.com', 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 only one request. 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 which still isn't
+  # a session token, but can be exchanged for one!
+  #
+  #   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
+    AuthScope   = "http://#{DOMAIN}/m8/feeds/"
+
+    # 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/")
+    # * <tt>:secure</tt> -- boolean indicating whether the token will be secure
+    #   (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 = { :next => target,
+                 :scope => AuthScope,
+                 :secure => false,
+                 :session => false
+               }.merge(options)
+               
+      query = params.inject [] do |url, pair|
+        unless pair.last.nil?
+          value = case pair.last
+            when TrueClass; 1
+            when FalseClass; 0
+            else pair.last
+            end
+          
+          url << "#{pair.first}=#{CGI.escape(value.to_s)}"
+        end
+        url
+      end.join('&')
+
+      "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 couln't be found in response
+    # body.
+    def self.session_token(token)
+      response = Net::HTTP.start(DOMAIN) do |google|
+        google.use_ssl
+        google.verify_mode = OpenSSL::SSL::VERIFY_NONE
+        google.get(AuthSubPath + 'SessionToken', auth_headers(token))
+      end
+
+      pair = response.body.split(/\s+/).detect {|p| p.index('Token') == 0 }
+      pair.split('=').last if pair
+    end
+
+    # User ID (email) and token are 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(user_id, token)
+      @user = user_id.to_s
+      @headers = { 'Accept-Encoding' => 'gzip' }.update(self.class.auth_headers(token))
+      @base_path = "/m8/feeds/contacts/#{CGI.escape(@user)}/base"
+    end
+
+    def get(params) #:nodoc:
+      response = Net::HTTP.start(DOMAIN) do |google|
+        google.get(@base_path + '?' + query_string(params), @headers)
+      end
+
+      raise FetchingError.new(response) unless response.is_a? Net::HTTPSuccess
+
+      response
+    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
+
+    protected
+      
+      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 self.auth_headers(token)
+        { 'Authorization' => %(AuthSub token=#{token.to_s.inspect}) }
+      end
+      
+      def parse_contacts(body)
+        doc = Hpricot::XML body
+        entries = []
+        
+        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
+            
+            person = email_nodes.inject [name] do |p, e|
+              p << e['address'].to_s
+            end
+            entries << person
+          end
+        end
+
+        entries
+      end
+
+      def query_string(params)
+        params.inject [] do |url, pair|
+          value = pair.last
+          unless value.nil?
+            key = case pair.first
+              when :limit
+                'max-results'
+              when :offset
+                value = value.to_i + 1
+                'start-index'
+              when :order
+                url << '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 pair.first
+              end
+            
+            url << "#{key}=#{CGI.escape(value.to_s)}"
+          end
+          url
+        end.join('&')
+      end
+  end
+end

metadata

@@ -0,0 +1,60 @@
+--- !ruby/object:Gem::Specification 
+name: nullstyle-contacts
+version: !ruby/object:Gem::Version 
+  version: "0.1"
+platform: ruby
+authors: 
+- "Mislav Marohni\xC4\x87"
+- Scott Fleckenstein
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2008-04-29 00:00:00 -07:00
+default_executable: 
+dependencies: []
+
+description: Fetch users' contact lists from your web application without asking them to provide their passwords.
+email: mislav.marohnic@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README.rdoc
+files: 
+- README.rdoc
+- MIT-LICENSE
+- Rakefile
+- contacts.gemspec
+- lib/contacts/google.rb
+- lib/contacts.rb
+has_rdoc: true
+homepage: http://test-spec.rubyforge.org
+post_install_message: 
+rdoc_options: 
+- --main
+- README.rdoc
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.0.1
+signing_key: 
+specification_version: 2
+summary: import contacts from google Contacts API
+test_files: []
+