roget v1.0.2

roget

Asynchronous HTTP wrapper for communication with the Roblox APIs.

• Installation
• Dependencies
• Finding Your Cookie
• Example Usage
  • Get Authenticated User
  • Set Status of a User
• API
  • roget.fetch
  • Convenience Methods
  • Reloading the ROBLOSECURITY Cookie
    • roget.reloadCookie
  • Config
  • Roget Class
• Feedback
• License

Installation

To install the latest version of roget, run:

$ npm i roget

Dependencies

Dependencies should be automatically installed by your package manager. These are the packages which are used by Roget:

• node-fetch/node-fetch
• TehShrike/deepmerge

Finding Your Cookie

This guide is intended for Chromium-based browsers, such as Google Chrome or Microsoft Edge. They may apply to other browsers also.

1. Login to Roblox with the account you'd like to use with Roget
2. Press F12 to open the Chrome DevTools (alternatively Menu (⋮) -> More tools -> Developer tools)
3. Navigate to the "Application" tab
4. Expand the "Cookies" option under "Storage" and select "https://www.roblox.com"
5. Click the row named ".ROBLOSECURITY" in the resulting table
6. Copy the value of the cookie from the bottom panel
7. Paste this value where you intend to set the cookie property of roget (including the full warning); e.g. roget.cookie = "_|WARNING:-DO-NOT..."

Example Usage

These are just some of the basic ways to use roget. You can find more examples in the /examples directory.

Get Authenticated User

This example is using the ES6 async-await syntax. Roget methods return Promise objects, so equally you can use the .then.catch method.

// Import the roget module
const roget = require("roget")

// Set the cookie to enable authenticated requests
roget.cookie = "_|WARNING:-DO-NOT-SHARE-THIS.--Sharing-this-will-allow-someone-to-log-in-as-you-and-to-steal-your-ROBUX-and-items.|_ABCDEFGHIJKLMNOPQRSTUVWXYZ012345689"

// Fetch the username of the logged-in user
async function GetLoggedInUser() {
    const { name } = await roget.get("users", "/v1/users/authenticated")

    console.log(`Logged in as: ${name}`)
    // "Logged in as INSERT_NAME_HERE"
}

Set Status of a User

This example requires a CSRF token in order to authorise the request. Roget has built-in support for fetching a CSRF token for such APIs. See the following example:

// Import the roget module
const roget = require("roget")

// Set the cookie to enable authenticated requests
roget.cookie = "_|WARNING:-DO-NOT-SHARE-THIS.--Sharing-this-will-allow-someone-to-log-in-as-you-and-to-steal-your-ROBUX-and-items.|_ABCDEFGHIJKLMNOPQRSTUVWXYZ012345689"

// Send a HTTP PATCH request to the required endpoint
roget.patch("users", "/v1/users/12345678/status", {
    // Set the message to apply to the user's status
    data: { status: "Hello, world!" },

    // Enable CSRF token generation
    csrf: true,
}).then(({ status }) => {
    // Echo the status message back to the console
    console.log(status)
    // "Hello, world!"
})

Note that although this endpoint will only update the authenticated user's status, it still requires a user ID. You might store the ID in a variable or environment variable, although you can always follow the first example to dynamically fetch the user ID.

API

roget.fetch(api, path, config)

• api represents the subdomain to fetch from; e.g. users
• path represents the API method to communicate with
• config represents the options for the HTTP request
• Returns: Promise<data>

Perform a HTTP fetch request to the given API and path. All parameters are technically optional; api will default to "www" and path will default to "/".

Convenience methods

Roget also supports a few convenience methods. They will automatically set the method key of the config (the HTTP request method to perform). The parameters of each are the same as fetch, and will return the same as the return value of fetch.

• roget.get
• roget.post
• roget.patch
• roget.delete

If you require another method, please use fetch and set the method field of the config to the required method. These convenience methods are the result of a personal observation of commonly used methods by the official Roblox APIs.

Reloading the ROBLOSECURITY Cookie

Sometimes you will need to reload your ROBLOSECURITY cookie. This is because Roblox will occasionally log users out for security reasons. We don't know how often this happens, and could be several months before it happens, but as in line with the guidance given by noblox.js, we recommend you do it no more often than once per 24 hours.

roget.reloadCookie(setCookie)

• setCookie should be a boolean value. It is true by default. Setting it to false will prevent it from automatically updating the value of roget.cookie.
• Returns: Promise<newCookie>

The value returned by this should be saved in a file or database for next time your app restarts. This means you won't need to manually re-set the cookie. You might use an external database (e.g. MongoDB), embedded database (e.g. SQLite), or a file in the project's directory (using fs or similar).

roget.reloadCookie()
    .then(newCookie => {
        // store new cookie for next app restart
        // could be accomplished with SQLite or filesystem
    })

Config

These are the default values of the request config:

{
    method: "GET",                      // The HTTP request method
    params: [],                         // A string or object representing query string parameters
    timeout: 12000,                     // Time to wait before the request times out
    domain: "roblox.com",               // The root domain of each API. Generally this should not be changed
    csrf: false,                        // Whether to fetch a CSRF token before making a request
    data: undefined,                    // The contents of the request body. Automatically converted to a JSON string when defined as a non-string value
    userAgent: "RobloxStudio/WinINet",  // The user agent to use when performing HTTP requests; uses Studio's user agent by default
    cache: true,                        // Whether response data should be cached
    cacheTimeout: 15000,                // How long (in ms) a cached entry should be kept alive for
    json: true,                         // When true, HTTP response bodies are decoded as JSON; set to false for plain text; ignored when fullResponse is true
    redirects: "follow",                // The redirect mode to use when making the HTTP request (see the fetch API for more info)
    fullResponse: false,                // Returns the full Response object (from node-fetch) when set to true (will not transform response body, and non-200 responses will *not* throw)
    contentType: "application/json",    // The value to set to the content-type header when performing a HTTP request
}

Roget Class

Roget, by default, returns a singleton instance of the Roget class. You can import the Roget class from /src/core. These are the fields of Roget:

• ESubdomains - Enum of Roblox API subdomains
• fetch - method for performing HTTP request to the Roblox APIs
• _fetchCSRF - method (for internal use) for generating a CSRF token
• reloadCookie - method for regenerating a new ROBLOSECURITY cookie
• get - convenience method for performing a HTTP GET request
• post - convenience method for performing a HTTP POST request
• patch - convenience method for performing a HTTP PATCH request
• delete - convenience method for performing a HTTP DELETE request
• defaults - object representing the default Roget configuration (can be overridden by invdividual requests)
• cookie - a property for storing the ROBLOSECURITY cookie
• _cache - internal Map object to be used for caching HTTP GET data

Feedback

Please create a new issue if you wish to report bugs, leave feedback or request a feature.

License

MIT