redd 0.8.1 → 0.8.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: a0f001106f53af036bc79b0d02fb744f9f8807ac
-  data.tar.gz: dea813c1bc65c8a42e7b533da29787e2f25d5786
+  metadata.gz: eb84c87afa0fb9151b0be21985da7f69c261df24
+  data.tar.gz: 2969272d1ae4cb25234ed9ff3902f2cdce51114d
 SHA512:
-  metadata.gz: 67c4940373ced4e6513a03168e3e61e56353b5db665e53a5313987f7fd07d86b33f0e93d546428691ee077e9c7731da66a4f9d179858ddaca61b61bfbe6671f5
-  data.tar.gz: 700cbec73a627b874ee3fd254c7cc2d78f8c0455f6c6c17574fa0a5518dd11b2438ff7e36be9e15aa01d2944c4d88bf63bc5a0b9cd811dcc2da775e1d7c00c70
+  metadata.gz: 0ad8183da54e6dbbea67234b2cab3796b2aaf79b7bfd8f1e35dc7a6c3f93c5c92a0f63830c8d8f9d39042bcf02ed99841aea0bd4b225754a992328503464eea9
+  data.tar.gz: 8b7bce2305a66a554d484015e593d212f646aaead6efc894219e32ad14a2e86c4b99198d99fd01f83432938f1cf176c4fb2eaf7f1aae35112c5acf53b857c567

data/README.md

@@ -17,15 +17,22 @@
 
   <!-- Intro Text -->
   <p>
-    <strong>Redd</strong> is an API wrapper
-    for <a href="https://www.reddit.com/dev/api">reddit</a>
-    that is all about being <strong>simple</strong>
-    and <strong>intuitive</strong>.
+    <strong>Redd</strong> is a <strong>batteries-included</strong>
+    API wrapper for <a href="https://www.reddit.com/dev/api">reddit</a>.
   </p>
 </div>
 
 ---
 
+### Features
+
+- Supports most of the reddit API, including live threads and the beta mod-mail.
+- Includes support for streaming new posts and comments.
+- Built-in rate limiting and error handling.
+- Automatic retrying of failed requests.
+
+### Demo
+
 ```ruby
 require 'redd'
 
@@ -46,18 +53,21 @@ session.subreddit('all').comment_stream do |comment|
 end
 ```
 
----
-
 ### FAQ
 
 #### Is that bot fully functional?
-**Yes**, that's all there is to it! You don't need to handle rate-limiting, refresh access tokens
-or protect against issues on reddit's end (like 5xx errors).
+**Yes**, that's all there is to it! You don't need to handle rate-limiting, refresh access tokens or protect against issues on reddit's end (like 5xx errors).
 
 #### Where can I find the documentation?
 
 [**Gem**](http://www.rubydoc.info/gems/redd/Redd/Models/Session) / [**GitHub**](http://www.rubydoc.info/github/avinashbot/redd/master/Redd/Models/Session)
 
+#### How do I request a feature / contribute?
+
+- The quickest way to get a feature into Redd is to raise a GitHub issue.
+- Pull requests are also appreciated!
+- Don't hesitate! There are no stupid questions!
+
 #### How can I contact you?
 [Reddit](https://www.reddit.com/message/compose/?to=Mustermind) /
 [GitHub](https://github.com/avinashbot/redd/issues/new) /

data/bin/console

@@ -3,6 +3,14 @@
 
 require 'webrick'
 require 'redd'
+require 'pry'
+
+# The REPL session to initialize Pry in.
+module Reddit
+  class << self
+    attr_accessor :reddit
+  end
+end
 
 server = WEBrick::HTTPServer.new(
   Port: 8000,
@@ -22,7 +30,7 @@ server.mount_proc '/' do |_, res|
     </style>
     <div class="wrapper">
       <h1>redd // quickstart</h1>
-      <a href="#" target="_blank" id="btn">Start</a>
+      <a href="/authenticate" target="_blank" id="btn">Start</a>
       <span>a new session in your terminal?</span>
     </div>
   EOS
@@ -36,9 +44,10 @@ server.mount_proc '/authenticate' do |_, res|
       response_type: 'code',
       state: '0',
       redirect_uri: 'http://localhost:8000/redirect',
-      'scope': %w(account creddits edit flair history identity livemanage modconfig modcontributors
-                  modflair modlog modmail modothers modposts modself modwiki mysubreddits
-                  privatemessages read report save submit subscribe vote wikiedit wikiread)
+      duration: 'permanent',
+      scope: %w(account creddits edit flair history identity livemanage modconfig modcontributors
+                modflair modlog modmail modothers modposts modself modwiki mysubreddits
+                privatemessages read report save submit subscribe vote wikiedit wikiread)
     )
   )
 end
@@ -53,11 +62,12 @@ server.mount_proc '/redirect' do |req, res|
   EOS
 
   unless err
-    R = Redd.it(
+    Reddit.reddit = Redd.it(
       user_agent: "Ruby:Redd-Quickstart:v#{Redd::VERSION} (by unknown)",
       client_id: 'P4txR-D6TzF8cg',
       redirect_uri: 'http://localhost:8000/redirect',
-      code: req.query['code']
+      code: req.query['code'],
+      auto_refresh: true
     )
     server.stop
   end
@@ -72,14 +82,30 @@ rescue Interrupt
   exit
 end
 
-# Post a colourful welcome message
-suggestions = [
-  'R.me.link_karma',
-  "R.subreddit('pics').hot.first.title",
-  "puts R.subreddit('all').hot.map(&:title)"
-]
-puts "Welcome, \e[35m/u/#{R.me.name}\e[0m! Try `\e[34m#{suggestions.sample}\e[0m`."
+Reddit.instance_exec do
+  # Post a colourful welcome message
+  suggestions = [
+    # Session#me
+    'reddit.me.link_karma',
+    # Subreddit listings
+    "reddit.subreddit('pics').hot.first.title",
+    # User listings
+    'puts reddit.me.comments(sort: :top).first.body',
+    # Sending messages
+    "reddit.user('Mustermind').send_message(subject: 'Hi!', text: 'How are you?')",
+    # Subscribing to subreddits
+    "reddit.subreddit('EarthPorn').subscribe",
+    # Upvoting
+    'reddit.front_page.hot(time: :month).first.upvote',
+    # Add friend
+    "reddit.user('Mustermind').friend",
+    # List friends
+    'reddit.friends.each { |friend| puts friend.name };',
+    # Hiding / Duplicates
+    'reddit.front_page.hot.each { |l| l.hide if l.duplicates.count > 2 }'
+  ]
+  puts "Hi \e[35m/u/#{reddit.me.name}\e[0m! Try `\e[34m#{suggestions.sample}\e[0m`."
 
-# Load Pry
-require 'pry'
-Pry.start
+  # Load Pry
+  Pry.start(self)
+end

data/lib/redd.rb

@@ -14,8 +14,40 @@ require_relative 'redd/api_client'
 # Redd is a simple and intuitive API wrapper.
 module Redd
   class << self
-    # Guesses the appropriate authentication strategy, creates an API client and starts you off with
-    # a {Models::Session}.
+    # Based on the arguments you provide it, it guesses the appropriate authentication strategy.
+    # You can do this manually with:
+    #
+    #     script   = Redd::AuthStrategies::Script.new(**arguments)
+    #     web      = Redd::AuthStrategies::Web.new(**arguments)
+    #     userless = Redd::AuthStrategies::Userless.new(**arguments)
+    #
+    # It then creates an {APIClient} with the auth strategy provided and calls authenticate on it:
+    #
+    #     client = Redd::APIClient.new(script); client.authenticate(code)
+    #     client = Redd::APIClient.new(web); client.authenticate
+    #     client = Redd::APIClient.new(userless); client.authenticate
+    #
+    # Finally, it creates the {Models::Session} model, which is essentially a starting point for
+    # the user. But you can basically create any model with the client.
+    #
+    #     session = Redd::Models::Session.new(client)
+    #
+    #     user = Redd::Models::User.new(client, name: 'Mustermind')
+    #     puts user.comment_karma
+    #
+    # If `auto_refresh` is `false` or if the access doesn't have an associated `expires_in`, you
+    # can manually refresh the token by calling:
+    #
+    #     session.client.refresh
+    #
+    # Also, you can swap out the client's access any time.
+    #
+    #     new_access = { access_token: '', refresh_token: '', expires_in: 1234 }
+    #
+    #     session.client.access = Redd::Models::Access.new(script, new_access)
+    #     session.client.access = Redd::Models::Access.new(web, new_access)
+    #     session.client.access = Redd::Models::Access.new(userless, new_access)
+    #
     # @see https://www.reddit.com/prefs/apps
     # @param opts [Hash] the options to create the object with
     # @option opts [String] :user_agent your app's *unique* and *descriptive* user agent
@@ -27,9 +59,9 @@ module Redd
     # @option opts [String] :code the code given by reddit (required for *web* and *installed*)
     # @return [Models::Session] a fresh {Models::Session} for you to make requests with
     def it(opts = {})
-      api_client = script(opts) || web(opts) || installed(opts) || userless(opts)
+      api_client = script(opts) || web(opts) || userless(opts)
       raise "couldn't guess app type" unless api_client
-      Models::Session.new(api_client) { |client| client.get('/api/v1/me').body }
+      Models::Session.new(api_client)
     end
 
     # Create a url to send to users for authorization.
@@ -38,14 +70,18 @@ module Redd
     # @param client_id [String] the client id of the app
     # @param redirect_uri [String] the URI for reddit to redirect to after authorization
     # @param scope [Array<String>] an array of scopes to request
+    # @param duration ['temporary', 'permanent'] the duration to request the code for (only applies
+    #   when response_type is 'code')
     # @return [String] the generated url
-    def url(client_id:, redirect_uri:, response_type: 'code', state: '', scope: ['identity'])
+    def url(client_id:, redirect_uri:, response_type: 'code', state: '', scope: ['identity'],
+            duration: 'temporary')
       'https://www.reddit.com/api/v1/authorize?' + URI.encode_www_form(
         client_id: client_id,
         redirect_uri: redirect_uri,
         state: state,
         scope: scope.join(','),
-        response_type: response_type
+        response_type: response_type,
+        duration: duration
       )
     end
 
@@ -56,32 +92,27 @@ module Redd
     end
 
     def filter_api(opts)
-      opts.select { |k| %i(user_agent).include?(k) }
+      opts.select { |k| %i(user_agent limit_time max_retries auto_refresh).include?(k) }
     end
 
     def script(opts = {})
       return unless %i(client_id secret username password).all? { |o| opts.include?(o) }
-      api = APIClient.new(AuthStrategies::Script.new(**filter_auth(opts)), **filter_api(opts))
+      auth = AuthStrategies::Script.new(filter_auth(opts))
+      api = APIClient.new(auth, **filter_api(opts))
       api.tap(&:authenticate)
     end
 
     def web(opts = {})
-      return unless %i(client_id secret redirect_uri code).all? { |o| opts.include?(o) }
-      code = opts.delete(:code)
-      api = APIClient.new(AuthStrategies::Web.new(**filter_auth(opts)), **filter_api(opts))
-      api.tap { |c| c.authenticate(code) }
-    end
-
-    def installed(opts = {})
       return unless %i(client_id redirect_uri code).all? { |o| opts.include?(o) }
-      code = opts.delete(:code)
-      api = APIClient.new(AuthStrategies::Installed.new(**filter_auth(opts)), **filter_api(opts))
-      api.tap { |c| c.authenticate(code) }
+      auth = AuthStrategies::Web.new(**filter_auth(opts))
+      api = APIClient.new(auth, **filter_api(opts))
+      api.tap { |c| c.authenticate(opts[:code]) }
     end
 
     def userless(opts = {})
       return unless %i(client_id secret).all? { |o| opts.include?(o) }
-      api = APIClient.new(AuthStrategies::Userless.new(**filter_auth(opts)), **filter_api(opts))
+      auth = AuthStrategies::Userless.new(filter_auth(opts))
+      api = APIClient.new(auth, **filter_api(opts))
       api.tap(&:authenticate)
     end
   end

data/lib/redd/api_client.rb

@@ -13,35 +13,27 @@ module Redd
     API_ENDPOINT = 'https://oauth.reddit.com'
 
     # @return [APIClient] the access the client uses
-    attr_reader :access
+    attr_accessor :access
 
-    # Create a new API client from an auth strategy.
+    # Create a new API client with an auth strategy.
     # @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 be successful if
-    #   retried
-    # @param auto_login [Boolean] (for script and userless) automatically authenticate if not done
-    #   so already
-    # @param auto_refresh [Boolean] (for script and userless) automatically refresh access token if
-    #   nearing expiration
+    # @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_login: true, auto_refresh: true)
+                   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)
-
-      # FIXME: hard dependencies on Script and Userless types
-      can_auto      = auth.is_a?(AuthStrategies::Script) || auth.is_a?(AuthStrategies::Userless)
-      @auto_login   = can_auto && auto_login
-      @auto_refresh = can_auto && auto_refresh
+      @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.
@@ -50,8 +42,8 @@ module Redd
     end
 
     # Refresh the access currently in use.
-    def refresh(*args)
-      @access = @auth.refresh(*args)
+    def refresh
+      @access = @auth.refresh(@access)
     end
 
     # Revoke the current access and remove it from the client.
@@ -84,6 +76,7 @@ module Redd
       @failures = 0
       response
     rescue Redd::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..."
@@ -94,12 +87,10 @@ module Redd
 
     # Makes sure a valid access is present, raising an error if nil
     def ensure_access_is_valid
-      # Authenticate first if auto_login is enabled
-      authenticate if @access.nil? && @auto_login
+      # 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
-      # Fuck it, panic
-      raise 'client access is nil, try calling #authenticate' if @access.nil?
     end
 
     def connection

data/lib/redd/auth_strategies/auth_strategy.rb

@@ -26,13 +26,14 @@ module Redd
       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(*)
+      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] the access object to revoke
+      # @param access [Access, String] the access to revoke
       def revoke(access)
         token =
           if access.is_a?(String)
@@ -42,7 +43,7 @@ module Redd
           else
             access.access_token
           end
-        post('/api/v1/revoke_token', token: token).body
+        post('/api/v1/revoke_token', token: token)
       end
 
       private

data/lib/redd/auth_strategies/script.rb

@@ -17,7 +17,12 @@ module Redd
       def authenticate
         request_access('password', username: @username, password: @password)
       end
-      alias refresh authenticate
+
+      # 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

@@ -11,7 +11,12 @@ module Redd
       def authenticate
         request_access('client_credentials')
       end
-      alias refresh authenticate
+
+      # 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

@@ -4,10 +4,9 @@ require_relative 'auth_strategy'
 
 module Redd
   module AuthStrategies
-    # A typical code-based authentication. I genuinely recommend this for bots.
-    # Only confidential web apps can be refreshed.
+    # A typical code-based authentication, for 'web' and 'installed' types.
     class Web < AuthStrategy
-      def initialize(client_id:, secret:, redirect_uri:, **kwargs)
+      def initialize(client_id:, redirect_uri:, secret: '', **kwargs)
         super(client_id: client_id, secret: secret, **kwargs)
         @redirect_uri = redirect_uri
       end
@@ -22,7 +21,8 @@ module Redd
       # Refresh the authentication and return a new refreshed access
       # @return [Access] the new access
       def refresh(access)
-        request_access('refresh_token', refresh_token: must_have(access, :refresh_token))
+        refresh_token = access.is_a?(String) ? refresh_token : access.refresh_token
+        request_access('refresh_token', refresh_token: refresh_token)
       end
     end
   end

data/lib/redd/models/access.rb

@@ -7,7 +7,12 @@ module Redd
     # Models access_token and related keys.
     class Access < BasicModel
       def expired?(grace_period = 60)
-        Time.now > @created_at + (get_attribute(:expires_in) - grace_period)
+        return false unless @attributes[:expires_in]
+        Time.now > @created_at + (@attributes[:expires_in] - grace_period)
+      end
+
+      def permanent?
+        !@attributes[:refresh_token].nil?
       end
 
       private