feat: add method for listing posts in a hashtag (#38)

README.md

@@ -61,6 +61,7 @@ const api = new TikTokAPI(params, { signURL });
 * [.postComment(postId, text, [tags])](#postcommentpostid-text-tags)
 * [.listCategories(params)](#listcategoriesparams)
 * [.searchHashtags(params)](#searchhashtagsparams)
+* [.listPostsInHashtag(params)](#listpostsinhashtagparams)
 * [.listForYouFeed([params])](#listforyoufeedparams)
 * [.listFollowingFeed([params])](#listfollowingfeedparams)
 * [.joinLiveStream(id)](#joinlivestreamid)
@@ -310,6 +311,24 @@ api.searchHashtags({
 
 See the [search types](src/types/search.d.ts) for the complete request/response objects.
 
+#### .listPostsInHashtag(params)
+
+Lists posts in a hashtag.
+
+```javascript
+api.listPostsInHashtag({
+  ch_id: '<hashtag_id>',
+})
+  .then(res => console.log(res.data.aweme_list))
+  .catch(console.log);
+
+// Outputs:
+// [{ author: {...}, aweme_id: '999', desc: 'description', music: {...}, statistics: {...}, video: {...} }, ...]
+
+```
+
+See the [hashtag types](src/types/hashtag.d.ts) for the complete request/response objects.
+
 #### .listForYouFeed([params])
 
 Lists posts in the For You feed.

src/index.ts

@@ -251,6 +251,20 @@ export default class TikTokAPI {
       params: withDefaultListParams(params),
     })
 
+  /**
+   *
+   * @param params
+   * @returns {AxiosPromise<ListPostsInHashtagRequest | BaseResponseData>}
+   */
+  listPostsInHashtag = (params: API.ListPostsInHashtagRequest) =>
+    this.request.get<API.ListPostsInHashtagResponse | API.BaseResponseData>('aweme/v1/challenge/aweme/', {
+      params: withDefaultListParams(<API.ListPostsInHashtagRequest>{
+        query_type: 0,
+        type: 5,
+        ...params,
+      }),
+    })
+
   /**
    * Lists posts in the For You feed.
    *

src/types/hashtag.d.ts

@@ -0,0 +1,22 @@
+import {
+  CountOffsetParams,
+  ListRequestParams,
+  ListResponseData,
+} from './request';
+import { Post } from './post';
+
+export interface ListPostsInHashtagRequest extends ListRequestParams, CountOffsetParams {
+  /** The ID of the hashtag */
+  ch_id: string;
+
+  /** ??? - set to 0 */
+  query_type: number;
+
+  /** ??? - set to 5 */
+  type: number;
+}
+
+export interface ListPostsInHashtagResponse extends ListResponseData, CountOffsetParams {
+  /** A list of posts containing the hashtag */
+  aweme_list: Post[];
+}

src/types/index.d.ts

@@ -4,6 +4,7 @@ export * from './comment';
 export * from './feed';
 export * from './follow';
 export * from './follower';
+export * from './hashtag';
 export * from './like';
 export * from './live-stream';
 export * from './login';

test/hashtag.spec.ts

@@ -0,0 +1,32 @@
+import MockAdapter from 'axios-mock-adapter';
+import { assert } from 'chai';
+import { describe, it } from 'mocha';
+
+import TikTokAPI, { ListPostsInHashtagRequest, ListPostsInHashtagResponse } from '../src';
+import {
+  loadTestData,
+  mockConfig,
+  mockParams,
+} from './util';
+
+describe('#listPostsInHashtag()', () => {
+  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/challenge/aweme/\?.*'))
+      .reply(200, loadTestData('listPostsInHashtag.json'), {});
+
+    const res = await api.listPostsInHashtag({ ch_id: '1000' } as ListPostsInHashtagRequest);
+    const expected: ListPostsInHashtagResponse = {
+      extra: {
+        now: 1000000000000,
+      },
+      aweme_list: [],
+      cursor: 20,
+      has_more: 1,
+      status_code: 0,
+    };
+    assert.deepStrictEqual(res.data, expected);
+  });
+});

test/testdata/listPostsInHashtag.json

@@ -0,0 +1,9 @@
+{
+  "extra": {
+    "now": 1000000000000
+  },
+  "aweme_list": [],
+  "cursor": 20,
+  "has_more": 1,
+  "status_code": 0
+}