ruqqus 0.1.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bd42579f445107afb73ab5bddc39fda6140c1fed069b05f65dd9cf57553ae3d8
-  data.tar.gz: 7e4e2e8ef4de56a77004e94454ef47d0312d80de869efba80061214ae29bc729
+  metadata.gz: a01559e849bc401630ad22455035ae0d00891f34e294eb00ea9780b82c932620
+  data.tar.gz: 56f99a8360fd71eb431dcf3d263f106412766f2afd51cdcda237aa643b9bb76d
 SHA512:
-  metadata.gz: a5261490b9979f2c5817ad9ab8708862cae3e98870631ec6e31cdda4c068465a773bd08a54a5a3d04a3e7dc7bbcd8b655b03d9ec59ee9aa45d7cee84621b7c79
-  data.tar.gz: e48634320aafc078099254ae5b74e4222b1ea2b8b043c71bd76168b53607c56e58ca43b196da7ef0ead733439abc7c3f3006add27392f700c3a165dbcd3f37ab
+  metadata.gz: 1417f32ba0e67970c1305c0f2cf48873fd6c4a6ffe5c6df98cb799f1459bf0ec364762a78f3eff4fb756b367e13650eeea7b8a62b516623e476b4d8488b7a167
+  data.tar.gz: 485fadd5ed20a3d6b1290ce709c9d5881f0f4a5ec890196fa16deff6b500ecfeb0f1f030a4dcc5eaeff853c9d2ac22a6180d080ed3cf583bf7679d2b9a10aa7c

data/.gitignore

@@ -1,8 +1,167 @@
-/.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

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,6 @@
 
 Documentation for library API changes.
 
-## Version 0.1
+## Version 1.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
 gemspec
-
-gem "rake", "~> 12.0"
-gem "minitest", "~> 5.0"

data/README.md

@@ -1,8 +1,19 @@
+<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. 
+
+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.
 
-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://badge.fury.io/rb/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)
 
 ## Installation
 
@@ -22,18 +33,103 @@ Or install it yourself as:
 
 ## Usage
 
-TODO: Write usage instructions here
+At this time, there are only four publicly exposed functions to utilize for acquiring information on the following items:
 
-## Development
+* Users
+* Guilds
+* Posts
+* Comments
 
-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 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.
 
-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).
+### Users
 
-## Contributing
+Obtain information about users.
+
+```ruby
+user = Ruqqus.user('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 = Ruqqus.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. 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.
+
+```ruby
+post = Ruqqus.post('2e0x')
+# ...or alternatively
+post = Ruqqus::Post.from_url('https://ruqqus.com/post/2e0x/made-this-project-in-ruby-on')
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/ruqqus.
+# 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
+comment = Ruqqus.comment('67mt')
+# ...or alternatively
+comment = Ruqqus::Comment.from_url('https://ruqqus.com/post/1wbo/hi-im-josh-roehl-singer-and/67mt')
+
+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
+#=> "Spam"
+```
+
+[Documentation](https://www.rubydoc.info/gems/ruqqus)
+
+## Contributing
 
+Bug reports and pull requests are welcome on GitHub at https://github.com/ForeverZer0/ruqqus.
 
 ## License
 

data/Rakefile

@@ -1,10 +1,6 @@
 require "bundler/gem_tasks"
-require "rake/testtask"
 
-Rake::TestTask.new(:test) do |t|
-  t.libs << "test"
-  t.libs << "lib"
-  t.test_files = FileList["test/**/*_test.rb"]
-end
+# Tests not implemented yet...
+task(:test) { |_| true }
 
-task :default => :test
+task default: :test

data/lib/ruqqus.rb

@@ -1,7 +1,125 @@
+require 'rest-client'
+
+require_relative 'ruqqus/item_base'
+require_relative 'ruqqus/comment'
+require_relative 'ruqqus/guild'
+require_relative 'ruqqus/post'
+require_relative 'ruqqus/user'
 require_relative 'ruqqus/version'
 
+##
+# Top-level namespace of the Ruqqus gem.
 module Ruqqus
 
-  class Error < StandardError; end
+  ##
+  # 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
+
+  ##
+  # A regular expression used for password validation.
+  VALID_PASSWORD= /^.{8,100}$/.freeze
+
+  ##
+  # A regular expression used for guild name validation.
+  VALID_GUILD = /^[a-zA-Z0-9][a-zA-Z0-9_]{2,24}$/.freeze
+
+  ##
+  # A regular expression used for post/comment ID validation.
+  VALID_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.
+  #
+  # @return [User] the requested {User}.
+  #
+  # @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
+
+  ##
+  # 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)
+  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 {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)
+  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 {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)
+  end
+
+  ##
+  # @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}.
+  #
+  # @return [Object] an instance of the specified class.
+  #
+  # @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
+  end
 end
+

data/lib/ruqqus/badge.rb

@@ -0,0 +1,61 @@
+module Ruqqus
+  ##
+  # Describes a trophy that can be earned/issued to an account for specific accomplishments.
+  class Badge
+
+    ##
+    # @!attribute [r] name
+    #   @return [String?] the name of the badge.
+
+    ##
+    # @!attribute [r] text
+    #   @return [String?] a brief description of the badge.
+
+    ##
+    # @!attribute [r] url
+    #   @return [String?] the URL associated with the badge, or `nil` if not defined.
+
+    ##
+    # @!attribute [r] created_utc
+    #   @return [Integer?] the time the badge was earned in seconds since the Unix epoch, or `0` if not defined.
+
+    ##
+    # @!attribute [r] created
+    #   @return [Time?] the time the badge was earned, or `nil` if not defined.
+
+    ##
+    # Creates a new instance of the {Badge} class.
+    #
+    # @param data [Hash] the parsed JSON payload defining this instance.
+    def initialize(data)
+      @data = data || raise(ArgumentError, 'data cannot be nil')
+    end
+
+    def name
+      @data[:name]
+    end
+
+    def text
+      @data[:text]
+    end
+
+    def url
+      @data[:url]
+    end
+
+    def created_utc
+      @data[:created_utc]
+    end
+
+    def created
+      #noinspection RubyYardReturnMatch
+      @data[:created_utc] ? Time.at(@data[:created_utc]) : nil
+    end
+
+    ##
+    # @return [String] the string representation of the object.
+    def to_s
+      @data[:text] || inspect
+    end
+  end
+end

data/lib/ruqqus/comment.rb

@@ -0,0 +1,61 @@
+require_relative 'submission'
+
+module Ruqqus
+
+  ##
+  # Describes a comment in a post.
+  class Comment < Submission
+
+    ##
+    # Captures the ID of a comment from a Ruqqus URL
+    COMMENT_REGEX = /ruqqus.com\/post\/.+\/.+\/([A-Za-z0-9]+)\/?/.freeze
+
+    ##
+    # @return [Integer] the level of "nesting" in the comment tree, starting at `1` when in direct reply to the post.
+    def level
+      @data[:level]
+    end
+
+    ##
+    # @return [String] the unique ID of the parent for this comment.
+    def parent_id
+      @data[:parent]
+    end
+
+    ##
+    # @return [Post,Comment] the parent for this content.
+    def parent
+      #noinspection RubyYardReturnMatch
+      @parent ||= level > 1 ? Ruqqus.comment(parent_id) : Ruqqus.post(parent_id)
+    end
+
+    ##
+    # @return [String] the ID of the post this comment belongs to.
+    def post_id
+      @data[:post]
+    end
+
+    ##
+    # @return [Post] the post this comment belongs to.
+    def post
+      #noinspection RubyYardReturnMatch
+      Ruqqus.post(post_id)
+    end
+
+    ##
+    # Creates a new {Comment} instance from the specified URL.
+    #
+    # @param url [String] a URL link to a comment.
+    #
+    # @return [Comment] the {Comment} instance the URL links to.
+    #
+    # @raise [ArgumentError] then `url` is `nil`.
+    # @raise [Ruqqus::Error] when the link is not for a Ruqqus comment.
+    def self.from_url(url)
+      raise(ArgumentError, 'url cannot be nil') unless url
+      match = COMMENT_REGEX.match(url)
+      raise(ArgumentError, 'invalid URL for a comment') unless match
+      Ruqqus.comment($1)
+    end
+  end
+end

data/lib/ruqqus/guild.rb

@@ -0,0 +1,85 @@
+module Ruqqus
+
+  ##
+  # Represents a Ruqqus guild.
+  class Guild < ItemBase
+
+    ##
+    # @return [String] the name of the guild.
+    def name
+      @data[:name]
+    end
+
+    ##
+    # @return [Integer] the number of members subscribed to the guild.
+    def member_count
+      @data[:subscriber_count]&.to_i || 0
+    end
+
+    ##
+    # @return [Integer] the number of guild masters who moderate this guild.
+    def gm_count
+      @data[:mods_count]&.to_i || 0
+    end
+
+    ##
+    # @return [String] the full ID of the guild.
+    def full_name
+      @data[:fullname]
+    end
+
+    ##
+    # @return [Boolean] `true` if the guild contains adult content and flagged as NSFW, otherwise `false`.
+    def nsfw?
+      @data[:over_18]
+    end
+
+    ##
+    # @return [Boolean] `true` if guild is private and required membership to view content, otherwise `false`.
+    def private?
+      !!@data[:is_private]
+    end
+
+    ##
+    # @return [Boolean] `true` if posting is restricted byy guild masters, otherwise `false`.
+    def restricted?
+      !!@data[:is_restricted]
+    end
+
+    ##
+    # @return [String] the description of the guild.
+    def description
+      @data[:description]
+    end
+
+    ##
+    # @return [String] the description of the guild in HTML format.
+    def description_html
+      @data[:description_html]
+    end
+
+    ##
+    # @return [String] the URL for the banner image associated with the guild.
+    def banner_url
+      @data[:banner_url]
+    end
+
+    ##
+    # @return [String] the URL for the profile image associated with the guild.
+    def profile_url
+      @data[:profile_url]
+    end
+
+    ##
+    # @return [String] the accent color used for the guild, in HTML format.
+    def color
+      @data[:color]
+    end
+
+    ##
+    # @return [String] the string representation of the object.
+    def to_s
+      @data[:name] || inspect
+    end
+  end
+end

data/lib/ruqqus/item_base.rb

@@ -0,0 +1,58 @@
+require 'json'
+
+module Ruqqus
+
+  ##
+  # @abstract
+  # Base class for all all major API types.
+  class ItemBase
+
+    ##
+    # @return [Boolean] `true` if item has been banned, otherwise `false`.
+    def banned?
+      !!@data[:is_banned]
+    end
+
+    ##
+    # @return [Integer] the time the item was created, in seconds since the Unix epoch.
+    def created_utc
+      @data[:created_utc]
+    end
+
+    ##
+    # @return [Time] the time the item was created.
+    def created
+      Time.at(created_utc)
+    end
+
+    ##
+    # @return [String] a unique ID for this item.
+    def id
+      @data[:id]
+    end
+
+    ##
+    # @return [Boolean] `true` if this object is equal to another, otherwise `false`.
+    def ==(other)
+      self.class == other.class && id == other.id
+    end
+
+    ##
+    # @return [String] a relative link to this item.
+    def permalink
+      @data[:permalink]
+    end
+
+    ##
+    # Loads the object from a JSON-formatted string.
+    #
+    # @return [Object] the loaded object.
+    def self.from_json(json)
+      obj = allocate
+      obj.instance_variable_set(:@data, JSON.parse(json, symbolize_names: true))
+      obj
+    end
+
+    private_class_method :new
+  end
+end

data/lib/ruqqus/post.rb

@@ -0,0 +1,85 @@
+require_relative 'submission'
+
+module Ruqqus
+
+  ##
+  # Represents a post on Ruqqus.
+  class Post < Submission
+
+    ##
+    # Captures the ID of a post from a Ruqqus URL
+    POST_REGEX = /ruqqus.com\/post\/([A-Za-z0-9]+)\/?.*/.freeze
+
+    ##
+    # @return [Title?] the title assigned to the author, or `nil` if none is defined.
+    def author_title
+      #noinspection RubyYardReturnMatch
+      @author_title ||= @data[:author_title] ? Title.new(@data[:author_title]) : nil
+    end
+
+    ##
+    # @return [Integer] the number of comments made on the post.
+    def comment_count
+      @data[:comment_count]
+    end
+
+    ##
+    # @return [String] the domain name for link posts, otherwise a short descriptor of the post type.
+    def domain
+      @data[:domain]
+    end
+
+    ##
+    # @return [String] the embed URL for the post.
+    def embed_url
+      @data[:embed_url]
+    end
+
+    ##
+    # @return [String] the name of the guild this post was originally posted in.
+    def original_guild_name
+      @data[:original_guild_name]
+    end
+
+    ##
+    # @return [Guild] the guild this post was originally posted in.
+    def original_guild
+      @original_guild ||= Ruqqus.guild(original_guild_name)
+    end
+
+    ##
+    # @return [String?] the URL of the post's thumbnail image, or `nil` if none exists.
+    def thumb_url
+      @data[:thumb_url]
+    end
+
+    ##
+    # @return [String?] the URL the post links to, or `nil` if none is specified.
+    def url
+      #noinspection RubyYardReturnMatch
+      @data[:url]&.empty? ? nil : @data[:url]
+    end
+
+    ##
+    # @return [String] the string representation of the object.
+    def to_s
+      @data[:title] || inspect
+    end
+
+    ##
+    # Creates a new {Post} instance from the specified URL.
+    #
+    # @param url [String] a URL link to a post.
+    #
+    # @return [Post] the {Post} instance the URL links to.
+    #
+    # @raise [ArgumentError] then `url` is `nil`.
+    # @raise [Ruqqus::Error] when the link is not for a Ruqqus post.
+    def self.from_url(url)
+      raise(ArgumentError, 'url cannot be nil') unless url
+      match = POST_REGEX.match(url)
+      raise(ArgumentError, 'invalid URL for a post') unless match
+      Ruqqus.post($1)
+    end
+  end
+end

data/lib/ruqqus/submission.rb

@@ -0,0 +1,132 @@
+require_relative 'item_base'
+
+module Ruqqus
+
+  ##
+  # @abstract
+  # Base class for {Post} and {Comment} types.
+  class Submission < ItemBase
+
+    ##
+    # @return [String?] the name of the creator of the item, or `nil` if deleted account.
+    def author_name
+      @data[:author]
+    end
+
+    ##
+    # @return [String] the creator of the item, or `nil` if deleted account.
+    def author
+      #noinspection RubyYardReturnMatch
+      @author ||= author_name ? Ruqqus.user(author_name) : nil
+    end
+
+    ##
+    # @return [String] the text body of the item.
+    def body
+      @data[:body]
+    end
+
+    ##
+    # @return [String] the text body of the item in HTML format.
+    def body_html
+      @data[:body_html]
+    end
+
+    ##
+    # @return [Integer] the time of the last edit in seconds since the Unix epoch, or `0` if never edited.
+    def last_edit_utc
+      @data[:edited_utc]
+    end
+
+    ##
+    # @return [Time] the time of the last edit.
+    def last_edit
+      Time.at(@data[:edited_utc])
+    end
+
+    ##
+    # @return [Boolean] `true` if post has been edited, otherwise `false`.
+    def edited?
+      @data[:edited_utc] != 0
+    end
+
+    ##
+    # @return [Integer] the number of upvotes this item has received.
+    def upvotes
+      @data[:upvotes]
+    end
+
+    ##
+    # @return [Integer] the number of downvotes this item has received.
+    def downvotes
+      @data[:downvotes]
+    end
+
+    ##
+    # @return [Integer] a score calculated by adding upvotes and subtracting downvotes.
+    def score
+      @data[:score]
+    end
+
+    ##
+    # @return [Boolean] `true` if item is adult content and flagged as NSFW, otherwise `false`.
+    def nsfw?
+      !!@data[:is_nsfw]
+    end
+
+    ##
+    # @return [Boolean] `true` if item is adult content and flagged as NSFL, otheriwse `false`.
+    def nsfl?
+      !!@data[:is_nsfl]
+    end
+
+    ##
+    # @return [Boolean] `true` if item has been archived, otherwise `false`.
+    def archived?
+      !!@data[:is_archived]
+    end
+
+    ##
+    # @return [Boolean] `true` if item has been deleted, otherwise `false`.
+    def deleted?
+      !!@data[:is_deleted]
+    end
+
+    ##
+    # @return [Boolean] `true` if item has been classified has offensive, otherwise `false`.
+    def offensive?
+      !!@data[:is_offensive]
+    end
+
+    ##
+    # @return [String] the full ID of this item.
+    def full_name
+      @data[:fullname]
+    end
+
+    ##
+    # @return [String] the name of the guild this item is contained within.
+    def guild_name
+      @data[:guild_name]
+    end
+
+    ##
+    # @return [Guild?] the guild this item is contained within.
+    def guild
+      #noinspection RubyYardReturnMatch
+      @guild ||= guild_name ? Ruqqus.guild(guild_name) : nil
+    end
+
+    ##
+    # @return [String] a unique ID associated with this item.
+    def id
+      @data[:id]
+    end
+
+    ##
+    # @return [String] the name/title of this item.
+    def title
+      @data[:title]
+    end
+  end
+end

data/lib/ruqqus/title.rb

@@ -0,0 +1,48 @@
+
+module Ruqqus
+
+  ##
+  # Describes a title associated with a username.
+  class Title
+
+    ##
+    # @!attribute [r] id
+    #   @return [Integer] a unique ID associated with this title.
+
+    ##
+    # @!attribute [r] text
+    #   @return [String] the text value of the title.
+
+    ##
+    # @!attribute [r] color
+    #   @return [String] the color used to display the title in HTML format.
+
+    ##
+    # @!attribute [r] kind
+    #   @return [Integer] an integer determining the "rank" of the title.
+
+    ##
+    # Creates a new instance of the {Title} class.
+    #
+    # @param data [Hash] the parsed JSON payload defining this instance.
+    def initialize(data)
+      @data = data || raise(ArgumentError, 'data cannot be nil')
+    end
+
+    def id
+      @data[:id]
+    end
+
+    def text
+      @data[:text]
+    end
+
+    def color
+      @data[:color]
+    end
+
+    def kind
+      @data[:kind]
+    end
+  end
+end

data/lib/ruqqus/user.rb

@@ -0,0 +1,96 @@
+require_relative 'badge'
+require_relative 'title'
+require_relative 'item_base'
+
+module Ruqqus
+
+  ##
+  # Represents a Ruqqus user account.
+  class User < ItemBase
+
+    ##
+    # @return [Integer] the number of comments the user has created.
+    def comment_count
+      @data[:comment_count] || 0
+    end
+
+    ##
+    # @return [Integer] the number of posts the user has created.
+    def post_count
+      @data[:post_count] || 0
+    end
+
+    ##
+    # @return [Integer] the amount of rep the user has earned from comments.
+    def comment_rep
+      @data[:comment_rep] || 0
+    end
+
+    ##
+    # @return [Integer] the amount of rep the user has earned from posts.
+    def post_rep
+      @data[:post_rep] || 0
+    end
+
+    ##
+    # @return [Integer] the total amount of rep the user has earned from comments and posts.
+    def total_rep
+      comment_rep + post_rep
+    end
+
+    ##
+    # @return [String] the username of the account.
+    def username
+      @data[:username]
+    end
+
+    ##
+    # @return [Array<Badge>] an array of badges associated with this account.
+    def badges
+      @badges ||= @data[:badges].map { |b| Badge.new(b) }
+    end
+
+    ##
+    # @return [Title?] the title the user has associated with their account, or `nil` if none is assigned.
+    def title
+      #noinspection RubyYardReturnMatch
+      @title ||= @data[:title] ? Title.new(@data[title]) : nil
+    end
+
+    ##
+    # @return [String] the URL for the banner image associated with the account.
+    def banner_url
+      @data[:banner_url]
+    end
+
+    ##
+    # @return [String] the URL for the profile image associated with the account.
+    def profile_url
+      @data[:profile_url]
+    end
+
+    ##
+    # @return [String] A brief statement/biography the user has associated with their account.
+    def bio
+      @data[:bio]
+    end
+
+    ##
+    # @return [String] a brief statement/biography the user has associated with their account in HTML format.
+    def bio_html
+      @data[:bio_html]
+    end
+
+    ##
+    # @return [String?] the reason the user was banned if they were, otherwise `nil`.
+    def ban_reason
+      @data[:ban_reason]
+    end
+
+    ##
+    # @return [String] the string representation of the object.
+    def to_s
+      @data[:username] || inspect
+    end
+  end
+end

data/lib/ruqqus/version.rb

@@ -1,3 +1,12 @@
 module Ruqqus
-  VERSION = "0.1.0"
+
+  ##
+  # The Ruqqus gem version.
+  VERSION = '1.0.0'.freeze
+
+  ##
+  # Lulz
+  ENDLESS_SUMMER = 'https://youtu.be/o_LskiXQ73c'.freeze
+
+  private_constant(:ENDLESS_SUMMER)
 end

data/ruqqus.gemspec

@@ -2,20 +2,24 @@ require_relative 'lib/ruqqus/version'
 
 Gem::Specification.new do |spec|
 
+  # Required specifications
   spec.name          = 'ruqqus'
   spec.version       = Ruqqus::VERSION
   spec.authors       = ['ForeverZer0']
   spec.email         = ['efreed09@gmail.com']
-
-  spec.summary       = %q{Base library for interacting with the ruqqus.com API.}
-  spec.description   = %q{Base library for interacting with the ruqqus.com API.}
+  spec.summary       = %q{A Ruby API implementation for Ruqqus, an open-source platform for online communities, free of censorship and moderator abuse by design.}
+  spec.description   = %q{A Ruby API implementation for Ruqqus, an open-source 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.}
   spec.homepage      = 'https://github.com/ForeverZer0/ruqqus'
   spec.license       = 'MIT'
   spec.required_ruby_version = Gem::Requirement.new('>= 2.3.0')
 
-  spec.metadata['homepage_uri'] = spec.homepage
-  spec.metadata['source_code_uri'] = 'https://github.com/ForeverZer0/ruqqus'
-  spec.metadata['changelog_uri'] = 'https://github.com/ForeverZer0/ruqqus/CHANGELOG.md'
+  # Metadata
+  spec.metadata['allowed_push_host'] = 'https://rubygems.org'
+  spec.metadata['homepage_uri']      = spec.homepage
+  spec.metadata['source_code_uri']   = 'https://github.com/ForeverZer0/ruqqus'
+  spec.metadata['changelog_uri']     = 'https://github.com/ForeverZer0/ruqqus/CHANGELOG.md'
+  spec.metadata['documentation_uri'] = 'https://www.rubydoc.info/gems/ruqqus'
+  spec.metadata['bug_tracker_uri']   = 'https://github.com/ForeverZer0/ruqqus/issues'
 
   # Specify which files should be added to the gem when it is released.
   # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
@@ -23,9 +27,14 @@ Gem::Specification.new do |spec|
     `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
   end
 
+  # Register executables (none yet...)
   spec.bindir        = 'exe'
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ['lib']
 
-  spec.add_runtime_dependency('nokogiri', '~> 1.10')
+  # Dependencies
+  spec.add_runtime_dependency('rest-client', '~> 2.1')
+
+  spec.add_development_dependency('rake', '~> 13.0')
+  spec.add_development_dependency('yard', '~> 0.9')
 end

metadata

@@ -1,30 +1,61 @@
 --- !ruby/object:Gem::Specification
 name: ruqqus
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 1.0.0
 platform: ruby
 authors:
 - ForeverZer0
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2020-08-25 00:00:00.000000000 Z
+date: 2020-08-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
-  name: nokogiri
+  name: rest-client
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.10'
+        version: '2.1'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.10'
-description: Base library for interacting with the ruqqus.com API.
+        version: '2.1'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+description: A Ruby API implementation for Ruqqus, an open-source 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.
 email:
 - efreed09@gmail.com
 executables: []
@@ -33,6 +64,7 @@ extra_rdoc_files: []
 files:
 - ".gitignore"
 - ".travis.yml"
+- ".yardopts"
 - CHANGELOG.md
 - Gemfile
 - LICENSE.txt
@@ -41,15 +73,26 @@ files:
 - bin/console
 - bin/setup
 - lib/ruqqus.rb
+- lib/ruqqus/badge.rb
+- lib/ruqqus/comment.rb
+- lib/ruqqus/guild.rb
+- lib/ruqqus/item_base.rb
+- lib/ruqqus/post.rb
+- lib/ruqqus/submission.rb
+- lib/ruqqus/title.rb
+- lib/ruqqus/user.rb
 - lib/ruqqus/version.rb
 - ruqqus.gemspec
 homepage: https://github.com/ForeverZer0/ruqqus
 licenses:
 - MIT
 metadata:
+  allowed_push_host: https://rubygems.org
   homepage_uri: https://github.com/ForeverZer0/ruqqus
   source_code_uri: https://github.com/ForeverZer0/ruqqus
   changelog_uri: https://github.com/ForeverZer0/ruqqus/CHANGELOG.md
+  documentation_uri: https://www.rubydoc.info/gems/ruqqus
+  bug_tracker_uri: https://github.com/ForeverZer0/ruqqus/issues
 post_install_message:
 rdoc_options: []
 require_paths:
@@ -68,5 +111,6 @@ requirements: []
 rubygems_version: 3.1.4
 signing_key:
 specification_version: 4
-summary: Base library for interacting with the ruqqus.com API.
+summary: A Ruby API implementation for Ruqqus, an open-source platform for online
+  communities, free of censorship and moderator abuse by design.
 test_files: []