redditkit 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: bf49ee7e4888671f3860d38d4a794b6594207827
+  data.tar.gz: 9495006c5cc268dd6df62780c97017521239c17f
+SHA512:
+  metadata.gz: d9e8b304a65560e2df483a9b0b55bfb8811647691e61afdb71ed454e7653fee11e8db600e28c23d6f944ff634e30d9d32a422994abe9fc96de9d8e143d9d59d6
+  data.tar.gz: b5fbc3f4729e5ed803d029d206369ff80132d697f73cd099fdb56fab15aaad9b0a049b84c7e548f0ebe29e57f5f791e57616c0b8661399cec172cea4f45c296c

data/LICENSE.md

@@ -0,0 +1,22 @@
+Copyright (c) 2013 Sam Symons
+
+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,155 @@
+# RedditKit.rb
+
+RedditKit.rb is a [reddit API](http://www.reddit.com/dev/api) wrapper, written in Ruby.
+
+[![Build Status](https://travis-ci.org/samsymons/RedditKit.rb.png?branch=master)][travis]
+[![Code Climate](https://codeclimate.com/github/samsymons/RedditKit.rb.png)][codeclimate]
+[![Coverage Status](https://coveralls.io/repos/samsymons/RedditKit.rb/badge.png?branch=master)][coveralls]
+
+[travis]: http://travis-ci.org/samsymons/RedditKit.rb
+[codeclimate]: https://codeclimate.com/github/samsymons/RedditKit.rb
+[coveralls]: https://coveralls.io/r/samsymons/RedditKit.rb
+
+## Installation
+
+Add this to your Gemfile:
+
+    gem 'redditkit', '~> 1.0'
+
+Or install it directly:
+
+    gem install redditkit
+
+## Getting Started
+
+RedditKit.rb is structured closely to the wonderful [Octokit.rb](https://github.com/octokit/octokit.rb) and [Twitter](https://github.com/sferik/twitter) gems. If you're familiar with either of those, you'll feel right at home here. You can find the [project's documentation on the RedditKit website](http://redditkit.com/redditkit.rb/).
+
+RedditKit.rb is used through either the `RedditKit` module, or `RedditKit::Client` objects, like so:
+
+**Module usage:**
+```ruby
+RedditKit.sign_in 'username', 'password'
+subreddits = RedditKit.subscribed_subreddits
+```
+
+**Instance method usage:**
+```ruby
+client = RedditKit::Client.new 'username', 'password'
+subreddits = client.subscribed_subreddits
+```
+
+Using RedditKit.rb at the module level allows you to use a single account without having to keep track of RedditKit::Client instances. Working at the instance method level makes it possible to use multiple accounts at once, with one client object per account.
+
+> RedditKit.rb doesn't have any built-in rate limiting. reddit's API rules require that you make no more than 30 requests per minute and try to avoid requesting the same page more than once every 30 seconds. You can read up on the API rules [on their wiki page](https://github.com/reddit/reddit/wiki/API).
+
+### Authentication
+
+```ruby
+client = RedditKit::Client.new 'username', 'password'
+client.signed_in? # => true
+```
+
+## More Examples
+
+**Fetch a user and check their link karma:**
+
+```ruby
+user = RedditKit.user 'samsymons'
+puts "#{user.username} has #{user.link_karma} link karma."
+```
+
+**Subscribe to a subreddit:**
+
+```ruby
+authenticated_client = RedditKit::Client.new 'samsymons', 'password'
+authenticated_client.subscribe 'ruby'
+```
+
+**Upvote the top post in a subreddit:**
+
+```ruby
+posts = authenticated_client.posts 'programming', :category => :top, :time => :all
+authenticated_client.upvote posts.first
+```
+
+**Send private messages:**
+
+```ruby
+authenticated_client.send_message 'How are you?', 'amberlynns', :subject => 'Hi!'
+```
+
+## Pagination
+
+Some RedditKit.rb methods accept pagination options and return `RedditKit::PaginatedResponse` objects upon completion. These options allow you to, for example, limit the number of results returned, or fetch results before/after a specific object.
+
+`RedditKit::PaginatedResponse` forwards its enumeration methods to its `results` array, so you can iterate over it like you would with a standard array.
+
+``` ruby
+paginated_response = RedditKit.front_page
+
+paginated_response.each do |link|
+  # Do something with each link.
+end
+```
+
+## Multiple Accounts
+
+## Configuration
+
+You can configure various aspects of RedditKit.rb's operation, including its default API endpoint and user agent, by setting attributes on `RedditKit::Client`.
+
+**You should set your user agent to the name and version of your app, along with your reddit username. That way, if you ever have a buggy version of your app abusing the API, the reddit admins will know who to contact.**
+
+## Contributing
+
+### Debugging
+
+Because RedditKit.rb is built atop Faraday, you can modify its middleware stack to add new behaviour. This is particularly handy for debugging as you can turn on Faraday's response logger.
+
+```ruby
+RedditKit.middleware = Faraday::Builder.new do |builder|
+  builder.use Faraday::Request::UrlEncoded
+  builder.use RedditKit::Response::RaiseError
+  builder.use RedditKit::Response::ParseJSON
+  builder.use Faraday::Response::Logger  
+  builder.adapter Faraday.default_adapter
+end
+```
+
+### Writing Tests
+
+Tests assume the presence of a `.env` file at the project's root. This file should contain the following three environment variables:
+
+* `REDDITKIT_TEST_USERNAME` The username of a reddit account dedicated solely to testing.
+* `REDDITKIT_TEST_PASSWORD` The password for the reddit account.
+* `REDDITKIT_TEST_SUBREDDIT` A subreddit for which the provided reddit account has admin privileges. This subreddit should be also be dedicated to testing as the test suite will run many different methods on it, creating & deleting various resources.
+
+## Requirements
+
+Ruby 1.9.3 and Ruby 2.0.0 are officially supported.
+
+## Need Help?
+
+Open an [issue](https://github.com/samsymons/RedditKit.rb/issues), or hit me up on [Twitter](http://twitter.com/sam_symons).
+
+## License
+
+Copyright (c) 2013 Sam Symons (http://samsymons.com/)
+
+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 @@
+require 'bundler'
+Bundler::GemHelper.install_tasks
+
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new(:spec)
+
+task :test => :spec
+task :default => :spec

data/lib/redditkit.rb

@@ -0,0 +1,26 @@
+require 'redditkit/client'
+
+# The main RedditKit module.
+module RedditKit
+  class << self
+
+    # A RedditKit::Client, used when calling methods on the RedditKit module itself. 
+    #
+    # @return [RedditKit::Client]
+    def client
+      @client ||= RedditKit::Client.new
+    end
+
+    def respond_to?(method_name, include_private = false)
+      client.respond_to?(method_name, include_private) || super
+    end 
+
+    private
+
+    def method_missing(method_name, *args, &block)
+      return super unless client.respond_to?(method_name)
+      client.send(method_name, *args, &block)
+    end
+    
+  end
+end

data/lib/redditkit/base.rb

@@ -0,0 +1,60 @@
+module RedditKit
+
+  # A base class for RedditKit's model objects, automatically generating attribute and predicate methods.
+  class Base
+
+    attr_reader :attributes
+
+    class << self
+
+      def attr_reader(*attrs)
+        attrs.each do |attr|
+          define_attribute_method(attr)
+          define_predicate_method(attr)
+        end
+      end
+
+      private
+
+      def define_attribute_method(method)
+        define_method(method) do
+          memoize(method) do
+            @attributes[method]
+          end
+        end
+      end
+
+      def define_predicate_method(method)
+        define_method(:"#{method}?") do
+          !!@attributes[method]
+        end
+      end
+
+    end
+
+    def initialize(attributes = {})
+      kind = attributes[:kind]
+      data = attributes[:data]
+
+      @attributes = data || {}
+      @attributes[:kind] = kind
+    end
+
+    def [](method)
+      send(method.to_sym)
+    rescue NoMethodError
+      nil
+    end
+
+    private
+
+    def memoize(key, &block)
+      ivar = :"@#{key}"
+      return instance_variable_get(ivar) if instance_variable_defined?(ivar)
+
+      result = block.call
+      instance_variable_set(ivar, result)
+    end
+
+  end
+end

data/lib/redditkit/client.rb

@@ -0,0 +1,142 @@
+require 'faraday'
+require 'redditkit/error'
+require 'redditkit/version'
+require 'redditkit/client/account'
+require 'redditkit/client/apps'
+require 'redditkit/client/captcha'
+require 'redditkit/client/comments'
+require 'redditkit/client/flair'
+require 'redditkit/client/links'
+require 'redditkit/client/miscellaneous'
+require 'redditkit/client/moderation'
+require 'redditkit/client/multireddits'
+require 'redditkit/client/private_messages'
+require 'redditkit/client/search'
+require 'redditkit/client/subreddits'
+require 'redditkit/client/users'
+require 'redditkit/client/utilities'
+require 'redditkit/client/voting'
+require 'redditkit/client/wiki'
+require 'redditkit/response/parse_json'
+require 'redditkit/response/raise_error'
+
+module RedditKit
+
+  # The client for the reddit API, handling all interactions with reddit's servers.
+  class Client
+    include RedditKit::Client::Account
+    include RedditKit::Client::Apps
+    include RedditKit::Client::Captcha
+    include RedditKit::Client::Comments
+    include RedditKit::Client::Flair
+    include RedditKit::Client::Links
+    include RedditKit::Client::Miscellaneous
+    include RedditKit::Client::Moderation
+    include RedditKit::Client::Multireddits
+    include RedditKit::Client::PrivateMessages
+    include RedditKit::Client::Search
+    include RedditKit::Client::Subreddits
+    include RedditKit::Client::Users
+    include RedditKit::Client::Utilities
+    include RedditKit::Client::Voting
+    include RedditKit::Client::Wiki
+
+    attr_reader :username
+    attr_reader :current_user
+    attr_reader :cookie
+    attr_reader :modhash
+
+    attr_accessor :api_endpoint
+    attr_accessor :authentication_endpoint
+    attr_accessor :user_agent
+    attr_accessor :middleware
+
+    def initialize(username = nil, password = nil)
+      @username = username
+      @password = password
+
+      @cookie = nil
+      @modhash = nil
+
+      unless @username.nil? or @password.nil?
+        sign_in @username, @password 
+      end
+    end
+
+    def api_endpoint
+      @api_endpoint ||= 'http://www.reddit.com/'
+    end
+
+    def authentication_endpoint
+      @authentication_endpoint ||= 'https://ssl.reddit.com/'
+    end
+
+    def user_agent
+      @user_agent ||= "RedditKit.rb #{RedditKit::Version.to_s}"
+    end
+
+    def middleware
+      @middleware ||= Faraday::Builder.new do |builder|
+        builder.use Faraday::Request::UrlEncoded
+        builder.use RedditKit::Response::RaiseError
+        builder.use RedditKit::Response::ParseJSON
+        builder.adapter Faraday.default_adapter
+      end
+    end
+
+    private
+
+    def get(path, params = nil)
+      request(:get, path, params, connection)
+    end
+
+    def post(path, params = nil)
+      request(:post, path, params, connection)
+    end
+
+    def https_post(path, params = nil)
+      request(:post, path, params, https_connection)
+    end
+
+    def put(path, params = nil)
+      request(:put, path, params, connection)
+    end
+
+    def delete_path(path, params = nil)
+      request(:delete, path, params, connection)
+    end
+
+    def request(method, path, parameters = {}, request_connection)
+      if signed_in?
+        request = authenticated_request_configuration(method, path, parameters)
+        request_connection.send(method.to_sym, path, parameters, &request).env
+      else
+        request_connection.send(method.to_sym, path, parameters).env
+      end
+    rescue Faraday::Error::ClientError 
+      raise RedditKit::RequestError
+    end
+
+    def authenticated_request_configuration(method, path, parameters)
+      raise RedditKit::NotAuthenticated unless signed_in?
+
+      Proc.new do |request|
+        request.headers['Cookie'] = "reddit_session=#{@cookie}"
+        request.headers['X-Modhash'] = @modhash
+      end
+    end
+
+    def connection
+      @connection ||= connection_with_url(api_endpoint)
+    end
+
+    def https_connection
+      @https_connection ||= connection_with_url(authentication_endpoint)
+    end
+
+    def connection_with_url(url)
+      Faraday.new(url, { :builder => middleware })
+    end
+
+  end
+end

data/lib/redditkit/client/account.rb

@@ -0,0 +1,73 @@
+module RedditKit
+  class Client
+
+    # Methods which operate on a user's account.
+    module Account
+
+      # Sign in to a reddit account.
+      #
+      # @see http://www.reddit.com/dev/api#POST_api_login
+      # @param username [String] The reddit account's username.
+      # @param password [String] The reddit account's password.
+      def sign_in(username, password)
+        response = https_post 'api/login', { :user => username, :passwd => password, :api_type => :json }
+        body = response[:body]
+
+        data = body[:json][:data]
+
+        @modhash = data[:modhash]
+        @cookie = data[:cookie]
+        @username = username
+
+        @current_user = user @username
+        @username = @current_user.username
+      end
+
+      # Check is a user is currently signed in.
+      #
+      # @return [Boolean]
+      def signed_in?
+        !!@modhash and !!@cookie
+      end
+
+      # Sign the current user out.
+      def sign_out
+        @username = nil
+        @current_user = nil
+
+        @modhash = nil
+        @cookie = nil
+      end
+
+      # Updates the current user's email or password.
+      #
+      # @see http://www.reddit.com/dev/api#POST_api_update
+      # @option options [String] current_password The user's current password.
+      # @option options [String] new_password The user's new password.
+      # @option options [String] email The user's new email address.
+      def update_account(options)
+        password = options[:new_password]
+        parameters = { :curpass => options[:current_password], :email => options[:email], :newpass => password, :verpass => password, :api_type => :json }
+
+        post('api/update', parameters)
+      end
+
+      # Invalidates all session cookies and updates the current one.
+      #
+      # @see http://www.reddit.com/dev/api#POST_api_clear_sessions
+      # @param password [String] The authenticated user's current password.
+      # @return [String] The new cookie value.
+      def update_session(password)
+        response = post('api/clear_sessions', :dest => api_endpoint, :curpass => password, :api_type => 'json')
+
+        response_headers = response[:response_headers]
+        full_cookie_string = response_headers['set-cookie']
+        cookie = full_cookie_string[/reddit_session=(.*?);/m, 1]
+
+        @cookie = cookie
+        cookie
+      end
+
+    end
+  end
+end