noblox.ts 4.10.5

package/lib/groups/getPlayers.js

@@ -0,0 +1,108 @@
+// Includes
+const http = require('../util/http.js').func
+
+// Args
+exports.required = ['group', ['rolesetId']]
+exports.optional = ['sortOrder', 'limit', 'cursor', 'jar']
+
+// Docs
+/**
+ * ✅ Get the players in a group for a specific role.
+ * @category Group
+ * @alias getPlayers
+ * @param {number} group - The id of the group.
+ * @param {number | Array<number>} rolesetId - The roleset's id.
+ * @param {SortOrder=} sortOrder - The order to get the players in.
+ * @param {Limit=} limit - The maximum result per a page.
+ * @param {string=} cursor - The cursor for the next page.
+ * @returns {Promise<GroupUser[]>}
+ * @example const noblox = require("noblox.js")
+ * const players = await noblox.getPlayers(1, 1117747196)
+**/
+
+// Define
+function getPlayersInRoleOnPage (jar, group, rolesetId, sortOrder, limit, cursor) {
+  return new Promise((resolve, reject) => {
+    const httpOpt = {
+      url: `//groups.roblox.com/v1/groups/${group}/roles/${rolesetId}/users?cursor=${cursor}&limit=${limit}&sortOrder=${sortOrder}`,
+      options: {
+        method: 'GET',
+        jar: jar,
+        resolveWithFullResponse: true
+      }
+    }
+    return http(httpOpt)
+      .then(function (res) {
+        if (res.statusCode === 200) {
+          resolve(JSON.parse(res.body))
+        } else {
+          const body = JSON.parse(res.body) || {}
+          if (body.errors && body.errors.length > 0) {
+            const errors = body.errors.map((e) => {
+              return e.message
+            })
+            reject(new Error(`${res.statusCode} ${errors.join(', ')}`))
+          }
+        }
+      }).catch(error => reject(error))
+  })
+}
+
+function getPlayersInRole (jar, group, rolesetId, sortOrder, limit, cursor, currentPlayers) {
+  return new Promise((resolve, reject) => {
+    if (!currentPlayers) currentPlayers = []
+
+    getPlayersInRoleOnPage(jar, group, rolesetId, sortOrder, 100, cursor, currentPlayers)
+      .then(function (pageData) {
+        const nextPageCursor = pageData.nextPageCursor
+        const dataArray = pageData.data
+
+        if (!dataArray) return reject(new Error('Error while retrieving players!'))
+
+        currentPlayers = currentPlayers.concat(dataArray)
+
+        if (limit > 0 && currentPlayers.length >= limit) {
+          return resolve(currentPlayers.slice(0, limit))
+        } else if (nextPageCursor === null) {
+          return resolve(currentPlayers)
+        }
+
+        getPlayersInRole(jar, group, rolesetId, sortOrder, limit, nextPageCursor, currentPlayers)
+          .then(function (newCurrentPlayers) {
+            return resolve(newCurrentPlayers)
+          })
+      }).catch(error => reject(error))
+  })
+}
+
+async function getPlayersInRoles (jar, group, rolesetIds, sortOrder, limit, cursor) {
+  let currentPlayers = []
+
+  for (let i = 0; i < rolesetIds.length; i++) {
+    const rolesetId = rolesetIds[i]
+    const roleLimit = limit <= 0 ? limit : limit - currentPlayers.length
+
+    await getPlayersInRole(jar, group, rolesetId, sortOrder, roleLimit, cursor)
+      .then((newData) => {
+        currentPlayers = currentPlayers.concat(newData)
+      })
+      .catch((error) => {
+        throw new Error(error)
+      })
+
+    if (limit > 0 && currentPlayers.length >= limit) {
+      return currentPlayers
+    }
+  }
+
+  return currentPlayers
+}
+
+exports.func = function (args) {
+  const jar = args.jar
+  const rolesetIds = Array.isArray(args.rolesetId) ? args.rolesetId : [args.rolesetId]
+  const sortOrder = args.sortOrder || 'Desc'
+  const limit = args.limit || -1
+  const cursor = args.cursor || ''
+  return getPlayersInRoles(jar, args.group, rolesetIds, sortOrder, limit, cursor)
+}

package/lib/groups/getRankInGroup.js

@@ -0,0 +1,52 @@
+// Includes
+const http = require('../util/http.js').func
+const cache = require('../cache')
+
+// Args
+exports.required = ['group', 'userId']
+
+// Docs
+/**
+ * ✅ Get the user's rank in the group.
+ * @category Group
+ * @alias getRankInGroup
+ * @param {number} group - The id of the group.
+ * @param {number} userId - The id of the user.
+ * @returns {Promise<number>}
+ * @example const noblox = require("noblox.js")
+ * const rankId = await noblox.getRankInGroup(1, 1)
+**/
+
+// Define
+function getRankInGroup (groupId, userId) {
+  if (typeof groupId === 'string') {
+    if (!isNaN(groupId)) {
+      // It's a number in a string
+      groupId = parseInt(groupId, 10)
+    } else {
+      throw new Error('Group id should be a number')
+    }
+  }
+  return http({ url: `//groups.roblox.com/v2/users/${userId}/groups/roles`, options: { json: true } }).then((body) => {
+    const error = body.errors && body.errors[0]
+
+    if (error) {
+      if (error.message === 'NotFound') {
+        throw new Error('An invalid UserID or GroupID was provided.')
+      } else {
+        throw new Error(error.message)
+      }
+    }
+
+    const groupObject = body.data.find((info) => groupId === info.group.id)
+
+    return groupObject ? parseInt(groupObject.role.rank) : 0
+  })
+}
+
+exports.func = function (args) {
+  const id = args.userId
+  return cache.wrap('Rank', id, function () {
+    return getRankInGroup(args.group, id)
+  })
+}

package/lib/groups/getRankNameInGroup.js

@@ -0,0 +1,52 @@
+// Includes
+const http = require('../util/http.js').func
+const cache = require('../cache')
+
+// Args
+exports.required = ['group', 'userId']
+
+// Docs
+/**
+ * ✅ Get a user's rank name in a group.
+ * @category Group
+ * @alias getRankNameInGroup
+ * @param {number} group - The id of the group.
+ * @param {number} userId - The id of the user.
+ * @returns {Promise<string>}
+ * @example const noblox = require("noblox.js")
+ * const rankName = await noblox.getRankNameInGroup(1, 1)
+**/
+
+// Define
+function getRankNameInGroup (group, userId) {
+  if (typeof group === 'string') {
+    if (!isNaN(group)) {
+      // It's a number in a string
+      group = parseInt(group, 10)
+    } else {
+      throw new Error('Group id should be a number')
+    }
+  }
+  return http({ url: `//groups.roblox.com/v2/users/${userId}/groups/roles`, options: { json: true } }).then((body) => {
+    const error = body.errors && body.errors[0]
+
+    if (error) {
+      if (error.message === 'NotFound') {
+        throw new Error('An invalid UserID or GroupID was provided.')
+      } else {
+        throw new Error(error.message)
+      }
+    }
+
+    const groupObject = body.data.find((info) => group === info.group.id)
+
+    return groupObject ? groupObject.role.name : 'Guest'
+  })
+}
+
+exports.func = function (args) {
+  const id = args.userId
+  return cache.wrap('Rank', id + 'Name', function () {
+    return getRankNameInGroup(args.group, id)
+  })
+}

package/lib/groups/getRole.js

@@ -0,0 +1,64 @@
+// Dependencies
+const entities = require('entities')
+
+// Includes
+const getRoles = require('./getRoles.js').func
+
+// Args
+exports.required = ['group', 'roleQuery']
+exports.optional = []
+
+// Docs
+/**
+ * ✅ Get a role in a group.
+ * @category Group
+ * @alias getRole
+ * @param {number | Array<number>} group - The ID of the group or an array of roles to query.
+ * @param {number | string} roleQuery - The rank of a role, the name of the role, or roleset ID.
+ * @returns {Promise<Role>}
+ * @example const noblox = require("noblox.js")
+ * const customerRole = await noblox.getRole(1, "Customer")
+**/
+
+// Define
+function getRole (roles, roleQuery) {
+  return new Promise((resolve, reject) => {
+    const result = []
+
+    for (let i = 0; i < roles.length; i++) {
+      const role = roles[i]
+      let find
+      if (typeof roleQuery === 'number' && roleQuery <= 255) {
+        find = role.rank
+      } else if (typeof roleQuery === 'string') {
+        find = entities.decodeHTML(role.name)
+      } else if (typeof roleQuery === 'number' || roleQuery > 255) {
+        find = role.id
+      }
+
+      if (roleQuery === find) {
+        result.push(role)
+      }
+    }
+
+    if (result.length === 1) {
+      resolve(result[0])
+    } else if (result.length > 1) {
+      reject(new Error(`There are two or more roles with the rank ${roleQuery}. You must specify the role name.`))
+    } else {
+      reject(new Error('Role not found with provided query.'))
+    }
+  })
+}
+
+exports.func = function (args) {
+  if (typeof args.group === 'number' || typeof args.group === 'string') {
+    return getRoles({ group: parseInt(args.group, 10) }).then(function (roles) {
+      return getRole(roles, args.roleQuery)
+    })
+  } else if (typeof args.group === 'object') {
+    return getRole(args.group, args.roleQuery)
+  } else {
+    throw new Error('Please provide a valid group or an array of roles to query.')
+  }
+}

package/lib/groups/getRolePermissions.js

@@ -0,0 +1,51 @@
+// Includes
+const http = require('../util/http.js').func
+
+exports.required = ['group', 'rolesetId']
+exports.optional = ['jar']
+
+// Docs
+/**
+ * 🔐 Get the permissions for a role.
+ * @category Group
+ * @alias getRolePermissions
+ * @param {number} group - The id of the group.
+ * @param {number} rolesetId - The rolesetId of the role.
+ * @returns {Promise<RolePermissions>}
+ * @example const noblox = require("noblox.js")
+ * // Login using your cookie
+ * const rolePermissions = await noblox.getRolePermissions(1, 1117747196)
+**/
+
+function getRolePermissions (group, rolesetId, jar) {
+  return new Promise((resolve, reject) => {
+    const httpOpt = {
+      url: `https://groups.roblox.com/v1/groups/${group}/roles/${rolesetId}/permissions`,
+      options: {
+        method: 'GET',
+        resolveWithFullResponse: true,
+        jar: jar
+      }
+    }
+
+    return http(httpOpt)
+      .then(function (res) {
+        const responseData = JSON.parse(res.body)
+        if (res.statusCode !== 200) {
+          let error = 'An unknown error has occurred.'
+          if (responseData && responseData.errors) {
+            error = responseData.errors.map((e) => e.message).join('\n')
+          }
+          reject(new Error(error))
+        } else {
+          resolve(responseData)
+        }
+      }).catch(error => reject(error))
+  })
+}
+
+// Define
+exports.func = function (args) {
+  const jar = args.jar
+  return getRolePermissions(args.group, args.rolesetId, jar)
+}

package/lib/groups/getRoles.js

@@ -0,0 +1,56 @@
+// Includes
+const http = require('../util/http.js').func
+const cache = require('../cache')
+
+// Args
+exports.required = ['group']
+
+// Docs
+/**
+ * ✅ Get the roles in a group.
+ * @category Group
+ * @alias getRoles
+ * @param {number} group - The id of the group.
+ * @returns {Promise<Role[]>}
+ * @example const noblox = require("noblox.js")
+ * const roles = await noblox.getRoles(1)
+**/
+
+// Define
+function getRoles (group) {
+  return new Promise((resolve, reject) => {
+    const httpOpt = {
+      url: `https://groups.roblox.com/v1/groups/${group}/roles`,
+      options: {
+        method: 'GET',
+        resolveWithFullResponse: true
+      }
+    }
+    return http(httpOpt)
+      .then(function (res) {
+        const responseData = JSON.parse(res.body)
+        if (res.statusCode !== 200) {
+          let error = 'An unknown error has occurred.'
+          if (responseData && responseData.errors) {
+            error = responseData.errors.map((e) => e.message).join('\n')
+          }
+          reject(new Error(error))
+        } else {
+          let roles = responseData.roles
+          roles = roles.sort((a, b) => a.rank - b.rank)
+          for (let i = 0; i < roles.length; i++) {
+            const role = roles[i]
+            role.ID = role.id
+          }
+          resolve(roles)
+        }
+      }).catch(error => reject(error))
+  })
+}
+
+exports.func = function (args) {
+  const group = args.group
+  return cache.wrap('Roles', group, function () {
+    return getRoles(group)
+  })
+}

package/lib/groups/getShout.js

@@ -0,0 +1,49 @@
+// Includes
+const http = require('../util/http.js').func
+
+// Args
+exports.required = ['group']
+exports.optional = []
+
+// Docs
+/**
+ * 🔓 Get the group's shout.
+ * @category Group
+ * @alias getShout
+ * @param {number} group - The id of the group.
+ * @returns {Promise<GroupShout>}
+ * @example const noblox = require("noblox.js")
+ * const groupShout = await noblox.getShout(1)
+**/
+
+// Define
+function getShout (group, jar) {
+  return new Promise((resolve, reject) => {
+    const httpOpt = {
+      url: `https://groups.roblox.com/v1/groups/${group}`,
+      options: {
+        method: 'GET',
+        resolveWithFullResponse: true,
+        jar: jar
+      }
+    }
+
+    return http(httpOpt)
+      .then(function (res) {
+        const responseData = JSON.parse(res.body)
+        if (res.statusCode === 400) {
+          reject(new Error('The group is invalid or does not exist.'))
+        }
+        if (responseData.shout === null) {
+          reject(new Error('You do not have permissions to view the shout for the group.'))
+        } else {
+          resolve(responseData.shout)
+        }
+      })
+      .catch(error => reject(error))
+  })
+}
+
+exports.func = function (args) {
+  return getShout(args.group, args.jar)
+}

package/lib/groups/getWall.js

@@ -0,0 +1,59 @@
+const http = require('../util/http.js').func
+
+exports.required = ['group']
+exports.optional = ['sortOrder', 'limit', 'cursor', 'jar']
+
+// Docs
+/**
+ * 🔓 Get the posts on the group wall.
+ * @category Group
+ * @alias getWall
+ * @param {number} group - The id of the group.
+ * @param {SortOrder=} sortOrder - The order to get the players in.
+ * @param {Limit=} limit - The maximum result per a page.
+ * @param {string=} cursor - The cursor for the next page.
+ * @returns {Promise<WallPostPage>}
+ * @example const noblox = require("noblox.js")
+ * // Login using your cookie
+ * const wallPosts = await noblox.getWall(1)
+**/
+
+function getPosts (group, sortOrder, limit, cursor, jar) {
+  return new Promise((resolve, reject) => {
+    const httpOpt = {
+      url: `https://groups.roblox.com/v2/groups/${group}/wall/posts?limit=${limit}&sortOrder=${sortOrder}&cursor=${cursor}`,
+      options: {
+        method: 'GET',
+        resolveWithFullResponse: true,
+        jar: jar
+      }
+    }
+
+    return http(httpOpt)
+      .then(function (res) {
+        const responseData = JSON.parse(res.body)
+        if (res.statusCode !== 200) {
+          let error = 'An unknown error has occurred.'
+          if (responseData && responseData.errors) {
+            error = responseData.errors.map((e) => e.message).join('\n')
+          }
+          reject(new Error(error))
+        } else {
+          responseData.data = responseData.data.map((entry) => {
+            entry.created = new Date(entry.created)
+            entry.updated = new Date(entry.updated)
+            return entry
+          })
+          resolve(responseData)
+        }
+      }).catch(error => reject(error))
+  })
+}
+
+// Define
+exports.func = function (args) {
+  const sortOrder = args.sortOrder || 'Asc'
+  const limit = args.limit || 100
+  const cursor = args.cursor || ''
+  return getPosts(args.group, sortOrder, limit, cursor, args.jar)
+}

package/lib/groups/groupPayout.js

@@ -0,0 +1,103 @@
+// Includes
+const http = require('../util/http.js').func
+const getGeneralToken = require('../util/getGeneralToken.js').func
+
+// Args
+exports.required = ['group', 'member', 'amount']
+exports.optional = ['recurring', 'usePercentage', 'jar']
+
+// Docs
+/**
+ * 🔐 Pay group funds out to a user.
+ * @category Group
+ * @alias groupPayout
+ * @param {number} group - The id of the group.
+ * @param {number | Array<number>} member - The member or array of members to payout.
+ * @param {number} amount - The amount of Robux for each recipient to receive.
+ * @param {boolean=} [recurring=false] - If the payment is recurring.
+ * @param {boolean=} [usePercentage=false] - If the amount is a percentage.
+ * @returns {Promise<void>}
+ * @example const noblox = require("noblox.js")
+ * // Login using your cookie
+ * noblox.groupPayout(1117747196, 55549140, 30)
+**/
+
+// Define
+function groupPayout (jar, token, group, data, recurring, usePercentage) {
+  return new Promise((resolve, reject) => {
+    const httpOpt = {
+      url: `//groups.roblox.com/v1/groups/${group}/payouts${recurring ? '/recurring' : ''}`,
+      options: {
+        resolveWithFullResponse: true,
+        method: 'POST',
+        jar: jar,
+        headers: {
+          'X-CSRF-TOKEN': token,
+          'Content-Type': 'application/json'
+        },
+        body: JSON.stringify({
+          PayoutType: (usePercentage ? 'Percentage' : 'FixedAmount'),
+          Recipients: data
+        })
+      }
+    }
+    return http(httpOpt)
+      .then(function (res) {
+        if (res.statusCode === 200) {
+          resolve()
+        } else {
+          const body = JSON.parse(res.body) || {}
+          if (body.errors && body.errors.length > 0) {
+            const errors = body.errors.map((e) => {
+              return e.message
+            })
+            reject(new Error(`${res.statusCode} ${errors.join(', ')}`))
+          }
+        }
+      }).catch(error => reject(error))
+  })
+}
+
+// Although I would normally leave it to the endpoint to error when incorrect percentages are given, it's not very reliable so I'll do it instead
+function isPercentage (num) {
+  return num >= 0 && num <= 100 && num % 1 === 0
+}
+
+exports.func = function (args) {
+  const jar = args.jar
+  let member = args.member
+  let amount = args.amount
+  const recurring = args.recurring || false
+  const usePercentage = recurring ? true : args.usePercentage
+  const data = []
+
+  if (!(member instanceof Array)) {
+    member = [member]
+    amount = [amount]
+  } else if (!(amount instanceof Array) || member.length !== amount.length) {
+    throw new Error('If member is an array amount must be a parallel array')
+  }
+  let total = 0
+  for (let i = 0; i < member.length; i++) {
+    const value = amount[i]
+    if (usePercentage) {
+      if (!isPercentage(value)) {
+        throw new Error('Percent values must be whole numbers between 0 and 100 inclusive')
+      }
+      total += value
+      if (total > 100) {
+        throw new Error('Sum of percent values must be less than 100')
+      }
+    }
+    data.push({
+      recipientId: member[i],
+      recipientType: 'User',
+      amount: value
+    })
+  }
+
+  return getGeneralToken({ jar: jar })
+    .then(function (xcsrf) {
+      return groupPayout(jar, xcsrf, args.group, data, recurring, usePercentage)
+    })
+}

package/lib/groups/handleJoinRequest.js

@@ -0,0 +1,60 @@
+// Includes
+const http = require('../util/http.js').func
+const getGeneralToken = require('../util/getGeneralToken.js').func
+
+// Args
+exports.required = ['group', 'userId', 'accept']
+exports.optional = ['jar']
+
+// Docs
+/**
+ * 🔐 Accept/decline a user's join request.
+ * @category Group
+ * @alias handleJoinRequest
+ * @param {number} group - The id of the group.
+ * @param {number} userId - The id of the user.
+ * @param {boolean} accept - If the user should be accepted into the group.
+ * @returns {Promise<void>}
+ * @example const noblox = require("noblox.js")
+ * // Login using your cookie
+ * noblox.handleJoinRequest(1, 1, true)
+**/
+
+function handleJoinRequest (group, userId, accept, jar, xcsrf) {
+  return new Promise((resolve, reject) => {
+    const httpOpt = {
+      url: `https://groups.roblox.com/v1/groups/${group}/join-requests/users/${userId}`,
+      options: {
+        method: accept ? 'POST' : 'DELETE',
+        resolveWithFullResponse: true,
+        jar: jar,
+        headers: {
+          'X-CSRF-TOKEN': xcsrf
+        }
+      }
+    }
+
+    return http(httpOpt)
+      .then(function (res) {
+        const responseData = JSON.parse(res.body)
+        if (res.statusCode !== 200) {
+          let error = 'An unknown error has occurred.'
+          if (responseData && responseData.errors) {
+            error = responseData.errors.map((e) => e.message).join('\n')
+          }
+          reject(new Error(error))
+        } else {
+          resolve()
+        }
+      }).catch(error => reject(error))
+  })
+}
+
+// Define
+exports.func = function (args) {
+  const jar = args.jar
+  return getGeneralToken({ jar: jar })
+    .then(function (xcsrf) {
+      return handleJoinRequest(args.group, args.userId, args.accept, args.jar, xcsrf)
+    })
+}