ruqqus 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a01559e849bc401630ad22455035ae0d00891f34e294eb00ea9780b82c932620
-  data.tar.gz: 56f99a8360fd71eb431dcf3d263f106412766f2afd51cdcda237aa643b9bb76d
+  metadata.gz: bb4087c263dae6ef0708a07d756733ea19f95e1e6f02983c658c9cfb40a2f475
+  data.tar.gz: d9d71b14897ec30ea1f5356916d1eb2cc432db02e7c007fb5f8efcea3a3f37fa
 SHA512:
-  metadata.gz: 1417f32ba0e67970c1305c0f2cf48873fd6c4a6ffe5c6df98cb799f1459bf0ec364762a78f3eff4fb756b367e13650eeea7b8a62b516623e476b4d8488b7a167
-  data.tar.gz: 485fadd5ed20a3d6b1290ce709c9d5881f0f4a5ec890196fa16deff6b500ecfeb0f1f030a4dcc5eaeff853c9d2ac22a6180d080ed3cf583bf7679d2b9a10aa7c
+  metadata.gz: f5864e192920e53c59921cf9bdb7d2f2acaf261d77ed4c0d3184a7f601cf967cf87f358c4b396705b8366fcda6ed3d54a9a125b0f13e7e139d0ce3ff0f67535e
+  data.tar.gz: 73d7d5b8a4551a7bc83efd54b8be72107a010f4023dc9784396dddce8ceae4808049cc6fed37487b07e259b6efc41a1ff75d8184bf5ce28f18f8c261e2ffd0e4

data/.gitignore

@@ -164,4 +164,7 @@ modules.xml
 # Ignore all local history of files
 .history
 
-# End of https://www.toptal.com/developers/gitignore/api/ruby,rubymine+all,visualstudiocode
+# End of https://www.toptal.com/developers/gitignore/api/ruby,rubymine+all,visualstudiocode
+
+# JSON file containing the token for test user during development
+/token.json

data/CHANGELOG.md

@@ -2,6 +2,29 @@
 
 Documentation for library API changes.
 
-## Version 1.0
+## Version 1.1.0
+
+* Implemented `Ruqqus::Token` class to handle OAuth2 authentication
+* Added `Ruqqus::Client` class as the primary object for API usage
+    * Implemented post creation
+    * Implemented comment creation and deletion
+    * Implementing querying for reserved usernames/guilds
+    * Implemented retrieving posts of guilds
+    * Implemented retrieving posts and comments of users
+    * Implemented voting on posts and comments as a user
+    * Implemented enumerating all guilds
+    * Implemented enumerating through all posts
+* Refactored `Ruqqus.user_info` to `Ruqqus::Client#user`
+* Refactored `Ruqqus.guild_info` to `Ruqqus::Client#guild`
+* Refactored `Ruqqus.post_info` to `Ruqqus::Client#post`
+* Refactored `Ruqqus.comment_info` to `Ruqqus::Client#comment`
+* Many improvements in code and better adhesion to DRY principles
+* Added helper method to automate uploading and creating image posts on Ruqqus via Imgur
+
+## Version 1.0.1
+
+* Changed validation for `fomr_url` methods in `Post` and `Comment` to also accept relative URIs.
+
+## Version 1.0.0
 
 * Initial release, 100% coverage of existing Ruqqus API

data/Gemfile

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

data/README.md

@@ -6,14 +6,16 @@
 
 # Ruqqus
 
-A Ruby API implementation for [Ruqqus](https://ruqqus.com/), an [open-source](https://github.com/ruqqus/ruqqus) platform for online communities, free of censorship and moderator abuse by design. 
-
-While platform is still in Beta at this time and the public API for it is still quite limited, this gem will be actively updated as it continues to grow and is developed.
+A Ruby API implementation for [Ruqqus](https://ruqqus.com/), an [open-source](https://github.com/ruqqus/ruqqus) platform for online communities, free of censorship and moderator abuse by design. [Sign up](https://ruqqus.com/signup?ref=foreverzer0
+) if you haven't yet!
 
 [![Build Status](https://travis-ci.org/ForeverZer0/ruqqus.svg?branch=master)](https://travis-ci.org/ForeverZer0/ruqqus)
-[![Gem Version](https://badge.fury.io/rb/ruqqus.svg)](https://badge.fury.io/rb/ruqqus)
+[![Gem Version](https://badge.fury.io/rb/ruqqus.svg)](https://rubygems.org/gems/ruqqus)
 [![Inline docs](http://inch-ci.org/github/ForeverZer0/ruqqus.svg?branch=master)](http://inch-ci.org/github/ForeverZer0/ruqqus)
 [![Maintainability](https://api.codeclimate.com/v1/badges/c39f44a706302e4cd340/maintainability)](https://codeclimate.com/github/ForeverZer0/ruqqus/maintainability)
+[![OpenIssues](https://img.shields.io/github/issues/ForeverZer0/ruqqus)](https://github.com/ForeverZer0/ruqqus/issues)
+[![License](https://img.shields.io/github/license/ForeverZer0/ruqqus)](https://opensource.org/licenses/MIT)
+[![Ruby](https://img.shields.io/badge/powered%20by-ruby-red)](https://www.ruby-lang.org/en/)
 
 ## Installation
 
@@ -31,23 +33,148 @@ Or install it yourself as:
 
     $ gem install ruqqus
 
+To use the `ruqqus-oauth` helper to generate user tokens for desktop development:
+
+    $ gem install ruqqus --development
+
+## Authentication
+
+Ruqqus enables 3rd-party client authorization using the [OAuth2 protocol](https://oauth.net/2/). Before it is possible
+to interact with the API, you will need to first [register an application](https://ruqqus.com/settings/apps), which can
+be supply you with an API key/secret pair. This key will allow you to authorize users and grant privileges with a an
+assortment of scopes to fit your needs.
+
+### Desktop Development
+
+This gem includes a tool to automate obtaining a client code for users, primarily aimed for desktop developers who do
+not have a server running to receive the redirect URL. The tool requires the `mechanize` and `tty-prompt` gems, which
+are not included by default.
+
+To install the tool with its dependencies, install this gem with the following flag.
+
+    $ gem insall ruqqus --development
+
+Once installed, simply run `ruqqus-oauth`. You will be prompted to input the API key that was issued by Ruqqus to your
+approved application, and the user credentials for the account you with to authorize, such as that for a bot. Once
+executed, an authorization code will be displayed on-screen, which you can then use to create a token.
+
+```ruby
+require 'ruqqus'
+
+client_id     = 'XXXXXX' # Received after registering application
+client_secret = 'XXXXXX' # Received after registering application
+code          = 'XXXXXX' # The generated code (or the one you obtained via traditional means)
+
+# You must implement a responsible way of storing this token for reuse.
+token = Ruqqus::Token.new(client_id, client_secret, code)
+client = Ruqqus::Client.new(token)
+```
+
+The token will automatically refresh itself as-needed, but you will need to handle storing its new value for repeated
+uses. To facilitate this and make it easier, there is a callback that can be subscribed to which will be called each
+time the access key is updated.
+
+```ruby
+token = Ruqqus::Token.load_json('./token.json')
+token.on_refresh do |t|
+  t.save_json('./token.json')
+end
+
+client = Ruqqus::Client.new(token)
+```
+
+The token obtains sensitive material, and due to the security issues of storing it in plain text, this functionality is
+left to the user. The token is essentially the equivalent of your user credentials for Ruqqus, so bear that in mind how
+and where you store this information so that it is not compromised.
+
 ## Usage
 
-At this time, there are only four publicly exposed functions to utilize for acquiring information on the following items:
+See the [documentation](https://www.rubydoc.info/gems/ruqqus) for a complete API reference.
+
+### Features
+
+The bulk of the API is obviously related to performing actions as a user, such as posting, commenting, voting, etc.. The
+following highlights some of these features.
+
+* Vote on posts and comments
+* Create posts (text/link/image)
+* Automated image upload via anonymous upload to Imgur ([API Key](https://imgur.com/account/settings/apps) required) 
+* Create/edit/delete comments
+* Enumerate all existing guilds
+* Enumerate all posts in a guild
+* Enumerate all posts on the "front page", "all", etc., with sorting and filtering
+* Enumerate all posts/comments of users (excluding private/banned/blocked accounts)
+
+#### Misc. Examples
+
+Some random examples displaying the ease in performing various operations.
+
+##### Let's do some voting!
+```ruby
+client.each_user_post('captainmeta4') do |post|
+  # Upvote our fearless leader's posts
+  client.vote_post(post, 1)
+end
+
+client.each_user_comment('captainmeta4') do |comment|
+  # ...and his comments.
+  client.vote_comment(comment, 1)
+end
+```
+
+##### Monitor For New Posts
+```ruby
+delay = 10
+puts 'Watching for new posts, press Ctrl+C to quit'
+loop do
+  time = Time.now
+  sleep(delay)
+
+  puts "Checking the front page for new posts since #{time}"
+  client.each_post(sort: :new, filter: :all) do |post|
+    # Stop checking post once we encounter one older than this iteration
+    break if post.created < time
+    # Do something about this new post showing up in All
+    puts "Found a new post: '#{post.title}'"
+  end
+end
+```
+##### Download all images from a guild
+```ruby
+require 'open-uri'
+domains = %w[i.ruqqus.com i.imgur.com]
+
+Dir.mkdir('./tree_pics') unless Dir.exist?('./tree_pics')
+client.each_guild_post('Trees', sort: :new) do |post|
+  next unless domains.include?(post.domain)
+  ext = File.extname(post.url)
+  ext = '.jpg' if ext.empty? # We don't care, just an example
+  path = File.join('./tree_pics', post.id + ext)
+  URI.open(post.url) { |src| File.open(path, 'wb') { |dst| dst.write(src.read) } }
+end
+```
+
+### Types
+
+The Ruqqus API exposes four primary types:
 
 * Users
 * Guilds
 * Posts
 * Comments
 
-The full documentation can be found [here](https://www.rubydoc.info/gems/ruqqus), but the API is rather intuitive. Here is some basic examples to give a taste of its basic usage.
+Nearly all client operations interact with one or more of these entities in some way. Each of these types also has an
+`#id` property that can be used with other related API functions, such as voting, replying, deleting, etc. The full
+documentation listing all properties they obtain can be found [here](https://www.rubydoc.info/gems/ruqqus), but the API
+is rather intuitive. Here are some samples of their basic
+usage.
 
-### Users
+#### Users
 
 Obtain information about users.
 
 ```ruby
-user = Ruqqus.user('foreverzer0')
+user = client.user_info('foreverzer0')
 
 # Get user's total rep (as well as separate for comments/posts)
 user.total_rep
@@ -62,12 +189,12 @@ user.created
 #=> 2020-06-16 21:59:04 -0400
 ```
 
-### Guilds
+#### Guilds
 
 Obtain information about guilds.
 
 ```ruby
-guild = Ruqqus.guild('Ruby')
+guild = client.guild('Ruby')
 
 # Query the number of members, description, accent color, etc.
 guild.member_count
@@ -82,14 +209,16 @@ guild.nsfw?
 #=> false
 ```
 
-### Posts
+#### Posts
 
-Obtain information about posts. The API functions for querying comments from a post are not yet implemented on the backend, so you will have to settle for web-scraping with `mechanize`, `nokogiri`, etc. if that information is needed.
+Obtain information about posts.
 
 ```ruby
-post = Ruqqus.post('2e0x')
-# ...or alternatively
-post = Ruqqus::Post.from_url('https://ruqqus.com/post/2e0x/made-this-project-in-ruby-on')
+# Post IDs can be found within any link to a post.
+# https://ruqqus.com/post/<POST ID>/<POST TITLE>
+ 
+post_id = '2e0x'
+post = client.post(post_id)
 
 # Obtain relevant information pertaining the guilds on Ruqqus
   
@@ -106,27 +235,27 @@ post.score
 #=> 10
 ```
 
-### Comments
+#### Comments
 
 Obtain information about comments. Comments are very similar to posts, but have a few unique methods for obtaining their nesting level, parent post/comment, etc.
 
 ```ruby
-comment = Ruqqus.comment('67mt')
-# ...or alternatively
-comment = Ruqqus::Comment.from_url('https://ruqqus.com/post/1wbo/hi-im-josh-roehl-singer-and/67mt')
+# Post IDs can be found within any link to a post.
+# https://ruqqus.com/post/<POST ID>/<POST TITLE>/<COMMENT ID>
 
-comment.post.title
+comment_id = '67mt'
+comment = client.comment(comment_id)
+
+client.post(comment.post).title
 #=> "Hi. I'm Josh Roehl, singer and songwriter of the hit song \"Endless Summer\". I am hosting an AMA here."
  
 comment.body
 #=> "I'm fully aware that I'm not a very good singer. Let's call it half-singing, half-rapping." 
 
-comment.author.ban_reason
+client.user(comment.author_name).ban_reason
 #=> "Spam"
 ```
 
-[Documentation](https://www.rubydoc.info/gems/ruqqus)
-
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/ForeverZer0/ruqqus.

data/Rakefile

@@ -1,6 +1,5 @@
 require "bundler/gem_tasks"
 
-# Tests not implemented yet...
-task(:test) { |_| true }
+task(:test) { true }
 
 task default: :test

data/TODO.md

@@ -0,0 +1,27 @@
+# TODO
+
+A scratch pad for things to do and ideas to look into
+
+* Create and centralize all API endpoints into `Routes` module
+* Check for `json[:error]` in `http_get` and `http_post` for all calls?
+* Create examples in documentation
+* Update README with more examples
+* Create wiki on GitHub
+* Finish and cleanup and `ruqqus-oauth` app
+* Groups in documentation
+* Front page method?
+* Embed comment/posts API 
+
+# Missing API features
+
+Some API features that would be beneficial to have implemented
+
+* Flagging
+* Post deletion/edit (!)
+* Notifications (!)
+* NSFW/NSFW toggling
+* Kicking/Yanking
+* User Settings
+* Guild Settings
+* Guild join/leave
+* Follow/Unfollow users

data/exe/ruqqus-oauth

@@ -0,0 +1,98 @@
+#!/usr/bin/env ruby
+
+require 'mechanize'
+require 'tty-prompt'
+
+#noinspection RubyResolve
+class RuqqusOAuth
+
+  def initialize
+    prompt = TTY::Prompt.new
+    agent = Mechanize.new
+
+    prompt.warn('After inputting your client information and credentials of user')
+    prompt.warn('to authorize, and a code for token creation will be generated.')
+    puts
+    url = authorization_url(prompt)
+    login(agent, prompt)
+    prompt.say('Generating code...')
+    puts
+    code = generate_code(url, agent)
+    STDOUT << 'CODE: '
+    prompt.ok(code)
+  end
+
+  def authorization_url(prompt)
+    url = 'https://ruqqus.com/oauth/authorize'
+    url << "?client_id=#{ask_client_id(prompt)}"
+    url << "&redirect_uri=#{ask_client_redirect(prompt)}"
+    url << "&scope=#{ask_scopes(prompt)}"
+    url << "&state=#{SecureRandom.uuid.gsub('-', '')}"
+    url << '&permanent=true'
+    url
+  end
+
+  def generate_code(url, agent)
+    agent.get(url) do |page|
+      page.form_with(action: '/oauth/authorize').submit
+      /.*\?code=([a-zA-Z0-9_-]+)&?/.match(agent.history.last.uri.to_s)
+      return $1
+    end
+  end
+
+  def ask_client_id(prompt)
+    prompt.ask('Client ID: ') { |q| q.validate(/^[A-Fa-f0-9]+$/, "Invalid client ID") }
+  end
+
+  def ask_client_secret(prompt)
+    prompt.ask('Client Secret: ') { |q| q.validate(/^[A-Fa-f0-9]+$/, "Invalid client secret") }
+  end
+
+  def ask_client_redirect(prompt)
+    prompt.ask('Redirect URI: ', default: 'https://www.google.com') do |q|
+      proc = Proc.new { |v| URI.regexp =~ v && URI(v).scheme == 'https' }
+      q.validate(proc, 'Invalid HTTPS URI/scheme (must be HTTPS, not localhost)')
+    end
+  end
+
+  def ask_scopes(prompt)
+    msg = 'Select scopes the client is authorized to perform:'
+    choices = %i(identity create read update delete vote guildmaster)
+    scopes = prompt.multi_select(msg, choices, per_page: choices.size) do |q|
+      defaults = (1..choices.size).to_a
+      q.default(*defaults)
+    end
+    scopes.join(',')
+  end
+
+  def login(agent, prompt)
+    agent.get('https://ruqqus.com/login') do |page|
+      page.form_with(action: '/login') do |form|
+        form['username'] = prompt.ask('Username: ') do |q|
+          q.validate(/^[a-zA-Z0-9_]{5,25}$/, 'Invalid username')
+        end
+        form['password'] = prompt.mask("Password: ") do |q|
+          q.validate(/^.{8,100}$/, 'Invalid password')
+        end
+        puts 'Logging into Ruqqus...'
+      end.submit
+    end
+  end
+end
+
+begin
+  RuqqusOAuth.new
+rescue Interrupt
+  puts
+  # Ignored
+end
+
+
+
+
+
+
+
+
+
+

data/lib/ruqqus.rb

@@ -1,10 +1,10 @@
 require 'rest-client'
+require 'json'
 
-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 +15,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 +31,78 @@ 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.
+  # Helper function to automate uploading images to Imgur anonymously and returning the direct image link.
   #
-  # @return [User] the requested {User}.
+  # @param client_id [String] an Imgur client ID
+  # @param image_path [String] the path to an image file.
+  # @params 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
   #
-  # @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)
-  end
+  # @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?
 
-  ##
-  # 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 {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)
+    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)
+    available?(guild_name, VALID_GUILD, "#{Routes::GUILD_AVAILABLE}#{name}")
   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}.
-  #
-  # @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)
+  # @return [Boolean] `true` is name is available, otherwise `false` if it has been reserved or is in use.
+  def self.username_available?(username)
+    available?(username, VALID_USERNAME, "#{Routes::USERNAME_AVAILABLE}#{name}")
   end
 
+  private
+
   ##
-  # @api private
-  # Calls the GET method at the specified API route, and returns the deserializes JSON response as an object.
-  #
-  # @param route [String] the full API route to the GET method.
-  # @param klass [Class] a Class instance that is inherited from {ItemBase}.
+  # Checks if the specified guild or user name is available to be created.
   #
-  # @return [Object] an instance of the specified class.
+  # @param name [String] the name of a guild or username to query.
+  # @param regex [Regex] a validation regex for the name.
+  # @param route [String] the API endpoint to invoke.
   #
-  # @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')
-    end
+  # @return [Boolean] `true` is name is available, otherwise `false` if it has been reserved or is in use.
+  def self.available?(name, regex, route)
+    return false unless name && regex.match?(name)
+    json = JSON.parse(RestClient.get(route))
+    !!json[name]
   end
-end
-
+end