google_contacts_api 0.1.1

data/.document

@@ -0,0 +1,5 @@
+lib/**/*.rb
+bin/*
+- 
+features/**/*.feature
+LICENSE.txt

data/Gemfile

@@ -0,0 +1,15 @@
+source "http://rubygems.org"
+# Add dependencies required to use your gem here.
+# Example:
+gem "activesupport"
+gem "json"
+gem "hashie"
+
+# Add dependencies to develop your gem here.
+# Include everything needed to run rake, tests, features, etc.
+group :development do
+  gem "shoulda", ">= 0"
+  gem "bundler", "~> 1.0.0"
+  gem "jeweler", "~> 1.5.2"
+  gem "rcov", ">= 0"
+end

data/LICENSE.txt

@@ -0,0 +1,20 @@
+Copyright (c) 2011 Alvin Liang
+
+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.markdown

@@ -0,0 +1,42 @@
+# google_contacts_api
+
+An unofficial Google Contacts API for ruby. Might not be stable (but probably is). In active usage at [thirsst.com](http://thirsst.com/). (Shameless plug: We help you manage your RSS and group bookmarking!)
+
+## Usage
+
+You need to provide an OAuth access token from one of the major OAuth libraries to this library.
+Then you can instantiate a GoogleContactsApi::Api object for direct posting and parsing, or a
+GoogleContactsApi::User object for easier stuff.
+
+```ruby
+google_contacts_user = GoogleContactsApi::User(oauth_access_token_for_user)
+contacts = google_contacts_user.contacts
+groups = google_contacts_user.groups
+groups.first.contacts
+contacts.first.photo
+contacts.first.title
+contacts.first.id
+```
+
+## TODO
+
+I welcome patches and pull requests, see the guidelines below (handily auto-generated
+by jeweler).
+
+* Tests! (using RSpec, please)
+* Posting/putting/deleting groups, contacts and their photos
+* Support ClientLogin
+
+## Contributing to google_contacts_api
+ 
+* Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet
+* Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it
+* Fork the project
+* Start a feature/bugfix branch
+* Commit and push until you are happy with your contribution
+* Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.
+* Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.
+
+## Copyright
+
+Copyright (c) 2011 Alvin Liang. See LICENSE.txt for further details.

data/Rakefile

@@ -0,0 +1,55 @@
+require 'rubygems'
+require 'bundler'
+begin
+  Bundler.setup(:default, :development)
+rescue Bundler::BundlerError => e
+  $stderr.puts e.message
+  $stderr.puts "Run `bundle install` to install missing gems"
+  exit e.status_code
+end
+require 'rake'
+
+require 'jeweler'
+Jeweler::Tasks.new do |gem|
+  # gem is a Gem::Specification... see http://docs.rubygems.org/read/chapter/20 for more options
+  gem.name = "google_contacts_api"
+  gem.homepage = "http://github.com/aliang/google_contacts_api"
+  gem.license = "MIT"
+  gem.summary = %Q{Lets you read from the Google Contacts API}
+  gem.description = %Q{Lets you read from the Google Contacts API. Posting to come later. Tests to come later.}
+  gem.email = "ayliang@gmail.com"
+  gem.authors = ["Alvin Liang"]
+  # Include your dependencies below. Runtime dependencies are required when using your gem,
+  # and development dependencies are only needed for development (ie running rake tasks, tests, etc)
+  gem.add_runtime_dependency 'activesupport'
+  gem.add_runtime_dependency 'hashie'
+  gem.add_runtime_dependency 'json'
+  #  gem.add_development_dependency 'rspec', '> 1.2.3'
+end
+Jeweler::RubygemsDotOrgTasks.new
+
+require 'rake/testtask'
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'lib' << 'test'
+  test.pattern = 'test/**/test_*.rb'
+  test.verbose = true
+end
+
+require 'rcov/rcovtask'
+Rcov::RcovTask.new do |test|
+  test.libs << 'test'
+  test.pattern = 'test/**/test_*.rb'
+  test.verbose = true
+end
+
+task :default => :test
+
+require 'rdoc/task'
+Rake::RDocTask.new do |rdoc|
+  version = File.exist?('VERSION') ? File.read('VERSION') : ""
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "google_contacts_api #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/VERSION

@@ -0,0 +1 @@
+0.1.1

data/google_contacts_api.gemspec

@@ -0,0 +1,80 @@
+# Generated by jeweler
+# DO NOT EDIT THIS FILE DIRECTLY
+# Instead, edit Jeweler::Tasks in Rakefile, and run 'rake gemspec'
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{google_contacts_api}
+  s.version = "0.1.1"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Alvin Liang"]
+  s.date = %q{2011-07-08}
+  s.description = %q{Lets you read from the Google Contacts API. Posting to come later. Tests to come later.}
+  s.email = %q{ayliang@gmail.com}
+  s.extra_rdoc_files = [
+    "LICENSE.txt",
+    "README.markdown"
+  ]
+  s.files = [
+    ".document",
+    "Gemfile",
+    "LICENSE.txt",
+    "README.markdown",
+    "Rakefile",
+    "VERSION",
+    "google_contacts_api.gemspec",
+    "lib/google_contacts_api.rb",
+    "test/helper.rb",
+    "test/test_google_contacts_api.rb"
+  ]
+  s.homepage = %q{http://github.com/aliang/google_contacts_api}
+  s.licenses = ["MIT"]
+  s.require_paths = ["lib"]
+  s.rubygems_version = %q{1.6.2}
+  s.summary = %q{Lets you read from the Google Contacts API}
+  s.test_files = [
+    "test/helper.rb",
+    "test/test_google_contacts_api.rb"
+  ]
+
+  if s.respond_to? :specification_version then
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
+      s.add_runtime_dependency(%q<activesupport>, [">= 0"])
+      s.add_runtime_dependency(%q<json>, [">= 0"])
+      s.add_runtime_dependency(%q<hashie>, [">= 0"])
+      s.add_development_dependency(%q<shoulda>, [">= 0"])
+      s.add_development_dependency(%q<bundler>, ["~> 1.0.0"])
+      s.add_development_dependency(%q<jeweler>, ["~> 1.5.2"])
+      s.add_development_dependency(%q<rcov>, [">= 0"])
+      s.add_runtime_dependency(%q<activesupport>, [">= 0"])
+      s.add_runtime_dependency(%q<hashie>, [">= 0"])
+      s.add_runtime_dependency(%q<json>, [">= 0"])
+    else
+      s.add_dependency(%q<activesupport>, [">= 0"])
+      s.add_dependency(%q<json>, [">= 0"])
+      s.add_dependency(%q<hashie>, [">= 0"])
+      s.add_dependency(%q<shoulda>, [">= 0"])
+      s.add_dependency(%q<bundler>, ["~> 1.0.0"])
+      s.add_dependency(%q<jeweler>, ["~> 1.5.2"])
+      s.add_dependency(%q<rcov>, [">= 0"])
+      s.add_dependency(%q<activesupport>, [">= 0"])
+      s.add_dependency(%q<hashie>, [">= 0"])
+      s.add_dependency(%q<json>, [">= 0"])
+    end
+  else
+    s.add_dependency(%q<activesupport>, [">= 0"])
+    s.add_dependency(%q<json>, [">= 0"])
+    s.add_dependency(%q<hashie>, [">= 0"])
+    s.add_dependency(%q<shoulda>, [">= 0"])
+    s.add_dependency(%q<bundler>, ["~> 1.0.0"])
+    s.add_dependency(%q<jeweler>, ["~> 1.5.2"])
+    s.add_dependency(%q<rcov>, [">= 0"])
+    s.add_dependency(%q<activesupport>, [">= 0"])
+    s.add_dependency(%q<hashie>, [">= 0"])
+    s.add_dependency(%q<json>, [">= 0"])
+  end
+end
+

data/lib/google_contacts_api.rb

@@ -0,0 +1,304 @@
+# TODO: Use more than one file
+
+require 'active_support/core_ext'
+require 'json'
+require 'hashie'
+
+module GoogleContactsApi
+  class Api
+    # keep separate in case of new auth method
+    BASE_URL = "https://www.google.com/m8/feeds/"
+
+    attr_reader :oauth
+    def initialize(oauth)
+      # TODO: Later, accept ClientLogin
+      @oauth = oauth
+    end
+
+    # Get request to specified link, with query params
+    # For get, post, put, delete, always use JSON, it's simpler
+    # and lets us use Hashie::Mash. Note that in the JSON conversion from XML,
+    # ":" is replaced with $, element content is keyed with $t
+    def get(link, params = {}, headers = {})
+      params["alt"] = "json"
+      @oauth.get("#{BASE_URL}#{link}?#{params.to_query}", headers)
+    end
+
+    # Post request to specified link, with query params
+    # Not tried yet, might be issues with params
+    def post(link, params = {}, headers = {})
+      params["alt"] = "json"
+      @oauth.post("#{BASE_URL}#{link}?#{params.to_query}", headers)
+    end
+
+    # Put request to specified link, with query params
+    # Not tried yet
+    def put(link, params = {}, headers = {})
+      params["alt"] = "json"
+      @oauth.put("#{BASE_URL}#{link}?#{params.to_query}", headers)
+    end
+
+    # Delete request to specified link, with query params
+    # Not tried yet
+    def delete(link, params = {}, headers = {})
+      params["alt"] = "json"
+      @oauth.delete("#{BASE_URL}#{link}?#{params.to_query}", headers)
+    end
+  end
+
+  module Contacts
+    # Retrieve the contacts for this user or group
+    def contacts(params = {})
+      params = params.with_indifferent_access
+
+      # compose params into a string
+      # See http://code.google.com/apis/contacts/docs/3.0/reference.html#Parameters
+      # alt, q, max-results, start-index, updated-min,
+      # orderby, showdeleted, requirealldeleted, sortorder, group
+      params["max-results"] = 100000 unless params.key?("max-results")
+      url = "contacts/default/full"
+      response = @api.get(url, params)
+      
+      # TODO: Define some fancy exceptions
+      case response.code
+      when 401; raise
+      when 403; raise
+      when 404; raise
+      when 400...500; raise
+      when 500...600; raise
+      end
+      ContactSet.new(response.body, @api)
+    end
+  end
+
+  class User
+    include Contacts
+    
+    attr_reader :api
+    def initialize(oauth)
+      @api = GoogleContactsApi::Api.new(oauth)
+    end
+
+    # Retrieve the groups for this user
+    # TODO: Handle 403, 404, 401
+    def groups(params = {})
+      params = params.with_indifferent_access
+      # compose params into a string
+      # See http://code.google.com/apis/contacts/docs/3.0/reference.html#Parameters
+      # alt, q, max-results, start-index, updated-min,
+      # orderby, showdeleted, requirealldeleted, sortorder
+      params["max-results"] = 100000 unless params.key?("max-results")
+      url = "groups/default/full"
+      # TODO: So weird thing, version 3 doesn't return system groups
+      # When it does, uncomment this line and use it to request instead
+      # response = @api.get(url, params)
+      response = @api.get(url, params, {"GData-Version" => "2"})
+
+      case response.code
+      when 401; raise
+      when 403; raise
+      when 404; raise
+      when 400...500; raise
+      when 500...600; raise
+      end
+      GroupSet.new(response.body, @api)
+    end
+  end
+
+  # Base class for GroupSet and ContactSet
+  class ResultSet
+    include Enumerable
+    attr_reader :api
+    attr_accessor :total_results, :start_index, :items_per_page, :parsed
+    
+    def initialize(response_body, api = nil)
+      @api = api
+      @parsed = Hashie::Mash.new(JSON.parse(response_body))
+      @total_results = @parsed.feed["openSearch$totalResults"]["$t"].to_i
+      @start_index = @parsed.feed["openSearch$startIndex"]["$t"].to_i
+      @items_per_page = @parsed.feed["openSearch$itemsPerPage"]["$t"].to_i
+      @results = []
+    end
+    
+    def each
+      @results.each { |x| yield x }
+    end
+    
+    def has_more?
+      # 1-based indexing
+      @start_index - 1 + @items_per_page <= @total_results
+    end
+    
+    def inspect
+      "<#{self.class}: @start_index=#{@start_index}, @items_per_page=#{@items_per_page}, @total_results=#{@total_results}>"
+    end
+  end
+
+  class GroupSet < ResultSet
+    # Populate from a response that contains contacts
+    def initialize(response_body, api = nil)
+      super
+      @results = @parsed.feed.entry.map { |e| Group.new(e, nil, api) }
+    end
+  end
+
+  class ContactSet < ResultSet
+    # Populate from a response that contains contacts
+    def initialize(response_body, api = nil)
+      super
+      @results = @parsed.feed.entry.map { |e| Contact.new(e, nil, api) }
+    end
+  end
+
+  # Base class for Group and Contact
+  class Result < Hashie::Mash
+    # Note that the title is really just the (full) name
+    # ":" replaced with $, element content is keyed with $t
+    
+    # These are the accessors we can write
+    # :id, :title, :updated, :content
+    
+    attr_reader :api
+    # Populate from a single result Hash/Hashie
+    def initialize(source_hash = nil, default = nil, api = nil, &blk)
+      @api = api if api
+      super(source_hash, default, &blk)
+    end
+
+    # TODO: Conditional retrieval? There might not be an etag in the
+    # JSON representation, there is in the XML representation
+    def etag
+    end
+
+    def id
+      _id = self["id"]
+      _id ? _id["$t"] : nil
+    end
+    
+    def title
+      _title = self["title"]
+      _title ? _title["$t"] : nil
+    end
+    
+    def content
+      _content = self["content"]
+      _content ? content["$t"] : nil
+    end
+    
+    def updated
+      _updated = self["updated"]
+      _updated ? DateTime.parse(_updated["$t"]) : nil
+    end
+    
+    # Returns the array of categories, as category is an array for Hashie.
+    def categories
+      category
+    end
+    
+    def deleted?
+      raise NotImplementedError
+    end
+    
+    def inspect
+      "<#{self.class}: #{title}>"
+    end
+  end
+
+  class Group < Result
+    include Contacts
+    # Populate from a single entry element in the result response
+    # when requesting a set of Contacts
+
+    def system_group?
+      !self["gContact$systemGroup"].nil?
+    end
+
+    def contacts(params = {})
+      # contacts in this group
+      @contacts ||= super({"group" => self.id}.merge(params))
+    end
+    
+    def contacts!(params = {})
+      # contacts in this group
+      @contacts = super({"group" => self.id}.merge(params))
+    end
+    
+    # Returns the array of links, as link is an array for Hashie.
+    def links
+      self["link"].map { |l| l.href }
+    end
+    
+    def self_link
+      _link = self["link"].find { |l| l.rel == "self" }
+      _link ? _link.href : nil
+    end
+    
+    def edit_link
+      _link = self["link"].find { |l| l.rel == "edit" }
+      _link ? _link.href : nil
+    end
+  end
+
+  class Contact < Result
+    # :categories, (:content again), :links, (:title again), :email
+    # :extended_properties, :deleted, :im, :name,
+    # :organizations, :phone_numbers, :structured_postal_addresses, :where
+    
+    # Returns the array of links, as link is an array for Hashie.
+    def links
+      self["link"].map { |l| l.href }
+    end
+    
+    def self_link
+      _link = self["link"].find { |l| l.rel == "self" }
+      _link ? _link.href : nil
+    end
+    
+    def alternate_link
+      _link = self["link"].find { |l| l.rel == "alternate" }
+      _link ? _link.href : nil
+    end
+    
+    def photo_link
+      _link = self["link"].find { |l| l.rel == "http://schemas.google.com/contacts/2008/rel#photo" }
+      _link ? _link.href : nil
+    end
+    
+    # Returns binary data for the photo. You can probably
+    # use it in a data-uri. This is in PNG format.
+    def photo
+      return nil unless photo_link
+      response = @api.oauth.get(photo_link)
+      
+      case response.code
+      # maybe return a placeholder instead of nil
+      when 400; return nil
+      when 401; return nil
+      when 403; return nil
+      when 404; return nil
+      when 400...500; return nil
+      when 500...600; return nil
+      else; return response.body
+      end
+    end
+    
+    def edit_photo_link
+      _link = self["link"].find { |l| l.rel == "http://schemas.google.com/contacts/2008/rel#edit_photo" }
+      _link ? _link.href : nil
+    end
+    
+    def edit_link
+      _link = self["link"].find { |l| l.rel == "edit" }
+      _link ? _link.href : nil
+    end
+    
+    def emails
+      self["gd$email"].map { |e| e.address }
+    end
+    
+    def primary_email
+      _email = self["gd$email"].find { |e| e.primary == "true" }
+      _email ? _email.address : nil
+    end
+  end
+end

data/test/helper.rb

@@ -0,0 +1,18 @@
+require 'rubygems'
+require 'bundler'
+begin
+  Bundler.setup(:default, :development)
+rescue Bundler::BundlerError => e
+  $stderr.puts e.message
+  $stderr.puts "Run `bundle install` to install missing gems"
+  exit e.status_code
+end
+require 'test/unit'
+require 'shoulda'
+
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+$LOAD_PATH.unshift(File.dirname(__FILE__))
+require 'google_contacts_api'
+
+class Test::Unit::TestCase
+end

data/test/test_google_contacts_api.rb

@@ -0,0 +1,7 @@
+require 'helper'
+
+class TestGoogleContactsApi < Test::Unit::TestCase
+  should "probably rename this file and start testing for real" do
+    flunk "hey buddy, you should probably rename this file and start testing for real"
+  end
+end

metadata

@@ -0,0 +1,179 @@
+--- !ruby/object:Gem::Specification 
+name: google_contacts_api
+version: !ruby/object:Gem::Version 
+  prerelease: 
+  version: 0.1.1
+platform: ruby
+authors: 
+- Alvin Liang
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2011-07-08 00:00:00 -04:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: activesupport
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+  type: :runtime
+  prerelease: false
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: json
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+  type: :runtime
+  prerelease: false
+  version_requirements: *id002
+- !ruby/object:Gem::Dependency 
+  name: hashie
+  requirement: &id003 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+  type: :runtime
+  prerelease: false
+  version_requirements: *id003
+- !ruby/object:Gem::Dependency 
+  name: shoulda
+  requirement: &id004 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+  type: :development
+  prerelease: false
+  version_requirements: *id004
+- !ruby/object:Gem::Dependency 
+  name: bundler
+  requirement: &id005 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        version: 1.0.0
+  type: :development
+  prerelease: false
+  version_requirements: *id005
+- !ruby/object:Gem::Dependency 
+  name: jeweler
+  requirement: &id006 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        version: 1.5.2
+  type: :development
+  prerelease: false
+  version_requirements: *id006
+- !ruby/object:Gem::Dependency 
+  name: rcov
+  requirement: &id007 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+  type: :development
+  prerelease: false
+  version_requirements: *id007
+- !ruby/object:Gem::Dependency 
+  name: activesupport
+  requirement: &id008 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+  type: :runtime
+  prerelease: false
+  version_requirements: *id008
+- !ruby/object:Gem::Dependency 
+  name: hashie
+  requirement: &id009 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+  type: :runtime
+  prerelease: false
+  version_requirements: *id009
+- !ruby/object:Gem::Dependency 
+  name: json
+  requirement: &id010 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+  type: :runtime
+  prerelease: false
+  version_requirements: *id010
+description: Lets you read from the Google Contacts API. Posting to come later. Tests to come later.
+email: ayliang@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- LICENSE.txt
+- README.markdown
+files: 
+- .document
+- Gemfile
+- LICENSE.txt
+- README.markdown
+- Rakefile
+- VERSION
+- google_contacts_api.gemspec
+- lib/google_contacts_api.rb
+- test/helper.rb
+- test/test_google_contacts_api.rb
+has_rdoc: true
+homepage: http://github.com/aliang/google_contacts_api
+licenses: 
+- MIT
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3049273964521607278
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.6.2
+signing_key: 
+specification_version: 3
+summary: Lets you read from the Google Contacts API
+test_files: 
+- test/helper.rb
+- test/test_google_contacts_api.rb