rgdata 0.1.0 → 0.2.1

data/README.rdoc

@@ -1,14 +1,14 @@
 = RGData
 
 RGData makes it easy to get data from Google's Data APIs.
-It streamlines requests and gives you back good ole Ruby objects.
+It streamlines the parts that give you headaches (requests, OAUTH2 authentication, etc.) and gives you back good ole Ruby objects.
 
 An Example:
 
   domain = 'redningja.com'
   profiles = RGData::API::Profiles.retrieve domain, oauth_token: 'access_token_thatlookslikegibberish'
-  => [#<RGData::Model::Profile full_name: 'Jared Ning'>, ...]
-  # Now you can just do this:
+  #=> [#<RGData::Model::Profile full_name: 'Jared Ning'>, ...]
+  # With a Ruby object in hand, getting the data is easy:
   profiles.first.full_name
   # Want each user's email addresses?
   profiles.map(&:emails)
@@ -16,7 +16,7 @@ An Example:
 == Installation
 
   gem install rgdata
-
+ 
   RGData.config do
     client_id     <your client_id>
     client_secret <your client_secret>
@@ -30,30 +30,33 @@ There's a lot of setup, but after that it should be easy.
 * Setup
   * Get your client_id and client_secret
     * https://code.google.com/apis/console
-    * Click on Identity at the left.
+    * Click on 'API Access' at the left.
     * Look for OAuth2 Credentials and you'll find your client_id and client_secret
-  * While you're you may want to list your redirect URIs if you know what they will be. These must match your authentication requests (more on this later).
+  * While you're here, you may want to list your redirect URIs if you know what they will be. These must match your authentication requests (more on this in just a bit).
 * Request authentication. (Depending on which API you are using, there may be specific instructions you may want to tell your user about. See the individual APIs classes for specifics.)
-  * Your user will go to the request URL generated for you by calling, for example, RGData::API::Profiles.request_url(scope, redirect_uri).
+  * Your user will go to the request URL generated for you by calling, for example, RGData::API::Profiles.request_url(redirect_uri) # redirect_uri MUST BE LISTED IN YOUR API CONSOLE.
   * They will be promted by Google to authenticate and grant permission.
-* Successful authentication will return hash that you are responsible for collecting. It includes 3 parts:
+* Successful authentication will return an authorization code in the form of a callback to redirect_uri. The authorization code is attached to the URL as a parameter - e.g. http://redirect_back.com?authorization_code=42istheanswer.
+* Now you have the dough, so go get the bread. (You get 1 shot at this. Once the authorization_code is used on Google, it's useless.) Use this authorization code to swap for a hash with all the goodies. The hash has 3 parts:
   * access_token: This is what we're after. You can use this immediately to retrieve data. You can also get one by using refresh_token which we'll get to in a sec.
-  * expiration: You have this many seconds to use access_token before it expires.
+  * expires_in: You have this many seconds to use access_token before it expires.
   * refresh_token: See below.
-* Once you have your access token, you can start accessing the data.
+* Finalyy, once you have your access token, you can start accessing the data.
 
 === Refresh tokens
 
-A refresh token won't get you into the data, but it will allow you to get more access tokens in the future. Keep this if you don't want your users to re-authenticate over and over again.
+A refresh token won't get you into the data, but it will allow you to get more access tokens in the future.
+Keep this if you don't want your users to re-authenticate over and over again.
+REFRESH TOKENS EXPIRE AFTER 24 HOURS.
 To get another access token:
 
-  RGData::API::Profiles.get_access_token(refresh_token)
+  RGData::API::Profiles.swap_refresh_token(refresh_token)
 
 For convenience, APIs are smart enough to do this work for you:
 
   RGData::API::Profiles.retrieve domain, refresh_token: refresh_token
 
-=== client-side and native application authentication
+=== Client-side and native application authentication
 
 TODO
 
@@ -86,6 +89,29 @@ Please feel free to contribute more APIs.
 Take a look at lib/rgdata/apis/profiles.rb and lib/rgdata/models/profile.rb to see how easy it is.
 For the API, just find the scope (link below)
 
+== TODOs
+
+Feel free to contribute.
+
+* Client-side authentication
+* Native application authentication
+* Retrieving data with query parameters (limit, start index, etc.)
+* Retrieving individual (as opposed to all)
+* Lots of more APIs.
+* Capture error messages: If google denies something, there may be some useful error messages.
+
+== Testing
+
+This gem tests live with Google.
+You'll need to set some environment variables for your own client_id, client_secret, refresh_token, and domain.
+See mspec/spec_helper.rb.
+I set them in my .bash_profile.
+
+  export GOOGLE_APPS_CLIENT_ID='1234567890.apps.googleusercontent.com'
+  export GOOGLE_APPS_CLIENT_SECRET='blahblahblah'
+  export GOOGLE_APPS_REFRESH_TOKEN='sierra_mist_foobar'
+  export GOOGLE_APPS_DOMAIN='redningja.com'
+
 == Compatibility
 
 Ruby 1.9. Want 1.8 support? Go fork yourself.

data/lib/rgdata/api.rb

@@ -18,21 +18,30 @@ module RGData::API
       RGData::Authentication.request_url(scope, redirect_uri)
     end
 
-    # Send request and return response.
+    # Send request for data (not authentication) and return response.
     # options can be :oauth_token, :access_token, or :refresh_token.
     def do_request(domain, options)
       oauth_token = extract_oauth_token_or_access_token_or_get_one_using_refresh_token(options)
-      query = {oauth_token: oauth_token}
-      query.verify_keys_present_and_values_not_nil(:oauth_token)
+      query = {
+        oauth_token: oauth_token,
+      }
+      query.verify_keys_present_and_values_not_blank(:oauth_token)
+      raise 'Domain cannot be blank' if domain.blank?
       get "/#{domain}/full", query: query
     end
 
-    # Perform request and instantiate new model objects.
+    # Perform request and create new model objects.
+    # See do_request() for arguments info.
     def retrieve(domain, options)
+      raise 'domain cannot be nil' unless domain
       full_xml_hash = do_request(domain, options)
       full_xml_hash['feed']['entry'].map do |xml_hash|
         model.new_from_xml_hash xml_hash
       end
+    rescue
+      puts 'Unexpected response:'
+      puts full_xml_hash
+      raise
     end
 
     private
@@ -45,7 +54,10 @@ module RGData::API
       oauth_token = hash.extract_values_at(:oauth_token, :access_token).compact.first
       unless oauth_token
         refresh_token = hash.extract(:refresh_token)
-        oauth_token = RGData::Authentication::get_access_token(refresh_token)
+        raise "Refresh token cannot be blank" if refresh_token.blank?
+        response_hash = RGData::Authentication::swap_refresh_token(refresh_token)
+        oauth_token = response_hash['access_token']
+        raise "Unexpected response: #{response_hash}" unless oauth_token
       end
       oauth_token
     end

data/lib/rgdata/authentication.rb

@@ -10,26 +10,37 @@ class RGData::Authentication
       method = Net::HTTP::Get
       path = default_options[:base_uri] + '/auth'
       query = {
+        client_id:     RGData.config.client_id,
         redirect_uri:  redirect_uri,
         scope:         scope,
         response_type: 'code',
-        client_id:     RGData.config.client_id,
       }
-      query.verify_keys_present_and_values_not_nil(:client_id, :redirect_uri, :scope, :response_type)
+      query.verify_keys_present_and_values_not_blank(:client_id, :redirect_uri, :scope, :response_type)
       request = HTTParty::Request.new(method, path, query: query)
       URI.unescape(request.uri.to_s)
     end
 
-    def get_access_token(refresh_token)
+    def swap_authorization_code(authorization_code, redirect_uri)
+      body = {
+        client_id:      RGData.config.client_id,
+        client_secret:  RGData.config.client_secret,
+        code:           authorization_code,
+        grant_type:     'authorization_code',
+        redirect_uri:   redirect_uri
+      }
+      body.verify_keys_present_and_values_not_blank(:client_secret, :client_id, :code, :grant_type, :redirect_uri)
+      post('/token', body: body)
+    end
+
+    def swap_refresh_token(refresh_token)
       body = {
-        refresh_token: refresh_token,
-        grant_type: 'refresh_token',
-        client_id: RGData.config.client_id,
-        client_secret: RGData.config.client_secret,
+        client_id:      RGData.config.client_id,
+        client_secret:  RGData.config.client_secret,
+        refresh_token:  refresh_token,
+        grant_type:     'refresh_token',
       }
-      body.verify_keys_present_and_values_not_nil(:refresh_token, :grant_type, :client_secret, :client_id)
-      response = post('/token', body: body)
-      response['access_token']
+      body.verify_keys_present_and_values_not_blank(:refresh_token, :grant_type, :client_secret, :client_id)
+      post('/token', body: body)
     end
 
   end

data/lib/rgdata/version.rb

@@ -1,3 +1,3 @@
 module Rgdata
-  VERSION = '0.1.0'
+  VERSION = '0.2.1'
 end

data/lib/support/hash.rb

@@ -3,12 +3,12 @@ class Hash
   # This gem was meant to help deal with the strictness of APIs
   # and their inability to give good feedback for mundane detail errors.
   # This method helps eliminate guessing when it comes to Request query/body/etc. hashes.
-  def verify_keys_present_and_values_not_nil(*keys)
+  def verify_keys_present_and_values_not_blank(*keys)
     keys.each do |key|
       unless has_key?(key.to_sym) || has_key?(key.to_s)
         raise "Options missing '#{key}'"
       end
-      if extract(key).nil?
+      if extract(key).blank?
         raise "Option '#{key}' cannot be nil"
       end
     end

data/lib/support/object.rb

@@ -0,0 +1,7 @@
+class Object
+
+  def blank?
+    nil? || self == ''
+  end
+
+end

data/mspec/apis/profiles_spec.rb

@@ -9,14 +9,12 @@ describe RGData::API::Profiles do
   it 'requests authentication url' do
     redirect_uri = 'http://come.back.here.after.successful.authentication.com/'
     request_url = RGData::API::Profiles.request_url(redirect_uri)
-    uri = URI.escape("https://accounts.google.com/o/oauth2/auth?redirect_uri=http://come.back.here.after.successful.authentication.com/&scope=http://www.google.com/m8/feeds/&response_type=code&client_id=#{RGData.config.client_id}")
+    uri = URI.escape("https://accounts.google.com/o/oauth2/auth?client_id=#{RGData.config.client_id}&redirect_uri=http://come.back.here.after.successful.authentication.com/&scope=http://www.google.com/m8/feeds/&response_type=code")
     request_url.must_equal uri
   end
 
   it 'retrieves profiles from a domain' do
-    domain = 'redningja.com'
-    access_token = RGData::Authentication.get_access_token(TEST_REFRESH_TOKEN)
-    profiles = RGData::API::Profiles.retrieve(domain, oauth_token: access_token)
+    profiles = RGData::API::Profiles.retrieve(TEST_DOMAIN, refresh_token: TEST_REFRESH_TOKEN)
     profiles.wont_be_empty
   end
 

data/mspec/assertions.rb

@@ -0,0 +1,15 @@
+module MiniTest::Assertions
+
+  def assert_has_keys(hash, keys, msg = nil)
+    missing_keys = keys.select { |key| !hash.has_key?(key) }
+    assert hash.is_a?(Hash), msg || "Exepcted Hash, got: #{mu_pp(hash)}"
+    assert missing_keys.none?, msg || "Hash missing keys: #{missing_keys.join(',')}"
+  end
+  Object.infect_an_assertion :assert_has_keys, :must_have_keys, true
+
+  def assert_httparty_response_has_keys(response, keys, msg = nil)
+    assert_has_keys response, keys, msg || "Unexpected response: #{response}"
+  end
+  Object.infect_an_assertion :assert_httparty_response_has_keys, :must_have_response_keys, true
+
+end

data/mspec/authentication_spec.rb

@@ -6,12 +6,24 @@ describe RGData::Authentication do
     scope        = RGData::API::Profiles.scope
     redirect_uri = 'http://come.back.here.after.successful.authentication.com/'
     request_url = RGData::Authentication.request_url(scope, redirect_uri)
-    uri = URI.escape("https://accounts.google.com/o/oauth2/auth?redirect_uri=http://come.back.here.after.successful.authentication.com/&scope=http://www.google.com/m8/feeds/&response_type=code&client_id=#{RGData.config.client_id}")
+    uri = URI.escape("https://accounts.google.com/o/oauth2/auth?client_id=#{RGData.config.client_id}&redirect_uri=http://come.back.here.after.successful.authentication.com/&scope=http://www.google.com/m8/feeds/&response_type=code")
     request_url.must_equal uri
   end
 
-  it 'retrieves another access_token given a refresh_token' do
-    RGData::Authentication.get_access_token(TEST_REFRESH_TOKEN).wont_be_nil
+  it 'swaps a refresh_token for a hash with access_token and expiration' do
+    response = RGData::Authentication.swap_refresh_token(TEST_REFRESH_TOKEN)
+    response.must_have_response_keys ['access_token', 'expires_in']
+  end
+
+  # This must be tested live because you have to contact Google through a web interface to get an authorization code.
+  # Remember, you only get 1 shot with this authorization code. Once it is sent to Google, it's expired.
+  # I setup a Sinatra app that makes it easy to request authorization codes. I will include it later.
+  it 'swaps an authorization_code for a hash with access_token, refresh_token, and expiration' do
+    unless TEST_AUTHORIZATION_CODE
+      skip 'This must be tested with a valid authorization code and registered redirect_uri.'
+    end
+    response = RGData::Authentication.swap_authorization_code(TEST_AUTHORIZATION_CODE, TEST_REDIRECT_URI)
+    response.must_have_response_keys ['access_token', 'expires_in', 'refresh_token']
   end
 
 end

data/mspec/helpers.rb

@@ -0,0 +1,9 @@
+module MiniTest::Spec::Helpers
+
+  def fixture_file(file_name)
+    File.open(ROOT_DIR + 'mspec/fixtures/' + file_name)
+  end
+
+end
+
+MiniTest::Unit::TestCase.send :include, MiniTest::Spec::Helpers

data/mspec/spec_helper.rb

@@ -1,23 +1,26 @@
 require 'minitest/pride'
 require 'minitest/autorun'
+require 'awesome_print'
+
 require 'pathname'
 ROOT_DIR = Pathname(File.dirname(File.expand_path(__FILE__))) + '..'
 $LOAD_PATH << (ROOT_DIR + 'lib').to_s
+
 require 'rgdata'
 require 'crack'
 
+$LOAD_PATH << (ROOT_DIR + 'mspec').to_s
+require 'helpers'
+require 'assertions'
+
+# Set these in your environment.
 RGData.config do
   client_id     ENV['GOOGLE_APPS_CLIENT_ID']
   client_secret ENV['GOOGLE_APPS_CLIENT_SECRET']
 end
 TEST_REFRESH_TOKEN = ENV['GOOGLE_APPS_REFRESH_TOKEN']
-
-module MiniTest::Spec::Helpers
-
-  def fixture_file(file_name)
-    File.open(ROOT_DIR + 'mspec/fixtures/' + file_name)
-  end
-
-end
-
-MiniTest::Unit::TestCase.send :include, MiniTest::Spec::Helpers
+TEST_DOMAIN        = ENV['GOOGLE_APPS_DOMAIN']
+TEST_REDIRECT_URI  = ENV['GOOGLE_REDIRECT_URI'] # THIS URI HAS TO BE REGISTERED WITH GOOGLE.
+# Test with authorization code? (See authorization_spec.rb test for more info on testing this.)
+authorization_code_arg = ARGV.detect { |arg| arg.start_with?('AUTHORIZATION_CODE') }
+TEST_AUTHORIZATION_CODE = authorization_code_arg ? /AUTHORIZATION_CODE=(?<code>.*)/.match(authorization_code_arg)[:code] : nil

metadata

@@ -2,7 +2,7 @@
 name: rgdata
 version: !ruby/object:Gem::Version 
   prerelease: 
-  version: 0.1.0
+  version: 0.2.1
 platform: ruby
 authors: 
 - Jared Ning
@@ -10,7 +10,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-04-01 00:00:00 -05:00
+date: 2011-04-10 00:00:00 -05:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -59,12 +59,15 @@ files:
 - lib/rgdata/models/profile.rb
 - lib/rgdata/version.rb
 - lib/support/hash.rb
+- lib/support/object.rb
 - mspec/api_spec.rb
 - mspec/apis/api_spec.rb
 - mspec/apis/profiles_spec.rb
+- mspec/assertions.rb
 - mspec/authentication_spec.rb
 - mspec/config_spec.rb
 - mspec/fixtures/profiles.xml
+- mspec/helpers.rb
 - mspec/models/profile_spec.rb
 - mspec/spec_helper.rb
 - rgdata.gemspec