feat: add method for searching users

README.md

@@ -93,6 +93,26 @@ api.getUser('<user_id>')
 
 See the [user types](src/types/user.d.ts) for the response data.
 
+#### .searchUsers(params)
+
+Searches for users.
+
+```javascript
+api.searchUsers({
+  keyword: 'example',
+  count: 10,
+  cursor: 0,
+})
+  .then(res => console.log(res.data.user_list))
+  .catch(console.log);
+
+// Outputs:
+// [{ user_info: {...}, position: [], uniqposition: [] }, ...]
+
+```
+
+See the [search types](src/types/search.d.ts) for the complete request/response objects.
+
 #### .listPosts(params)
 
 Lists a user's posts.

src/index.ts

@@ -27,6 +27,8 @@ import {
   PostCommentRequest,
   PostCommentResponse,
   RequiredUserDefinedRequestParams,
+  SearchUsersRequest,
+  SearchUsersResponse,
   StaticRequestParams,
   Tag,
   TikTokAPIConfig,
@@ -121,6 +123,23 @@ export default class TikTokAPI {
   getUser = (userId: string) =>
     this.request.get<UserProfileResponse | BaseResponseData>('aweme/v1/user/', { params: { user_id: userId } })
 
+  /**
+   * Searches for users.
+   *
+   * @param params
+   * @returns {AxiosPromise<SearchUsersResponse | BaseResponseData>}
+   */
+  searchUsers = (params: SearchUsersRequest) =>
+    this.request.get<SearchUsersResponse | BaseResponseData>('aweme/v1/discover/search/', {
+      params: withDefaultListParams(<SearchUsersRequest>{
+        count: 10,
+        cursor: 0,
+        keyword: '',
+        type: 1,
+        ...params,
+      }),
+    })
+
   /**
    * Lists a user's posts.
    *

src/types/index.d.ts

@@ -8,6 +8,7 @@ export * from './login';
 export * from './music';
 export * from './post';
 export * from './request';
+export * from './search';
 export * from './tag';
 export * from './user';
 export * from './video';

src/types/search.d.ts

@@ -0,0 +1,46 @@
+import { CountOffsetParams, ListRequestParams, ListResponseData } from './request';
+import { CommonUserDetails } from './user';
+
+export interface SearchUsersRequest extends ListRequestParams, CountOffsetParams {
+  /** The term to search for */
+  keyword: string;
+
+  /** The scope of the search - users = 1 */
+  type?: number;
+}
+
+export interface SearchUsersResponse extends ListResponseData, CountOffsetParams {
+  /** A list of users that match the search term */
+  user_list: UserSearchResult[];
+
+  /** The scope of the search - users = 1 */
+  type: number;
+}
+
+export interface UserSearchResult {
+  /** If the user's nickname contains the search term, this array contains the location of the term */
+  position: SubstringPosition[];
+
+  /** If the user's username (unique_id) contains the search term, this array contains the location of the term */
+  uniqid_position: SubstringPosition[];
+
+  /** Details about the user */
+  user_info: CommonUserDetails;
+}
+
+/**
+ * Represents the location of a substring in a string.
+ *
+ * e.g. For the string "The quick brown fox", the substring "quick" would be:
+ * {
+ *     begin: 4,
+ *     end: 6
+ * }
+ */
+export interface SubstringPosition {
+  /** The start index of the substring */
+  begin: number;
+
+  /** The end index of the substring */
+  end: number;
+}

test/search.spec.ts

@@ -0,0 +1,45 @@
+import MockAdapter from 'axios-mock-adapter';
+import { assert } from 'chai';
+import { describe, it } from 'mocha';
+
+import TikTokAPI, {
+  CommonUserDetails,
+  SearchUsersResponse,
+} from '../src';
+import {
+  loadTestData,
+  mockConfig,
+  mockParams,
+} from './util';
+
+describe('#searchUsers()', () => {
+  it('a successful response should match the interface', async () => {
+    const api = new TikTokAPI(mockParams, mockConfig);
+    const mock = new MockAdapter(api.request);
+    mock
+      .onGet(new RegExp('aweme/v1/discover/search/\?.*'))
+      .reply(200, loadTestData('searchUsers.json'), {});
+
+    const res = await api.searchUsers({ keyword: 'example', count: 10, cursor: 0 });
+    const expected: SearchUsersResponse = {
+      extra: {
+        now: 1000000000000,
+      },
+      user_list: [
+        {
+          position: [{
+            begin: 0,
+            end: 6,
+          }],
+          uniqid_position: [],
+          user_info: {} as CommonUserDetails,
+        },
+      ],
+      type: 1,
+      cursor: 1,
+      has_more: 1,
+      status_code: 0,
+    };
+    assert.deepStrictEqual(res.data, expected);
+  });
+});

test/testdata/searchUsers.json

@@ -0,0 +1,19 @@
+{
+  "extra": {
+    "now": 1000000000000
+  },
+  "user_list": [
+    {
+      "position": [{
+        "begin": 0,
+        "end": 6
+      }],
+      "uniqid_position": [],
+      "user_info": {}
+    }
+  ],
+  "type": 1,
+  "cursor": 1,
+  "has_more": 1,
+  "status_code": 0
+}