diff --git a/lib/index.js b/lib/index.js index bd6063b3a..431ce54a4 100644 --- a/lib/index.js +++ b/lib/index.js @@ -169,6 +169,7 @@ noblox.getIdFromUsername = require('./users/getIdFromUsername.js') noblox.getPlayerInfo = require('./users/getPlayerInfo.js') noblox.getUsernameFromId = require('./users/getUsernameFromId.js') noblox.onBlurbChange = require('./users/onBlurbChange.js') +noblox.searchUsers = require('./users/searchUsers.js') noblox.clearSession = require('./util/clearSession.js') noblox.generalRequest = require('./util/generalRequest.js') noblox.getAction = require('./util/getAction.js') diff --git a/lib/users/searchUsers.js b/lib/users/searchUsers.js new file mode 100644 index 000000000..fed4540f7 --- /dev/null +++ b/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} + * @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 + ) +} diff --git a/test/users.test.js b/test/users.test.js index 8d9be36cc..8f78ad0c2 100644 --- a/test/users.test.js +++ b/test/users.test.js @@ -1,4 +1,4 @@ -const { getBlurb, getIdFromUsername, getPlayerInfo, getUsernameFromId, setCookie } = require('../lib') +const { getBlurb, getIdFromUsername, getPlayerInfo, getUsernameFromId, searchUsers, setCookie } = require('../lib') beforeAll(() => { return new Promise(resolve => { @@ -65,4 +65,20 @@ describe('Users Methods', () => { return expect(res).toEqual(expect.any(String)) }) }) + + it('searchUsers() returns results for the specified keyword', () => { + return searchUsers('roblox').then((res) => { + return expect(res).toMatchObject( + expect.arrayContaining([ + expect.objectContaining({ + previousUsernames: expect.any(Array), + hasVerifiedBadge: expect.any(Boolean), + id: expect.any(Number), + name: expect.any(String), + displayName: expect.any(String) + }) + ]) + ) + }) + }) }) diff --git a/typings/index.d.ts b/typings/index.d.ts index 5f12970f8..d39a4eac7 100644 --- a/typings/index.d.ts +++ b/typings/index.d.ts @@ -1162,6 +1162,14 @@ declare module "noblox.js" { guilded?: string; } + interface UserSearchResult { + previousUsernames: string[]; + hasVerifiedBadge: boolean; + id: number; + name: string; + displayName: string; + } + /// Badges interface BadgeAwarder { @@ -2169,6 +2177,11 @@ declare module "noblox.js" { */ function getUsernameFromId(id: number): Promise; + /** + * ✅ Gets user search results for a keyword. + */ + function searchUsers(keyword: string, limit: number, cursor: string): Promise; + /// Utility /** diff --git a/typings/jsDocs.ts b/typings/jsDocs.ts index 6a85a8a3a..25d38ec33 100644 --- a/typings/jsDocs.ts +++ b/typings/jsDocs.ts @@ -1603,6 +1603,14 @@ type PromotionChannelsResponse = { guilded?: string; } +type UserSearchResult = { + previousUsernames: string[]; + hasVerifiedBadge: boolean; + id: number; + name: string; + displayName: string; +} + /// Badges /**