koala 0.8.0 → 0.9.0

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.8.0"
+  s.version = "0.9.0"
 
   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-06-27}
+  s.date = %q{2010-09-30}
   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", "LICENSE", "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", "LICENSE", "Manifest", "Rakefile", "init.rb", "koala.gemspec", "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"]
+  s.files = ["CHANGELOG", "LICENSE", "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", "koala.gemspec", "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/graph_api/graph_collection_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"]
   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

@@ -5,6 +5,9 @@ require 'digest/md5'
 require 'rubygems'
 require 'json'
 
+# openssl is required to support signed_request
+require 'openssl'
+
 # include default http services
 require 'koala/http_services'
 
@@ -49,9 +52,13 @@ module Koala
       def api(path, args = {}, verb = "get", options = {}, &error_checking_block)
         # Fetches the given path in the Graph API.
         args["access_token"] = @access_token || @app_access_token if @access_token || @app_access_token
+
+        # add a leading /
+        path = "/#{path}" unless path =~ /^\//
+
         # make the request via the provided service
         result = Koala.make_request(path, args, verb, options)
-
+        
         # Check for any 500 errors before parsing the body
         # since we're not guaranteed that the body is valid JSON
         # in the case of a server error
@@ -189,6 +196,22 @@ module Koala
           string = info["access_token"] 
         end
       end
+      
+      # signed_request
+      def parse_signed_request(request)
+        # Facebook's signed requests come in two parts -- the signature and the data payload
+        # see http://developers.facebook.com/docs/authentication/canvas
+        encoded_sig, payload = request.split(".")
+        
+        sig = base64_url_decode(encoded_sig)
+
+        # if the signature matches, return the data, decoded and parsed as JSON
+        if OpenSSL::HMAC.digest("sha256", @app_secret, payload) == sig
+          JSON.parse(base64_url_decode(payload))
+        else
+          nil
+        end
+      end
 
       # from session keys
       def get_token_info_from_session_keys(sessions)
@@ -198,9 +221,8 @@ module Koala
           :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 == ""
+        # Facebook returns an empty body in certain error conditions
+        if response == "" 
           raise APIError.new("ArgumentError", "get_token_from_session_key received an error (empty response body) for sessions #{sessions.inspect}!")
         end
         
@@ -211,7 +233,7 @@ module Koala
         # get the original hash results
         results = get_token_info_from_session_keys(sessions)
         # now recollect them as just the access tokens
-        results.collect { |r| string = r["access_token"] }
+        results.collect { |r| r ? r["access_token"] : nil }
       end
       
       def get_token_from_session_key(session)
@@ -242,11 +264,19 @@ module Koala
       end
 
       def fetch_token_string(args, post = false, endpoint = "access_token")
-        Koala.make_request("oauth/#{endpoint}", {
+        Koala.make_request("/oauth/#{endpoint}", {
           :client_id => @app_id, 
           :client_secret => @app_secret
         }.merge!(args), post ? "post" : "get").body
       end
+      
+      # base 64
+      def base64_url_decode(string)
+        # to properly decode what Facebook provides, we need to add == to the end
+        # and translate certain characters to others before running the actual decoding
+        # see http://developers.facebook.com/docs/authentication/canvas 
+        "#{string}==".tr("-_", "+/").unpack("m")[0]
+      end
     end
   end
   

data/lib/koala/graph_api.rb

@@ -2,6 +2,59 @@ module Koala
   module Facebook
     GRAPH_SERVER = "graph.facebook.com"
 
+    class GraphCollection < Array
+      #This class is a light wrapper for collections returned
+      #from the Graph API.
+      #
+      #It extends Array to allow direct access to the data colleciton
+      #which should allow it to drop in seamlessly.
+      #
+      #It also allows access to paging information and the
+      #ability to get the next/previous page in the collection
+      #by calling next_page or previous_page.
+      attr_reader :paging
+      attr_reader :api
+      
+      def initialize(response, api)
+        super response["data"]
+        @paging = response["paging"]
+        @api = api
+      end
+            
+      # defines methods for NEXT and PREVIOUS pages
+      %w{next previous}.each do |this|
+        
+        # def next_page
+        # def previous_page
+        define_method "#{this.to_sym}_page" do
+          base, args = send("#{this}_page_params")
+          base ? @api.get_page([base, args]) : nil
+        end
+        
+        # def next_page_params
+        # def previous_page_params
+        define_method "#{this.to_sym}_page_params" do
+          return nil unless @paging and @paging[this]
+          parse_page_url(@paging[this])
+        end
+      end
+      
+      def parse_page_url(url)
+        match = url.match(/.com\/(.*)\?(.*)/)
+        base = match[1]
+        args = match[2]
+        params = CGI.parse(args)
+        new_params = {}
+        params.each_pair do |key,value|
+          new_params[key] = value.join ","
+        end
+        [base,new_params]
+      end
+      
+    end
+    
+    
+
     module GraphAPIMethods
       # A client for the Facebook Graph API.
       # 
@@ -41,11 +94,18 @@ module Koala
         # we raise an exception.
         graph_call("", args.merge("ids" => ids.join(",")))
       end
+      
+      def get_page(params)
+        result = graph_call(*params)
+        result ? GraphCollection.new(result, self) : nil # when facebook is down nil can be returned
+      end
     
       def get_connections(id, connection_name, args = {})
         # Fetchs the connections for given object.
-        graph_call("#{id}/#{connection_name}", args)["data"]
+        result = graph_call("#{id}/#{connection_name}", args)
+        result ? GraphCollection.new(result, self) : nil # when facebook is down nil can be returned
       end
+      
     
       def get_picture(object, args = {})
         result = graph_call("#{object}/picture", args, "get", :http_component => :headers)
@@ -113,7 +173,8 @@ module Koala
     
       def search(search_terms, args = {})
         # Searches for a given term
-        graph_call("search", args.merge({:q => search_terms}))
+        result = graph_call("search", args.merge({:q => search_terms}))
+        result ? GraphCollection.new(result, self) : nil # when facebook is down nil can be returned
       end
     
       def graph_call(*args)

data/lib/koala/http_services.rb

@@ -39,7 +39,7 @@ module Koala
 
         protected
         def self.encode_params(param_hash)
-          # TODO investigating whether a built-in method handles this
+          # unfortunately, we can't use to_query because that's Rails, not Ruby
           # if no hash (e.g. no auth token) return empty string
           ((param_hash || {}).collect do |key_and_value| 
             key_and_value[1] = key_and_value[1].to_json if key_and_value[1].class != String
@@ -61,7 +61,8 @@ module Koala
           # if the verb isn't get or post, send it as a post argument
           args.merge!({:method => verb}) && verb = "post" if verb != "get" && verb != "post"
           server = options[:rest_api] ? Facebook::REST_SERVER : Facebook::GRAPH_SERVER
-          response = self.send(verb, "https://#{server}/#{path}", :params => args)
+          typhoeus_options = {:params => args}.merge(options[:typhoeus_options] || {})
+          response = self.send(verb, "https://#{server}#{path}", typhoeus_options)
           Koala::Response.new(response.code, response.body, response.headers_hash)
         end
       end # class_eval