ruqqus 0.1.0 → 1.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bd42579f445107afb73ab5bddc39fda6140c1fed069b05f65dd9cf57553ae3d8
-  data.tar.gz: 7e4e2e8ef4de56a77004e94454ef47d0312d80de869efba80061214ae29bc729
+  metadata.gz: 1274eade9799203bd720c94da255a81a0e0295da9e438519a687626c1db7f0b7
+  data.tar.gz: 96fe1b73d77d38004981f476ddca3acde81577755de6939f77c6c4ea65fdc693
 SHA512:
-  metadata.gz: a5261490b9979f2c5817ad9ab8708862cae3e98870631ec6e31cdda4c068465a773bd08a54a5a3d04a3e7dc7bbcd8b655b03d9ec59ee9aa45d7cee84621b7c79
-  data.tar.gz: e48634320aafc078099254ae5b74e4222b1ea2b8b043c71bd76168b53607c56e58ca43b196da7ef0ead733439abc7c3f3006add27392f700c3a165dbcd3f37ab
+  metadata.gz: da793dbcee6ae0cd28b6f5160f85a752804a44ceb00f295291209e2529a3ba39ed26300f43b8b9df95f4ce41b7c3c10b97f60550eed9b9ce5c27c50b4252a638
+  data.tar.gz: 92b77622dcaf2fa8129e013465a91186d1de731eb927bcd219fac8160c7afccceb2beecf4f509f7e3b9fe95c8b9431955d301566eeaa5608302a2331ce87743c

data/.gitignore

@@ -1,8 +1,171 @@
-/.bundle/
-/.yardoc
-/_yardoc/
+
+# Created by https://www.toptal.com/developers/gitignore/api/ruby,rubymine+all,visualstudiocode
+# Edit at https://www.toptal.com/developers/gitignore?templates=ruby,rubymine+all,visualstudiocode
+
+### Ruby ###
+*.gem
+*.rbc
+/.config
 /coverage/
-/doc/
+/InstalledFiles
 /pkg/
 /spec/reports/
+/spec/examples.txt
+/test/tmp/
+/test/version_tmp/
 /tmp/
+
+# Used by dotenv library to load environment variables.
+# .env
+
+# Ignore Byebug command history file.
+.byebug_history
+
+## Specific to RubyMotion:
+.dat*
+.repl_history
+build/
+*.bridgesupport
+build-iPhoneOS/
+build-iPhoneSimulator/
+
+## Specific to RubyMotion (use of CocoaPods):
+#
+# We recommend against adding the Pods directory to your .gitignore. However
+# you should judge for yourself, the pros and cons are mentioned at:
+# https://guides.cocoapods.org/using/using-cocoapods.html#should-i-check-the-pods-directory-into-source-control
+# vendor/Pods/
+
+## Documentation cache and generated files:
+/.yardoc/
+/_yardoc/
+/doc/
+/rdoc/
+
+## Environment normalization:
+/.bundle/
+/vendor/bundle
+/lib/bundler/man/
+
+# for a library or gem, you might want to ignore these files since the code is
+# intended to run in multiple environments; otherwise, check them in:
+Gemfile.lock
+# .ruby-version
+# .ruby-gemset
+
+# unless supporting rvm < 1.11.0 or doing something fancy, ignore this:
+.rvmrc
+
+# Used by RuboCop. Remote config files pulled in from inherit_from directive.
+# .rubocop-https?--*
+
+### Ruby Patch ###
+# Used by RuboCop. Remote config files pulled in from inherit_from directive.
+# .rubocop-https?--*
+
+### RubyMine+all ###
+# Covers JetBrains IDEs: IntelliJ, RubyMine, PhpStorm, AppCode, PyCharm, CLion, Android Studio, WebStorm and Rider
+# Reference: https://intellij-support.jetbrains.com/hc/en-us/articles/206544839
+
+# User-specific stuff
+.idea/**/workspace.xml
+.idea/**/tasks.xml
+.idea/**/usage.statistics.xml
+.idea/**/dictionaries
+.idea/**/shelf
+
+# Generated files
+.idea/**/contentModel.xml
+
+# Sensitive or high-churn files
+.idea/**/dataSources/
+.idea/**/dataSources.ids
+.idea/**/dataSources.local.xml
+.idea/**/sqlDataSources.xml
+.idea/**/dynamic.xml
+.idea/**/uiDesigner.xml
+.idea/**/dbnavigator.xml
+
+# Gradle
+.idea/**/gradle.xml
+.idea/**/libraries
+
+# Gradle and Maven with auto-import
+# When using Gradle or Maven with auto-import, you should exclude module files,
+# since they will be recreated, and may cause churn.  Uncomment if using
+# auto-import.
+# .idea/artifacts
+# .idea/compiler.xml
+# .idea/jarRepositories.xml
+# .idea/modules.xml
+# .idea/*.iml
+# .idea/modules
+# *.iml
+# *.ipr
+
+# CMake
+cmake-build-*/
+
+# Mongo Explorer plugin
+.idea/**/mongoSettings.xml
+
+# File-based project format
+*.iws
+
+# IntelliJ
+out/
+
+# mpeltonen/sbt-idea plugin
+.idea_modules/
+
+# JIRA plugin
+atlassian-ide-plugin.xml
+
+# Cursive Clojure plugin
+.idea/replstate.xml
+
+# Crashlytics plugin (for Android Studio and IntelliJ)
+com_crashlytics_export_strings.xml
+crashlytics.properties
+crashlytics-build.properties
+fabric.properties
+
+# Editor-based Rest Client
+.idea/httpRequests
+
+# Android studio 3.1+ serialized cache file
+.idea/caches/build_file_checksums.ser
+
+### RubyMine+all Patch ###
+# Ignores the whole .idea folder and all .iml files
+# See https://github.com/joeblau/gitignore.io/issues/186 and https://github.com/joeblau/gitignore.io/issues/360
+
+.idea/
+
+# Reason: https://github.com/joeblau/gitignore.io/issues/186#issuecomment-249601023
+
+*.iml
+modules.xml
+.idea/misc.xml
+*.ipr
+
+# Sonarlint plugin
+.idea/sonarlint
+
+### VisualStudioCode ###
+.vscode/*
+!.vscode/settings.json
+!.vscode/tasks.json
+!.vscode/launch.json
+!.vscode/extensions.json
+*.code-workspace
+
+### VisualStudioCode Patch ###
+# Ignore all local history of files
+.history
+
+# 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/.yardopts

@@ -0,0 +1,6 @@
+--readme README.md
+--title 'Ruqqus'
+--charset utf-8
+--markup markdown
+--protected
+lib/**/*.rb

data/CHANGELOG.md

@@ -2,7 +2,53 @@
 
 Documentation for library API changes.
 
-## Version 0.1
+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,7 +1,4 @@
-source "https://rubygems.org"
+source 'https://rubygems.org'
 
-# Specify your gem's dependencies in ruqqus.gemspec
+# Dependencies specified in ruqqus.gemspec
 gemspec
-
-gem "rake", "~> 12.0"
-gem "minitest", "~> 5.0"

data/README.md

@@ -1,8 +1,21 @@
+<p align="center">
+<img src="https://raw.githubusercontent.com/ruqqus/ruqqus/master/ruqqus/assets/images/logo/ruqqus_text_logo.png" width="250"/>
+</p>
+
+<hr>
+
 # Ruqqus
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/ruqqus`. To experiment with that code, run `bin/console` for an interactive prompt.
+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!
 
-TODO: Delete this and the text above, and describe your gem
+[![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://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
 
@@ -20,20 +33,240 @@ 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
 
-TODO: Write usage instructions here
+See the [documentation](https://www.rubydoc.info/gems/ruqqus) for a complete API reference (100% coverage).
 
-## Development
+### Features
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+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.
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+* 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)
 
-## Contributing
+#### 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
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/ruqqus.
+The Ruqqus API exposes four primary types:
+
+* Users
+* Guilds
+* Posts
+* Comments
+
+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
+
+Obtain information about users.
+
+```ruby
+user = client.user_info('foreverzer0')
+
+# Get user's total rep (as well as separate for comments/posts)
+user.total_rep
+#=> 22234
+
+# Enumerate earned badges
+user.badges.map(&:to_s)
+#=> ["Joined Ruqqus during open beta", "Verified Email", "Recruited 10 friends to join Ruqqus"]
+
+# Retrieve a Time object for when user created account
+user.created
+#=> 2020-06-16 21:59:04 -0400
+```
+
+#### Guilds
+
+Obtain information about guilds.
+
+```ruby
+guild = client.guild('Ruby')
+
+# Query the number of members, description, accent color, etc.
+guild.member_count
+#=> 43
+
+# Links to guild's banner, profile, etc.
+guild.banner_url
+#=> "https://i.ruqqus.com/board/ruby/banner-2.png"
+
+# Check for flags such as NSFW, NSFL, deletion, banned, "offensive", etc.
+guild.nsfw?
+#=> false
+```
+
+#### Posts
+
+Obtain information about posts.
+
+```ruby
+# 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
+  
+post.author_name
+#=> "Galadriel"
+
+post.title
+#=> "Made this project in Ruby On Rails"
+
+post.url
+#=> "https://ruqqus-metrics.com/"
+
+post.score
+#=> 10
+```
+
+#### 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
+# Post IDs can be found within any link to a post.
+# https://ruqqus.com/post/<POST ID>/<POST TITLE>/<COMMENT ID>
+
+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." 
+
+client.user(comment.author_name).ban_reason
+#=> "Spam"
+```
+
+## Contributing
 
+Bug reports and pull requests are welcome on GitHub at https://github.com/ForeverZer0/ruqqus.
 
 ## License