rublox 0.1.0

data/lib/rublox/models/presence.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Rublox
+  # The state of the presence.
+  #
+  # Can be offline, online/on the website, playing a game, developing on studio.
+  module PresenceType
+    # The user is/was offline.
+    OFFLINE = :Offline
+    # The user is/was online (this also applies to the website).
+    ONLINE = :Online
+    # The user is/was playing a game.
+    GAME = :"In game"
+    # The user is/was developing on studio.
+    STUDIO = :"In Studio"
+
+    # @!visibility private
+    PRESENCE_MAP = [
+      OFFLINE,
+      ONLINE,
+      GAME,
+      STUDIO
+    ].freeze
+
+    # Convert the Roblox PresenceType enum response to rublox's PresenceType
+    # equivalent.
+    # @!visibility private
+    # @param enum [Integer]
+    # @return [Symbol]
+    def self.enum_to_presence_type(enum)
+      PRESENCE_MAP[enum]
+    end
+  end
+
+  # @note This class is handled internally by the public interface such as
+  #   {Client#user_presence_from_id}. You should not be creating it yourself.
+  # The {Presence} class corresponds to a response you can get via
+  # https://presence.roblox.com/v1/presence/users. You can use it to get information
+  # about the presence states of users.
+  class Presence
+    # @return [PresenceType] the current presence type
+    attr_reader :presence_type
+
+    # @return [PresenceType] the last presence type of the user
+    attr_reader :last_presence_type
+
+    # @note Unlike it sounds, this is not a numerical ID like of a user. It's a
+    # randomly generated string with hexadecimal numbers containing the server's
+    # job ID (which looks like "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"), it can be
+    # also accessed in-game via the game.JobId property.
+    # @return [String, nil] the job ID of the game last played by the user.
+    attr_reader :game_job_id
+
+    # @return [Time] the date at which the user was last online
+    attr_reader :last_online_date
+
+    def initialize(data, client)
+      @presence_type = PresenceType.enum_to_presence_type(data["userPresenceType"])
+      @last_location = data["lastLocation"]
+      @place_id = data["placeId"]
+      @root_place_id = data["rootPlaceId"]
+      @game_job_id = data["gameId"]
+      @universe_id = data["universeId"]
+      @user_id = data["userId"]
+      @last_online_date = Time.iso8601(data["lastOnline"])
+
+      @client = client
+    end
+
+    # @todo add Place class
+    # @return [Place, nil] the place last visited by the user, can be nil if the
+    #   user has never played a game
+    def place
+      return unless @place_id
+    end
+
+    # @todo add Place class
+    # @return [Place, nil] the root of the place last visited by the user, can
+    #   be nil if the user has never played a game
+    def root_place
+      return unless @root_place_id
+    end
+
+    # @todo add Universe class
+    # @return [Universe, nil] the universe of the place last visited by the user,
+    #   can be nil if the user has never played a game
+    def universe
+      return unless @universe_id
+    end
+
+    # @return [FullUser] the user tied to the presence
+    def user
+      @client.user_from_id(@user_id)
+    end
+  end
+end

data/lib/rublox/util/cache.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Rublox
+  # @note Only use if you have an use case that the library doesn't cover (and
+  #   create an issue and perhaps we'll implement it!).
+  module Cache
+    # The key for the user cache.
+    USER = :users
+    # The key for the group cache.
+    GROUP = :groups
+    # The key for the page cache.
+    PAGE = :pages
+
+    # @!visiblity private
+    @cache = {
+      users: {},
+      groups: {},
+      pages: {}
+    }
+
+    # Try to get an object from cache.
+    # @param type [Symbol] {USER}, {GROUP} or {PAGE}
+    # @param id [Integer] the ID of the object
+    # @return [FullUser, FullGroup, Pages, nil]
+    def self.get(type, id)
+      @cache[type][id]
+    end
+
+    # Set an object in the cache, under the type's key.
+    # @param type [Symbol] {USER}, {GROUP} or {PAGE}
+    # @param id [Integer] the ID of the object
+    # @param object [FullUser, FullGroup, Pages] the object to be added to the
+    #   cache
+    # @return [nil]
+    def self.set(type, id, object)
+      @cache[type][id] = object
+    end
+  end
+end

data/lib/rublox/util/errors.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module Rublox
+  # This module contains errors that can be raised by rublox methods.
+  module Errors
+    # Exception raised when a user cannot be found.
+    class UserNotFoundError < StandardError
+      # @return [Integer, "(no ID information provided)"] the given user's ID
+      attr_reader :user_id
+
+      # @return [String, "(no username information provided)"] the given user's
+      #   username
+      attr_reader :user_username
+
+      # @param user_id [Integer]
+      # @param username [String, nil]
+      def initialize(
+        user_id = "(no ID information provided)",
+        username = "(no username information provided)"
+      )
+        @user_id = user_id
+        @user_username = username
+        super("The user of ID #{user_id} and username #{username} could not be found.")
+      end
+    end
+
+    # Exception raised when a group cannot be found.
+    class GroupNotFoundError < StandardError
+      # @return [Integer] the given group's ID
+      attr_reader :group_id
+
+      # @param group_id [Integer]
+      def initialize(group_id)
+        @group_id = group_id
+        super("The group of ID #{group_id} could not be found.")
+      end
+    end
+
+    # Exception raised when a user's presence cannot be found.
+    class PresenceNotFoundError < StandardError
+      # @return [Integer] the presence user's ID
+      attr_reader :user_id
+
+      def initialize(user_id)
+        @user_id = user_id
+        super("The presence of the user with ID #{user_id} could not be found.")
+      end
+    end
+
+    # Exception raised when a user is not part of a group.
+    class MemberNotFoundError < StandardError
+      # @return [Integer] the given user's ID
+      attr_reader :user_id
+
+      # @return [Integer] the given group's ID
+      attr_reader :group_id
+
+      # @param id [Integer]
+      # @param group_id [Integer]
+      def initialize(id, group_id)
+        @user_id = id
+        @group_id = group_id
+        super("The user of ID #{id} is not part of this group of ID #{group_id}")
+      end
+    end
+
+    # Exception raised when a role doesn't exist.
+    class RoleNotFoundError < StandardError
+      # @return [Integer] the given role's ID
+      attr_reader :role_id
+
+      # @return [Integer] the given group's ID
+      attr_reader :group_id
+
+      # @param role_id [Integer]
+      # @param group_id [Integer]
+      def initialize(role_id, group_id)
+        @role_id = role_id
+        @group_id = group_id
+        super("The role of ID #{role_id} does not exist in group of ID #{group_id}.")
+      end
+    end
+
+    # Exception raised when an unhandled status code is returned.
+    class UnhandledStatusCodeError < StandardError
+      # @return [HTTP::Response::Status] the unhandled status code
+      attr_reader :status_code
+
+      # @return [String] a string containing all the errors returned by the API
+      #   neatly formatted
+      attr_reader :errors
+
+      # @param status_code [Integer]
+      # @param errors [String, nil]
+      def initialize(status_code, errors = "")
+        super("Unhandled status code #{status_code}.\nRoblox errors:\n#{errors}")
+        @status_code = status_code
+        @errors = errors
+      end
+    end
+
+    # Exception raised when an invalid .ROBLOSECURITY cookie is used.
+    class InvalidROBLOSECURITYError < StandardError
+      def initialize
+        super("A valid .ROBLOSECURITY cookie needs to be passed to Rublox's constructor for this action.")
+      end
+    end
+  end
+end

data/lib/rublox/util/http_client.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+require "http"
+require "json"
+
+require "rublox/util/errors"
+
+module Rublox
+  # @note Only use if you have an use case that the library doesn't cover (and
+  #   create an issue and perhaps we'll implement it!).
+  # The {HTTPClient} is a wrapper around the http library, designed specifically
+  # for the Roblox API. It automatically handles the X-CSRF-TOKEN and the
+  # .ROBLOSECURITY cookie.
+  class HTTPClient
+    # @param roblosecurity [String]
+    def initialize(roblosecurity = "")
+      @client = HTTP.cookies(
+        {
+          ".ROBLOSECURITY": roblosecurity
+        }
+      )
+    end
+
+    # Send a GET request to the specified URL.
+    # @param url [String]
+    # @return [Hash]
+    def get(url, *args)
+      request(:get, url, *args)
+    end
+
+    # Send a POST request to the specified URL.
+    # @param url [String]
+    # @return [Hash]
+    def post(url, *args)
+      request(:post, url, *args)
+    end
+
+    # Send a PATCH request to the specified URL.
+    # @param url [String]
+    # @return [Hash]
+    def patch(url, *args)
+      request(:patch, url, *args)
+    end
+
+    # Send a DELETE request to the specified URL.
+    # @param url [String]
+    # @return [Hash]
+    def delete(url, *args)
+      request(:delete, url, *args)
+    end
+
+    private
+
+    # @param verb [Symbol]
+    # @param url [String]
+    # @return [Hash]
+    def request(verb, url, *args)
+      response = @client.request(verb, url, *args)
+      return JSON.parse(response.body) if response.status == 200
+
+      handle_status_code(response, verb, url, *args)
+    end
+
+    # @param response [HTTP::Response]
+    def handle_status_code(response, verb, url, *args)
+      case response.status
+      # token validation failed
+      when 403
+        @client = @client.headers(
+          {
+            "x-csrf-token": response.headers["x-csrf-token"]
+          }
+        )
+        # retry the request
+        request(verb, url, *args)
+      # invalid .ROBLOSECURITY cookie
+      when 401
+        raise Errors::InvalidROBLOSECURITYError
+      else
+        raise Errors::UnhandledStatusCodeError.new(response.status, get_errors_from_response(response))
+      end
+    end
+
+    # @param response [HTTP::Response]
+    def get_errors_from_response(response)
+      body = JSON.parse(response.body)
+    rescue JSON::ParserError
+      "\ncould not parse errors, raw body:\n#{response.body}\n"
+    else
+      body["errors"].reduce("") do |error_message, error|
+        error_message + "\tCode: #{error['code']}\n\tMessage: #{error['message']}\n\n"
+      end
+    end
+  end
+end

data/lib/rublox/util/pages.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+require "rublox/util/url"
+require "rublox/util/cache"
+
+module Rublox
+  # The order to sort pages in.
+  module SortOrder
+    # Sort the pages ina ascending order.
+    ASCENDING = "Asc"
+    # Sort the pages in descending order.
+    DESCENDING = "Desc"
+  end
+
+  # The {Pages} class acts as an iterator over pages returned by the API.
+  # @!visibility private
+  # @todo Make more customizable, polish and battle-test
+  # @note Only use if you have an use case that the library doesn't cover (and
+  #   create an issue and perhaps we'll implement it!).
+  class Pages
+    # How many items are returned per page
+    PAGE_DATA_LIMIT = 100
+
+    # @!visibility private
+    DEFAULT_REQUEST_PARAMETERS = {
+      params: {
+        sortOrder: SortOrder::DESCENDING,
+        limit: PAGE_DATA_LIMIT
+      }
+    }.freeze
+
+    # @param client [Client]
+    # @param initial_data [Hash]
+    # @param url [String]
+    # @param request_params [Hash]
+    def initialize(client, initial_data, url, request_params = {}, &data_handler)
+      request_params[:params] = DEFAULT_REQUEST_PARAMETERS[:params].merge(
+        request_params
+      )
+
+      @client = client
+      @raw_data = initial_data
+      @url = url
+      @request_parameters = request_parameters
+      @data_handler = data_handler
+
+      @data = []
+    end
+
+    # Iterate over the pages
+    def each
+      raise unless block_given?
+      # i = 0
+
+      # until @raw_data
+      #   if i == @data.length
+      #     i = 0
+      #     data = Cache.get(Cache::PAGE, @raw_data["nextPageCursor"])
+      #     if data
+      #       @data = data
+      #     else
+      #       @raw_data, @data = next_page
+      #       break if @raw_data.empty?
+
+      #       Cache.set(Cache::PAGE, @raw_data["nextPageCursor"], @data)
+      #     end
+      #   end
+
+      #   yield @data[i]
+      #   i += 1
+      # end
+    end
+
+    private
+
+    # @return [Array] tuple {raw data, processed data}
+    def next_page
+      @request_parameters[:params][:cursor] = @raw_data["nextPageCursor"]
+
+      data = @client.http_client.get(@url, @request_parameters)
+
+      [data["data"], @data_handler.call(data["data"])]
+    end
+  end
+end

data/lib/rublox/util/url.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Rublox
+  # Module for making URLs.
+  module URL
+    # The base URL to be used. If using a proxy, you can change the URL as long
+    # as it follows Roblox's API structure:
+    #   https://users.roblox.com/v1/users/1
+    #   Bad:
+    #   https://myproxy.test/get-user/1
+    #   https://myproxy.test/users/1
+    #   https://users.myproxy.test/users/1
+    #   Good:
+    #   https://users.myproxy.test/v1/users/1
+    BASE_URL = "roblox.com"
+
+    # Creates an endpoint URL from the the given ApiSite and path.
+    # @param api_site [String] ApiSite
+    # @param path [String]
+    # @return [String] the endpoint
+    def self.endpoint(api_site, path)
+      "https://#{api_site}.#{BASE_URL}/#{path}"
+    end
+  end
+end

data/lib/rublox/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module Rublox
+  # Current version of rublox
+  VERSION = "0.1.0"
+end

data/lib/rublox.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+require "http"
+
+require "rublox/version"
+require "rublox/util/http_client"
+require "rublox/util/cache"
+require "rublox/models/full_user"
+require "rublox/models/full_group"
+require "rublox/models/presence"
+
+# rublox is a Roblox web API wrapper written in Ruby. It aims to provide an
+# object oriented interface to get and modify data from Roblox's web API.
+#
+# Repository: https://github.com/roblox-api-wrappers/rublox
+#
+# Docs: https://rubydoc.info/gems/rublox
+module Rublox
+  # The {Client} object is the gateway to the API. Tt supplies methods that
+  # return classes modeled after the interactions you can do with the API.
+  #
+  # Initialize the client with a .ROBLOSECURITY cookie if you need functionality
+  # that requires it.
+  # @example
+  #   require "rublox"
+  #   # without a cookie
+  #   client = Rublox::Client.new
+  #   # with a cookie
+  #   client = Rublox::Client.new("_|WARNING:-DO-NOT-SHARE-THIS.--Sharing-this ...")
+  class Client
+    # @note The HTTP client should only be used when there are no methods
+    #   provided by the library to achieve what you want.
+    # @return [HTTPClient]
+    attr_reader :http_client
+
+    # Initialize the client with a .ROBLOSECURITY cookie if you require functionality
+    # that needs it.
+    # @example
+    #   require "rublox"
+    #   # without a cookie
+    #   client = Rublox::Client.new
+    #   # with a cookie
+    #   client = Rublox::Client.new("_|WARNING:-DO-NOT-SHARE-THIS.--Sharing-this ...")
+    # @param roblosecurity [String, nil] a valid .ROBLOSECURITY cookie
+    def initialize(roblosecurity = "")
+      @http_client = HTTPClient.new(roblosecurity)
+    end
+
+    # @example
+    #   client = Rublox::Client.new
+    #   user = client.user_from_id(1)
+    #   puts user.username # -> Roblox
+    # @param id [Integer] the user's ID
+    # @return [FullUser] a model of the user specified by the ID
+    def user_from_id(id)
+      user = Cache.get(Cache::USER, id)
+      return user if user
+
+      data = @http_client.get(
+        URL.endpoint("users", "v1/users/#{id}")
+      )
+    rescue Errors::UnhandledStatusCodeError
+      raise Errors::UserNotFoundError, id
+    else
+      user = FullUser.new(
+        data,
+        self
+      )
+      Cache.set(Cache::USER, id, user)
+
+      user
+    end
+
+    # @note This method sends 2 requests, use {#user_from_id} if possible.
+    # @example
+    #   client = Rublox::Client.new
+    #   user = client.user_from_username("Roblox")
+    #   puts user.id # -> 1
+    # @param username [String] the user's username
+    # @return [FullUser] a model of the user specified by the ID
+    def user_from_username(username)
+      data = @http_client.post(
+        URL.endpoint("users", "/v1/usernames/users"),
+        json: {
+          usernames: [username],
+          excludeBannedUsers: false
+        }
+      )["data"]
+      raise Errors::UserNotFoundError.new(nil, username) if data.empty?
+
+      user_from_id(
+        data[0]["id"]
+      )
+    end
+
+    # @example
+    #   client = Rublox::Client.new
+    #   group = client.group_from_id(1)
+    #   puts group.name # -> RobloHunks
+    # @param id [Integer] the groups's ID
+    # @return [FullGroup] a model of the group specified by the ID
+    def group_from_id(id)
+      group = Cache.get(Cache::GROUP, id)
+      return group if group
+
+      data = @http_client.get(
+        URL.endpoint("groups", "v1/groups/#{id}")
+      )
+    rescue Errors::UnhandledStatusCodeError
+      raise Errors::GroupNotFoundError, id
+    else
+      group = FullGroup.new(data, self)
+      Cache.set(Cache::GROUP, id, group)
+
+      group
+    end
+
+    # @param id [Integer] the user's ID
+    # @return [Presence] a model of the presence specified by the user's ID
+    def user_presence_from_id(id)
+      data = http_client.post(
+        URL.endpoint("presence", "v1/presence/users"),
+        json: {
+          userIds: [id]
+        }
+      )
+    rescue Errors::UnhandledStatusCodeError
+      raise Errors::PresenceNotFoundError, id
+    else
+      Presence.new(
+        data["userPresences"][0],
+        self
+      )
+    end
+  end
+end

data/rublox.gemspec

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require_relative "lib/rublox/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "rublox"
+  spec.version = Rublox::VERSION
+  spec.authors = %w[Zamdie Keef]
+  spec.email = "rorg.devv@gmail.com"
+  spec.summary = "A Roblox web API wrapper written in Ruby"
+  spec.description = "This gem allows easy interaction with the Roblox web API via class models."
+  spec.homepage = "https://github.com/roblox-api-wrappers/rublox"
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 3.0"
+  spec.files = Dir[
+      "LICENSE",
+      "CHANGELOG.MD",
+      "lib/**/*.rb",
+      "rublox.gemspec",
+      "Gemfile",
+      "Rakefile"
+  ]
+  spec.extra_rdoc_files = ["README.MD"]
+
+  spec.add_dependency "http", "~> 5.0.2"
+
+  spec.add_development_dependency "dotenv", "~> 2.7"
+  spec.add_development_dependency "rake", "~> 13.0.6"
+  spec.add_development_dependency "rubocop", "~> 1.21.0"
+  spec.add_development_dependency "rubocop-performance", "~> 1.11.5"
+  spec.add_development_dependency "yard", "~> 0.9.26"
+end