redditkit 1.0.0

data/lib/redditkit/client/apps.rb

@@ -0,0 +1,63 @@
+module RedditKit
+  class Client
+
+    # Methods for operating on apps in the current user's account.
+    module Apps
+      
+      # Create or update an app.
+      #
+      # @param name [String] The app's name.
+      # @option options [String] description The app's description.
+      # @option options [String] about_url The app's URL.
+      # @option options [String] redirect_url The app's redirect URL.
+      # @option options [String] app_identifier The identifier of the app, if you are updating an existing one.
+      def create_app(name, options = {})
+        description = options[:description]
+        about_url = options[:about_url]
+        redirect_url = options[:redirect_url]
+        app_identifier = options[:app_identifier]
+        parameters = { :client_id => app_identifier, :name => name, :description => description, :about_url => about_url, :redirect_uri => redirect_url }
+
+        post('api/updateapp', parameters)
+      end
+      alias update_app create_app
+      
+      # Delete an app.
+      #
+      # @param app_identifier [String] The identifier of the app.
+      def delete_app(app_identifier)
+        post('api/deleteapp', { :client_id => app_identifier })
+      end
+
+      # Revoke an app.
+      #
+      # @param app_identifier [String] The identifier of the app.
+      def revoke_app(app_identifier)
+        post('api/revokeapp', { :client_id => app_identifier })
+      end
+
+      # Add a user as a developer of an app.
+      # 
+      # @param user [String, RedditKit::User] The username of the user to add, or a RedditKit::User.
+      # @param app_identifier [String] The identifier of the app.
+      def add_developer(user, app_identifier)
+        username = extract_string user, :username
+        parameters = { :name => username, :client_id => app_identifier }
+
+        post('api/adddeveloper', parameters)
+      end
+
+      # Remove an app's developer.
+      # 
+      # @param user [String, RedditKit::User] The username of the user to add, or a RedditKit::User.
+      # @param app_identifier [String] The identifier of the app.
+      def remove_developer(user, app_identifier)
+        username = extract_string user, :username
+        parameters = { :name => username, :client_id => app_identifier }
+
+        post('api/removedeveloper', parameters)
+      end
+
+    end
+  end
+end

data/lib/redditkit/client/captcha.rb

@@ -0,0 +1,36 @@
+module RedditKit
+  class Client
+
+    # Methods for retrieving and submitting CAPTCHAs.
+    module Captcha
+
+      # Whether the current user will need to answer a CAPTCHA for methods which may require one.
+      #
+      # @return [Boolean]
+      def needs_captcha?
+        response = get('api/needs_captcha.json', nil)
+        needs_captcha = response[:body]
+
+        needs_captcha == 'true'
+      end
+
+      # Returns a new CATPCHA identifier.
+      #
+      # @return [String] The CAPTCHA identifier.
+      def new_captcha_identifier
+        response = post('api/new_captcha', { :api_type => :json })
+        data = response[:body][:json][:data]
+
+        data[:iden]
+      end
+
+      # Returns the URL for a CAPTCHA image with a given identifier.
+      #
+      # @return [String]
+      def captcha_url(captcha_identifier)
+        "http://reddit.com/captcha/#{captcha_identifier}.png"
+      end
+
+    end
+  end
+end

data/lib/redditkit/client/comments.rb

@@ -0,0 +1,54 @@
+require 'redditkit/comment'
+
+module RedditKit
+  class Client
+
+    # Methods for interacting with comment threads.
+    module Comments
+
+      # Get a comment object from its full name.
+      #
+      # @param comment_full_name [String] The full name of the comment.
+      # @return [RedditKit::Comment]
+      # @note This method does not include any replies to the comment.
+      def comment(comment_full_name)
+        comments = objects_from_response(:get, 'api/info.json', { :id => comment_full_name })
+        comments.first
+      end
+
+      # Get comments on a link. 
+      #
+      # @param link [String, RedditKit::Link] The identifier of the link, or a RedditKit::Link.
+      # @option options [Integer] :limit The number of comments to return.
+      # @return [Array<RedditKit::Comment>]
+      def comments(link, options = {})
+        return nil unless link
+
+        link_id = extract_id link
+        path = "comments/#{link_id}.json"
+
+        comments_from_response(:get, path, options)
+      end
+
+      # Submit a comment on a link or comment.
+      #
+      # @param link_or_comment [String, RedditKit::Comment, RedditKit::Link] The object to comment on.
+      # @param text [String] The text of the comment, formatted as Markdown.
+      # @return [RedditKit::Comment] The new comment object.
+      def submit_comment(link_or_comment, text)
+        object_full_name = extract_full_name link_or_comment
+        parameters = { :text => text, :thing_id => object_full_name, :api_type => :json }
+
+        response = post('/api/comment', parameters)
+        response_data = response[:body][:json][:data]
+
+        full_comment_data = response_data[:things].first
+        comment_data = full_comment_data[:data]
+        comment_full_name = comment_data[:id]
+        
+        comment comment_full_name
+      end
+
+    end
+  end
+end

data/lib/redditkit/client/flair.rb

@@ -0,0 +1,148 @@
+require 'ostruct'
+
+module RedditKit
+  class Client
+
+    # Methods for interacting with flair in subreddits.
+    module Flair
+
+      # Lists users and their flair in a subreddit. 
+      #
+      # @param subreddit [String, RedditKit::Subreddit] A subreddit's name, or a RedditKit::Subreddit.
+      # @option options [1..1000] :limit The number of items to return.
+      # @option options [String] :before Only return objects before this id. 
+      # @option options [String] :after Only return objects after this id.
+      def flair_list(subreddit, options = {})
+        subreddit_name = extract_string(subreddit, :display_name)
+        list = get("/r/#{subreddit_name}/api/flairlist.json", options)
+        users = list[:body][:users]
+
+        users.collect { |user| OpenStruct.new(user) }
+      end
+      
+      # Creates a flair template in a subreddit.
+      #
+      # @param subreddit [String, RedditKit::Subreddit] A subreddit's name, or a RedditKit::Subreddit.
+      # @param type [user, link] The template's type. Defaults to user.
+      # @option options [String] text The text value for the template.
+      # @option options [String] css_class The CSS class for the template.
+      # @option options [Boolean] user_editable Whether the template should be editable by users.
+      def create_flair_template(subreddit, type, options = {})
+        subreddit_name = extract_string(subreddit, :display_name)
+        flair_type = (type.to_s == 'link') ? 'LINK_FLAIR' : 'USER_FLAIR'
+
+        parameters = { :r => subreddit_name, :flair_type => flair_type, :text => options[:text], :css_class => options[:css_class], :api_type => :json }
+        parameters[:text_editable] = 'on' if options[:user_editable]
+
+        post('api/flairtemplate', parameters)
+      end
+
+      # Deletes a flair template.
+      #
+      # @param subreddit [String, RedditKit::Subreddit] A subreddit's name, or a RedditKit::Subreddit.
+      # @param template_identifier [String] The template's identifier.
+      def delete_flair_template(subreddit, template_identifier)
+        subreddit_name = extract_string(subreddit, :display_name)
+        parameters = { :flair_template_id => template_identifier, :r => subreddit_name }
+
+        post('api/deleteflairtemplate', parameters)
+      end
+
+      # Toggles flair for a subreddit. 
+      #
+      # @param subreddit [String, RedditKit::Subreddit] A subreddit's name, or a RedditKit::Subreddit.
+      # @param flair_enabled [Boolean] Whether to enable flair for the subreddit. 
+      def toggle_flair(subreddit, flair_enabled)
+        post('api/setflairenabled', { :r => subreddit, :flair_enabled => flair_enabled }) 
+      end
+
+      # Sets flair on a link or user.
+      #
+      # @option options [String, RedditKit::Subreddit] subreddit A subreddit's name, or a RedditKit::Subreddit.
+      # @option options [String] text The text value for the template.
+      # @option options [String] css_class The CSS class for the template.
+      # @option options [String, RedditKit::Link] link A link's full name, or a RedditKit::Link.
+      # @option options [String, RedditKit::User] user A user's username, or a RedditKit::User.
+      # @note Raises RedditKit::BadClassName if any CSS classes contain invalid characters, or RedditKit::TooManyClassNames if there are too many.
+      def set_flair(options)
+        subreddit_name = extract_string(options[:subreddit], :display_name)
+        link_full_name = extract_full_name options[:link]
+        username = extract_string options[:user], :username
+
+        parameters = { :r => subreddit_name, :text => options[:text], :css_class => options[:css_class], :name => username, :link => link_full_name }
+
+        post('api/flair', parameters)
+      end
+
+      # Sets a subreddit's flair using a string formatted as CSV.
+      #
+      # @param subreddit [String, RedditKit::Subreddit] A subreddit's name, or a RedditKit::Subreddit.
+      # @param csv_string [String] A string in CSV format.
+      # @note Each line in the string should be in the format 'user,flair-text,css_class'.
+      def set_flair_with_csv(subreddit, csv_string)
+        subreddit_name = extract_string(subreddit, :display_name)
+        parameters = { :r => subreddit_name, :flair_csv => csv_string }
+
+        post('api/flaircsv', parameters)
+      end
+
+      # Clears a user's flair.
+      #
+      # @param subreddit [String, RedditKit::Subreddit] A subreddit's name, or a RedditKit::Subreddit.
+      # @param user [String, RedditKit::User] A subreddit's name, or a RedditKit::Subreddit.
+      def delete_user_flair(subreddit, user)
+        subreddit_name = extract_string(subreddit, :display_name)
+        username = extract_string(user, :username)
+        parameters = { :name => username, :r => subreddit_name }
+
+        post('api/deleteflair', parameters)
+      end
+
+      # Clears all flair templates of a certain type.
+      #
+      # @option options [String, RedditKit::Subreddit] subreddit A subreddit's name, or a RedditKit::Subreddit.
+      # @option options [user, link] type The template's type. Defaults to user.
+      def clear_flair_templates(options)
+        subreddit_name = extract_string(options[:subreddit], :display_name)
+        flair_type = 'USER_FLAIR'
+        flair_type = 'LINK_FLAIR' if options[:type].to_s == 'link'
+
+        parameters = { :r => subreddit_name, :flair_type => flair_type, :text => options[:text], :css_class => options[:css_class] }
+
+        post('api/clearflairtemplates', parameters)
+      end
+
+      # Applys a flair template to a link or user.
+      #
+      # @option options [String, RedditKit::Subreddit] subreddit A subreddit's name, or a RedditKit::Subreddit.
+      # @option options [String] template_id The template's identifier.
+      # @option options [String, RedditKit::Link] link A link's full name, or a RedditKit::Link.
+      # @option options [String, RedditKit::User] user A user's username, or a RedditKit::User.
+      def apply_flair_template(options)
+        subreddit_name = extract_string(options[:subreddit], :display_name)
+        link_full_name = extract_full_name options[:link]
+        username = extract_string options[:user], :username
+
+        parameters = { :flair_template_id => options[:template_id], :r => subreddit_name, :name => username, :link => link_full_name }
+
+        post('api/selectflair', parameters)
+      end
+
+      # Sets flair options for a subreddit.
+      #
+      # @param subreddit [String, RedditKit::Subreddit] A subreddit's name, or a RedditKit::Subreddit.
+      # @option options [Boolean] flair_enabled Whether to enable flair for the subreddit.
+      # @option options [left, right] flair_position The position of user flair. 
+      # @option options [left, right] link_flair_position The position of link flair.
+      # @option options [Boolean] flair_self_assign_enabled Whether users may assign their own flair.
+      # @option options [Boolean] link_flair_self_assign_enabled Whether users may assign their own link flair.
+      def set_flair_options(subreddit, options = {})
+        subreddit_name = extract_string(subreddit, :display_name)
+        options.merge!({ :r => subreddit_name, :uh => @modhash })
+
+        post('api/flairconfig', options) 
+      end
+
+    end
+  end
+end

data/lib/redditkit/client/links.rb

@@ -0,0 +1,134 @@
+require 'redditkit/link'
+
+module RedditKit
+  class Client
+
+    # Methods for retrieving, submitting and interacting with links.
+    module Links
+      
+      # Gets the links currently on the front page.
+      #
+      # @option options [hot, new, rising, controversial, top] :category The category from which to retrieve links.  
+      # @option options [hour, day, week, month, year, all] :time The time from which to retrieve links. Defaults to all time.
+      # @option options [1..100] :limit The number of links to return.
+      # @option options [String] :before Only return links before this identifier. 
+      # @option options [String] :after Only return links after this identifier.
+      # @return [RedditKit::PaginatedResponse]
+      def front_page(options = {})
+        links nil, options
+      end
+
+      # Gets an array of links from a specific subreddit.
+      #
+      # @param subreddit [String, RedditKit::Subreddit] The display name of the subreddit, or a RedditKit::Subreddit.
+      # @option options [hot, new, rising, controversial, top] :category The category from which to retrieve links.  
+      # @option options [hour, day, week, month, year, all] :time The time from which to retrieve links. Defaults to all time.
+      # @option options [1..100] :limit The number of links to return.
+      # @option options [String] :before Only return links before this identifier. 
+      # @option options [String] :after Only return links after this identifier.
+      # @return [RedditKit::PaginatedResponse]
+      def links(subreddit, options = {})
+        subreddit_name = extract_string(subreddit, :display_name) if subreddit
+        category = options[:category] || :hot
+
+        path = "%s/#{category.to_s}.json" % ('r/' + subreddit_name if subreddit_name)
+
+        options[:t] = options[:time] if options[:time]
+        options.delete :category
+        options.delete :time
+
+        objects_from_response(:get, path, options)
+      end
+
+      # Gets a link object from its full name.
+      #
+      # @param link_full_name [String] The full name of the link.
+      # @return [RedditKit::Link]
+      # @note This method will return nil if there is not a user currently signed in.
+      def link(link_full_name)
+        links = objects_from_response(:get, 'api/info.json', { :id => link_full_name })
+        links.first
+      end
+
+      # Gets links with a specific domain. 
+      #
+      # @param domain [String] The domain for which to get links.
+      # @option options [hour, day, week, month, year] :time The time from which to retrieve links. Defaults to all time.
+      # @option options [1..100] :limit The number of links to return.
+      # @option options [String] :before Only return links before this identifier. 
+      # @option options [String] :after Only return links after this identifier.
+      # @return [RedditKit::PaginatedResponse]
+      # @example links = RedditKit.links_with_domain "github.com"
+      def links_with_domain(domain, options = {})
+        parameters = { :url => domain, :t => options[:time] }
+        options.merge! parameters
+        options.delete :t
+
+        objects_from_response(:get, 'api/info.json', options)
+      end
+
+      # Submits a link or self post to reddit. 
+      #
+      # @param title [String] The title of the post.
+      # @param subreddit [String, RedditKit::Subreddit] A subreddit's display name, or a RedditKit::Subreddit. 
+      # @option options [String] :url The URL for the post. Note that if this value is present, :text will be ignored.
+      # @option options [String] :text The text value for the post, as Markdown.
+      # @option options [String] :captcha_identifier An identifier for a CAPTCHA, if the current user is required to fill one out.
+      # @option options [String] :captcha_value The value for the CAPTCHA with the given identifier, as filled out by the user.
+      def submit(title, subreddit, options = {})
+        subreddit_name = extract_string subreddit, :display_name
+        parameters = { :title => title, :sr => subreddit_name, :iden => options[:captcha_identifier], :captcha => options[:captcha_value] }
+        
+        if options[:url]
+          parameters[:url] = options[:url]
+        else
+          parameters[:text] = options[:text]
+        end
+
+        post('api/submit', parameters)
+      end
+
+      # Marks a link as not safe for work.
+      #
+      # @param link [String, RedditKit::Link] A link's full name, or a RedditKit::Link. 
+      def mark_nsfw(link)
+        post('api/marknsfw', { :id => extract_full_name(link) })
+      end
+
+      # Marks a link as safe for work.
+      #
+      # @param link [String, RedditKit::Subreddit] A link's full name, or a RedditKit::Link. 
+      def mark_sfw(link)
+        post('api/unmarknsfw', { :id => extract_full_name(link) })
+      end
+      alias unmark_nsfw mark_sfw
+
+      # Hides a link.
+      #
+      # @param link [String, RedditKit::Link] A link's full name, or a RedditKit::Link. 
+      def hide(link)
+        post('api/hide', { :id => extract_full_name(link) })
+      end
+
+      # Unhides a link.
+      #
+      # @param link [String, RedditKit::Link] A link's full name, or a RedditKit::Link. 
+      def unhide(link)
+        post('api/unhide', { :id => extract_full_name(link) })
+      end
+
+      # Gets a random link.
+      #
+      # @return [RedditKit::Link]
+      def random_link
+        response = get('/random', nil)
+        headers = response[:response_headers]
+        location = headers[:location]
+
+        link_id = location[/\/tb\/(.*)/, 1]
+        link "t3_#{link_id}"
+      end
+
+    end
+  end
+end

data/lib/redditkit/client/miscellaneous.rb

@@ -0,0 +1,50 @@
+module RedditKit
+  class Client
+
+    # Methods which don't belong in any clear categroy, such as editing and deleting items on reddit.
+    module Miscellaneous
+
+      # Edit the text or a self post or comment.
+      #
+      # @param object [String, RedditKit::Comment, RedditKit::Link] A link or comment's full name, a RedditKit::Link, or a RedditKit::Subreddit. 
+      # @option options [String] text The new text for the link or comment.
+      def edit(object, options)
+        parameters = { :text => options[:text], :thing_id => extract_full_name(object) }
+        post('/api/editusertext', parameters)
+      end
+
+      # Deletes a link or comment.
+      #
+      # @param object [String, RedditKit::Comment, RedditKit::Link] A link or comment's full name, a RedditKit::Link, or a RedditKit::Subreddit. 
+      def delete(object)
+        full_name = extract_full_name object
+        post('api/del', { :id => full_name })
+      end
+
+      # Saves a link or comment.
+      #
+      # @param object [String, RedditKit::Link, RedditKit::Subreddit] A link or comment's full name, a RedditKit::Link, or a RedditKit::Subreddit. 
+      def save(object)
+        full_name = extract_full_name object
+        post('api/save', { :id => full_name })
+      end
+
+      # Unsaves a link or comment.
+      #
+      # @param object [String, RedditKit::Link, RedditKit::Subreddit] A link or comment's full name, a RedditKit::Link, or a RedditKit::Subreddit. 
+      def unsave(object)
+        full_name = extract_full_name object
+        post('api/unsave', { :id => full_name })
+      end
+
+      # Reports a link or comment. The reddit API will also hide the link or comment.
+      #
+      # @param object [String, RedditKit::Link, RedditKit::Comment] A link or comment's full name, a RedditKit::Link, or a RedditKit::Subreddit. 
+      def report(object)
+        full_name = extract_full_name object
+        post('api/report', { :id => full_name })
+      end
+      
+    end
+  end
+end