spinels-redd 0.9.0

data/docs/tutorials/creating-bots-with-redd.md

@@ -0,0 +1,101 @@
+---
+title: Creating Bots with Redd
+path: /tutorials/creating-bots-with-redd
+---
+
+## Step 1: Creating an Application
+
+Every bot needs to be registered on reddit. Some API wrappers let you skip this, but chances are, you will be heavily rate limited. Start by visiting your [**applications**](https://www.reddit.com/prefs/apps#developed-apps) and skipping to the "**developed apps**" section and clicking the button to create an app. Give it a name and a description and select the **script** app type. If you want to create a web application, [**follow this guide**](/tutorials/creating-webapps-with-redd). The text input labeled "redirect uri" is mandatory but you can just put any url in there because it doesn't really matter.
+
+## Step 2: Creating a Bot Account (optional)
+
+If you want your bot to interact with other users on the site (like submitting posts or replying to comments), you'll need to create a bot account. Log out and click the "Log in or sign up" link at the top right. Pick a nice bot name and a secure password (a valid email is encouraged in case you forget the password).
+
+**This step is important!** Go to the application [you just created](https://www.reddit.com/prefs/apps#developed-apps) and add the bot's username as a developer for the app.
+
+## Step 3: Installing Redd
+
+Go ahead and [install Ruby](https://www.ruby-lang.org/en/downloads/) if you haven't already. Most package managers have a pretty recent version of Ruby up. The latest version at the time of writing is `2.4.1`. Redd supports Ruby versions `2.1.0` and up, but it's recommended to get the latest version, since I'll probably stop supporting older versions as time passes.
+
+While you can just run `gem install redd` and call it a day, we're going to use [Bundler](https://bundler.io) like the responsible Rubyist we are.
+
+1. Let's make sure bundler is installed:
+
+        $ gem install bundler
+
+2. Then, create a folder for your bot's code to live in:
+
+        $ mkdir myfancybot
+        $ cd myfancybot
+
+3. Create a `Gemfile`listing all the gems our bot is going to use. It should look something like this:
+
+    ```ruby
+    source 'https://rubygems.org'
+    gem 'redd', '~> 0.8'
+    ```
+
+4. Okay, now we just need to download all the gems and then we're ready to get coding!
+
+        $ bundle install
+
+## Step 4: Test Drive
+
+Let's create the file our bot is going to run from. I'm going to call it `app.rb`, but feel free to use your imagination. Let's put the following in it to start off:
+
+```ruby
+require 'bundler/setup'
+require 'redd'
+```
+Redd has a pretty convenient method to get us up and running with the API as quickly as possible called [`Redd.it`](http://www.rubydoc.info/github/avinashbot/redd/master/Redd#it-class_method). I'm going to use that to plug in all my application details. Add the following to your bot's file, replacing the text in angled brackets with your app's details. If you don't need an account for your bot, just skip the `username` and `password` fields.
+
+```ruby
+reddit = Redd.it(
+  user_agent: 'Redd:MyFancyBot:v1.2.3',
+  client_id:  '[the code under the title of your app]',
+  secret:     '[the apps secret]',
+  username:   '[your bot account username]',
+  password:   '[your bot account password]'
+)
+```
+
+For more info on the user_agent, take a look at reddit's [API rules](https://github.com/reddit/reddit/wiki/API).
+
+Now if everything went as planned, `reddit` should be a valid reddit session. The [**Session documentation**](http://www.rubydoc.info/github/avinashbot/redd/master/Redd/Models/Session) lists all the things you can do from here. But for now, let's just print out the title of the post on top of /r/all right now by adding the following to your code:
+
+```ruby
+r_all = reddit.subreddit('all')
+post = r_all.hot.first
+puts post.title
+```
+
+**We're all done!** Let's run this baby!
+
+    $ ruby app.rb
+
+## Step 6: Making your Dream Bot
+
+The [**documentation**](http://www.rubydoc.info/github/avinashbot/redd/master/Redd/Models/Session) is a great starting point for things you can do with Redd. If you need help with Ruby, /r/learnruby is a great place to visit. If you need help with the Reddit API, /r/redditdev is also very helpful, along with [reddit's API documentation](https://reddit.com/dev/api).
+
+**Remember to respect the the [bottiquette](https://www.reddit.com/wiki/bottiquette)!** P.S. /r/Bottiquette keeps a [list of subreddits where bots aren't allowed](https://www.reddit.com/r/Bottiquette/wiki/robots_txt), while [/r/botsrights does the opposite](https://www.reddit.com/r/botsrights/wiki/listofbotfriendlysubs).
+
+## Step 7: Making it Legendary
+
+While it convenient that you can run the bot straight from your home, running a bot 24/7 from your overheating laptop isn't exactly the best long term solution, ya dig? There are three solutions to this dilemma:
+
+1. Abuse free pricing tiers:
+    - [**Heroku**](https://www.heroku.com/free) offers up to 1000 dyno hours per account per month.
+    - [**AWS**](https://aws.amazon.com/free/) has a free tier, offering 750 hours a month for a year.
+    - [**Google Cloud Platform**](https://cloud.google.com/free/docs/always-free-usage-limits) has an always free tier, offering 28 instance hours a day.
+
+2. Five bucks a month:  
+Both [DigitalOcean](https://www.digitalocean.com/pricing) and [Linode](https://www.linode.com/pricing) offer cloud computing for $5 a month.
+
+3. One-time payment:  
+Buy a [Raspberry Pi](https://www.raspberrypi.org/products/) or a [CHIP](https://getchip.com/) to run from your home.
+
+---
+
+I hope that got you started making your first reddit bot! If you need help, don't hesitate to [**submit a self post**](https://www.reddit.com/r/Redd/submit?selftext=true) or [**PM me**](https://www.reddit.com/message/compose/?to=Mustermind).
+
+If you're uploading your Ruby bot to GitHub, post a link to the bot's code to the subreddit!

data/docs/tutorials/creating-webapps-with-redd.md

@@ -0,0 +1,124 @@
+---
+title: Creating Webapps with Redd
+path: /tutorials/creating-webapps-with-redd
+---
+Redd can also help with simplifying web apps that need to use the reddit API thanks to OAuth2. This guide assumes you are somewhat familiar with web development on Ruby and skips some of the basic steps (you can always ask if you need help). The full code from this example can be found [**here**](https://gist.github.com/avinashbot/f298efca5622d77e4ba65abc57c253e4).
+
+## A quick primer on OAuth2
+
+1. A user goes to our fancy website.
+2. Then, they see a cool orangered button labeled "login with reddit" and click it.
+3. Our website then **redirects them to reddit**, which asks the user if they are sure want to login through reddit.
+4. If they change their mind and press "Decline", **reddit redirects the user back to our site** saying that they denied giving us access.
+5. If they press "Allow", **reddit redirects the user back to our site with a code**.
+6. We can now **make a request to reddit with the code to get an access token** (and maybe a refresh token too).
+7. Tada! Now that we have an access token, we can make API requests to reddit.
+8. Once the access token has **expired**, we ask reddit to give us a new one using our refresh token.
+
+## Step 1: Creating an Application
+
+Start by visiting your [**applications**](https://www.reddit.com/prefs/apps#developed-apps) and skipping to the "**developed apps**" section and clicking the button to create an app. Give it a name and a description. Make it friendly, because the user is going to see them! You are also given a choice between three app types (two of which are relevant to us).
+
+- **web app**: if you're running the application from a trusted server
+- **installed app**: if you're running the application on the user's device
+
+The "*redirect uri*" is the URL that the user gets redirected to once they've either allowed or denied access to reddit.
+
+## Step 2: Break out the Rails (or Sinatra)
+
+Let's start with a simple Sinatra app.
+
+```ruby
+require 'bundler/setup'
+require 'sinatra'
+require 'redd/middleware'
+
+enable :sessions
+
+get '/' do
+  '<a href="/login">login with reddit</a>'
+end
+```
+
+Sweet. That login link will 404, but we're going to fix that in next step.
+
+## Step 3: The Secret Weapon
+
+Redd (from `v0.8.6` onwards) sports a new [Rack Middleware](http://www.rubydoc.info/github/avinashbot/redd/master/Redd/Middleware) that makes integrating Redd with traditional web-apps much easier. In your preferred framework (guides for [Rails](http://guides.rubyonrails.org/rails_on_rack.html#adding-a-middleware), [Sinatra](http://www.sinatrarb.com/intro.html#Rack%20Middleware), [Rackup](https://github.com/rack/rack/wiki/%28tutorial%29-rackup-howto)), add the Redd::Middleware, providing it options similar to the following:
+
+```ruby
+use Redd::Middleware,
+    user_agent:   'Redd:Your App:v1.0.0 (by /u/<your username>)',
+    client_id:    '<your client id>',
+    secret:       '<your app secret>',
+    redirect_uri: '<your redirect uri>',
+    scope:        %w(identity),
+    via:          '/login'
+```
+
+Before continuing, **make sure that sessions are enabled**.
+
+- Rails: has it in by default. No work needed on your end.
+- Sinatra: Add `enable :sessions` **before** adding the `Redd::Middleware`.
+- Rackup: Add `use Rack::Session::Cookie` **before** adding the `Redd::Middleware`.
+
+Modify as needed. The `via` option specifies the path that takes the user to the authorization page (`/auth/reddit` by default). We'll use `/login` since that's we used in the previous step.
+
+## Step 4: All Logged In (Maybe)
+
+When the user comes back to our site, they are sent to the redirect uri that we gave reddit. So let's define a route so that our user isn't met with a 404 when they authorize us. Assuming our redirect uri is something like `https://<your website>/redirect`, the code should look like this:
+
+```ruby
+get '/redirect' do
+  redirect to('/profile')
+end
+```
+
+But what if the user clicked deny? Or what if the user got sent to us because of a [CSRF attack](https://www.owasp.org/index.php/Cross-Site_Request_Forgery_%28CSRF%29)? Redd detects that and puts an exception in the 'redd.error' rack environment variable. If you already have a mechanism in place to deal with exceptions, you can just raise the error.
+
+```ruby
+get '/redirect' do
+  redirect to('/profile') if request.env['redd.error'].nil?
+  
+  if request.env['redd.error'].message == 'access_denied'
+    'Sorry, you clicked decline. <a href="/login">Login again?</a>'
+  elsif request.env['redd.error'].message == 'invalid_state'
+    'Did you login through our website? <a href="/login">(No)</a>'
+  else
+    puts "Error while logging in!"
+    raise request.env['redd.error'] # Raise a 500 and make a mental note to look at the logs later
+  end
+end
+```
+
+Much better.
+
+## Step 5: Using the API
+
+```ruby
+get '/profile' do
+  "Hi, #{request.env['redd.session'].me.name}! <a href='/logout'>Log out</a>"
+end
+```
+
+Well, that was easy! `redd.session` is a [**Session**](http://www.rubydoc.info/github/avinashbot/redd/master/Redd/Models/Session) model, which is basically a starting point for all the API calls that Redd offers.
+
+## Step 6: Logging out
+
+```ruby
+get '/logout' do
+  request.env['redd.session'] = nil
+  redirect to('/')
+end
+```
+
+Well, there isn't anything I need to explain, is there?
+
+---
+
+I know you're just excited to build your awesome website, but before you leave, a few tips:
+
+- Here's the [**documentation**](http://www.rubydoc.info/github/avinashbot/redd/master/Redd/Models/Session), and feel free to [**shoot me a message**](https://www.reddit.com/message/compose/?to=Mustermind) if you need help.
+- Rate limits still apply (although they're per user). If you're going to be making many API requests per page request, you might want to look into caching.
+- There are restrictions on commercial use of the API. [**Here's the rules on that**](https://www.reddit.com/wiki/api).
+- I love hearing about the crazy ways you people make use of my gem! Feel free to post in this subreddit if you have an application that relies on Redd.

data/docs/tutorials/make-a-grammar-bot.md

@@ -0,0 +1,5 @@
+---
+title: Make a Grammar Bot
+---
+
+TODO: add more content

data/docs/tutorials.md

@@ -0,0 +1,7 @@
+---
+title: Tutorials
+---
+
+- [Creating Bots with Redd](/tutorials/creating-bots-with-redd)
+- [Creating Webapps with Redd](/tutorials/creating-webapps-with-redd)
+- [Make a Grammar Bot (_in progress_)](/tutorials/make-a-grammar-bot)

data/lib/redd/api_client.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+require_relative 'client'
+require_relative 'utilities/error_handler'
+require_relative 'utilities/rate_limiter'
+require_relative 'utilities/unmarshaller'
+
+module Redd
+  # The class for API clients.
+  class APIClient < Client
+    # The endpoint to make API requests to.
+    API_ENDPOINT = 'https://oauth.reddit.com'
+
+    # @return [APIClient] the access the client uses
+    attr_accessor :access
+
+    # Create a new API client with an auth strategy.
+    # TODO: Give user option to pass through all retryable errors.
+    # @param auth [AuthStrategies::AuthStrategy] the auth strategy to use
+    # @param endpoint [String] the API endpoint
+    # @param user_agent [String] the user agent to send
+    # @param limit_time [Integer] the minimum number of seconds between each request
+    # @param max_retries [Integer] number of times to retry requests that may succeed if retried
+    # @param auto_refresh [Boolean] automatically refresh access token if nearing expiration
+    def initialize(auth, endpoint: API_ENDPOINT, user_agent: USER_AGENT, limit_time: 1,
+                   max_retries: 5, auto_refresh: true)
+      super(endpoint: endpoint, user_agent: user_agent)
+
+      @auth          = auth
+      @access        = nil
+      @max_retries   = max_retries
+      @failures      = 0
+      @error_handler = Utilities::ErrorHandler.new
+      @rate_limiter  = Utilities::RateLimiter.new(limit_time)
+      @unmarshaller  = Utilities::Unmarshaller.new(self)
+      @auto_refresh  = auto_refresh
+    end
+
+    # Authenticate the client using the provided auth.
+    def authenticate(*args)
+      @access = @auth.authenticate(*args)
+    end
+
+    # Refresh the access currently in use.
+    def refresh
+      @access = @auth.refresh(@access)
+    end
+
+    # Revoke the current access and remove it from the client.
+    def revoke
+      @auth.revoke(@access)
+      @access = nil
+    end
+
+    def unmarshal(object)
+      @unmarshaller.unmarshal(object)
+    end
+
+    def model(verb, path, options = {})
+      unmarshal(send(verb, path, options).body)
+    end
+
+    # Makes a request, ensuring not to break the rate limit by sleeping.
+    # @see Client#request
+    def request(verb, path, raw: false, params: {}, **options)
+      # Make sure @access is populated by a valid access
+      ensure_access_is_valid
+      # Setup base API params and make request
+      api_params = { api_type: 'json', raw_json: 1 }.merge(params)
+
+      # This loop is retried @max_retries number of times until it succeeds
+      handle_retryable_errors do
+        response = @rate_limiter.after_limit { super(verb, path, params: api_params, **options) }
+        # Raise errors if encountered at the API level.
+        response_error = @error_handler.check_error(response, raw: raw)
+        raise response_error unless response_error.nil?
+
+        # All done, return the response
+        response
+      end
+    end
+
+    private
+
+    # Makes sure a valid access is present, raising an error if nil
+    def ensure_access_is_valid
+      # If access is nil, panic
+      raise 'client access is nil, try calling #authenticate' if @access.nil?
+
+      # Refresh access if auto_refresh is enabled
+      refresh if @access.expired? && @auto_refresh && @auth && @auth.refreshable?(@access)
+    end
+
+    def handle_retryable_errors # rubocop:disable Metrics/MethodLength
+      response = yield
+    rescue Errors::ServerError, HTTP::TimeoutError => e
+      # FIXME: maybe only retry GET requests, for obvious reasons?
+      @failures += 1
+      raise e if @failures > @max_retries
+
+      warn "Redd got a #{e.class.name} error (#{e.message}), retrying..."
+      retry
+    rescue Errors::RateLimitError => e
+      warn "Redd was rate limited for #{e.duration} seconds, waiting..."
+      sleep e.duration
+      retry
+    else
+      @failures = 0
+      response
+    end
+
+    def connection
+      super.auth("Bearer #{@access.access_token}")
+    end
+  end
+end

data/lib/redd/assist/delete_badly_scoring.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Redd
+  module Assist
+    # Helper class for deleting negative links or comments. You can run this as a separate process,
+    # as long as you set your rate limit time higher in your main process.
+    # @note Works with {Submission} and {Comment}.
+    # @example
+    #   assist = Redd::Assist::DeleteBadlyScoring.new(session.client)
+    #   assist.track(comment)
+    #   loop do
+    #     assist.delete_badly_scoring(under_score: 1, minimum_age: 600)
+    #     sleep 30
+    #   end
+    class DeleteBadlyScoring
+      # Create a DeleteBadlyScoring assist.
+      # @param client [APIClient] the API client
+      def initialize(client)
+        @client = client
+        @queue = []
+      end
+
+      # Add this model's id to the list of items that are tracked.
+      def track(model)
+        @queue << model.name
+      end
+
+      # Delete all items that are older than the minimum age and score 0 or below.
+      # @param under_score [Integer] the maximum score that the comment must have to be kept
+      # @param minimum_age [Integer] the minimum age for deletion (seconds)
+      # @return [Array<String>] the deleted item fullnames
+      def delete_badly_scoring!(under_score: 1, minimum_age: 15 * 60)
+        delete_if do |comment|
+          if comment.created_at + minimum_age > Time.now
+            :skip
+          elsif comment.score < under_score && !comment.deleted? && !comment.archived?
+            :delete
+          else
+            :keep
+          end
+        end
+      end
+
+      # Delete all items that the block returns true for.
+      # @param minimum_age [Integer] the minimum age for deletion
+      # @yieldparam comment [Comment] the comment to filter
+      # @yieldreturn [:keep, :delete, :skip] whether to keep, delete, or check again later
+      # @return [Array<String>] the deleted item fullnames
+      def delete_if # rubocop:disable Metrics/MethodLength
+        deleted = []
+        @queue.delete_if do |fullname|
+          comment = Models::Comment.new(@client, name: fullname).reload
+          action = yield comment
+          if action == :delete
+            comment.delete
+            deleted << fullname
+          end
+          %i[keep delete].include?(action)
+        end
+        deleted
+      end
+    end
+  end
+end

data/lib/redd/auth_strategies/auth_strategy.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require_relative '../client'
+
+module Redd
+  module AuthStrategies
+    # The API client for authentication to reddit.
+    class AuthStrategy < Client
+      # The API to make authentication requests to.
+      AUTH_ENDPOINT = 'https://www.reddit.com'
+
+      # @param client_id [String] the client id of the reddit app
+      # @param secret [String] the app's secret string
+      # @param endpoint [String] the url to contact for authentication requests
+      # @param user_agent [String] the user agent to send with requests
+      def initialize(client_id:, secret:, endpoint: AUTH_ENDPOINT, user_agent: USER_AGENT)
+        super(endpoint: endpoint, user_agent: user_agent)
+        @client_id = client_id
+        @secret = secret
+      end
+
+      # @abstract Perform authentication and return the resulting access object
+      # @return [Access] the access token object
+      def authenticate(*)
+        raise 'abstract method: this strategy cannot authenticate with reddit'
+      end
+
+      # @return [Boolean] whether the access object can be refreshed
+      def refreshable?(_access)
+        false
+      end
+
+      # @abstract Refresh the authentication and return the refreshed access
+      # @param _access [Access, String] the access to refresh
+      # @return [Access] the new access
+      def refresh(_access)
+        raise 'abstract method: this strategy cannot refresh access'
+      end
+
+      # Revoke the access token, making it invalid for future requests.
+      # @param access [Access, String] the access to revoke
+      def revoke(access)
+        token =
+          if access.is_a?(String)
+            access
+          elsif access.respond_to?(:refresh_token)
+            access.refresh_token
+          else
+            access.access_token
+          end
+        post('/api/v1/revoke_token', token: token)
+      end
+
+      private
+
+      def connection
+        @connection ||= super.basic_auth(user: @client_id, pass: @secret)
+      end
+
+      def request_access(grant_type, options = {})
+        response = post('/api/v1/access_token', { grant_type: grant_type }.merge(options))
+        raise Errors::AuthenticationError.new(response) if response.body.key?(:error)
+
+        Models::Access.new(response.body)
+      end
+    end
+  end
+end

data/lib/redd/auth_strategies/script.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require_relative 'auth_strategy'
+
+module Redd
+  module AuthStrategies
+    # A password-based authentication scheme. Requests all scopes.
+    class Script < AuthStrategy
+      def initialize(client_id:, secret:, username:, password:)
+        super(client_id: client_id, secret: secret)
+        @username = username
+        @password = password
+      end
+
+      # Perform authentication and return the resulting access object
+      # @return [Access] the access token object
+      def authenticate
+        request_access('password', username: @username, password: @password)
+      end
+
+      # Since the access isn't used for refreshing, the strategy is inherently
+      # refreshable.
+      # @return [true]
+      def refreshable?(_access)
+        true
+      end
+
+      # Refresh the authentication and return the refreshed access
+      # @return [Access] the new access
+      def refresh(_)
+        authenticate
+      end
+    end
+  end
+end

data/lib/redd/auth_strategies/userless.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require_relative 'auth_strategy'
+
+module Redd
+  module AuthStrategies
+    # A userless authentication scheme.
+    class Userless < AuthStrategy
+      # Perform authentication and return the resulting access object
+      # @return [Access] the access token object
+      def authenticate
+        request_access('client_credentials')
+      end
+
+      # Since the access isn't used for refreshing, the strategy is inherently
+      # refreshable.
+      # @return [true]
+      def refreshable?(_access)
+        true
+      end
+
+      # Refresh the authentication and return the refreshed access
+      # @return [Access] the new access
+      def refresh(_)
+        authenticate
+      end
+    end
+  end
+end

data/lib/redd/auth_strategies/web.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require_relative 'auth_strategy'
+
+module Redd
+  module AuthStrategies
+    # A typical code-based authentication, for 'web' and 'installed' types.
+    class Web < AuthStrategy
+      def initialize(client_id:, redirect_uri:, secret: '', **kwargs)
+        super(client_id: client_id, secret: secret, **kwargs)
+        @redirect_uri = redirect_uri
+      end
+
+      # Authenticate with a code using the "web" flow.
+      # @param code [String] the code returned by reddit
+      # @return [Access]
+      def authenticate(code)
+        request_access('authorization_code', code: code, redirect_uri: @redirect_uri)
+      end
+
+      # @return [Boolean] whether the access has a refresh token
+      def refreshable?(access)
+        access.permanent?
+      end
+
+      # Refresh the authentication and return a new refreshed access
+      # @return [Access] the new access
+      def refresh(access)
+        token = access.is_a?(String) ? access : access.refresh_token
+        response = post('/api/v1/access_token', grant_type: 'refresh_token', refresh_token: token)
+        # When refreshed, the response doesn't include an access token, so we have to add it.
+        Models::Access.new(response.body.merge(refresh_token: token))
+      end
+    end
+  end
+end