koala 2.5.0 → 3.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: cb4d756e15fa642ec1e30f91d951f33d49c436f8
-  data.tar.gz: a3ba0cc83d91175c351ffccb09eef6078d299a28
+  metadata.gz: 6941f9efa1f2d1a275581f20b5d10977f3d73fdd
+  data.tar.gz: 726f62799f0c20c9266515dc6d68bc333e9995d0
 SHA512:
-  metadata.gz: c67c06d0e2978428f01a8e4f6d245715a6486fc2b572a152f49fcaf58c53fafc570885bd9df88450cded73e6b90b2ce72f6802b947ebdbf02aad8b5f2e3ca97f
-  data.tar.gz: b65059fbac83cd3d891baf4ce84a92cd53926644877be4ac76d80cebd5fc8ae630cd2997721bfb998b5067eb05a2576e12156ab62cee32c0f2fe0318f5e0f5c4
+  metadata.gz: 10d6e349ebe3e89487f9052840d12d27b52b5fce77cb649fb97e2554855bf39c12acf60da93c3c5e55bf2f0ea66b9533310c50cad23006da331b4e253dfa4e77
+  data.tar.gz: 67c74e5c4af1c273d4c1e7edae915897753b610357763bf398b8c8b6107853dbbdaf86ac174951e2efddadd9aa5a611cb343c0655388e7a75b407ba80823a1c4

data/.travis.yml

@@ -3,15 +3,17 @@ sudo: false
 cache: bundler
 rvm:
   # MRI
-  - 2.0
   - 2.1
   - 2.2
-  - 2.3.0
+  - 2.3.1
+  - 2.4.0
   # Rubinius is failing due to segfaults on Travis (and takes significantly longer to run)
   # those builds will be restored later
   # jruby
-  - jruby-19mode
+  # - jruby-19mode
 bundler_args: --without development
 addons:
   code_climate:
     repo_token: 7af99d9225b4c14640f9ec3cb2e24d2f7103ac49417b0bd989188fb6c25f2909
+after_success:
+    - bundle exec codeclimate-test-reporter

data/Gemfile

@@ -15,7 +15,7 @@ group :test do
   gem "rspec", '~> 3.4'
   gem "vcr"
   gem "webmock"
-  gem "codeclimate-test-reporter", require: nil
+  gem "codeclimate-test-reporter", "~> 1.0.0", require: nil
 end
 
 gem "jruby-openssl" if defined? JRUBY_VERSION

data/ISSUE_TEMPLATE

@@ -0,0 +1,25 @@
+Thanks for using Koala! Sorry you've run into an issue 😓  Here are some questions to help get things figured out as quickly as possible.
+
+You don't have to fill this all out -- it's more of a guide. If in doubt, delete any sections that aren't relevant and open the issue. I want to help.
+
+[ ] This is a Koala bug/issue/documentation problem.
+
+Koala is a labor of love both from me and from the awesome community members who answer questions here. Much as we'd love to be able to help with everything, I have to focus my time on issues with the gem itself and can't help with questions on how to _use_ Facebook. (Plus, Facebook is huge!)
+
+If you have questions about using the Facebook API, [facebook.stackoverflow.com](http://facebook.stackoverflow.com) is a great resource.
+
+_For code issues:_
+
+[ ] What I'm doing works on the [Graph API explorer](https://developers.facebook.com/tools/explorer/)/curl/another tool.
+
+Seeing an example of what works helps diagnose what doesn't work.
+
+[ ] I'm using the newest version
+[ ] Here's code to replicate the issue:
+
+Obviously not all code can be shared -- feel free to put variables in place of any sensitive information and describe what should be used to replicate it.
+
+Thanks for submitting an issue! Looking forward to working with you to figure it out.
+
+
+Note: Koala has a [code of conduct](https://github.com/arsduo/koala/blob/master/code_of_conduct.md). Check it out.

data/PULL_REQUEST_TEMPLATE

@@ -0,0 +1,11 @@
+Thanks for submitting a pull request to Koala! A huge portion of the gem has been built by awesome people (like you) from the Ruby community.
+
+Here are a few things that will help get your pull request merged in quickly. None of this is required -- you can delete anything not relevant. If in doubt, open the PR! I want to help.
+
+[ ] My PR has tests and they pass!
+[ ] The live tests pass for my changes (`LIVE=true rspec` -- unrelated failures are okay).
+[ ] The PR is based on the most recent master commit and has no merge conflicts.
+
+If you have any questions, feel free to open an issue or comment on your PR!
+
+Note: Koala has a [code of conduct](https://github.com/arsduo/koala/blob/master/code_of_conduct.md). Check it out.

data/changelog.md

@@ -1,4 +1,66 @@
-v2.5.0
+v3.0.0 (2017-03-17)
+======
+
+Most users should not see any difference upgrading from 2.x to 3.0. Most of the changes are
+internal to how requests go from a graph method (like `get_connections`) through the API to the
+HTTP layer and back. If you're not using API#api or HTTPService.make_request directly, upgrading
+should (in theory) require no code changes. (Let me know if you run into any issues.)
+
+**Key breaking changes:**
+
+* Koala now requires Ruby 2.1+ (or equivalent for JRuby, etc.)
+* API#api now returns a Koala::HTTPService::Response object; graph_call handles further processing
+* GraphBatchAPI no longer inherits from API (the interface is otherwise unchanged)
+* Empty response bodies in batch API calls will raise a JSON::ParserError rather than returning nil
+* HTTPService.make_request now requires an HTTPService::Request object (Koala.make_request does
+  not)
+* HTTPService behavior *should not* change, but in edge cases might. (If so, please let me know.)
+* API#search now requires a "type"/:type argument, matching Facebook's behavior (improving their
+  cryptic error message)
+
+New features:
+
+* Koala now supports global configuration for tokens, secrets, etc! See the readme.
+* GraphCollection now exposes #headers, allowing access to etag/rate limiting/etc. info (thanks,
+  pawandubey and jessieay!) (#589)
+
+Updated features:
+
+* Koala.config now uses a dedicated Koala::Configuration object
+* TestUser#befriend will provide the appsecret_proof if a secret is set (thanks, kwasimensah!)
+* API#search now requires an object type parameter to be included, matching Facebook's API (#575)
+* RealtimeUpdates will now only fetch the app access token if necessary, avoiding unnecessary calls
+
+Removed features:
+
+* Removed support for the Rest API, since Facebook removed support for it (#568)
+* Removed support for FQL, which Facebook removed on August 8, 2016 (#569)
+* Removed legacy duplication of serveral constants in the Koala module (#569)
+* Removed API#get_comments_for_urls, which pointed to a no-longer-extant endpoint(#570)
+
+Internal improvements:
+
+* Completely rewrote HTTPService.make_request and several others, extracting most logic into
+  HTTPService::Request (#566)
+* API#api now returns a Koala::HTTPService::Response object (#584)
+* GraphBatchAPI no longer inherits from API (#580)
+* GraphBatchAPI has been refactored to be simpler and more readable (thanks, acuppy!) (#551)
+* Use the more secure JSON.parse instead of JSON.load (thanks, lautis!) (#567)
+* Use JSON's quirks_mode option to remove hacky JSON hack (#573 -- thanks sakuro for the
+  suggestion!)
+* The gemspec now allows both JSON 1.8 and 2.0 (#596) (thanks, pawandubey!)
+* Remove Autotest and Guard references (no longer used/needed)
+
+Testing improvements:
+
+* Fixed a bunch of failing mocked specs
+
+Others:
+
+* Added an issue and pull request template
+* Updated Code of Conduct to 1.4
+
+v2.5.0 (2017-02-17)
 ======
 
 New features:
@@ -13,7 +75,7 @@ Internal improvements:
 
 * Remove MultiJson dependency (thanks, sakuro!)
 
-v2.4.0
+v2.4.0 (2016-07-08)
 ======
 
 **Note:** Koala is no longer officially supported on Ruby 1.9.3 (which was [end-of-lifed back in
@@ -36,7 +98,7 @@ Testing improvements:
 * Test Koala against Ruby 2.3.0 (thanks, thedrow!)
 
 
-v2.3.0
+v2.3.0 (2016-04-10)
 ======
 
 Updated features:
@@ -57,7 +119,7 @@ Testing improvements:
 * Removed pended specs that were no longer relevant
 * Improved https regex in test suite (thanks, lucaskds!)
 
-v2.2.0
+v2.2.0 (2015-08-11)
 ======
 
 Updated features:

data/code_of_conduct.md

@@ -1,22 +1,74 @@
-# Contributor Code of Conduct
+# Contributor Covenant Code of Conduct
 
-As contributors and maintainers of this project, and in the interest of fostering an open and welcoming community, we pledge to respect all people who contribute through reporting issues, posting feature requests, updating documentation, submitting pull requests or patches, and other activities.
+## Our Pledge
 
-We are committed to making participation in this project a harassment-free experience for everyone, regardless of level of experience, gender, gender identity and expression, sexual orientation, disability, personal appearance, body size, race, ethnicity, age, religion, or nationality.
+In the interest of fostering an open and welcoming environment, we as
+contributors and maintainers pledge to making participation in our project and
+our community a harassment-free experience for everyone, regardless of age, body
+size, disability, ethnicity, gender identity and expression, level of experience,
+nationality, personal appearance, race, religion, or sexual identity and
+orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to creating a positive environment
+include:
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+* Showing empathy towards other community members
 
 Examples of unacceptable behavior by participants include:
 
-* The use of sexualized language or imagery
-* Personal attacks
-* Trolling or insulting/derogatory comments
+* The use of sexualized language or imagery and unwelcome sexual attention or
+advances
+* Trolling, insulting/derogatory comments, and personal or political attacks
 * Public or private harassment
-* Publishing other's private information, such as physical or electronic addresses, without explicit permission
-* Other unethical or unprofessional conduct.
+* Publishing others' private information, such as a physical or electronic
+  address, without explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable
+behavior and are expected to take appropriate and fair corrective action in
+response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit, or
+reject comments, commits, code, wiki edits, issues, and other contributions
+that are not aligned to this Code of Conduct, or to ban temporarily or
+permanently any contributor for other behaviors that they deem inappropriate,
+threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community. Examples of
+representing a project or community include using an official project e-mail
+address, posting via an official social media account, or acting as an appointed
+representative at an online or offline event. Representation of a project may be
+further defined and clarified by project maintainers.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by contacting the project team at [INSERT EMAIL ADDRESS]. All
+complaints will be reviewed and investigated and will result in a response that
+is deemed necessary and appropriate to the circumstances. The project team is
+obligated to maintain confidentiality with regard to the reporter of an incident.
+Further details of specific enforcement policies may be posted separately.
 
-Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct. By adopting this Code of Conduct, project maintainers commit themselves to fairly and consistently applying these principles to every aspect of managing this project. Project maintainers who do not follow or enforce the Code of Conduct may be permanently removed from the project team.
+Project maintainers who do not follow or enforce the Code of Conduct in good
+faith may face temporary or permanent repercussions as determined by other
+members of the project's leadership.
 
-This code of conduct applies both within project spaces and in public spaces when an individual is representing the project or its community.
+## Attribution
 
-Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by opening an issue or contacting one or more of the project maintainers.
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
+available at [http://contributor-covenant.org/version/1/4][version]
 
-This Code of Conduct is adapted from the [Contributor Covenant](http://contributor-covenant.org), version 1.2.0, available at [http://contributor-covenant.org/version/1/2/0/](http://contributor-covenant.org/version/1/2/0/)
+[homepage]: http://contributor-covenant.org
+[version]: http://contributor-covenant.org/version/1/4/

data/koala.gemspec

@@ -21,6 +21,9 @@ Gem::Specification.new do |gem|
   gem.extra_rdoc_files = ["readme.md", "changelog.md"]
   gem.rdoc_options     = ["--line-numbers", "--inline-source", "--title", "Koala"]
 
+  gem.required_ruby_version = '>= 2.1'
+
   gem.add_runtime_dependency("faraday")
   gem.add_runtime_dependency("addressable")
+  gem.add_runtime_dependency("json", ">= 1.8")
 end

data/lib/koala/api/batch_operation.rb

@@ -1,4 +1,5 @@
 require 'koala/api'
+require 'koala/api/graph_batch_api'
 
 module Koala
   module Facebook
@@ -65,13 +66,13 @@ module Koala
         def process_binary_args
           # collect binary files
           @args.each_pair do |key, value|
-            if UploadableIO.binary_content?(value)
+            if HTTPService::UploadableIO.binary_content?(value)
               @files ||= {}
               # we use a class-level counter to ensure unique file identifiers across multiple batch operations
               # (this is thread safe, since we just care about uniqueness)
               # so remove the file from the original hash and add it to the file store
               id = "op#{identifier}_file#{@files.keys.length}"
-              @files[id] = @args.delete(key).is_a?(UploadableIO) ? value : UploadableIO.new(value)
+              @files[id] = @args.delete(key).is_a?(HTTPService::UploadableIO) ? value : HTTPService::UploadableIO.new(value)
             end
           end
         end
@@ -81,9 +82,5 @@ module Koala
         end
       end
     end
-
-    # @private
-    # legacy support for when BatchOperation lived directly under Koala::Facebook
-    BatchOperation = GraphBatchAPI::BatchOperation
   end
 end

data/lib/koala/api/{graph_api.rb → graph_api_methods.rb}

@@ -32,7 +32,6 @@ module Koala
     # for the active user from the cookie provided by Facebook.
     # See the Koala and Facebook documentation for more information.
     module GraphAPIMethods
-
       # Objects
 
       # Get information about a Facebook object.
@@ -107,7 +106,7 @@ module Koala
       # @return true if successful, false (or an APIError) if not
       def delete_object(id, options = {}, &block)
         # Deletes the object with the given ID from the graph.
-        raise AuthenticationError.new(nil, nil, "Delete requires an access token") unless @access_token
+        raise AuthenticationError.new(nil, nil, "Delete requires an access token") unless access_token
         graph_call(id, {}, "delete", options, &block)
       end
 
@@ -157,7 +156,7 @@ module Koala
       # @return a hash containing the new object's id
       def put_connections(id, connection_name, args = {}, options = {}, &block)
         # Posts a certain connection
-        raise AuthenticationError.new(nil, nil, "Write operations require an access token") unless @access_token
+        raise AuthenticationError.new(nil, nil, "Write operations require an access token") unless access_token
 
         graph_call("#{id}/#{connection_name}", args, "post", options, &block)
       end
@@ -175,7 +174,7 @@ module Koala
       # @return (see #delete_object)
       def delete_connections(id, connection_name, args = {}, options = {}, &block)
         # Deletes a given connection
-        raise AuthenticationError.new(nil, nil, "Delete requires an access token") unless @access_token
+        raise AuthenticationError.new(nil, nil, "Delete requires an access token") unless access_token
         graph_call("#{id}/#{connection_name}", args, "delete", options, &block)
       end
 
@@ -336,7 +335,7 @@ module Koala
       # @return (see #delete_object)
       def delete_like(id, options = {}, &block)
         # Unlikes a given object for the logged-in user
-        raise AuthenticationError.new(nil, nil, "Unliking requires an access token") unless @access_token
+        raise AuthenticationError.new(nil, nil, "Unliking requires an access token") unless access_token
         graph_call("#{id}/likes", {}, "delete", options, &block)
       end
 
@@ -344,14 +343,16 @@ module Koala
       # See {http://developers.facebook.com/docs/reference/api/#searching Facebook documentation} for more information.
       #
       # @param search_terms the query to search for
-      # @param args additional arguments, such as type, fields, etc.
+      # @param args object type and any additional arguments, such as fields, etc.
       # @param options (see #get_object)
       # @param block (see Koala::Facebook::API#api)
       #
       # @return [Koala::Facebook::API::GraphCollection] an array of search results
       def search(search_terms, args = {}, options = {}, &block)
-        args.merge!({:q => search_terms}) unless search_terms.nil?
-        graph_call("search", args, "get", options, &block)
+        # Normally we wouldn't enforce Facebook API behavior, but the API fails with cryptic error
+        # messages if you fail to include a type term. For a convenience method, that is valuable.
+        raise ArgumentError, "type must be includedin args when searching" unless args[:type] || args["type"]
+        graph_call("search", args.merge("q" => search_terms), "get", options, &block)
       end
 
       # Convenience Methods
@@ -359,45 +360,6 @@ module Koala
       # except to support cases where the Facebook API requires non-standard input
       # such as JSON-encoding arguments, posts directly to objects, etc.
 
-      # Make an FQL query.
-      # Convenience method equivalent to get_object("fql", :q => query).
-      #
-      # @param query the FQL query to perform
-      # @param args (see #get_object)
-      # @param options (see #get_object)
-      # @param block (see Koala::Facebook::API#api)
-      #
-      # @return the result of the FQL query.
-      def fql_query(query, args = {}, options = {}, &block)
-        get_object("fql", args.merge(:q => query), options, &block)
-      end
-
-      # Make an FQL multiquery.
-      # This method simplifies the result returned from multiquery into a more logical format.
-      #
-      # @param queries a hash of query names => FQL queries
-      # @param args (see #get_object)
-      # @param options (see #get_object)
-      # @param block (see Koala::Facebook::API#api)
-      #
-      # @example
-      #     @api.fql_multiquery({
-      #       "query1" => "select post_id from stream where source_id = me()",
-      #       "query2" => "select fromid from comment where post_id in (select post_id from #query1)"
-      #     })
-      #     # returns {"query1" => [obj1, obj2, ...], "query2" => [obj3, ...]}
-      #     # instead of [{"name":"query1", "fql_result_set":[]},{"name":"query2", "fql_result_set":[]}]
-      #
-      # @return a hash of FQL results keyed to the appropriate query
-      def fql_multiquery(queries = {}, args = {}, options = {}, &block)
-        resolved_results = if results = get_object("fql", args.merge(:q => JSON.dump(queries)), options)
-          # simplify the multiquery result format
-          results.inject({}) {|outcome, data| outcome[data["name"]] = data["fql_result_set"]; outcome}
-        end
-
-        block ? block.call(resolved_results) : resolved_results
-      end
-
       # Get a page's access token, allowing you to act as the page.
       # Convenience method for @api.get_object(page_id, :fields => "access_token").
       #
@@ -430,21 +392,6 @@ module Koala
         block ? block.call(access_token_info) : access_token_info
       end
 
-      # Fetches the comments from fb:comments widgets for a given set of URLs (array or comma-separated string).
-      # See https://developers.facebook.com/blog/post/490.
-      #
-      # @param urls the URLs for which you want comments
-      # @param args (see #get_object)
-      # @param options (see #get_object)
-      # @param block (see Koala::Facebook::API#api)
-      #
-      # @returns a hash of urls => comment arrays
-      def get_comments_for_urls(urls = [], args = {}, options = {}, &block)
-        return [] if urls.empty?
-        args.merge!(:ids => urls.respond_to?(:join) ? urls.join(",") : urls)
-        get_object("comments", args, options, &block)
-      end
-
       # App restrictions require you to JSON-encode the restriction value. This
       # is neither obvious nor intuitive, so this convenience method is
       # provided.
@@ -463,13 +410,13 @@ module Koala
       # Those methods use get_page to request another set of results from Facebook.
       #
       # @note You'll rarely need to use this method unless you're using Sinatra or another non-Rails framework
-      #       (see {Koala::Facebook::GraphCollection GraphCollection} for more information).
+      #       (see {Koala::Facebook::API::GraphCollection GraphCollection} for more information).
       #
       # @param params an array of arguments to graph_call
-      #               as returned by {Koala::Facebook::GraphCollection.parse_page_url}.
+      #               as returned by {Koala::Facebook::API::GraphCollection.parse_page_url}.
       # @param block (see Koala::Facebook::API#api)
       #
-      # @return Koala::Facebook::GraphCollection the appropriate page of results (an empty array if there are none)
+      # @return Koala::Facebook::API::GraphCollection the appropriate page of results (an empty array if there are none)
       def get_page(params, &block)
         graph_call(*params, &block)
       end
@@ -518,44 +465,8 @@ module Koala
         end
       end
 
-      # Make a call directly to the Graph API.
-      # (See any of the other methods for example invocations.)
-      #
-      # @param path the Graph API path to query (no leading / needed)
-      # @param args (see #get_object)
-      # @param verb the type of HTTP request to make (get, post, delete, etc.)
-      # @options (see #get_object)
-      #
-      # @yield response when making a batch API call, you can pass in a block
-      #        that parses the results, allowing for cleaner code.
-      #        The block's return value is returned in the batch results.
-      #        See the code for {#get_picture} or {#fql_multiquery} for examples.
-      #        (Not needed in regular calls; you'll probably rarely use this.)
-      #
-      # @raise [Koala::Facebook::APIError] if Facebook returns an error
-      #
-      # @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, response.headers)
-          raise error if error
-        end
-
-        # turn this into a GraphCollection if it's pageable
-        result = GraphCollection.evaluate(result, self)
-
-        # now process as appropriate for the given call (get picture header, etc.)
-        post_processing ? post_processing.call(result) : result
-      end
-
       private
 
-      def check_response(http_status, body, headers)
-        GraphErrorChecker.new(http_status, body, headers).error_if_appropriate
-      end
-
       def parse_media_args(media_args, method)
         # photo and video uploads can accept different types of arguments (see above)
         # so here, we parse the arguments into a form directly usable in put_connections
@@ -573,7 +484,7 @@ module Koala
           fb_expected_arg_name = method == "photos" ? :url : :file_url
           args.merge!(fb_expected_arg_name => media_args.first)
         else
-          args["source"] = Koala::UploadableIO.new(*media_args.slice(0, 1 + args_offset))
+          args["source"] = Koala::HTTPService::UploadableIO.new(*media_args.slice(0, 1 + args_offset))
         end
 
         [target_id, method, args, options]