rublox 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 1e1d91f1dc37df6df866bdf110705af8a5f78e68748edd2d577ff44de821e0f7
+  data.tar.gz: c91696dacf025936ce517ffdcca4cae5672856bcd46822b04f28c002bc5eb0e5
+SHA512:
+  metadata.gz: db8304263e8be041a5fb44b6c090240014c5473c84088d72b7c881b0c40abad7134d6f5dec7842b1d7a767655db833a193d4c8c79d5f0486c9a06d59748ea175
+  data.tar.gz: a32d33986c09589f38f95f9e91b8f4746b4236fea4263aabbb41af8fc63f6d717e865d21d02755b1a578c2673a45cf4f5a22fda4f3f8fb13b6fd659856fd4a6f

data/CHANGELOG.MD

@@ -0,0 +1,4 @@
+# 0.1.0 (9th October, 2021)
+
+-   Initial repository and package setup
+-   User, group, presence, group member and group role APIs added

data/Gemfile

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+source "http://rubygems.org"
+ruby ">= 3.0"
+
+gemspec

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2021 Roblox API wrappers
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.MD

@@ -0,0 +1,68 @@
+<div align="center">
+  <img src="https://raw.githubusercontent.com/roblox-api-wrappers/.github/main/res/rublox_logo.png" alt="rublox" width="15%" height="15%"/>
+</div>
+
+<br>
+
+<div align="center">
+  <a href="https://rubygems.org/gems/rublox">
+    <img alt="gem" src="https://img.shields.io/gem/dt/rublox?color=rgb%28170%2C%200%2C%200%29&logo=rubygems&style=flat-square">
+  </a>
+
+  <a href="https://rubygems.org/gems/rublox">
+    <img alt="gem version" src="https://img.shields.io/gem/v/rublox?color=rgb%28170%2C%200%2C%200%29&label=gem%20version&logo=rubygems&style=flat-square">
+  </a>
+
+  <a href="https://github.com/roblox-api-wrappers/rublox/blob/main/LICENSE">
+    <img alt="license: MIT" src="https://img.shields.io/github/license/roblox-api-wrappers/rublox?color=rgb%28150%2C%200%2C%200%29&logo=github&style=flat-square">
+  </a>
+
+  <img alt="commit activity" src="https://img.shields.io/github/commit-activity/m/roblox-api-wrappers/rublox?color=rgb%28170%2C%200%2C%200%29&logo=github&style=flat-square">
+
+  <img alt="repo stars" src="https://img.shields.io/github/stars/roblox-api-wrappers/rublox?color=rgb%28170%2C%200%2C%200%29&logo=github&style=flat-square">
+
+  <a href="https://rubydoc.info/gems/rublox">
+    <img alt="docs" src="https://img.shields.io/badge/docs-rubydoc.info-aa0000?style=flat-square">
+  </a>
+
+  <a href="https://guilded.gg/roblox-api-wrappers">
+    <img alt="support server" src="https://img.shields.io/badge/guilded-support%20server-aa0000.svg?style=flat-square&logo=guilded">
+  </a>
+</div>
+
+<div align="center"> <i>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. </i> </div>
+
+<br>
+
+# Installation
+
+Include rublox in your application's `Gemfile`
+
+```ruby
+gem "rublox", "~> 0.1.0"
+```
+
+or run
+
+> $ gem install rublox
+
+on your terminal.
+
+# Getting started
+
+The gateway to the API is the [Rublox::Client](https://rubydoc.info/gems/rublox/Rublox/Client) object. You can initialize it with your _.ROBLOSECURITY_ cookie if you need functionality that needs it.
+
+```ruby
+# Without a cookie
+client = Rublox::Client.new
+# With a cookie
+client = Rublox::Client.new("_|WARNING:-DO-NOT-SHARE-THIS.--Sharing-this ...")
+```
+
+**(if you open-source/work with other people on your application, it is recommended to keep your cookie in a `.env` file and load it with a library like [dotenv](https://rubygems.org/gems/dotenv))**
+
+From there, you can build off your application's logic with methods provided via [Rublox::Client](https://rubydoc.info/gems/rublox/Rublox/Client)
+
+# Documentation
+
+You can access the documentation at https://rubydoc.info/gems/rublox.

data/Rakefile

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require "rake"
+
+desc "run rubocop"
+task :rubocop do
+  system "rubocop"
+end
+
+desc "run tests"
+task :test do
+  system "ruby -I ./lib ./tests/run_tests.rb"
+end
+
+desc "build docs"
+task :docs do
+  system "yardoc"
+end
+
+desc "build docs, showing private objects"
+task :docs_priv do
+  system "yardoc --private"
+end
+
+desc "open local server to live preview docs"
+task :doc_server do
+  system "yard server --reload"
+end
+
+desc "list all undocumented objects"
+task :list_undoc do
+  system "yard stats --list-undoc"
+end

data/lib/rublox/derive/group.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require "rublox/models/group_member"
+require "rublox/models/group_role"
+
+module Rublox
+  # This mixin module contains functions that can be called on group objects.
+  # @abstract
+  module Group
+    # @example
+    #   client = Rublox::Client.new
+    #   group = client.group_from_id(1)
+    #   group.roles.each { |role| puts role.rank } # 0, 1, 180, 100, 254, 255
+    # @return [Array<GroupRole>] the group's roles
+    def roles
+      @client.http_client.get(
+        URL.endpoint("groups", "v1/groups/#{@id}/roles")
+      )["roles"].map { |role| GroupRole.new(role, self, @client) }
+    end
+
+    # @example
+    #   client = Rublox::Client.new
+    #   group = client.group_from_id(7384468)
+    #   member = group.member_by_id(1)
+    #   puts member.role.rank # -> 1
+    # @param id [Integer] the user's ID
+    # @return [GroupMember] the user as a group member object
+    def member_by_id(id)
+      member_by_user(@client.user_from_id(id))
+    rescue Errors::UserNotFoundError
+      raise Errors::MemberNotFoundError.new(id, @id)
+    end
+
+    # @example
+    #   client = Rublox::Client.new
+    #   group = client.group_from_id(7384468)
+    #   owner_member = group.member_by_user(group.owner)
+    #   puts owner_member.role.rank # -> 255
+    # @param user [FullUser, LimitedUser] the user to tie to the group member
+    # @return [GroupMember] the user as a group member object
+    def member_by_user(user)
+      data = @client.http_client.get(
+        URL.endpoint("groups", "v2/users/#{user.id}/groups/roles")
+      )["data"].find { |member_data| member_data["group"]["id"] == @id }
+      raise Errors::MemberNotFoundError.new(user.id, @id) unless data
+
+      GroupMember.new(user, GroupRole.new(data["role"], self, @client), self, @client)
+    end
+  end
+end

data/lib/rublox/derive/user.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+require "rublox/util/url"
+
+module Rublox
+  # This mixin module contains functions that can be called on user objects.
+  # @abstract
+  module User
+    # @example Updating a {FullUser}
+    #   client = Rublox::Client.new
+    #   user = client.user_from_id(1)
+    #   puts user.display_name # -> Roblox
+    #   # suppose the Roblox account changes it's display name to "ABC"
+    #   refreshed_user = user.refresh
+    #   puts refreshed_user.display_name # -> ABC
+    # @example Updating a {LimitedUser}
+    #   client = Rublox::Client.new
+    #   group = client.group_from_id(1)
+    #   # say we want the user's join date. LimitedUsers do not contain that information, so we can update it to get a
+    #   # FullUser, which has that
+    #   the_full_user_owner = group.owner.refresh
+    #   # we can now get the owner's join date
+    #   puts the_full_user_owner.join_date.inspect # "2008-09-30 15:54:26 UTC"
+    # @return [FullUser] a mirrored {FullUser} object, containing new information
+    #   about theuser if it has been changed, or if the user is a {LimitedUser}.
+    def refresh
+      @client.user_from_id(@id)
+    end
+
+    # @example
+    #   client = Rublox::Client.new
+    #   user = client.user_from_id(1)
+    #   puts user.friend_count # -> 0
+    # @return [Integer] the count of how many friends the user has
+    def friend_count
+      @client.http_client.get(
+        URL.endpoint("friends", "/v1/users/#{@id}/friends/count")
+      )["count"]
+    end
+
+    # @example
+    #   client = Rublox::Client.new
+    #   user = client.user_from_id(1)
+    #   puts user.follower_count # -> around 6 million
+    # @return [Integer] the count of how many followers the user has
+    def follower_count
+      @client.http_client.get(
+        URL.endpoint("friends", "/v1/users/#{@id}/followers/count")
+      )["count"]
+    end
+
+    # @example
+    #   client = Rublox::Client.new
+    #   user = client.user_from_id(1)
+    #   puts user.followings_count # -> 0
+    # @return [Integer] the count of how many users the user has followed
+    def followings_count
+      @client.http_client.get(
+        URL.endpoint("friends", "/v1/users/#{@id}/followings/count")
+      )["count"]
+    end
+
+    # @example
+    #   client = Rublox::Client.new
+    #   user = client.user_from_id(1)
+    #   puts user.status # -> "Welcome to Roblox, the Imagination Platform. Make friends, explore, and play games!"
+    # @return [String] the user's status
+    def status
+      @client.http_client.get(
+        URL.endpoint("users", "/v1/users/#{@id}/status")
+      )["status"]
+    end
+
+    # @example
+    #   client = Rublox::Client.new
+    #   user = client.user_from_id(1)
+    #   presence = user.presence
+    #   puts presence.last_location # -> "Website"
+    # @return [Presence] the presence state of the user
+    def presence
+      @client.user_presence_from_id(@id)
+    end
+
+    # @return [String] a readable string representation of the user
+    def to_s
+      "User of ID #{@id}, username: #{@username}"
+    end
+  end
+end

data/lib/rublox/models/full_group.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require "rublox/models/group_shout"
+require "rublox/models/limited_user"
+require "rublox/derive/group"
+
+module Rublox
+  # @note This class is handled internally by the public interface such as
+  #   {Client#group_from_id}. You should not be creating it yourself.
+  # The {FullGroup} class corresponds to a full group response you can get via
+  # https://groups.roblox.com/v1/groups/groupId. You can use it to get information
+  # about groups.
+  #
+  # See {Group} for methods you can call on groups!
+  class FullGroup
+    include Group
+
+    # @return [Integer] the group's ID
+    attr_reader :id
+
+    # @return [String] the group's name
+    attr_reader :name
+
+    # @return [String] the group's description
+    attr_reader :description
+
+    # @return [LimitedUser, nil] the group's owner, can be nil if the group has
+    #   no owner
+    attr_reader :owner
+
+    # @return [GroupShout, nil] the group's shout, can be nil if the group has
+    #   no shout
+    attr_reader :shout
+
+    # @return [Integer] the count of how many members the group has
+    attr_reader :member_count
+
+    # @return [true, false] is the group locked?
+    attr_reader :locked
+
+    # @return [true, false] is the group private/invite only?
+    attr_reader :private
+
+    # @param data [Hash]
+    # @param client [Client]
+    def initialize(data, client)
+      @id = data["id"]
+      @name = data["name"]
+      @description = data["description"]
+      @owner = LimitedUser.new(data["owner"], client) if data["owner"]
+      @shout = GroupShout.new(data["shout"], client, @id) if data["shout"]
+      @member_count = data["memberCount"]
+      # isLocked is only returned if the group is locked, else it is just null (awesome)
+      @locked = !data["isLocked"].nil?
+      @private = data["publicEntryAllowed"]
+
+      @client = client
+    end
+  end
+end

data/lib/rublox/models/full_user.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require "time"
+
+require "rublox/derive/user"
+
+module Rublox
+  # @note This class is handled internally by the public interface such as
+  #   {Client#user_from_id}. You should not be creating it yourself.
+  # The {FullUser} class corresponds to a full user response you can get via
+  # https://users.roblox.com/v1/users/userId. You can use it to get information
+  # about users.
+  #
+  # See {User} for methods you can call on users!
+  class FullUser
+    include User
+
+    # @return [Integer] the user's ID
+    attr_reader :id
+
+    # @return [String] the user's username
+    attr_reader :username
+
+    # @return [String] the user's display name
+    attr_reader :display_name
+
+    # @return [String] the user's profile description
+    attr_reader :description
+
+    # @return [true, false] is the user banned?
+    attr_reader :banned
+
+    # @return [Time] the user's join date
+    attr_reader :join_date
+
+    # @param data [Hash]
+    # @param client [Client]
+    def initialize(data, client)
+      @id = data["id"]
+      @username = data["name"]
+      @display_name = data["displayName"]
+      @description = data["description"]
+      @banned = data["banned"]
+      @join_date = Time.iso8601(data["created"])
+
+      @client = client
+    end
+  end
+end

data/lib/rublox/models/group_member.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Rublox
+  # @note This class is handled internally by the public interface such as
+  #   such as {Group#member_by_user}. You should not be creating it yourself.
+  # The {GroupMember} class corresponds to a member response, which contains
+  # information about the user, their role and group.
+  class GroupMember
+    # @return [LimitedUser] the user object tied to this member
+    attr_reader :user
+
+    # @return {GroupRole} the role object tied to this member
+    attr_reader :role
+
+    # @return [FullGroup] the group object tied to this member
+    attr_reader :group
+
+    # @param user [FullUser, LimitedUser]
+    # @param role [GroupRole]
+    # @param group [FullGroup]
+    # @param client [Client]
+    def initialize(user, role, group, client)
+      @user = user
+      @role = role
+      @group = group
+      @client = client
+    end
+
+    # @note Use this if you need the state of the member changed. If you only
+    #   want the role's state updated without updating the member's state, use
+    #   {GroupRole#refresh}
+    # @example
+    #   client = Rublox::Client.new
+    #   group = client.group_from_id(7384468)
+    #   member = group.member_by_id(1)
+    #   puts member.role.rank # -> 1
+    #   # Assume Roblox now has the Owner role
+    #   updated_member = member.refresh_role
+    #   puts updated_member.role.rank # -> 255
+    # @return [GroupMember] a new {GroupMember} with a new {#role}, if it has been changed.
+    def refresh_role
+      data = @client.http_client.get(
+        URL.endpoint("groups", "/v2/users/#{@user.id}/groups/roles")
+      )["data"].find { |role| role["group"]["id"] == @group.id }
+
+      GroupMember.new(
+        @user,
+        GroupRole.new(data["role"], @group, @client),
+        @group,
+        @client
+      )
+    end
+  end
+end

data/lib/rublox/models/group_role.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require "rublox/util/Errors"
+
+module Rublox
+  # @note This class is handled internally by the public interface such as
+  #   {Group#roles}. You should not be creating it yourself.
+  # The {GroupRole} class corresponds to a group's role. You can use it to get
+  # and set information about roles.
+  class GroupRole
+    # @return [Integer] the role's ID
+    attr_reader :id
+
+    # @return [String] the role's name
+    attr_reader :name
+
+    # @return [String, nil] the role's description. Can be nil if the authenticated
+    #   user does not have access to the group's role settings.
+    attr_reader :description
+
+    # @return [Integer] the role's rank (0-255)
+    attr_reader :rank
+
+    # @return [Integer] the count of how many users have the role
+    attr_reader :member_count
+
+    # @return [Group] the group tied to this role
+    attr_reader :group
+
+    # @param data [Hash]
+    # @param group [FullGroup]
+    # @param client [Client]
+    def initialize(data, group, client)
+      @id = data["id"]
+      @name = data["name"]
+      @description = data["description"]
+      @rank = data["rank"]
+      @member_count = data["memberCount"]
+      @group = group
+
+      @client = client
+    end
+
+    # @example
+    #   client = Rublox::Client.new
+    #   client.group_from_id(7384468)
+    #   role = client
+    #     .group_from_id(7384468)
+    #     .member_by_id(1)
+    #     .role
+    #   puts role.rank # -> 1
+    #   # Assume Roblox now has the Owner role
+    #   updated_role = role.refresh
+    #   puts updated_role.rank # -> 255
+    # @return [GroupRole] a mirrored {GroupRole} object, containing new information
+    #   about the role if it has been changed.
+    def refresh
+      data = @client.http_client.get(
+        URL.endpoint("groups", "/v1/groups/#{@group.id}/roles")
+      )["roles"].find { |role| role["id"] == @id }
+      raise Errors::RoleNotFoundError.new(@id, @group.id) unless data
+
+      GroupRole.new(
+        data,
+        @group,
+        @client
+      )
+    end
+  end
+end

data/lib/rublox/models/group_shout.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require "rublox/models/limited_user"
+
+module Rublox
+  # @note This class is handled internally by the public interface such as
+  #   {FullGroup#shout}. You should not be creating it yourself.
+  # The {GroupShout} class corresponds to a shout response. You can use it to get
+  # and set information about group shouts.
+  class GroupShout
+    # @return [String] the shout's body
+    attr_reader :body
+
+    # @return [LimitedUser, nil] the user that made the shout, can be nil if the
+    #   shout has no poster
+    attr_reader :poster
+
+    # @param data [Hash]
+    # @param client [Client]
+    # @param group_id [Integer]
+    def initialize(data, client, group_id)
+      @body = data["body"]
+      @poster = LimitedUser.new(data["poster"], client) if data["poster"]
+
+      @group_id = group_id
+      @client = client
+    end
+
+    # Sends a new shout.
+    # @example
+    #   client = Rublox::Client.new
+    #   group = client.group_from_id(1)
+    #   group.shout.send_shout("new shout")
+    # @param new_shout [String] the body of the new shout
+    # @return [void]
+    def send_shout(new_shout)
+      @client.http_client.patch(
+        URL.endpoint("groups", "v1/groups/#{@group_id}/status"),
+        json: {
+          message: new_shout
+        }
+      )
+    end
+
+    # Clears the group shout. Same as calling {#send_shout} with an empty string.
+    # @example
+    #   client = Rublox::Client.new
+    #   group = client.group_from_id(1)
+    #   group.shout.clear
+    #   # same as
+    #   group.shout.send_shout("")
+    # @return [void]
+    def clear
+      send_shout("")
+    end
+
+    # @return [GroupShout] A new group shout object with updated information.
+    def refresh
+      @client.group_from_id(@group_id).shout
+    end
+  end
+end

data/lib/rublox/models/limited_user.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require "time"
+
+require "rublox/derive/user"
+
+module Rublox
+  # @note This class is handled internally by the public interface such as
+  #   {FullGroup#owner}. You should not be creating it yourself.
+  # The {LimitedUser} is an user containing less information. It exists as some
+  # API's do not return full user information, and I decided to not send extra
+  # requests. You can call {#refresh} to get a {FullUser} if needed.
+  class LimitedUser
+    include User
+
+    # (see FullUser#id)
+    attr_reader :id
+
+    # (see FullUser#username)
+    attr_reader :username
+
+    # (see FullUser#display_name)
+    attr_reader :display_name
+
+    # (see FullUser#initialize)
+    def initialize(data, client)
+      @id = data["id"] || data["userId"] || data["builderId"]
+      @username = data["name"] || data["username"] || data["builder"]
+      @display_name = data["displayName"] || data["DisplayName"]
+
+      @client = client
+    end
+  end
+end