koala 1.8.0 → 1.9.0rc1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 3e1a6dda373cb710ccef9730d0df433344aaf70d
-  data.tar.gz: 8f3124c7b07d7ec70094f2d4eb113118c970285e
+  metadata.gz: 19a19ff9100a2e1c3374404311fa53f597cd5267
+  data.tar.gz: fc6230dc12b06d9c774f01a1159e125549103f9f
 SHA512:
-  metadata.gz: 0407cc6716f5c64eacc6c98b9b97258730a2a17e68c0cc577cd0e50fdbbca552c6c47745d9b1803e7c2eb19d5057afda93edc6741462e71552c804651087650b
-  data.tar.gz: dc3152b756199095a5ba3fdeee53f858b87915240862c2e409ab974ec88be9d8f6d4d734bfa251caf953afecc6488eed7be14df0ae4803e29ad462bd22207d8e
+  metadata.gz: 150c78781dfc53db7a56f964f2499c37c8f1fadd81dd9844f309fa8d52a4a8463623efab79803ed94a9fc8f926e1e85dcd9249bb8b088473e92a1fb1a44a5181
+  data.tar.gz: b3b2d5a6daa041cd2916e4455aef83feb1577522539ce216fa570961e767f4f98854df00e9f205549560c72048dcbca601b1b7f8626275ec91eb41c4b98461f5

data/.travis.yml

@@ -2,10 +2,10 @@ rvm:
   # MRI
   - 1.9.3
   - 2.0.0
-  - ruby-head
+  - 2.1.0
   # rbx
   - rbx-2.1.1
   - rbx
   # jruby
   - jruby-19mode
-  - jruby-head
+bundler_args: --without development

data/Gemfile

@@ -1,21 +1,17 @@
 source "https://rubygems.org"
 
 group :development do
+  gem 'debugger'
   gem "yard"
 end
 
 group :development, :test do
+  gem "rake"
   gem "typhoeus" unless defined? JRUBY_VERSION
+end
 
-  # Testing infrastructure
-  gem 'guard'
-  gem 'guard-rspec'
-
-  if RUBY_PLATFORM =~ /darwin/
-    # OS X integration
-    gem "ruby_gntp"
-    gem "rb-fsevent"
-  end
+group :test do
+  gem "rspec", '~> 3.0.0.beta1'
 end
 
 gem "jruby-openssl" if defined? JRUBY_VERSION

data/changelog.md

@@ -1,3 +1,21 @@
+v1.9.0
+======
+
+Updated Methods:
+* API#new now takes an optional access_token, which will be used to generate
+  the appsecret_proof parameters ([thanks,
+  nchelluri!](https://github.com/arsduo/koala/pull/323))
+
+Testing Improvements:
+* Add 2.1.0 to travis.yml and update specs to pass w/o deprecation on RSpec 3.0
+  ([thanks](https://github.com/arsduo/koala/pull/350),
+  [petergoldstein](https://github.com/arsduo/koala/pull/348)!)
+* With 1.9.0+ only support, removed the OrderedHash patch
+
+Documentation Improvements:
+* Make it clear that connections take a singlar form in API#put_connection
+(thanks, [josephdburdick](https://github.com/arsduo/koala/pull/349)!)
+
 v1.8.0
 =========
 
@@ -14,12 +32,13 @@ New methods:
 * OAuth#generate_client_code lets you get long-lived user tokens for client apps (thanks, binarygeek!)
 
 Updated methods:
-* API#new now takes an optional access_token, which will be used to generate
-  the appsecret_proof parameters ([thanks,
-  nchelluri!](https://github.com/arsduo/koala/pull/323))
 * GraphCollection#next_page and #previous_page can now take additional
   parameters ([thanks, gacha!](https://github.com/arsduo/koala/pull/330))
 
+NOTE: the appsecret_proof update from nchelluri was originally listed in the
+changelog for 1.8.0, but didn't make it in. It's now properly in the changelog
+for 1.9.0.
+
 Internal Improvements:
 * FIXED: TestUser#delete_all will avoid infinite loops if the user hashes
   change ([thanks, chunkerchunker!](https://github.com/arsduo/koala/pull/331))

data/koala.gemspec

@@ -23,6 +23,4 @@ Gem::Specification.new do |gem|
   gem.add_runtime_dependency("multi_json")
   gem.add_runtime_dependency("faraday")
   gem.add_runtime_dependency("addressable")
-  gem.add_development_dependency("rspec")
-  gem.add_development_dependency("rake")
 end

data/lib/koala.rb

@@ -38,6 +38,11 @@ module Koala
     def config
       @config ||= OpenStruct.new(HTTPService::DEFAULT_SERVERS)
     end
+
+    # Used for testing.
+    def reset_config
+      @config = nil
+    end
   end
 
   # @private

data/lib/koala/api.rb

@@ -1,19 +1,26 @@
 # graph_batch_api and legacy are required at the bottom, since they depend on API being defined
 require 'koala/api/graph_api'
 require 'koala/api/rest_api'
+require 'openssl'
 
 module Koala
   module Facebook
     class API
       # Creates a new API client.
       # @param [String] access_token access token
+      # @param [String] app_secret app secret, for tying your access tokens to your app secret
+      #                 If you provide an app secret, your requests will be
+      #                 signed by default, unless you pass appsecret_proof:
+      #                 false as an option to the API call. (See
+      #                 https://developers.facebook.com/docs/graph-api/securing-requests/)
       # @note If no access token is provided, you can only access some public information.
       # @return [Koala::Facebook::API] the API client
-      def initialize(access_token = nil)
+      def initialize(access_token = nil, app_secret = nil)
         @access_token = access_token
+        @app_secret = app_secret
       end
 
-      attr_reader :access_token
+      attr_reader :access_token, :app_secret
 
       include GraphAPIMethods
       include RestAPIMethods
@@ -45,6 +52,9 @@ module Koala
         # This is explicitly needed in batch requests so GraphCollection
         # results preserve any specific access tokens provided
         args["access_token"] ||= @access_token || @app_access_token if @access_token || @app_access_token
+        if options.delete(:appsecret_proof) && args["access_token"] && @app_secret
+          args["appsecret_proof"] = OpenSSL::HMAC.hexdigest(OpenSSL::Digest.new("sha256"), @app_secret, args["access_token"])
+        end
 
         # Translate any arrays in the params into comma-separated strings
         args = sanitize_request_parameters(args)

data/lib/koala/api/graph_api.rb

@@ -119,7 +119,8 @@ module Koala
 
       # Write an object to the Graph for a specific user.
       # See {http://developers.facebook.com/docs/api#publishing Facebook's documentation}
-      # for all the supported writeable objects.
+      # for all the supported writeable objects. It is important to note that objects 
+      # take the singular form, i.e. "event" when using put_connections.
       #
       # @note (see #get_connection)
       #
@@ -495,6 +496,8 @@ module Koala
       #
       # @return the result from Facebook
       def graph_call(path, args = {}, verb = "get", options = {}, &post_processing)
+        # enable appsecret_proof by default
+        options = {:appsecret_proof => true}.merge(options) if @app_secret
         result = api(path, args, verb, options) do |response|
           error = check_response(response.status, response.body)
           raise error if error

data/lib/koala/version.rb

@@ -1,3 +1,3 @@
 module Koala
-  VERSION = "1.8.0"
+  VERSION = "1.9.0rc1"
 end

data/readme.md

@@ -41,12 +41,19 @@ profile = @graph.get_object("me")
 friends = @graph.get_connections("me", "friends")
 @graph.put_connections("me", "feed", :message => "I am writing on my wall!")
 
-# three-part queries are easy too!
+# Three-part queries are easy too!
 @graph.get_connections("me", "mutualfriends/#{friend_id}")
 
-# you can even use the new Timeline API
-# see https://developers.facebook.com/docs/beta/opengraph/tutorial/
+# You can use the Timeline API:
+# (see https://developers.facebook.com/docs/beta/opengraph/tutorial/)
 @graph.put_connections("me", "namespace:action", :object => object_url)
+
+# For extra security (recommended), you can provide an appsecret parameter,
+# tying your access tokens to your app secret. 
+# (See https://developers.facebook.com/docs/reference/api/securing-graph-api/
+# You'll need to turn on 'Require proof on all calls' in the advanced section
+# of your app's settings when doing this.
+@graph = Koala::Facebook::API.new(oauth_access_token, app_secret)
 ```
 
 The response of most requests is the JSON data returned from the Facebook servers as a Hash.
@@ -223,14 +230,20 @@ The <a href="https://github.com/arsduo/koala/wiki/HTTP-Services">HTTP Services w
 
 See examples, ask questions
 -----
+
 Some resources to help you as you play with Koala and the Graph API:
 
 * Complete Koala documentation <a href="https://github.com/arsduo/koala/wiki">on the wiki</a>
-* The <a href="http://groups.google.com/group/koala-users">Koala users group</a> on Google Groups, the place for your Koala and API questions
+* Facebook's <a href="http://facebook.stackoverflow.com/">Stack Overflow site</a> is a stupendous place to ask questions, filled with people who will help you figure out what's up with the Facebook API.
 * Facebook's <a href="http://developers.facebook.com/tools/explorer/">Graph API Explorer</a>, where you can play with the Graph API in your browser
 * The Koala-powered <a href="http://oauth.twoalex.com" target="_blank">OAuth Playground</a>, where you can easily generate OAuth access tokens and any other data needed to test out the APIs or OAuth
 * Follow Koala on <a href="http://www.facebook.com/pages/Koala/315368291823667">Facebook</a> and <a href="https://twitter.com/#!/koala_fb">Twitter</a> for SDK updates and occasional news about Facebook API changes.
 
+*Note*: I use the Koala issues tracker on Github to triage and address issues
+with the gem itself; if you need help using the Facebook API, the above
+resources will be far more effective. Depending on how much time I have, Github
+issues filed about how to use the Facebook API may be closed with a reference
+to the Facebook Stack Overflow page.
 
 Testing
 -----

data/spec/cases/api_spec.rb

@@ -6,7 +6,7 @@ describe "Koala::Facebook::API" do
   end
 
   it "doesn't include an access token if none was given" do
-    Koala.should_receive(:make_request).with(
+    expect(Koala).to receive(:make_request).with(
       anything,
       hash_not_including('access_token' => 1),
       anything,
@@ -20,7 +20,7 @@ describe "Koala::Facebook::API" do
     token = 'adfadf'
     service = Koala::Facebook::API.new token
 
-    Koala.should_receive(:make_request).with(
+    expect(Koala).to receive(:make_request).with(
       anything,
       hash_including('access_token' => token),
       anything,
@@ -33,7 +33,13 @@ describe "Koala::Facebook::API" do
   it "has an attr_reader for access token" do
     token = 'adfadf'
     service = Koala::Facebook::API.new token
-    service.access_token.should == token
+    expect(service.access_token).to eq(token)
+  end
+
+  it "has an attr_reader for app_secret" do
+    secret = double
+    service = Koala::Facebook::API.new(@token, secret)
+    expect(service.app_secret).to eq(secret)
   end
 
   it "gets the attribute of a Koala::HTTPService::Response given by the http_component parameter" do
@@ -41,24 +47,24 @@ describe "Koala::Facebook::API" do
 
     response = double('Mock KoalaResponse', :body => '', :status => 200)
     result = double("result")
-    response.stub(http_component).and_return(result)
-    Koala.stub(:make_request).and_return(response)
+    allow(response).to receive(http_component).and_return(result)
+    allow(Koala).to receive(:make_request).and_return(response)
 
-    @service.api('anything', {}, 'get', :http_component => http_component).should == result
+    expect(@service.api('anything', {}, 'get', :http_component => http_component)).to eq(result)
   end
 
   it "returns the entire response if http_component => :response" do
     http_component = :response
     response = double('Mock KoalaResponse', :body => '', :status => 200)
-    Koala.stub(:make_request).and_return(response)
-    @service.api('anything', {}, 'get', :http_component => http_component).should == response
+    allow(Koala).to receive(:make_request).and_return(response)
+    expect(@service.api('anything', {}, 'get', :http_component => http_component)).to eq(response)
   end
 
   it "turns arrays of non-enumerables into comma-separated arguments" do
     args = [12345, {:foo => [1, 2, "3", :four]}]
     expected = ["/12345", {:foo => "1,2,3,four"}, "get", {}]
     response = double('Mock KoalaResponse', :body => '', :status => 200)
-    Koala.should_receive(:make_request).with(*expected).and_return(response)
+    expect(Koala).to receive(:make_request).with(*expected).and_return(response)
     @service.api(*args)
   end
 
@@ -70,57 +76,57 @@ describe "Koala::Facebook::API" do
     # or raise an exception
     expected = ["/12345", params, "get", {}]
     response = double('Mock KoalaResponse', :body => '', :status => 200)
-    Koala.should_receive(:make_request).with(*expected).and_return(response)
+    expect(Koala).to receive(:make_request).with(*expected).and_return(response)
     @service.api(*args)
   end
 
   it "returns the body of the request as JSON if no http_component is given" do
     response = double('response', :body => 'body', :status => 200)
-    Koala.stub(:make_request).and_return(response)
+    allow(Koala).to receive(:make_request).and_return(response)
 
     json_body = double('JSON body')
-    MultiJson.stub(:load).and_return([json_body])
+    allow(MultiJson).to receive(:load).and_return([json_body])
 
-    @service.api('anything').should == json_body
+    expect(@service.api('anything')).to eq(json_body)
   end
 
   it "executes an error checking block if provided" do
     response = Koala::HTTPService::Response.new(200, '{}', {})
-    Koala.stub(:make_request).and_return(response)
+    allow(Koala).to receive(:make_request).and_return(response)
 
     yield_test = double('Yield Tester')
-    yield_test.should_receive(:pass)
+    expect(yield_test).to receive(:pass)
 
     @service.api('anything', {}, "get") do |arg|
       yield_test.pass
-      arg.should == response
+      expect(arg).to eq(response)
     end
   end
 
   it "raises an API error if the HTTP response code is greater than or equal to 500" do
-    Koala.stub(:make_request).and_return(Koala::HTTPService::Response.new(500, 'response body', {}))
+    allow(Koala).to receive(:make_request).and_return(Koala::HTTPService::Response.new(500, 'response body', {}))
 
-    lambda { @service.api('anything') }.should raise_exception(Koala::Facebook::APIError)
+    expect { @service.api('anything') }.to raise_exception(Koala::Facebook::APIError)
   end
 
   it "handles rogue true/false as responses" do
-    Koala.should_receive(:make_request).and_return(Koala::HTTPService::Response.new(200, 'true', {}))
-    @service.api('anything').should be_true
+    expect(Koala).to receive(:make_request).and_return(Koala::HTTPService::Response.new(200, 'true', {}))
+    expect(@service.api('anything')).to be_truthy
 
-    Koala.should_receive(:make_request).and_return(Koala::HTTPService::Response.new(200, 'false', {}))
-    @service.api('anything').should be_false
+    expect(Koala).to receive(:make_request).and_return(Koala::HTTPService::Response.new(200, 'false', {}))
+    expect(@service.api('anything')).to be_falsey
   end
 
   describe "with regard to leading slashes" do
     it "adds a leading / to the path if not present" do
       path = "anything"
-      Koala.should_receive(:make_request).with("/#{path}", anything, anything, anything).and_return(Koala::HTTPService::Response.new(200, 'true', {}))
+      expect(Koala).to receive(:make_request).with("/#{path}", anything, anything, anything).and_return(Koala::HTTPService::Response.new(200, 'true', {}))
       @service.api(path)
     end
 
     it "doesn'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::HTTPService::Response.new(200, 'true', {}))
+      expect(Koala).to receive(:make_request).with(path, anything, anything, anything).and_return(Koala::HTTPService::Response.new(200, 'true', {}))
       @service.api(path)
     end
   end
@@ -150,4 +156,55 @@ describe "Koala::Facebook::API" do
     it_should_behave_like "Koala GraphAPI without an access token"
     it_should_behave_like "Koala GraphAPI with GraphCollection"
   end
+
+  context '#api' do
+    let(:access_token) { 'access_token' }
+    let(:api) { Koala::Facebook::API.new(access_token) }
+    let(:path) { '/path' }
+    let(:appsecret) { 'appsecret' }
+    let(:token_args) { { 'access_token' => access_token } }
+    let(:appsecret_proof_args) { { 'appsecret_proof' => OpenSSL::HMAC.hexdigest(OpenSSL::Digest.new('sha256'), appsecret, access_token) } }
+    let(:verb) { 'get' }
+    let(:response) { Koala::HTTPService::Response.new(200, '', '') }
+
+    describe "the appsecret_proof arguments" do
+      describe "with an API access token present" do
+        describe "and with an appsecret included on API initialization " do
+          let(:api) { Koala::Facebook::API.new(access_token, appsecret) }
+
+          it "will be included by default" do
+            Koala.should_receive(:make_request).with(path, token_args.merge(appsecret_proof_args), verb, {}).and_return(response)
+            api.api(path, {}, verb, :appsecret_proof => true)
+          end
+        end
+
+        describe "but without an appsecret included on API initialization" do
+          it "will not be included" do
+            Koala.should_receive(:make_request).with(path, token_args, verb, {}).and_return(response)
+            api.api(path, {}, verb, :appsecret_proof => true)
+          end
+        end
+      end
+
+      describe "but without an API access token present" do
+        describe "and with an appsecret included on API initialization " do
+          let(:api) { Koala::Facebook::API.new(nil, appsecret) }
+
+          it "will not be included" do
+            Koala.should_receive(:make_request).with(path, {}, verb, {}).and_return(response)
+            api.api(path, {}, verb, :appsecret_proof => true)
+          end
+        end
+
+        describe "but without an appsecret included on API initialization" do
+          let(:api) { Koala::Facebook::API.new }
+
+          it "will not be included" do
+            Koala.should_receive(:make_request).with(path, {}, verb, {}).and_return(response)
+            api.api(path, {}, verb, :appsecret_proof => true)
+          end
+        end
+      end
+    end
+  end
 end

data/spec/cases/error_spec.rb

@@ -2,23 +2,23 @@ require 'spec_helper'
 
 describe Koala::Facebook::APIError do
   it "is a Koala::KoalaError" do
-    Koala::Facebook::APIError.new(nil, nil).should be_a(Koala::KoalaError)
+    expect(Koala::Facebook::APIError.new(nil, nil)).to be_a(Koala::KoalaError)
   end
 
   [:fb_error_type, :fb_error_code, :fb_error_subcode, :fb_error_message, :http_status, :response_body].each do |accessor|
     it "has an accessor for #{accessor}" do
-      Koala::Facebook::APIError.instance_methods.map(&:to_sym).should include(accessor)
-      Koala::Facebook::APIError.instance_methods.map(&:to_sym).should include(:"#{accessor}=")
+      expect(Koala::Facebook::APIError.instance_methods.map(&:to_sym)).to include(accessor)
+      expect(Koala::Facebook::APIError.instance_methods.map(&:to_sym)).to include(:"#{accessor}=")
     end
   end
 
   it "sets http_status to the provided status" do
     error_response = '{ "error": {"type": "foo", "other_details": "bar"} }'
-    Koala::Facebook::APIError.new(400, error_response).response_body.should == error_response
+    expect(Koala::Facebook::APIError.new(400, error_response).response_body).to eq(error_response)
   end
 
   it "sets response_body to the provided response body" do
-    Koala::Facebook::APIError.new(400, '').http_status.should == 400
+    expect(Koala::Facebook::APIError.new(400, '').http_status).to eq(400)
   end
 
   context "with an error_info hash" do
@@ -39,12 +39,12 @@ describe Koala::Facebook::APIError do
       :fb_error_subcode => 'subcode'
     }.each_pair do |accessor, value|
       it "sets #{accessor} to #{value}" do
-        error.send(accessor).should == value
+        expect(error.send(accessor)).to eq(value)
       end
     end
 
     it "sets the error message \"type: error_info['type'], code: error_info['code'], error_subcode: error_info['error_subcode'], message: error_info['message'] [HTTP http_status]\"" do
-      error.message.should == "type: type, code: 1, error_subcode: subcode, message: message [HTTP 400]"
+      expect(error.message).to eq("type: type, code: 1, error_subcode: subcode, message: message [HTTP 400]")
     end
   end
 
@@ -52,7 +52,7 @@ describe Koala::Facebook::APIError do
     it "sets the error message \"error_info [HTTP http_status]\"" do
       error_info = "Facebook is down."
       error = Koala::Facebook::APIError.new(400, '', error_info)
-      error.message.should == "Facebook is down. [HTTP 400]"
+      expect(error.message).to eq("Facebook is down. [HTTP 400]")
     end
   end
 
@@ -66,7 +66,7 @@ describe Koala::Facebook::APIError do
         :fb_error_code => 1,
         :fb_error_subcode => 'subcode'
       }.each_pair do |accessor, value|
-        error.send(accessor).should == value
+        expect(error.send(accessor)).to eq(value)
       end
     end
   end
@@ -75,42 +75,42 @@ end
 
 describe Koala::KoalaError do
   it "is a StandardError" do
-     Koala::KoalaError.new.should be_a(StandardError)
+     expect(Koala::KoalaError.new).to be_a(StandardError)
   end
 end
 
 describe Koala::Facebook::OAuthSignatureError do
   it "is a Koala::KoalaError" do
-     Koala::KoalaError.new.should be_a(Koala::KoalaError)
+     expect(Koala::KoalaError.new).to be_a(Koala::KoalaError)
   end
 end
 
 describe Koala::Facebook::BadFacebookResponse do
   it "is a Koala::Facebook::APIError" do
-     Koala::Facebook::BadFacebookResponse.new(nil, nil).should be_a(Koala::Facebook::APIError)
+     expect(Koala::Facebook::BadFacebookResponse.new(nil, nil)).to be_a(Koala::Facebook::APIError)
   end
 end
 
 describe Koala::Facebook::OAuthTokenRequestError do
   it "is a Koala::Facebook::APIError" do
-     Koala::Facebook::OAuthTokenRequestError.new(nil, nil).should be_a(Koala::Facebook::APIError)
+     expect(Koala::Facebook::OAuthTokenRequestError.new(nil, nil)).to be_a(Koala::Facebook::APIError)
   end
 end
 
 describe Koala::Facebook::ServerError do
   it "is a Koala::Facebook::APIError" do
-     Koala::Facebook::ServerError.new(nil, nil).should be_a(Koala::Facebook::APIError)
+     expect(Koala::Facebook::ServerError.new(nil, nil)).to be_a(Koala::Facebook::APIError)
   end
 end
 
 describe Koala::Facebook::ClientError do
   it "is a Koala::Facebook::APIError" do
-     Koala::Facebook::ClientError.new(nil, nil).should be_a(Koala::Facebook::APIError)
+     expect(Koala::Facebook::ClientError.new(nil, nil)).to be_a(Koala::Facebook::APIError)
   end
 end
 
 describe Koala::Facebook::AuthenticationError do
   it "is a Koala::Facebook::ClientError" do
-     Koala::Facebook::AuthenticationError.new(nil, nil).should be_a(Koala::Facebook::ClientError)
+     expect(Koala::Facebook::AuthenticationError.new(nil, nil)).to be_a(Koala::Facebook::ClientError)
   end
 end