feat: add method to list posts that use a sticker/effect

README.md

@@ -72,6 +72,7 @@ const api = new TikTokAPI(params, { signURL });
 * [.listFollowingFeed([params])](#listfollowingfeedparams)
 * [.getSticker(id)](#getstickerid)
 * [.getStickers([ids])](#getstickersids)
+* [.listPostsBySticker(params)](#listpostsbystickerparams)
 * [.joinLiveStream(id)](#joinlivestreamid)
 * [.leaveLiveStream(id)](#leavelivestreamid)
 * [.canStartLiveStream()](#canstartlivestream)
@@ -506,6 +507,25 @@ api.getStickers(['<sticker_id>', '<sticker_id>'])
 
 See the [sticker types](src/types/sticker.d.ts) for the complete response object.
 
+#### .listPostsBySticker(params)
+
+Lists posts that use a sticker/effect.
+
+```javascript
+api.listPostsBySticker({
+  count: 20,
+  cursor: 0,
+  sticker_id: '100000',
+})
+  .then(res => console.log(res.data.aweme_list))
+  .catch(console.log);
+
+// Outputs:
+// [{ author: {...}, aweme_id: '999', desc: 'description', music: {...}, statistics: {...}, video: {...} }, ...]
+```
+
+See the [sticker types](src/types/sticker.d.ts) for the complete request/response object.
+
 #### .joinLiveStream(id)
 
 Joins a live stream.  

src/index.ts

@@ -420,11 +420,22 @@ export default class TikTokAPI {
    *
    * @param stickerIds
    */
-  getStickers = (stickerIds: string[]) => this.request.get<API.GetStickersResponse>('aweme/v1/sticker/detail/', {
-    params: <API.GetStickersRequest>{
-      sticker_ids: stickerIds.join(','),
-    },
-  })
+  getStickers = (stickerIds: string[]) =>
+    this.request.get<API.GetStickersResponse | API.BaseResponseData>('aweme/v1/sticker/detail/', {
+      params: <API.GetStickersRequest>{
+        sticker_ids: stickerIds.join(','),
+      },
+    })
+
+  /**
+   * Lists posts that use a sticker/effect.
+   *
+   * @param params
+   */
+  listPostsBySticker = (params: API.ListPostsByStickerRequest) =>
+    this.request.get<API.ListPostsByStickerResponse | API.BaseResponseData>('aweme/v1/sticker/aweme/', {
+      params: withDefaultListParams(params),
+    })
 
   /**
    * Joins a live stream.

src/types/sticker.d.ts

@@ -1,7 +1,24 @@
 import {
   BaseResponseData,
+  CountOffsetParams,
+  ListRequestParams,
+  ListResponseData,
   Media,
 } from './request';
+import { Post } from './post';
+
+export interface ListPostsByStickerRequest extends ListRequestParams, CountOffsetParams {
+  /** The ID of the sticker */
+  sticker_id: string;
+}
+
+export interface ListPostsByStickerResponse extends ListResponseData, CountOffsetParams {
+  /** A list of posts using the sticker */
+  aweme_list: Post[];
+
+  /** Currently empty */
+  stickers: any[];
+}
 
 export interface GetStickersRequest {
   /** A list of sticker ids to get information about */

test/sticker.spec.ts

@@ -2,7 +2,11 @@ import MockAdapter from 'axios-mock-adapter';
 import { assert } from 'chai';
 import { describe, it } from 'mocha';
 
-import TikTokAPI, { GetStickersResponse } from '../src';
+import TikTokAPI, {
+  GetStickersResponse,
+  ListPostsByStickerRequest,
+  ListPostsByStickerResponse,
+} from '../src';
 import {
   loadTestData,
   mockConfig,
@@ -103,3 +107,31 @@ describe('#getStickers()', () => {
     assert.deepStrictEqual(res.data, expected);
   });
 });
+
+describe('#listPostsBySticker()', () => {
+  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/sticker/aweme/\?.*'))
+      .reply(200, loadTestData('listPostsBySticker.json'), {});
+
+    const res = await api.listPostsBySticker({
+      cursor: 0,
+      count: 20,
+      sticker_id: '100000',
+    } as ListPostsByStickerRequest);
+    const expected: ListPostsByStickerResponse = {
+      extra: {
+        now: 1000000000000,
+      },
+      aweme_list: [],
+      cursor: 20,
+      has_more: 1,
+      status_code: 0,
+      stickers: [],
+    };
+    assert.deepStrictEqual(res.data, expected);
+  });
+});

test/testdata/listPostsBySticker.json

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