snoo 0.0.1

data/.gitignore

@@ -0,0 +1,19 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+
+.DS_Store

data/.yardopts

@@ -0,0 +1 @@
+--markup markdown

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in snoo.gemspec
+gemspec

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2012 Jeff Sandberg
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,86 @@
+# Snoo
+
+Snoo is a *simple* wrapper for the reddit.com api. Its designed to provide an interface as close to the official api as possible, while freeing you from the problems of dealing with json, webserver requests, and session/cookie management.
+
+Unlike other API wrappers, this one doesn't make use of complicated objects or classes, once you instantiate it once, you are good to go.
+
+Since it's designed to be simple, it leaves things like rate limiting up to you. Please follow the [reddit api rules](https://github.com/reddit/reddit/wiki/API) and only send one request every 2 seconds (you can use `sleep 2` between requests).
+
+Also, if you build programs with it, please change the user agent to your specific use case.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'snoo'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install snoo
+
+## Usage
+
+Here's a simple script that sends a private message:
+
+```ruby
+require 'snoo'
+
+# Create a new instance of the client
+reddit = Snoo::Client.new
+
+# Log into reddit
+reddit.log_in 'Username', 'Password'
+
+# Send a private message to me (Paradox!)
+reddit.send_pm 'Paradox', 'Snoo rubygem rocks!', "Hey Paradox, I'm trying your Snoo rubygem out and it rocks. Thanks for providing such an awesome thing!"
+
+# Log back out of reddit
+reddit.log_out
+```
+
+See the [docs](http://rubydoc.info/github/paradox460/snoo/) for more info.
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Added some feature'`)
+4. Test your changes (via `rspec`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request
+
+## Testing
+
+1. Edit `spec/auth.rb` and fill out all the globals with a test user account and test reddit
+2. Run rspec
+
+## License
+
+```
+Copyright (c) 2012 Jeff Sandberg
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+```

data/Rakefile

@@ -0,0 +1,8 @@
+#!/usr/bin/env rake
+require "bundler/gem_tasks"
+
+desc 'Uninstall snoo, build it, and install it locally'
+task :cycle do
+  sh 'gem uninstall snoo'
+  Rake::Task["install"].execute
+end

data/lib/snoo.rb

@@ -0,0 +1,38 @@
+require 'httparty'
+
+%w{version exceptions utilities account flair links_comments listings moderation pms subreddits users}.each do |local|
+  require "snoo/#{local}"
+end
+# Snoo reddit API wrapper
+#
+# @author Jeff Sandberg <paradox460@gmail.com>
+module Snoo
+  # Snoo reddit API wrapper
+  #
+  # @author (see Snoo)
+  class Client
+    include HTTParty
+    [Account, Flair, LinksComments, Listings, Moderation, PM, Utilities, User, Subreddit].each do |inc|
+      include inc
+    end
+
+    attr_reader(:modhash, :username, :userid, :cookie)
+
+
+    # Creates a new instance of Snoo.
+    #
+    # Please change the useragent if you write your own program.
+    #
+    # @param url [String] url The base url of reddit.
+    # @param useragent [String] The User-Agent this bot will use.
+    def initialize( url = "http://www.reddit.com", useragent = "Snoo ruby reddit api wrapper v#{VERSION}" )
+      @baseurl = url
+      self.class.base_uri url
+      @headers = {'User-Agent' => useragent }
+      self.class.headers @headers
+      @cookies = nil
+      @modhash = nil
+    end
+  end
+end
+

data/lib/snoo/account.rb

@@ -0,0 +1,92 @@
+module Snoo
+  # Account related methods, such as logging in, deleting the current user, changing passwords, etc
+  #
+  # @author (see Snoo)
+  module Account
+
+    # Log into a reddit account. You need to do this to use any restricted or write APIs
+    #
+    # @param username [String] The reddit account's username you wish to log in as
+    # @param password [String] The password of the reddit account
+    # @return [HTTParty::Response] The httparty request object.
+    def log_in username, password
+      login = post("/api/login", :body => {user: username, passwd: password, api_type: 'json'})
+      errors = login['json']['errors']
+      raise errors[0][1] unless errors.size == 0
+      cookies login.headers['set-cookie']
+      @modhash = login['json']['data']['modhash']
+      @username = username
+      @userid = 't2_' + get('/api/me.json')['data']['id']
+      return login
+    end
+
+    # Logs out of a reddit account. This is usually uneeded, you can just log_in as a new account to replace the current one.
+    # This just nils the cookies and modhash
+    def log_out
+      cookies nil
+      @modhash = nil
+      @userid = nil
+      @username = nil
+    end
+
+    # Invalidates all other reddit session cookies, and updates the current one.
+    # This will log out all other reddit clients, as described in the [reddit API](http://www.reddit.com/dev/api#POST_api_clear_sessions)
+    #
+    # @note This method provides no verification or checking, so use with care
+    # @param password [String] The password of the reddit account
+    # @return (see #log_in)
+    def clear_sessions password
+      logged_in?
+      clear = post('/api/clear_sessions', body: { curpass: password, dest: @baseurl, uh: @modhash })
+      cookies clear.headers['set-cookie']
+      return clear
+    end
+
+    # Deletes the current user. This requires a password for security reasons.
+    #
+    # @note (see #clear_sessions)
+    # @param password [String] The password for the current user
+    # @param reason [String] The reason the current user account is being deleted.
+    # @return (see #clear_sessions)
+    def delete_user password, reason = "deleted by script command"
+      logged_in?
+      delete = post('/api/delete_user', body: {
+        confirm: true,
+        delete_message: reason,
+        passwd: password,
+        uh: @modhash,
+        user: @username
+        })
+      return delete
+    end
+
+    # Gets info about the currently logged in user.
+    # @return (see #clear_sessions)
+    def me
+      logged_in?
+      get("/api/me.json")
+    end
+
+    # Changes the current user's password/email.
+    #
+    # @note (see #clear_sessions)
+    # @param currentPass [String] The current password
+    # @param newPass [String] The new password
+    # @param email [String] The email address you would like to update to. Optional
+    # @return (see #clear_sessions)
+    def update_user currentPass, newPass, email = nil
+      logged_in?
+      params = {
+        curpass: currentPass,
+        newpass: newPass,
+        uh: @modhash,
+        verify: true,
+        verpass: newPass
+        }
+      params[:email] = email if email
+      update = post('/api/update', body: params )
+      cookies update.headers['set-cookie']
+      return update
+    end
+  end
+end

data/lib/snoo/exceptions.rb

@@ -0,0 +1,13 @@
+module Snoo
+  # Not Authenticated exception. Thrown whenever a user is not logged into reddit and they should be
+  #
+  # @author (see Snoo)
+  class NotAuthenticated < StandardError
+  end
+
+  # Thrown whenever the webserver returns anyting but 200
+  #
+  # @author (see Snoo)
+  class WebserverError < StandardError
+  end
+end

data/lib/snoo/flair.rb

@@ -0,0 +1,184 @@
+module Snoo
+  # Flair related methods.
+  # These are used for interacting with flair in reddit. Things like giving flair, setting templates, and whatnot.
+  #
+  # @author (see Snoo)
+  module Flair
+
+    # Clear all the flair templates of a particular type
+    #
+    # @param type [USER_FLAIR, LINK_FLAIR] The type of template to clear.
+    # @param subreddit [String] The subreddit targeted.
+    # @return (see #clear_sessions)
+    def clear_flair_templates type, subreddit
+      logged_in?
+      tests = ['USER_FLAIR', 'LINK_FLAIR']
+      raise ArgumentError, 'type needs to be either USER_FLAIR or LINK_FLAIR' unless tests.include?(type)
+      post('/api/clearflairtemplates', body: { flair_type: type, r: subreddit, uh: @modhash})
+    end
+
+    # Deletes a user's flair
+    #
+    # @param user [String] The user who'se flair is affected
+    # @param subreddit [String] The subreddit targeted.
+    # @return (see #clear_sessions)
+    def delete_user_flair user, subreddit
+      logged_in?
+      post('/api/deleteflair', body: {name: user, r: subreddit, uh: @modhash})
+    end
+
+    # Deletes a flair template by ID.
+    #
+    # @param id [String] The flair template's ID to delete. Get this from {#flair_template_list}
+    # @param subreddit [String] The subreddit targeted.
+    def delete_flair_template id, subreddit
+      logged_in?
+      post('/api/deleteflairtemplate', body: {flair_template_id: id, r: subreddit, uh: @modhash})
+    end
+
+    # Sets flair on a thing, currently supports links and users. Must specify **either** link *or* user, **not** both
+    #
+    # @param subreddit [String] The subreddit targeted.
+    # @param opts [Hash] An options hash.
+    # @option opts [String] :css_class The class(es) applied to the flair. Whitespace separated
+    # @option opts [String] :text The flair text
+    # @option opts [String] :name The user who we are flairing. This requires a username.r
+    # @option opts [String] :link The thing id of the link (if a link). Begins with `t3_`
+    # @return (see #clear_sessions)
+    def flair subreddit, opts = {}
+      logged_in?
+      raise ArgumentError, "link or name, not both" if opts[:link] && opts[:name]
+      params = {
+        r: subreddit,
+        uh: @modhash,
+      }
+      params.merge! opts
+
+      post('/api/flair', body: params)
+    end
+
+    # Configures flair options for a subreddit. All options are required
+    #
+    # @param enabled [true, false] Flair enabled?
+    # @param position [left, right] Position of user flair.
+    # @param self_assign [true, false] Allow users to assign their own flair from templates
+    # @param link_position [none, left, right] The position of link flair. Set to `none` to disable
+    # @param link_assign [true, false] Allow a submitter to assign their own link flair
+    # @param subreddit [String] The subreddit targeted.
+    # @return (see #clear_sessions)
+    def flair_config enabled, position, self_assign, link_position, link_assign, subreddit
+      logged_in?
+      # Test the params
+      tests = [true, false]
+      raise "parameter error" unless tests.include?(enabled) && tests.include?(self_assign) && tests.include?(link_assign)
+      tests << "none"
+      raise "parameter error" unless tests.include?(link_position)
+
+      post('/api/flairconfig', body: {
+        flair_enabled: enabled,
+        flair_position: position,
+        flair_self_assign_enabled: self_assign,
+        link_flair_position: link_position,
+        link_flair_self_assign_enabled: link_assign,
+        uh: @modhash,
+        r: subreddit
+        })
+    end
+
+    # Post flair in a CSV file to reddit
+    #
+    # @param csv [String] A string, in CSV format, of `user,flair-text,css_class` per line, with no more than 100 flairs, and **no header line**.
+    # @param subreddit [String] The subreddit targeted.
+    # @return [HTTParty::Response] The request object. Note that this request object contains a json confirming the status of each line of the CSV
+    def flair_csv csv, subreddit
+      logged_in?
+      post('/api/flaircsv.json', body: {flair_csv: csv, r: subreddit, uh: @modhash})
+    end
+
+    # Downloads flair from the subreddit
+    # This is limited to 1000 per request, use before/after to get "pages"
+    #
+    # @param (see #flair)
+    # @option opts [Fixnum] :limit (1000) The amount of flairs to get. Must be between 1 and 1000
+    # @option opts [String] :before Return entries just before this user id
+    # @option opts [String] :after Return entries just after this user id
+    # @return (see #clear_sessions)
+    def get_flair_list subreddit, opts = {}
+      logged_in?
+      raise ArgumentError, 'limit is too high/low' unless (1..1000).include?(opts[:limit]) or opts[:limit].nil?
+      query = {
+        limit: 1000,
+        uh: @modhash
+      }
+      query.merge! opts
+      get("/r/#{subreddit}/api/flairlist.json", query: query)
+    end
+
+    # Create or edit a flair template.
+    #
+    # @param css_class [String] The list of css classes applied to this style, space separated
+    # @param type [USER_FLAIR, LINK_FLAIR] The type of flair template.
+    # @param text [String] The flair template's text.
+    # @param user_editable [true, false] If the templ
+    # @param subreddit [String] The subreddit targeted.ate allows users to specify their own text
+    # @param template_id [String] The flair template ID, for editing. Get this from {#flair_template_list}
+    # @return (see #clear_sessions)
+    def flair_template css_class, type, text, user_editable, subreddit, template_id = nil
+      logged_in?
+      test = ['USER_FLAIR', 'LINK_FLAIR']
+      raise ArgumentError, 'type is either USER_FLAIR or LINK_FLAIR' unless test.include?(type)
+      test = [true, false]
+      raise ArgumentError, 'user_editable needs to be true or false' unless test.include?(user_editable)
+
+      params = {
+        css_class: css_class,
+        flair_type: type,
+        text: text,
+        text_editable: user_editable,
+        uh: @modhash,
+        r: subreddit
+      }
+      params[:flair_template_id] = template_id if template_id
+      post('/api/flairtemplate', body: params)
+    end
+
+    # Select a flair template and apply it to a user or link
+    #
+    # @param template_id [String] The template id to apply. Get this from {#flair_template_list}
+    # @param text [String] The flair text
+    # @param subreddit [String] The subreddit targeted.
+    # @param (see LinksComments#info)
+    # @option opts [String] :link The link id to apply to
+    # @option opts [String] :user The username to apply flair to
+    # @return (see #clear_sessions)
+    def select_flair_template template_id, text, subreddit, opts = {}
+      logged_in?
+      raise ArgumentError, 'link or user, not both' if link && user
+      params = {
+        flair_template_id: template_id,
+        text: text,
+        uh: @modhash,
+        r: subreddit
+      }
+      params.merge! opts
+      post('/api/selectflair', body: params)
+    end
+
+    # Toggle flair on and off for a subreddit
+    #
+    # @param enabled [true, false] Enable/disable flair
+    # @param subreddit [String] The subreddit targeted.
+    # @return (see #clear_sessions)
+    def flair_toggle enabled, subreddit
+      logged_in?
+      test = [true, false]
+      raise ArgumentError, 'enabled must be boolean' unless test.include?(enabled)
+      post('/api/setflairenabled', body: {flair_enabled: enabled, uh: @modhash, r: subreddit})
+    end
+
+    # @todo implement this.
+    #   it will probably require nokogiri and some trickery.
+    def flair_template_list
+    end
+  end
+end