gplus 0.3.1 → 0.4.0

data/README.md

@@ -1,19 +1,19 @@
-# Gplus: A Google+ API client library for Ruby
+# gplus: A Google+ API client library for Ruby
 
 ## Intro
 
-GPlus is a complete implementation of the Google+ API, with help from OAuth2 and MultiJson.
+gplus is a complete implementation of the Google+ API, with help from OAuth2 and MultiJson.
 
 I'm aiming to produce something light-weight, well documented, and thoroughly tested.
 
 It currently has full support for the People and Activities APIs, using either OAuth requests for private data or API key requests for public data.
 
-* [Documentation](http://rubydoc.info/gems/gplus/frames)
+* [Documentation](http://rubydoc.info/github/nfm/gplus/master/frames)
 * [Issues](https://github.com/nfm/gplus/issues)
 
 ## Installation
 
-Add GPlus to your Gemfile, then run `bundle install`.
+Add gplus to your Gemfile, then run `bundle install`.
 
     gem "gplus", "~> 0.3.1"
 
@@ -54,24 +54,48 @@ Generate an authorization URL, and use it in a view:
 
     = link_to 'Authorize This App', @auth_url
 
-After the user authorizes your app, they will be redirected to your `redirect_uri`. Store `params[:code]`:
+After the user authorizes your app, they will be redirected to your `redirect_uri`. Use `params[:code]` to retrieve an OAuth token for the user, and store the `token`, `refresh_token` and `expires_at` for persistence:
 
     class OauthController < ApplicationController
       def callback
-        current_user.update_attributes(:oauth_code => params[:code])
+        access_token = client.authorize(params[:code])
+        current_user.update_attributes(
+          :token => access_token.token,
+          :refresh_token => access_token.refresh_token,
+          :token_expires_at => access_token.expires_at
+        )
       end
     end
 
-Finally, create an authorized client instance:
-
-    client.authorize(current_user.oauth_code)
-
-If you have an OAuth code stored, you can use it to initialize your API client:
+Now you can create an authorized client instance using the stored OAuth token:
 
     @client = Gplus::Client.new(
-      :token => current_user.oauth_code,
+      :token => current_user.token,
+      :refresh_token => current_user.refresh_token,
+      :token_expires_at => current_user.token_expires_at,
+      :client_id => 'YOUR_CLIENT_ID',
+      :client_secret => 'YOUR_CLIENT_SECRET',
+      :redirect_uri => 'http://example.com/oauth/callback'
     )
 
+## Refreshing OAuth tokens
+
+Google+ OAuth tokens are currently only valid for 3600 seconds (one hour). You can use the `:refresh_token` to get a new OAuth token after your existing token expires, without requiring the user to re-authorize your application.
+
+Gplus will automatically request a new token if the provided token has expired. You should check to see if this has occured so that you can store the new token. Otherwise, after the initial token expires, you'll be requesting a new token from Google each time you initialize an API client. This is slow!
+
+You can determine whether a token has been refreshed by calling `access_token_refreshed?`:
+
+    if @client.access_token_refreshed?
+      access_token = @client.access_token
+      current_user.update_attributes(
+        :token => access_token.token,
+        :token_expires_at => access_token.expires_at
+      )
+    end
+
+The refreshed OAuth token will have `:refresh_token` set to `nil`. Keep using the initial `:refresh_token` you were given for all future refreshes.
+
 ## [People](http://developers.google.com/+/api/latest/people)
 
 Get a person's profile with `client.get_person`:
@@ -86,7 +110,7 @@ The person's profile will be returned as a nested hash:
     person[:urls].count
     person[:name][:middleName]
 
-See the API documentation for [People](http://developers.google.com/+/api/latest/people) and [People: get](http://developers.google.com/+/api/latest/people/get) for more info.
+See the Google+ API documentation for [People](http://developers.google.com/+/api/latest/people) and [People: get](http://developers.google.com/+/api/latest/people/get) for more info.
 
 ## [Activities](http://developers.google.com/+/api/latest/activities)
 
@@ -120,9 +144,9 @@ If you want more than 100 results, take the `:nextPageToken` returned from your
     activities = client.list_activities(id, :results => 100)
     more_activities = client.list_activities(id, :results => 100, :page => activities[:nextPageToken])
 
-See the API documentation for [Activities](http://developers.google.com/+/api/latest/activities), [Activities: get](http://developers.google.com/+/api/latest/activities/get) and [Activities: list](http://developers.google.com/+/api/latest/activities/list).
+See the Google+ API documentation for [Activities](http://developers.google.com/+/api/latest/activities), [Activities: get](http://developers.google.com/+/api/latest/activities/get) and [Activities: list](http://developers.google.com/+/api/latest/activities/list).
 
-## Contributing to Gplus
+## Contributing to gplus
 
 Please submit bug reports as [Github Issues](https://github.com/nfm/Gplus/issues).
 

data/lib/gplus/client.rb

@@ -8,16 +8,20 @@ module Gplus
     # @param [Hash] options
     # @option options [String] :api_key Your application's API key, used for non-authenticated requests (for public data).
     # @option options [String] :token The OAuth token to authorize the API client for authenticated requests (for non-public data). This can be supplied after initialization by calling {#authorize}.
+    # @option options [String] :refresh_token The OAuth refresh_token, to request a new token if the provided token has expired.
+    # @option options [Integer] :token_expires_at The time that the OAuth token expires at in seconds since the epoch.
     # @option options [String] :client_id Your application's Client ID. Required to generate an authorization URL with {#authorize_url}.
     # @option options [String] :client_secret Your application's Client Secret. Required to generate an authorization URL with {#authorize_url}.
     # @option options [String] :redirect_uri The default URI to redirect to after authorization. You can override this in many other methods. It must be specified as an authorized URI in your application's console. Required to generate an authorization URL with #authorize_url.
     # @return [Gplus::Client] A Google+ API client.
     def initialize(options = {})
       @api_key = options[:api_key]
+      @token = options[:token]
+      @refresh_token = options[:refresh_token]
+      @token_expires_at = options[:token_expires_at]
       @client_id = options[:client_id]
       @client_secret = options[:client_secret]
       @redirect_uri = options[:redirect_uri]
-      @token = options[:token]
 
       @oauth_client = OAuth2::Client.new(
         @client_id,
@@ -37,6 +41,7 @@ module Gplus
     end
 
     # Authorize an API client instance to access the user's private data.
+    #
     # @param [String] auth_code The code returned to your redirect_uri after the user authorized your application to access their Google+ data.
     # @param [String] redirect_uri An optional over-ride for the redirect_uri you initialized the API client with.
     # @return [OAuth2::AccessToken] An OAuth access token. Store access_token[:token] and access_token[:refresh_token] to get persistent access to the user's data until access_token[:expires_at].
@@ -44,13 +49,25 @@ module Gplus
       @access_token = @oauth_client.auth_code.get_token(auth_code, :redirect_uri => redirect_uri)
     end
 
-  private
+    # Retrieve or create an OAuth2::AccessToken, using the :token and :refresh_token specified when the API client instance was initialized
+    #
+    # @return An OAuth2::AccessToken
     def access_token
       if @token
-        @access_token ||= OAuth2::AccessToken.new(@oauth_client, @token)
+        @access_token ||= OAuth2::AccessToken.new(@oauth_client, @token, :refresh_token => @refresh_token, :expires_at => @token_expires_at)
+        if @access_token.expired?
+          @access_token.refresh!
+          @access_token_refreshed = true
+        end
       end
     end
 
+    # Return true if the user's access token has been refreshed. If so, you should store the new token's :token and :expires_at.
+    def access_token_refreshed?
+      @access_token_refreshed
+    end
+
+  private
     def get(path, params = {})
       if access_token
         response = access_token.get("v1/#{path}", params)

data/lib/gplus/version.rb

@@ -1,3 +1,3 @@
 module Gplus
-  VERSION = "0.3.1"
+  VERSION = "0.4.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: gplus
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.4.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,11 +9,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2011-09-17 00:00:00.000000000Z
+date: 2011-09-18 00:00:00.000000000Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: multi_json
-  requirement: &11450460 !ruby/object:Gem::Requirement
+  requirement: &18783920 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -21,10 +21,10 @@ dependencies:
         version: '1.0'
   type: :runtime
   prerelease: false
-  version_requirements: *11450460
+  version_requirements: *18783920
 - !ruby/object:Gem::Dependency
   name: oauth2
-  requirement: &11449420 !ruby/object:Gem::Requirement
+  requirement: &18783100 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -32,7 +32,7 @@ dependencies:
         version: '0.5'
   type: :runtime
   prerelease: false
-  version_requirements: *11449420
+  version_requirements: *18783100
 description: A complete implementation of the Google plus API for Ruby
 email:
 - nicholas@2suggestions.com.au