redd 0.7.10 → 0.8.0.pre.1

data/lib/redd/models/more_comments.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require_relative 'lazy_model'
+
+module Redd
+  module Models
+    class MoreComments < LazyModel
+    end
+  end
+end

data/lib/redd/models/multireddit.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require_relative 'lazy_model'
+
+module Redd
+  module Models
+    # A multi.
+    class Multireddit < LazyModel
+      # Make a Multireddit from its path.
+      # @option hash [String] :path the multi's path
+      # @return [Multireddit]
+      def self.from_response(client, hash)
+        path = hash.fetch(:path)
+        new(client, hash) { |c| c.get("/api/multi#{path}").body[:data] }
+      end
+
+      # Create a Multireddit from its path.
+      # @param client [APIClient] the api client to initialize the object with
+      # @param id [String] the multi's path (prepended by a /)
+      # @return [Multireddit]
+      def self.from_id(client, id)
+        from_response(client, path: id)
+      end
+
+      def after_initialize
+        @attributes[:subreddits].map! do |subreddit|
+          Subreddit.from_response(client, display_name: subreddit[:name])
+        end
+      end
+    end
+  end
+end

data/lib/redd/models/postable.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module Redd
+  module Models
+    # Methods for user-submitted content, i.e. Submissions and Comments.
+    module Postable
+      # Edit a thing.
+      # @param text [String] The new text.
+      # @return [self] the edited thing
+      def edit(text)
+        @client.post('/api/editusertext', thing_id: get_attribute(:name), text: text)
+        @attributes[is_a?(Submission) ? :selftext : :body] = text
+        self
+      end
+
+      # Delete the thing.
+      def delete
+        @client.post('/api/del', id: get_attribute(:name))
+      end
+
+      # Save a link or comment to the user's account.
+      # @param category [String] a category to save to
+      def save(category = nil)
+        params = { id: fullname }
+        params[:category] = category if category
+        @client.post('/api/save', params)
+      end
+
+      # Remove the link or comment from the user's saved links.
+      def unsave
+        @client.post('/api/unsave', id: get_attribute(:name))
+      end
+
+      # Hide a link from the user.
+      def hide
+        @client.post('/api/hide', id: get_attribute(:fullname))
+      end
+
+      # Unhide a previously hidden link.
+      def unhide
+        @client.post('/api/unhide', id: get_attribute(:fullname))
+      end
+
+      # Upvote the model.
+      def upvote
+        vote(1)
+      end
+
+      # Downvote the model.
+      def downvote
+        vote(-1)
+      end
+
+      # Clear any upvotes or downvotes on the model.
+      def undo_vote
+        vote(0)
+      end
+
+      private
+
+      # Send a vote.
+      # @param direction [-1, 0, 1] the direction to vote in
+      def vote(direction)
+        fullname = get_attribute(:name)
+        @client.post('/api/vote', id: fullname, dir: direction)
+        @attributes[:ups] += direction
+      end
+    end
+  end
+end

data/lib/redd/models/private_message.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require_relative 'lazy_model'
+require_relative 'inboxable'
+require_relative 'replyable'
+
+module Redd
+  module Models
+    # A private message
+    class PrivateMessage < LazyModel
+      include Inboxable
+      include Replyable
+
+      # Make a Message from its id.
+      # @option hash [String] :id the post's id (e.g. abc123)
+      # @return [Submission]
+      def self.from_response(client, hash)
+        # FIXME: This returns the entire conversation, not the specific message. Possible to search,
+        #   because depth of replies is just one.
+        super
+      end
+
+      # Delete the message from the user's inbox.
+      def delete
+        @client.post('/api/del_msg', id: get_attribute(:name))
+      end
+    end
+  end
+end

data/lib/redd/models/replyable.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Redd
+  module Models
+    # A model that can be commented on or replied to.
+    module Replyable
+      # Add a comment to a link, reply to a comment or reply to a message.
+      # @param text [String] the text to comment
+      # @return [Comment, PrivateMessage] The created reply.
+      def reply(text)
+        fullname = get_attribute(:name)
+        @client.model(:post, '/api/comment/', text: text, thing_id: fullname).first
+      end
+    end
+  end
+end

data/lib/redd/models/session.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require_relative 'lazy_model'
+
+module Redd
+  module Models
+    # The starter class.
+    class Session < BasicModel
+      # @return [FrontPage] the user's front page
+      def front_page
+        FrontPage.new(@client)
+      end
+
+      # @return [User] the logged-in user
+      def me
+        User.new(@client) { |client| client.get('/api/v1/me').body }
+      end
+
+      # Get a (lazily loaded) reddit user by their name.
+      # @param name [String] the username
+      # @return [User]
+      def user(name)
+        User.from_id(@client, name)
+      end
+
+      # Get a (lazily loaded) subreddit by its name.
+      # @param display_name [String] the subreddit's display name
+      # @return [Subreddit]
+      def subreddit(display_name)
+        Subreddit.from_id(@client, display_name)
+      end
+
+      # @return [Array<Multireddit>] array of multireddits belonging to the user
+      def my_multis
+        @client.get('/api/multi/mine').body.map { |m| @client.unmarshal(m) }
+      end
+
+      # Get a (lazily loaded) multi by its path.
+      # @param path [String] the multi's path, prepended by a /
+      # @return [Multireddit]
+      def multi(path)
+        Multireddit.from_id(@client, path)
+      end
+
+      # Get submissions or comments by their fullnames.
+      # @param fullnames [String, Array<String>] one or an array of fullnames (e.g. t3_abc1234)
+      # @return [Listing<Submission, Comment>]
+      def get(fullnames)
+        # XXX: Could we use better methods for t1_ and t3_?
+        @client.model(:get, '/api/info', id: Array(fullnames).join(','))
+      end
+
+      # Get submissions or comments by their fullnames.
+      # @param url [String] the object's url
+      # @return [Submission, Comment, nil] the object, or nil if not found
+      def from_url(url)
+        @client.model(:get, '/api/info', url: url).first
+      end
+
+      # Return a listing of the user's inbox (including comment replies and 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 optional 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.
+      # @return [Listing]
+      def my_messages(category: 'inbox', mark: false, **params)
+        @client.model(:get, "/message/#{category}.json", params.merge(mark: mark))
+      end
+
+      # Mark all messages as read.
+      def read_all_messages
+        @client.post('/api/read_all_messages')
+      end
+    end
+  end
+end

data/lib/redd/models/submission.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require_relative 'lazy_model'
+require_relative 'moderatable'
+require_relative 'postable'
+require_relative 'replyable'
+
+require_relative 'user'
+require_relative 'subreddit'
+
+module Redd
+  module Models
+    # A text or link post.
+    class Submission < LazyModel
+      include Moderatable
+      include Postable
+      include Replyable
+
+      coerce_attribute :author, User
+      coerce_attribute :subreddit, Subreddit
+
+      # Make a Submission from its id.
+      # @option hash [String] :id the post's id (e.g. abc123)
+      # @return [Submission]
+      def self.from_response(client, hash)
+        link_id = hash.fetch(:id)
+        new(client, hash) do |c|
+          # `details` is a pair (2-element array):
+          #   - details[0] is a one-item listing containing the submission
+          #   - details[1] is listing of comments
+          details = c.get("/comments/#{link_id}").body
+          comments = details[1][:data][:children].map do |comment_object|
+            Comment.from_response(c, comment_object[:data])
+          end
+          details[0][:data][:children][0][:data].merge(comments: comments)
+        end
+      end
+    end
+  end
+end

data/lib/redd/models/subreddit.rb

@@ -0,0 +1,201 @@
+# frozen_string_literal: true
+
+require_relative 'lazy_model'
+require_relative 'messageable'
+require_relative '../utilities/stream'
+
+module Redd
+  module Models
+    # A subreddit.
+    class Subreddit < LazyModel
+      include Messageable
+
+      # Make a Subreddit from its name.
+      # @option hash [String] :display_name the subreddit's name
+      # @return [Subreddit]
+      def self.from_response(client, hash)
+        name = hash.fetch(:display_name)
+        new(client, hash) { |c| c.get("/r/#{name}/about").body[:data] }
+      end
+
+      # Create a Subreddit from its name.
+      # @param client [APIClient] the api client to initialize the object with
+      # @param id [String] the subreddit name
+      # @return [Subreddit]
+      def self.from_id(client, id)
+        from_response(client, display_name: id)
+      end
+
+      # @return [Array<String>] the subreddit's wiki pages
+      def wiki_pages
+        @client.get("/r/#{get_attribute(:display_name)}/wiki/pages").body[:data]
+      end
+
+      # Get a wiki page by its title.
+      # @param title [String] the page's title
+      # @return [WikiPage]
+      def wiki_page(title)
+        WikiPage.from_response(@client, title: title, subreddit: self)
+      end
+
+      # @!group Listings
+
+      # Get the appropriate listing.
+      # @param sort [:hot, :new, :top, :controversial, :comments, :rising] the type of listing
+      # @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 the number of items already seen in the listing
+      # @option params [1..100] :limit the maximum number of things to return
+      # @option params [:hour, :day, :week, :month, :year, :all] :time the time period to consider
+      #   when sorting
+      #
+      # @note The option :time only applies to the top and controversial sorts.
+      # @return [Listing<Submission, Comment>]
+      def listing(sort, **params)
+        params[:t] = params.delete(:time) if params.key?(:time)
+        @client.model(:get, "/r/#{get_attribute(:display_name)}/#{sort}.json", params)
+      end
+
+      # @!method hot(**params)
+      # @!method new(**params)
+      # @!method top(**params)
+      # @!method controversial(**params)
+      # @!method comments(**params)
+      # @!method rising(**params)
+      #
+      # @see #listing
+      %i(hot new top controversial comments rising).each do |sort|
+        define_method(sort) { |**params| listing(sort, **params) }
+      end
+
+      # @!endgroup
+      # @!group Moderator Listings
+
+      # Get the appropriate moderator listing.
+      # @param type [:reports, :spam, :modqueue, :unmoderated, :edited] the type of listing
+      # @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 the number of items already seen in the listing
+      # @option params [1..100] :limit the maximum number of things to return
+      # @option params [:links, :comments] :only the type of objects required
+      #
+      # @return [Listing<Submission, Comment>]
+      def moderator_listing(type, **params)
+        @client.model(:get, "/r/#{get_attribute(:display_name)}/about/#{type}.json", params)
+      end
+
+      # @!method reports(**params)
+      # @!method spam(**params)
+      # @!method modqueue(**params)
+      # @!method unmoderated(**params)
+      # @!method edited(**params)
+      #
+      # @see #moderator_listing
+      %i(reports spam modqueue unmoderated edited).each do |type|
+        define_method(type) { |**params| moderator_listing(type, **params) }
+      end
+
+      # @!endgroup
+
+      # Stream newly submitted posts.
+      def post_stream(**params, &block)
+        params[:limit] ||= 100
+        stream = Utilities::Stream.new do |before|
+          listing(:new, params.merge(before: before))
+        end
+        block_given? ? stream.stream(&block) : stream.enum_for(:stream)
+      end
+
+      # Stream newly submitted comments.
+      def comment_stream(**params, &block)
+        params[:limit] ||= 100
+        stream = Utilities::Stream.new do |before|
+          listing(:comments, params.merge(before: before))
+        end
+        block_given? ? stream.stream(&block) : stream.enum_for(:stream)
+      end
+
+      # Submit a link or a text post to the subreddit.
+      # @note If both text and url are provided, url takes precedence.
+      #
+      # @param title [String] the title of the submission
+      # @param text [String] the text of the self-post
+      # @param url [String] the URL of the link
+      # @param resubmit [Boolean] whether to post a link to the subreddit despite it having been
+      #   posted there before (you monster)
+      # @param sendreplies [Boolean] whether to send the replies to your inbox
+      # @return [Submission] The returned object (url, id and name)
+      def submit(title, text: nil, url: nil, resubmit: false, sendreplies: true)
+        params = {
+          title: title, sr: get_attribute(:display_name),
+          resubmit: resubmit, sendreplies: sendreplies
+        }
+        params[:kind] = url ? 'link' : 'self'
+        params[:url]  = url  if url
+        params[:text] = text if text
+        Submission.from_response(@client, @client.post('/api/submit', params).body[:json][:data])
+      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: "/r/#{get_attribute(:display_name)}", subject: subject, text: text, from: from)
+      end
+
+      # Set the flair for a link or a user for this subreddit.
+      # @param thing [User, Submission] the object whose flair to edit
+      # @param text [String] a string no longer than 64 characters
+      # @param css_class [String] the css class to assign to the flair
+      def set_flair(thing, text, css_class: nil)
+        key = thing.is_a?(User) ? :name : :link
+        params = { :text => text, key => thing.name }
+        params[:css_class] = css_class if css_class
+        @client.post("/r/#{get_attribute(:display_name)}/api/flair", params)
+      end
+
+      # Get a listing of all user flairs.
+      # @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 the number of items already seen in the listing
+      # @option params [String] :name prefer {#get_flair}
+      # @option params [:links, :comments] :only the type of objects required
+      #
+      # @return [Listing<Hash<Symbol, String>>]
+      def flair_listing(**params)
+        res = @client.get("/r/#{get_attribute(:display_name)}/api/flairlist", params).body
+        Listing.new(@client, children: res[:users], before: res[:prev], after: res[:next])
+      end
+
+      # Get the user's flair data.
+      # @param user [User] the user whose flair to fetch
+      # @return [Hash, nil]
+      def get_flair(user)
+        # We have to do this because reddit returns all flairs if given a nonexistent user
+        flair = flair_listing(name: user.name).first
+        return flair if flair && flair[:user].casecmp(user.name).zero?
+        nil
+      end
+
+      # Add the subreddit to the user's subscribed subreddits.
+      def subscribe(action: :sub, skip_initial_defaults: false)
+        @client.post(
+          '/api/subscribe',
+          sr_name: get_attribute(:display_name),
+          action: action,
+          skip_initial_defaults: skip_initial_defaults
+        )
+      end
+
+      # Remove the subreddit from the user's subscribed subreddits.
+      def unsubscribe
+        subscribe(action: :unsub)
+      end
+    end
+  end
+end