snoo 0.0.1

data/lib/snoo/links_comments.rb

@@ -0,0 +1,151 @@
+module Snoo
+  # Methods for interacting with links and comments, such as leaving a comment, voting, etc
+  #
+  # @author (see Snoo)
+  module LinksComments
+
+    # Posts a comment to the site
+    #
+    # @param text [String] The comment text, formatted as markdown
+    # @param id [String] The parent object id. Should be a comment or link
+    # @return (see #clear_sessions)
+    def comment text, id
+      logged_in?
+      post('/api/comment', body: { text: text, thing_id: id, uh: @modhash})
+    end
+
+    # Deletes a thing from the site
+    #
+    # @param id [String] The thing to target.
+    # @return (see #clear_sessions)
+    def delete id
+      logged_in?
+      post('/api/del', body: { id: id, uh: @modhash })
+    end
+
+    # Edits a thing.
+    # Can be a self post body, or a comment
+    #
+    # @param (see #comment)
+    # @return (see #clear_sessions)
+    def edit text, id
+      logged_in?
+      post('/api/editusertext', body: {text: text, thing_id: id, uh: @modhash})
+    end
+
+    # Hides a thing
+    #
+    # @param (see #delete)
+    # @return (see #clear_sessions)
+    def hide id
+      logged_in?
+      post('/api/hide', body: {id: id, uh: @modhash})
+    end
+
+    # Get a listing of things which have the provided URL.
+    # You can use a plain url, or a reddit link id to get reposts of said link
+    # @note Using {Listings#search} is probably better for url lookups
+    #
+    # @param opts [Hash] An options hash
+    # @option opts [String] :id The id of a reddit thing to look up. Specify either this or a url, not both
+    # @option opts [String] :url The url to search for matching things. Specify either this or an id, not both
+    # @option opts [Fixnum] :limit The number of things to return. Go too high and the API will ignore you
+    # @return (see #clear_sessions)
+    def info opts = {}
+      raise ArgumentError, 'url or id, not both' if opts[:id] && opts[:url]
+      query = { limit: 100 }
+      query.merge! opts
+      get('/api/info.json', query: query)
+    end
+
+    # Marks a post NSFW. Currently, this only works on links
+    #
+    # @param (see #delete)
+    # @return (see #clear_sessions)
+    def mark_nsfw id
+      logged_in?
+      post('/api/marknsfw', body: {id: id, uh: @modhash})
+    end
+
+    # Reports a comment or link
+    #
+    # @param (see #delete)
+    # @reutrn (see #comment)
+    def report id
+      logged_in?
+      post('/api/report', body: {id: id, uh: @modhash})
+    end
+
+    # Saves a link
+    #
+    # @param (see #delete)
+    # @return (see #clear_sessions)
+    def save id
+      logged_in?
+      post('/api/save', body: { id: id, uh: @modhash})
+    end
+
+    # Submit a link or self post
+    #
+    # @param title [String] Title of the post
+    # @param subreddit [String] The subreddit in which we are posting
+    # @param (see #info)
+    # @option opts [String] :url The url for the post. If this is specified, it will not be a self post, and `text` will be ignored
+    # @option opts [String] :text The self-post text. Can be formatted in markdown
+    # @return (see #clear_sessions)
+    def submit title, subreddit, opts = {}
+      logged_in?
+      raise ArgumentError, 'url or text, not both' if opts[:url] && opts[:text]
+      post = {
+        title: title,
+        sr: subreddit,
+        uh: @modhash,
+        kind: (opts[:url] ? "link" : "self")
+      }
+      post.merge! opts
+      post('/api/submit', body: post)
+    end
+
+    # Unhide a thing
+    #
+    # @param (see #delete)
+    # @return (see #clear_sessions)
+    def unhide id
+      logged_in?
+      post('/api/unhide', body: {id: id, uh: @modhash})
+    end
+
+    # Un-mark NSFW a thing.
+    #
+    # @param (see #delete)
+    # @return (see #clear_sessions)
+    def unmark_nsfw id
+      logged_in?
+      post('/api/unmarknsfw', body: {id: id, uh: @modhash})
+    end
+
+    # Vote on a comment or link
+    #
+    # @param direction [-1, 0, 1] The direction to vote in. -1 is a downvote, 1 is an upvote, 0 cancels any vote
+    # @param id [String] The thing to target.
+    # @return (see #clear_sessions)
+    def vote direction, id
+      logged_in?
+      raise ArgumentError, "direction needs to be one of -1, 0, or 1 (was #{direction}" unless (-1..1).include?(direction)
+      post('/api/vote', body: {id: id, dir: direction, uh: @modhash})
+    end
+
+    # Upvote
+    # An alias for `vote 1, id`
+    #
+
+    # Downvote
+    # An alias for `vote -1, id`
+    #
+
+    # Sidevote (clear your vote)
+    # An alias for `vote 0, id`
+    #
+
+  end
+end

data/lib/snoo/listings.rb

@@ -0,0 +1,89 @@
+module Snoo
+  # Methods for getting thing listings. Comments, links, etc
+  #
+  # @author (see Snoo)
+  module Listings
+
+    # Get a comment listing from the site
+    #
+    # @param link_id [String] The link id of the comment thread. Must always be present
+    # @param (see LinksComments#info)
+    # @option opts [String] :comment_id The parent comment of a thread.
+    # @option opts [Fixnum] :context The context of the thread, that is, how far above the `comment_id` to return
+    # @option opts [Fixnum] :limit (100) The total number of comments to return. If you have gold this can include the whole thread, but is buggy. Recommend no more than 1000
+    # @option opts [Fixnum] :depth How deep to render a comment thread.
+    # @option opts [old, new, hot, top, controversial, best] :sort The sort used.
+    # @return (see #clear_sessions)
+    def get_comments link_id, opts = {}
+      sorts = %w{old new hot top controversial best}
+      raise ArgumentError, "sort cannot be #{sort}" unless sorts.include?(opts[:sort]) or opts[:sort].nil?
+      query = { limit: 100 }
+      query.merge! opts
+      url = "/comments/%s%s.json" % [link_id, ('/' + opts[:comment_id] if opts[:comment_id])]
+      get(url, query: query)
+    end
+
+    # Gets a listing of links from reddit.
+    #
+    # @param (see LinksComments#info)
+    # @option opts [String] :subreddit The subreddit targeted. Can be psuedo-subreddits like `all` or `mod`. If blank, the front page
+    # @option opts [new, controversial, top] :page The page to view.
+    # @option opts [new, rising] :sort The sorting method. Only relevant on the `new` page
+    # @option opts [hour, day, week, month, year] :t The timeframe. Only relevant on some pages, such as `top`. Leave empty for all time
+    # @option opts [1..100] :limit The number of things to return.
+    # @option opts [String] :after Get things *after* this thing id
+    # @option opts [String] :before Get things *before* this thing id
+    # @return (see #clear_sessions)
+    def get_listing opts = {}
+      pages = %w{new controversial top}
+      sorts = %w{new rising}
+      times = %w{hour day week month year}
+      # Invalid Page
+      raise ArgumentError, "page must be #{pages * ', '}, is #{opts[:page]}" unless pages.include?(opts[:page]) or opts[:page].nil?
+      # Invalid Sort
+      raise ArgumentError, "sort must be one of #{sorts * ', '}, is #{opts[:sort]}" unless sorts.include?(opts[:sort]) or opts[:sort].nil?
+      # Sort on useless page
+      raise ArgumentError, "sort can only be used on page = 'new'" if opts[:page] != 'new' && opts[:sort]
+      # Invalid time
+      raise ArgumentError, "time can only be one of #{times * ', '}, is #{opts[:time]}" unless times.include?(opts[:time]) or opts[:time].nil?
+      # Invalid limit
+      raise ArgumentError, "limit cannot be outside 1..100, is #{opts[:limit]}" unless (1..100).include?(opts[:limit]) or opts[:limit].nil?
+
+      # Build the basic url
+      url = "%s/%s.json" % [('/r/' + opts[:subreddit] if opts[:subreddit] ), (opts[:page] if opts[:page])]
+      # Delete subreddit and page from the hash, they dont belong in the query
+      [:subreddit, :page].each {|k| opts.delete k}
+      query = opts
+      # Make the request
+      get(url, query: query)
+    end
+
+    # Search reddit
+    #
+    # @param query [String] The search query.
+    # @param (see LinksComments#info)
+    # @option opts [true, false] :restrict_sr Restrict to the calling subreddit
+    # @option opts [String] :subreddit The calling subreddit.
+    # @option opts [1..100] :limit The amount of results to return
+    # @option opts [String] :before Return things *before* this id
+    # @option opts [String] :after Return things *after* this id
+    # @option opts [relevance, new, top] :sort The sorting of the results.
+    # @option opts [cloudsearch, lucene] :syntax The search syntax.
+    # @return (see #clear_sessions)
+    def search query, opts = {}
+      raise ArgumentError, 'restrict_subreddit needs to be boolean' unless [true, false].include?(opts[:restrict_sr]) or opts[:restrict_sr].nil?
+      raise ArgumentError, "limit needs to be 1..100, is #{opts[:limit]}" unless (1..100).include?(opts[:limit]) or opts[:limit].nil?
+      raise ArgumentError, "sort needs to be one of relevance, new, top, is #{opts[:sort]}" unless %w{relevance new top}.include?(opts[:sort]) or opts[:sort].nil?
+      raise ArgumentError, "syntax needs to be one of cloudsearch, lucene; is #{opts[:syntax]}" if %w{cloudsearch lucene}.include?(opts[:syntax])
+
+      # This supports searches with and without a subreddit
+      url = "%s/search.json" % (opts[:subreddit] if opts[:subreddit])
+
+      # Construct the query
+      httpquery = {q: query}
+      httpquery.merge! opts
+
+      get(url, query: httpquery)
+    end
+  end
+end

data/lib/snoo/moderation.rb

@@ -0,0 +1,61 @@
+module Snoo
+  # Methods for moderating on reddit, including tasks such as removing, approving, and distinguishing
+  #
+  # @author (see Snoo)
+  module Moderation
+
+    # Approve a thing
+    #
+    # @param id [String] Thing targeted
+    # @return (see #clear_sessions)
+    def approve id
+      logged_in?
+      post('/api/approve', body: {id: id, uh: @modhash})
+    end
+
+    # Distinguish a thing
+    #
+    # @param (see #approve)
+    # @param how [yes, no, admin, special] Determines how to distinguish something. Only works for the permissions you have.
+    # @return (see #clear_sessions)
+    def distinguish id, how
+      logged_in?
+      hows = %w{yes no admin special}
+      raise ArgumentError, "how should be one of #{hows * ', '}, is #{how}" if hows.include?(how)
+      post('/api/distinguish', body: {id: id, how: how, uh: @modhash})
+    end
+
+    # Removes you from a subreddits list of contributors
+    # @note (see #clear_sessions)
+    #
+    # @param id [String] The subreddit id
+    # @return (see #clear_sessions)
+    def leave_contributor id
+      logged_in?
+      post('/api/leavecontributor', body: {id: id, uh: @modhash})
+    end
+
+    # Removes you from a subreddits moderators
+    # @note (see #clear_sessions)
+    #
+    # @param (see #leave_contributor)
+    # @return (see #clear_sessions)
+    def leave_moderator id
+      logged_in?
+      post('/api/leavemoderator', body: {id: id, uh: @modhash})
+    end
+
+    # Removes a thing
+    #
+    # @param (see #approve)
+    # @param spam [true, false] Mark this removal as a spam removal (and train the spamfilter)
+    # @return (see #clear_sessions)
+    def remove id, spam
+      logged_in?
+      spams = [true, false]
+      raise ArgumentError, "spam should be boolean, is #{spam}" unless spams.include?(spam)
+      post('/api/remove', body: {id: id, spam: spam, uh: @modhash})
+    end
+
+  end
+end

data/lib/snoo/pms.rb

@@ -0,0 +1,69 @@
+module Snoo
+  # Methods for interacting with private messages
+  #
+  # @author (see Snoo)
+  module PM
+
+    # Block a user from sending you messages
+    #
+    # @param id [String] the user id.
+    # @return (see #clear_sessions)
+    def block_pm id
+      logged_in?
+      post('/api/block', body: {id: id, uh: @modhash})
+    end
+
+    # Send a private message
+    # To reply to PM, use {LinksComments#comment}, with the PM id as the link id
+    #
+    # @param to [String] The username you are sending to
+    # @param subject [String] The subject of the message
+    # @param text [String] The message body
+    # @return (see #clear_sessions)
+    def send_pm to, subject, text
+      logged_in?
+      post('/api/compose.json', body: {to: to, subject: subject, text: text, uh: @modhash})
+    end
+
+    # Mark a PM as read
+    #
+    # @param id [String] The message id
+    # @return (see #clear_sessions)
+    def mark_read id
+      logged_in?
+      post('/api/read_message', body: {id: id, uh: @modhash})
+    end
+
+    # Mark a PM as unread
+    #
+    # @param (see #mark_read)
+    # @return (see #clear_sessions)
+    def mark_unread id
+      logged_in?
+      post('/api/unread_message', body: {id: id, uh: @modhash})
+    end
+
+    # Gets a listing of PMs
+    #
+    # @param where [inbox, unread, sent] Where to get messages from
+    # @param (see LinksComments#info)
+    # @option opts [true, false] :mark (false) Mark the messages requested as read?
+    # @option opts [1..100] :limit The total number of messages to get
+    # @option opts [String] :before Get all comments *before* this id
+    # @option opts [String] :after Get all comments *after* this
+    # @return (see #clear_sessions)
+    def get_messages where = "inbox", opts = {},
+      bools = [true, false]
+      wheres = %w{inbox unread sent}
+      raise ArgumentError, "where must be #{wheres * ', '}, is #{where}" unless wheres.include?(where)
+      raise ArgumentError, "mark must be boolean, is #{opts[:mark]}" unless bools.include?(opts[:mark]) or opts[:mark].nil?
+      raise ArgumentError, "limit must be 1..100, is #{opts[:limit]}" unless (1..100).include?(opts[:limit]) or opts[:limit].nil?
+
+      query = {
+        mark: false
+      }
+      query.merge! opts
+      get("/message/#{where}.json", query: query)
+    end
+  end
+end

data/lib/snoo/subreddits.rb

@@ -0,0 +1,242 @@
+module Snoo
+  # Methods for administering a subreddit, as well as looking up subreddits (subreddit search)
+  #
+  # @author (see Snoo)
+  module Subreddit
+
+    # Deletes the header image of a subreddit
+    #
+    # @param subreddit [String] The subreddit targeted
+    # @return (see #clear_sessions)
+    def delete_header subreddit
+      logged_in?
+      post('/api/delete_sr_header', body: {r: subreddit, uh: @modhash})
+    end
+
+    # Deletes an image from a subreddit. This is for css, not removing posts
+    #
+    # @param (see #delete_header)
+    # @param image_name [String] the image to delete from the subreddit. Can be obtained via {#get_stylesheet}
+    # @return (see #clear_sessions)
+    def delete_image subreddit, image_name
+      logged_in?
+      post('/api/delete_sr_image', body: {r: subreddit, img_name: image_name, uh: @modhash})
+    end
+
+    # @todo test if every param is actually required
+    # Sets subreddit settings.
+    #
+    # @param (see #delete_header)
+    # @param (see LinksComments#info)
+    # @option opts [String] :title The subreddit's title
+    # @option opts [String] :public_description The subreddit's public description
+    # @option opts [String] :description The subreddit's sidebar
+    # @option opts [String] :lang (en) The default language. ISO language code
+    # @option opts [public, private, restricted] :type (public) The subreddits type
+    # @option opts [any, link, self] :link_type (any) The type of posts allowed on this subreddit
+    # @option opts [true, false] :allow_top (true) Allow this subreddit to appear on the front page
+    # @option opts [true, false] :show_media (true) show thumbnails and media embeds
+    # @option opts [String] :header-title The header mouse-over text
+    # @option opts [true, false] :over_18 (false) If the subreddit requires over 18 access
+    # @return (see #clear_sessions)
+    def subreddit_settings subreddit, opts = {}
+      logged_in?
+      bool = [true, false]
+      raise ArgumentError, "type must be one of public, private, restricted, is #{opts[:type]}" unless %w{public private restricted}.include?(opts[:type]) or opts[:type].nil?
+      raise ArgumentError, "post_type must be one of any, link, self; is #{opts[:link_type]}" unless %w{any link self}.include?(opts[:link_type]) or opts[:link_type].nil?
+      raise ArgumentError, "allow_frontpage must be boolean" unless bool.include?(opts[:allow_top]) or opts[:allow_top].nil?
+      raise ArgumentError, "show_media must be boolean" unless bool.include?(opts[:show_media]) or opts[:show_media].nil?
+      raise ArgumentError, "adult must be boolean" unless bool.include?(opts[:over_18]) or opts[:over_18].nil?
+      params = {
+        type: 'public',
+        link_type: 'any',
+        lang: 'en',
+        r: subreddit,
+        uh: @modhash,
+        allow_top: true,
+        show_media: true,
+        over_18: false,
+      }
+      params.merge! opts
+      post('/api/site_admin', body: params)
+    end
+
+    # Set the subreddit stylesheet
+    #
+    # @param stylesheet [String] The stylesheet for the subreddit. Overwrites the current one
+    # @param (see #delete_header)
+    # @return (see #clear_sessions)
+    def set_stylesheet stylesheet, subreddit
+      logged_in?
+      post('/api/subreddit_stylesheet', body: {op: "save", stylesheet_contents: stylesheet, uh: @modhash})
+    end
+
+    # Subscribe to a subreddit
+    #
+    # @param (see #delete_header)
+    # @param action [sub, unsub] Subscribe or unsubscribe
+    # @return (see #clear_sessions)
+    def subscribe subreddit, action = "sub"
+      logged_in?
+      raise ArgumentError, "action must be one of sub, unsub; is #{action}" unless %w{sub unsub}.include?(action)
+      post('/api/subscribe', body: {action: action, sr: subreddit, uh: @modhash})
+    end
+
+    # Unsubscribe from a subreddit
+    # This is an alias for `subscribe "unsub"`
+    #
+    # @param (see #delete_header)
+    # @return (see #clear_sessions)
+    def unsubscribe subreddit
+      subscribe("unsub", subreddit)
+    end
+
+
+    # Get subreddit info
+    #
+    # @param (see #delete_header)
+    # @return (see #clear_sessions)
+    def subreddit_info subreddit
+      get("/r/#{subreddit}/about.json")
+    end
+
+    # Get subreddit stylesheet and images
+    #
+    # @param (see #delete_header)
+    # @return (see #clear_sessions)
+    def get_stylesheet subreddit
+      logged_in?
+      get("/r/#{subreddit}/about/stylesheet.json")
+    end
+
+    # Get subreddits I have
+    #
+    # @param (see LinksComments#info)
+    # @option opts [subscriber, contributor, moderator] :condition The permission level to return subreddits from
+    # @option opts [1..100] :limit The number of results to return
+    # @option opts [String] :after Return subreddits *after* this id
+    # @option opts [String] :before Return subreddits *before* this id
+    # @return (see #clear_sessions)
+    def my_reddits opts = {}
+      logged_in?
+      raise ArgumentError, "condition must be one of subscriber, contributor, moderator; is #{opts[:condition]}" unless %w{subscriber contributor moderator}.include?(opts[:condition]) or opts[:condition].nil?
+      raise ArgumentError, "limit must be within 1..100; is #{opts[:limit]}" unless (1..100).include?(opts[:limit]) or opts[:limit].nil?
+      url = "/reddits/mine/%s.json" % (opts[:condition] if opts[:condition])
+      opts.delete! :condition
+      query = ops
+      get(url, query: query)
+    end
+
+    # Get a list of subreddits
+    #
+    # @param (see LinksComments#info)
+    # @option opts [popular, new, banned] :condition The type of subreddits to return
+    # @option opts [1..100] :limit The number of results to return
+    # @option opts [String] :after Return subreddits *after* this id.
+    # @option opts [String] :before Return subreddits *before* this id.
+    # @return (see #clear_sessions)
+    def get_reddits opts = {}
+      raise ArgumentError, "condition must be one of popular, new, banned; is #{opts[:condition]}" unless %w{popular new banned}.include?(opts[:condition]) or opts[:condition].nil?
+      raise ArgumentError, "limit must be within 1..100; is #{opts[:limit]}" unless (1..100).include?(opts[:limit]) or opts[:limit].nil?
+
+      url = "/reddits/%s.json" % (opts[:condition] if opts[:condition])
+      opts.delete! :condition
+      query = opts
+
+      get(url, query: query)
+    end
+
+    # Search subreddits
+    #
+    # @param q [String] The search query
+    # @param (see LinksComments#info)
+    # @option opts [1..100] :limit The number of results to return
+    # @option opts [String] :after Return subreddits *after* this id.
+    # @option opts [String] :before Return subreddits *before* this id.
+    # @return (see #clear_sessions)
+    def search_reddits q, opts = {}
+      raise ArgumentError, "limit must be within 1..100; is #{opts[:limit]}" unless (1..100).include?(opts[:limit]) or opts[:limit].nil?
+
+      query = {q: q}
+      query.merge! opts
+      get('/reddits/search.json', query: query)
+    end
+
+    # Add a moderator to the subreddit
+    #
+    # @param container [String] The subreddit id. Must be a subreddit id (begins with t5_)
+    # @param user [String] The user
+    # @param (see #delete_header)
+    # @return (see #clear_sessions)
+    def add_moderator container, user, subreddit
+      friend_wrapper api_container = container, api_name = user, api_subreddit = subreddit, api_type = "moderator"
+    end
+
+    # Add a contributor to the subreddit
+    #
+    # @param (see #add_moderator)
+    # @return (see #clear_sessions)
+    def add_contributor container, user, subreddit
+      friend_wrapper api_container = container, api_name = user, api_subreddit = subreddit, api_type = "contributor"
+    end
+
+    # Ban a user from a subreddit
+    #
+    # @param (see #add_moderator)
+    # @return (see #clear_sessions)
+    def ban_user container, user, subreddit
+      friend_wrapper api_container = container, api_name = user, api_subreddit = subreddit, api_type ="banned"
+    end
+
+    # Remove a moderator from a subreddit
+    #
+    # @param id [String] The user id
+    # @param (see #add_moderator)
+    # @return (see #clear_sessions)
+    def remove_moderator id, container, user, subreddit
+      unfriend_wrapper api_id = id, api_container = container, api_name = user, api_subreddit = subreddit, api_type = "moderator"
+    end
+
+    # Remove a contributor from a subreddit
+    #
+    # @param (see #remove_moderator)
+    # @return (see #clear_sessions)
+    def remove_contributor id, container, user, subreddit
+      unfriend_wrapper api_id = id, api_container = container, api_name = user, api_subreddit = subreddit, api_type = "contributor"
+    end
+
+    # Unban a user from a subreddit
+    #
+    # @param (see #remove_moderator)
+    # @return (see #clear_sessions)
+    def unban_user id, container, user, subreddit
+      unfriend_wrapper api_id = id, api_container = container, api_name = user, api_subreddit = subreddit, api_type = "banned"
+    end
+
+    # List moderators of a subreddit
+    #
+    # @param (see #delete_header)
+    # @return (see #clear_sessions)
+    def get_moderators subreddit
+      get("/r/#{subreddit}/about/moderators.json")
+    end
+
+    # List contributors of a subreddit
+    #
+    # @param (see #delete_header)
+    # @param (see #clear_sessions)
+    def get_contributors subreddit
+      logged_in?
+      get("/r/#{subreddit}/about/contributors.json")
+    end
+
+    # List banned users of a subreddit
+    #
+    # @param (see #delete_header)
+    # @param (see #clear_sessions)
+    def get_banned_users subreddit
+      logged_in?
+      get("/r/#{subreddit}/about/banned.json")
+    end
+  end
+end