noblox-asset.js 7.4.0

package/lib/users/getPlayerInfo.js

@@ -0,0 +1,128 @@
+// Includes
+const settings = require('../../settings.json')
+const getFollowingCount = require('../friends/getFollowingCount.js').func
+const getFollowerCount = require('../friends/getFollowerCount.js').func
+const getFriendCount = require('../friends/getFriendCount.js').func
+const getUserInfo = require('../users/getUserInfo.js').func
+
+// Args
+exports.required = ['userId']
+
+// Docs
+/**
+ * ✅ Get a user's information.
+ * @category User
+ * @alias getPlayerInfo
+ * @param { number } userId - The id of the user.
+ * @returns {Promise<PlayerInfo>}
+ * @deprecated `getPlayerInfo()` is deprecated; see `getUserInfo()`, `getFollowerCount()`, `getFollowingCount()`, `getFriendCount()`, `getUsernameHistory()`, `getUserFunds()`, `getPlayerThumbnail()` instead - high rate limits on endpoints such as username history and follower count have made this aggregate function not suitable for most users
+ * @example const noblox = require("noblox.js")
+ * let information = await noblox.getPlayerInfo({userId: 123456})
+ **/
+
+// Define
+function getPlayerInfo (userId) {
+  return new Promise((resolve, reject) => {
+    const requests = [
+      getUserInfo({ userId }),
+      getFriendCount({ userId }),
+
+      getFollowingCount({ userId }),
+      getFollowerCount({ userId })
+    ].map((promise) =>
+      promise.then(
+        (val) => ({ status: 'fulfilled', value: val }),
+        (rej) => ({ status: 'rejected', reason: rej })
+      )
+    )
+
+    Promise.all(requests).then((promiseResponses) => {
+      const responses = promiseResponses.map((response) => response.value)
+      const userBody = responses[0]
+      const failedResponses = promiseResponses.filter(
+        (presponse) => presponse.status === 'rejected'
+      )
+
+      if (userBody?.isBanned) {
+        const joinDate = new Date(userBody.created)
+        const blurb = userBody.description
+        const isBanned = userBody.isBanned
+        const username = userBody.name
+        const displayName = userBody.displayName
+
+        resolve({
+          username,
+          joinDate,
+          blurb,
+          isBanned,
+          displayName
+        })
+      } else if (failedResponses.length) {
+        const failureReason = failedResponses
+          .map((response) => response.reason)
+          .join('\n')
+
+        if (
+          (failureReason.toLowerCase().includes('too many requests') ||
+            failureReason.toLowerCase().includes('(429')) &&
+          settings.show_deprecation_warnings
+        ) {
+          console.warn()
+          console.warn(
+            '=============================================================================================================================================================================================='
+          )
+          console.warn(
+            'DEPRECATION WARNING: getPlayerInfo is an aggregate of multiple endpoints, rate limit changes have made this method unsuitable for many people, please use the individualized endpoints instead'
+          )
+          console.warn(
+            ' see getUserInfo(), getFollowerCount(), getFollowingCount(), getFriendCount(), getUsernameHistory(), getUserFunds(), getPlayerThumbnail()'
+          )
+          console.warn()
+          console.warn(
+            '> Opt out of these warnings using noblox.setOptions({ show_deprecation_warnings: false })'
+          )
+          console.warn(
+            '=============================================================================================================================================================================================='
+          )
+          console.warn()
+        }
+
+        const error = failedResponses.map((r) => r.reason).join('\n')
+        reject(new Error(error))
+      } else {
+        const responseBodies = responses.map((res) => res.body ?? res)
+        const friendCount = responseBodies[1]
+        const followerCount = responseBodies[3]
+        const followingCount = responseBodies[2]
+        const joinDate = new Date(userBody.created)
+        const blurb = userBody.description
+        const isBanned = userBody.isBanned
+        const username = userBody.name
+        const displayName = userBody.displayName
+
+        const currentTime = new Date()
+        const age = Math.round(
+          Math.abs(
+            (joinDate.getTime() - currentTime.getTime()) / (24 * 60 * 60 * 1000)
+          )
+        )
+
+        resolve({
+          username,
+          displayName,
+          blurb,
+          joinDate,
+          age,
+          friendCount,
+          followerCount,
+          followingCount,
+          isBanned
+        })
+      }
+    })
+  })
+}
+
+exports.func = (args) => {
+  return getPlayerInfo(args.userId)
+}

package/lib/users/getUserInfo.js

@@ -0,0 +1,35 @@
+// Includes
+const http = require('../util/http.js').func
+const RobloxAPIError = require('../util/apiError.js')
+
+// Args
+exports.required = ['userId']
+
+// Docs
+/**
+ * ✅ Get base-level user profile information
+ * @category User
+ * @alias getUserInfo
+ * @param { number } userId
+ * @returns {Promise<UserInfo>}
+**/
+
+// Define
+exports.func = function (args) {
+  const httpOpt = {
+    url: `//users.roblox.com/v1/users/${args.userId}`,
+    options: {
+      json: true,
+      method: 'GET',
+      resolveWithFullResponse: true
+    }
+  }
+
+  return http(httpOpt).then(function (res) {
+    if (res.statusCode !== 200) { throw new RobloxAPIError(res) }
+
+    res.body.created = new Date(res.body.created)
+
+    return res.body
+  })
+}

package/lib/users/getUsernameFromId.js

@@ -0,0 +1,45 @@
+// Includes
+const http = require('../util/http.js').func
+const cache = require('../cache')
+const RobloxAPIError = require('../util/apiError.js')
+
+// Args
+exports.required = ['id']
+
+// Docs
+/**
+ * ✅ Get a user's username from their user id.
+ * @category User
+ * @alias getUsernameFromId
+ * @param {number} id - The id of the user.
+ * @returns {Promise<string>}
+ * @example const noblox = require("noblox.js")
+ * let username = await noblox.getUsernameFromId(123456)
+**/
+
+// Define
+function getUsernameFromId (id) {
+  const httpOpt = {
+    url: `//users.roblox.com/v1/users/${id}`,
+    options: {
+      resolveWithFullResponse: true,
+      method: 'GET'
+    }
+  }
+  return http(httpOpt)
+    .then(function (res) {
+      if (res.statusCode === 200) {
+        const json = JSON.parse(res.body)
+        return json.name
+      } else {
+        throw new RobloxAPIError(res)
+      }
+    })
+}
+
+exports.func = function (args) {
+  const id = args.id
+  return cache.wrap('NameFromID', id, function () {
+    return getUsernameFromId(id)
+  })
+}

package/lib/users/getUsernameHistory.js

@@ -0,0 +1,42 @@
+// Includes
+const getPageResults = require('../util/getPageResults.js').func
+const cache = require('../cache')
+
+// Args
+exports.required = ['userId']
+exports.optional = ['limit', 'sortOrder', 'pageCursor']
+
+// Docs
+/**
+ * ✅ Get a user's username history.
+ * @category User
+ * @alias getUsernameHistory
+ * @param {number} userId
+ * @param {Limit=} [limit=100]
+ * @param {SortOrder=} [sortOrder=Asc]
+ * @param {string} cursor
+ * @returns {Promise<UsernameHistoryEntry[]>}
+ * @example const noblox = require("noblox.js")
+ * const history = await noblox.getUsernameHistory({ userId: 1, limit: 10, sortOrder: "Asc", cursor: "somecursorstring" })
+**/
+
+// Define
+function getUsernameHistory (userId, limit, sortOrder, cursor) {
+  return getPageResults({
+    url: `//users.roblox.com/v1/users/${userId}/username-history`,
+    query: {},
+    limit,
+    pageCursor: cursor,
+    sortOrder
+  })
+}
+
+exports.func = function (args) {
+  let { userId, limit, sortOrder, cursor } = args
+  limit ||= 100
+  sortOrder ||= 'Asc'
+
+  return cache.wrap('UsernameHistory', `${userId}-${limit}-${sortOrder}-${cursor}`, function () {
+    return getUsernameHistory(userId, limit, sortOrder, cursor)
+  })
+}

package/lib/users/onBlurbChange.js

@@ -0,0 +1,46 @@
+// Includes
+const shortPoll = require('../util/shortPoll.js').func
+const getBlurb = require('./getBlurb.js').func
+
+// Args
+exports.required = ['userId']
+
+// Docs
+/**
+ * ✅ An event for when a user's blurb changes.
+ * @category User
+ * @alias onBlurbChange
+ * @param {number} userId - The id of the user.
+ * @returns An EventEmitter that emits when a user's blurb changes.
+ * @example const noblox = require("noblox.js")
+ * const blurbEvent = noblox.onBlurbChange(1)
+ * blurbEvent.on("data", function(data) {
+ *  console.log("User's blurb changed!", data)
+ * })
+ * blurbEvent.on("error", function(err) {
+ *  console.error("Something went wrong: ", err)
+ *  // Handle error as needed
+ * })
+**/
+
+// Define
+exports.func = function (args) {
+  return shortPoll({
+    getLatest: function (latest) {
+      return getBlurb({ userId: args.userId })
+        .then(function (blurb) {
+          const given = []
+          if (blurb !== latest) {
+            latest = blurb
+            given.push(blurb)
+          }
+
+          return {
+            latest,
+            data: given
+          }
+        })
+    },
+    delay: 'onBlurbChange'
+  })
+}

package/lib/users/searchUsers.js

@@ -0,0 +1,41 @@
+// Includes
+const getPageResults = require('../util/getPageResults.js').func
+
+// Args
+exports.required = ['keyword']
+exports.optional = ['limit', 'cursor', 'jar']
+
+// Docs
+/**
+ * ✅ Gets a list of users matching the keyword
+ * @category User
+ * @alias searchUsers
+ * @param {string} keyword - The search term to use
+ * @param {10 | 25 | 50 | 100} limit - The maximum number of matching users to return
+ * @param {string} cursor - The cursor to use when fetching the next or previous page
+ * @returns {Promise<UserSearchResult[]>}
+ * @example const noblox = require("noblox.js")
+ * noblox.searchUsers("bob", 10, "cursorstring")
+**/
+
+// Define
+function searchUsers (jar, keyword, limit, cursor) {
+  return getPageResults({
+    url: '//users.roblox.com/v1/users/search',
+    jar,
+    limit,
+    pageCursor: cursor,
+    query: {
+      keyword
+    }
+  })
+}
+
+exports.func = function (args) {
+  return searchUsers(
+    args.jar,
+    args.keyword,
+    args.limit ?? 10,
+    args.cursor
+  )
+}

package/lib/util/apiError.js

@@ -0,0 +1,50 @@
+// The data should be a response object
+
+class RobloxAPIError extends Error {
+  constructor (data) {
+    super(getResponseBody(data))
+
+    this.name = 'RobloxAPIError'
+    this.httpStatusCode = data.statusCode
+    this.responseBody = getResponseBody(data)
+  }
+
+  get error () {
+    let obj
+
+    try {
+      obj = JSON.parse(this.responseBody)
+    } catch {
+      return { code: 0, message: this.responseBody.toString() }
+    }
+
+    if (Object.hasOwn(obj, 'error')) return obj.error // V1 open cloud and some very old BEDEV1 endpoints + some global errors
+
+    else if (Object.hasOwn(obj, 'errors')) { // Most BEDEV1 endpoints
+      return obj.errors.at(0) // In spite of BEDEV1 endpoint errors being nested in an array, they are never seen in groups.
+    } else if (Object.hasOwn(obj, 'code') && Object.hasOwn(obj, 'message')) { // V2 open cloud
+      return obj
+    } else return { code: 0, message: this.responseBody } // Roblox did a funny (i.e. the platform is down)
+  }
+
+  get caller () {
+    try {
+      // https://stackoverflow.com/a/57023880
+      return (new Error()).stack?.split('\n')[2]?.trim().split(' ').at(1) ?? null
+    } catch {
+      return null
+    }
+  }
+}
+
+function getResponseBody (data) {
+  if (typeof data.body === 'string') return data.body
+
+  try {
+    return JSON.stringify(data.body)
+  } catch {
+    throw Error('The passed response body is not a valid object')
+  }
+}
+
+module.exports = RobloxAPIError

package/lib/util/clearSession.js

@@ -0,0 +1,32 @@
+// Includes
+const settings = require('../../settings.json')
+
+// Args
+exports.required = ['jar']
+
+// Docs
+/**
+ * 🔐 Remove .ROBLOSECURITY cookie from jar.
+ * @category Utility
+ * @alias clearSession
+ * @param {CookieJar} jar - The CookieJar containing the .ROBLOSECURITY cookie.
+ * @returns {Promise<string>}
+ * @example const noblox = require("noblox.js")
+ * noblox.clearSession()
+**/
+
+// Define
+exports.func = function (args) {
+  const jar = args.jar
+  if (settings.session_only) {
+    jar.session = ''
+  } else {
+    const cookies = jar._jar.store.idx['roblox.com']
+    if (cookies) {
+      const cookie = cookies['/']
+      if (cookie && cookie['.ROBLOSECURITY']) {
+        delete cookies['/']['.ROBLOSECURITY']
+      }
+    }
+  }
+}

package/lib/util/generalRequest.js

@@ -0,0 +1,61 @@
+// Includes
+const http = require('./http.js').func
+const getVerification = require('./getVerification.js').func
+
+// Args
+exports.required = ['url', 'events']
+exports.optional = ['http', 'ignoreCache', 'getBody', 'jar']
+
+// Docs
+/**
+ * 🔐 Get the verification inputs and send a request.
+ * @category Utility
+ * @alias generalRequest
+ * @param {string} url - The url to post to.
+ * @param {object} events - Form data to send with the request.
+ * @param {boolean=} [ignoreCache=false] - Whether to ignore the cache or not.
+ * @param {boolean=} [getBody=false] - Whether to return the original body before the POST request.
+ * @param {CookieJar=} jar - The CookieJar containing the .ROBLOSECURITY cookie.
+ * @returns {Promise<Object>}
+ * @example const noblox = require("noblox.js")
+ * // Login using your cookie.
+ * noblox.generalRequest("//www.roblox.com/Groups/Group.aspx?gid=1", { __EVENTTARGET: 'JoinGroupDiv', __EVENTARGUMENT: 'Click' })
+**/
+
+// Define
+function general (jar, url, inputs, events, customOpt, body) {
+  for (const input in events) {
+    inputs[input] = events[input]
+  }
+  const httpOpt = {
+    url,
+    options: {
+      resolveWithFullResponse: true,
+      method: 'POST',
+      form: inputs,
+      jar
+    }
+  }
+  if (customOpt) {
+    if (customOpt.url) {
+      delete customOpt.url
+    }
+    Object.assign(httpOpt.options, customOpt)
+  }
+  return http(httpOpt).then(function (res) {
+    return {
+      res,
+      body
+    }
+  })
+}
+
+exports.func = function (args) {
+  const jar = args.jar
+  const url = args.url
+  const custom = args.http
+  return getVerification({ url: custom ? (custom.url || url) : url, jar, ignoreCache: args.ignoreCache, getBody: args.getBody })
+    .then(function (response) {
+      return general(jar, url, response.inputs, args.events, args.http, response.body)
+    })
+}

package/lib/util/getAction.js

@@ -0,0 +1,45 @@
+// Args
+exports.required = ['row']
+
+// Define
+const regex = [
+  /rank from (.+) to (.+)\.$/,
+  /deleted post "(.+)" by user .+\.$/,
+  /changed the group status to: (.*)$/
+]
+// This is no longer used within the library and is maintained only for the purposes of backwards compatibility
+// TODO: Remove this in next Semver major version
+
+// Docs
+/**
+ * ✅ Get the action row for the audit log text. Supported: change rank, delete post, change group status.
+ * @category Utility
+ * @alias getAction
+ * @deprecated
+ * @param {string} row - The audit log action row.
+ * @returns {AuditItem}
+**/
+
+exports.func = function (args) {
+  const row = args.row
+  const text = row.text()
+  const params = []
+  for (let i = 0; i < regex.length; i++) {
+    const match = text.match(regex[i])
+    if (match) {
+      for (let j = 1; j < match.length; j++) {
+        params.push(match[j])
+      }
+    }
+  }
+  const target = row.find('a').last().attr('href')
+  let found = target.match(/\?ID=(\d+)$/)
+  if (!found) {
+    found = target.match(/^games\/(\d+)\//)
+  }
+  found = found && parseInt(found[1], 10)
+  return {
+    target: found,
+    params
+  }
+}

package/lib/util/getAuthenticatedUser.js

@@ -0,0 +1,41 @@
+// Includes
+const http = require('./http.js').func
+
+// Args
+exports.optional = ['jar']
+
+// Docs
+/**
+ * 🔐 Get the current authenticated user.
+ * @category Utility
+ * @alias getAuthenticatedUser
+ * @returns {AuthenticatedUserData}
+ * @example const noblox = require("noblox.js")
+ * // Login using your cookie.
+ * const user = await noblox.getAuthenticatedUser()
+**/
+
+// Define
+exports.func = async function (args) {
+  const jar = args.jar
+  const httpOpt = {
+    url: '//users.roblox.com/v1/users/authenticated',
+    options: {
+      method: 'GET',
+      followRedirect: false,
+      jar,
+      json: true,
+      resolveWithFullResponse: true
+    }
+  }
+
+  const res = await http(httpOpt)
+
+  if (res.statusCode === 401) {
+    throw new Error('You are not logged in.')
+  } else if (res.statusCode !== 200) {
+    throw new Error(JSON.stringify(res.body))
+  }
+
+  return res.body
+}

package/lib/util/getCurrentUser.js

@@ -0,0 +1,58 @@
+// Includes
+const settings = require('../../settings.json')
+
+const noblox = require('../index.js')
+
+exports.optional = ['option', 'jar']
+
+// Docs
+/**
+ * 🔐 Get the current logged in user.
+ * @category Utility
+ * @alias getCurrentUser
+ * @param {string=} option - A specific option to return.
+ * @returns {LoggedInUserData}
+ * @example const noblox = require("noblox.js")
+ * @deprecated getCurrentUser() is deprecated; see getAuthenticatedUser(), getPremium(), getThumbnails(), getUserFunds() instead | August 27, 2024 - https://devforum.roblox.com/t/official-list-of-deprecated-web-endpoints/62889/66
+ * // Login using your cookie.
+ * const user = await noblox.getCurrentUser()
+**/
+
+// Define
+exports.func = async function (args) {
+  const jar = args.jar
+  const option = args.option
+  if (settings.show_deprecation_warnings) {
+    console.warn('[DEPRECATED]: getCurrentUser() is deprecated by Roblox; use getAuthenticatedUser(), getPremium(), getThumbnails(), or getUserFunds() instead!')
+    console.warn(' > Opt out of these warnings using noblox.setOptions({ show_deprecation_warnings: false })')
+  }
+
+  const currentUser = await noblox.getAuthenticatedUser(jar)
+  const [premiumStatus, thumbnailResponse, robuxBalance] = await Promise.all(
+    [
+      noblox.getPremium(currentUser.id, jar),
+      noblox.getPlayerThumbnail(currentUser.id, '352x352', 'png', false, 'Body', jar),
+      noblox.getUserFunds(currentUser.id, jar)
+    ]
+  )
+
+  const json = {
+    UserID: currentUser.id,
+    UserName: currentUser.name,
+    RobuxBalance: robuxBalance,
+    ThumbnailUrl: thumbnailResponse[0].imageUrl,
+    IsAnyBuildersClubMember: false,
+    IsPremium: premiumStatus,
+    DEPRECATION_WARNING: '[DEPRECATED]: noblox.getCurrentUser() is deprecated; use getAuthenticatedUser(), getPremium(), getThumbnails(), or getUserFunds() instead!'
+  }
+
+  if (!option) {
+    return json
+  }
+
+  // Support queried rgequests `getCurrentUser('UserID') -> only UserID`
+  const searchKey = Object.keys(json).filter((key) => {
+    return option.toLowerCase() === key.toLowerCase()
+  })[0]
+  return json[searchKey]
+}

package/lib/util/getGeneralToken.js

@@ -0,0 +1,52 @@
+// Includes
+const getHash = require('./getHash.js').func
+const http = require('./http.js').func
+const cache = require('../cache')
+const options = require('../options.js')
+
+// Args
+exports.optional = ['jar']
+
+// Docs
+/**
+ * 🔐 Generate an X-CSRF-Token.
+ * @category Utility
+ * @alias getGeneralToken
+ * @param {CookieJar=} jar - The jar containing the .ROBLOSECURITY token.
+ * @returns {Promise<string>}
+ * @example const noblox = require("noblox.js")
+ * // Login using your cookie.
+ * const XCSRF = await noblox.getGeneralToken()
+**/
+
+// Define
+function getGeneralToken (jar) {
+  if (!jar && !options.jar.session) {
+    throw new Error('Cannot get CSRF: You are not logged in.')
+  }
+  const httpOpt = {
+    // This will never actually sign you out because an X-CSRF-TOKEN isn't provided, only received
+    url: '//auth.roblox.com/v2/logout', // REQUIRES https. Thanks for letting me know, ROBLOX...
+    options: {
+      resolveWithFullResponse: true,
+      method: 'POST',
+      jar
+    }
+  }
+  return http(httpOpt)
+    .then(function (res) {
+      const xcsrf = res.headers['x-csrf-token']
+      if (xcsrf) {
+        return xcsrf
+      } else {
+        throw new Error('Did not receive X-CSRF-TOKEN')
+      }
+    })
+}
+
+exports.func = function (args) {
+  const jar = args.jar
+  return cache.wrap('XCSRF', getHash({ jar }), function () {
+    return getGeneralToken(jar)
+  })
+}