ruqqus 1.0.0 → 1.1.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a01559e849bc401630ad22455035ae0d00891f34e294eb00ea9780b82c932620
-  data.tar.gz: 56f99a8360fd71eb431dcf3d263f106412766f2afd51cdcda237aa643b9bb76d
+  metadata.gz: ddc434cd09ab2ab6f3c4460bd6d309e4311af4c6349e5fba9cdb89cc257133ab
+  data.tar.gz: 47f92d628a870e88ef893dea295c86e4bfd9b770b7fafa23caf988ba8bd3c798
 SHA512:
-  metadata.gz: 1417f32ba0e67970c1305c0f2cf48873fd6c4a6ffe5c6df98cb799f1459bf0ec364762a78f3eff4fb756b367e13650eeea7b8a62b516623e476b4d8488b7a167
-  data.tar.gz: 485fadd5ed20a3d6b1290ce709c9d5881f0f4a5ec890196fa16deff6b500ecfeb0f1f030a4dcc5eaeff853c9d2ac22a6180d080ed3cf583bf7679d2b9a10aa7c
+  metadata.gz: c01173a089510e8deb760dcab13144cfa5e5678ddfa5a2e136066c0de3d61cb192b30eadb461d28de588ba711c6ebe66d1c7b92fd83a8e2dff3694d51fb58611
+  data.tar.gz: 05ac950bf17799b45cfef60b3734f432c05906ab7caf8adf8b7e14898b53e46027284a671b9db32a70f45500382ff44dbec84e7b5fd12932ff76351e86d245ee

data/.gitignore

@@ -164,4 +164,8 @@ 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
+/test.rb

data/CHANGELOG.md

@@ -2,6 +2,53 @@
 
 Documentation for library API changes.
 
-## Version 1.0
+Versioning system:
+
+`MAJOR.MINOR.REVISION`
+
+* `MAJOR` Corresponds to the native Ruqqus API major version
+* `MINOR` Indicates possible breaking API changes for existing code
+* `REVISION` Added functionality, bug-fixes, and other non-breaking alterations
+
+## Version 1.1.3
+
+* Implemented browser-based confirmation process
+* Implemented capturing confirmation code from `localhost`  OAuth redirects
+* Fixed bug in querying guild/username availability
+
+## Version 1.1.2
+
+* Implemented enumerating comments of guilds and posts
+
+## Version 1.1.1
+
+* BUGFIX: Added acceptance of variable args to `Token#to_json`
+* BUGFIX: Fixed regex validator in `ruqqus-oauth` for the client ID
+* Separated the client ID/secret from the `Token` class, and placed within `Client` to now handle this logic
+
+## 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,156 @@ 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 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(client_id, client_secret, token)
+
+# Alternatively, you can create a new token and a client with a single call.
+# This will perform the "grant" action of the code while creating it automatically 
+client = Ruqqus::Client.new(client_id, client_secret, code)
+```
+
+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
+# Load an existing token that has already been authorized
+token = Ruqqus::Token.load_json('./token.json')
+
+# Create your client
+client = Ruqqus::Client.new(client_id, client_secret, token)
+
+# Set the callback block to automatically update the saved token when it refreshes
+client.token_refreshed do |t|
+  t.save_json('./token.json')
+end
+```
+
+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 (100% coverage).
+
+### 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 +197,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 +217,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 +243,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,25 @@
+# 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
+* 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-Za-z0-9_-]+$/, "Invalid client ID") }
+  end
+
+  def ask_client_secret(prompt)
+    prompt.ask('Client Secret: ') { |q| q.validate(/^[A-Za-z0-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
+
+
+
+
+
+
+
+
+
+