spinels-redd 0.9.0

data/lib/redd/models/user.rb

@@ -0,0 +1,239 @@
+# frozen_string_literal: true
+
+require_relative 'model'
+require_relative 'messageable'
+
+module Redd
+  module Models
+    # A reddit user.
+    class User < Model
+      include Messageable
+
+      # Get the appropriate listing.
+      # @param type [:overview, :submitted, :comments, :liked, :disliked, :hidden, :saved, :gilded]
+      #   the type of listing to request
+      # @param options [Hash] a list of options to send with the request
+      # @option options [:hot, :new, :top, :controversial] :sort the order of the listing
+      # @option options [String] :after return results after the given fullname
+      # @option options [String] :before return results before the given fullname
+      # @option options [Integer] :count the number of items already seen in the listing
+      # @option options [1..100] :limit the maximum number of things to return
+      # @option options [:hour, :day, :week, :month, :year, :all] :time the time period to consider
+      #   when sorting
+      # @option options [:given] :show whether to show the gildings given
+      #
+      # @note The option :time only applies to the top and controversial sorts.
+      # @return [Listing<Submission>]
+      def listing(type, **options)
+        options[:t] = options.delete(:time) if options.key?(:time)
+        PaginatedListing.new(client, **options) do |**req_opts|
+          client.model(:get, "/user/#{read_attribute(:name)}/#{type}.json", options.merge(req_opts))
+        end
+      end
+
+      # @!method overview(**params)
+      # @!method submitted(**params)
+      # @!method comments(**params)
+      # @!method liked(**params)
+      # @!method disliked(**params)
+      # @!method hidden(**params)
+      # @!method saved(**params)
+      # @!method gilded(**params)
+      #
+      # @see #listing
+      %i[overview submitted comments liked disliked hidden saved gilded].each do |type|
+        define_method(type) { |**params| listing(type, **params) }
+      end
+
+      # Compose a message to the moderators of a subreddit.
+      #
+      # @param subject [String] the subject of the message
+      # @param text [String] the message text
+      # @param from [Subreddit, nil] the subreddit to send the message on behalf of
+      def send_message(subject:, text:, from: nil)
+        super(to: read_attribute(:name), subject: subject, text: text, from: from)
+      end
+
+      # Block this user.
+      def block
+        client.post('/api/block_user', account_id: read_attribute(:id))
+      end
+
+      # @return [Array<Trophy>] this user's trophies
+      def trophies
+        client.get("/api/v1/user/#{read_attribute(:name)}/trophies")
+              .body[:data][:trophies]
+              .map { |t| client.unmarshal(t) }
+      end
+
+      # Unblock a previously blocked user.
+      # @param me [User] (optional) the person doing the unblocking
+      def unblock(me: nil) # rubocop:disable Naming/MethodParameterName
+        my_id = "t2_ #{me.is_a?(User ? user.id : client.get('/api/v1/me').body[:id])}"
+        # Talk about an unintuitive endpoint
+        client.post('/api/unfriend', container: my_id, name: read_attribute(:name), type: 'enemy')
+      end
+
+      # Add the user as a friend.
+      # @param note [String] a note for the friend
+      def friend(note = nil)
+        name = read_attribute(:name)
+        body = JSON.generate(note ? { name: name, note: note } : { name: name })
+        client.request(:put, "/api/v1/me/friends/#{name}", body: body)
+      end
+
+      # Unfriend the user.
+      def unfriend
+        name = read_attribute(:name)
+        client.request(:delete, "/api/v1/me/friends/#{name}", raw: true, form: { id: name })
+      end
+
+      # Gift a redditor reddit gold.
+      # @param months [Integer] the number of months of gold to gift
+      def gift_gold(months: 1)
+        client.post("/api/v1/gold/give/#{read_attribute(:name)}", months: months)
+      end
+
+      # @!attribute [r] name
+      #   @return [String] the user's username
+      property :name
+
+      # @!attribute [r] employee?
+      #   @return [Boolean] whether the user is a reddit employee
+      property :employee?, from: :is_employee
+
+      # @!attribute [r] features
+      #   @return [Hash] a hash of features
+      property :features
+
+      # @!attribute [r] friend?
+      #   @return [Boolean] whether the user is your friend
+      property :friend?, from: :is_friend
+
+      # @!attribute [r] no_profanity?
+      #   @return [Boolean] whether the user chooses to filter profanity
+      property :no_profanity?, from: :pref_no_profanity
+
+      # @!attribute [r] suspended?
+      #   @return [Boolean] whether the user is suspended
+      property :suspended?, from: :is_suspended
+
+      # @!attribute [r] geopopular
+      #   @return [String]
+      property :geopopular, from: :pref_geopopular
+
+      # @!attribute [r] subreddit
+      #   @return [Subreddit] the user's personal "subreddit"
+      property :subreddit, with: ->(name) { Subreddit.new(client, display_name: name) if name }
+
+      # @!attribute [r] sponsor?
+      #   @return [Boolean]
+      property :sponsor?, from: :is_sponsor
+
+      # @!attribute [r] gold_expiration
+      #   @return [Time, nil] the time when the user's gold expires
+      property :gold_expiration, with: ->(epoch) { Time.at(epoch) if epoch }
+
+      # @!attribute [r] id
+      #   @return [String] the user's base36 id
+      property :id
+
+      # @!attribute [r] profile_image
+      #   @return [String] a link to the user's profile image
+      property :profile_image, from: :profile_img
+
+      # @!attribute [r] over_18?
+      #   @return [Boolean] whether the user's profile is considered over 18.
+      property :over_18?, from: :profile_over_18
+
+      # @!attribute [r] suspension_expiration
+      #   @return [Time, nil] the time when the user's suspension expires
+      property :suspension_expiration, from: :suspension_expiration_utc,
+                                       with: ->(epoch) { Time.at(epoch) if epoch }
+
+      # @!attribute [r] verified?
+      #   @return [Boolean] whether the user is verified (?)
+      property :verified?, from: :verified
+
+      # @!attribute [r] new_modmail_exists?
+      #   @return [Boolean] whether the user has mail in the new modmail
+      property :new_modmail_exists?, from: :new_modmail_exists
+
+      # @!attribute [r] over_18?
+      #   @return [Boolean] whether the user has indicated they're over 18
+      property :over_18?, from: :over_18
+
+      # @!attribute [r] gold?
+      #   @return [Boolean] whether the user currently has gold
+      property :gold?, from: :is_gold
+
+      # @!attribute [r] mod?
+      #   @return [Boolean] whether the user is a moderator
+      property :mod?, from: :is_mod
+
+      # @!attribute [r] has_verified_email?
+      #   @return [Boolean] whether the user's email has been verified
+      property :has_verified_email?, from: :has_verified_email
+
+      # @!attribute [r] has_mod_mail?
+      #   @return [Boolean] whether the user has old-style mod mail
+      property :has_mod_mail?, from: :has_mod_mail
+
+      # @!attribute [r] hidden_from_robots?
+      #   @return [Boolean] whether the user chose to hide from Google
+      property :hidden_from_robots?, from: :hide_from_robots
+
+      # @!attribute [r] link_karma
+      #   @return [Integer] the user's link karma
+      property :link_karma
+
+      # @!attribute [r] inbox_count
+      #   @return [Integer] the number of messages in the user's inbox
+      property :inbox_count
+
+      # @!attribute [r] show_top_karma_subreddits?
+      #   @return [Boolean] whether top karma subreddits are shown on the user's page
+      property :show_top_karma_subreddits?, from: :pref_top_karma_subreddits
+
+      # @!attribute [r] has_mail?
+      #   @return [Boolean] whether the user has new messages
+      property :has_mail?, from: :has_mail
+
+      # @!attribute [r] show_snoovatar?
+      #   @return [Boolean] whether the user's snoovatar is shown
+      property :show_snoovatar?, from: :pref_show_snoovatar
+
+      # @!attribute [r] created_at
+      #   @return [Time] the time the user signed up
+      property :created_at, from: :created_utc, with: ->(epoch) { Time.at(epoch) }
+
+      # @!attribute [r] gold_creddits
+      #   @return [Integer] the number of gold creddits the user has
+      property :gold_creddits
+
+      # @!attribute [r] in_beta?
+      #   @return [Boolean] whether the user is in beta
+      property :in_beta?, from: :in_beta
+
+      # @!attribute [r] comment_karma
+      #   @return [Integer] the user's comment karma
+      property :comment_karma
+
+      # @!attribute [r] has_subscribed?
+      #   @return [Boolean]
+      property :has_subscribed?, from: :has_subscribed
+
+      private
+
+      def lazer_reload
+        # return load_from_fullname if self[:id] && !self[:name]
+        fully_loaded!
+        client.get("/user/#{read_attribute(:name)}/about").body[:data]
+      end
+
+      def load_from_fullname
+        client.get('/api/user_data_by_account_ids', ids: read_attribute(:id)).body.values.first
+      end
+    end
+  end
+end

data/lib/redd/models/wiki_page.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require_relative 'model'
+
+module Redd
+  module Models
+    # A reddit user.
+    class WikiPage < Model
+      # Edit the wiki page.
+      # @param content [String] the new wiki page contents
+      # @param reason [String, nil] an optional reason for editing the page
+      def edit(content, reason: nil)
+        params = { page: read_attribute(:title), content: content }
+        params[:reason] = reason if reason
+        client.post("/r/#{read_attribute(:subreddit).display_name}/api/wiki/edit", params)
+      end
+
+      # @!attribute [r] title
+      #   @return [String] the page title
+      property :title, :required
+
+      # @!attribute [r] subreddit
+      #   @return [Subreddit] the wiki page's (optional) subreddit
+      property :subreddit, :nil
+
+      # @!attribute [r] may_revise?
+      #   @return [Boolean] not sure, whether you're allowed to edit the page?
+      property :may_revise?, from: :may_revise
+
+      # @!attribute [r] revision_date
+      #   @return [Time] the time of the last revision
+      property :revision_date, with: ->(t) { Time.at(t) }
+
+      # @!attribute [r] content_md
+      #   @return [String] the markdown version of the content
+      property :content_md
+
+      # @!attribute [r] content_html
+      #   @return [String] the html version of the content
+      property :content_html
+
+      # @!attribute [r] revision_by
+      #   @return [User] the user who made the last revision
+      property :revision_by, with: ->(res) { User.new(client, res[:data]) }
+
+      private
+
+      def lazer_reload
+        fully_loaded!
+        path = "/wiki/#{read_attribute(:title)}"
+        path = "/r/#{read_attribute(:subreddit).display_name}#{path}" if exists_locally?(:subreddit)
+        client.get(path).body[:data]
+      end
+    end
+  end
+end

data/lib/redd/utilities/error_handler.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require_relative '../errors'
+
+module Redd
+  module Utilities
+    # Handles response errors in API responses.
+    class ErrorHandler
+      AUTH_HEADER        = 'www-authenticate'
+      INVALID_TOKEN      = 'invalid_token'
+      INSUFFICIENT_SCOPE = 'insufficient_scope'
+
+      HTTP_ERRORS = {
+        400 => Errors::BadRequest,
+        403 => Errors::Forbidden,
+        404 => Errors::NotFound,
+        429 => Errors::TooManyRequests,
+        500 => Errors::ServerError,
+        502 => Errors::ServerError,
+        503 => Errors::ServerError,
+        504 => Errors::ServerError
+      }
+
+      def check_error(res, raw:)
+        # Check for status code-based errors first and return it if we found one.
+        error = invalid_access_error(res) || insufficient_scope_error(res) || other_http_error(res)
+        return error if error || raw
+
+        # If there wasn't an status code error and we're allowed to look into the response, parse
+        # it and check for errors.
+        # TODO: deal with errors of type { fields:, explanation:, message:, reason: }
+        rate_limit_error(res) || other_api_error(res)
+      end
+
+      private
+
+      # Deal with an error caused by having an expired or invalid access token.
+      def invalid_access_error(res)
+        return nil unless res.code == 401 && res.headers[AUTH_HEADER] &&
+                          res.headers[AUTH_HEADER].include?(INVALID_TOKEN)
+
+        Errors::InvalidAccess.new(res)
+      end
+
+      # Deal with an error caused by not having enough the correct scope
+      def insufficient_scope_error(res)
+        return nil unless res.code == 403 && res.headers[AUTH_HEADER] &&
+                          res.headers[AUTH_HEADER].include?(INSUFFICIENT_SCOPE)
+
+        Errors::InsufficientScope.new(res)
+      end
+
+      # Deal with an error signalled by the HTTP response code.
+      def other_http_error(res)
+        HTTP_ERRORS[res.code].new(res) if HTTP_ERRORS.key?(res.code)
+      end
+
+      def rate_limit_error(res)
+        return nil unless res.body.is_a?(Hash) && res.body[:json] && res.body[:json][:ratelimit]
+
+        Errors::RateLimitError.new(res)
+      end
+
+      # Deal with those annoying errors that come with perfect 200 status codes.
+      def other_api_error(res)
+        return nil unless res.body.is_a?(Hash) && res.body[:json] && res.body[:json][:errors] &&
+                          !res.body[:json][:errors].empty?
+
+        Errors::APIError.new(res)
+      end
+    end
+  end
+end

data/lib/redd/utilities/rate_limiter.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Redd
+  module Utilities
+    # Manages rate limiting by sleeping.
+    class RateLimiter
+      def initialize(gap)
+        @gap = gap
+        @last_request_time = Time.now - gap
+      end
+
+      def after_limit
+        sleep_time = (@last_request_time + @gap) - Time.now
+        sleep(sleep_time) if sleep_time > 0.01
+        response = yield
+        @last_request_time += @gap
+        response
+      end
+    end
+  end
+end

data/lib/redd/utilities/unmarshaller.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module Redd
+  module Utilities
+    # Unmarshals hashes into objects.
+    class Unmarshaller
+      # Contains the mapping from 'kind' strings to classes.
+      # TODO: UserList type!
+      MAPPING = {
+        'Listing' => Models::Listing,
+        't1' => Models::Comment,
+        't2' => Models::User,
+        't3' => Models::Submission,
+        't4' => Models::PrivateMessage,
+        't5' => Models::Subreddit,
+        't6' => Models::Trophy,
+        'more' => Models::MoreComments,
+        'wikipage' => Models::WikiPage,
+        'modaction' => Models::ModAction,
+        'LabeledMulti' => Models::Multireddit,
+        'LiveUpdate' => Models::LiveUpdate
+      }
+
+      def initialize(client)
+        @client = client
+      end
+
+      def unmarshal(res)
+        # I'm loving the hell out of this pattern.
+        model = js_listing(res) || js_model(res) || api_model(res)
+        raise "cannot unmarshal: #{res.inspect}" if model.nil?
+
+        model
+      end
+
+      private
+
+      # Unmarshal frontent API-style listings
+      def js_listing(res)
+        # One day I'll get to deprecate Ruby 2.2 and jump into the world of Hash#dig.
+        return nil unless res[:json] && res[:json][:data] && res[:json][:data][:things]
+
+        Models::Listing.new(@client, children: res[:json][:data][:things])
+      end
+
+      # Unmarshal frontend API-style models.
+      def js_model(res)
+        # FIXME: deprecate this? this shouldn't be happening in the API, so this is better handled
+        #   in the respective classes.
+        Models::Model.new(@client, res[:json][:data]) if res[:json] && res[:json][:data]
+      end
+
+      # Unmarshal API-provided listings.
+      def api_listing(res)
+        return nil unless res[:kind] == 'Listing'
+
+        attributes = res[:data]
+        attributes[:children].map! { |child| unmarshal(child) }
+        Models::Listing.new(@client, attributes)
+      end
+
+      # Unmarshal API-provided model.
+      def api_model(res)
+        return nil unless MAPPING[res[:kind]]
+
+        MAPPING[res[:kind]].new(@client, res[:data])
+      end
+    end
+  end
+end

data/lib/redd/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Redd
+  VERSION = '0.9.0'
+end

data/lib/redd.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+require 'uri'
+
+# Redd Version
+require_relative 'redd/version'
+# Models
+Dir[File.join(__dir__, 'redd', 'models', '*.rb')].sort.each { |f| require f }
+# Authentication Clients
+Dir[File.join(__dir__, 'redd', 'auth_strategies', '*.rb')].sort.each { |f| require f }
+# Error Classes
+require_relative 'redd/errors'
+# Regular Client
+require_relative 'redd/api_client'
+# Assists
+Dir[File.join(__dir__, 'redd', 'assist', '*.rb')].sort.each { |f| require f }
+
+# Redd is a simple and intuitive API wrapper.
+module Redd
+  class << self
+    # 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
+    # @option opts [String] :client_id the client id of your app
+    # @option opts [String] :secret the app secret (for confidential types, i.e. *not* *installed*)
+    # @option opts [String] :username the username of your bot (only for *script*)
+    # @option opts [String] :password the plaintext password of your bot (only for *script*)
+    # @option opts [String] :redirect_uri the provided redirect URI (only for *web* and *installed*)
+    # @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) || userless(opts)
+      raise "couldn't guess app type" unless api_client
+
+      Models::Session.new(api_client)
+    end
+
+    # Create a url to send to users for authorization.
+    # @param response_type ['code', 'token'] the type of response from reddit
+    # @param state [String] a randomly generated token to avoid CSRF attacks.
+    # @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'],
+            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,
+          duration: duration
+        )
+      }"
+    end
+
+    private
+
+    def filter_auth(opts)
+      opts.select { |k| %i[client_id secret username password redirect_uri user_agent].include?(k) }
+    end
+
+    def filter_api(opts)
+      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) }
+
+      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 redirect_uri code].all? { |o| opts.include?(o) }
+
+      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) }
+
+      auth = AuthStrategies::Userless.new(**filter_auth(opts))
+      api = APIClient.new(auth, **filter_api(opts))
+      api.tap(&:authenticate)
+    end
+  end
+end

data/lib/spinels-redd.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require 'redd'

data/spinels-redd.gemspec

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+lib = File.expand_path('lib', __dir__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'redd/version'
+
+Gem::Specification.new do |spec| # rubocop:disable Metrics/BlockLength
+  spec.name     = 'spinels-redd'
+  spec.version  = Redd::VERSION
+  spec.authors  = ['Avinash Dwarapu']
+  spec.email    = ['avinash@dwarapu.me']
+  spec.summary  = 'A batteries-included API wrapper for reddit.'
+  spec.homepage = 'https://github.com/spinels/redd'
+  spec.license  = 'MIT'
+  spec.required_ruby_version = '>= 2.6'
+
+  spec.files = `git ls-files -z`.split("\x0").reject do |f|
+    f.match(%r{^(test|spec|features)/})
+  end
+  spec.bindir        = 'exe'
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ['lib']
+
+  spec.add_dependency 'http', '>= 4.0', '< 6.0'
+  spec.add_dependency 'lazy_lazer', '~> 0.8.1'
+
+  spec.add_development_dependency 'bundler', '~> 2.0'
+  spec.add_development_dependency 'pry', '~> 0.10'
+  spec.add_development_dependency 'rake', '~> 13.0'
+  spec.add_development_dependency 'rubocop', '~> 1.26'
+  spec.add_development_dependency 'yard', '~> 0.9.9'
+
+  spec.add_development_dependency 'guard', '~> 2.14'
+  spec.add_development_dependency 'guard-rspec', '~> 4.7'
+  spec.add_development_dependency 'rspec', '~> 3.5'
+  spec.add_development_dependency 'simplecov', '~> 0.13'
+  spec.add_development_dependency 'vcr', '~> 6.1'
+  spec.add_development_dependency 'webmock', '~> 3.14'
+end