ruqqus 1.0.0 → 1.1.0

data/lib/ruqqus/routes.rb

@@ -0,0 +1,68 @@
+module Ruqqus
+
+  ##
+  # A module containing constants that define the method routes for the Ruqqus REST API.
+  module Routes
+
+    ##
+    # The Ruqqus API version.
+    API_VERSION = 1
+
+    ##
+    # The top-level site URL.
+    HOME = 'https://ruqqus.com'.freeze
+
+    ##
+    # The base URL for the Ruqqus REST API.
+    API_BASE = "#{HOME}/api/v#{API_VERSION}".freeze
+
+    ##
+    # The endpoint for the GET method to obtain user information.
+    USER = "#{API_BASE}/user/".freeze
+
+    ##
+    # The endpoint for the GET method to obtain guild information.
+    GUILD = "#{API_BASE}/guild/".freeze
+
+    ##
+    # The endpoint for the GET method to obtain post information.
+    POST = "#{API_BASE}/post/".freeze
+
+    ##
+    # The endpoint for the GET method to obtain comment information.
+    COMMENT = "#{API_BASE}/comment/".freeze
+
+    ##
+    # The endpoint for the POST method to place a vote on a post.
+    POST_VOTE = "#{API_BASE}/vote/post/".freeze
+
+    ##
+    # The endpoint for the GET method to query guild availability.
+    GUILD_AVAILABLE = "#{HOME}/api/board_available/".freeze
+
+    ##
+    # The endpoint for the GET method to query username availability.
+    USERNAME_AVAILABLE = "#{HOME}/api/is_available/".freeze
+
+    ##
+    # The endpoint for the POST method to submit a post.
+    SUBMIT = "#{Routes::API_BASE}/submit/".freeze
+
+    ##
+    # The endpoint for the GET method to get the current user.
+    IDENTITY = "#{Routes::API_BASE}/identity".freeze
+
+    ##
+    # The endpoint for the GET method to get the guild listings.
+    GUILDS = "#{Routes::API_BASE}/guilds".freeze
+
+    ##
+    # The endpoint for the GET method to get the front page listings.
+    FRONT_PAGE = "#{Routes::API_BASE}/front/listing".freeze
+
+    ##
+    # The endpoint for the GET method to get all post listings.
+    ALL_LISTINGS = "#{Routes::API_BASE}/all/listing".freeze
+
+  end
+end

data/lib/ruqqus/token.rb

@@ -0,0 +1,148 @@
+module Ruqqus
+
+  ##
+  # Represents a Ruqqus [OAuth2](https://oauth.net/2/) access token.
+  class Token
+
+    ##
+    # @!attribute [r] access_token
+    #   @return [String] the access token value.
+
+    ##
+    # @!attribute [r] refresh_token
+    #   @return [String] the refresh token value.
+
+    ##
+    # @!attribute [r] expires
+    #   @return [Time] the time the token expires and will require a refresh.
+
+    ##
+    # @!attribute [r] type
+    #   @return [String] the token type to specify in the HTTP header.
+
+    ##
+    # @!attribute [r] scopes
+    #   @return [Array<Symbol>] an array of scopes this token authorizes.
+
+    ##
+    # Grants access to a user account and returns an a newly created {Token} to use as authentication for it.
+    #
+    # @param client_id [String] the ID of client application.
+    # @param client_secret [String] the secret of the client application.
+    # @param code [String] the code received in the redirect response when the user requested API access.
+    # @param persist [Boolean] `true` if token will be reusable, otherwise `false`.
+    #
+    # @return [Token] a newly created {Token} object.
+    def initialize(client_id, client_secret, code, persist = true)
+      headers = { 'User-Agent': Client::USER_AGENT, 'Accept': 'application/json', 'Content-Type': 'application/json' }
+      params = { code: code, client_id: client_id, client_secret: client_secret, grant_type: 'code', permanent: persist }
+      resp = RestClient.post('https://ruqqus.com/oauth/grant', params, headers )
+
+      @client_id = client_id
+      @client_secret = client_secret
+      @data = JSON.parse(resp.body, symbolize_names: true)
+
+      raise(Ruqqus::Error, 'failed to grant access for token') if @data[:oauth_error]
+    end
+
+
+    def access_token
+      @data[:access_token]
+    end
+
+    def refresh_token
+      @data[:refresh_token]
+    end
+
+    def type
+      @data[:token_type]
+    end
+
+    def expires
+      Time.at(@data[:expires_at])
+    end
+
+    def scopes
+      @data[:scopes].split(',').map(&:to_sym)
+    end
+
+    ##
+    # Refreshes the access token and resets its time of expiration.
+    #
+    # @return [void]
+    def refresh
+      headers = { 'User-Agent': Client::USER_AGENT, Authorization: "Bearer #{access_token}" }
+      params = { client_id: @client_id, client_secret: @client_secret, refresh_token: refresh_token, grant_type: 'refresh' }
+      resp = RestClient.post('https://ruqqus.com/oauth/grant', params, headers )
+
+      data = JSON.parse(resp.body, symbolize_names: true)
+      raise(Ruqqus::Error, 'failed to refresh authentication token') unless resp.code == 200 || data[:oauth_error]
+      @data.merge!(data)
+      @refreshed&.call(self)
+    end
+
+    ##
+    # Sets a callback block that will be invoked when the token is refresh. This can be used to automate saving the
+    # token after its gets updated.
+    #
+    # @yieldparam token [Token] yields the token to the block.
+    #
+    # @return [self]
+    #
+    # @example Auto-save updated token
+    #   token = Token.load_json('./token.json')
+    #   token.on_refresh { |t| t.save_json('./token.json') }
+    def on_refresh(&block)
+      raise(LocalJumpError, "block required") unless block_given?
+      @refreshed = block
+      self
+    end
+
+    ##
+    # @return [Boolean] `true` if token is expired, otherwise `false`.
+    def expired?
+      expires <= Time.now
+    end
+
+    ##
+    # @return [String] the object as a JSON-formatted string.
+    def to_json
+      { client_id: @client_id, client_secret: @client_secret, data: @data }.to_json
+    end
+
+    ##
+    # Saves this token in JSON format to the specified file.
+    #
+    # @param filename [String] the path to a file where the token will be written to.
+    # @return [Integer] the number of bytes written.
+    # @note **Security Alert:** The token is essentially the equivalent to login credentials in regards to security,
+    #   so it is important to not share or store it somewhere that it can be easily compromised.
+    def save_json(filename)
+      File.open(filename, 'wb') { |io| io.write(to_json) }
+    end
+
+    ##
+    # Loads a token in JSON format from a file.
+    #
+    # @param filename [String] the path to a file where the token is written to.
+    # @return [Token] a newly created {Token} instance.
+    def self.load_json(filename)
+      from_json(File.read(filename))
+    end
+
+    ##
+    # Loads the object from a JSON-formatted string.
+    #
+    # @param json [String] a JSON string representing the object.
+    #
+    # @return [Object] the loaded object.
+    def self.from_json(payload)
+      data = JSON.parse(payload, symbolize_names: true)
+      token = allocate
+      token.instance_variable_set(:@client_id, data[:client_id])
+      token.instance_variable_set(:@client_secret, data[:client_secret])
+      token.instance_variable_set(:@data, data[:data])
+      token
+    end
+  end
+end

data/lib/ruqqus/types.rb

@@ -0,0 +1,11 @@
+
+# Bootstrap script to load all concrete Ruqqus types
+
+require_relative 'types/item_base'
+require_relative 'types/submission'
+require_relative 'types/comment'
+require_relative 'types/guild'
+require_relative 'types/post'
+require_relative 'types/badge'
+require_relative 'types/title'
+require_relative 'types/user'

data/lib/ruqqus/types/comment.rb

@@ -0,0 +1,38 @@
+
+module Ruqqus
+
+  ##
+  # Describes a comment in a post.
+  class Comment < Submission
+
+    ##
+    # @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 [Boolean] `true` if {#parent_id} refers to a comment, otherwise `false` if a post.
+    def parent_comment?
+      level > 1
+    end
+
+    ##
+    # @return [Boolean] `true` if {#parent_id} refers to a post, otherwise `false` if a comment.
+    def parent_post?
+      level == 1
+    end
+
+    ##
+    # @return [String] the ID of the post this comment belongs to.
+    def post_id
+      @data[:post]
+    end
+  end
+end

data/lib/ruqqus/{item_base.rb → types/item_base.rb}

@@ -1,4 +1,3 @@
-require 'json'
 
 module Ruqqus
 
@@ -46,10 +45,13 @@ module Ruqqus
     ##
     # Loads the object from a JSON-formatted string.
     #
+    # @param json [String,Hash] a JSON string representing the object.
+    #
     # @return [Object] the loaded object.
     def self.from_json(json)
       obj = allocate
-      obj.instance_variable_set(:@data, JSON.parse(json, symbolize_names: true))
+      data = json.is_a?(Hash) ? json : JSON.parse(json, symbolize_names: true)
+      obj.instance_variable_set(:@data, data)
       obj
     end
 

data/lib/ruqqus/{post.rb → types/post.rb}

@@ -1,4 +1,3 @@
-require_relative 'submission'
 
 module Ruqqus
 
@@ -6,10 +5,6 @@ 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
@@ -41,12 +36,6 @@ module Ruqqus
       @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
@@ -59,27 +48,5 @@ module Ruqqus
       #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 → types/submission.rb}

@@ -1,4 +1,3 @@
-require_relative 'item_base'
 
 module Ruqqus
 
@@ -13,13 +12,6 @@ module Ruqqus
       @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
@@ -111,22 +103,15 @@ module Ruqqus
     end
 
     ##
-    # @return [Guild?] the guild this item is contained within.
-    def guild
-      #noinspection RubyYardReturnMatch
-      @guild ||= guild_name ? Ruqqus.guild(guild_name) : nil
+    # @return [String] the name/title of this item.
+    def title
+      @data[:title]
     end
 
     ##
-    # @return [String] a unique ID associated with this item.
-    def id
+    # @return [String] the string representation of the object.
+    def to_s
       @data[:id]
     end
-
-    ##
-    # @return [String] the name/title of this item.
-    def title
-      @data[:title]
-    end
   end
 end

data/lib/ruqqus/{user.rb → types/user.rb}

@@ -1,6 +1,3 @@
-require_relative 'badge'
-require_relative 'title'
-require_relative 'item_base'
 
 module Ruqqus
 

data/lib/ruqqus/version.rb

@@ -2,7 +2,7 @@ module Ruqqus
 
   ##
   # The Ruqqus gem version.
-  VERSION = '1.0.0'.freeze
+  VERSION = '1.1.0'.freeze
 
   ##
   # Lulz

data/ruqqus.gemspec

@@ -7,8 +7,8 @@ Gem::Specification.new do |spec|
   spec.version       = Ruqqus::VERSION
   spec.authors       = ['ForeverZer0']
   spec.email         = ['efreed09@gmail.com']
-  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.summary       = %q{A Ruby API implementation for Ruqqus, an open-source platform for online communities.}
+  spec.description   = %q{A Ruby API implementation for Ruqqus, an open-source platform for online communities, free of censorship and moderator abuse by design.}
   spec.homepage      = 'https://github.com/ForeverZer0/ruqqus'
   spec.license       = 'MIT'
   spec.required_ruby_version = Gem::Requirement.new('>= 2.3.0')
@@ -35,6 +35,8 @@ Gem::Specification.new do |spec|
   # Dependencies
   spec.add_runtime_dependency('rest-client', '~> 2.1')
 
+  spec.add_development_dependency('mechanize', '~> 2.7')
   spec.add_development_dependency('rake', '~> 13.0')
+  spec.add_development_dependency('tty-prompt', '~> 0.22')
   spec.add_development_dependency('yard', '~> 0.9')
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ruqqus
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - ForeverZer0
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2020-08-28 00:00:00.000000000 Z
+date: 2020-09-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rest-client
@@ -24,6 +24,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.1'
+- !ruby/object:Gem::Dependency
+  name: mechanize
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.7'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.7'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -38,6 +52,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: tty-prompt
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.22'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.22'
 - !ruby/object:Gem::Dependency
   name: yard
   requirement: !ruby/object:Gem::Requirement
@@ -53,12 +81,11 @@ dependencies:
       - !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.
+  communities, free of censorship and moderator abuse by design.
 email:
 - efreed09@gmail.com
-executables: []
+executables:
+- ruqqus-oauth
 extensions: []
 extra_rdoc_files: []
 files:
@@ -70,17 +97,23 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
+- TODO.md
 - bin/console
 - bin/setup
+- exe/ruqqus-oauth
 - 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/client.rb
+- lib/ruqqus/routes.rb
+- lib/ruqqus/token.rb
+- lib/ruqqus/types.rb
+- lib/ruqqus/types/badge.rb
+- lib/ruqqus/types/comment.rb
+- lib/ruqqus/types/guild.rb
+- lib/ruqqus/types/item_base.rb
+- lib/ruqqus/types/post.rb
+- lib/ruqqus/types/submission.rb
+- lib/ruqqus/types/title.rb
+- lib/ruqqus/types/user.rb
 - lib/ruqqus/version.rb
 - ruqqus.gemspec
 homepage: https://github.com/ForeverZer0/ruqqus
@@ -112,5 +145,5 @@ rubygems_version: 3.1.4
 signing_key:
 specification_version: 4
 summary: A Ruby API implementation for Ruqqus, an open-source platform for online
-  communities, free of censorship and moderator abuse by design.
+  communities.
 test_files: []