ruqqus 1.1.0 → 1.1.5

data/lib/ruqqus/client.rb

@@ -9,10 +9,18 @@ module Ruqqus
 
     ##
     # The user-agent the client identified itself as.
-    USER_AGENT = "ruqqus-ruby/#{Ruqqus::VERSION} (efreed09@gmail.com)".freeze
+    USER_AGENT = "ruqqus-ruby/#{Ruqqus::VERSION}".freeze
 
     ##
     # A collection of valid scopes that can be authorized.
+    #
+    #   * `:identity` - See your username.
+    #   * `:create` - Save posts and comments as you
+    #   * `:read` - View Ruqqus as you, including private or restricted content
+    #   * `:update` - Edit your posts and comments
+    #   * `:delete` - Delete your posts and comments
+    #   * `:vote` - Cast votes as you
+    #   * `:guildmaster` - Perform Guildmaster actions
     SCOPES = %i(identity create read update delete vote guildmaster).freeze
 
     ##
@@ -20,22 +28,40 @@ module Ruqqus
     DEFAULT_HEADERS = { 'User-Agent': USER_AGENT, 'Accept': 'application/json', 'Content-Type': 'application/json' }.freeze
 
     ##
-    # @return [Token] the OAuth2 token that grants the client authentication.
-    attr_reader :token
+    # @!attribute [rw] token
+    #   @return [Token] the OAuth2 token that grants the client authentication.
 
     ##
     # @!attribute [r] identity
     #   @return [User] the authenticated user this client is performing actions as.
 
     ##
-    # Creates a new instance of the {Client} class.
-    #
-    # @param token [Token] a valid access token to authorize the client.
-    def initialize(token)
-      @token = token || raise(ArgumentError, 'token cannot be nil')
+    # @overload initialize(client_id, client_secret, token)
+    #   Creates a new instance of the {Client} class with an existing token for authorization.
+    #   @param client_id [String] the client ID of your of your application, issued after registration on Ruqqus.
+    #   @param client_secret [String] the client secret of your of your application, issued after registration on Ruqqus.
+    #   @param token [Token] a valid access token that has previously been granted access for the client.
+    #
+    # @overload initialize(client_id, client_secret, code)
+    #   Creates a new instance of the {Client} class with an existing token for authorization.
+    #   @param client_id [String] the client ID of your of your application, issued after registration on Ruqqus.
+    #   @param client_secret [String] the client secret of your of your application, issued after registration on Ruqqus.
+    #   @param code [String] a the code from the Oauth2 redirect to create a new {Token} and grant access to it.
+    def initialize(client_id, client_secret, token)
+      @client_id = client_id || raise(ArgumentError, 'client ID cannot be nil')
+      @client_secret = client_secret || raise(ArgumentError, 'client secret cannot be nil')
+
+      @token = token.is_a?(Token) ? token : Token.new(client_id, client_secret, token.to_s)
+      @token.refresh(client_id, client_secret)
       @session = nil
     end
 
+    attr_reader :token
+
+    def token=(token)
+      @token = token || raise(ArgumentError, 'token cannot be nil')
+    end
+
     # @!group Object Querying
 
     ##
@@ -45,7 +71,7 @@ module Ruqqus
     #
     # @return [User] the requested {User}.
     #
-    # @raise [ArgumentError] when `username` is `nil` or value does match the {VALID_USERNAME} regular expression.
+    # @raise [ArgumentError] when `username` is `nil` or value does match the {Ruqqus::VALID_USERNAME} regular expression.
     # @raise [Error] thrown when user account does not exist.
     def user(username)
       raise(ArgumentError, 'username cannot be nil') unless username
@@ -60,7 +86,7 @@ module Ruqqus
     #
     # @return [Guild] the requested {Guild}.
     #
-    # @raise [ArgumentError] when `guild_name` is `nil` or value does match the {VALID_GUILD} regular expression.
+    # @raise [ArgumentError] when `guild_name` is `nil` or value does match the {Ruqqus::VALID_GUILD} regular expression.
     # @raise [Error] thrown when guild does not exist.
     def guild(guild_name)
       raise(ArgumentError, 'guild_name cannot be nil') unless guild_name
@@ -75,7 +101,7 @@ module Ruqqus
     #
     # @return [Post] the requested {Post}.
     #
-    # @raise [ArgumentError] when `post_id` is `nil` or value does match the {VALID_POST} regular expression.
+    # @raise [ArgumentError] when `post_id` is `nil` or value does match the {Ruqqus::VALID_POST} regular expression.
     # @raise [Error] thrown when a post with the specified ID does not exist.
     def post(post_id)
       raise(ArgumentError, 'post_id cannot be nil') unless post_id
@@ -90,7 +116,7 @@ module Ruqqus
     #
     # @return [Comment] the requested {Comment}.
     #
-    # @raise [ArgumentError] when `comment_id` is `nil` or value does match the {VALID_POST} regular expression.
+    # @raise [ArgumentError] when `comment_id` is `nil` or value does match the {Ruqqus::VALID_POST} regular expression.
     # @raise [Error] when a comment with the specified ID does not exist.
     def comment(comment_id)
       raise(ArgumentError, 'comment_id cannot be nil') unless comment_id
@@ -129,10 +155,10 @@ module Ruqqus
     # @note This method is restricted to 6/minute, and will fail when that limit is exceeded.
     def comment_reply(body, comment)
       if comment.is_a?(Comment)
-        comment_submit(comment.full_name, comment.post_id, body)
+        comment_submit(comment.fullname, comment.post_id, body)
       else
         comment = self.comment(comment.to_s)
-        comment_submit(comment.full_name, comment.post_id, body)
+        comment_submit(comment.fullname, comment.post_id, body)
       end
     end
 
@@ -148,6 +174,18 @@ module Ruqqus
       http_post(url).empty? rescue false
     end
 
+    ##
+    # Deletes an existing post.
+    #
+    # @param post [Comment,String] a {Post} instance, or the unique ID of the post to delete.
+    #
+    # @return [Boolean] `true` if deletion completed without error, otherwise `false`.
+    def post_delete(post)
+      id = post.is_a?(Post) ? post.id : post.sub(/^t3_/, '')
+      url = "#{Routes::API_BASE}/delete_post/#{id}"
+      http_post(url).empty? rescue false
+    end
+
     # @!endgroup Commenting
 
     # @!group Posting
@@ -306,6 +344,54 @@ module Ruqqus
       self
     end
 
+    ##
+    # Enumerates through each comment in a guild, yielding each to a block.
+    #
+    # @param guild [Guild,String] a {Guild} instance, or the name of the guild to query.
+    # @yieldparam [Comment] yields a {Comment} to the block.
+    #
+    # @return [self]
+    # @raise [LocalJumpError] when a block is not supplied to the method.
+    def each_guild_comment(guild)
+      raise(LocalJumpError, 'block required') unless block_given?
+      name = guild.to_s
+      raise(ArgumentError, 'invalid guild name') unless Ruqqus::VALID_GUILD.match?(name)
+
+      page = 1
+      loop do
+        params = { page: page }
+        json = http_get("#{Routes::GUILD}#{name}/comments", headers(params: params))
+        break if json[:error]
+
+        json[:data].each { |hash| yield Comment.from_json(hash) }
+        break if json[:data].size < 25
+        page += 1
+      end
+
+      self
+    end
+
+    ##
+    # Enumerates through each comment in a guild, yielding each to a block.
+    #
+    # @param post [Post,String] a {Post} instance, or the unique ID of the post to query.
+    # @yieldparam [Comment] yields a {Comment} to the block.
+    #
+    # @return [self]
+    # @raise [LocalJumpError] when a block is not supplied to the method.
+    # @note This method is very inefficient, as it the underlying API does not yet implement it, therefore each comment
+    #   in the entire guild must be searched through.
+    def each_post_comment(post)
+      # TODO: This is extremely inefficient, but will have to do until it gets implemented in the API
+      raise(LocalJumpError, 'block required') unless block_given?
+      post = self.post(post) unless post.is_a?(Post)
+      each_guild_comment(post.guild_name) do |comment|
+        next unless comment.post_id == post.id
+        yield comment
+      end
+      self
+    end
+
     ##
     # Enumerates through every post on Ruqqus, yielding each post to a block.
     #
@@ -358,10 +444,25 @@ module Ruqqus
 
     # @!endgroup Object Enumeration
 
+    ##
+    # @return [User] the authenticated user this client is performing actions as.
     def identity
       @me ||= User.from_json(http_get(Routes::IDENTITY))
     end
 
+    ##
+    # @overload token_refreshed(&block)
+    #   Sets a callback to be invoked when the token is refreshed, and a new access token is assigned.
+    #   @yieldparam token [Token] yields the newly refreshed {Token} to the block.
+    #
+    # @overload token_refreshed
+    #   When called without a block, clears any callback that was previously assigned.
+    #
+    # @return [void]
+    def token_refreshed(&block)
+      @refreshed = block_given? ? block : nil
+    end
+
     private
 
     ##
@@ -444,7 +545,7 @@ module Ruqqus
     # @return [Hash] the response deserialized into a JSON hash.
     # @see http_post
     def http_get(uri, header = nil)
-      @token.refresh if @token && @token.expired?
+      refresh_token
       header ||= headers
       response = RestClient.get(uri.chomp('/'), header)
       @session = response.cookies['session_ruqqus'] if response.cookies['session_ruqqus']
@@ -463,12 +564,21 @@ module Ruqqus
     # @return [Hash] the response deserialized into a JSON hash.
     # @see http_get
     def http_post(uri, params = {}, header = nil)
-      @token.refresh if @token && @token.expired?
+      refresh_token
       header ||= headers
       response = RestClient.post(uri.chomp('/'), params, header)
       @session = response.cookies['session_ruqqus'] if response.cookies['session_ruqqus']
       raise(Ruqqus::Error, 'HTTP request failed') if response.code < 200 || response.code >= 300
       JSON.parse(response, symbolize_names: response.body)
     end
+
+    ##
+    # @api private
+    # Checks if token is expired, and refreshes if so, calling the {#token_refreshed} block as if defined.
+    def refresh_token
+      return unless @token.need_refresh?
+      @token.refresh(@client_id, @client_secret)
+      @refreshed&.call(@token)
+    end
   end
 end

data/lib/ruqqus/token.rb

@@ -4,6 +4,10 @@ module Ruqqus
   # Represents a Ruqqus [OAuth2](https://oauth.net/2/) access token.
   class Token
 
+    ##
+    # The minimum number of seconds that can remain before the token refreshes itself.
+    REFRESH_THRESHOLD = 60
+
     ##
     # @!attribute [r] access_token
     #   @return [String] the access token value.
@@ -37,15 +41,11 @@ module Ruqqus
       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
@@ -70,32 +70,15 @@ module Ruqqus
     # Refreshes the access token and resets its time of expiration.
     #
     # @return [void]
-    def refresh
+    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' }
+      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
+      sleep(1) # TODO: Test. Get internment 401 error when token needs refreshed
     end
 
     ##
@@ -104,10 +87,16 @@ module Ruqqus
       expires <= Time.now
     end
 
+    ##
+    # @return [Boolean] `true` if remaining lifetime is within the {REFRESH_THRESHOLD}, otherwise `false`.
+    def need_refresh?
+      (expires - Time.now) < REFRESH_THRESHOLD
+    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
+    def to_json(*_unused_)
+      @data.to_json
     end
 
     ##
@@ -133,15 +122,13 @@ module Ruqqus
     ##
     # Loads the object from a JSON-formatted string.
     #
-    # @param json [String] a JSON string representing the object.
+    # @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 = JSON.parse(payload, symbolize_names: true)
+      data = payload.is_a?(Hash) ? payload: 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.instance_variable_set(:@data, data)
       token
     end
   end

data/lib/ruqqus/types/comment.rb

@@ -6,31 +6,37 @@ module Ruqqus
   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
+    # @!attribute [r] level
+    #   @return [Integer] the level of "nesting" in the comment tree, starting at `1` when in direct reply to the post.
 
     ##
-    # @return [String] the unique ID of the parent for this comment.
-    def parent_id
-      @data[:parent]
-    end
+    # @!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 {#parent_id} refers to a comment, otherwise `false` if a post.
+    # @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 {#parent_id} refers to a post, otherwise `false` if a comment.
+    # @return [Boolean] `true` if the comment's parent is post, otherwise `false` if it is a comment.
     def parent_post?
       level == 1
     end
 
-    ##
-    # @return [String] the ID of the post this comment belongs to.
+    def level
+      @data[:level]
+    end
+
+    def parent_id
+      @data[:parent]
+    end
+
     def post_id
       @data[:post]
     end

data/lib/ruqqus/types/guild.rb

@@ -5,28 +5,44 @@ module Ruqqus
   class Guild < ItemBase
 
     ##
-    # @return [String] the name of the guild.
-    def name
-      @data[:name]
-    end
+    # @!attribute [r] name
+    #   @return [String] the name of the guild.
 
     ##
-    # @return [Integer] the number of members subscribed to the guild.
-    def member_count
-      @data[:subscriber_count]&.to_i || 0
-    end
+    # @!attribute [r] member_count
+    #   @return [Integer] the number of members subscribed to the guild.
 
     ##
-    # @return [Integer] the number of guild masters who moderate this guild.
-    def gm_count
-      @data[:mods_count]&.to_i || 0
-    end
+    # @!attribute [r] fullname
+    #   @return [String] the full ID of the guild.
 
     ##
-    # @return [String] the full ID of the guild.
-    def full_name
-      @data[:fullname]
-    end
+    # @!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.
+
+    ##
+    # @!attribute [r] guildmasters
+    #   @return [Array<User>] an array of {User} instances of the moderators for this guild.
 
     ##
     # @return [Boolean] `true` if the guild contains adult content and flagged as NSFW, otherwise `false`.
@@ -47,39 +63,50 @@ module Ruqqus
     end
 
     ##
-    # @return [String] the description of the guild.
-    def description
-      @data[:description]
+    # @return [String] the string representation of the object.
+    def to_s
+      @data[:name] || inspect
     end
 
-    ##
-    # @return [String] the description of the guild in HTML format.
-    def description_html
-      @data[:description_html]
+    def description
+      @data[:description]
     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 description_html
+      @data[:description_html]
+    end
+
     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
+    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
+
+    def guildmasters
+      return Array.new unless @data[:guildmasters]
+      @data[:guildmasters].map { |gm| User.from_json(gm) }
     end
   end
 end