redd 0.6.5 → 0.7.0

data/Rakefile

@@ -1,6 +1,5 @@
-require "bundler/gem_tasks"
-require "rspec/core/rake_task"
-
-RSpec::Core::RakeTask.new
-
-task default: :spec
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+task default: :spec

data/{RedditKit.LICENSE.md → RedditKit.LICENSE.txt}

@@ -1,13 +1,13 @@
-The error and base files would have been impossible if it weren't for [@samsymons](https://github.com/samsymons) :)
-
----
-
-Copyright (c) 2013 Sam Symons
-
-MIT License
-
-Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
-
-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.
+error.rb would have been impossible if it weren't for @samsymons :)
+
+---
+
+Copyright (c) 2013 Sam Symons
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+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.

data/lib/redd.rb

@@ -1,4 +1,50 @@
-require "redd/client/unauthenticated"
-require "redd/client/authenticated"
-require "redd/client/oauth2"
-require "redd/client/oauth2_script"
+require_relative "redd/version"
+require_relative "redd/clients/installed"
+require_relative "redd/clients/script"
+require_relative "redd/clients/userless"
+require_relative "redd/clients/web"
+
+# The main Redd module.
+module Redd
+  # @overload it(:installed, client_id, redirect_uri, **kwargs)
+  #   Authorize a user via an installed app.
+  #   @param [String] client_id The client ID provided by reddit.
+  #   @param [String] redirect_uri The exact uri you provided to reddit.
+  #   @param [Hash] kwargs The keyword arguments provided to the client.
+  #   @return [Clients::Installed]
+  #
+  # @overload it(:script, client_id, secret, username, password, **kwargs)
+  #   Authorize a user that you have full access to, i.e. a bot.
+  #   @param [String] client_id The client ID provided by reddit.
+  #   @param [String] secret The client secret provided by reddit.
+  #   @param [String] username The username.
+  #   @param [String] password The password of the user.
+  #   @param [Hash] kwargs The keyword arguments provided to the client.
+  #   @return [Clients::Script]
+  #
+  # @overload it(:userless, client_id, secret, **kwargs)
+  #   Connect to reddit from a web-app or a script without a specific user.
+  #   @param [String] client_id The client ID provided by reddit.
+  #   @param [String] secret The client secret provided by reddit.
+  #   @param [Hash] kwargs The keyword arguments provided to the client.
+  #   @return [Clients::Userless]
+  #
+  # @overload it(:web, client_id, secret, redirect_uri, **kwargs)
+  #   Authorize a user from a website.
+  #   @param [String] client_id The client ID provided by reddit.
+  #   @param [String] secret The client secret provided by reddit.
+  #   @param [String] redirect_uri The exact uri you provided to reddit.
+  #   @param [Hash] kwargs The keyword arguments provided to the client.
+  #   @return [Clients::Web]
+  #
+  def self.it(type, *args, **kwargs)
+    types = {
+      installed: Clients::Installed,
+      script: Clients::Script,
+      userless: Clients::Userless,
+      web: Clients::Web
+    }
+
+    @client = types[type].new(*args, **kwargs)
+  end
+end

data/lib/redd/access.rb

@@ -0,0 +1,76 @@
+require "multi_json"
+
+module Redd
+  # A container for the client's access to their account via OAuth2
+  class Access
+    # @!attribute [r] access_token
+    # @return [String] The access token used to access the users account.
+    attr_reader :access_token
+
+    # @!attribute [r] refresh_token
+    # @return [String, nil] The refresh token, if the access was permanent.
+    attr_reader :refresh_token
+
+    # @!attribute [r] scope
+    # @return [Array] The scope that the client is allowed to access.
+    attr_reader :scope
+
+    # @!attribute [r] expires_at
+    # @return [Time] The time when the access token expires.
+    attr_reader :expires_at
+
+    # @param [String] body The response body containing the required info.
+    def initialize(body)
+      @access_token = body[:access_token]
+      @refresh_token = body[:refresh_token]
+      @scope = (body[:scope] ? body[:scope].split(",") : [])
+      @expires_at =
+        if body[:expires_at]
+          Time.at(body[:expires_at])
+        else
+          Time.now + (body[:expires_in] || 0)
+        end
+    end
+
+    # @return [Boolean] Whether the access is temporary.
+    def temporary?
+      !refresh_token
+    end
+
+    # @return [Boolean] Whether the access is permanent.
+    def permanent?
+      !temporary?
+    end
+
+    # @return [Boolean] Whether the access has expired.
+    def expired?
+      Time.now > @expires_at
+    end
+
+    # Refresh the object with the new response body.
+    # This happens when a new access token is requested using a request token.
+    # @param [Hash] body The new response body.
+    def refreshed!(body)
+      @access_token = body[:access_token]
+      @expires_at = Time.now + body[:expires_in]
+    end
+
+    # @return [String] A JSON version of the data that can be loaded later.
+    def to_json
+      MultiJson.dump(
+        access_token: @access_token,
+        refresh_token: @refresh_token,
+        scope: @scope.join(","),
+        expires_at: @expires_at.to_i
+      )
+    end
+
+    # Create a new instance of the class from the JSON returned from #to_json
+    # @param [String] json
+    # @return [Access]
+    def self.from_json(json)
+      hash = MultiJson.load(json, symbolize_keys: true)
+      new(hash)
+    end
+  end
+end

data/lib/redd/clients/base.rb

@@ -0,0 +1,178 @@
+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] access The access to use.
+      # @yield The client with the given access.
+      def with(access)
+        new_instance = dup
+        new_instance.access = access
+        yield new_instance
+      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::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/base/account.rb

@@ -0,0 +1,20 @@
+module Redd
+  module Clients
+    class Base
+      # Methods that require the "account" scope
+      module Account
+        # Edit some user preferences
+        # @param [Hash] changed_prefs The preferences to override.
+        # @return [Objects::Base] A Hashie-style container of the new prefs.
+        # @see https://www.reddit.com/dev/api/oauth#PATCH_api_v1_me_prefs
+        def edit_my_prefs(changed_prefs)
+          response = connection.patch do |req|
+            req.url "/api/v1/me/prefs"
+            req.body = MultiJson.dump(changed_prefs)
+          end
+          Objects::Base.new(self, response.body)
+        end
+      end
+    end
+  end
+end

data/lib/redd/clients/base/identity.rb

@@ -0,0 +1,22 @@
+module Redd
+  module Clients
+    class Base
+      # Methods that require the "identity" scope
+      module Identity
+        # @return [Objects::User] The logged-in user.
+        def me
+          response = get("/api/v1/me")
+          object_from_body(kind: "t2", data: response.body)
+        end
+
+        # @return [Objects::Base] Your current preferences.
+        # @see https://www.reddit.com/dev/api/oauth#GET_api_v1_me_prefs
+        def my_prefs
+          response = get("/api/v1/me/prefs")
+          # Basically an uneditable mashie.
+          Objects::Base.new(self, response.body)
+        end
+      end
+    end
+  end
+end

data/lib/redd/clients/base/none.rb

@@ -0,0 +1,27 @@
+module Redd
+  module Clients
+    class Base
+      # Methods that don't require any scope.
+      module None
+        # @return [Boolean] Whether a captcha is required for some API methods.
+        def needs_captcha?
+          get("/api/needs_captcha.json").body
+        end
+
+        # Create a new captcha identifier.
+        # @return [String] The identifier.
+        # @todo Maybe create some kind of set_captcha!(...) method for the
+        #   client to send automatically with the next response.
+        def new_captcha
+          post("/api/new_captcha").body[:json][:data][:iden]
+        end
+
+        # @param iden [String] The captcha identifier.
+        # @return The url for the captcha image.
+        def captcha_url(iden)
+          "http://www.reddit.com/captcha/#{identifier}.png"
+        end
+      end
+    end
+  end
+end

data/lib/redd/clients/base/privatemessages.rb

@@ -0,0 +1,28 @@
+module Redd
+  module Clients
+    class Base
+      # Methods that require the "privatemessages" scope
+      module Privatemessages
+        # Return a listing of a user's private messages.
+        #
+        # @param category ["inbox", "unread", "sent"] The category of messages
+        #   to view.
+        # @param mark [Boolean] Whether to remove the orangered from the
+        #   user's inbox.
+        # @param params [Hash] A list of params to send with the request.
+        # @option params [String] :after Return results after the given
+        #   fullname.
+        # @option params [String] :before Return results before the given
+        #   fullname.
+        # @option params [Integer] :count (0) The number of items already seen
+        #   in the listing.
+        # @option params [1..100] :limit (25) The maximum number of things to
+        #   return.
+        def my_messages(category = "inbox", mark = false, params = {})
+          params[:mark] = mark
+          request_object(:get, "/message/#{category}.json", params)
+        end
+      end
+    end
+  end
+end