pietern-contacts 0.1.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,79 @@
+== 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
+  contacts.select { |c| c.name }
+  #-> ['Fitzgerald', 'William Paginate', ... ]
+  
+Although this is quite nice, it won't use this library to it's fullest power.
+Instead, ask for a session token, which remains valid after subsequent requests,
+via this URL:
+
+  Contacts::Google.authentication_url('http://mysite.com/invite', :session => true)
+  
+The user will authenticate just like the previous example, but the token you get
+back can be used to acquire a session token like this:
+
+  Contacts::Google.session_token(params[:token])
+  
+This token can be used to instantiate a new Contacts::Google object which you can
+use like this:
+
+  gmail = Contacts::Google.new('example@gmail.com', my_session_token)
+  
+  # Fetch all contacts (in chunks, so this will render really ALL the contacts)
+  contacts = gmail.all_contacts
+  
+  # Set some parameters and update all contacts
+  contacts.each do |c|
+    c.name += " (appended string)"
+    c['my_custom_parameter'] = "something"
+    c.update!
+  end
+  
+  # Add a new contact
+  new_contact = gmail.new_contact(:name => 'Pieter', :email => 'email@some.host.com')
+  new_contact.create!
+  
+  # Russian roulette!
+  another_contact = gmail.all_contacts.choice # Pick a random contact
+  another_contact.delete!
+
+The contact objects take the methods +name+ and +email+ for direct access to the 
+most important fields for your contact. The Google Data API provides a 
+<tt>gd:extendedProperty</tt> tag for custom parameters. You can use this tag via
+the <tt>[]</tt> and <tt>[]=</tt> methods.
+
+The example stated above will be extremely slow if you have a lot of contacts. To
+provide easy manipulation of large sets of contacts, you can use the batch method:
+
+  gmail.batch_contacts do
+    # Create, update and delete contacts, as long as you don't execute
+    # more than one action per contact in one batch. This won't
+    # report errors, but doesn't succeed.
+  end
+
+This will result in a single POST request for every 100 operations. Because you
+cannot batch operations to both contacts and groups, the batch method <tt>batch_groups</tt>
+is provided for handling a lot of groups.
+
+Make sure you don't issue multiple operations per contact each batch! After one request
+for a contact, it needs to be reloaded.
+
+More can be read in the rdoc of this lib, although they are not complete
+
+Authors:<br/>
+<b>Mislav Marohnić</b> (mislav.marohnic@gmail.com) (initial codebase)<br/>
+<b>Pieter Noordhuis</b> (pcnoordhuis@gmail.com) (further development)<br/>

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.1"
+  s.date     = "2008-08-02"
+  s.summary  = "Interfacing with the Google Contacts API"
+  s.email    = "tom@rubyisawesome.com"
+  s.homepage = "http://github.com/pietern/contacts"
+  s.description = "Provides easy access and manipulation with the Google Contacts API"
+  s.has_rdoc = true
+  s.authors  = ["Mislav Marohnić", "Pieter Noordhuis"]
+  s.files = [
+    "lib/contacts",
+    "lib/contacts/google.rb",
+    "lib/contacts.rb",
+    "spec/feeds",
+    "spec/feeds/google-many.xml",
+    "spec/feeds/google-single.xml",
+    "spec/gmail",
+    "spec/gmail/auth_spec.rb",
+    "spec/gmail/fetching_spec.rb",
+    "spec/spec.opts",
+    "spec/spec_helper.rb",
+    "contacts.gemspec",
+    "Rakefile",
+    "README.rdoc",
+    "MIT-LICENSE"
+  ]
+  #s.rdoc_options = ["--main", "README.rdoc"]
+  s.add_dependency("hpricot", [">= 0.6"])
+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,547 @@
+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)
+      http = Net::HTTP.new(DOMAIN, 443)
+      http.use_ssl = true
+      http.verify_mode = OpenSSL::SSL::VERIFY_NONE
+      response = http.request_get(AuthSubPath + 'SessionToken', auth_headers(token))
+
+      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',
+        'User-Agent' => 'agent-that-accepts-gzip',
+      }.update(self.class.auth_headers(token))
+      @in_batch = false
+    end
+    
+    PATH = {
+      'contacts_full' => '/m8/feeds/contacts/default/full',
+      'contacts_batch' => '/m8/feeds/contacts/default/full/batch',
+      'groups_full' => '/m8/feeds/groups/default/full',
+      'groups_batch' => '/m8/feeds/groups/default/full/batch',
+    }
+
+    def get(path, params) #:nodoc:
+      response = Net::HTTP.start(DOMAIN) do |google|
+        google.get(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
+
+    def post(url, body, headers)
+      if @in_batch
+        @batch_request << [body, headers]
+      else
+        response = Net::HTTP.start(DOMAIN) do |google|
+          google.post(url, body.to_s, @headers.merge(headers))
+        end
+        
+        raise FetchingError.new(response) unless response.is_a? Net::HTTPSuccess
+
+        response
+      end
+    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(PATH['contacts_full'], params)
+      parse_contacts response_body(response)
+    end
+    
+    # Fetches, parses and returns the group list.
+    #
+    # ==== Options
+    # see contacts
+    def groups(options = {})
+      params = { :limit => 200 }.update(options)
+      response = get(PATH['groups_full'], params)
+      parse_groups response_body(response)
+    end
+    
+    # Fetches all contacts in chunks of 200.
+    #
+    # For example: if you have 1000 contacts, this will render in 5 GET requests
+    def all_contacts
+      ret = []
+      chunk_size = 200
+      offset = 0
+      
+      while (chunk = contacts(:limit => chunk_size, :offset => offset)).size != 0
+        ret.push(*chunk)
+        offset += chunk_size
+        break if chunk.size < chunk_size
+      end
+      ret
+    end
+    
+    def all_groups
+      ret = []
+      chunk_size = 200
+      offset = 0
+      
+      while (chunk = groups(:limit => chunk_size, :offset => offset)).size != 0
+        ret.push(*chunk)
+        offset += chunk_size
+      end
+      ret
+    end
+    
+    def new_contact(attr = {})
+      c = Contact.new(self)
+      c.load_attributes(attr)
+    end
+    
+    def new_group(attr = {})
+      g = Group.new(self)
+      g.load_attributes(attr)
+    end
+    
+    def batch_contacts(&blk)
+      batch(PATH['contacts_batch'], &blk)
+    end
+    
+    def batch_groups(&blk)
+      batch(PATH['groups_batch'], &blk)
+    end
+    
+    def batch(url, &blk)
+      # Init
+      limit = 512 * 1024
+      @batch_request = []
+      @in_batch = true
+
+      # Execute the block
+      yield
+
+      # Pack post-request in batch job(s)
+      while !@batch_request.empty?
+        doc = Hpricot("<?xml version='1.0' encoding='UTF-8'?>\n<feed/>", :xml => true)
+        root = doc.root
+        root['xmlns'] = 'http://www.w3.org/2005/Atom'
+        root['xmlns:gContact'] = 'http://schemas.google.com/contact/2008'
+        root['xmlns:gd'] = 'http://schemas.google.com/g/2005'
+        root['xmlns:batch'] = 'http://schemas.google.com/gdata/batch'
+
+        size = doc.to_s.size
+        100.times do
+          break if size >= limit || @batch_request.empty?
+          r = @batch_request.shift
+
+          # Get stuff for request
+          headers = r[1]
+          xml = r[0]
+
+          # Delete all namespace attributes
+          xml.root.attributes.each { |a,v| xml.root.remove_attribute(a) if a =~ /^xmlns/ }
+
+          # Find out what to do
+          operation = case headers['X-HTTP-Method-Override']
+          when 'PUT'
+            'update'
+          when 'DELETE'
+            'delete'
+          else
+            'insert'
+          end
+          
+          xml.root.children << Hpricot.make("<batch:operation type='#{operation}'/>").first
+          root.children << xml.root
+          size += xml.root.to_s.size
+        end
+        
+        #puts "Doing POST... (#{size} bytes)"
+        @in_batch = false
+        post(url, doc, 'Content-Type' => 'application/atom+xml')
+        @in_batch = true
+      end
+      @in_batch = false
+    end
+
+    class Base
+      attr_reader :gmail, :xml
+      
+      BASE_XML = "<entry><category scheme='http://schemas.google.com/g/2005#kind' /><title type='text' /></entry>"
+      
+      def initialize(gmail, xml = nil)
+        xml = BASE_XML if xml.nil?
+        @xml = Hpricot(xml.to_s, :xml => true)
+        @gmail = gmail
+      end
+      
+      def load_attributes(attr)
+        attr.each do |k,v|
+          self.send((k.to_s+"=").to_sym, v)
+        end
+        self
+      end
+      
+      def new?
+        @xml.at('id').nil?
+      end
+      
+      def id
+        @xml.at('id').inner_html unless new?
+      end
+      
+      def name
+        @xml.at('title').inner_html
+      end
+      
+      def name=(str)
+        @xml.at('title').inner_html = str
+      end
+      
+      def [](attr)
+        el = get_extended_property(attr)
+        return nil if el.nil?
+        
+        if el.has_attribute?('value')
+          el['value']
+        else
+          Hpricot(el.inner_html)
+        end
+      end
+      
+      def []=(attr, value)
+        el = get_extended_property(attr)
+        
+        # Create element if it not already exists
+        if el.nil?
+          @xml.root.children.push *Hpricot.make("<gd:extendedProperty name='#{attr}' />")
+          el = get_extended_property(attr)
+        end
+        
+        if value.kind_of?(Hpricot)
+          # If value is valid XML, set as element content
+          el.remove_attribute('value')
+          el.inner_html = value.to_s
+        else
+          # If value is not XML, set as value-attribute
+          el['value'] = value
+          el.inner_html = ''
+        end
+        value
+      end
+      
+      def create_url
+        raise "Contacts::Google::Base must be subclassed!"
+      end
+      
+      def edit_url
+        @xml.at("link[@rel='edit']")['href'].gsub(/^http:\/\/www.google.com(\/.*)$/, '\1') unless new?
+      end
+      
+      def create!
+        raise "Cannot create existing entry" unless new?
+        response = gmail.post(create_url, document_for_request, {
+          'Content-Type' => 'application/atom+xml'
+        })
+      end
+      
+      def update!
+        raise "Cannot update new entry" if new?
+        response = gmail.post(edit_url, document_for_request,
+          'Content-Type' => 'application/atom+xml',
+          'X-HTTP-Method-Override' => 'PUT'
+        )
+      end
+
+      def delete!
+        raise "Cannot delete new entry" if new?
+        gmail.post(edit_url, document_for_request,
+          'X-HTTP-Method-Override' => 'DELETE'
+        )
+      end
+      
+      protected
+        def document_for_request
+          # Make a new document from this entry, specify :xml => true to make sure Hpricot
+          # doesn't downcase all tags, which results in bad input to Google
+          atom = Hpricot(@xml.to_s, { :xml => true })
+
+          # Remove <updated> tag (not necessary, but results in smaller XML)
+          # Make sure not to delete the <link> tags, they seem unnecessary
+          # but result in strange errors while making batch requests
+          (atom / 'updated').remove
+          
+          # Set the right namespaces
+          root = atom.at('entry')
+          root['xmlns'] = 'http://www.w3.org/2005/Atom'
+          root['xmlns:gd'] = 'http://schemas.google.com/g/2005'
+          root['xmlns:gContact'] = 'http://schemas.google.com/contact/2008'
+          
+          after_document_for_request_hook(atom)
+        end
+        
+        def after_document_for_request_hook(xml)
+          xml
+        end
+        
+        def get_extended_property(attr)
+          raise "Attribute naming error" if attr =~ /['\[\]]/
+          @xml.at("gd:extendedProperty[@name='#{attr}']")
+        end
+    end
+
+    class Contact < Base
+      attr_reader :groups
+      
+      PRIMARY_EMAIL_TAG = "<gd:email rel='http://schemas.google.com/g/2005#home' primary='true' address='' />"
+      
+      def initialize(gmail, xml = nil)
+        super(gmail, xml)
+        
+        if xml.nil?
+          # Specific constructs for a contact
+          @xml.at('category')['term'] = "http://schemas.google.com/contact/2008#contact"
+          @xml.root.children.push *Hpricot.make(PRIMARY_EMAIL_TAG)
+        end
+        
+        @groups = []
+        (@xml / 'gContact:groupMembershipInfo').each do |e|
+          @groups << e['href']
+        end
+        
+        # All groups are saved in an array for easy access
+        (@xml / 'gContact:groupMembershipInfo').remove
+      end
+      
+      def create_url
+        '/m8/feeds/contacts/default/full'
+        PATH['contacts_full']
+      end
+      
+      def email
+        @xml.at('gd:email')['address']
+      end
+      
+      def email=(str)
+        @xml.at('gd:email')['address'] = str
+      end
+      
+      def clear_groups!
+        @groups = []
+      end
+      
+      def add_group(group)
+        href = get_group_href(group)
+        return nil if @groups.include?(href)
+        @groups << href
+      end
+      
+      def remove_group(group)
+        href = get_group_href(group)
+        @groups.delete(href)
+      end
+      
+      protected
+        def get_group_href(group)
+          raise "Needs Group object" unless group.instance_of?(Group)
+          group.id
+        end
+        
+        def after_document_for_request_hook(xml)
+          str = ""
+          @groups.each do |href|
+            str << "<gContact:groupMembershipInfo deleted='false' href='#{href}' />"
+          end
+          xml.root.children.push *Hpricot.make(str, :xml => true)
+          xml
+        end
+    end
+    
+    class Group < Base
+      def initialize(gmail, xml = nil)
+        super(gmail, xml)
+        @xml.at('category')['term'] = 'http://schemas.google.com/contact/2008#group'
+      end
+      
+      def create_url
+        '/m8/feeds/groups/default/full'
+      end
+    end
+
+    protected
+      
+      def response_body(response)
+        unless response['Content-Encoding'] == 'gzip'
+          puts 'no 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)
+        parse_entries(body, lambda { |*args| Contact.new(*args) })
+      end
+      
+      def parse_groups(body)
+        parse_entries(body, lambda { |*args| Group.new(*args) })
+      end
+      
+      def parse_entries(body, lmbd)
+        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|
+          entries << lmbd.call(self, entry)
+        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

data/spec/feeds/google-many.xml

@@ -0,0 +1,48 @@
+<feed>
+  <entry xmlns='http://www.w3.org/2005/Atom' xmlns:gd='http://schemas.google.com/g/2005'>
+    <category scheme='http://schemas.google.com/g/2005#kind' term='http://schemas.google.com/contact/2008#contact'/>
+    <title>Elizabeth Bennet</title>
+    <content>My good friend, Liz.  A little quick to judge sometimes, but nice girl.</content>
+    <gd:email rel='http://schemas.google.com/g/2005#work' primary='true' address='liz@gmail.com'/>
+    <gd:email rel='http://schemas.google.com/g/2005#home' address='liz@example.org'/>
+    <gd:phoneNumber rel='http://schemas.google.com/g/2005#work' primary='true'>
+      (206)555-1212
+    </gd:phoneNumber>
+    <gd:phoneNumber rel='http://schemas.google.com/g/2005#home'>
+      (206)555-1213
+    </gd:phoneNumber>
+    <gd:phoneNumber rel='http://schemas.google.com/g/2005#mobile'>
+      (206) 555-1212
+    </gd:phoneNumber>
+    <gd:im rel='http://schemas.google.com/g/2005#home' 
+        protocol='http://schemas.google.com/g/2005#GOOGLE_TALK' 
+        address='liz@gmail.com'/>
+    <gd:postalAddress rel='http://schemas.google.com/g/2005#work' primary='true'>
+      1600 Amphitheatre Pkwy 
+      Mountain View, CA 94043
+    </gd:postalAddress>
+    <gd:postalAddress rel='http://schemas.google.com/g/2005#home'>
+      800 Main Street
+      Mountain View, CA 94041
+    </gd:postalAddress>
+    <gd:organization>
+      <gd:orgName>Google, Inc.</gd:orgName>
+      <gd:orgTitle>Tech Writer</gd:orgTitle>
+    </gd:organization>
+  </entry>
+  
+  <entry>
+    <title>Poor Jack</title>
+    <content>Poor Jack doesn't have an e-mail address</content>
+  </entry>
+  
+  <entry>
+    <title>William Paginate</title>
+    <gd:email address='will_paginate@googlegroups.com' />
+  </entry>
+  
+  <entry>
+    <content>This guy doesn't have a name</content>
+    <gd:email address='anonymous@example.com' />
+  </entry>
+</feed>

data/spec/feeds/google-single.xml

@@ -0,0 +1,46 @@
+<!-- source: http://code.google.com/apis/contacts/developers_guide_protocol.html -->
+<feed xmlns='http://www.w3.org/2005/Atom'
+    xmlns:openSearch='http://a9.com/-/spec/opensearchrss/1.0/'
+    xmlns:gd='http://schemas.google.com/g/2005'>
+  <id>http://www.google.com/m8/feeds/contacts/liz%40gmail.com/base</id>
+  <updated>2008-03-05T12:36:38.836Z</updated>
+  <category scheme='http://schemas.google.com/g/2005#kind'
+    term='http://schemas.google.com/contact/2008#contact' />
+  <title type='text'>Contacts</title>
+  <link rel='http://schemas.google.com/g/2005#feed'
+    type='application/atom+xml'
+    href='http://www.google.com/m8/feeds/contacts/liz%40gmail.com/base' />
+  <link rel='http://schemas.google.com/g/2005#post'
+    type='application/atom+xml'
+    href='http://www.google.com/m8/feeds/contacts/liz%40gmail.com/base' />
+  <link rel='self' type='application/atom+xml'
+    href='http://www.google.com/m8/feeds/contacts/liz%40gmail.com/base?max-results=25' />
+  <author>
+    <name>Elizabeth Bennet</name>
+    <email>liz@gmail.com</email>
+  </author>
+  <generator version='1.0' uri='http://www.google.com/m8/feeds/contacts'>
+    Contacts
+  </generator>
+  <openSearch:totalResults>1</openSearch:totalResults>
+  <openSearch:startIndex>1</openSearch:startIndex>
+  <openSearch:itemsPerPage>25</openSearch:itemsPerPage>
+  <entry>
+    <id>
+      http://www.google.com/m8/feeds/contacts/liz%40gmail.com/base/c9012de
+    </id>
+    <updated>2008-03-05T12:36:38.835Z</updated>
+    <category scheme='http://schemas.google.com/g/2005#kind'
+      term='http://schemas.google.com/contact/2008#contact' />
+    <title type='text'>Fitzgerald</title>
+    <link rel='self' type='application/atom+xml'
+      href='http://www.google.com/m8/feeds/contacts/liz%40gmail.com/base/c9012de' />
+    <link rel='edit' type='application/atom+xml'
+      href='http://www.google.com/m8/feeds/contacts/liz%40gmail.com/base/c9012de/1204720598835000' />
+    <gd:phoneNumber rel='http://schemas.google.com/g/2005#home'
+      primary='true'>
+      456
+    </gd:phoneNumber>
+    <gd:email label="Personal" rel="http://schemas.google.com/g/2005#home" address="fubar@gmail.com" primary="true" />
+  </entry>
+</feed>

data/spec/gmail/auth_spec.rb

@@ -0,0 +1,48 @@
+require File.dirname(__FILE__) + '/../spec_helper'
+require 'contacts/google'
+require 'uri'
+
+describe Contacts::Google, '.authentication_url' do
+  it 'generates a URL for target with default parameters' do
+    uri = url('http://example.com/invite')
+    
+    uri.host.should == 'www.google.com'
+    uri.scheme.should == 'https'
+    uri.query.split('&').sort.should == [
+      'next=http%3A%2F%2Fexample.com%2Finvite',
+      'scope=http%3A%2F%2Fwww.google.com%2Fm8%2Ffeeds%2F',
+      'secure=0',
+      'session=0'
+      ]
+  end
+
+  it 'should handle boolean parameters' do
+    pairs = url(nil, :secure => true, :session => true).query.split('&')
+    
+    pairs.should include('secure=1')
+    pairs.should include('session=1')
+  end
+
+  it 'skips parameters that have nil value' do
+    query = url(nil, :secure => nil).query
+    query.should_not include('next')
+    query.should_not include('secure')
+  end
+
+  it 'should be able to exchange one-time for session token' do
+    connection = mock('HTTP connection')
+    response = mock('HTTP response')
+    Net::HTTP.expects(:start).with('www.google.com').yields(connection).returns(response)
+    connection.expects(:use_ssl)
+    connection.expects(:verify_mode=).with(OpenSSL::SSL::VERIFY_NONE)
+    connection.expects(:get).with('/accounts/AuthSubSessionToken', 'Authorization' => %(AuthSub token="dummytoken"))
+
+    response.expects(:body).returns("Token=G25aZ-v_8B\nExpiration=20061004T123456Z")
+
+    Contacts::Google.session_token('dummytoken').should == 'G25aZ-v_8B'
+  end
+
+  def url(*args)
+    URI.parse Contacts::Google.authentication_url(*args)
+  end
+end

data/spec/gmail/fetching_spec.rb

@@ -0,0 +1,156 @@
+require File.dirname(__FILE__) + '/../spec_helper'
+require 'contacts/google'
+
+describe Contacts::Google do
+
+  before :each do
+    @gmail = create
+  end
+
+  it 'fetches contacts feed via HTTP GET' do
+    @gmail.expects(:query_string).returns('a=b')
+    connection = mock('HTTP connection')
+    response = mock('HTTP response')
+    response.stubs(:is_a?).with(Net::HTTPSuccess).returns(true)
+    Net::HTTP.expects(:start).with('www.google.com').yields(connection).returns(response)
+    connection.expects(:get).with('/m8/feeds/contacts/example%40gmail.com/base?a=b', {
+        'Authorization' => %(AuthSub token="dummytoken"),
+        'Accept-Encoding' => 'gzip'
+      })
+
+    @gmail.get({})
+  end
+
+  it 'handles a normal response body' do
+    response = mock('HTTP response')
+    @gmail.expects(:get).returns(response)
+
+    response.expects(:'[]').with('Content-Encoding').returns(nil)
+    response.expects(:body).returns('<feed/>')
+
+    @gmail.expects(:parse_contacts).with('<feed/>')
+    @gmail.contacts
+  end
+
+  it 'handles gzipped response' do
+    response = mock('HTTP response')
+    @gmail.expects(:get).returns(response)
+
+    gzipped = StringIO.new
+    gzwriter = Zlib::GzipWriter.new gzipped
+    gzwriter.write(('a'..'z').to_a.join)
+    gzwriter.close
+
+    response.expects(:'[]').with('Content-Encoding').returns('gzip')
+    response.expects(:body).returns gzipped.string
+
+    @gmail.expects(:parse_contacts).with('abcdefghijklmnopqrstuvwxyz')
+    @gmail.contacts
+  end
+
+  it 'raises a FetchingError when something goes awry' do
+    response = mock('HTTP response', :code => 666, :class => Net::HTTPBadRequest, :message => 'oh my')
+    Net::HTTP.expects(:start).returns(response)
+
+    lambda {
+      @gmail.get({})
+    }.should raise_error(Contacts::FetchingError)
+  end
+
+  it 'parses the resulting feed into name/email pairs' do
+    @gmail.stubs(:get)
+    @gmail.expects(:response_body).returns(sample_xml('google-single'))
+
+    @gmail.contacts.should == [['Fitzgerald', 'fubar@gmail.com']]
+  end
+
+  it 'parses a complex feed into name/email pairs' do
+    @gmail.stubs(:get)
+    @gmail.expects(:response_body).returns(sample_xml('google-many'))
+
+    @gmail.contacts.should == [
+      ['Elizabeth Bennet', 'liz@gmail.com', 'liz@example.org'],
+      ['William Paginate', 'will_paginate@googlegroups.com'],
+      [nil, 'anonymous@example.com']
+    ]
+  end
+
+  it 'makes modification time available after parsing' do
+    @gmail.updated_at.should be_nil
+    @gmail.stubs(:get)
+    @gmail.expects(:response_body).returns(sample_xml('google-single'))
+
+    @gmail.contacts
+    u = @gmail.updated_at
+    u.year.should == 2008
+    u.day.should == 5
+    @gmail.updated_at_string.should == '2008-03-05T12:36:38.836Z'
+  end
+
+  describe 'GET query parameter handling' do
+    
+    before :each do
+      @gmail = create
+      @gmail.stubs(:response_body)
+      @gmail.stubs(:parse_contacts)
+      
+      @connection = mock('HTTP connection')
+      response = mock('HTTP response')
+      response.stubs(:is_a?).with(Net::HTTPSuccess).returns(true)
+      Net::HTTP.stubs(:start).yields(@connection).returns(response)
+    end
+    
+    it 'abstracts ugly parameters behind nicer ones' do
+      expect_params %w( max-results=25
+                        orderby=lastmodified
+                        sortorder=ascending
+                        start-index=11
+                        updated-min=datetime )
+
+      @gmail.contacts :limit => 25,
+        :offset => 10,
+        :order => 'lastmodified',
+        :descending => false,
+        :updated_after => 'datetime'
+    end
+
+    it 'should have implicit :descending with :order' do
+      expect_params %w( orderby=lastmodified
+                        sortorder=descending ), true
+                        
+      @gmail.contacts :order => 'lastmodified'
+    end
+
+    it 'should have default :limit of 200' do
+      expect_params %w( max-results=200 )
+      @gmail.contacts
+    end
+
+    it 'should skip nil values in parameters' do
+      expect_params %w( start-index=1 )
+      @gmail.contacts :limit => nil, :offset => 0
+    end
+
+    def expect_params(params, some = false)
+      @connection.expects(:get).with() do |path, headers|
+        pairs = path.split('?').last.split('&').sort
+        unless some
+          pairs.should == params
+          pairs.size == params.size
+        else
+          params.each {|p| pairs.should include(p) }
+          pairs.size >= params.size
+        end
+      end
+    end
+    
+  end
+
+  def create
+    Contacts::Google.new('example@gmail.com', 'dummytoken')
+  end
+
+  def sample_xml(name)
+    File.read File.dirname(__FILE__) + "/../feeds/#{name}.xml"
+  end
+end

data/spec/spec.opts

@@ -0,0 +1,2 @@
+--colour
+--reverse

data/spec/spec_helper.rb

@@ -0,0 +1,13 @@
+require 'rubygems'
+gem 'rspec', '~> 1.1.3'
+require 'spec'
+
+# add library's lib directory
+$:.unshift File.dirname(__FILE__) + '/../lib'
+
+Spec::Runner.configure do |config|
+  # config.include My::Pony, My::Horse, :type => :farm
+  # config.predicate_matchers[:swim] = :can_swim?
+  
+  config.mock_with :mocha
+end

metadata

@@ -0,0 +1,76 @@
+--- !ruby/object:Gem::Specification 
+name: pietern-contacts
+version: !ruby/object:Gem::Version 
+  version: 0.1.1
+platform: ruby
+authors: 
+- "Mislav Marohni\xC4\x87"
+- Pieter Noordhuis
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2008-08-02 00:00:00 -07:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: hpricot
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0.6"
+    version: 
+description: Provides easy access and manipulation with the Google Contacts API
+email: tom@rubyisawesome.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- lib/contacts
+- lib/contacts/google.rb
+- lib/contacts.rb
+- spec/feeds
+- spec/feeds/google-many.xml
+- spec/feeds/google-single.xml
+- spec/gmail
+- spec/gmail/auth_spec.rb
+- spec/gmail/fetching_spec.rb
+- spec/spec.opts
+- spec/spec_helper.rb
+- contacts.gemspec
+- Rakefile
+- README.rdoc
+- MIT-LICENSE
+has_rdoc: true
+homepage: http://github.com/pietern/contacts
+post_install_message: 
+rdoc_options: []
+
+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.2.0
+signing_key: 
+specification_version: 2
+summary: Interfacing with the Google Contacts API
+test_files: []
+