redd 0.6.0 → 0.6.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: b44594ffd55f136e44b2ec3ee48fa04b2d69c611
-  data.tar.gz: ed0efe9a7f3cf79b22aae8a3a8942cf1b6fc8699
+  metadata.gz: 6760b565561bde890fe1595ebda87ada31bae326
+  data.tar.gz: 7bccd9ea39fb2fa9d8201648d2c6164cab2791f6
 SHA512:
-  metadata.gz: b7903c63b7044e3f4abb504d9c9ec93f1360622e744c4e88ec282d9bdf4438a448ed8b2c4810ee7861a45b32b2a6eef3f81e74b51e17885aac0c1f977bf97381
-  data.tar.gz: 5f4142ff913b834502cbb0fe5d114c19a69c2cba1e7de735383baac3923040c4bc9e51302b5f183ef91532d7681d740968e346e9f51f846a30324ecb6f05a7cd
+  metadata.gz: 24762a4de14370f0d6cb4b9a79150c8d8db6f86a290d06edb82034e664f2b878cb48c37bf4a046fe5f03b23623bd8c6af2008ca9687154596da56bf34d522072
+  data.tar.gz: ba5116ceaa492bdefb12dcd626597fdf9989b301dcc66154240f844b38163cc944eb682290f0282bd9118785dd7919a1d87c1b343ab5071a3f4edf4e7847cc88

data/README.md

@@ -1,16 +1,19 @@
 <p align="center">
   <img src="https://i.imgur.com/2JfE4M1.png" alt="redd"><br>
-  <a href="http://badge.fury.io/rb/redd"><img src="https://badge.fury.io/rb/redd.svg" alt="Gem Version" height="18"></a>
-  <a href="https://travis-ci.org/avidw/redd"><img src="https://travis-ci.org/avidw/redd.svg?branch=master" alt="Build Status"></a>
+  <a href="https://rubygems.org/gems/redd"><img src="http://img.shields.io/gem/v/redd.svg?style=flat-square" alt="Gem Version"></a>
+  <a href="https://travis-ci.org/avidw/redd"><img src="http://img.shields.io/travis/avidw/redd.svg?style=flat-square" alt="Build Status"></a>
+  <a href="https://rubygems.org/gems/redd"><img src="http://img.shields.io/badge/license-MIT-blue.svg?style=flat-square" alt="MIT License"></a>
+  <a href="https://rubygems.org/gems/redd"><img src="http://img.shields.io/gem/dt/redd.svg?style=flat-square" alt="Gem Downloads"></a>
 </p>
 
 **redd** is an API wrapper for [reddit](http://reddit.com/dev/api) written in ruby that focuses on being *simple and extensible*.  
-Check out the latest documentation on [RubyDoc](http://rubydoc.info/github/avidw/redd/master/frames).
+**Check out the latest documentation on [RubyDoc](http://rubydoc.info/github/avidw/redd/master/frames).**
 
 ---
 
 <p align="center">
   <a href="#getting-started">Getting Started</a> |
+  <a href="#oauth2">OAuth2</a> |
   <a href="#extending-redd">Extending Redd</a> |
   <a href="#supported-rubies">Supported Rubies</a> |
   <a href="#copyright">Copyright</a>
@@ -23,6 +26,7 @@ Ruby and redd make creating reddit bots accessible and fun. To demonstrate, let'
 
 1. **Installing**  
    You can either install the gem directly by running `gem install redd` or by placing the gem into your `Gemfile` and running `bundle install`.
+
    ```ruby
    source "https://rubygems.org"
    gem "redd"
@@ -33,84 +37,189 @@ Ruby and redd make creating reddit bots accessible and fun. To demonstrate, let'
 
 2. **Setting Up**  
    Let's load up redd and create a client for us to work with. (The username and password aren't real!)
+
    ```ruby
    require "redd"
    #=> true
    
-   r = Redd.client "HelloWorldBot", "hunter2",
-                    user_agent: "HelloWorldBot v1.0 by /u/you"
+   r = Redd::Client::Authenticated.new_from_credentials "HelloWorldBot", "hunter2", user_agent: "HelloWorldBot v1.0 by /u/you"
    # => #<Redd::Client::Authenticated:0xY4D4y4D4y4dA ...
    ```
 
 3. **Scouting**  
-   Redd has a really cool method similar to praw's `helpers.comment_stream` that "streams" comments to you while avoiding duplicates. You won't have to take care of rate-limiting either; Redd `sleep`s after requests to avoid ratelimit errors. If you want to write a rate limiting class yourself, take a look at `lib/redd/rate_limit.rb`
+   Redd has a really cool method similar to praw's `helpers.comment_stream` that "streams" comments to you while avoiding duplicates. You won't have to take care of rate-limiting either; Redd `sleep`s after requests to avoid ratelimit errors. If you want to write a rate limiting class yourself, take a look at [`lib/redd/rate_limit.rb`](https://github.com/avidw/redd/blob/master/lib/redd/rate_limit.rb#L2-L23)
+
    ```ruby
    r.comment_stream "test" do |comment|
-     comment.reply "World!" if comment.body =~ /^Hello\?$/i
+      comment.reply "World!" if comment.body =~ /^Hello\?$/i
    end
    ```
 
 4. **Just in Case**  
    It's also a good idea to escape some common errors from reddit in case they happen:
+
    ```ruby
    begin
-     r.comment_stream "test" do |comment|
-       comment.reply "World!" if comment.body =~ /^Hello\?$/i
-     end
-   rescue Redd::Error::RateLimited => e
-     time_left = e.time
-     sleep(time_left)
-   rescue Redd::Error => e
-     status = e.code
-     # 5-something errors are usually errors on reddit's end.
-     raise e unless (500...600).include?(status)
+      r.comment_stream "test" do |comment|
+        comment.reply "World!" if comment.body =~ /^Hello\?$/i
+      end
+    rescue Redd::Error::RateLimited => e
+      time_left = e.time
+      sleep(time_left)
+    rescue Redd::Error => e
+      status = e.code
+      # 5-something errors are usually errors on reddit's end.
+      raise e unless (500...600).include?(status)
    end
    ```
 
+## OAuth2
+Redd also provides a wrapper to connect to reddit via OAuth2. The client's methods are similar to the authenticated client, given that you have the required scopes. Refer to [reddit's api](https://www.reddit.com/dev/api/oauth) for the various scopes. Getting it running is really simple and can even be used to integrate reddit's features into a [**Rails**](https://github.com/rails/rails) application. Another plus is that logging in via OAuth2 lets you make twice as many requests without hitting a rate limit (1/second). Let's try logging into reddit with [**sinatra**](http://www.sinatrarb.com/).
+
+The first thing you need to do is to create an OAuth2 application in reddit [**here**](https://ssl.reddit.com/prefs/apps). For more information, refer to [**"Getting Started"**](https://github.com/reddit/reddit/wiki/OAuth2#getting-started) on reddit's wiki. 
+
+Note: Although I enter the client id and secret in the code directly, I recommend you store them in environment variables or a **`.env`** file and load it with [**dotenv**](https://github.com/bkeepers/dotenv).
+
+```ruby
+# config.ru
+
+require "./connect_to_reddit"
+run ConnectToReddit
+```
+
+```ruby
+# connect_to_reddit.rb
+
+require "sinatra/base"
+require "redd"
+
+class ConnectToReddit < Sinatra::Base
+  configure do
+    enable :sessions
+
+    # If you're on Rails, you can replace the fixed url with a named one (e.g. redirect_url).
+    set :client, Redd::Client::OAuth2.new("sa_xTDcJ3dWz0w", "very-sensitive-secret", "http://localhost:8080/auth/reddit/redirect")
+  end
+
+  get "/auth/reddit" do
+    # Make use of the state!
+    # SecureRandom, which is included in Ruby, helps create a url-safe random string.
+    state = SecureRandom.urlsafe_base64
+    session[:state] = state
+    redirect settings.client.auth_url(["identity"], :temporary, state)
+  end
+
+  get "/auth/reddit/redirect" do
+    raise "Your state doesn't match!" unless session[:state] == params[:state]
+
+    # access is a Redd::OAuth2Access object.
+    access = settings.client.request_access(params[:code])
+    me = settings.client.with_access(access) { |client| client.me }
+
+    # Now use the Redd::Object::User object to create a user, maybe assign some
+    # sort of token to remember their session.
+    redirect to("/success")
+  end
+end
+```
+
+Now let's run the application:
+
+```shell
+$ rackup -p 8080
+```
+
+#### Remember Me
+If you want longer control of users' accounts for background tasks like auto-saving to a users' account behind the scenes or not have to ask your user to go through reddit every time, you can choose to have a permanent access by changing the second parameter of `auth_url`.
+
+```ruby
+client = Redd::Client::OAuth2.new("sa_xTDcJ3dWz0w", "very-sensitive-secret", "http://localhost:8080/auth/reddit/redirect")
+state = SecureRandom.urlsafe_base64
+auth_url = client.auth_url(["identity"], :permanent, state)
+```
+
+The access will still only last one hour, but you can refresh the access whenever you want.
+
+```ruby
+access = client.request_access(params[:code])
+
+# 1 hour or more later
+client.refresh_access(access) if access.expired?
+```
+
+Now if you are running a web application, you can't just store access tokens in memory. `Redd::OAuth2Access` offers a couple of methods for serializing the access to JSON and retrieving it.
+
+```ruby
+json = access.to_json
+current_user.update!(access: json) # Rails
+redis.set("some-token", json)      # Redis
+
+# After some time
+access = Redd::OAuth2Access.from_json(current_user.access)
+client.with_access(access) do |authenticated_client|
+  authenticated_client.do_whatever_redd_client_can_do
+end
+```
+
+#### Who, me?
+You can also revoke access tokens after the user has logged out to make sure the tokens can't be used for malicious purposes.
+
+```ruby
+also_revoke_refresh_token = true
+client.revoke_access(access, also_revoke_refresh_token)
+```
+
 ## Extending Redd
 Extending any ruby library, including redd is incredibly easy. Let's try this out by adding a gilding extension. Reddit provides an api to be able to gild posts and comments, given that you have "creddits".
 
 1. Let's start by creating a module for the methods to live in.
+
    ```ruby
    module MyGildingExtension
    end
    ```
 
 2. Let's add a method to gild a thing, using the [reddit api](http://www.reddit.com/dev/api#section_gold) and following the conventions.
+
    ```ruby
    module MyGildingExtension
-     def gild(thing)
-       # Redd::Client::Unauthenticated::Utilities has some pretty helpful
-       # methods.
-       fullname = extract_fullname(thing)
-
-       # We're using post instead of object_from_response, because we don't
-       # expect any object from the response.
-       post "/api/v1/gold/gild/#{fullname}"
-     end
+      def gild(thing)
+        # Redd::Client::Unauthenticated::Utilities has some pretty helpful
+        # methods.
+        fullname = extract_fullname(thing)
+
+        # We're using post instead of object_from_response, because we don't
+        # expect any object from the response.
+        post "/api/v1/gold/gild/#{fullname}"
+      end
    end
    ```
 
 3. Let's add the method to the Authenticated client. You can also add it to the Unauthenticated client, but since unauthenticated users can't gild, there's no point.
+
    ```ruby
    Redd::Client::Authenticated.include(MyGildingExtension)
    ```
 
 4. You might also want to add the method to objects to make it easier to access.
+
    ```ruby
    module Gildable
-     def gild
-       # Every Redd::Object is instantiated with the client that created
-       # it, so the method can be called on the client easily, similar to
-       # praw in python.
-       client.gild(self)
-     end
+      def gild
+        # Every Redd::Object is instantiated with the client that created
+        # it, so the method can be called on the client easily, similar to
+        # praw in python.
+        client.gild(self)
+      end
    end
 
    Redd::Object::Submission.include(Gildable)
    Redd::Object::Comment.include(Gildable)
    ```
 
+#### Contributing
+Please do. If you would like to become a contributor, do ask.
+
 ## Supported Rubies
 This gem aims to work on the following rubies:
 

data/RedditKit.LICENSE.md

@@ -1,4 +1,4 @@
-The error and base files would have been impossible if it weren't for @samsymons :)
+The error and base files would have been impossible if it weren't for [@samsymons](https://github.com/samsymons) :)
 
 ---
 
@@ -10,4 +10,4 @@ Permission is hereby granted, free of charge, to any person obtaining a copy of
 
 The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
 
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/lib/redd/client/authenticated/subreddits.rb

@@ -71,6 +71,18 @@ module Redd
           Redd::Object::Listing.new(data: {children: things})
         end
 
+        def edit_stylesheet(subreddit, contents, reason = nil)
+          name = extract_attribute(subreddit, :display_name)
+          path = "/r/#{name}/api/subreddit_stylesheet"
+          params = {
+            api_type: "json",
+            op: "save",
+            stylesheet_contents: contents
+          }
+          params[:reason] = reason if reason
+          post path, params
+        end
+
         private
 
         # Subscribe or unsubscribe to a subreddit.

data/lib/redd/client/oauth2/authorization.rb

@@ -95,9 +95,9 @@ module Redd
           params = {token: token}
 
           if remove_refresh_token
-            params[:token_type_hint] = true
+            params[:token_type_hint] = :refresh_token
           elsif remove_refresh_token == false
-            params[:token_type_hint] = false
+            params[:token_type_hint] = :access_token
           end
 
           auth_connection.post "/api/v1/revoke_token", params

data/lib/redd/client/unauthenticated.rb

@@ -64,7 +64,7 @@ module Redd
 
       # Gets the Faraday connection or creates one if it doesn't exist yet.
       #
-      # @return [Faraday] A new Faraday connection.
+			# @return [Faraday] A new or existing Faraday connection.
       def connection
         @connection ||= Faraday.new(url: api_endpoint) do |faraday|
           faraday.use Faraday::Request::UrlEncoded
@@ -80,36 +80,36 @@ module Redd
       #
       # @param [#to_sym] method The HTTP verb to use.
       # @param [String] path The path under the api endpoint to request from.
-      # @param [Hash] params The additional parameters to send (defualt: {}).
-      # @return [String] The response body.
+      # @param [Hash] params The additional parameters to send.
+			# @return [Faraday::Response] The faraday response.
       def request(method, path, params = {})
         rate_limit.after_limit do
-          connection.send(method.to_sym, path, params).body
+          connection.send(method.to_sym, path, params)
         end
       end
 
       # Performs a GET request via {#request}.
       # @see #request
       def get(*args)
-        request(:get, *args)
+        request(:get, *args).body
       end
 
       # Performs a POST request via {#request}.
       # @see #request
       def post(*args)
-        request(:post, *args)
+        request(:post, *args).body
       end
 
       # Performs a PUT request via {#request}.
       # @see #request
       def put(*args)
-        request(:put, *args)
+        request(:put, *args).body
       end
 
       # Performs a DELETE request via {#request}.
       # @see #request
       def delete(*args)
-        request(:delete, *args)
+        request(:delete, *args).body
       end
     end
   end

data/lib/redd/client/unauthenticated/moderation.rb

@@ -7,11 +7,11 @@ module Redd
         #   query.
         # @return [String] The url for the subreddit's css stylesheet.
         def stylesheet_url(subreddit = nil)
-          name = extract_attribute(subreddit, :display_name)
+          name = extract_attribute(subreddit, :display_name) if subreddit
           path = "/stylesheet"
           path = path.prepend("/r/#{name}") if subreddit
 
-          get(path).headers[:location]
+					request(:get, path).headers[:location]
         end
 
         # @param subreddit [Redd::Object::Subreddit, String] The subreddit to
@@ -23,4 +23,4 @@ module Redd
       end
     end
   end
-end
+end

data/lib/redd/client/unauthenticated/utilities.rb

@@ -95,12 +95,12 @@ module Redd
         end
 
         def comments_from_response(*args)
-          body = request(*args)[1]
+					body = request(*args).body[1]
           object_from_body(body)
         end
 
         def object_from_response(*args)
-          body = request(*args)
+					body = request(*args).body
           object_from_body(body)
         end
       end

data/lib/redd/response/parse_json.rb

@@ -1,3 +1,5 @@
+require "faraday_middleware"
+
 module Redd
   # The module that contains middleware that alters the Faraday response.
   module Response

data/lib/redd/response/raise_error.rb

@@ -1,3 +1,4 @@
+require "faraday_middleware"
 require "redd/error"
 
 module Redd

data/lib/redd/version.rb

@@ -1,5 +1,5 @@
 # The main Redd module.
 module Redd
   # The semantic version number for Redd.
-  VERSION = "0.6.0"
+  VERSION = "0.6.1"
 end

data/redd.gemspec

@@ -27,6 +27,7 @@ Gem::Specification.new do |s|
   s.add_development_dependency "webmock"
 
   s.add_dependency "faraday", "~> 0.9.0"
+  s.add_dependency "faraday_middleware", "~> 0.9.1"
   s.add_dependency "multi_json", "~> 1.10"
   s.add_dependency "memoizable"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: redd
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.6.1
 platform: ruby
 authors:
 - Avinash Dwarapu
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-08-29 00:00:00.000000000 Z
+date: 2014-09-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -122,6 +122,20 @@ dependencies:
     - - ~>
       - !ruby/object:Gem::Version
         version: 0.9.0
+- !ruby/object:Gem::Dependency
+  name: faraday_middleware
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.9.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.9.1
 - !ruby/object:Gem::Dependency
   name: multi_json
   requirement: !ruby/object:Gem::Requirement