redditkit 1.0.0

data/lib/redditkit/client/search.rb

@@ -0,0 +1,25 @@
+module RedditKit
+  class Client
+
+    # Methods for searching reddit's links.
+    module Search
+
+      # Search for links.
+      #
+      # @param query [String] The search query.
+      # @option options [true, false] :restrict_to_subreddit Whether to search only in a specified subreddit. 
+      # @option options [String, RedditKit::Subreddit] :subreddit The optional subreddit to search. 
+      # @option options [1..100] limit The number of links to return.
+      # @option options [String] before Only return links before this full name. 
+      # @option options [String] after Only return links after this full name.
+      # @return [RedditKit::PaginatedResponse]
+      def search(query, options = {})
+        path = "%s/search.json" % ('r/' + options[:subreddit] if options[:subreddit])
+        parameters = { :q => query, :restrict_sr => options[:restrict_to_subreddit], :limit => options[:limit] }
+        
+        objects_from_response(:get, path, parameters)
+      end
+
+    end
+  end
+end

data/lib/redditkit/client/subreddits.rb

@@ -0,0 +1,120 @@
+require 'redditkit/subreddit'
+
+module RedditKit
+  class Client
+
+    # Methods for interacting with subreddits.
+    module Subreddits
+
+      # Gets subreddits from a specified category.
+      #
+      # @option options [new, popular, banned] category The category of subreddits. Defaults to popular.
+      # @option options [1..100] limit The number of subreddits to return.
+      # @option options [String] before Only return subreddits before this id. 
+      # @option options [String] after Only return subreddits after this id.
+      # @return [RedditKit::PaginatedResponse]
+      def subreddits(options = {})
+        category = options[:category] or 'popular'
+        path = "reddits/#{category}.json"
+        options.delete :category
+
+        objects_from_response(:get, path, options)
+      end
+
+      # Gets the current user's subscribed subreddits. 
+      #
+      # @option options [subscriber, contributor, moderator] category The category from which to return subreddits. Defaults to subscriber.
+      # @option options [1..100] limit The number of subreddits to return.
+      # @option options [String] before Only return subreddits before this id. 
+      # @option options [String] after Only return subreddits after this id.
+      # @return [RedditKit::PaginatedResponse]
+      def subscribed_subreddits(options = {})
+        category = options[:category] or 'subscriber'
+        path = "subreddits/mine/#{category}.json"
+        options.delete :category
+
+        objects_from_response(:get, path, options)
+      end
+
+      # Gets a subreddit object.
+      #
+      # @param subreddit_name [String] A subreddit's display name.
+      # @return [RedditKit::Subreddit]
+      # @example client.subreddit "programming"
+      def subreddit(subreddit_name)
+        object_from_response(:get, "r/#{subreddit_name}/about.json", nil)
+      end
+
+      # Subscribes to a subreddit.
+      #
+      # @param subreddit [String, RedditKit::Subreddit] A subreddit's full name, or a RedditKit::Subreddit.
+      def subscribe(subreddit)
+        full_name = extract_full_name subreddit
+        parameters = { :action => 'sub', :sr => full_name }
+
+        post("api/subscribe", parameters)
+      end
+
+      # Unsubscribes from a subreddit.
+      #
+      # @param subreddit [String, RedditKit::Subreddit] A subreddit's full name, or a RedditKit::Subreddit.
+      def unsubscribe(subreddit)
+        full_name = extract_full_name subreddit
+        parameters = { :action => 'unsub', :sr => full_name }
+
+        post("api/subscribe", parameters)
+      end
+
+      # Gets a random subreddit.
+      #
+      # @return [RedditKit::Subreddit]
+      def random_subreddit
+        response = get('r/random', nil)
+        headers = response[:response_headers]
+        location = headers[:location]
+
+        subreddit_name = location[/\/r\/(.*)\//, 1]
+        subreddit subreddit_name
+      end
+
+      # Searches for subreddits with a specific name.
+      #
+      # @param name [String] The name to search for.
+      # @return [RedditKit::PaginatedResponse]
+      def search_subreddits_by_name(name)
+        parameters = { :q => name }
+        objects_from_response :get, 'subreddits/search.json', parameters
+      end
+
+      # Gets an array of subreddit names by topic.
+      #
+      # @param topic [String] The desired topic.
+      # @return [Array<String>] An array of subreddit names.
+      # @example RedditKit.subreddits_by_topic 'programming'
+      def subreddits_by_topic(topic)
+        parameters = { :query => topic }
+
+        response = get('api/subreddits_by_topic.json', parameters)
+        body =  response[:body]
+
+        body.collect { |subreddit| subreddit[:name] }
+      end
+
+      # Gets an array of recommended subreddits.
+      #
+      # @param subreddits [Array<String>] An array of subreddit names.
+      # @return [Array<String>] An array of recommended subreddit names.
+      # @example RedditKit.recommended_subreddits %w(ruby programming)
+      def recommended_subreddits(subreddits)
+        names = subreddits.join(',')
+        parameters = { :srnames => names }
+
+        response = get('api/subreddit_recommendations.json', parameters)
+        body =  response[:body]
+
+        body.collect { |subreddit| subreddit[:sr_name] }
+      end
+
+    end
+  end
+end

data/lib/redditkit/client/users.rb

@@ -0,0 +1,109 @@
+require 'redditkit/user'
+
+module RedditKit
+  class Client
+
+    # Methods for interacting with reddit users.
+    module Users
+
+      # Gets a user object.
+      #
+      # @param username [String] A reddit account's username. Gets the current user if this is nil.
+      # @return [RedditKit::User]
+      # @example current_user = client.user
+      # @example user = client.user 'amberlynns' 
+      def user(username = nil)
+        if username
+          object_from_response(:get, "user/#{username}/about.json", nil)
+        else
+          object_from_response(:get, "api/me.json", nil)
+        end
+      end
+
+      # Gets links and comments for the current user. 
+      #
+      # @option options [overview, comments, submitted, liked, disliked] :category The category from which to return links and comments. Defaults to overview.
+      # @option options [1..100] :limit The number of links and comments to return.
+      # @option options [String] :before Only return links and comments before this id. 
+      # @option options [String] :after Only return links and comments after this id.
+      # @return [RedditKit::PaginatedResponse]
+      def my_content(options = {})
+        category = options[:category] || :overview
+        path = "user/#{@username}/#{category}.json"
+        options.delete :category
+
+        objects_from_response(:get, path, options)
+      end
+
+      # Gets links and comments for a user. 
+      #
+      # @option options [overview, comments, submitted, liked, disliked] :category The category from which to return links and comments. Defaults to overview.
+      # @option options [1..100] :limit The number of links and comments to return.
+      # @option options [String] :before Only return links and comments before this id. 
+      # @option options [String] :after Only return links and comments after this id.
+      # @return [RedditKit::PaginatedResponse]
+      # @note Public access to the liked and disliked categories is disabled by default, so this will return an empty array for most users.
+      def user_content(user, options = {})
+        username = user
+
+        path = "user/#{username}/%s.json" % (options[:category] if options[:category])
+        options.delete :category
+
+        objects_from_response(:get, path, options)
+      end
+
+      # Gets the current user's friends.
+      #
+      # @return [Array<OpenStruct>]
+      def friends
+        response = request(:get, 'prefs/friends.json', nil, https_connection)
+        body = response[:body]
+        friends = body[0][:data][:children]
+
+        friends.collect { |friend| OpenStruct.new(friend) }
+      end
+
+      # Adds a user to the current user's friend list.
+      #
+      # @param user [String, RedditKit::User] A user's username, or a RedditKit::User.
+      def friend(user)
+        friend_name = extract_string(user, :username)
+        friend_request 'friend', :container => current_user.full_name, :name => friend_name, :type => :friend
+      end
+
+      # Removes a user from the current user's friend list. 
+      #
+      # @param user [String, RedditKit::User] A user's ID, or a RedditKit::User. 
+      def unfriend(user)
+        friend_name = extract_string(user, :username)
+        friend_request 'unfriend', :container => current_user.full_name, :name => friend_name, :type => :friend
+      end
+
+      # Checks whether a specific username is available. 
+      #
+      # @param username [String] A username for which to check availability.
+      # @return [Boolean]
+      # @example puts "Username is available" if client.username_available? 'some_username' 
+      def username_available?(username)
+        response = get('api/username_available.json', :user => username)
+        available = response[:body]
+        
+        available == 'true'
+      end
+
+      # Registers a new reddit account. 
+      #
+      # @option options [String] username The username to register.
+      # @option options [String] password The password for the account.
+      # @option options [String] email The optional email address for the account.
+      # @option options [String] captcha_identifier The identifier for the CAPTCHA challenge solved by the user.
+      # @option options [String] captcha The user's response to the CAPTCHA challenge.
+      # @option options [Boolean] remember Whether to keep the user's session cookie beyond the current session.
+      def register(username, password, options = {})
+        parameters = { :user => username, :passwd => password, :passwd2 => password, :captcha => options[:captcha], :iden => options[:captcha_identifier] }
+        post('api/register', parameters)
+      end
+
+    end
+  end
+end

data/lib/redditkit/client/utilities.rb

@@ -0,0 +1,137 @@
+require 'redditkit/paginated_response'
+
+module RedditKit
+  class Client
+
+    # Methods for streamlining requests to reddit's servers.
+    module Utilities
+
+      private
+
+      # Return an id from a string or a RedditKit::Thing object.
+      #
+      # @param object [String, RedditKit::Thing] A string or object.
+      # @return [String]
+      def extract_id(object)
+        extract_string object, :id
+      end
+
+      # Return a full name from a string or a RedditKit::Thing object.
+      #
+      # @param object [String, RedditKit::Thing] A string or object.
+      # @return [String]
+      def extract_full_name(object)
+        extract_string object, :full_name
+      end
+
+      def extract_string(object, attribute_name)
+        case object
+        when ::String
+          object
+        else
+          object.send attribute_name if object.respond_to? attribute_name
+        end
+      end
+
+      # Return the class of an object from a response.
+      #
+      # @param response [Faraday::Response] A response.
+      # @return [Class]
+      def object_class_from_response(response)
+        kind = object_kind_from_response(response)
+        object_class_from_kind(kind)
+      end
+
+      # Return the class of an object of a given kind.
+      #
+      # @param kind [String] The object's kind.
+      # @return [Class]
+      def object_class_from_kind(kind)
+        case kind
+        when "t1"
+          RedditKit::Comment
+        when "t2"
+          RedditKit::User
+        when "t3"
+          RedditKit::Link
+        when "t4"
+          RedditKit::PrivateMessage
+        when "t5"
+          RedditKit::Subreddit
+        when "LabeledMulti"
+          RedditKit::Multireddit
+        when "LabeledMultiDescription"
+          RedditKit::MultiredditDescription
+        when "modaction"
+          RedditKit::ModeratorAction
+        end
+      end
+
+      def object_kind_from_response(response)
+        response[:kind]
+      end
+
+      def object_from_response(request_type, path, parameters = {})
+        response = send(request_type.to_sym, path, parameters)
+        body = response[:body]
+
+        object_class = object_class_from_response(body)
+        object_class.new(body) if object_class
+      end
+
+      def objects_from_response(request_type, path, parameters = {})
+        response = send(request_type.to_sym, path, parameters)
+        body = response[:body]
+
+        if body.is_a?(Hash) and body[:kind] == 'Listing'
+          data = body[:data]
+          results = objects_from_listing(body)
+
+          RedditKit::PaginatedResponse.new(data[:before], data[:after], results)
+        elsif body.is_a?(Array)
+          objects_from_array body
+        elsif body.is_a?(Hash)
+          objects_from_array body[:data]
+        end
+      end
+
+      def objects_from_listing(listing)
+        children = listing[:data][:children]
+        objects_from_array children
+      end
+
+      def objects_from_array(array)
+        array.map do |thing|
+          object_class = object_class_from_response(thing)
+          object_class.new(thing) if object_class
+        end
+      end
+
+      def comments_from_response(request_type, path, parameters = {})
+        response = send(request_type.to_sym, path, parameters)
+        body = response[:body]
+        comments_listing = body.last
+
+        objects_from_listing(comments_listing)
+      end
+
+      def path_for_multireddit(username, multireddit_name)
+         "/user/#{username}/m/#{multireddit_name}"
+      end
+
+      # Performs a friend or unfriend request.
+      #
+      # @param type [friend, unfriend] The type of request.
+      # @param options Any parameters to send with the request.
+      def friend_request(type, options)
+        if options[:subreddit]
+          options[:r] = options[:subreddit]
+          options.delete :subreddit
+        end
+
+        post("api/#{type}", options)
+      end
+
+    end
+  end
+end

data/lib/redditkit/client/voting.rb

@@ -0,0 +1,41 @@
+module RedditKit
+  class Client
+
+    # Methods for voting on links and comments.
+    module Voting
+
+      # Upvotes a link or comment.
+      #
+      # @param link_or_comment [String, RedditKit::Comment, RedditKit::Link] The link or comment to upvote. 
+      def upvote(link_or_comment)
+        vote link_or_comment, 1
+      end
+
+      # Downvotes a link or comment. 
+      #
+      # @param link_or_comment [String, RedditKit::Comment, RedditKit::Link] The link or comment to downvote. 
+      def downvote(link_or_comment)
+        vote link_or_comment, -1
+      end
+
+      # Withdraws a vote on a link or comment.
+      #
+      # @param link_or_comment [String, RedditKit::Comment, RedditKit::Link] The link or comment from which to withdraw the vote. 
+      def withdraw_vote(link_or_comment)
+        vote link_or_comment, 0
+      end
+
+      # Votes on a link or comment.
+      #
+      # @param link_or_comment [String, RedditKit::Comment, RedditKit::Link] The link or comment from which to withdraw the vote. 
+      # @param direction [-1, 0, 1] Downvote, no vote, and upvote respectively.
+      def vote(link_or_comment, direction)
+        full_name = extract_full_name(link_or_comment)
+        parameters = { :id => full_name, :dir => direction, :api_type => 'json' }
+
+        post('api/vote', parameters)
+      end
+
+    end
+  end
+end

data/lib/redditkit/client/wiki.rb

@@ -0,0 +1,83 @@
+module RedditKit
+  class Client
+
+    # Methods for interacting with a subreddit's wiki.
+    module Wiki
+
+      # Adds a user as an approved editor of a wiki page.
+      #
+      # @param subreddit [String, RedditKit::Subreddit] A subreddit's display name, or a RedditKit::Subreddit.
+      # @param user [String, RedditKit::User] A user's full name, or a RedditKit::User.
+      # @param page [String] page The name of an existing wiki page.
+      def add_wiki_editor(subreddit, user, page)
+        toggle_wiki_editor(subreddit, user, page, 'add')
+      end
+
+      # Removes a user from being an approved editor of a wiki page.
+      #
+      # @param subreddit [String, RedditKit::Subreddit] A subreddit's display name, or a RedditKit::Subreddit.
+      # @param user [String, RedditKit::User] A user's full name, or a RedditKit::User.
+      # @param page [String] page The name of an existing wiki page.
+      def remove_wiki_editor(subreddit, user, page)
+        toggle_wiki_editor(subreddit, user, page, 'del')
+      end
+
+      # Edits a wiki page.
+      #
+      # @option options [String, RedditKit::Subreddit] subreddit A subreddit's display name, or a RedditKit::Subreddit.
+      # @option options [String] page The name of an existing wiki page.
+      # @option options [String] content The contents of the edit.
+      # @option options [String] reason The reason for the edit.
+      # @option options [String] previous_revision The starting revision for this edit.
+      def edit_wiki_page(options)
+        subreddit_name = extract_string(options[:subreddit], :display_name)
+        parameters = { :page => options[:page], :previous => options[:previous_revision], :content => options[:content], :reason => options[:reason] }
+
+        post("r/#{subreddit_name}/api/wiki/edit", parameters)
+      end
+
+      # Hides a wiki page revision. If the revision is already hidden, this will unhide it.
+      #
+      # @option options [String, RedditKit::Subreddit] subreddit A subreddit's display name, or a RedditKit::Subreddit.
+      # @option options [String] page The name of an existing wiki page.
+      # @option options [String] revision The revision to hide.
+      # @return [Boolean] True if the revision is now hidden, false if it is not hidden.
+      def hide_wiki_revision(options)
+        subreddit_name = extract_string(options[:subreddit], :display_name)
+        options.delete :subreddit
+
+        response = post("r/#{subreddit_name}/api/wiki/hide", options)
+        response[:body][:status]
+      end
+
+      # Reverts to a specific wiki page revision.
+      #
+      # @option options [String, RedditKit::Subreddit] subreddit A subreddit's display name, or a RedditKit::Subreddit.
+      # @option options [String] page The name of an existing wiki page.
+      # @option options [String] revision The revision to revert to.
+      def revert_to_revision(options)
+        subreddit_name = extract_string(options[:subreddit], :display_name)
+        options.delete :subreddit
+
+        post("r/#{subreddit_name}/api/wiki/revert", options)
+      end
+
+      private
+
+      # Adds or removes a user as an approved editor of a wiki page.
+      #
+      # @param subreddit [String, RedditKit::Subreddit] A subreddit's display name, or a RedditKit::Subreddit.
+      # @param user [String, RedditKit::User] A user's full name, or a RedditKit::User.
+      # @param page [String] page The name of an existing wiki page.
+      # @param status [add, del] Whether to add or delete a user.
+      def toggle_wiki_editor(subreddit, user, page, status)
+        subreddit_name = extract_string(subreddit, :display_name)
+        username = extract_string(user, :username)
+        parameters = { :page => page, :username => username }
+
+        post("r/#{subreddit_name}/api/wiki/alloweditor/#{status}", parameters)
+      end
+
+    end
+  end
+end