koala 1.0.0.beta2.1 → 1.0.0

data/.gitignore

@@ -0,0 +1,3 @@
+pkg
+.project
+Gemfile.lock

data/CHANGELOG

@@ -1,26 +1,29 @@
 v1.0
 New methods:
 -- Photo and file upload now supported through #put_picture
-  -- 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:
--- 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: 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
--- Beta 3: Updated parse_signed_request to match Facebook's current implementation (thanks, imajes!)
+-- 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:
+-- 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/Gemfile

@@ -0,0 +1,3 @@
+source :rubygems
+
+gemspec

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/Rakefile

@@ -1,17 +1,16 @@
-# Rakefile
-require 'rubygems'
 require 'rake'
-require 'echoe'
 
-# gem management
-Echoe.new('koala', '1.0.0.beta2.1') 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"
-  p.author         = ["Alex Koppel", "Chris Baclig", "Rafi Jacoby", "Context Optional"]
-  p.email          = "alex@alexkoppel.com"
-  p.ignore_pattern = ["tmp/*", "script/*", "pkg/*"]
-  p.runtime_dependencies = ["json >=1.0", "multipart-post >=1.0"]
-  p.development_dependencies = []
-  p.retain_gemspec = true
+begin
+  require 'bundler/setup'
+  Bundler::GemHelper.install_tasks
+rescue LoadError
+  puts 'although not required, bundler is recommened for running the tests'
+end
+
+
+task :default => :spec
+
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new do |t|
+  t.rspec_opts = ["--color", '--format doc']
 end

data/koala.gemspec

@@ -1,35 +1,50 @@
 # -*- encoding: utf-8 -*-
 
 Gem::Specification.new do |s|
-  s.name = %q{koala}
-  s.version = "1.0.0.beta2.1"
+  s.name    = %q{koala}
+  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.}
+  s.homepage    = %q{http://github.com/arsduo/koala}
 
-  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{2011-04-06}
-  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", "lib/koala/test_users.rb", "lib/koala/uploadable_io.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", "lib/koala/test_users.rb", "lib/koala/uploadable_io.rb", "readme.md", "spec/facebook_data.yml", "spec/koala/api_base_tests.rb", "spec/koala/assets/beach.jpg", "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_tests.rb", "spec/koala/graph_api/graph_api_with_access_token_tests.rb", "spec/koala/graph_api/graph_collection_tests.rb", "spec/koala/http_services/http_service_tests.rb", "spec/koala/http_services/net_http_service_tests.rb", "spec/koala/http_services/typhoeus_service_tests.rb", "spec/koala/live_testing_data_helper.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_tests.rb", "spec/koala/rest_api/rest_api_with_access_token_tests.rb", "spec/koala/test_users/test_users_tests.rb", "spec/koala/uploadable_io/uploadable_io_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"]
-  s.require_paths = ["lib"]
-  s.rubyforge_project = %q{koala}
-  s.rubygems_version = %q{1.4.2}
-  s.summary = %q{A lightweight, flexible library for Facebook with support for the Graph API, the old REST API, realtime updates, and OAuth validation.}
+  s.email   = %q{alex@alexkoppel.com}
+
+  s.files = `git ls-files`.split("\n")
+  s.test_files = `git ls-files -- {test,spec,features}/*`.split("\n")
+
+  s.extra_rdoc_files = ["readme.md", "CHANGELOG"]
+  s.rdoc_options     = ["--line-numbers", "--inline-source", "--title", "Koala"]
+
+  s.require_paths     = ["lib"]
+
+  s.rubygems_version  = %q{1.4.2}
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 1.2") if s.respond_to? :required_rubygems_version=
 
   if s.respond_to? :specification_version then
     s.specification_version = 3
 
     if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
-      s.add_runtime_dependency(%q<json>, [">= 1.0"])
-      s.add_runtime_dependency(%q<multipart-post>, [">= 1.0"])
+      s.add_runtime_dependency(%q<json>,          ["~> 1.0"])
+      s.add_runtime_dependency(%q<multipart-post>,  ["~> 1.0"])
+      s.add_development_dependency(%q<rspec>,     ["~> 2.5.0"])
+      s.add_development_dependency(%q<rake>,      ["~> 0.8.7"])
+      s.add_development_dependency(%q<typhoeus>,  ["~> 0.2.4"])
     else
-      s.add_dependency(%q<json>, [">= 1.0"])
-      s.add_dependency(%q<multipart-post>, [">= 1.0"])
+      s.add_dependency(%q<json>,      ["~> 1.0"])
+      s.add_dependency(%q<multipart-post>,  ["~> 1.0"])
+      s.add_dependency(%q<rspec>,     ["~> 2.5.0"])
+      s.add_dependency(%q<rake>,      ["~> 0.8.7"])
+      s.add_dependency(%q<typhoeus>,  ["~> 0.2.4"])
     end
   else
-    s.add_dependency(%q<json>, [">= 1.0"])
-    s.add_dependency(%q<multipart-post>, [">= 1.0"])
+    s.add_dependency(%q<json>,      ["~> 1.0"])
+    s.add_dependency(%q<multipart-post>,  ["~> 1.0"])
+    s.add_dependency(%q<rspec>,     ["~> 2.5.0"])
+    s.add_dependency(%q<rake>,      ["~> 0.8.7"])
+    s.add_dependency(%q<typhoeus>,  ["~> 0.2.4"])
   end
 end

data/lib/koala/graph_api.rb

@@ -171,8 +171,8 @@ module Koala
       # Search
             
       def search(search_terms, args = {}, options = {})
-        # Searches for a given term among posts visible to the current user (or public posts if no token)
-        result = graph_call("search", args.merge(:q => search_terms), "get", options)
+        args.merge!({:q => search_terms}) unless search_terms.nil?
+        result = graph_call("search", args, "get", options)
         result ? GraphCollection.new(result, self) : nil # when facebook is down nil can be returned
       end      
       

data/lib/koala/http_services.rb

@@ -54,7 +54,7 @@ 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"
 
-          http = Net::HTTP.new(server(options), private_request ? 443 : nil)
+          http = create_http(server(options), private_request, options)
           http.use_ssl = true if private_request
 
           result = http.start do |http|
@@ -87,6 +87,22 @@ module Koala
             [key, value.kind_of?(Koala::UploadableIO) ? value.to_upload_io : value]
           end.flatten]
         end
+
+        def self.create_http(server, private_request, options)
+          if options[:proxy]
+            proxy = URI.parse(options[:proxy])
+            http  = Net::HTTP.new(server, private_request ? 443 : nil,
+                                  proxy.host, proxy.port, proxy.user, proxy.password)
+          else
+            http = Net::HTTP.new(server, private_request ? 443 : nil)
+          end
+          if options[:timeout]
+            http.open_timeout = options[:timeout]
+            http.read_timeout = options[:timeout]
+          end
+          http
+        end
+
       end
     end
   end
@@ -94,11 +110,6 @@ module Koala
   module TyphoeusService
     # this service uses Typhoeus to send requests to the graph
 
-    # used for multipart file uploads (see below)
-    class NetHTTPInterface
-      include NetHTTPService
-    end
-
     def self.included(base)
       base.class_eval do
         require "typhoeus" unless defined?(Typhoeus)
@@ -107,34 +118,28 @@ module Koala
         include Koala::HTTPService
 
         def self.make_request(path, args, verb, options = {})
-          unless params_require_multipart?(args)
-            # 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"
+          # 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"
 
-            # switch any UploadableIOs to the files Typhoeus expects 
-            # args.each_pair {|key, value| args[key] = value.to_file if value.is_a?(UploadableIO)}
+          # switch any UploadableIOs to the files Typhoeus expects 
+          args.each_pair {|key, value| args[key] = value.to_file if value.is_a?(UploadableIO)}
 
-            # you can pass arguments directly to Typhoeus using the :typhoeus_options key
-            typhoeus_options = {:params => args}.merge(options[:typhoeus_options] || {})
+          # you can pass arguments directly to Typhoeus using the :typhoeus_options key
+          typhoeus_options = {:params => args}.merge(options[:typhoeus_options] || {})
 
-            # by default, we use SSL only for private requests (e.g. with access token)
-            # this makes public requests faster
-            prefix = (args["access_token"] || @always_use_ssl || options[:use_ssl]) ? "https" : "http"
+          # by default, we use SSL only for private requests (e.g. with access token)
+          # this makes public requests faster
+          prefix = (args["access_token"] || @always_use_ssl || options[:use_ssl]) ? "https" : "http"
 
-            response = self.send(verb, "#{prefix}://#{server(options)}#{path}", typhoeus_options)
-            Koala::Response.new(response.code, response.body, response.headers_hash)
-          else
-            # we have to use NetHTTPService for multipart for file uploads
-            # until Typhoeus integrates support
-            Koala::TyphoeusService::NetHTTPInterface.make_request(path, args, verb, options)
-          end
+          response = self.send(verb, "#{prefix}://#{server(options)}#{path}", typhoeus_options)
+          Koala::Response.new(response.code, response.body, response.headers_hash)
         end
         
         private
-        # Typhoeus file uploads are not currently supported; this will be added when we can get them working
-        #def self.multipart_requires_content_type?
-        #  false # Typhoeus handles multipart file types, we don't have to require it
-        #end
+        
+        def self.multipart_requires_content_type?
+          false # Typhoeus handles multipart file types, we don't have to require it
+        end
       end # class_eval
     end
   end

data/lib/koala/test_users.rb

@@ -20,11 +20,11 @@ module Koala
         @graph_api = GraphAPI.new(@app_access_token)
       end
 
-      def create(installed, permissions = nil)
+      def create(installed, permissions = nil, args = {}, options = {})
         # Creates and returns a test user
-        args = {'installed' => installed}
+        args['installed'] = installed
         args['permissions'] = (permissions.is_a?(Array) ? permissions.join(",") : permissions) if installed
-        result = @graph_api.graph_call(accounts_path, args, "post")
+        result = @graph_api.graph_call(accounts_path, args, "post", options)
       end
       
       def list
@@ -49,7 +49,7 @@ module Koala
           # we explicitly raise an error here to minimize the risk of confusing output
           # if you pass in a string (as was previously supported) no local exception would be raised
           # but the Facebook call would fail
-          raise ArgumentError, "TestUsers#befriend requires hash arguments with id and access_token"
+          raise ArgumentError, "TestUsers#befriend requires hash arguments for both users with id and access_token"
         end
         
         u1_graph_api = GraphAPI.new(user1_token)

data/lib/koala/uploadable_io.rb

@@ -42,7 +42,7 @@ module Koala
       
       # Expects a parameter of type ActionDispatch::Http::UploadedFile
       def parse_rails_3_param(uploaded_file)
-        if uploaded_file.respond_to?(:content_type) and uploaded_file.respond_to?(:tempfile) and uploaded_file.respond_to?(:path)
+        if uploaded_file.respond_to?(:content_type) and uploaded_file.respond_to?(:tempfile) and uploaded_file.tempfile.respond_to?(:path)
           @io_or_path = uploaded_file.tempfile.path
           @content_type = uploaded_file.content_type
         end

data/lib/koala.rb

@@ -1,27 +1,17 @@
 require 'cgi'
 require 'digest/md5'
 
-# rubygems is required to support json, how facebook returns data
-require 'rubygems'
 require 'json'
 
 # OpenSSL and Base64 are required to support signed_request
 require 'openssl'
 require 'base64'
 
-# include default http services
+# include koala modules
 require 'koala/http_services'
-
-# add Graph API methods
 require 'koala/graph_api'
-
-# add REST API methods
 require 'koala/rest_api'
-
-# add realtime update methods
 require 'koala/realtime_updates'
-
-# add test user methods
 require 'koala/test_users'
 
 # add KoalaIO class
@@ -31,28 +21,12 @@ 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 
+      # initialize with an access token
       def initialize(access_token = nil)
         @access_token = access_token
       end
@@ -61,7 +35,7 @@ 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 =~ /^\//
 
@@ -173,12 +147,13 @@ module Koala
         # for permissions, see http://developers.facebook.com/docs/authentication/permissions
         permissions = options[:permissions]
         scope = permissions ? "&scope=#{permissions.is_a?(Array) ? permissions.join(",") : permissions}" : ""
-
+        display = options.has_key?(:display) ? "&display=#{options[:display]}" : ""
+        
         callback = options[:callback] || @oauth_callback_url
         raise ArgumentError, "url_for_oauth_code must get a callback either from the OAuth object or in the options!" unless callback
 
         # Creates the URL for oauth authorization for a given callback and optional set of permissions
-        "https://#{GRAPH_SERVER}/oauth/authorize?client_id=#{@app_id}&redirect_uri=#{callback}#{scope}"
+        "https://#{GRAPH_SERVER}/oauth/authorize?client_id=#{@app_id}&redirect_uri=#{callback}#{scope}#{display}"
       end
 
       def url_for_access_token(code, options = {})
@@ -188,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
@@ -225,19 +200,19 @@ module Koala
         raise "SignedRequest: Unsupported algorithm #{envelope['algorithm']}" if envelope['algorithm'] != 'HMAC-SHA256'
 
         # now see if the signature is valid (digest, key, data)
-        hmac = OpenSSL::HMAC.hexdigest('sha256', @app_secret, encoded_envelope.tr("-_", "+/"))
+        hmac = OpenSSL::HMAC.hexdigest(OpenSSL::Digest::SHA256.new, @app_secret, encoded_envelope.tr("-_", "+/"))
         raise 'SignedRequest: Invalid signature' if (signature != hmac)
 
         return envelope
       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 == ""
@@ -250,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/
@@ -284,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
@@ -299,7 +274,7 @@ module Koala
       end
     end
   end
-  
+
   class KoalaError< StandardError; end
 
   # finally, set up the http service Koala methods used to make requests

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/api_base_spec.rb

@@ -0,0 +1,101 @@
+require 'spec_helper'
+
+describe "Koala::Facebook::API" do
+  before(:each) do
+    @service = Koala::Facebook::API.new
+  end
+
+  it "should not include an access token if none was given" do
+    Koala.should_receive(:make_request).with(
+      anything,
+      hash_not_including('access_token' => 1),
+      anything,
+      anything
+    ).and_return(Koala::Response.new(200, "", ""))
+
+    @service.api('anything')
+  end
+
+  it "should include an access token if given" do
+    token = 'adfadf'
+    service = Koala::Facebook::API.new token
+
+    Koala.should_receive(:make_request).with(
+      anything,
+      hash_including('access_token' => token),
+      anything,
+      anything
+    ).and_return(Koala::Response.new(200, "", ""))
+
+    service.api('anything')
+  end
+
+  it "should have an attr_reader for access token" do
+    token = 'adfadf'
+    service = Koala::Facebook::API.new token
+    service.access_token.should == token
+  end
+
+  it "should get the attribute of a Koala::Response given by the http_component parameter" do
+    http_component = :method_name
+
+    response = mock('Mock KoalaResponse', :body => '', :status => 200)
+    response.should_receive(http_component).and_return('')
+
+    Koala.stub(:make_request).and_return(response)
+
+    @service.api('anything', 'get', {}, :http_component => http_component)
+  end
+
+  it "should return the body of the request as JSON if no http_component is given" do
+    response = stub('response', :body => 'body', :status => 200)
+    Koala.stub(:make_request).and_return(response)
+
+    json_body = mock('JSON body')
+    JSON.stub(:parse).and_return([json_body])
+
+    @service.api('anything').should == json_body
+  end
+
+  it "should execute a block with the response body if passed one" do
+    body = '{}'
+    Koala.stub(:make_request).and_return(Koala::Response.new(200, body, {}))
+
+    yield_test = mock('Yield Tester')
+    yield_test.should_receive(:pass)
+
+    @service.api('anything') do |arg|
+      yield_test.pass
+      arg.should == JSON.parse(body)
+    end
+  end
+
+  it "should raise an API error if the HTTP response code is greater than or equal to 500" do
+    Koala.stub(:make_request).and_return(Koala::Response.new(500, 'response body', {}))
+
+    lambda { @service.api('anything') }.should raise_exception(Koala::Facebook::APIError)
+  end
+
+  it "should handle rogue true/false as responses" do
+    Koala.should_receive(:make_request).and_return(Koala::Response.new(200, 'true', {}))
+    @service.api('anything').should be_true
+
+    Koala.should_receive(:make_request).and_return(Koala::Response.new(200, 'false', {}))
+    @service.api('anything').should be_false
+  end
+
+  describe "with regard to leading slashes" do
+    it "should add a leading / to the path if not present" do
+      path = "anything"
+      Koala.should_receive(:make_request).with("/#{path}", anything, anything, anything).and_return(Koala::Response.new(200, 'true', {}))
+      @service.api(path)
+    end
+
+    it "shouldn't change the path if a leading / is present" do
+      path = "/anything"
+      Koala.should_receive(:make_request).with(path, anything, anything, anything).and_return(Koala::Response.new(200, 'true', {}))
+      @service.api(path)
+    end
+  end
+
+end