redditkit 1.0.0

data/lib/redditkit/client/moderation.rb

@@ -0,0 +1,179 @@
+require 'redditkit/moderator_action'
+
+module RedditKit
+  class Client
+
+    # Methods for moderating subreddits.
+    module Moderation
+
+      # Ban a user. This requires moderator privileges on the specified subreddit.
+      #
+      # @param user [String, RedditKit::User] The user's username, or a RedditKit::User.
+      # @param subreddit [String, RedditKit::Subreddit] The subreddit's name, or a RedditKit::Subreddit.
+      # @note If a subreddit's name is passed as the :subreddit option, a second HTTP request will be made to get the RedditKit::Subreddit object.
+      def ban(user, subreddit)
+        ban_or_unban_user true, user, subreddit
+      end
+
+      # Lift the ban on a user. This requires moderator privileges on the specified subreddit.
+      #
+      # @param user [String, RedditKit::User] The user's username, or a RedditKit::User.
+      # @param subreddit [String, RedditKit::Subreddit] The subreddit's name, or a RedditKit::Subreddit.
+      def unban(user, subreddit)
+        ban_or_unban_user false, user, subreddit
+      end
+
+      # Approves an unmoderated link.
+      #
+      # @param link [String, RedditKit::Link] A link's full name, or a RedditKit::Link.
+      def approve(link)
+        full_name = extract_full_name link
+        post('api/approve', { :id => full_name, :api_type => :json })
+      end
+
+      # Removes a link or comment.
+      #
+      # @param object [String, RedditKit::Comment, RedditKit::Link] The full name of a link/comment, a RedditKit::Comment, or a RedditKit::Link.
+      def remove(object)
+        full_name = extract_full_name object
+        post('api/remove', { :id => full_name, :api_type => :json })
+      end
+
+      # Ignores the reports on a link or comment.
+      #
+      # @param object [String, RedditKit::Comment, RedditKit::Link] The full name of a link/comment, a RedditKit::Comment, or a RedditKit::Link.
+      def ignore_reports(object)
+        full_name = extract_full_name object
+        post('api/ignore_reports', { :id => full_name, :api_type => :json })
+      end
+
+      # Unignores the reports on a link or comment.
+      #
+      # @param object [String, RedditKit::Comment, RedditKit::Link] The full name of a link/comment, a RedditKit::Comment, or a RedditKit::Link.
+      def unignore_reports(object)
+        full_name = extract_full_name object
+        post('api/unignore_reports', { :id => full_name, :api_type => :json })
+      end
+
+      # Distinguishes a comment as being posted by a moderator or admin.
+      #
+      # @option options [String, RedditKit::Comment] comment The full name of a comment, or a RedditKit::Comment.
+      # @option options [yes, no, admin, special] distinguish How to distinguish the comment. Defaults to yes.
+      # @note admin and special values may only be used if the current user has the right privileges.
+      def distinguish(options)
+        full_name = extract_full_name options[:comment]
+        how = options[:distinguish] || :yes
+        parameters = { :id => full_name, :api_type => :json }
+
+        post("api/distinguish/#{how}", parameters)
+      end
+
+      # Sets a post as have its contest mode enabled or disabled.
+      #
+      # @param link [String, RedditKit::Link] The full name of a link, or a RedditKit::Link.
+      # @param contest_mode [Boolean] Whether to enable contest mode for the link's comments. Defaults to true.
+      def set_contest_mode(link, contest_mode = true)
+        full_name = extract_full_name link
+        set_as_contest = contest_mode ? 'True' : 'False'
+
+        post('api/set_contest_mode', { :id => full_name, :state => set_as_contest, :api_type => :json })
+      end
+      
+      # Sets a post as sticky within its parent subreddit. This will replace the existing sticky post, if there is one.
+      #
+      # @param link [String, RedditKit::Link] The full name of a link, or a RedditKit::Link.
+      # @param sticky [Boolean] Whether to mark the post as sticky or unsticky. Defaults to true.
+      def set_sticky_post(link, sticky = true)
+        full_name = extract_full_name link
+        set_as_sticky = sticky ? 'True' : 'False'
+
+        post('api/set_subreddit_sticky', { :id => full_name, :state => set_as_sticky, :api_type => :json })
+      end
+
+      # Get the moderators of a subreddit.
+      # 
+      # @param subreddit [String, RedditKit::Subreddit] The display name of a subreddit, or a RedditKit::Subreddit.
+      # @return [Array<OpenStruct>]
+      def moderators_of_subreddit(subreddit)
+        members_in_subreddit subreddit, 'moderators'
+      end
+
+      # Get the contributors to a subreddit.
+      # 
+      # @param subreddit [String, RedditKit::Subreddit] The display name of a subreddit, or a RedditKit::Subreddit.
+      # @return [Array<OpenStruct>]
+      def contributors_to_subreddit(subreddit)
+        members_in_subreddit subreddit, 'contributors'
+      end
+
+      # Accepts an invitation to become a moderator of a subreddit.
+      #
+      # @param subreddit [String, RedditKit::Subreddit] The display name of the subreddit, or a RedditKit::Subreddit.
+      def accept_moderator_invitation(subreddit)
+        subreddit_name = extract_string(subreddit, :display_name)
+        post('api/accept_moderator_invite', { :r => subreddit_name })
+      end
+
+      # Resign as a contributor to a subreddit.
+      #
+      # @param subreddit [String, RedditKit::Subreddit] A subreddit's full name, or a RedditKit::Subreddit.
+      def resign_as_contributor(subreddit)
+        full_name = extract_full_name subreddit
+        post('api/leavecontributor', { :id => full_name })
+      end
+      
+      # Resign as a moderator of a subreddit.
+      #
+      # @param subreddit [String, RedditKit::Subreddit] A subreddit's full name, or a RedditKit::Subreddit.
+      def resign_as_moderator(subreddit)
+        full_name = extract_full_name subreddit
+        post('api/leavemoderator', { :id => full_name })
+      end
+
+      # Resets a subreddit's header image.
+      #
+      # @param subreddit [String, RedditKit::Subreddit] The display name of the subreddit, or a RedditKit::Subreddit.
+      def reset_subreddit_header(subreddit)
+        subreddit_name = extract_string(subreddit, :display_name)
+        post('api/delete_sr_header', { :r => subreddit_name })
+      end
+
+      # Gets the moderation log for a subreddit.
+      #
+      # @param subreddit [String, RedditKit::Subreddit] A subreddit's display name, or a RedditKit::Subreddit.
+      # @return [RedditKit::PaginatedResponse]
+      def moderation_log(subreddit)
+        display_name = extract_string subreddit, :display_name
+        objects_from_response(:get, "r/#{display_name}/about/log.json", nil)
+      end
+
+      private
+
+      # Lift the ban on a user. This requires moderator privileges on the specified subreddit.
+      #
+      # @param ban_or_unban [true, false] Whether to ban or unban the user.
+      # @param user [String, RedditKit::User] The user's username, or a RedditKit::User.
+      # @param subreddit [String, RedditKit::Subreddit] The subreddit's name, or a RedditKit::Subreddit.
+      def ban_or_unban_user(ban, user, subreddit)
+        username = extract_string(user, :username)
+        subreddit_object = (subreddit.is_a? String) ? subreddit(subreddit) : subreddit
+        friend_request_type = ban ? 'friend' : 'unfriend'
+
+        friend_request friend_request_type, :container => subreddit_object.full_name, :name => username, :subreddit => subreddit_object.name, :type => :banned
+      end
+
+      # Gets members of a given type in a subreddit.
+      #
+      # @param subreddit [String, RedditKit::Subreddit] A subreddit's display name, or a RedditKit::Subreddit.
+      # @param member_type [moderators, contributors] The type of members.
+      def members_in_subreddit(subreddit, member_type)
+        subreddit_name = extract_string(subreddit, :display_name)
+        response = get("r/#{subreddit_name}/about/#{member_type}.json", nil)
+
+        members = response[:body][:data][:children]
+        members.collect { |member| OpenStruct.new(member) }
+      end
+
+    end
+  end
+end

data/lib/redditkit/client/multireddits.rb

@@ -0,0 +1,207 @@
+require 'json'
+require 'redditkit/multireddit'
+require 'redditkit/multireddit_description'
+
+module RedditKit
+  class Client
+
+    # Methods for interacting with multireddits.
+    module Multireddits
+
+      # Fetch the current user's multireddits.
+      #
+      # @return [Array<RedditKit::Multireddit>]
+      def my_multireddits
+        objects_from_response(:get, 'api/multi/mine.json', nil)
+      end
+
+      # Fetch a single multireddit.
+      #
+      # @overload multireddit(path)
+      #   @param path [String] The multireddit's path.
+      # @overload multireddit(username, multireddit_name)
+      #   @param username [String] The username of the user who owns the multireddit.
+      #   @param multireddit_name [String] The multireddit's name.
+      # @return [RedditKit::Multireddit]
+      def multireddit(*args)
+        path = "api/multi"
+
+        if args.length == 1
+          path << args.first
+        else
+          path << path_for_multireddit(args.first, args.last << '.json')
+        end
+
+        object_from_response(:get, path, nil)
+      end
+
+      # Fetches the description for a multireddit.
+      #
+      # @overload multireddit_description(multireddit)
+      #   @param multireddit [RedditKit::Multireddit] A RedditKit::Multireddit object.
+      # @overload multireddit_description(user, multireddit_name)
+      #   @param user [String, RedditKit::User] The name of the user who owns the multireddit.
+      #   @param multireddit_name [String] The name of the multireddit.
+      # @raise [RedditKit::NotAuthenticated] if there is not a user signed in.
+      def multireddit_description(*args)
+        raise RedditKit::NotAuthenticated unless signed_in?
+
+        multireddit = args.pop
+        user = args.first
+        multireddit_path = nil
+
+        if user.nil?
+          multireddit_path = multireddit.path
+        else
+          username = extract_string(user, :username)
+          multireddit_path = path_for_multireddit username, multireddit
+        end
+
+        object_from_response(:get, "api/multi#{multireddit_path}/description", nil)
+      end
+
+      # Sets the description for a multireddit.
+      #
+      # @param multireddit [String, RedditKit::Multireddit] The name of the multireddit, or a RedditKit::Multireddit.
+      # @param description [String] The new description for the subreddit.
+      # @return [RedditKit::MultiredditDescription] The updated multireddit description.
+      def set_multireddit_description(multireddit, description)
+        multireddit_name = extract_string(multireddit, :name)
+        multireddit_path = path_for_multireddit username, multireddit_name
+
+        model = { :body_md => description }
+        parameters = { :multipath => multireddit_path, :model => model.to_json }
+        path = "api/multi#{multireddit_path}/description"
+
+        response = put path, parameters
+
+        RedditKit::MultiredditDescription.new response[:body]
+      end
+
+      # Creates a new multireddit.
+      #
+      # @param multireddit [String, RedditKit::Multireddit] The name of the multireddit, or a RedditKit::Multireddit.
+      # @param subreddits [Array] An array of subreddit names or RedditKit::Subreddit objects.
+      # @param visibility [public, private] An array of subreddit names to be added to the multireddit.
+      def create_multireddit(multireddit, subreddits = [], visibility = 'private')
+        create_or_update_multireddit(:post, multireddit, subreddits, visibility)
+      end
+
+      # Updates an existing multireddit.
+      #
+      # @param multireddit [String, RedditKit::Multireddit] The name of the multireddit, or a RedditKit::Multireddit.
+      # @param subreddits [Array] An array of subreddit names or RedditKit::Subreddit objects.
+      # @param visibility [public, private] An array of subreddit names to be added to the multireddit.
+      def update_multireddit(multireddit, subreddits = [], visibility = 'private')
+        create_or_update_multireddit(:put, multireddit, subreddits, visibility)
+      end
+
+      # Copies a multireddit.
+      #
+      # @overload copy_multireddit(multireddit, copied_name)
+      #   @param multireddit [String, RedditKit::Multireddit] The name of the multireddit, or a RedditKit::Multireddit.
+      #   @param copied_name [String] The copied name for the multireddit.
+      # @overload copy_multireddit(user, multireddit_name, copied_name)
+      #   @param user [String, RedditKit::User] The name of the user who owns the multireddit.
+      #   @param multireddit_name [String] The name of the multireddit.
+      #   @param copied_name [String] The copied name for the multireddit.
+      def copy_multireddit(*args)
+        copied_name = args.pop
+        multireddit_name = extract_string(args.pop, :name)
+        user = args.first
+
+        if user.nil?
+          user = @username
+        else
+          user = extract_string(user, :username)
+        end
+
+        target_multireddit_path = path_for_multireddit user, multireddit_name
+        destination_multireddit_path = path_for_multireddit user, copied_name
+        parameters = { :from => target_multireddit_path, :to => destination_multireddit_path }
+
+        post('api/multi/copy', parameters)
+      end
+
+      # Rename a multireddit owned by the current user.
+      #
+      # @param from [String] The multireddit's current name.
+      # @param to [String] The new name for the multireddit.
+      def rename_multireddit(from, to)
+        old_multireddit_path = path_for_multireddit @username, from
+        new_multireddit_path = path_for_multireddit @username, to
+
+        parameters = { :from => old_multireddit_path, :to => new_multireddit_path }
+        response = post('api/multi/rename', parameters)
+
+        RedditKit::Multireddit.new response[:body]
+      end
+
+      # Delete a multireddit.
+      #
+      # @param multireddit [String, RedditKit::Multireddit] A multireddit's name, or a RedditKit::Multireddit.
+      def delete_multireddit(multireddit)
+        multireddit_name = extract_string(multireddit, :name)
+
+        multireddit_path = path_for_multireddit @username, multireddit_name
+        path = "api/multi#{multireddit_path}"
+        parameters = { :multireddit => path_for_multireddit(@username, multireddit_name) }
+
+        delete_path(path, parameters)
+      end
+
+      # Add a subreddit to a multireddit owned by the current user.
+      #
+      # @param multireddit [String, RedditKit::Multireddit] The multireddit's name, or a RedditKit::Multireddit.
+      # @param subreddit [String, RedditKit::Subreddit] The subreddit's name, or a RedditKit::Subreddit.
+      def add_subreddit_to_multireddit(multireddit, subreddit)
+        multireddit_name = extract_string multireddit, :name
+        subreddit_name = extract_string subreddit, :name
+
+        multireddit_path = path_for_multireddit @username, multireddit_name
+        path = "api/multi#{multireddit_path}/r/#{subreddit_name}"
+        model = { :name => subreddit_name }
+
+        put(path, { :model => model.to_json })
+      end
+
+      # Removes a subreddit from a multireddit owned by the current user.
+      #
+      # @param multireddit [String, RedditKit::Multireddit] The multireddit's name, or a RedditKit::Multireddit.
+      # @param subreddit [String, RedditKit::Subreddit] The subreddit's name, or a RedditKit::Subreddit.
+      def remove_subreddit_from_multireddit(multireddit, subreddit)
+        multireddit_name = extract_string multireddit, :name
+        subreddit_name = extract_string subreddit, :name
+
+        multireddit_path = path_for_multireddit @username, multireddit_name
+        path = "api/multi#{multireddit_path}/r/#{subreddit_name}"
+
+        delete_path(path, nil)
+      end
+
+      private
+
+      # Creates or updates a multireddit.
+      #
+      # @param method [post, put] The HTTP method for the request. POST creates a multireddit, PUT updates one.
+      # @param multireddit [String, RedditKit::Multireddit] The name of the multireddit, or a RedditKit::Multireddit.
+      # @param subreddits [Array] An array of subreddit names or RedditKit::Subreddit objects.
+      # @param visibility [public, private] An array of subreddit names to be added to the multireddit.
+      def create_or_update_multireddit(method, multireddit, subreddits = [], visibility = 'private')
+        multireddit_name = extract_string(multireddit, :name)
+        multireddit_path = path_for_multireddit @username, multireddit_name
+        path = "api/multi#{multireddit_path}"
+
+        subreddit_hashes = subreddits.collect do |subreddit|
+          { :name => extract_string(subreddit, :name) }
+        end
+
+        model = { :visibility => visibility, :subreddits => subreddit_hashes }
+        parameters = { :multipath => multireddit_path, :model => model.to_json }
+        
+        request(method, path, parameters, connection)
+      end
+
+    end
+  end
+end

data/lib/redditkit/client/private_messages.rb

@@ -0,0 +1,74 @@
+require 'redditkit/private_message'
+
+module RedditKit
+  class Client
+    
+    # Methods for retrieving and sending private messages.
+    module PrivateMessages
+
+      # Gets the current user's private messages or comment replies.
+      #
+      # @option options [inbox, unread, sent, messages, mentions, moderator, comments, selfreply] :category The category from which to return messages.
+      # @option options [1..100] :limit The number of messages to return.
+      # @option options [String] :before Only return subreddits before this id. 
+      # @option options [String] :after Only return subreddits after this id.
+      # @option options [Boolean] :mark Whether to mark requested messages as read.
+      # @return [RedditKit::PaginatedResponse]
+      def messages(options = {})
+        category = options[:category] || 'inbox'
+        path = "message/#{category}.json"
+        options.delete :category
+
+        objects_from_response(:get, path, options)
+      end
+
+      # Send a message to another reddit user.
+      #
+      # @param message [String] The text of the message.
+      # @param recipient [String, RedditKit::User] The recipient of the message.
+      # @option options [String] :subject The subject of the message.
+      # @option options [String] :captcha_identifier A CAPTCHA identifier to send with the message, if the current user is required to fill one out.
+      # @option options [String] :captcha_value The value of the CAPTCHA to send with the message, if the current user is required to fill one out.
+      def send_message(message, recipient, options = {})
+        username = extract_string(recipient, :username)
+        parameters = { :to => username, :text => message, :subject => options[:subject], :captcha => options[:captcha_value], :iden => options[:captcha_identifier] }
+
+        post('api/compose', parameters)
+      end
+
+      # Marks a message as read.
+      #
+      # @param message [String, RedditKit::PrivateMessage] A private message's full name, or a RedditKit::PrivateMessage.
+      def mark_as_read(message)
+        parameters = { :id => extract_full_name(message) }
+        post('api/read_message', parameters)
+      end
+
+      # Marks a message as unread.
+      #
+      # @param message [String, RedditKit::PrivateMessage] A private message's full name, or a RedditKit::PrivateMessage.
+      def mark_as_unread(message)
+        parameters = { :id => extract_full_name(message) }
+        post('api/unread_message', parameters)
+      end
+
+      # Blocks the author of a private message or comment.
+      # Users cannot be blocked based on username as reddit only allows you to block those who have harassed you (thus leaving a message in your inbox).
+      #
+      # @param message [String, RedditKit::PrivateMessage] A private message's full name, or a RedditKit::PrivateMessage. 
+      def block_author_of_message(message)
+        parameters = { :id => extract_full_name(message) }
+        post('api/block', parameters)
+      end
+
+      # Unblocks a user.
+      #
+      # @param user [String, RedditKit::User] A user's username, or a RedditKit::User. 
+      def unblock(user)
+        enemy_name = extract_string(user, :username)
+        friend_request 'unfriend', :container => current_user.full_name, :name => enemy_name, :type => :enemy
+      end
+
+    end
+  end
+end