gmail-contacts 0.0.4

data/README.md

@@ -0,0 +1,55 @@
+gmail-contacts
+==============
+
+A Ruby gem for getting a list of your Gmail contacts. Most of the code here has been extracted from
+[mislav's contacts gem](https://github.com/mislav/contacts). It's been updated to work with Ruby 1.9
+and Rails 3.
+
+Installation
+-------
+
+    gem install gmail-contacts
+
+Usage
+-----
+Get a link to the authorization URL:
+
+    GmailContacts::Google.authentication_url("http://mysite.com/invites")
+
+The user will be redirected to the URL you pass and a `token` parameter will be sent along. Capture
+that token and then request the contacts:
+
+    GmailContacts::Google.new("some_token").contacts
+
+Every `Contact` has a name and email fields:
+
+    GmailContacts::Google.new("some_token").contacts.each do |contact|
+      puts "#{contact.name}: #{contact.email}"
+    end
+
+Usage with Rails
+----
+First create the authorization link in one of your views:
+
+    # app/views/invites/new.html.erb
+    <%= link_to "Invite your Gmail contacts", GmailContacts::Google.authentication_url("http://mysite.com/invites") %>
+
+Then create a controller action that receives the token and fetches the contacts:
+
+    # config/routes.rb
+    match "/invites" => "invites#index"
+
+    # app/controllers/invites_controller.rb
+    class InvitesController
+      def index
+        token = params[:token]
+        @contacts = GmailContacts::Google.new("some_token").contacts
+      end
+    end
+
+Finally, iterate through the contacts in your view:
+
+    # app/views/invites/index.html.erb
+    <% @contacts.each do |contact| %>
+      <span><strong><%= contact.name %></strong>: <% contact.email %></span>
+    <% end %>

data/Rakefile

@@ -0,0 +1,150 @@
+require 'rubygems'
+require 'rake'
+require 'date'
+
+#############################################################################
+#
+# Helper functions
+#
+#############################################################################
+
+def name
+  @name ||= Dir['*.gemspec'].first.split('.').first
+end
+
+def version
+ line = File.read("lib/#{name}.rb")[/^\s*VERSION\s*=\s*.*/]
+  line.match(/.*VERSION\s*=\s*['"](.*)['"]/)[1]
+end
+
+def date
+  Date.today.to_s
+end
+
+def rubyforge_project
+  name
+end
+
+def gemspec_file
+  "#{name}.gemspec"
+end
+
+def gem_file
+  "#{name}-#{version}.gem"
+end
+
+def replace_header(head, header_name)
+  head.sub!(/(\.#{header_name}\s*= ').*'/) { "#{$1}#{send(header_name)}'"}
+end
+
+#############################################################################
+#
+# Standard tasks
+#
+#############################################################################
+
+task :default => :test
+
+require 'rake/testtask'
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'lib' << 'test'
+  test.pattern = 'test/**/test_*.rb'
+  test.verbose = true
+end
+
+desc "Generate RCov test coverage and open in your browser"
+task :coverage do
+  require 'rcov'
+  sh "rm -fr coverage"
+  sh "rcov test/test_*.rb"
+  sh "open coverage/index.html"
+end
+
+require 'rdoc/task'
+Rake::RDocTask.new do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "#{name} #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+desc "Open an irb session preloaded with this library"
+task :console do
+  sh "irb -rubygems -r ./lib/#{name}.rb"
+end
+
+#############################################################################
+#
+# Custom tasks (add your own tasks here)
+#
+#############################################################################
+
+
+
+#############################################################################
+#
+# Packaging tasks
+#
+#############################################################################
+
+desc "Create tag v#{version} and build and push #{gem_file} to Rubygems"
+task :release => :build do
+  unless `git branch` =~ /^\* master$/
+    puts "You must be on the master branch to release!"
+    exit!
+  end
+  sh "git commit --allow-empty -a -m 'Release #{version}'"
+  sh "git tag v#{version}"
+  sh "git push origin master"
+  sh "git push origin v#{version}"
+  sh "gem push pkg/#{name}-#{version}.gem"
+end
+
+desc "Build #{gem_file} into the pkg directory"
+task :build => :gemspec do
+  sh "mkdir -p pkg"
+  sh "gem build #{gemspec_file}"
+  sh "mv #{gem_file} pkg"
+end
+
+desc "Generate #{gemspec_file}"
+task :gemspec => :validate do
+  # read spec file and split out manifest section
+  spec = File.read(gemspec_file)
+  head, manifest, tail = spec.split("  # = MANIFEST =\n")
+
+  # replace name version and date
+  replace_header(head, :name)
+  replace_header(head, :version)
+  replace_header(head, :date)
+  #comment this out if your rubyforge_project has a different name
+  replace_header(head, :rubyforge_project)
+
+  # determine file list from git ls-files
+  files = `git ls-files`.
+    split("\n").
+    sort.
+    reject { |file| file =~ /^\./ }.
+    reject { |file| file =~ /^(rdoc|pkg)/ }.
+    map { |file| "    #{file}" }.
+    join("\n")
+
+  # piece file back together and write
+  manifest = "  s.files = %w[\n#{files}\n  ]\n"
+  spec = [head, manifest, tail].join("  # = MANIFEST =\n")
+  File.open(gemspec_file, 'w') { |io| io.write(spec) }
+  puts "Updated #{gemspec_file}"
+end
+
+desc "Validate #{gemspec_file}"
+task :validate do
+  libfiles = Dir['lib/*'] - ["lib/#{name}.rb", "lib/#{name}"]
+  unless libfiles.empty?
+    puts "Directory `lib` should only contain a `#{name}.rb` file and `#{name}` dir."
+    exit!
+  end
+  unless Dir['VERSION*'].empty?
+    puts "A `VERSION` file at root level violates Gem best practices."
+    exit!
+  end
+end

data/gmail-contacts.gemspec

@@ -0,0 +1,56 @@
+## This is the rakegem gemspec template. Make sure you read and understand
+## all of the comments. Some sections require modification, and others can
+## be deleted if you don't need them. Once you understand the contents of
+## this file, feel free to delete any comments that begin with two hash marks.
+## You can find comprehensive Gem::Specification documentation, at
+## http://docs.rubygems.org/read/chapter/20
+Gem::Specification.new do |s|
+  s.specification_version = 2 if s.respond_to? :specification_version=
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.rubygems_version = '1.3.5'
+
+  ## Leave these as is they will be modified for you by the rake gemspec task.
+  ## If your rubyforge_project name is different, then edit it and comment out
+  ## the sub! line in the Rakefile
+  s.name              = 'gmail-contacts'
+  s.version           = '0.0.4'
+  s.date              = '2012-06-19'
+  s.rubyforge_project = 'gmail-contacts'
+
+  ## Make sure your summary is short. The description may be as long
+  ## as you like.
+  s.summary     = "A Ruby library for fetching Gmail account contacts"
+  s.description = "A Ruby library for fetching Gmail account contacts"
+
+  ## List the primary authors. If there are a bunch of authors, it's probably
+  ## better to set the email to an email list or something. If you don't have
+  ## a custom homepage, consider using your GitHub URL or the like.
+  s.authors  = ["Federico Builes"]
+  s.email    = 'federico.builes@gmail.com'
+  s.homepage = 'https://github.com/febuiles/gmail-contacts'
+
+  ## This gets added to the $LOAD_PATH so that 'lib/NAME.rb' can be required as
+  ## require 'NAME.rb' or'/lib/NAME/file.rb' can be as require 'NAME/file.rb'
+  s.require_paths = %w[lib]
+
+  ## List your runtime dependencies here. Runtime dependencies are those
+  ## that are needed for an end user to actually USE your code.
+  s.add_dependency("hpricot")
+
+  ## Leave this section as-is. It will be automatically generated from the
+  ## contents of your Git repository via the gemspec task. DO NOT REMOVE
+  ## THE MANIFEST COMMENTS, they are used as delimiters by the task.
+  # = MANIFEST =
+  s.files = %w[
+    README.md
+    Rakefile
+    gmail-contacts.gemspec
+    lib/gmail-contacts.rb
+    lib/gmail-contacts/google.rb
+  ]
+  # = MANIFEST =
+
+  ## Test files will be grabbed from the file list. Make sure the path glob
+  ## matches what you actually use.
+  s.test_files = s.files.select { |path| path =~ /^test\/test_.*\.rb/ }
+end

data/lib/gmail-contacts/google.rb

@@ -0,0 +1,306 @@
+require 'gmail_contacts'
+
+require 'rubygems'
+require 'hpricot'
+require 'cgi'
+require 'time'
+require 'zlib'
+require 'stringio'
+require 'net/http'
+require 'net/https'
+
+module GmailContacts
+  # == Fetching Google Contacts
+  #
+  # First, get the user to follow the following URL:
+  #
+  #   GmailContacts::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 = GmailContacts::Google.new(params[:token])
+  #   gmail.contacts
+  #   # => [#<Contact 1>, #<Contact 2>, ...]
+  #
+  # == 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:
+  #
+  #   GmailContacts::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 = GmailContacts::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 GmailContacts::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 GmailContacts::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}\n----" unless response.body.empty?
+      end
+  end
+end

data/lib/gmail-contacts.rb

@@ -0,0 +1,48 @@
+require 'gmail_contacts/google'
+
+module GmailContacts
+
+  VERSION = "0.0.4"
+
+  Identifier = 'GmailContacts v' + VERSION
+
+  # 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
+      %!#<GmailContacts::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

metadata

@@ -0,0 +1,60 @@
+--- !ruby/object:Gem::Specification
+name: gmail-contacts
+version: !ruby/object:Gem::Version
+  version: 0.0.4
+  prerelease: 
+platform: ruby
+authors:
+- Federico Builes
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-06-19 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: hpricot
+  requirement: &70217158537480 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: *70217158537480
+description: A Ruby library for fetching Gmail account contacts
+email: federico.builes@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- Rakefile
+- gmail-contacts.gemspec
+- lib/gmail-contacts.rb
+- lib/gmail-contacts/google.rb
+homepage: https://github.com/febuiles/gmail-contacts
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: gmail-contacts
+rubygems_version: 1.8.10
+signing_key: 
+specification_version: 2
+summary: A Ruby library for fetching Gmail account contacts
+test_files: []