koala 1.0.0.rc → 1.0.0

data/CHANGELOG

@@ -1,31 +1,29 @@
 v1.0
 New methods:
 -- Photo and file upload now supported through #put_picture
-  -- RC: now supported natively through Typhoeus
-  -- Beta 2: support for Rails 3, Sinatra, File objects, and paths (see documentation)
-  -- Beta 2: Added UploadableIO class to manage file uploads
--- Added a delete_like method (thanks to wassem)
--- Beta 2: Added put_connection and delete_connection convenience methods
+  -- Added UploadableIO class to manage file uploads
+-- Added a delete_like method (thanks to waseem)
+-- Added put_connection and delete_connection convenience methods
 Updated methods:
--- RC: url_for_oauth_code can now take a :display option (thanks, netbe!)
--- RC: Net::HTTP can now accept :timeout and :proxy options (thanks, gilles!)
--- RC: search can now search places, checkins, etc. (thanks, rickyc!)
--- Beta 2: TestUser#befriend now requires user info hashes (id and access token) due to Facebook API changes (thanks to pulsd/kbighorse)
--- Beta 2: all methods now accept an http_options hash as their optional last parameter
--- Beta 2: You can now pass :beta => true in the http options to use Facebook's beta tier.
+-- Search can now search places, checkins, etc. (thanks, rickyc!)
+-- You can now pass :beta => true in the http options to use Facebook's beta tier.
+-- TestUser#befriend now requires user info hashes (id and access token) due to Facebook API changes (thanks, pulsd and kbighorse!)
+-- All methods now accept an http_options hash as their optional last parameter (thanks, spiegela!)
+-- url_for_oauth_code can now take a :display option (thanks, netbe!)
+-- Net::HTTP can now accept :timeout and :proxy options (thanks, gilles!)
+-- Test users now supports using test accounts across multiple apps
 Internal improvements: 
 -- For public requests, Koala now uses http by default (instead of https) to improve speed
   -- This can be overridden through Koala.always_use_ssl= or by passing :use_ssl => true in the options hash for an api call
 -- Read-only REST API requests now go through the faster api-read server
 -- Replaced parse_signed_request with a version from Facebook that also supports the new signed params proposal
   -- Note: invalid requests will now raise exceptions rather than return nil, in keeping with other SDKs
--- delete_object will now raise an error if there's no access token (like put_object and delete_like)
--- Beta 2.1: Updated parse_signed_request to match Facebook's current implementation (thanks, imajes!)
--- Beta 2: photo and file uploads now accept symbols as well as strings overall
--- Beta 2: APIError is now < StandardError, not Exception
--- Beta 2: Added KoalaError for non-API errors
+-- Delete methods will now raise an error if there's no access token (like put_object and delete_like)
+-- Updated parse_signed_request to match Facebook's current implementation (thanks, imajes!)
+-- APIError is now < StandardError, not Exception
+-- Added KoalaError for non-API errors
 Test improvements:
--- RC: Incorporated joshk's awesome rewrite of the entire Koala test suite (thanks, joshk!)
+-- Incorporated joshk's awesome rewrite of the entire Koala test suite (thanks, joshk!)
 -- Expanded HTTP service tests (added Typhoeus test suite and additional Net::HTTP test cases)
 -- Live tests now verify that the access token has the necessary permissions before starting
 -- Replaced the 50-person network test, which often took 15+ minutes to run live, with a 5-person test

data/LICENSE

@@ -1,6 +1,6 @@
 The MIT License
 
-Copyright (c) 2010 Alex Koppel
+Copyright (c) 2010-2011 Alex Koppel
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/koala.gemspec

@@ -2,8 +2,8 @@
 
 Gem::Specification.new do |s|
   s.name    = %q{koala}
-  s.version = "1.0.0.rc"
-  s.date    = %q{2011-04-18}
+  s.version = "1.0.0"
+  s.date    = %q{2011-05-01}
 
   s.summary     = %q{A lightweight, flexible library for Facebook with support for the Graph API, the REST API, realtime updates, and OAuth authentication.}
   s.description = %q{Koala is a lightweight, flexible Ruby SDK for Facebook.  It allows read/write access to the social graph via the Graph and REST APIs, 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.}

data/lib/koala.rb

@@ -21,25 +21,9 @@ module Koala
 
   module Facebook
     # Ruby client library for the Facebook Platform.
-    # Copyright 2010 Facebook
-    # Adapted from the Python library by Alex Koppel, Rafi Jacoby, and the team at Context Optional
-    #
-    # Licensed under the Apache License, Version 2.0 (the "License"); you may
-    # not use this file except in compliance with the License. You may obtain
-    # a copy of the License at
-    #     http://www.apache.org/licenses/LICENSE-2.0
-    #
-    # Unless required by applicable law or agreed to in writing, software
-    # distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
-    # WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
-    # License for the specific language governing permissions and limitations
-    # under the License.
-    #
-    # This client library is designed to support the Graph API and the official
-    # Facebook JavaScript SDK, which is the canonical way to implement
-    # Facebook authentication. Read more about the Graph API at
-    # http://developers.facebook.com/docs/api. You can download the Facebook
-    # JavaScript SDK at http://github.com/facebook/connect-js/.
+    # Copyright 2010-2011 Alex Koppel
+    # Contributors: Alex Koppel, Chris Baclig, Rafi Jacoby, and the team at Context Optional
+    # http://github.com/arsduo/koala
 
     class API
       # initialize with an access token
@@ -179,26 +163,26 @@ module Koala
         "https://#{GRAPH_SERVER}/oauth/access_token?client_id=#{@app_id}&redirect_uri=#{callback}&client_secret=#{@app_secret}&code=#{code}"
       end
 
-      def get_access_token_info(code)
+      def get_access_token_info(code, options = {})
         # convenience method to get a parsed token from Facebook for a given code
         # should this require an OAuth callback URL?
-        get_token_from_server(:code => code, :redirect_uri => @oauth_callback_url)
+        get_token_from_server({:code => code, :redirect_uri => @oauth_callback_url}, false, options)
       end
 
-      def get_access_token(code)
+      def get_access_token(code, options = {})
         # upstream methods will throw errors if needed
-        if info = get_access_token_info(code)
+        if info = get_access_token_info(code, options)
           string = info["access_token"]
         end
       end
 
-      def get_app_access_token_info
+      def get_app_access_token_info(options = {})
         # convenience method to get a the application's sessionless access token
-        get_token_from_server({:type => 'client_cred'}, true)
+        get_token_from_server({:type => 'client_cred'}, true, options)
       end
 
-      def get_app_access_token
-        if info = get_app_access_token_info
+      def get_app_access_token(options = {})
+        if info = get_app_access_token_info(options)
           string = info["access_token"]
         end
       end
@@ -223,12 +207,12 @@ module Koala
       end
 
       # from session keys
-      def get_token_info_from_session_keys(sessions)
+      def get_token_info_from_session_keys(sessions, options = {})
         # fetch the OAuth tokens from Facebook
         response = fetch_token_string({
           :type => 'client_cred',
           :sessions => sessions.join(",")
-        }, true, "exchange_sessions")
+        }, true, "exchange_sessions", options)
 
         # Facebook returns an empty body in certain error conditions
         if response == ""
@@ -241,24 +225,24 @@ module Koala
         JSON.parse(response)
       end
 
-      def get_tokens_from_session_keys(sessions)
+      def get_tokens_from_session_keys(sessions, options = {})
         # get the original hash results
-        results = get_token_info_from_session_keys(sessions)
+        results = get_token_info_from_session_keys(sessions, options)
         # now recollect them as just the access tokens
         results.collect { |r| r ? r["access_token"] : nil }
       end
 
-      def get_token_from_session_key(session)
+      def get_token_from_session_key(session, options = {})
         # convenience method for a single key
         # gets the overlaoded strings automatically
-        get_tokens_from_session_keys([session])[0]
+        get_tokens_from_session_keys([session], options)[0]
       end
 
       protected
 
-      def get_token_from_server(args, post = false)
+      def get_token_from_server(args, post = false, options = {})
         # fetch the result from Facebook's servers
-        result = fetch_token_string(args, post)
+        result = fetch_token_string(args, post, "access_token", options)
 
         # if we have an error, parse the error JSON and raise an error
         raise APIError.new((JSON.parse(result)["error"] rescue nil) || {}) if result =~ /error/
@@ -275,11 +259,11 @@ module Koala
         components
       end
 
-      def fetch_token_string(args, post = false, endpoint = "access_token")
+      def fetch_token_string(args, post = false, endpoint = "access_token", options = {})
         Koala.make_request("/oauth/#{endpoint}", {
           :client_id => @app_id,
           :client_secret => @app_secret
-        }.merge!(args), post ? "post" : "get", :use_ssl => true).body
+        }.merge!(args), post ? "post" : "get", {:use_ssl => true}.merge!(options)).body
       end
 
       # base 64

data/readme.md

@@ -7,12 +7,16 @@ Koala (<a href="http://github.com/arsduo/koala" target="_blank">http://github.co
 * Flexible: Koala should be useful to everyone, regardless of their current configuration.  (We have no dependencies beyond the JSON gem.  Koala also has a built-in mechanism for using whichever HTTP library you prefer to make requests against the graph.)
 * Tested: Koala should have complete test coverage, so you can rely on it.  (Our complete test coverage can be run against either mocked responses or the live Facebook servers.)
 
-1.0 beta
+1.0 
 ---
-Version 1.0 is currently in beta, chock-full of great new features.  To download the beta, just add --pre when installing the gem:
+Version 1.0 is due out on May 1st, 2011 with a ton of great features.  
     
-    sudo gem install koala --pre
+    sudo gem install koala
 
+Until then, you can install the release candidate like so:
+  
+    sudo gem install koala --pre
+  
 Graph API
 ----
 The Graph API is the simple, slick new interface to Facebook's data.  Using it with Koala is quite straightforward:
@@ -126,11 +130,14 @@ Testing
 -----
 
 Unit tests are provided for all of Koala's methods.  By default, these tests run against mock responses and hence are ready out of the box:
-    # From the spec directory
-    spec koala_spec.rb
+    
+    # From anywhere in the project directory:
+    rake spec
+    
 
 You can also run live tests against Facebook's servers:
-    # Again from the spec directory
-    spec koala_spec_without_mocks.rb
+    
+    # Again from anywhere in the project directory:
+    LIVE=true rake spec
 
-Important Note: to run the live tests, you have to provide some of your own data: a valid OAuth access token with publish\_stream, read\_stream, and user\_photos permissions and an OAuth code that can be used to generate an access token.  You can get these data at the OAuth Playground; if you want to use your own app, remember to swap out the app ID, secret, and other values.  (The file also provides valid values for other tests, which you're welcome to swap out for data specific to your own application.)
+Important Note: to run the live tests, you have to provide some of your own data in spec/fixtures/facebook_data.yml: a valid OAuth access token with publish\_stream, read\_stream, and user\_photos permissions and an OAuth code that can be used to generate an access token.  You can get thisdata at the OAuth Playground; if you want to use your own app, remember to swap out the app ID, secret, and other values.  (The file also provides valid values for other tests, which you're welcome to swap out for data specific to your own application.)

data/spec/cases/oauth_spec.rb

@@ -157,7 +157,6 @@ describe "Koala::Facebook::OAuth" do
     end
   
     describe "for access token URLs" do
-
       # url_for_access_token
       it "should generate a properly formatted OAuth token URL when provided a code" do 
         url = @oauth.url_for_access_token(@code)
@@ -204,6 +203,12 @@ describe "Koala::Facebook::OAuth" do
       it "should raise an error when get_access_token is called with a bad code" do
         lambda { @oauth.get_access_token("foo") }.should raise_error(Koala::Facebook::APIError) 
       end
+
+      it "should pass on any options provided to make_request" do
+        options = {:a => 2}
+        Koala.should_receive(:make_request).with(anything, anything, anything, hash_including(options)).and_return(Koala::Response.new(200, "", {}))
+        @oauth.get_access_token(@code, options)
+      end
     end
 
     describe "get_app_access_token_info" do
@@ -211,11 +216,17 @@ describe "Koala::Facebook::OAuth" do
         result = @oauth.get_app_access_token_info
         result.should be_a(Hash)
       end
-  
+        
       it "should include the access token" do
         result = @oauth.get_app_access_token_info
         result["access_token"].should
       end
+      
+      it "should pass on any options provided to make_request" do
+        options = {:a => 2}
+        Koala.should_receive(:make_request).with(anything, anything, anything, hash_including(options)).and_return(Koala::Response.new(200, "", {}))
+        @oauth.get_app_access_token_info(options)
+      end
     end
   
     describe "get_app_acess_token" do
@@ -229,6 +240,12 @@ describe "Koala::Facebook::OAuth" do
         original = @oauth.get_app_access_token_info
         result.should == original["access_token"]
       end
+      
+      it "should pass on any options provided to make_request" do
+        options = {:a => 2}
+        Koala.should_receive(:make_request).with(anything, anything, anything, hash_including(options)).and_return(Koala::Response.new(200, "", {}))
+        @oauth.get_app_access_token(options)
+      end
     end
     
     describe "protected methods" do
@@ -299,12 +316,18 @@ describe "Koala::Facebook::OAuth" do
         @oauth.should_receive(:fetch_token_string).and_return("")
         lambda { @oauth.get_token_info_from_session_keys(@oauth_data["multiple_session_keys"]) }.should raise_error(Koala::Facebook::APIError)
       end
+      
+      it "should pass on any options provided to make_request" do
+        options = {:a => 2}
+        Koala.should_receive(:make_request).with(anything, anything, anything, hash_including(options)).and_return(Koala::Response.new(200, "[{}]", {}))
+        @oauth.get_token_info_from_session_keys([], options)
+      end
     end
     
     describe "with get_tokens_from_session_keys" do
       it "should call get_token_info_from_session_keys" do
         args = @oauth_data["multiple_session_keys"]
-        @oauth.should_receive(:get_token_info_from_session_keys).with(args).and_return([])
+        @oauth.should_receive(:get_token_info_from_session_keys).with(args, anything).and_return([])
         @oauth.get_tokens_from_session_keys(args)
       end
       
@@ -325,12 +348,18 @@ describe "Koala::Facebook::OAuth" do
         # it should return nil for each of the invalid ones
         result.each_with_index {|r, index| index > 0 ? r.should(be_a(String)) : r.should(be_nil)}
       end
+      
+      it "should pass on any options provided to make_request" do
+        options = {:a => 2}
+        Koala.should_receive(:make_request).with(anything, anything, anything, hash_including(options)).and_return(Koala::Response.new(200, "[{}]", {}))
+        @oauth.get_tokens_from_session_keys([], options)
+      end
     end
 
     describe "get_token_from_session_key" do
       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.should_receive(:get_tokens_from_session_keys).with([key], anything).and_return([])
         @oauth.get_token_from_session_key(key)
       end
 
@@ -349,6 +378,12 @@ describe "Koala::Facebook::OAuth" do
         result = @oauth.get_token_from_session_key("foo")
         result.should be_nil
       end
+      
+      it "should pass on any options provided to make_request" do
+        options = {:a => 2}
+        Koala.should_receive(:make_request).with(anything, anything, anything, hash_including(options)).and_return(Koala::Response.new(200, "[{}]", {}))
+        @oauth.get_token_from_session_key("", options)
+      end
     end    
   end
   

data/spec/fixtures/mock_facebook_responses.yml

@@ -118,29 +118,31 @@ graph_api:
       get: 
         <<: *token_required
         with_token: '{"data": [{}]}'
-        
-  /chris.baclig/picture:
-    no_args:
+  
+  /lukeshepard/picture:
+    type=large:
       get:
         no_token:
           code: 302
           headers:
-            Location: http://facebook.com/
+            Location: https://facebook.com/large
         with_token:
           code: 302
           headers:
-            Location: http://facebook.com/
-    type=large:
+            Location: https://facebook.com/large
+    
+   
+  /chris.baclig/picture:
+    no_args:
       get:
         no_token:
           code: 302
           headers:
-            Location: http://facebook.com/large
+            Location: http://facebook.com/
         with_token:
           code: 302
           headers:
-            Location: http://facebook.com/large
-
+            Location: http://facebook.com/
 
   /search:
     q=facebook:

data/spec/support/graph_api_shared_examples.rb

@@ -57,11 +57,11 @@ shared_examples_for "Koala GraphAPI" do
   end
 
   it "should be able to access a user's picture" do
-    @api.get_picture("chris.baclig").should =~ /http\:\/\//
+    @api.get_picture("chris.baclig").should =~ /http[s]*\:\/\//
   end
 
   it "should be able to access a user's picture, given a picture type"  do
-    @api.get_picture("chris.baclig", {:type => 'large'}).should =~ /^http\:\/\//
+    @api.get_picture("lukeshepard", {:type => 'large'}).should =~ /^http[s]*\:\/\//
   end
 
   it "should be able to access connections from public Pages" do

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: koala
 version: !ruby/object:Gem::Version 
-  hash: 7712010
-  prerelease: 6
+  hash: 23
+  prerelease: 
   segments: 
   - 1
   - 0
   - 0
-  - rc
-  version: 1.0.0.rc
+  version: 1.0.0
 platform: ruby
 authors: 
 - Alex Koppel, Chris Baclig, Rafi Jacoby, Context Optional
@@ -16,10 +15,10 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-04-18 00:00:00 +02:00
-default_executable: 
+date: 2011-05-01 00:00:00 Z
 dependencies: 
 - !ruby/object:Gem::Dependency 
+  prerelease: false
   requirement: &id001 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
@@ -30,11 +29,11 @@ dependencies:
         - 1
         - 0
         version: "1.0"
-  prerelease: false
-  version_requirements: *id001
   type: :runtime
   name: json
+  version_requirements: *id001
 - !ruby/object:Gem::Dependency 
+  prerelease: false
   requirement: &id002 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
@@ -45,11 +44,11 @@ dependencies:
         - 1
         - 0
         version: "1.0"
-  prerelease: false
-  version_requirements: *id002
   type: :runtime
   name: multipart-post
+  version_requirements: *id002
 - !ruby/object:Gem::Dependency 
+  prerelease: false
   requirement: &id003 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
@@ -61,11 +60,11 @@ dependencies:
         - 5
         - 0
         version: 2.5.0
-  prerelease: false
-  version_requirements: *id003
   type: :development
   name: rspec
+  version_requirements: *id003
 - !ruby/object:Gem::Dependency 
+  prerelease: false
   requirement: &id004 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
@@ -77,11 +76,11 @@ dependencies:
         - 8
         - 7
         version: 0.8.7
-  prerelease: false
-  version_requirements: *id004
   type: :development
   name: rake
+  version_requirements: *id004
 - !ruby/object:Gem::Dependency 
+  prerelease: false
   requirement: &id005 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
@@ -93,10 +92,9 @@ dependencies:
         - 2
         - 4
         version: 0.2.4
-  prerelease: false
-  version_requirements: *id005
   type: :development
   name: typhoeus
+  version_requirements: *id005
 description: Koala is a lightweight, flexible Ruby SDK for Facebook.  It allows read/write access to the social graph via the Graph and REST APIs, 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.
 email: alex@alexkoppel.com
 executables: []
@@ -143,7 +141,6 @@ files:
 - spec/support/rest_api_shared_examples.rb
 - spec/support/setup_mocks_or_live.rb
 - spec/support/uploadable_io_shared_examples.rb
-has_rdoc: true
 homepage: http://github.com/arsduo/koala
 licenses: []
 
@@ -177,7 +174,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 
 rubyforge_project: 
-rubygems_version: 1.4.2
+rubygems_version: 1.7.2
 signing_key: 
 specification_version: 3
 summary: A lightweight, flexible library for Facebook with support for the Graph API, the REST API, realtime updates, and OAuth authentication.