ruqqus 1.0.0 → 1.1.4

data/lib/ruqqus.rb

@@ -1,10 +1,14 @@
+require 'base64'
+require 'json'
+require 'rbconfig'
 require 'rest-client'
+require 'securerandom'
+require 'socket'
 
-require_relative 'ruqqus/item_base'
-require_relative 'ruqqus/comment'
-require_relative 'ruqqus/guild'
-require_relative 'ruqqus/post'
-require_relative 'ruqqus/user'
+require_relative 'ruqqus/token'
+require_relative 'ruqqus/routes'
+require_relative 'ruqqus/client'
+require_relative 'ruqqus/types'
 require_relative 'ruqqus/version'
 
 ##
@@ -15,10 +19,6 @@ module Ruqqus
   # The base Ruqqus URL.
   HOME = 'https://ruqqus.com'.freeze
 
-  ##
-  # The Ruqqus API version.
-  API_VERSION = 1
-
   ##
   # A regular expression used for username validation.
   VALID_USERNAME = /^[a-zA-Z0-9_]{5,25}$/.freeze
@@ -35,91 +35,244 @@ module Ruqqus
   # A regular expression used for post/comment ID validation.
   VALID_POST = /[A-Za-z0-9]+/.freeze
 
+  ##
+  # Captures the ID of a post from a Ruqqus URL
+  POST_REGEX = /\/post\/([A-Za-z0-9]+)\/?.*/.freeze
+
+  ##
+  # Captures the ID of a comment from a Ruqqus URL
+  COMMENT_REGEX = /\/post\/.+\/.+\/([A-Za-z0-9]+)\/?/.freeze
+
   ##
   # Generic error class for exceptions specific to the Ruqqus API.
   class Error < StandardError
   end
 
   ##
-  # Retrieves the {User} with the specified username.
-  #
-  # @param username [String] the username of the Ruqqus account to retrieve.
+  # @!attribute self.proxy [rw]
+  #   @return [URI?] the URI of the proxy server in use, or `nil` if none has been set.
+
+  ##
+  # Obtains a list of URIs of free proxy servers that can be used to route network traffic through.
   #
-  # @return [User] the requested {User}.
+  # @param anon [Symbol] anonymity filter for the servers to return, either `:transparent`, `:anonymous`, or `:elite`.
+  # @param country [String,Symbol] country filter for servers to return, an ISO-3166 two digit county code.
   #
-  # @raise [ArgumentError] when `username` is `nil` or value does match the {VALID_USERNAME} regular expression.
-  # @raise [Error] thrown when user account does not exist.
-  def self.user(username)
-    raise(ArgumentError, 'username cannot be nil') unless username
-    raise(ArgumentError, 'invalid username') unless VALID_USERNAME.match?(username)
-    api_get("#{HOME}/api/v1/user/#{username}", User)
+  # @return [Array<URI>] an array of proxy URIs that match the input filters.
+  # @note These proxies are free, keep that in mind. They are refreshed frequently, can go down unexpectedly, be slow,
+  #   and other manners of inconvenience that can be expected with free services.
+  # @see https://www.nationsonline.org/oneworld/country_code_list.htm
+  def self.proxy_list(anon: :elite, country: nil)
+    raise(ArgumentError, 'invalid anonymity value') unless %i(transparent anonymous elite).include?(anon.to_sym)
+
+    url = "https://www.proxy-list.download/api/v1/get?type=https&anon=#{anon}"
+    url << "&country=#{country}" if country
+
+    RestClient.get(url) do |resp|
+      break if resp.code != 200
+      return resp.body.split.map { |proxy| URI.parse("https://#{proxy}") }
+    end
+    Array.new
+  end
+
+  def self.proxy
+    RestClient.proxy
+  end
+
+  def self.proxy=(uri)
+    raise(TypeError, "#{uri} is not a URI") if uri && !uri.is_a?(URI)
+    RestClient.proxy = uri
   end
 
   ##
-  # Retrieves the {Guild} with the specified name.
+  # Helper function to automate uploading images to Imgur anonymously and returning the direct image link.
   #
-  # @param guild_name [String] the name of the Ruqqus guild to retrieve.
+  # @param client_id [String] an Imgur client ID
+  # @param image_path [String] the path to an image file.
+  # @param opts [Hash] the options hash.
+  # @option opts [String] :title a title to set on the Imgur post
+  # @option opts [String] :description a description to set on the Imgur post
   #
-  # @return [Guild] the requested {Guild}.
-  #
-  # @raise [ArgumentError] when `guild_name` is `nil` or value does match the {VALID_GUILD} regular expression.
-  # @raise [Error] thrown when guild does not exist.
-  def self.guild(guild_name)
-    raise(ArgumentError, 'guild_name cannot be nil') unless guild_name
-    raise(ArgumentError, 'invalid guild name') unless VALID_POST.match?(guild_name)
-    api_get("#{HOME}/api/v1/guild/#{guild_name}", Guild)
+  # @return [String] the direct image link from Imgur.
+  # @note To obtain a free Imgur client ID, visit https://api.imgur.com/oauth2/addclient
+  # @note No authentication is required for anonymous image upload, though rate limiting (very generous) applies.
+  # @see Client.post_create
+  def self.imgur_upload(client_id, image_path, **opts)
+    #noinspection RubyResolve
+    raise(Errno::ENOENT, image_path) unless File.exist?(image_path)
+    raise(ArgumentError, 'client_id cannot be nil or empty') if client_id.nil? || client_id.empty?
+
+    header = { 'Content-Type': 'application/json', 'Authorization': "Client-ID #{client_id}" }
+    params = { image: File.new(image_path), type: 'file', title: opts[:title], description: opts[:description] }
+
+    response = RestClient.post('https://api.imgur.com/3/upload', params, header)
+    json = JSON.parse(response.body, symbolize_names: true)
+    json[:data][:link]
   end
 
   ##
-  # Retrieves the {Post} with the specified name.
-  #
-  # @param post_id [String] the ID of the post to retrieve.
+  # Checks if the specified guild name is available to be created.
   #
-  # @return [Post] the requested {Post}.
+  # @param guild_name [String] the name of a guild to query.
   #
-  # @raise [ArgumentError] when `post_id` is `nil` or value does match the {VALID_POST} regular expression.
-  # @raise [Error] thrown when a post with the specified ID does not exist.
-  def self.post(post_id)
-    raise(ArgumentError, 'post_id cannot be nil') unless post_id
-    raise(ArgumentError, 'invalid post ID') unless VALID_POST.match?(post_id)
-    api_get("#{HOME}/api/v1/post/#{post_id}", Post)
+  # @return [Boolean] `true` is name is available, otherwise `false` if it has been reserved or is in use.
+  def self.guild_available?(guild_name)
+    begin
+      response = RestClient.get("#{Routes::GUILD_AVAILABLE}#{guild_name}")
+      json = JSON.parse(response.body, symbolize_names: true)
+      return json[:available]
+    rescue
+      puts 'err'
+      return false
+    end
   end
 
   ##
-  # Retrieves the {Comment} with the specified name.
+  # Checks if the specified username is available to be created.
   #
-  # @param comment_id [String] the ID of the comment to retrieve.
+  # @param username [String] the name of a user to query.
   #
-  # @return [Comment] the requested {Comment}.
+  # @return [Boolean] `true` is name is available, otherwise `false` if it has been reserved or is in use.
+  def self.username_available?(username)
+    begin
+      response = RestClient.get("#{Routes::USERNAME_AVAILABLE}#{username}")
+      json = JSON.parse(response.body)
+      return json[username]
+    rescue
+      return false
+    end
+  end
+
+  ##
+  # Generates a URL for the user to navigate to that will allow them to authorize an application.
   #
-  # @raise [ArgumentError] when `comment_id` is `nil` or value does match the {VALID_POST} regular expression.
-  # @raise [Error] when a comment with the specified ID does not exist.
-  def self.comment(comment_id)
-    raise(ArgumentError, 'comment_id cannot be nil') unless comment_id
-    raise(ArgumentError, 'invalid comment ID') unless VALID_POST.match?(comment_id)
-    api_get("#{HOME}/api/v1/comment/#{comment_id}", Comment)
+  # @param client_id [String] the unique ID of the approved client to authorize.
+  # @param redirect [String] the redirect URL where the client sends the OAuth authorization code.
+  # @param scopes [Array<Symbol>] a collection of values indicating the permissions the application is requesting from
+  #   the user. See {Ruqqus::Client::SCOPES} for valid values.
+  # @param permanent [Boolean] `true` if authorization should persist until user explicitly revokes it,
+  #   otherwise `false`.
+  # @param csrf [String] a token to authenticate and prevent a cross-site request forgery (CSRF) attack, or `nil` if
+  #   you do not plan to validate the presence of the cookie in the redirection.
+  #
+  # @see https://ruqqus.com/settings/apps
+  # @see https://owasp.org/www-community/attacks/csrf
+  def self.authorize_url(client_id, redirect, scopes, permanent = true, csrf = nil)
+
+    raise(ArgumentError, 'invalid redirect URI') unless URI.regexp =~ redirect
+    raise(ArgumentError, 'scopes cannot be empty') unless scopes && !scopes.empty?
+
+    scopes = scopes.map(&:to_sym)
+    raise(ArgumentError, "invalid scopes specified") unless scopes.all? { |s| Client::SCOPES.include?(s) }
+    if scopes.any? { |s| [:create, :update, :guildmaster].include?(s) } && !scopes.include?(:identity)
+      # Add identity permission if missing, which is obviously required for a few other permissions
+      scopes << :identity
+    end
+
+    url = 'https://ruqqus.com/oauth/authorize'
+    url << "?client_id=#{client_id || raise(ArgumentError, 'client ID cannot be nil')}"
+    url << "&redirect_uri=#{redirect}"
+    url << "&scope=#{scopes.join(',')}"
+    url << "&state=#{csrf || Base64.encode64(SecureRandom.uuid).chomp}"
+    url << "&permanent=#{permanent}"
+    url
   end
 
+
   ##
-  # @api private
-  # Calls the GET method at the specified API route, and returns the deserializes JSON response as an object.
+  # Opens a URL in the system's default web browser, using the appropriate command for the host platform.
   #
-  # @param route [String] the full API route to the GET method.
-  # @param klass [Class] a Class instance that is inherited from {ItemBase}.
+  # @param [String] the URL to open.
   #
-  # @return [Object] an instance of the specified class.
+  # @return [void]
+  def self.open_browser(url)
+
+    cmd = case RbConfig::CONFIG['host_os']
+    when /mswin|mingw|cygwin/ then "start \"\"#{url}\"\""
+    when /darwin/ then "open '#{url}'"
+    when /linux|bsd/ then "xdg-open '#{url}'"
+    else raise(Ruqqus::Error, 'unable to determine how to open URL for current platform')
+    end
+
+    system(cmd)
+  end
+
+  ##
+  # If using a `localhost` address for your application's OAuth redirect, this method can be used to open a socket and
+  # listen for a request, returning the authorization code once it arrives.
   #
-  # @raise [Error] thrown when the requested item is not found.
-  # @raise [ArgumentError] when the specified class is not inherited from {ItemBase}.
-  def self.api_get(route, klass)
-    raise(ArgumentError, 'klass is not a child class of Ruqqus::ItemBase') unless klass < ItemBase
-    #noinspection RubyResolve
-    begin
-      response = RestClient.get(route)
-      klass.from_json(response.body)
-    rescue RestClient::BadRequest
-      raise(Error, 'invalid search parameters, object with specified criteria does not exist')
+  # @param port [Integer] the port to listen on.
+  # @param timeout [Numeric] sets the number of seconds to wait before cancelling and returning `nil`.
+  #
+  # @return [String?] the authorization code, `nil` if an error occurred.
+  # @note This method is blocking, and will *not* return until a connection is made and data is received on the
+  #   specified port, or the timeout is reached.
+  def self.wait_for_code(port, timeout = 30)
+
+    thread = Thread.new do
+      sleep(timeout)
+      TCPSocket.open('localhost', port) { |s| s.puts }
     end
+
+    params = {}
+    TCPServer.open('localhost', port) do |server|
+
+      session = server.accept
+      request = session.gets
+      match = /^GET [\/?]+(.*) HTTP.*/.match(request)
+
+      Thread.kill(thread)
+      return nil unless match
+
+      $1.split('&').each do |str|
+        key, value = str.split('=')
+        next unless key && value
+        params[key.to_sym] = value
+      end
+
+      session.puts "HTTP/1.1 200\r\n"
+      session.puts "Content-Type: text/html\r\n"
+      session.puts "\r\n"
+      session.puts create_response(!!params[:code])
+
+      session.close
+    end
+
+    params[:code]
   end
-end
 
+  private
+
+  ##
+  # @return [String] a generic confirmation page to display in the user's browser after confirming application access.
+  def self.create_response(success)
+    args = success ? ['#339966', 'Authorization Confirmed'] : ['#ff0000', 'Authorization Failed']
+    format ='<h1 style="text-align: center;"><span style="color: %s;"><strong>%s</strong></span></h1>'
+    message = sprintf(format, *args)
+    <<-EOS
+<html>
+<head>
+    <style>
+    .center {
+      margin: 0;
+      position: absolute;
+      top: 50%;
+      left: 50%;
+      -ms-transform: translate(-50%, -50%);
+      transform: translate(-50%, -50%);
+    }
+  </style>
+</head>
+<body>
+<div class="center">
+    <div><img src="https://raw.githubusercontent.com/ruqqus/ruqqus/master/ruqqus/assets/images/logo/ruqqus_text_logo.png" alt="" width="365" height="92" /></div>
+    <p style="text-align: center;">&nbsp;</p>
+    #{message}
+    <p style="text-align: center;">&nbsp;&nbsp;</p>
+    <p style="text-align: center;"><span style="color: #808080;">You can safely close the tab/browser and return to the application.</span></p>
+</div>
+</body>
+</html>
+    EOS
+  end
+end

data/lib/ruqqus/client.rb

@@ -0,0 +1,571 @@
+require_relative 'version'
+
+module Ruqqus
+
+  ##
+  # Implements interacting with the Ruqqus API as a user, such as login, posting, account management, etc.
+  #noinspection RubyTooManyMethodsInspection
+  class Client
+
+    ##
+    # The user-agent the client identified itself as.
+    USER_AGENT = "ruqqus-ruby/#{Ruqqus::VERSION}".freeze
+
+    ##
+    # A collection of valid scopes that can be authorized.
+    #
+    #   * `:identity` - See your username.
+    #   * `:create` - Save posts and comments as you
+    #   * `:read` - View Ruqqus as you, including private or restricted content
+    #   * `:update` - Edit your posts and comments
+    #   * `:delete` - Delete your posts and comments
+    #   * `:vote` - Cast votes as you
+    #   * `:guildmaster` - Perform Guildmaster actions
+    SCOPES = %i(identity create read update delete vote guildmaster).freeze
+
+    ##
+    # A set of HTTP headers that will be included with every request.
+    DEFAULT_HEADERS = { 'User-Agent': USER_AGENT, 'Accept': 'application/json', 'Content-Type': 'application/json' }.freeze
+
+    ##
+    # @!attribute [rw] token
+    #   @return [Token] the OAuth2 token that grants the client authentication.
+
+    ##
+    # @!attribute [r] identity
+    #   @return [User] the authenticated user this client is performing actions as.
+
+    ##
+    # @overload initialize(client_id, client_secret, token)
+    #   Creates a new instance of the {Client} class with an existing token for authorization.
+    #   @param client_id [String] the client ID of your of your application, issued after registration on Ruqqus.
+    #   @param client_secret [String] the client secret of your of your application, issued after registration on Ruqqus.
+    #   @param token [Token] a valid access token that has previously been granted access for the client.
+    #
+    # @overload initialize(client_id, client_secret, code)
+    #   Creates a new instance of the {Client} class with an existing token for authorization.
+    #   @param client_id [String] the client ID of your of your application, issued after registration on Ruqqus.
+    #   @param client_secret [String] the client secret of your of your application, issued after registration on Ruqqus.
+    #   @param code [String] a the code from the Oauth2 redirect to create a new {Token} and grant access to it.
+    def initialize(client_id, client_secret, token)
+      @client_id = client_id || raise(ArgumentError, 'client ID cannot be nil')
+      @client_secret = client_secret || raise(ArgumentError, 'client secret cannot be nil')
+
+      @token = token.is_a?(Token) ? token : Token.new(client_id, client_secret, token.to_s)
+      @session = nil
+    end
+
+    attr_reader :token
+
+    def token=(token)
+      @token = token || raise(ArgumentError, 'token cannot be nil')
+    end
+
+    # @!group Object Querying
+
+    ##
+    # Retrieves the {User} with the specified username.
+    #
+    # @param username [String] the username of the Ruqqus account to retrieve.
+    #
+    # @return [User] the requested {User}.
+    #
+    # @raise [ArgumentError] when `username` is `nil` or value does match the {Ruqqus::VALID_USERNAME} regular expression.
+    # @raise [Error] thrown when user account does not exist.
+    def user(username)
+      raise(ArgumentError, 'username cannot be nil') unless username
+      raise(ArgumentError, 'invalid username') unless VALID_USERNAME.match?(username)
+      User.from_json(http_get("#{Routes::USER}#{username}"))
+    end
+
+    ##
+    # Retrieves the {Guild} with the specified name.
+    #
+    # @param guild_name [String] the name of the Ruqqus guild to retrieve.
+    #
+    # @return [Guild] the requested {Guild}.
+    #
+    # @raise [ArgumentError] when `guild_name` is `nil` or value does match the {Ruqqus::VALID_GUILD} regular expression.
+    # @raise [Error] thrown when guild does not exist.
+    def guild(guild_name)
+      raise(ArgumentError, 'guild_name cannot be nil') unless guild_name
+      raise(ArgumentError, 'invalid guild name') unless VALID_GUILD.match?(guild_name)
+      Guild.from_json(http_get("#{Routes::GUILD}#{guild_name}"))
+    end
+
+    ##
+    # Retrieves the {Post} with the specified name.
+    #
+    # @param post_id [String] the ID of the post to retrieve.
+    #
+    # @return [Post] the requested {Post}.
+    #
+    # @raise [ArgumentError] when `post_id` is `nil` or value does match the {Ruqqus::VALID_POST} regular expression.
+    # @raise [Error] thrown when a post with the specified ID does not exist.
+    def post(post_id)
+      raise(ArgumentError, 'post_id cannot be nil') unless post_id
+      raise(ArgumentError, 'invalid post ID') unless VALID_POST.match?(post_id)
+      Post.from_json(http_get("#{Routes::POST}#{post_id}"))
+    end
+
+    ##
+    # Retrieves the {Comment} with the specified name.
+    #
+    # @param comment_id [String] the ID of the comment to retrieve.
+    #
+    # @return [Comment] the requested {Comment}.
+    #
+    # @raise [ArgumentError] when `comment_id` is `nil` or value does match the {Ruqqus::VALID_POST} regular expression.
+    # @raise [Error] when a comment with the specified ID does not exist.
+    def comment(comment_id)
+      raise(ArgumentError, 'comment_id cannot be nil') unless comment_id
+      raise(ArgumentError, 'invalid comment ID') unless VALID_POST.match?(comment_id)
+      Comment.from_json(http_get("#{Routes::COMMENT}#{comment_id}"))
+    end
+
+    # @!endgroup Object Querying
+
+    # @!group Commenting
+
+    ##
+    # Submits a new comment on a post.
+    #
+    # @param body [String] the text content of the post (supports Markdown)
+    # @param post [Post,String] a {Post} instance or the unique ID of a post.
+    # @param comment [Comment,String] a {Comment} with the post to reply under, or `nil` to reply directly to the post.
+    #
+    # @return [Comment?] the comment that was submitted, or `nil` if an error occurred.
+    #
+    # @note This method is restricted to 6/minute, and will fail when that limit is exceeded.
+    def comment_create(body, post, comment = nil)
+      pid = post.to_s
+      parent = comment ? 't3_' + comment.to_s : 't2_' + pid
+      comment_submit(parent, pid, body)
+    end
+
+    ##
+    # Submits a new comment on a post.
+    #
+    # @param body [String] the text content of the comment (supports Markdown)
+    # @param comment [Comment,String] a {Comment} instance or the unique ID of a comment.
+    #
+    # @return [Comment?] the comment that was submitted, or `nil` if an error occurred.
+    #
+    # @note This method is restricted to 6/minute, and will fail when that limit is exceeded.
+    def comment_reply(body, comment)
+      if comment.is_a?(Comment)
+        comment_submit(comment.fullname, comment.post_id, body)
+      else
+        comment = self.comment(comment.to_s)
+        comment_submit(comment.fullname, comment.post_id, body)
+      end
+    end
+
+    ##
+    # Deletes an existing comment.
+    #
+    # @param comment [Comment,String] a {Comment} instance, or the unique ID of the comment to delete.
+    #
+    # @return [Boolean] `true` if deletion completed without error, otherwise `false`.
+    def comment_delete(comment)
+      id = comment.is_a?(Comment) ? comment.id : comment.sub(/^t3_/, '')
+      url = "#{Routes::API_BASE}/delete/comment/#{id}"
+      http_post(url).empty? rescue false
+    end
+
+    # @!endgroup Commenting
+
+    # @!group Posting
+
+    ##
+    # Creates a new post on Ruqqus as the current user.
+    #
+    # @param guild [Guild,String] a {Guild} instance or the name of the guild to post to.
+    # @param title [String] the title of the post to create.
+    # @param body [String?] the text body of the post, which can be `nil` if supplying URL or image upload.
+    # @param opts [Hash] The options hash to specify a link or image to upload.
+    # @option opts [String] :image (nil) the path to an image file to upload.
+    # @option opts [String] :url (nil) a URL to share with the post.
+    # @option opts [String] :imgur_client (nil) an Imgur client ID to automatically share images via Imgur instead of
+    #   direct upload.
+    #
+    # @return [Post?] the newly created {Post} instance, or `nil` if an error occurred.
+    # @note This method is restricted to 6/minute, and will fail when that limit is exceeded.
+    def post_create(guild, title, body = nil, **opts)
+      name = guild.is_a?(Guild) ? guild.name : guild.strip.sub(/^\+/, '')
+      raise(ArgumentError, 'invalid guild name') unless Ruqqus::VALID_GUILD.match?(name)
+      raise(ArgumentError, 'title cannot be nil or empty') unless title && !title.empty?
+      params = { title: title, board: name, body: body }
+
+      if opts[:image]
+        if opts[:imgur_client]
+          params[:url] = Ruqqus.imgur_upload(opts[:imgur_client], opts[:image])
+        else
+          params[:file] = File.new(opts[:image])
+        end
+      elsif opts[:url]
+        raise(ArgumentError, 'invalid URI') unless URI.regexp =~ opts[:url]
+        params[:url] = opts[:url]
+      end
+
+      if [params[:body], params[:image], params[:url]].none?
+        raise(ArgumentError, 'text body cannot be nil or empty without URL or image') if body.nil? || body.empty?
+      end
+      Post.from_json(http_post(Routes::SUBMIT, params)) rescue nil
+    end
+
+    # @!endgroup Posting
+
+    # @!group Voting
+
+    ##
+    # Places a vote on a post.
+    #
+    # @param post [Post,String] a {Post} instance, or the unique ID of a post.
+    # @param value [Integer] the vote value to place, either `-1`, `0`, or `1`.
+    #
+    # @return [Boolean] `true` if vote was placed successfully, otherwise `false`.
+    def vote_post(post, value = 1)
+      submit_vote(post.to_s, value, 'https://ruqqus.com/api/v1/vote/post/')
+    end
+
+    ##
+    # Places a vote on a comment.
+    #
+    # @param comment [Comment,String] a {Comment} instance, or the unique ID of a comment.
+    # @param value [Integer] the vote value to place, either `-1`, `0`, or `1`.
+    #
+    # @return [Boolean] `true` if vote was placed successfully, otherwise `false`.
+    def vote_comment(comment, value = 1)
+      submit_vote(comment.to_s, value, 'https://ruqqus.com/api/v1/vote/comment/')
+    end
+
+    # @!endgroup Voting
+
+    # @!group Object Enumeration
+
+    ##
+    # Enumerates through each post of a user, yielding each to a block.
+    #
+    # @param user [User,String] a {User} instance or the name of the account to query.
+    # @yieldparam post [Post] yields a {Post} to the block.
+    # @return [self]
+    # @raise [LocalJumpError] when a block is not supplied to the method.
+    # @note An API invocation is required for every 25 items that are yielded to the block, so observing brief pauses at
+    #   these intervals is an expected behavior.
+    def each_user_post(user)
+      raise(LocalJumpError, 'block required') unless block_given?
+      each_submission(user, Post, 'listing') { |obj| yield obj }
+    end
+
+    ##
+    # Enumerates through each comment of a user, yielding each to a block.
+    #
+    # @param user [User,String] a {User} instance or the name of the account to query.
+    # @yieldparam comment [Comment] yields a {Comment} to the block.
+    # @return [self]
+    # @raise [LocalJumpError] when a block is not supplied to the method.
+    # @note An API invocation is required for every 25 items that are yielded to the block, so observing brief pauses at
+    #   these intervals is an expected behavior.
+    def each_user_comment(user)
+      raise(LocalJumpError, 'block required') unless block_given?
+      each_submission(user, Comment, 'comments') { |obj| yield obj }
+    end
+
+    ##
+    # Enumerates through each post in the specified guild, and yields each one to a block.
+    #
+    # @param sort [Symbol] a symbol to determine the sorting method, valid values include `:trending`, `:subs`, `:new`.
+    # @yieldparam guild [Guild] yields a {Guild} to the block.
+    # @return [self]
+    # @raise [LocalJumpError] when a block is not supplied to the method.
+    # @note An API invocation is required for every 25 items that are yielded to the block, so observing brief pauses at
+    #   these intervals is an expected behavior.
+    def each_guild(sort = :subs)
+      raise(LocalJumpError, 'block required') unless block_given?
+
+      page = 1
+      loop do
+        params = { sort: sort, page: page }
+        json = http_get(Routes::GUILDS, headers(params: params))
+        break if json[:error]
+        json[:data].each { |hash| yield Guild.from_json(hash) }
+        break if json[:data].size < 25
+        page += 1
+      end
+      self
+    end
+
+    ##
+    # Enumerates through each post in a guild, yielding each to a block.
+    #
+    # @param guild [Guild,String] a {Guild} instance, or the name of the guild to query.
+    # @param opts [Hash] the options hash.
+    # @option opts [Symbol] :sort (:new) Valid: `:new`, `:top`, `:hot`, `:activity`, `:disputed`
+    # @option opts [Symbol] :filter (:all) Valid: `:all`, `:day`, `:week`, `:month`, `:year`
+    #
+    # @yieldparam post [Post] yields a {Post} to the block.
+    # @return [self]
+    # @raise [LocalJumpError] when a block is not supplied to the method.
+    # @note An API invocation is required for every 25 items that are yielded to the block, so observing brief pauses at
+    #   these intervals is an expected behavior.
+    def each_guild_post(guild, **opts)
+      raise(LocalJumpError, 'block required') unless block_given?
+      name = guild.to_s
+      raise(ArgumentError, 'invalid guild name') unless Ruqqus::VALID_GUILD.match?(name)
+
+      sort = opts[:sort] || :new
+      filter = opts[:filter] || :all
+
+      page = 1
+      loop do
+        params = { page: page, sort: sort, t: filter }
+        json = http_get("#{Routes::GUILD}#{name}/listing", headers(params: params))
+        break if json[:error]
+
+        json[:data].each { |hash| yield Post.from_json(hash) }
+        break if json[:data].size < 25
+        page += 1
+      end
+
+      self
+    end
+
+    ##
+    # Enumerates through each comment in a guild, yielding each to a block.
+    #
+    # @param guild [Guild,String] a {Guild} instance, or the name of the guild to query.
+    # @yieldparam [Comment] yields a {Comment} to the block.
+    #
+    # @return [self]
+    # @raise [LocalJumpError] when a block is not supplied to the method.
+    def each_guild_comment(guild)
+      raise(LocalJumpError, 'block required') unless block_given?
+      name = guild.to_s
+      raise(ArgumentError, 'invalid guild name') unless Ruqqus::VALID_GUILD.match?(name)
+
+      page = 1
+      loop do
+        params = { page: page }
+        json = http_get("#{Routes::GUILD}#{name}/comments", headers(params: params))
+        break if json[:error]
+
+        json[:data].each { |hash| yield Comment.from_json(hash) }
+        break if json[:data].size < 25
+        page += 1
+      end
+
+      self
+    end
+
+    ##
+    # Enumerates through each comment in a guild, yielding each to a block.
+    #
+    # @param post [Post,String] a {Post} instance, or the unique ID of the post to query.
+    # @yieldparam [Comment] yields a {Comment} to the block.
+    #
+    # @return [self]
+    # @raise [LocalJumpError] when a block is not supplied to the method.
+    # @note This method is very inefficient, as it the underlying API does not yet implement it, therefore each comment
+    #   in the entire guild must be searched through.
+    def each_post_comment(post)
+      # TODO: This is extremely inefficient, but will have to do until it gets implemented in the API
+      raise(LocalJumpError, 'block required') unless block_given?
+      post = self.post(post) unless post.is_a?(Post)
+      each_guild_comment(post.guild_name) do |comment|
+        next unless comment.post_id == post.id
+        yield comment
+      end
+      self
+    end
+
+    ##
+    # Enumerates through every post on Ruqqus, yielding each post to a block.
+    #
+    # @param opts [Hash] the options hash.
+    # @option opts [Symbol] :sort (:new) Valid: `:new`, `:top`, `:hot`, `:activity`, `:disputed`
+    # @option opts [Symbol] :filter (:all) Valid: `:all`, `:day`, `:week`, `:month`, `:year`
+    #
+    # @yieldparam post [Post] yields a post to the block.
+    # @return [self]
+    # @raise [LocalJumpError] when a block is not supplied to the method.
+    # @note An API invocation is required for every 25 items that are yielded to the block, so observing brief pauses at
+    #   these intervals is an expected behavior.
+    def each_post(**opts)
+      raise(LocalJumpError, 'block required') unless block_given?
+
+      sort = opts[:sort] || :new
+      filter = opts[:filter] || :all
+
+      page = 1
+      loop do
+        params = { page: page, sort: sort, t: filter }
+        json = http_get(Routes::ALL_LISTINGS, headers(params: params))
+        break if json[:error]
+        json[:data].each { |hash| yield Post.from_json(hash) }
+        break if json[:data].size < 25
+        page += 1
+      end
+      self
+    end
+
+    ##
+    # Enumerates through every post on the "front page", yielding each post to a block.
+    #
+    # @yieldparam post [Post] yields a {Post} to the block.
+    #
+    # @return [self]
+    # @note The front page uses a unique algorithm that is essentially "hot", but for guilds the user is subscribed to.
+    def each_home_post
+      raise(LocalJumpError, 'block required') unless block_given?
+      page = 1
+      loop do
+        json = http_get(Routes::FRONT_PAGE, headers(params: { page: page }))
+        break if json[:error]
+        json[:data].each { |hash| yield Post.from_json(hash) }
+        break if json[:data].size < 25
+        page += 1
+      end
+      self
+    end
+
+    # @!endgroup Object Enumeration
+
+    ##
+    # @return [User] the authenticated user this client is performing actions as.
+    def identity
+      @me ||= User.from_json(http_get(Routes::IDENTITY))
+    end
+
+    ##
+    # @overload token_refreshed(&block)
+    #   Sets a callback to be invoked when the token is refreshed, and a new access token is assigned.
+    #   @yieldparam token [Token] yields the newly refreshed {Token} to the block.
+    #
+    # @overload token_refreshed
+    #   When called without a block, clears any callback that was previously assigned.
+    #
+    # @return [void]
+    def token_refreshed(&block)
+      @refreshed = block_given? ? block : nil
+    end
+
+    private
+
+    ##
+    # @api private
+    # Places a vote on a comment or post.
+    #
+    # @param id [String] the ID of a post or comment.
+    # @param value [Integer] the vote to place, between -1 and 1.
+    # @param route [String] the endpoint of the vote method to invoke.
+    #
+    # @return [Boolean] `true` if vote was placed successfully, otherwise `false`.
+    def submit_vote(id, value, route)
+      raise(Ruqqus::Error, 'invalid ID') unless Ruqqus::VALID_POST.match?(id)
+      amount = [-1, [1, value.to_i].min].max
+      !!http_post("#{route}#{id}/#{amount}")[:error] rescue false
+    end
+
+    ##
+    # @api private
+    # Retrieves the HTTP headers for API calls.
+    #
+    # @param opts [Hash] the options hash to include any additional parameters.
+    #
+    # @return [Hash<Symbol, Sting>] a hash containing the header parameters.
+    def headers(**opts)
+      hash = DEFAULT_HEADERS.merge({ Authorization: "#{@token.type} #{@token.access_token}" })
+      opts[:cookies] = { session: @session } if @session
+      hash.merge(opts)
+    end
+
+    ##
+    # @api private
+    # Submits a new comment.
+    #
+    # @param parent [String] the full name of a post or comment to reply under. (i.e. `t2_`, `t3_`, etc.)
+    # @param pid [String] the unique ID of the parent post to comment within.
+    # @param body [String] the text body of the comment.
+    #
+    # @return [Comment] the newly submitted comment.
+    def comment_submit(parent, pid, body)
+      raise(ArgumentError, 'body cannot be nil or empty') unless body && !body.empty?
+      params = { submission: pid, parent_fullname: parent, body: body }
+      Comment.from_json(http_post(Routes::COMMENT, params)) rescue nil
+    end
+
+    ##
+    # @api private
+    # Enumerates over each page of posts/comments for a user, and returns the deserialized objects.
+    #
+    # @param user [User,String] a {User} instance or the name of the account to query.
+    # @param klass [Class] the type of object to return, must implement `.from_json`.
+    # @param route [String] the final API route for the endpoint, either `"listing"` or "comments"`
+    #
+    # @return [self]
+    def each_submission(user, klass, route)
+
+      username = user.is_a?(User) ? user.username : user.to_s
+      raise(Ruqqus::Error, 'invalid username') unless VALID_USERNAME.match?(username)
+
+      page = 1
+      loop do
+        url = "#{Routes::USER}#{username}/#{route}"
+        json = http_get(url, headers(params: { page: page }))
+        break if json[:error]
+
+        json[:data].each { |hash| yield klass.from_json(hash) }
+        break if json[:data].size < 25
+        page += 1
+      end
+      self
+    end
+
+    ##
+    # @api private
+    # Creates and sends a GET request and returns the response as a JSON hash.
+    #
+    # @param uri [String] the endpoint to invoke.
+    # @param header [Hash] a set of headers to send, or `nil` to use the default headers.
+    #
+    # @return [Hash] the response deserialized into a JSON hash.
+    # @see http_post
+    def http_get(uri, header = nil)
+      refresh_token
+      header ||= headers
+      response = RestClient.get(uri.chomp('/'), header)
+      @session = response.cookies['session_ruqqus'] if response.cookies['session_ruqqus']
+      raise(Ruqqus::Error, 'HTTP request failed') if response.code < 200 || response.code >= 300
+      JSON.parse(response, symbolize_names: response.body)
+    end
+
+    ##
+    # @api private
+    # Creates and sends a POST request and returns the response as a JSON hash.
+    #
+    # @param uri [String] the endpoint to invoke.
+    # @param params [Hash] a hash of parameters that will be sent with the request.
+    # @param header [Hash] a set of headers to send, or `nil` to use the default headers.
+    #
+    # @return [Hash] the response deserialized into a JSON hash.
+    # @see http_get
+    def http_post(uri, params = {}, header = nil)
+      refresh_token
+      header ||= headers
+      response = RestClient.post(uri.chomp('/'), params, header)
+      @session = response.cookies['session_ruqqus'] if response.cookies['session_ruqqus']
+      raise(Ruqqus::Error, 'HTTP request failed') if response.code < 200 || response.code >= 300
+      JSON.parse(response, symbolize_names: response.body)
+    end
+
+    ##
+    # @api private
+    # Checks if token is expired, and refreshes if so, calling the {#token_refreshed} block as if defined.
+    def refresh_token
+      return unless @token.expired?
+      @token.refresh(@client_id, @client_secret)
+      @refreshed&.call(@token)
+    end
+  end
+end