neonredd 0.0.1

data/lib/redd/clients/base.rb

@@ -0,0 +1,181 @@
+require 'faraday'
+require_relative '../version'
+require_relative '../response/raise_error'
+require_relative '../response/parse_json'
+require_relative '../rate_limit'
+require_relative '../access'
+
+module Redd
+  # The module containing the multiple types of clients.
+  module Clients
+    # The basic client to inherit from. Don't use this directly, prefer
+    # {Redd.it}
+    class Base
+      # @!parse include Utilities
+      # @!parse include Account
+      # @!parse include Identity
+      # @!parse include None
+      # @!parse include Privatemessages
+      # @!parse include Read
+      # @!parse include Submit
+      # @!parse include Stream
+      # @!parse include Wikiread
+      %w(
+        utilities account identity none privatemessages read submit stream
+        wikiread
+      ).each do |mixin_name|
+        require_relative "base/#{mixin_name}"
+        camel_case = mixin_name.split('_').map(&:capitalize).join
+        include const_get(camel_case)
+      end
+
+      # @!attribute [r] user_agent
+      # @return [String] The user-agent used to communicate with reddit.
+      attr_reader :user_agent
+
+      # @!attribute [r] rate_limit
+      # @return [#after_limit] The handler that takes care of rate limiting.
+      attr_reader :rate_limit
+
+      # @!attribute [r] auth_endpoint
+      # @return [String] The site to connect to for authentication.
+      attr_reader :auth_endpoint
+
+      # @!attribute [r] api_endpoint
+      # @return [String] The site to make API requests with.
+      attr_reader :api_endpoint
+
+      # @!attribute [rw] access
+      # @return [Access] The access object to make API requests with.
+      attr_accessor :access
+
+      # Create a Client.
+      #
+      # @param [Hash] options The options to create the client with.
+      # @option options [String] :user_agent The User-Agent string to use in
+      #   the header of every request.
+      # @option options [#after_limit] :rate_limit The handler that takes care
+      #   of rate limiting.
+      # @option options [String] :auth_endpoint The main domain to authenticate
+      #   with.
+      # @option options [String] :api_endpoint The main domain to make requests
+      #   with.
+      # @note HTTPS is mandatory for OAuth2.
+      def initialize(**options)
+        @user_agent = options[:user_agent] || "Redd/Ruby, v#{Redd::VERSION}"
+        @rate_limit = options[:rate_limit] || RateLimit.new(1)
+        @auth_endpoint = options[:auth_endpoint] || 'https://www.reddit.com/'
+        @api_endpoint = options[:api_endpoint] || 'https://oauth.reddit.com/'
+        @access = Access.new(expires_at: Time.at(0))
+      end
+
+      # @!method get(path, params = {})
+      # @!method post(path, params = {})
+      # @!method put(path, params = {})
+      # @!method patch(path, params = {})
+      # @!method delete(path, params = {})
+      #
+      # Sends the request to the given path with the given params and return
+      # the body of the response.
+      # @param [String] path The path under the api_endpoint to request.
+      # @param [Hash] params The parameters to send with the request.
+      # @return [Faraday::Response] The response.
+      [:get, :post, :put, :patch, :delete].each do |meth|
+        define_method(meth) do |path, params = {}|
+          @rate_limit.after_limit do
+            final_params = default_params.merge(params)
+            connection.send(meth, path, final_params)
+          end
+        end
+      end
+
+      # @param [Access] new_access The access to use.
+      # @yield The client with the given access.
+      def with(new_access)
+        old_access = @access
+        @access = new_access
+        response = yield(self)
+        @access = old_access
+        response
+      end
+
+      # Obtain a new access token using a refresh token.
+      # @return [Access] The refreshed information.
+      def refresh_access!
+        response = auth_connection.post(
+          '/api/v1/access_token',
+          grant_type: 'refresh_token',
+          refresh_token: access.refresh_token
+        )
+        access.refreshed!(response.body)
+      end
+
+      # Dispose of an access or refresh token when you're done with it.
+      # @param [Boolean] remove_refresh_token Whether or not to remove all
+      #   tokens associated with the user.
+      def revoke_access!(remove_refresh_token = false)
+        token_type = remove_refresh_token ? :refresh_token : :access_token
+        token = access.send(token_type)
+        @access = nil
+        auth_connection.post(
+          '/api/v1/revoke_token',
+          token: token,
+          token_type_hint: token_type
+        )
+      end
+
+      private
+
+      # @return [Faraday::RackBuilder] The middleware to use when creating the
+      #   connection.
+      def middleware
+        @middleware ||= Faraday::RackBuilder.new do |builder|
+          builder.use Response::RaiseError
+          builder.use Response::ParseJson
+          builder.use Faraday::Request::Multipart
+          builder.use Faraday::Request::UrlEncoded
+          builder.adapter Faraday.default_adapter
+        end
+      end
+
+      # @return [Hash] The minimum parameters to send with every request.
+      def default_params
+        @default_params ||= { api_type: 'json' }
+      end
+
+      # @return [Hash] A hash of the headers used.
+      def default_headers
+        {
+          'User-Agent' => @user_agent,
+          'Authorization' => "bearer #{@access.access_token}"
+        }
+      end
+
+      # @return [Faraday::Connection] A new or existing connection.
+      def connection
+        @connection ||= Faraday.new(
+          @api_endpoint,
+          headers: default_headers,
+          builder: middleware
+        )
+      end
+
+      # @return [Hash] A hash of the headers with basic auth.
+      def auth_headers
+        {
+          'User-Agent' => @user_agent,
+          'Authorization' => Faraday.basic_auth(@client_id, @secret)
+        }
+      end
+
+      # @return [Faraday::Connection] A new or existing connection.
+      def auth_connection
+        @auth_connection ||= Faraday.new(
+          @auth_endpoint,
+          headers: auth_headers,
+          builder: middleware
+        )
+      end
+    end
+  end
+end

data/lib/redd/clients/installed.rb

@@ -0,0 +1,56 @@
+require 'cgi'
+require_relative 'base'
+
+module Redd
+  module Clients
+    # The client for installed apps that can't keep a secret.
+    # It might even work with Rubymotion (fingers crossed).
+    class Installed < Base
+      # @!attribute [r] client_id
+      attr_reader :client_id
+
+      # @!attribute [r] redirect_uri
+      attr_reader :redirect_uri
+
+      # @param [Hash] options The options to create the client with.
+      # @see Base#initialize
+      # @see Redd.it
+      def initialize(client_id, redirect_uri, **options)
+        @client_id = client_id
+        @redirect_uri = redirect_uri
+        super(**options)
+      end
+
+      # @param [String] state A random string to double-check later.
+      # @param [Array<String>] scope The scope to request access to.
+      # @param [:temporary, :permanent] duration
+      # @return [String] The url to redirect the user to.
+      # rubocop:disable Metrics/MethodLength
+      def auth_url(state, scope = ['identity'], duration = :temporary)
+        query = {
+          response_type: 'token',
+          client_id: @client_id,
+          redirect_uri: @redirect_uri,
+          state: state,
+          scope: scope.join(','),
+          duration: duration
+        }
+        url = URI.join(auth_endpoint, '/api/v1/authorize')
+        url.query = URI.encode_www_form(query)
+        url.to_s
+      end
+
+      # Authorize using the url fragment.
+      # @param [String] fragment The part of the url after the "#".
+      # @return [Access] The access given by reddit.
+      def authorize!(fragment)
+        parsed = CGI.parse(fragment)
+        @access = Access.new(
+          access_token: parsed[:access_token].first,
+          expires_in: parsed[:expires_in].first,
+          scope: parsed[:scope]
+        )
+      end
+    end
+  end
+end

data/lib/redd/clients/script.rb

@@ -0,0 +1,40 @@
+require_relative 'base'
+
+module Redd
+  module Clients
+    # The client for an account you own (e.g. bots).
+    class Script < Base
+      # @!attribute [r] client_id
+      attr_reader :client_id
+
+      # @!attribute [r] username
+      attr_reader :username
+
+      # @param [Hash] options The options to create the client with.
+      # @see Base#initialize
+      # @see Redd.it
+      def initialize(client_id, secret, username, password, **options)
+        @client_id = client_id
+        @secret = secret
+        @username = username
+        @password = password
+        super(**options)
+      end
+
+      # Authorize using the given data.
+      # @return [Access] The access given by reddit.
+      def authorize!
+        response = auth_connection.post(
+          '/api/v1/access_token',
+          grant_type: 'password',
+          username: @username,
+          password: @password
+        )
+
+        @access = Access.new(response.body)
+      end
+
+      alias refresh_access! authorize!
+    end
+  end
+end

data/lib/redd/clients/userless.rb

@@ -0,0 +1,32 @@
+require_relative 'base'
+
+module Redd
+  module Clients
+    # The client that doesn't need a user to function.
+    # @note Of course, that means many editing methods throw an error.
+    class Userless < Base
+      # @!attribute [r] client_id
+      attr_reader :client_id
+
+      # @param [Hash] options The options to create the client with.
+      # @see Base#initialize
+      # @see Redd.it
+      def initialize(client_id, secret, **options)
+        @client_id = client_id
+        @secret = secret
+        super(**options)
+      end
+
+      # Authorize using the given data.
+      # @return [Access] The access given by reddit.
+      def authorize!
+        response = auth_connection.post(
+          '/api/v1/access_token',
+          grant_type: 'client_credentials'
+        )
+
+        @access = Access.new(response.body)
+      end
+    end
+  end
+end

data/lib/redd/clients/web.rb

@@ -0,0 +1,59 @@
+require 'uri'
+require_relative 'base'
+
+module Redd
+  module Clients
+    # The client for a web-based flow (e.g. "login with reddit")
+    class Web < Base
+      # @!attribute [r] client_id
+      attr_reader :client_id
+
+      # @!attribute [r] redirect_uri
+      attr_reader :redirect_uri
+
+      # @param [Hash] options The options to create the client with.
+      # @see Base#initialize
+      # @see Redd.it
+      def initialize(client_id, secret, redirect_uri, **options)
+        @client_id = client_id
+        @secret = secret
+        @redirect_uri = redirect_uri
+        super(**options)
+      end
+
+      # @param [String] state A random string to double-check later.
+      # @param [Array<String>] scope The scope to request access to.
+      # @param [:temporary, :permanent] duration
+      # @return [String] The url to redirect the user to.
+      # rubocop:disable Metrics/MethodLength
+      def auth_url(state, scope = ['identity'], duration = :temporary)
+        query = {
+          response_type: 'code',
+          client_id: @client_id,
+          redirect_uri: @redirect_uri,
+          state: state,
+          scope: scope.join(','),
+          duration: duration
+        }
+
+        url = URI.join(auth_endpoint, '/api/v1/authorize')
+        url.query = URI.encode_www_form(query)
+        url.to_s
+      end
+
+      # Authorize using the code given.
+      # @param [String] code The code from the get params.
+      # @return [Access] The access given by reddit.
+      def authorize!(code)
+        response = auth_connection.post(
+          '/api/v1/access_token',
+          grant_type: 'authorization_code',
+          code: code,
+          redirect_uri: @redirect_uri
+        )
+
+        @access = Access.new(response.body)
+      end
+    end
+  end
+end

data/lib/redd/error.rb

@@ -0,0 +1,151 @@
+module Redd
+  # An error from reddit
+  # TODO: Move Error to an Errors module in next minor version?
+  class Error < StandardError
+    attr_reader :code
+    attr_reader :headers
+    attr_reader :body
+
+    def initialize(env)
+      @code = env[:status]
+      @headers = env[:response_headers]
+      @body = env[:body]
+    end
+
+    def self.from_response(env) # rubocop:disable all
+      status = env[:status]
+      body = parse_error(env[:body]).to_s
+      case status
+      when 200
+        case body
+        when /access_denied/i             then OAuth2AccessDenied
+        when /unsupported_response_type/i then InvalidResponseType
+        when /unsupported_grant_type/i    then InvalidGrantType
+        when /invalid_scope/i             then InvalidScope
+        when /invalid_request/i           then InvalidRequest
+        when /no_text/i                   then NoTokenGiven
+        when /invalid_grant/i             then ExpiredCode
+        when /wrong_password/i            then InvalidCredentials
+        when /bad_captcha/i               then InvalidCaptcha
+        when /ratelimit/i                 then RateLimited
+        when /quota_filled/i              then QuotaFilled
+        when /bad_css_name/i              then InvalidClassName
+        when /too_old/i                   then Archived
+        when /too_much_flair_css/i        then TooManyClassNames
+        when /user_required/i             then AuthenticationRequired
+        end
+      when 400 then BadRequest
+      when 401 then InvalidOAuth2Credentials
+      when 403
+        if /user_required/i =~ body
+          AuthenticationRequired
+        else
+          PermissionDenied
+        end
+      when 404 then NotFound
+      when 409 then Conflict
+      when 500 then InternalServerError
+      when 502 then BadGateway
+      when 503 then ServiceUnavailable
+      when 504 then TimedOut
+      end
+    end
+
+    def self.parse_error(body) # rubocop:disable all
+      return body unless body.is_a?(Hash)
+
+      if body.key?(:json) && body[:json].key?(:errors)
+        body[:json][:errors].first
+      elsif body.key?(:jquery)
+        body[:jquery]
+      elsif body.key?(:error)
+        body[:error]
+      elsif body.key?(:code) && body[:code] == 'NO_TEXT'
+        'NO_TEXT'
+      end
+    end
+
+    # This item has been archived and can no longer be edited.
+    Archived = Class.new(Error)
+
+    AuthenticationRequired = Class.new(Error)
+
+    # Bad Gateway. Either a network or a reddit error. Either way, try again.
+    BadGateway = Class.new(Error)
+
+    BadRequest = Class.new(Error)
+
+    Conflict = Class.new(Error)
+
+    # You already received an access token using this code. The user should
+    # grant you access again to get a new code.
+    ExpiredCode = Class.new(Error)
+
+    # There is an issue on reddit's end. Try again.
+    InternalServerError = Class.new(Error)
+
+    InvalidCaptcha = Class.new(Error)
+
+    InvalidClassName = Class.new(Error)
+
+    # Either your username or your password is wrong.
+    InvalidCredentials = Class.new(Error)
+
+    InvalidGrantType = Class.new(Error)
+
+    InvalidMultiredditName = Class.new(Error)
+
+    # Your client id or your secret is wrong.
+    InvalidOAuth2Credentials = Class.new(Error)
+
+    InvalidResponseType = Class.new(Error)
+
+    InvalidRequest = Class.new(Error)
+
+    # You don't have the proper scope to perform this request.
+    InvalidScope = Class.new(Error)
+
+    # Looks like we didn't get a JSON response. Raise this error.
+    JSONError = Class.new(Error)
+
+    # Four, oh four! The thing you're looking for wasn't found.
+    NotFound = Class.new(Error)
+
+    # No access token was given.
+    NoTokenGiven = Class.new(Error)
+
+    OAuth2AccessDenied = Class.new(Error)
+
+    PermissionDenied = Class.new(Error)
+
+    # Raised when the client needs to wait before making another request
+    class RateLimited < Error
+      # @!attribute [r] time
+      # @return [Integer] the seconds to wait before making another request.
+      attr_reader :time
+
+      def initialize(env)
+        super
+        @time = env[:body][:json][:ratelimit] || 3600
+      end
+    end
+
+    # This seems to be a more OAuth2-focused error.
+    class QuotaFilled < RateLimited
+      def initialize(env)
+        super
+        @time = 3600
+      end
+    end
+
+    RequestError = Class.new(Error)
+
+    # Issue on reddit's end. Try again.
+    ServiceUnavailable = Class.new(Error)
+
+    # The connection timed out. Try again.
+    TimedOut = Class.new(Error)
+
+    TooManyClassNames = Class.new(Error)
+  end
+end

data/lib/redd/objects/base.rb

@@ -0,0 +1,39 @@
+require 'hashie'
+require 'forwardable'
+
+module Redd
+  # A bunch of objects that can hold properties.
+  module Objects
+    # A base for all objects to inherit from.
+    class Base < Hashie::Hash
+      include Hashie::Extensions::MergeInitializer
+      include Hashie::Extensions::MethodReader
+      include Hashie::Extensions::MethodQuery
+      include Hashie::Extensions::DeepMerge
+
+      # The `delete` method is called `delete_path` because it conflicts with
+      # Hash#delete.
+      extend Forwardable
+      def_delegators :@client, :get, :post, :put, :delete_path
+
+      # @!attribute [r] client
+      # @return [Clients::Base] The client that used to make requests.
+      attr_reader :client
+
+      # @param [Clients::Base] client The client instance.
+      # @param [Hash] attributes A hash of attributes.
+      def initialize(client, attributes = {})
+        @client = client
+        super(attributes)
+      end
+
+      # Define an alias for a property.
+      # @param [Symbol] new_name The alias.
+      # @param [Symbol] old_name The existing property.
+      def self.alias_property(new_name, old_name)
+        define_method(new_name) { send(old_name) }
+        define_method(:"#{new_name}?") { send(old_name) }
+      end
+    end
+  end
+end

data/lib/redd/objects/comment.rb

@@ -0,0 +1,22 @@
+require_relative 'thing'
+
+module Redd
+  module Objects
+    # A comment that can be made on a link.
+    class Comment < Thing
+      include Thing::Editable
+      include Thing::Inboxable
+      include Thing::Moderatable
+      include Thing::Refreshable
+      include Thing::Saveable
+      include Thing::Votable
+
+      alias_property :reports_count, :num_reports
+
+      # @return [Listing] The comment's replies.
+      def replies
+        @replies ||= (client.object_from_body(self[:replies]) || [])
+      end
+    end
+  end
+end

data/lib/redd/objects/labeled_multi.rb

@@ -0,0 +1,13 @@
+module Redd
+  module Objects
+    # A comment that can be made on a link.
+    class LabeledMulti < Base
+      # @see Objects::Base
+      def initialize(client, attributes = {})
+        attr_dup = attributes.dup
+        attr_dup[:subreddits].map! { |sub| sub[:name] }
+        super(client, attr_dup)
+      end
+    end
+  end
+end

data/lib/redd/objects/listing.rb

@@ -0,0 +1,29 @@
+module Redd
+  module Objects
+    # A collection of reddit things.
+    # @see https://www.reddit.com/dev/api#listings
+    class Listing < Array
+      # @!attribute [r] before
+      # @return [String] The id of the object before the listing.
+      attr_reader :before
+
+      # @!attribute [r] after
+      # @return [String] The id of the object after the listing.
+      attr_reader :after
+
+      # @param [Clients::Base] client The client to expand the comments with.
+      # @param [{:before => String, :after => String,
+      #   :children => Array<Hash>}] attributes The data to initialize the
+      #   class with.
+      # @todo Only call Clients::Base#object_from_body when item is being
+      #   accessed.
+      def initialize(client, attributes)
+        @before = attributes[:before]
+        @after = attributes[:after]
+        attributes[:children].each do |child|
+          self << (client.object_from_body(child) || child)
+        end
+      end
+    end
+  end
+end

data/lib/redd/objects/more_comments.rb

@@ -0,0 +1,10 @@
+module Redd
+  module Objects
+    # The model for a morecomments object
+    class MoreComments < Array
+      def initialize(_, attributes)
+        super(attributes[:children])
+      end
+    end
+  end
+end

data/lib/redd/objects/private_message.rb

@@ -0,0 +1,28 @@
+require_relative 'thing'
+
+module Redd
+  module Objects
+    # The model for private messages
+    class PrivateMessage < Thing
+      include Thing::Inboxable
+
+      alias_property :from, :author
+      alias_property :to, :dest
+
+      # Block the sender of the message from sending any more.
+      def block_sender!
+        post('/api/block', id: fullname)
+      end
+
+      # Mark the message as read.
+      def mark_as_read
+        post('/api/read_message', id: fullname)
+      end
+
+      # Mark the message as unread and add orangered to account.
+      def mark_as_unread
+        post('/api/unread_message', id: fullname)
+      end
+    end
+  end
+end