ruqqus 1.1.0 → 1.1.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bb4087c263dae6ef0708a07d756733ea19f95e1e6f02983c658c9cfb40a2f475
-  data.tar.gz: d9d71b14897ec30ea1f5356916d1eb2cc432db02e7c007fb5f8efcea3a3f37fa
+  metadata.gz: 62b35161bf5278e264c66836f39a80de3492dcd627f7e1e9d701a5439af30649
+  data.tar.gz: 0cbc0628bcceebaac0770ed2c2fa5558d632ab3f02f5c7c9deb500f9552c3e4f
 SHA512:
-  metadata.gz: f5864e192920e53c59921cf9bdb7d2f2acaf261d77ed4c0d3184a7f601cf967cf87f358c4b396705b8366fcda6ed3d54a9a125b0f13e7e139d0ce3ff0f67535e
-  data.tar.gz: 73d7d5b8a4551a7bc83efd54b8be72107a010f4023dc9784396dddce8ceae4808049cc6fed37487b07e259b6efc41a1ff75d8184bf5ce28f18f8c261e2ffd0e4
+  metadata.gz: da177c6d90e02598bb5438d79b3c0fca5219922a1bda1d20a67e458be8bebf078621c45bdbf557f84c278bfa2d668cee6002911512a98ce6dda8945383c97c72
+  data.tar.gz: 46f0839094cfd3e134df3719cc7bf189df295963f34a106c0540063af57d5dac887c7ca5c019e1afb7152c4d4051a025b1dbe12dd7f287ac4c316e9fe265bc18

data/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,24 @@
+---
+name: Bug report
+about: Create a report to help us improve
+title: "[BUG] "
+labels: ''
+assignees: ''
+
+---
+
+**Describe the bug**
+A clear and concise description of what the bug is.
+
+**To Reproduce**
+Steps to reproduce the behavior:
+1. Go to '...'
+2. Click on '....'
+3. Scroll down to '....'
+4. See error
+
+**Expected behavior**
+A clear and concise description of what you expected to happen.
+
+**Additional context**
+Add any other context about the problem here.

data/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,17 @@
+---
+name: Feature request
+about: Suggest an idea for this project
+title: ''
+labels: ''
+assignees: ''
+
+---
+
+**Is your feature request related to a problem? Please describe.**
+A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
+
+**Describe the solution you'd like**
+A clear and concise description of what you want to happen.
+
+**Additional context**
+Add any other context or screenshots about the feature request here.

data/.gitignore

@@ -168,3 +168,4 @@ modules.xml
 
 # JSON file containing the token for test user during development
 /token.json
+/test.rb

data/CHANGELOG.md

@@ -2,6 +2,39 @@
 
 Documentation for library API changes.
 
+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.5
+
+* Added `Ruqqus::Clien#post_delete` method
+* Added `Ruqqus::Guild#guildmasters` attribute
+
+## Version 1.1.4
+
+* Improved the way refreshing works to do so within a certain threshold
+
+## 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

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,51 @@
+# Contributor Code of Conduct
+
+As contributors and maintainers of this project, and in the interest of
+fostering an open and welcoming community, we pledge to respect all people who
+contribute through reporting issues, posting feature requests, updating
+documentation, submitting pull requests or patches, and other activities.
+
+We are committed to making participation in this project a harassment-free
+experience for everyone, regardless of level of experience, gender, gender
+identity and expression, sexual orientation, disability, personal appearance,
+body size, race, ethnicity, age, religion, or nationality.
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery  
+* Personal attacks  
+* Trolling or insulting/derogatory comments  
+* Public or private harassment  
+* Publishing other's private information, such as physical or electronic
+  addresses, without explicit permission  
+* Other unethical or unprofessional conduct
+
+Project maintainers have the right and responsibility to remove, edit, or
+reject comments, commits, code, wiki edits, issues, and other contributions
+that are not aligned to this Code of Conduct, or to ban temporarily or
+permanently any contributor for other behaviors that they deem inappropriate,
+threatening, offensive, or harmful. This will always involve a public and
+open discussion of the action beinng taken in full transparency.
+
+By adopting this Code of Conduct, project maintainers commit themselves to
+fairly and consistently applying these principles to every aspect of managing
+this project. Project maintainers who do not follow or enforce the Code of
+Conduct may be permanently removed from the project team.
+
+This code of conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community.
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by contacting a project maintainer at efreed09@gmail.com. All
+complaints will be reviewed and investigated and will result in a response that
+is deemed necessary and appropriate to the circumstances. Maintainers are
+obligated to maintain confidentiality with regard to the reporter of an
+incident.  
+
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 1.3.0, available at
+[http://contributor-covenant.org/version/1/3/0/][version]
+
+[homepage]: http://contributor-covenant.org
+[version]: http://contributor-covenant.org/version/1/3/0/

data/CONTRIBUTING.md

@@ -0,0 +1,24 @@
+# How to contribute
+First of all, thank you for taking the time to contribute to this project. We've tried to make a stable project and try to fix bugs and add new features continuously. You can help us do more.
+
+## Getting started
+
+### Check out existing issues/pull requests
+
+If there is a bug or a feature that is not listed in the **issues** page or there is no one assigned to the issue, feel free to fix/add it! Although it's better to discuss it in the issue or create a new issue for it so there is no confilcting code.
+
+### Writing some code!
+
+Contributing to a project on Github is pretty straight forward. If this is you're first time, these are the steps you should take.
+
+- Fork this repo.
+
+And that's it! Read the code available and change the part you don't like! You're change should not break the existing code and should pass the tests.
+
+If you're adding a new functionality, start from the branch **master**. It would be a better practice to create a new branch and work in there.
+
+When you're done, submit a pull request and for one of the maintainers to check it out. We would let you know if there is any problem or any changes that should be considered.
+
+### Documentation
+
+This project enforces 100% documentation coverage, even on non-public methods that aren't part of the API surface. We use [YARD](https://www.rubydoc.info/gems/yard/file/docs/Tags.md) as our tool of choice for documentation. It is rather intuitive, but feel free to ask if you questions if unsure or are unfamiliar with it. Pull requests will not be merged unless documented, so please don't forget to include it!

data/README.md

@@ -1,5 +1,5 @@
 <p align="center">
-<img src="https://raw.githubusercontent.com/ruqqus/ruqqus/master/ruqqus/assets/images/logo/ruqqus_text_logo.png" width="250"/>
+<img src="https://raw.githubusercontent.com/ForeverZer0/ruqqus/master/assets/ruqqus_text_logo.png" width="360"/>
 </p>
 
 <hr>
@@ -41,7 +41,7 @@ To use the `ruqqus-oauth` helper to generate user tokens for desktop development
 
 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
+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
@@ -67,7 +67,11 @@ code          = 'XXXXXX' # The generated code (or the one you obtained via tradi
 
 # 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)
+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
@@ -75,12 +79,16 @@ uses. To facilitate this and make it easier, there is a callback that can be sub
 time the access key is updated.
 
 ```ruby
+# Load an existing token that has already been authorized
 token = Ruqqus::Token.load_json('./token.json')
-token.on_refresh do |t|
+
+# 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
-
-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
@@ -89,7 +97,10 @@ and where you store this information so that it is not compromised.
 
 ## Usage
 
-See the [documentation](https://www.rubydoc.info/gems/ruqqus) for a complete API reference.
+For in-depth documentation and instructions on how to get started, please see the following resources:
+
+* [API Documentation](https://www.rubydoc.info/gems/ruqqus) - Complete documentation of the entire API (100% coverage)
+* [Wiki](https://github.com/ForeverZer0/ruqqus/wiki) - Public wiki with more in-depth explanation, code samples, best practices, etc.
 
 ### Features
 

data/TODO.md

@@ -8,8 +8,6 @@ A scratch pad for things to do and ideas to look into
 * 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

data/exe/ruqqus-oauth

@@ -41,11 +41,11 @@ class RuqqusOAuth
   end
 
   def ask_client_id(prompt)
-    prompt.ask('Client ID: ') { |q| q.validate(/^[A-Fa-f0-9]+$/, "Invalid client ID") }
+    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-Fa-f0-9]+$/, "Invalid client secret") }
+    prompt.ask('Client Secret: ') { |q| q.validate(/^[A-Za-z0-9_-]+$/, "Invalid client secret") }
   end
 
   def ask_client_redirect(prompt)

data/lib/ruqqus.rb

@@ -1,5 +1,9 @@
-require 'rest-client'
+require 'base64'
 require 'json'
+require 'rbconfig'
+require 'rest-client'
+require 'securerandom'
+require 'socket'
 
 require_relative 'ruqqus/token'
 require_relative 'ruqqus/routes'
@@ -44,12 +48,48 @@ module Ruqqus
   class Error < StandardError
   end
 
+  ##
+  # @!attribute self.proxy [rw]
+  #   @return [URI?] the URI of the proxy server in use, or `nil` if none has been set.
+
+  ##
+  # Obtains a list of URIs of free proxy servers that can be used to route network traffic through.
+  #
+  # @param anon [Symbol] anonymity filter for the servers to return, either `:transparent`, `:anonymous`, or `:elite`.
+  # @param country [String,Symbol] country filter for servers to return, an ISO-3166 two digit county code.
+  #
+  # @return [Array<URI>] an array of proxy URIs that match the input filters.
+  # @note These proxies are free, keep that in mind. They are refreshed frequently, can go down unexpectedly, be slow,
+  #   and other manners of inconvenience that can be expected with free services.
+  # @see https://www.nationsonline.org/oneworld/country_code_list.htm
+  def self.proxy_list(anon: :elite, country: nil)
+    raise(ArgumentError, 'invalid anonymity value') unless %i(transparent anonymous elite).include?(anon.to_sym)
+
+    url = "https://www.proxy-list.download/api/v1/get?type=https&anon=#{anon}"
+    url << "&country=#{country}" if country
+
+    RestClient.get(url) do |resp|
+      break if resp.code != 200
+      return resp.body.split.map { |proxy| URI.parse("https://#{proxy}") }
+    end
+    Array.new
+  end
+
+  def self.proxy
+    RestClient.proxy
+  end
+
+  def self.proxy=(uri)
+    raise(TypeError, "#{uri} is not a URI") if uri && !uri.is_a?(URI)
+    RestClient.proxy = uri
+  end
+
   ##
   # Helper function to automate uploading images to Imgur anonymously and returning the direct image link.
   #
   # @param client_id [String] an Imgur client ID
   # @param image_path [String] the path to an image file.
-  # @params opts [Hash] the options hash.
+  # @param opts [Hash] the options hash.
   # @option opts [String] :title a title to set on the Imgur post
   # @option opts [String] :description a description to set on the Imgur post
   #
@@ -77,7 +117,14 @@ module Ruqqus
   #
   # @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}")
+    begin
+      response = RestClient.get("#{Routes::GUILD_AVAILABLE}#{guild_name}")
+      json = JSON.parse(response.body, symbolize_names: true)
+      return json[:available]
+    rescue
+      puts 'err'
+      return false
+    end
   end
 
   ##
@@ -87,22 +134,145 @@ module Ruqqus
   #
   # @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}")
+    begin
+      response = RestClient.get("#{Routes::USERNAME_AVAILABLE}#{username}")
+      json = JSON.parse(response.body)
+      return json[username]
+    rescue
+      return false
+    end
+  end
+
+  ##
+  # Generates a URL for the user to navigate to that will allow them to authorize an application.
+  #
+  # @param client_id [String] the unique ID of the approved client to authorize.
+  # @param redirect [String] the redirect URL where the client sends the OAuth authorization code.
+  # @param scopes [Array<Symbol>] a collection of values indicating the permissions the application is requesting from
+  #   the user. See {Ruqqus::Client::SCOPES} for valid values.
+  # @param permanent [Boolean] `true` if authorization should persist until user explicitly revokes it,
+  #   otherwise `false`.
+  # @param csrf [String] a token to authenticate and prevent a cross-site request forgery (CSRF) attack, or `nil` if
+  #   you do not plan to validate the presence of the cookie in the redirection.
+  #
+  # @see https://ruqqus.com/settings/apps
+  # @see https://owasp.org/www-community/attacks/csrf
+  def self.authorize_url(client_id, redirect, scopes, permanent = true, csrf = nil)
+
+    raise(ArgumentError, 'invalid redirect URI') unless URI.regexp =~ redirect
+    raise(ArgumentError, 'scopes cannot be empty') unless scopes && !scopes.empty?
+
+    scopes = scopes.map(&:to_sym)
+    raise(ArgumentError, "invalid scopes specified") unless scopes.all? { |s| Client::SCOPES.include?(s) }
+    if scopes.any? { |s| [:create, :update, :guildmaster].include?(s) } && !scopes.include?(:identity)
+      # Add identity permission if missing, which is obviously required for a few other permissions
+      scopes << :identity
+    end
+
+    url = 'https://ruqqus.com/oauth/authorize'
+    url << "?client_id=#{client_id || raise(ArgumentError, 'client ID cannot be nil')}"
+    url << "&redirect_uri=#{redirect}"
+    url << "&scope=#{scopes.join(',')}"
+    url << "&state=#{csrf || Base64.encode64(SecureRandom.uuid).chomp}"
+    url << "&permanent=#{permanent}"
+    url
   end
 
-  private
 
   ##
-  # Checks if the specified guild or user name is available to be created.
+  # Opens a URL in the system's default web browser, using the appropriate command for the host platform.
   #
-  # @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.
+  # @param [String] the URL to open.
   #
-  # @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]
+  # @return [void]
+  def self.open_browser(url)
+
+    cmd = case RbConfig::CONFIG['host_os']
+    when /mswin|mingw|cygwin/ then "start \"\"#{url}\"\""
+    when /darwin/ then "open '#{url}'"
+    when /linux|bsd/ then "xdg-open '#{url}'"
+    else raise(Ruqqus::Error, 'unable to determine how to open URL for current platform')
+    end
+
+    system(cmd)
+  end
+
+  ##
+  # If using a `localhost` address for your application's OAuth redirect, this method can be used to open a socket and
+  # listen for a request, returning the authorization code once it arrives.
+  #
+  # @param port [Integer] the port to listen on.
+  # @param timeout [Numeric] sets the number of seconds to wait before cancelling and returning `nil`.
+  #
+  # @return [String?] the authorization code, `nil` if an error occurred.
+  # @note This method is blocking, and will *not* return until a connection is made and data is received on the
+  #   specified port, or the timeout is reached.
+  def self.wait_for_code(port, timeout = 30)
+
+    thread = Thread.new do
+      sleep(timeout)
+      TCPSocket.open('localhost', port) { |s| s.puts }
+    end
+
+    params = {}
+    TCPServer.open('localhost', port) do |server|
+
+      session = server.accept
+      request = session.gets
+      match = /^GET [\/?]+(.*) HTTP.*/.match(request)
+
+      Thread.kill(thread)
+      return nil unless match
+
+      $1.split('&').each do |str|
+        key, value = str.split('=')
+        next unless key && value
+        params[key.to_sym] = value
+      end
+
+      session.puts "HTTP/1.1 200\r\n"
+      session.puts "Content-Type: text/html\r\n"
+      session.puts "\r\n"
+      session.puts create_response(!!params[:code])
+
+      session.close
+    end
+
+    params[:code]
+  end
+
+  private
+
+  ##
+  # @return [String] a generic confirmation page to display in the user's browser after confirming application access.
+  def self.create_response(success)
+    args = success ? ['#339966', 'Authorization Confirmed'] : ['#ff0000', 'Authorization Failed']
+    format ='<h1 style="text-align: center;"><span style="color: %s;"><strong>%s</strong></span></h1>'
+    message = sprintf(format, *args)
+    <<-EOS
+<html>
+<head>
+    <style>
+    .center {
+      margin: 0;
+      position: absolute;
+      top: 50%;
+      left: 50%;
+      -ms-transform: translate(-50%, -50%);
+      transform: translate(-50%, -50%);
+    }
+  </style>
+</head>
+<body>
+<div class="center">
+    <div><img src="https://raw.githubusercontent.com/ruqqus/ruqqus/master/ruqqus/assets/images/logo/ruqqus_text_logo.png" alt="" width="365" height="92" /></div>
+    <p style="text-align: center;">&nbsp;</p>
+    #{message}
+    <p style="text-align: center;">&nbsp;&nbsp;</p>
+    <p style="text-align: center;"><span style="color: #808080;">You can safely close the tab/browser and return to the application.</span></p>
+</div>
+</body>
+</html>
+    EOS
   end
 end