ruqqus 0.1.0 → 1.1.3

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,124 @@
+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 )
+      @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(client_id, client_secret)
+      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)
+    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(*_unused_)
+      @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,Hash] a JSON string representing the object, or the parsed Hash of the JSON (symbol keys).
+    #
+    # @return [Object] the loaded object.
+    def self.from_json(payload)
+      data = payload.is_a?(Hash) ? payload: JSON.parse(payload, symbolize_names: true)
+      token = allocate
+      token.instance_variable_set(:@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/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/types/comment.rb

@@ -0,0 +1,44 @@
+
+module Ruqqus
+
+  ##
+  # Describes a comment in a post.
+  class Comment < Submission
+
+    ##
+    # @!attribute [r] level
+    #   @return [Integer] the level of "nesting" in the comment tree, starting at `1` when in direct reply to the post.
+
+    ##
+    # @!attribute parent_id
+    #   @return [String] the unique ID of the parent for this comment.
+
+    ##
+    # @!attribute [r] post_id
+    #   @return [String] the ID of the post this comment belongs to.
+
+    ##
+    # @return [Boolean] `true` if the comment's parent is comment, otherwise `false` if it is a post.
+    def parent_comment?
+      level > 1
+    end
+
+    ##
+    # @return [Boolean] `true` if the comment's parent is post, otherwise `false` if it is a comment.
+    def parent_post?
+      level == 1
+    end
+
+    def level
+      @data[:level]
+    end
+
+    def parent_id
+      @data[:parent]
+    end
+
+    def post_id
+      @data[:post]
+    end
+  end
+end

data/lib/ruqqus/types/guild.rb

@@ -0,0 +1,103 @@
+module Ruqqus
+
+  ##
+  # Represents a Ruqqus guild.
+  class Guild < ItemBase
+
+    ##
+    # @!attribute [r] name
+    #   @return [String] the name of the guild.
+
+    ##
+    # @!attribute [r] member_count
+    #   @return [Integer] the number of members subscribed to the guild.
+
+    ##
+    # @!attribute [r] fullname
+    #   @return [String] the full ID of the guild.
+
+    ##
+    # @!attribute [r] guildmaster_count
+    #   @return [Integer] the number of guild masters who moderate this guild.
+
+    ##
+    # @!attribute [r] profile_url
+    #   @return [String] the URL for the profile image associated with the guild.
+
+    ##
+    # @!attribute [r] color
+    #   @return [String] the accent color used for the guild, in HTML format.
+
+    ##
+    # @!attribute [r] description
+    #   @return [String] the description of the guild.
+
+    ##
+    # @!attribute [r] description_html
+    #   @return [String] the description of the guild in HTML format.
+
+    ##
+    # @!attribute [r] banner_url
+    #   @return [String] the URL for the banner image associated with the guild.
+
+    ##
+    # @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 string representation of the object.
+    def to_s
+      @data[:name] || inspect
+    end
+
+    def description
+      @data[:description]
+    end
+
+    def banner_url
+      @data[:banner_url]
+    end
+
+    def description_html
+      @data[:description_html]
+    end
+
+    def profile_url
+      @data[:profile_url]
+    end
+
+    def color
+      @data[:color]
+    end
+
+    def name
+      @data[:name]
+    end
+
+    def member_count
+      @data[:subscriber_count]&.to_i || 0
+    end
+
+    def guildmaster_count
+      @data[:mods_count]&.to_i || 0
+    end
+
+    def fullname
+      @data[:fullname]
+    end
+  end
+end

data/lib/ruqqus/types/item_base.rb

@@ -0,0 +1,68 @@
+
+module Ruqqus
+
+  ##
+  # @abstract
+  # Base class for all all major API types.
+  class ItemBase
+
+    ##
+    # @!attribute [r] permalink
+    #   @return [String] a relative link to this item.
+
+    ##
+    # @!attribute [r] created_utc
+    #   @return [Integer] the time the item was created, in seconds since the Unix epoch.
+
+    ##
+    # @!attribute [r] created
+    #   @return [Time] the time the item was created.
+
+    ##
+    # @!attribute [r] id
+    #   @return [String] a unique ID for this item.
+
+    ##
+    # @return [Boolean] `true` if item has been banned, otherwise `false`.
+    def banned?
+      !!@data[:is_banned]
+    end
+
+    ##
+    # @return [Boolean] `true` if this object is equal to another, otherwise `false`.
+    def ==(other)
+      self.class == other.class && id == other.id
+    end
+
+    def created_utc
+      @data[:created_utc]
+    end
+
+    def created
+      Time.at(created_utc)
+    end
+
+    def id
+      @data[:id]
+    end
+
+    def permalink
+      @data[:permalink]
+    end
+
+    ##
+    # 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
+      data = json.is_a?(Hash) ? json : JSON.parse(json, symbolize_names: true)
+      obj.instance_variable_set(:@data, data)
+      obj
+    end
+
+    private_class_method :new
+  end
+end