koala 0.7.1 → 0.7.2

data/CHANGELOG

@@ -1,3 +1,9 @@
+v0.7.2
+-- Added support for exchanging session keys for OAuth access tokens (get_token_from_session_key for single keys, get_tokens_from_session_keys for multiple)
+-- Moved Koala files into a koala/ subdirectory to minimize risk of name collisions
+-- Added OAuth Playground git submodule as an example 
+-- Updated tests, readme, and changelog
+
 v0.7.1
 -- Updated RealtimeUpdates#list_subscriptions and GraphAPI#get_connections to now return an 
 array of results directly (rather than a hash with one key)

data/Manifest

@@ -1,12 +1,26 @@
 CHANGELOG
 Manifest
 Rakefile
+examples/oauth_playground/Capfile
+examples/oauth_playground/LICENSE
+examples/oauth_playground/Rakefile
+examples/oauth_playground/config.ru
+examples/oauth_playground/config/deploy.rb
+examples/oauth_playground/config/facebook.yml
+examples/oauth_playground/lib/load_facebook.rb
+examples/oauth_playground/lib/oauth_playground.rb
+examples/oauth_playground/readme.md
+examples/oauth_playground/spec/oauth_playground_spec.rb
+examples/oauth_playground/spec/spec_helper.rb
+examples/oauth_playground/tmp/restart.txt
+examples/oauth_playground/views/index.erb
+examples/oauth_playground/views/layout.erb
 init.rb
-lib/graph_api.rb
-lib/http_services.rb
 lib/koala.rb
-lib/realtime_updates.rb
-lib/rest_api.rb
+lib/koala/graph_api.rb
+lib/koala/http_services.rb
+lib/koala/realtime_updates.rb
+lib/koala/rest_api.rb
 readme.md
 spec/facebook_data.yml
 spec/koala/api_base_tests.rb

data/Rakefile

@@ -4,7 +4,7 @@ require 'rake'
 require 'echoe'
 
 # gem management
-Echoe.new('koala', '0.7.1') do |p|
+Echoe.new('koala', '0.7.2') do |p|
   p.summary    = "A lightweight, flexible library for Facebook with support for the Graph API, the old REST API, realtime updates, and OAuth validation."
   p.description = "Koala is a lightweight, flexible Ruby SDK for Facebook.  It allows read/write access to the social graph via the Graph API and the older REST API, as well as support for realtime updates and OAuth and Facebook Connect authentication.  Koala is fully tested and supports Net::HTTP and Typhoeus connections out of the box and can accept custom modules for other services."
   p.url            = "http://github.com/arsduo/koala"

data/examples/oauth_playground/Capfile

@@ -0,0 +1,2 @@
+load 'deploy' if respond_to?(:namespace) # cap2 differentiator
+load 'config/deploy' # remove this line to skip loading any of the default tasks

data/examples/oauth_playground/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2010 Alex Koppel
+
+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/examples/oauth_playground/Rakefile

@@ -0,0 +1,4 @@
+namespace :oauth_playground do
+  
+  
+end

data/examples/oauth_playground/config/deploy.rb

@@ -0,0 +1,39 @@
+set :application, "oauth_playground"
+set :repository,  "git://github.com/arsduo/oauth_playground.git"
+set :domain, "oauth.twoalex.com"
+set :deploy_to, "$HOME/rails_apps/#{application}/"
+
+# authentication
+set :scm, "git"
+set :user, "alexkm"
+set :use_sudo, false
+ssh_options[:forward_agent] = true
+
+# web server
+role :web, "oauth.twoalex.com"                          # Your HTTP server, Apache/etc
+role :app, "oauth.twoalex.com"                          # This may be the same as your `Web` server
+role :db,  "oauth.twoalex.com", :primary => true  # This is where Rails migrations will run
+
+
+# other git-related commands
+set :branch, "master"
+default_run_options[:pty] = true
+# cache the repository locally to speed updates
+set :repository_cache, "git_cache" 
+set :deploy_via, :remote_cache
+
+
+# passenger-specific deploy tasks
+namespace :deploy do
+  task :start do
+    run "#{try_sudo} touch #{File.join(current_path,'tmp','restart.txt')}"
+  end
+  
+  task :stop do
+    # nothing
+  end
+  
+  task :restart, :roles => :app, :except => { :no_release => true } do
+    run "touch #{File.join(current_path,'tmp','restart.txt')}"
+  end
+end

data/examples/oauth_playground/config/facebook.yml

@@ -0,0 +1,13 @@
+development:
+  api_key: 
+  secret_key: 
+  app_id: 
+
+test:
+  api_key: 
+  secret_key: 
+
+production:
+  api_key: 
+  secret_key: 
+  app_id: 

data/examples/oauth_playground/config.ru

@@ -0,0 +1,27 @@
+# gems
+require 'sinatra'
+require 'logger'
+require 'yaml'
+
+# app files
+require 'koala'
+require File.join(File.dirname(__FILE__), 'lib', 'load_facebook.rb')
+require File.join(File.dirname(__FILE__), 'lib', 'oauth_playground.rb')
+
+# LOGGING
+# set up the logfile
+Dir.mkdir('log') unless File.exists?('log')
+log_filename = File.join(File.dirname(__FILE__), "log", "sinatra.log")
+log = File.new(log_filename, "a+")
+
+# log requests
+use Rack::CommonLogger, log 
+# log application-generated code
+LOGGER = Logger.new(log_filename) 
+# log output to stdout and stderr as well
+$stdout.reopen(log)
+$stderr.reopen(log)
+
+# activate the app
+disable :run
+run OAuthPlayground

data/examples/oauth_playground/lib/load_facebook.rb

@@ -0,0 +1,3 @@
+# load Facebook info for this environment
+FACEBOOK_INFO = YAML.load_file(File.join(File.dirname(__FILE__), "..", "config", "facebook.yml"))[ENV["RACK_ENV"]]
+

data/examples/oauth_playground/lib/oauth_playground.rb

@@ -0,0 +1,187 @@
+APP_ROOT = File.expand_path(File.join(File.dirname(__FILE__), '..'))
+
+require 'rubygems'
+require 'sinatra'
+require 'erb'
+
+class OAuthPlayground < Sinatra::Application
+  
+  set :root, APP_ROOT  
+
+  include Koala
+
+  layout :layout
+
+  get "/" do
+    @app_data = FACEBOOK_INFO.merge("callback_url" => "#{request.scheme}://#{request.host}/")
+    @oauth = Facebook::OAuth.new(@app_data["app_id"], @app_data["secret_key"], @app_data["callback_url"])
+    
+    # get authentication info
+    set_facebook_cookies 
+    set_oauth_data
+    set_access_token
+    
+    unless (@permissions = params[:permissions]) && @permissions.length > 0
+      @active_permissions = (get_active_permissions || {}).inject([]) do |active, perm| 
+        # collect our active permissions
+        active << perm[0].to_sym if perm[1] == 1
+        active
+      end
+      @fetched_permissions = true
+    else
+      @active_permissions = @permissions.collect {|p| p.to_sym}
+    end
+        
+    @available_permissions = [
+      {:name => "User Activity", :perms => ACTIVITY_PERMISSIONS},
+      {:name => "User Info", :perms => USER_PERMISSIONS},
+      {:name => "Friend Info", :perms => FRIEND_PERMISSIONS}
+    ]
+  
+    erb :index
+  end
+  
+  get "/subscriptions" do
+    # validate that this is a valid response
+    # it will automatically render the result of the verification
+    # e.g. either the challenge phrase or false
+    subscription = Facebook::RealtimeUpdates.meet_challenge(params) do |verification_token|
+      token_parts = verification_token.split("|")
+      expected = Digest::MD5.hexdigest("#{token_parts.first}~koala")
+      logger.info "expected: #{expected}"
+      logger.info "got: #{token_parts.last}"
+      # determine if this is a valid token -- that is, if the send part is a properly encoding of the first
+      expected == token_parts.last
+    end
+  end
+  
+  helpers do
+    def logger
+      LOGGER
+    end 
+  end
+
+  # helpers
+
+  # set up our understanding of the user's session
+  
+  def set_access_token
+    # get the access token from wherever we can
+    @access_token ||= (set_oauth_data && @oauth_access_token) || (set_facebook_cookies && @cookie_access_token)
+  end
+  
+  def set_oauth_data
+    unless @oauth_access_token
+      if (@code = params[:code]) && @raw_access_response = @oauth.send(:fetch_token_string, {:code => @code, :redirect_uri => @app_data["callback_url"]})
+        parsed = @oauth.send(:parse_access_token, @raw_access_response)
+        @oauth_access_token = parsed["access_token"]
+        @expiration = parsed["expires"] || "Does not expire (offline)"
+      end
+    end
+    
+    @oauth_access_token
+  end
+  
+  def set_facebook_cookies
+    unless @facebook_cookies
+      if @facebook_cookies = @oauth.get_user_from_cookie(request.cookies)
+        @cookie_access_token = @facebook_cookies["access_token"]
+      end
+    end
+    
+    @facebook_cookies
+  end
+  
+  def set_uid
+    # get the OAuth data, including fetching the access token, if available and necessary
+    # e.g. if we have an OAuth token and no cookie data    
+    unless @uid 
+      if @facebook_cookies
+        @uid = @facebook_cookies["uid"]
+      elsif token = set_access_token
+        # we have to fetch the info
+        @graph = Facebook::GraphAPI.new(token)
+        result = @graph.get_object("me")
+        @uid = result["id"]
+      end
+    end
+    @uid
+  end
+  
+  # fetch the active permissions about the user    
+  def get_active_permissions
+    set_access_token
+    if @access_token && !@permissions && set_uid
+      # if we don't have permissions set but have an access token
+      # grab the user's info
+      @rest = Facebook::RestAPI.new(@access_token)      
+      result = @rest.fql_query("select #{all_permissions.join(",")} from permissions where uid = #{@uid.to_s}")
+      result.first
+    end  
+  end
+  
+  # list of permissions
+
+  def all_permissions
+    ACTIVITY_PERMISSIONS + USER_PERMISSIONS + FRIEND_PERMISSIONS
+  end
+  
+  ACTIVITY_PERMISSIONS = [
+    :publish_stream, # Enables your application to post content, comments, and likes to a user's stream and to the streams of the user's friends, without prompting the user each time.
+    :create_event, # Enables your application to create and modify events on the user's behalf
+    :rsvp_event, # Enables your application to RSVP to events on the user's behalf
+    :sms, # Enables your application to send messages to the user and respond to messages from the user via text message
+    :offline_access # Enables your application to perform authorized requests on behalf of the user at any time. By default, most access tokens expire after a short time period to ensure applications only make requests on behalf of the user when the are actively using the application. This permission makes the access token returned by our OAuth endpoint long-lived.
+  ]
+
+  USER_PERMISSIONS = [
+    :email, # Provides access to the user's primary email address in the email property. Do not spam users. Your use of email must comply both with Facebook policies and with the CAN-SPAM Act.
+    :read_insights, # Provides read access to the Insights data for pages, applications, and domains the user owns.
+    :read_stream, # Provides access to all the posts in the user's News Feed and enables your application to perform searches against the user's News Feed
+    :user_about_me, # Provides access to the "About Me" section of the profile in the about property
+    :user_activities, # Provides access to the user's list of activities as the activities connection
+    :user_birthday, # Provides access to the full birthday with year as the birthday_date property
+    :user_education_history, # Provides access to education history as the education property
+    :user_events, # Provides access to the list of events the user is attending as the events connection
+    :user_groups, # Provides access to the list of groups the user is a member of as the groups connection
+    :user_hometown, # Provides access to the user's hometown in the hometown property
+    :user_interests, # Provides access to the user's list of interests as the interests connection
+    :user_likes, # Provides access to the list of all of the pages the user has liked as the likes connection
+    :user_location, # Provides access to the user's current location as the current_location property
+    :user_notes, # Provides access to the user's notes as the notes connection
+    :user_online_presence, # Provides access to the user's online/offline presence
+    :user_photo_video_tags, # Provides access to the photos the user has been tagged in as the photos connection
+    :user_photos, # Provides access to the photos the user has uploaded
+    :user_relationships, # Provides access to the user's family and personal relationships and relationship status
+    :user_religion_politics, # Provides access to the user's religious and political affiliations
+    :user_status, # Provides access to the user's most recent status message
+    :user_videos, # Provides access to the videos the user has uploaded
+    :user_website, # Provides access to the user's web site URL
+    :user_work_history # Provides access to work history as the work property
+  ]
+  
+  FRIEND_PERMISSIONS = [
+    :read_friendlists, # Provides read access to the user's friend lists
+    :read_requests, # Provides read access to the user's friend requests
+    :friends_about_me, # Provides access to the "About Me" section of the profile in the about property
+    :friends_activities, # Provides access to the user's list of activities as the activities connection
+    :friends_birthday, # Provides access to the full birthday with year as the birthday_date property
+    :friends_education_history, # Provides access to education history as the education property
+    :friends_events, # Provides access to the list of events the user is attending as the events connection
+    :friends_groups, # Provides access to the list of groups the user is a member of as the groups connection
+    :friends_hometown, # Provides access to the user's hometown in the hometown property
+    :friends_interests, # Provides access to the user's list of interests as the interests connection
+    :friends_likes, # Provides access to the list of all of the pages the user has liked as the likes connection
+    :friends_location, # Provides access to the user's current location as the current_location property
+    :friends_notes, # Provides access to the user's notes as the notes connection
+    :friends_online_presence, # Provides access to the user's online/offline presence
+    :friends_photo_video_tags, # Provides access to the photos the user has been tagged in as the photos connection
+    :friends_photos, # Provides access to the photos the user has uploaded
+    :friends_relationships, # Provides access to the user's family and personal relationships and relationship status
+    :friends_religion_politics, # Provides access to the user's religious and political affiliations
+    :friends_status, # Provides access to the user's most recent status message
+    :friends_videos, # Provides access to the videos the user has uploaded
+    :friends_website, # Provides access to the user's web site URL
+    :friends_work_history # Provides access to work history as the work property
+  ]
+end

data/examples/oauth_playground/readme.md

@@ -0,0 +1,8 @@
+A simple OAuth Playground chock full of the info you need to test your OAuth-based Facebook application.
+
+To Do's
+=======
+
+* Extend the permissions controls to cover all available permissions
+* Make expiration dates human-readable
+* Let people plug in their own app (updating the app's connect properties through setAppProperties)

data/examples/oauth_playground/spec/oauth_playground_spec.rb

@@ -0,0 +1,35 @@
+require 'spec_helper'
+require 'ruby-debug'
+
+describe 'OAuthPlayground' do
+  before :each do
+    @hydra = Typhoeus::Hydra.hydra
+  end
+  
+  after :each do 
+    @hydra.clear_stubs
+  end
+  
+  it 'should load the index' do
+    get '/'
+    last_response.should be_ok
+  end
+
+=begin  
+  # unfortunately, this fails when you pass the get method a param named code!
+  # fixing this will require some mucking around in Rack::Test
+  
+  it "should make a request to Facebook's OAuth server when passed a code" do 
+    test_string = Regexp.new("The time is #{Time.now.to_i}")
+
+    # stub out the request and make sure it's returned
+    @hydra.stub("https://#{Koala::Facebook::GRAPH_SERVER}/oauth/access_token", "get").and_return(test_string)
+    
+    get "/", {"code" => "foo_bar"}
+
+    # make sure the body includes the request string
+    last_response.body.should =~ test_string
+  end
+=end
+end
+

data/examples/oauth_playground/spec/spec_helper.rb

@@ -0,0 +1,36 @@
+require 'rubygems'
+require 'sinatra'
+require 'rack/test'
+require 'typhoeus'
+require 'koala'
+
+require File.join(File.dirname(__FILE__), '..', 'lib', 'oauth_playground.rb')
+require File.join(File.dirname(__FILE__), '..', 'lib', 'load_facebook.rb')
+
+OAuthPlayground.set(
+  :environment => :test,
+  :run => false,
+  :raise_errors => true,
+  :logging => false
+)
+
+module TestHelper
+  
+  def app
+    # change to your app class if using the 'classy' style
+    OAuthPlayground
+  end
+  
+  def body
+    last_response.body
+  end
+  
+  def status
+    last_response.status
+  end
+  
+  include Rack::Test::Methods
+
+end
+
+include TestHelper

data/examples/oauth_playground/views/index.erb

@@ -0,0 +1,206 @@
+<div id="header">
+	<h1>Facebook OAuth Playground</h1>
+	<h4>Powered by <a href="http://github.com/arsduo/koala" target="_blank">Koala</a></h2>
+	<h4>For novelty use only.  Remember, the application's secret key is public.</h4>
+</div>
+
+<style>
+	#header { 
+		text-align: center; 
+	} 
+	
+	h1, h2, h3, h4 { margin: 0; }
+
+	.section {
+		border: 1px solid black;
+		padding: 10px;
+		-moz-border-radius: 9px;
+		-webkit-border-radius: 9px;
+		margin-bottom: 10px;
+		width: 100%;
+	}
+	
+	#contents {
+		border: 2px solid #CCC;
+		border-width: 2px 0;
+		background-color: #EEE;
+		padding: 14px 3px 8px 8px;
+	}
+	
+	#configurationInfo {
+		float:left;
+		margin-right: 2.5%;
+		width: 25%;
+	}
+	
+	#configurationInfo .section {
+		background-color: #CCC;
+	}
+	
+	#permissions .header {
+		margin-bottom: 5px;
+	}
+	
+	#permissions .list {
+		height: 380px;
+		overflow: auto;
+	}
+	
+	#generatedInfo {
+		float: left;
+		width: 70%;
+	}
+	
+	#generatedInfo .section {
+		border-color: gray;
+		background: #DDD;
+		overflow: auto;
+	}
+	
+	.clearFloat {
+		height: 1px;
+		height: 0px;
+		clear: both;
+		overflow: hidden;
+	}
+	
+	ul, li { margin: 0; padding: 0; list-style: none; }
+	ul { margin: 12px 0; }
+
+	.code {
+		font-family: Courier, fixed;
+		font-size: 1.15em;
+		width: 100%;
+	}
+	
+	.explanation {
+		font-size: 0.9em;
+	}
+	
+	.datumName {
+		font-weight: bold;
+	}
+	
+	.permissionType {
+		font-style: italic;
+	}
+</style>
+	
+</style>
+
+<div id="contents">
+
+	<div id="configurationInfo">
+		<div id="fbApp" class="section">
+			<h3>Facebook App Info</h3>
+			<ul>
+				<% @app_data.each_pair do |key, value| %>
+					<li><span class="datumName"><%= key %>:</span> <%= value %></li>
+				<% end %>
+			</ul>
+		</div>
+		
+		<div id="permissions" class="section">
+			<form method="get">
+				<div class="header">
+					<h3>Permissions</h3>
+					<input type="submit" value="Update permissions" />
+					<a href="/">Reset Selection</a>
+					<div class="explanation">Choose permissions for the OAuth URL and the fb:login button.</div>
+					<% if @fetched_permissions %>
+						<div class="permissionType">Showing currently-active permissions</div>
+						<div class="explanation">(These were fetched by Koala as the page loaded!)</div>
+					<% else %>
+						<div class="permissionType">Showing selected permissions</div>
+					<% end %>
+				</div>
+		
+				<div class="list">
+					<% @available_permissions.each do |permissions| %>
+						<h4><%= permissions[:name] %> Permissions</h4>
+						<ul>
+							<% permissions[:perms].each do |p| %>
+								<li>
+									<input type="checkbox" id="permission<%= p %>" name="permissions[]" value="<%= p %>" <%= @active_permissions.include?(p) ? "checked='checked'" : "" %> />
+									<label for="permission<%= p %>"><%= p %></a> (<a href="#" onclick="FB.api({method: 'auth.revokeExtendedPermission', perm: '<%= p %>'}, function(response) { alert(response) }); return false;">revoke</a>)
+								</li>
+							<% end %>
+						</ul>
+					<% end %>
+				</div>
+			</form>
+		</div>
+	</div>
+
+	<div id="generatedInfo">		
+		<div id="oauthURLs" class="section">
+			<h3>OAuth URLs</h3>
+			<ul>
+				<li><span class="datumName">Generate a code:</span> <a href="<%= @oauth.url_for_oauth_code(:permissions => @permissions) %>"><%=  @oauth.url_for_oauth_code(:permissions => @permissions) %></a></li>
+				<li><span class="datumName">OAuth code:</span> <%= @code || "click on the link above" %></li>
+				<li>
+					<span class="datumName">Access token:</span> <%= @oauth_access_token || "click on the link above" %>
+					<% if @oauth_access_token %><div class="explanation">This was fetched by Koala as the page loaded!</div><% end %>
+				</li>
+				<li><span class="datumName">Expiration:</span> <%= @expiration || "click on the link above" %></li>
+				<li><span class="datumName">Raw access response:</span> <%= @raw_access_response || "click on the link above" %></li>
+				<li><span class="datumName">URL for access code:</span>
+					<% if @code %>
+						<a href="<%= @oauth.url_for_access_token(@code) %>"><%= @oauth.url_for_access_token(@code) %></a>
+					<% else %>
+						click on the link above
+					<% end %>
+				</li>
+			</ul>
+		</div>
+
+		<div id="jsLogin" class="section">
+			<h3>Javascript Login (e.g. Facebook Connect)</h3>
+			<p>
+				<fb:login-button onlogin="location.reload()" perms="<%= (@permissions || []).join(",") %>"></fb:login-button>
+				<% if @permissions %>
+					and prompt for <%= @permissions.join(", ") %>
+				<% end %>
+				<% if @facebook_cookies %>
+					<div class="logout">
+						<a href="#" onclick="FB.logout(function() { location.reload() }); return false;">Logout</a>
+					</div>
+				<% end %>
+			</p>
+		</div>
+
+		<div id="cookieInfo" class="section">
+			<h3>Cookie info</h3>
+			<ul>
+				<% if @facebook_cookies %>
+					<% @facebook_cookies.each_pair do |key, value| %>
+						<li><span class="datumName"><%= key %>:</span> <%= value %></li>
+					<% end %>
+				<% else %>
+					<li>You're not signed in via Javascript.  Login below.</li>
+				<% end %>
+				<li><span class="datumName">Raw hash</span>: 
+					<div class="code"><%= request.cookies.inspect %></div>
+				</li>
+			</ul>
+		</div>
+
+		<div id="koala" class="section">
+			<h3>Koala</h3>
+			<ul>
+				<li><span class="datumName">GraphAPI:</span>
+					<div class="code"><%= @access_token ? "@graph = Koala::Facebook::GraphAPI.new(\"#{@access_token}\")" : "sign in above" %></div>
+				</li>
+				<li><span class="datumName">OAuth:</span> 
+					<div class="code">@oauth = Koala::Facebook::OAuth.new(<%= @app_data["app_id"] %>, "<%= @app_data["secret_key"] %>", "<%= @app_data["callback_url"] %>")</div>
+				</li>
+			</ul>
+		</div>
+	</div>
+
+	<div class="clearFloat">&nbsp;</div>
+</div>
+
+<center>
+	<h5>Check out the playground's code at <a href="http://github.com/arsduo/oauth_playground">http://github.com/arsduo/oauth_playground</a>!</h5>
+</center>

data/examples/oauth_playground/views/layout.erb

@@ -0,0 +1,39 @@
+<html>
+<head>
+	<title>Facebook OAuth Playground</title>
+	<meta name="description" content="Making it easier to play with Facebook's new Graph API and OAuth authentication."></meta>
+	<style>
+		body {
+			font-family: verdana, arial, sans-serif;
+			font-size: 12px;
+			margin: 0px;
+		}
+	</style>
+</head>
+<body>
+
+<script type="text/javascript">
+
+  var _gaq = _gaq || [];
+  _gaq.push(['_setAccount', 'UA-16395421-1']);
+  _gaq.push(['_trackPageview']);
+
+  (function() {
+    var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
+    ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
+    var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
+  })();
+
+</script>
+	
+<%= yield %>		
+		
+<div id="fb-root"></div>
+<script src="http://connect.facebook.net/en_US/all.js"></script>
+<script>
+	FB.init({ appId: <%= @app_data["app_id"] %>, cookie: true, status: true, xfbml: true });
+</script>
+
+</body>
+
+</html>

data/koala.gemspec

@@ -2,15 +2,15 @@
 
 Gem::Specification.new do |s|
   s.name = %q{koala}
-  s.version = "0.7.1"
+  s.version = "0.7.2"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 1.2") if s.respond_to? :required_rubygems_version=
   s.authors = ["Alex Koppel, Chris Baclig, Rafi Jacoby, Context Optional"]
-  s.date = %q{2010-05-27}
+  s.date = %q{2010-06-02}
   s.description = %q{Koala is a lightweight, flexible Ruby SDK for Facebook.  It allows read/write access to the social graph via the Graph API and the older REST API, as well as support for realtime updates and OAuth and Facebook Connect authentication.  Koala is fully tested and supports Net::HTTP and Typhoeus connections out of the box and can accept custom modules for other services.}
   s.email = %q{alex@alexkoppel.com}
-  s.extra_rdoc_files = ["CHANGELOG", "lib/graph_api.rb", "lib/http_services.rb", "lib/koala.rb", "lib/realtime_updates.rb", "lib/rest_api.rb"]
-  s.files = ["CHANGELOG", "Manifest", "Rakefile", "init.rb", "lib/graph_api.rb", "lib/http_services.rb", "lib/koala.rb", "lib/realtime_updates.rb", "lib/rest_api.rb", "readme.md", "spec/facebook_data.yml", "spec/koala/api_base_tests.rb", "spec/koala/graph_and_rest_api/graph_and_rest_api_no_token_tests.rb", "spec/koala/graph_and_rest_api/graph_and_rest_api_with_token_tests.rb", "spec/koala/graph_api/graph_api_no_access_token_tests.rb", "spec/koala/graph_api/graph_api_with_access_token_tests.rb", "spec/koala/live_testing_data_helper.rb", "spec/koala/net_http_service_tests.rb", "spec/koala/oauth/oauth_tests.rb", "spec/koala/realtime_updates/realtime_updates_tests.rb", "spec/koala/rest_api/rest_api_no_access_token_tests.rb", "spec/koala/rest_api/rest_api_with_access_token_tests.rb", "spec/koala_spec.rb", "spec/koala_spec_helper.rb", "spec/koala_spec_without_mocks.rb", "spec/mock_facebook_responses.yml", "spec/mock_http_service.rb", "koala.gemspec"]
+  s.extra_rdoc_files = ["CHANGELOG", "lib/koala.rb", "lib/koala/graph_api.rb", "lib/koala/http_services.rb", "lib/koala/realtime_updates.rb", "lib/koala/rest_api.rb"]
+  s.files = ["CHANGELOG", "Manifest", "Rakefile", "examples/oauth_playground/Capfile", "examples/oauth_playground/LICENSE", "examples/oauth_playground/Rakefile", "examples/oauth_playground/config.ru", "examples/oauth_playground/config/deploy.rb", "examples/oauth_playground/config/facebook.yml", "examples/oauth_playground/lib/load_facebook.rb", "examples/oauth_playground/lib/oauth_playground.rb", "examples/oauth_playground/readme.md", "examples/oauth_playground/spec/oauth_playground_spec.rb", "examples/oauth_playground/spec/spec_helper.rb", "examples/oauth_playground/tmp/restart.txt", "examples/oauth_playground/views/index.erb", "examples/oauth_playground/views/layout.erb", "init.rb", "lib/koala.rb", "lib/koala/graph_api.rb", "lib/koala/http_services.rb", "lib/koala/realtime_updates.rb", "lib/koala/rest_api.rb", "readme.md", "spec/facebook_data.yml", "spec/koala/api_base_tests.rb", "spec/koala/graph_and_rest_api/graph_and_rest_api_no_token_tests.rb", "spec/koala/graph_and_rest_api/graph_and_rest_api_with_token_tests.rb", "spec/koala/graph_api/graph_api_no_access_token_tests.rb", "spec/koala/graph_api/graph_api_with_access_token_tests.rb", "spec/koala/live_testing_data_helper.rb", "spec/koala/net_http_service_tests.rb", "spec/koala/oauth/oauth_tests.rb", "spec/koala/realtime_updates/realtime_updates_tests.rb", "spec/koala/rest_api/rest_api_no_access_token_tests.rb", "spec/koala/rest_api/rest_api_with_access_token_tests.rb", "spec/koala_spec.rb", "spec/koala_spec_helper.rb", "spec/koala_spec_without_mocks.rb", "spec/mock_facebook_responses.yml", "spec/mock_http_service.rb", "koala.gemspec"]
   s.homepage = %q{http://github.com/arsduo/koala}
   s.rdoc_options = ["--line-numbers", "--inline-source", "--title", "Koala", "--main", "readme.md"]
   s.require_paths = ["lib"]

data/lib/koala.rb

@@ -6,15 +6,15 @@ require 'rubygems'
 require 'json'
 
 # include default http services
-require 'http_services'
+require 'koala/http_services'
 
 # add Graph API methods
-require 'graph_api'
+require 'koala/graph_api'
 
 # add REST API methods
-require 'rest_api'
+require 'koala/rest_api'
 
-require 'realtime_updates'
+require 'koala/realtime_updates'
 
 module Koala
     
@@ -156,7 +156,7 @@ module Koala
         raise ArgumentError, "url_for_access_token must get a callback either from the OAuth object or in the parameters!" unless callback
         "https://#{GRAPH_SERVER}/oauth/access_token?client_id=#{@app_id}&redirect_uri=#{callback}&client_secret=#{@app_secret}&code=#{code}"
       end
-      
+            
       def get_access_token(code)
         # convenience method to get a parsed token from Facebook for a given code
         # should this require an OAuth callback URL?
@@ -168,6 +168,27 @@ module Koala
         get_token_from_server({:type => 'client_cred'}, true)
       end
       
+      def get_tokens_from_session_keys(sessions)
+        # fetch the OAuth tokens from Facebook
+        response = fetch_token_string({
+          :type => 'client_cred',
+          :sessions => sessions.join(",")
+        }, true, "exchange_sessions")
+        
+        # get_token_from_session_key should return an empty body if an empty string or nil is provided
+        # if invalid tokens are provided, it returns an array of nulls, which is a valid result
+        if response == ""
+          raise APIError.new("ArgumentError", "get_token_from_session_key received an error (empty response body) for sessions #{sessions.inspect}!")
+        end
+        
+        JSON.parse(response)
+      end
+  
+      def get_token_from_session_key(session)
+        # convenience method for a single key
+        get_tokens_from_session_keys([session])[0]
+      end
+      
       protected
       
       def get_token_from_server(args, post = false)
@@ -189,8 +210,8 @@ module Koala
         components 
       end
 
-      def fetch_token_string(args, post = false)
-        Koala.make_request("oauth/access_token", {
+      def fetch_token_string(args, post = false, endpoint = "access_token")
+        Koala.make_request("oauth/#{endpoint}", {
           :client_id => @app_id, 
           :client_secret => @app_secret
         }.merge!(args), post ? "post" : "get").body

data/readme.md

@@ -34,7 +34,7 @@ We reserve the right to expand the built-in REST API coverage to additional conv
 OAuth
 -----
 You can use the Graph and REST APIs without an OAuth access token, but the real magic happens when you provide Facebook an OAuth token to prove you're authenticated.  Koala provides an OAuth class to make that process easy:
-     @oauth = Koala::Facebook::OAuth.new(app_id, code, callback_url)
+    @oauth = Koala::Facebook::OAuth.new(app_id, code, callback_url)
 
 If your application uses Koala and the Facebook [JavaScript SDK](http://github.com/facebook/connect-js) (formerly Facebook Connect), you can use the OAuth class to parse the cookies:
     @oauth.get_user_from_cookie(cookies)
@@ -50,6 +50,9 @@ You can also get your application's own access token, which can be used without
 
 That's it!  It's pretty simple once you get the hang of it.  If you're new to OAuth, though, check out the wiki and the OAuth Playground example site (see below).
 
+*Exchanging session keys:* Stuck building tab applications on Facebook?  Wishing you had an OAuth token so you could use the Graph API?  You're in luck! Koala now allows you to exchange session keys for OAuth access tokens:
+    @oauth.get_token_from_session_key(session_key)
+    @oauth.get_tokens_from_session_keys(array_of_session_keys)
 
 Real-time Updates
 -----

data/spec/facebook_data.yml

@@ -5,14 +5,19 @@
  
 # You must supply this value yourself to test the GraphAPI class.
 # Your OAuth token should have publish_stream and read_stream permissions.
-oauth_token: 119908831367602|2.6WkxQTbQPGFCyLblPYdsMg__.3600.1274979600-2905623|8YPVs-jBmpWC6y10pMCWzMRFrdk. 
+oauth_token: 119908831367602|2.r_nk_Ghvmy2OVfCqc2xD5w__.3600.1275534000-2905623|uRgZZ9WrZL7sBmS2f02G7UpMFZg. 
 
 # for testing the OAuth class    
 # baseline app
 oauth_test_data: 
   # You must supply this value yourself, since they will expire.
-  code:  2.6WkxQTbQPGFCyLblPYdsMg__.3600.1274979600-2905623|zHzbqwoONeqNxOXX7z9LZlpEGdc.
-    
+  code: 2.r_nk_Ghvmy2OVfCqc2xD5w__.3600.1275534000-2905623|4nUNPLdAgG0Q7PauPJ00TffIB88.
+  # easiest way to get session keys: use multiple test accounts with the Javascript login at http://oauth.twoalex.com
+  session_key: 2.r_nk_Ghvmy2OVfCqc2xD5w__.3600.1275534000-2905623
+  multiple_session_keys:
+    - 2.r_nk_Ghvmy2OVfCqc2xD5w__.3600.1275534000-2905623
+    - 2.r_nk2_Ghvmy2OVfCqc2xD5w__.3600.1275534000-2905623
+  
   # These values will work out of the box
   app_id: 119908831367602
   secret: e45e55a333eec232d4206d2703de1307

data/spec/koala/net_http_service_tests.rb

@@ -1,4 +1,4 @@
-require 'http_services'
+require 'koala/http_services'
   
 class NetHTTPServiceTests < Test::Unit::TestCase
   module Bear

data/spec/koala/oauth/oauth_tests.rb

@@ -157,8 +157,6 @@ class FacebookOAuthTests < Test::Unit::TestCase
       out.should_not be_nil
     end
 
-    # START CODE THAT NEEDS MOCKING
-
     # get_access_token
     it "should properly get and parse an access token token results" do
       result = @oauth.get_access_token(@code)
@@ -169,10 +167,37 @@ class FacebookOAuthTests < Test::Unit::TestCase
       lambda { @oauth.get_access_token("foo") }.should raise_error(Koala::Facebook::APIError) 
     end
     
+    # get_app_access_token
+    
     it "should properly get and parse an app's access token token results" do
       result = @oauth.get_app_access_token
       result["access_token"].should
     end
+
+    # get_tokens_from_session_keys
+    it "should get an array of session keys from Facebook when passed a single key" do
+      result = @oauth.get_tokens_from_session_keys([@oauth_data["session_key"]])
+      result.should be_an(Array)
+      result.length.should == 1
+    end
+
+    it "should get an array of session keys from Facebook when passed multiple keys" do
+      result = @oauth.get_tokens_from_session_keys(@oauth_data["multiple_session_keys"])
+      result.should be_an(Array)
+      result.length.should == 2
+    end
+
+    # get_token_from_session_key
+    it "should call get_tokens_from_session_keys when the get_token_from_session_key is called" do
+      key = @oauth_data["session_key"]
+      @oauth.should_receive(:get_tokens_from_session_keys).with([key]).and_return([])
+      @oauth.get_token_from_session_key(key)
+    end
+    
+    it "should get back a hash from get_token_from_session_key" do
+      result = @oauth.get_token_from_session_key(@oauth_data["session_key"])
+      result["access_token"].should
+    end
     
     # protected methods
     # since these are pretty fundamental and pretty testable, we want to test them

data/spec/mock_facebook_responses.yml

@@ -136,7 +136,15 @@ graph_api:
     client_id=<%= APP_ID %>&client_secret=<%= SECRET %>&type=client_cred:
       post:
         no_token: access_token=<%= ACCESS_TOKEN %>
-        
+  oauth/exchange_sessions:
+    client_id=<%= APP_ID %>&client_secret=<%= SECRET %>&sessions=<%= OAUTH_DATA["session_key"] %>&type=client_cred: 
+      post:
+        no_token: '[{"access_token":"<%= ACCESS_TOKEN %>","expires":4315}]'
+    client_id=<%= APP_ID %>&client_secret=<%= SECRET %>&sessions=<%= OAUTH_DATA["multiple_session_keys"].join(",") %>&type=client_cred: 
+      post:
+        no_token: '[{"access_token":"<%= ACCESS_TOKEN %>","expires":4315}, {"access_token":"<%= ACCESS_TOKEN %>","expires":4315}]'
+
+
 
 # -- Subscription Responses -- 
   <%= APP_ID %>/subscriptions:

data/spec/mock_http_service.rb

@@ -15,7 +15,11 @@ module Koala
     
     # Useful in mock_facebook_responses.yml
     OAUTH_DATA = TEST_DATA['oauth_test_data']
-    OAUTH_DATA.merge!('app_access_token' => Koala::MockHTTPService::ACCESS_TOKEN)
+    OAUTH_DATA.merge!({
+      'app_access_token' => Koala::MockHTTPService::ACCESS_TOKEN,
+      'session_key' => "session_key",
+      'multiple_session_keys' => ["session_key", "session_key_2"]
+    })
     APP_ID = OAUTH_DATA['app_id']
     SECRET = OAUTH_DATA['secret']
     SUBSCRIPTION_DATA = TEST_DATA["subscription_test_data"]

metadata

@@ -5,8 +5,8 @@ version: !ruby/object:Gem::Version
   segments: 
   - 0
   - 7
-  - 1
-  version: 0.7.1
+  - 2
+  version: 0.7.2
 platform: ruby
 authors: 
 - Alex Koppel, Chris Baclig, Rafi Jacoby, Context Optional
@@ -14,7 +14,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-05-27 00:00:00 -07:00
+date: 2010-06-02 00:00:00 -07:00
 default_executable: 
 dependencies: []
 
@@ -26,21 +26,35 @@ extensions: []
 
 extra_rdoc_files: 
 - CHANGELOG
-- lib/graph_api.rb
-- lib/http_services.rb
 - lib/koala.rb
-- lib/realtime_updates.rb
-- lib/rest_api.rb
+- lib/koala/graph_api.rb
+- lib/koala/http_services.rb
+- lib/koala/realtime_updates.rb
+- lib/koala/rest_api.rb
 files: 
 - CHANGELOG
 - Manifest
 - Rakefile
+- examples/oauth_playground/Capfile
+- examples/oauth_playground/LICENSE
+- examples/oauth_playground/Rakefile
+- examples/oauth_playground/config.ru
+- examples/oauth_playground/config/deploy.rb
+- examples/oauth_playground/config/facebook.yml
+- examples/oauth_playground/lib/load_facebook.rb
+- examples/oauth_playground/lib/oauth_playground.rb
+- examples/oauth_playground/readme.md
+- examples/oauth_playground/spec/oauth_playground_spec.rb
+- examples/oauth_playground/spec/spec_helper.rb
+- examples/oauth_playground/tmp/restart.txt
+- examples/oauth_playground/views/index.erb
+- examples/oauth_playground/views/layout.erb
 - init.rb
-- lib/graph_api.rb
-- lib/http_services.rb
 - lib/koala.rb
-- lib/realtime_updates.rb
-- lib/rest_api.rb
+- lib/koala/graph_api.rb
+- lib/koala/http_services.rb
+- lib/koala/realtime_updates.rb
+- lib/koala/rest_api.rb
 - readme.md
 - spec/facebook_data.yml
 - spec/koala/api_base_tests.rb