noblox-asset.js 7.4.0

package/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,29 @@
+---
+name: Bug report
+about: Create a report to help us improve
+title: "[BUG]"
+labels: ''
+assignees: ''
+
+---
+
+## Before posting a bug, be sure that someone else has not posted it already and it is an actual bug with noblox.js and not other frameworks like discord.js
+
+**Describe the bug**
+A clear and concise description of what the bug is.
+
+**To Reproduce**
+Steps to reproduce the behavior:
+1. Go to '...'
+2. Click on '....'
+3. Scroll down to '....'
+4. See error
+
+**Expected behavior**
+A clear and concise description of what you expected to happen.
+
+**Error messages**
+If applicable, add error messages to help explain your problem.
+
+**Additional context**
+Add any other context about the problem here.

package/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,22 @@
+---
+name: Feature request
+about: Suggest an idea for this project
+title: ''
+labels: ''
+assignees: ''
+
+---
+
+## Before posting a feature request, make sure that it hasn't been suggested before, is a feasible idea, and can benefit everyone.
+
+**Is your feature request related to a problem? Please describe.**
+A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
+
+**Describe the solution you'd like**
+A clear and concise description of what you want to happen.
+
+**Describe alternatives you've considered**
+A clear and concise description of any alternative solutions or features you've considered.
+
+**Additional context**
+Add any other context or screenshots about the feature request here.

package/.github/workflows/doc-publish.yml

@@ -0,0 +1,33 @@
+name: Publish docs
+
+on:
+  push:
+    branches:
+      - master
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 24
+
+      - name: Install yarn
+        run: npm install -g yarn
+
+      - name: Build docs
+        run: |
+          yarn install
+          yarn docs
+
+      - name: Deploy
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          deploy_key: ${{ secrets.ACTIONS_DEPLOY_KEY }}
+          publish_dir: ./docs
+          cname: noblox.js.org

package/.github/workflows/npmpublish.yml

@@ -0,0 +1,72 @@
+name: Test & Publish
+
+on:
+  pull_request:
+    branches:
+      - master
+      - next
+
+  push:
+    branches:
+      - master
+      - next
+
+permissions:
+  contents: write
+  packages: write
+  id-token: write
+  issues: write
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 24
+
+      - name: Install yarn
+        run: npm install -g yarn
+
+      - name: Install dependencies
+        run: yarn install
+
+      - name: Lint lib/
+        run: yarn lint
+
+  publish-npm:
+    needs: test
+    if: github.event_name == 'push'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 24
+
+      - name: Install yarn
+        run: npm install -g yarn
+
+      - name: Install dependencies
+        run: yarn install --frozen-lockfile
+
+      - name: Cache node modules
+        uses: actions/cache@v4
+        with:
+          path: node_modules
+          key: yarn-deps-${{ hashFiles('yarn.lock') }}
+          restore-keys: |
+            yarn-deps-${{ hashFiles('yarn.lock') }}
+
+      - name: Create Release
+        run: npx semantic-release@25.0.3
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+    

package/.github/workflows/run-tests.yml

@@ -0,0 +1,49 @@
+name: Run tests
+
+on:
+  workflow_dispatch
+
+
+jobs:
+  test:
+    permissions:
+      id-token: write
+
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 24
+
+      - name: Enable Corepack
+        run: corepack enable
+
+      - name: Install dependencies
+        run: yarn install --frozen-lockfile
+
+      - name: Lint lib/
+        run: yarn lint
+
+      - id: auth
+        name: Generate ID Token
+        uses: google-github-actions/auth@v2
+        with:
+          token_format: id_token
+          workload_identity_provider: ${{ vars.workload_identity_provider }}
+          service_account: ${{ vars.service_account }}
+          id_token_audience: "https://${{ vars.forwarder_hostname }}"
+          id_token_include_email: true
+
+      - name: Run tests
+        env:
+          API_KEY: ${{ secrets.API_KEY }}
+          COOKIE: ${{ secrets.COOKIE }}
+          COOKIE_2: ${{ secrets.COOKIE_2 }}
+          FORWARDER_HOSTNAME: ${{ vars.forwarder_hostname }}
+          ID_TOKEN: ${{ steps.auth.outputs.id_token }}
+        run: yarn test
+

package/CODE_OF_CONDUCT.md

@@ -0,0 +1,76 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as
+contributors and maintainers pledge to making participation in our project and
+our community a harassment-free experience for everyone, regardless of age, body
+size, disability, ethnicity, sex characteristics, gender identity and expression,
+level of experience, education, socio-economic status, nationality, personal
+appearance, race, religion, or sexual identity and orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to creating a positive environment
+include:
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+* Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery and unwelcome sexual attention or
+ advances
+* Trolling, insulting/derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or electronic
+ address, without explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+ professional setting
+
+## Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable
+behavior and are expected to take appropriate and fair corrective action in
+response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit, or
+reject comments, commits, code, wiki edits, issues, and other contributions
+that are not aligned to this Code of Conduct, or to ban temporarily or
+permanently any contributor for other behaviors that they deem inappropriate,
+threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community. Examples of
+representing a project or community include using an official project e-mail
+address, posting via an official social media account, or acting as an appointed
+representative at an online or offline event. Representation of a project may be
+further defined and clarified by project maintainers.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by contacting the project team at noblox@mit.edu. All
+complaints will be reviewed and investigated and will result in a response that
+is deemed necessary and appropriate to the circumstances. The project team is
+obligated to maintain confidentiality with regard to the reporter of an incident.
+Further details of specific enforcement policies may be posted separately.
+
+Project maintainers who do not follow or enforce the Code of Conduct in good
+faith may face temporary or permanent repercussions as determined by other
+members of the project's leadership.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
+available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html
+
+[homepage]: https://www.contributor-covenant.org
+
+For answers to common questions about this code of conduct, see
+https://www.contributor-covenant.org/faq

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2015 Joshua Lanese <froastj@gmail.com>
+
+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.

package/README.md

@@ -0,0 +1,182 @@
+<h1 align="center">
+    <img src="https://raw.githubusercontent.com/noblox/noblox.js/master/img/noblox-js.png" alt="noblox.js" width="400"/>
+    <br>
+</h1>
+
+<h4 align="center">A Node.js wrapper for interacting with the Roblox API; forked from <a href="https://github.com/sentanos/roblox-js">roblox-js</a>.</h4>
+
+<p align="center">
+    <a href="https://standardjs.com"><img src="https://img.shields.io/badge/code_style-standard-blue.svg?style=flat-square" alt="JavaScript Style Guide"/></a>
+    <a href="https://discord.gg/R5GVSyTVGv"><img src="https://img.shields.io/badge/discord-noblox.js-blue.svg?style=flat-square" alt="noblox.js Discord"/></a>
+    <a href="https://npmjs.org/noblox.js"><img src="https://img.shields.io/npm/v/noblox.js.svg?style=flat-square" alt="NPM package"/>
+</p>
+
+<p align="center">
+  <a href="#about">About</a> •
+  <a href="#prerequisites">Prerequisites</a> •
+  <a href="#installation">Installation</a> •
+  <a href="#quickstart">Quickstart</a> •
+  <a href="#documentation">Documentation</a> •
+  <a href="#common-issues">Common Issues</a> •
+  <a href="https://www.youtube.com/playlist?list=PLEW4K4VqMUb_VMA3Yp9LI4gReRyVWGTnU">YouTube Series</a> •
+  <a href="#credits">Credits</a> •
+  <a href="#license">License</a>
+</p>
+
+---
+
+# ⚠️ Deprecation Notice
+As of 29 March 2026, noblox.js is no longer maintained. This library is deprecated and will not receive further updates, including bug fixes or support for new Roblox API changes.
+We have a few recommendations for alternatives:
+- If you only need OpenCloud endpoints, [relatiocc/opencloud](https://github.com/relatiocc/opencloud)
+- For a more fully featured library, written in typescript: [rozod](https://rozod.alrovi.com/)
+
+Existing versions will remain available on npm, but may break as the Roblox API evolves.
+  Noblox.js and noblox.js-server are now deprecated, effective immediately. You should not create new work using these libraries, and where possible you should move off them to other ones.
+
+Thank you for being a part of our community, and I hope that the library was useful to you.
+
+
+--- 
+## About
+
+`noblox.js` is an open-source Roblox API wrapper written in JavaScript (with TypeScript compatibility) as a fork from sentanos's <a href="https://github.com/sentanos/roblox-js"> roblox-js module</a>.
+
+This NPM package enables operations froms the [Roblox website](https://www.roblox.com) to be executed via NodeJS; many individuals leverage `noblox.js` along side [Roblox's HTTPService](http://wiki.roblox.com/index.php?title=API:Class/HttpService) to create in-game scripts that interact with the website, i.e. promote users, shout events, and so on, or to create Discord utilities to manage their community.
+
+If you are looking for more information on how to create something like this, check out [our sister library, `noblox.js-server`](https://github.com/noblox/noblox.js-server) or [our YouTube series](https://www.youtube.com/playlist?list=PLEW4K4VqMUb_VMA3Yp9LI4gReRyVWGTnU). Keep in mind that these resources may not always be up to date, so it is **highly** encouraged that you learn to use the `noblox.js` library directly.
+
+
+Note: We use the semantic release plugin. You should treat npm as the source of truth regarding package versions - the package.json version in this repository will not be up to date.
+---
+
+## Prerequisites
+
+- [**Node.js®**](https://nodejs.org/en/download/current/) v18.18 or later
+
+---
+
+## Installation
+
+With node.js installed simply run: 
+```bash
+# Run this to install noblox.js locally to your repository. 
+$ npm install noblox.js
+
+# Alternatively, if you are using yarn:
+$ yarn add noblox.js
+
+# To use noblox.js anywhere, run this code to install the package globally:
+$ npm install noblox.js -g
+```
+That's it!
+
+---
+
+## Documentation
+
+You can locate the [`noblox.js` documentation here](https://noblox.js.org/); keep in mind some internal or legacy methods may not be documented.
+
+### Legend
+You may notice our documentation utilizes emojis in every function description; they have meanings!
+
+| Icon | Description |
+| ---- | ----------- |
+| 🔐 | Authentication through `setCookie()` is required to use this method.<sup id="a1">[1](#f1)</sup>
+| 🔓 | Authentication through `setCookie()` is required in **some** use-cases; dependent on the target's privacy settings.
+| ✅ | No authentication is required to use this method.
+
+<b id="f1">[1](#a1)</b> : Extended permissions may be required such as edit permissions or account ownership.
+
+---
+
+## Quickstart
+
+1) [Install `noblox.js`.](#installation)
+
+2) Retrieve your `.ROBLOSECURITY` cookie. Instructions on how to do that can be found [here](https://noblox.js.org/tutorial-Authentication.html).
+
+3) Write your code.
+
+    _Using `async/await` syntax:_
+    ```js
+    const noblox = require('noblox.js')
+    async function startApp () {
+        // You MUST call setCookie() before using any authenticated methods [marked by 🔐]
+        // Replace the parameter in setCookie() with your .ROBLOSECURITY cookie.
+        const currentUser = await noblox.setCookie('_|WARNING:-DO-NOT-SHARE-THIS.--Sharing-this-will-allow-someone-to-log-in-as-you-and-to-steal-your-ROBUX-and-items.|_6E6F626C6F782E6A73') 
+        console.log(`Logged in as ${currentUser.UserName} [${currentUser.UserID}]`)
+    
+        // Do everything else, calling functions and the like.
+        const groupInfo = await noblox.getGroup(9997719)
+        console.log(groupInfo)
+    }
+    startApp()
+    ```
+
+You are now using noblox.js!
+
+### [More examples can be found here.](https://github.com/noblox/noblox.js/tree/master/examples)
+
+**Promises are fundamental to this library**; if you are unfamiliar with JavaScript promises, we recommend you check out [our tutorial here](https://noblox.js.org/tutorial-Promises.html), and [Daniel Shiffman's JavaScript series](https://www.youtube.com/watch?v=QO4NXhWo_NM&list=PLRqwX-V7Uu6YgpA3Oht-7B4NBQwFVe3pr&index=12).
+
+---
+
+## Hiding Your Cookie
+
+It is bad practice to store your `.ROBLOSECURITY` cookie inside your codebase; it is too easy to accidentally screenshot or push this private key to GitHub. We recommend using a [package such as `dotenv`](https://www.npmjs.com/package/dotenv) to store your private information in environmental variables.
+
+We recommend using a secondary account for botting purposes.
+
+Consult their documentation or [follow this video](https://www.youtube.com/watch?v=17UVejOw3zA).
+
+---
+
+### Invalidating A Cookie
+
+In the event of accidentally exposing your `.ROBLOSECURITY` cookie, do not panic. Go to [`Account Settings` > `Security`](https://www.roblox.com/my/account#!/security), select `Sign out of all other sessions`, then log out of your account. This should invalidate your `.ROBLOSECURITY` cookie. 
+
+
+---
+
+## Common Issues
+
+> **Error: You are not logged in.**
+
+You may be calling a function before `setCookie()` is completed; make sure that you are awaiting `setCookie()` before initializing any event listeners or function calls.
+
+`noblox.js` is a promise based library, this enables you to run operations concurrently; however if you are not awaiting your promises, this means while `setCookie()` is validating your cookie, _your other functions will continue to run_- ~30ms is a **long time** at the computer scale.
+
+**Promises are fundamental to this library**; if you are unfamiliar with JavaScript promises, we recommend you check out [our tutorial here](https://noblox.js.org/tutorial-Promises.html), and [Daniel Shiffman's JavaScript series](https://www.youtube.com/watch?v=QO4NXhWo_NM&list=PLRqwX-V7Uu6YgpA3Oht-7B4NBQwFVe3pr&index=12).
+
+> **Error: 400 The roleset is invalid or does not exist.**
+
+You likely are using a `rankId` (0 - 255) instead of a `rolesetId` (>255); a `rolesetId` is a unique identifier for a role which you can find by calling [`getRoles(groupId)`](https://noblox.js.org/global.html#getRoles).
+
+Roblox's naming scheme is a fickle beast; similarly, a `developerProductId` is _different_ than a `productId` (which appears on the public facing dashboard); use [`getDeveloperProducts(placeId)`](https://noblox.js.org/global.html#getDeveloperProducts) to see the `developerProductId`.
+
+
+
+> **Error: Initialization failed: 401 Authorization has been denied for this request.**
+
+First, see the steps for `Error: You are not logged in`. 
+
+If this is unresolved, are you sure the bot has permissions to access this resource? Can you do this operation manually on the website through the bot account?
+
+At the end of the day, a 'bot' is a user account, it cannot magically bypass privacy restrictions or group permissions.
+
+---
+
+## Credits
+* [suufi](https://github.com/suufi) - Lead maintainer
+* [sentanos](https://github.com/sentanos) - We wouldn't exist without him. 😀
+* [Neztore](https://github.com/Neztore) - Library maintenance and review 
+* [alanbixby](https://github.com/alanbixby) - Library maintenance
+* [popeeyy](https://github.com/popeeyy) - Creation of the documentation.
+* [edward](https://github.com/edwrddd) - Helping with the creation of the documentation.
+
+---
+
+## License
+
+[MIT](https://github.com/noblox/noblox.js/blob/master/LICENSE)

package/eslint.config.mjs

@@ -0,0 +1,34 @@
+import jest from "eslint-plugin-jest";
+import globals from "globals";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import js from "@eslint/js";
+import { FlatCompat } from "@eslint/eslintrc";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const compat = new FlatCompat({
+    baseDirectory: __dirname,
+    recommendedConfig: js.configs.recommended,
+    allConfig: js.configs.all
+});
+
+export default [...compat.extends("standard", "plugin:jest/recommended"), {
+    plugins: {
+        jest,
+    },
+
+    languageOptions: {
+        globals: {
+            ...globals.commonjs,
+            ...globals.node,
+            Atomics: "readonly",
+            SharedArrayBuffer: "readonly",
+        },
+
+        ecmaVersion: 2018,
+        sourceType: "commonjs",
+    },
+
+    rules: {},
+}];

package/examples/cleanPlayers.js

@@ -0,0 +1,130 @@
+/**
+ * About:
+ * Exiles group members with optional filtering.
+ *
+ * NOTE: By default, this will exile all players in the rolesets provided. Change the body of shouldExile to alter this behaviour.
+ */
+
+// Settings
+const cookie = process.env.COOKIE || '' // Roblox account .ROBLOSECURITY cookie
+const options = {
+  group: 0, // Group ID
+  roleset: [1, 2, 3], // Array of roleset IDs - NOTE: This is not the same as role number
+  limit: -1, // Search limit - NOTE: When <= 0 there is no limit
+  exileLimit: -1, // Exile limit - NOTE: When <= 0 there is no limit
+  sortOrder: 'Asc' // Sort order: "Asc" or "Desc"
+}
+
+function shouldExile (player) {
+  /*
+  if (player.username === "Bob") {
+    return true // Exile Bob
+  } else if (player.username.toLowerCase().includes("bot")) {
+    return true // Exile users with username containing "bot"
+  } else if (player.userId > 1000000000) {
+    return true // Exile users with userId over 1 billion
+  }
+
+  return false
+  */
+
+  return true // Exile all players found
+}
+
+// Dependencies
+const noblox = require('noblox.js')
+const logUpdate = require('log-update')
+
+const players = {
+  passed: 0,
+  exiled: 0,
+  failed: 0
+}
+
+noblox.setCookie(cookie)
+  .then(async () => {
+    console.time('Time taken')
+
+    const getRolesOptions = {
+      group: options.group
+    }
+
+    const groupRoles = await noblox.getRoles(getRolesOptions)
+    const targetRoles = []
+
+    for (const role of groupRoles) {
+      if (options.roleset.includes(role.id)) {
+        targetRoles.push(role)
+      }
+
+      if (targetRoles.length === options.roleset.length) {
+        break
+      }
+    }
+
+    if (targetRoles.length === 0) {
+      console.error('No roles matching the roleset IDs were found.')
+
+      return
+    }
+
+    options.roleset = targetRoles.map((role) => {
+      return role.id
+    })
+
+    let totalPlayers = 0
+
+    for (const role of targetRoles) {
+      totalPlayers += role.memberCount
+    }
+
+    if (options.limit > 0) {
+      totalPlayers = Math.min(options.limit, totalPlayers)
+    }
+
+    if (totalPlayers >= 10000) {
+      console.log(`Fetching ${totalPlayers} players, this will take a while...`)
+    } else if (totalPlayers >= 2000) {
+      console.log(`Fetching ${totalPlayers} players, this may take a while...`)
+    } else {
+      console.log(`Fetching ${totalPlayers} players...`)
+    }
+
+    const getPlayersOptions = {
+      group: options.group,
+      limit: 100,
+      sortOrder: options.sortOrder,
+      rolesetId: options.roleset
+    }
+
+    const groupPlayers = await noblox.getPlayers(getPlayersOptions)
+
+    const logUpdater = setInterval(() => {
+      logUpdate(`Got ${groupPlayers.length} players, exiling...\nPassed: ${players.passed}\nExiled: ${players.exiled}\nFailed: ${players.failed}`)
+
+      if (players.passed + players.exiled + players.failed === groupPlayers.length) {
+        clearInterval(logUpdater)
+
+        console.timeEnd('Time taken')
+      }
+    }, 100)
+
+    groupPlayers.forEach((player) => {
+      if (shouldExile(player)) {
+        const exileOptions = {
+          group: options.group,
+          target: player.userId
+        }
+
+        noblox.exile(exileOptions)
+          .then(() => {
+            players.exiled++
+          })
+          .catch(() => {
+            players.failed++
+          })
+      } else {
+        players.passed++
+      }
+    })
+  })