feat: add method to retrieve information about stickers (#86)

README.md

@@ -70,6 +70,8 @@ const api = new TikTokAPI(params, { signURL });
 * [.listPostsInHashtag(params)](#listpostsinhashtagparams)
 * [.listForYouFeed([params])](#listforyoufeedparams)
 * [.listFollowingFeed([params])](#listfollowingfeedparams)
+* [.getSticker(id)](#getstickerid)
+* [.getStickers([ids])](#getstickersids)
 * [.joinLiveStream(id)](#joinlivestreamid)
 * [.leaveLiveStream(id)](#leavelivestreamid)
 * [.canStartLiveStream()](#canstartlivestream)
@@ -472,6 +474,38 @@ api.listFollowingFeed()
 
 See the [feed types](src/types/feed.d.ts) for the complete request/response objects.
 
+#### .getSticker(id)
+
+Gets information about a sticker/effect.
+
+```javascript
+api.getSticker('<sticker_id>')
+  .then(res => console.log(res.data.sticker_infos))
+  .catch(console.log);
+
+// Outputs:
+// [{ id: '100000', name: 'cloned', owner_nickname: 'Effect Assistant', ...}]
+
+```
+
+See the [sticker types](src/types/sticker.d.ts) for the complete response object.
+
+#### .getStickers([ids])
+
+Gets information about many stickers/effects.
+
+```javascript
+api.getStickers(['<sticker_id>', '<sticker_id>'])
+  .then(res => console.log(res.data.sticker_infos))
+  .catch(console.log);
+
+// Outputs:
+// [{ id: '100000', name: 'cloned', owner_nickname: 'Effect Assistant', ...}, ...]
+
+```
+
+See the [sticker types](src/types/sticker.d.ts) for the complete response object.
+
 #### .joinLiveStream(id)
 
 Joins a live stream.  

src/index.ts

@@ -408,6 +408,24 @@ export default class TikTokAPI {
       }),
     })
 
+  /**
+   * Gets information about a sticker/effect.
+   *
+   * @param stickerId
+   */
+  getSticker = (stickerId: string) => this.getStickers([stickerId]);
+
+  /**
+   * Gets information about many stickers/effects.
+   *
+   * @param stickerIds
+   */
+  getStickers = (stickerIds: string[]) => this.request.get<API.GetStickersResponse>('aweme/v1/sticker/detail/', {
+    params: <API.GetStickersRequest>{
+      sticker_ids: stickerIds.join(','),
+    },
+  })
+
   /**
    * Joins a live stream.
    *

src/types/index.d.ts

@@ -13,6 +13,7 @@ export * from './post';
 export * from './qr-code';
 export * from './request';
 export * from './search';
+export * from './sticker';
 export * from './tag';
 export * from './user';
 export * from './video';

src/types/sticker.d.ts

@@ -0,0 +1,48 @@
+import {
+  BaseResponseData,
+  Media,
+} from './request';
+
+export interface GetStickersRequest {
+  /** A list of sticker ids to get information about */
+  sticker_ids: string;
+}
+
+export interface GetStickersResponse extends BaseResponseData {
+  sticker_infos: Sticker[];
+}
+
+export interface Sticker {
+  /** ??? */
+  children: [];
+
+  /** A description of the sticker */
+  desc: string;
+
+  /** The ID of the sticker */
+  effect_id: string;
+
+  /** The icon associated with the sticker */
+  icon_url: Media;
+
+  /** The ID of the sticker */
+  id: string;
+
+  /** True if the current user has favorited the sticker */
+  is_favorite: boolean;
+
+  /** The name of the sticker */
+  name: string;
+
+  /** The ID the user that owns the sticker (empty if owned by the Effect Assistant) */
+  owner_id: string;
+
+  /** The nickname of the owner, e.g. "Effect Assistant" */
+  owner_nickname: string;
+
+  /** ??? */
+  tags: any[];
+
+  /** The total number of posts using this sticker */
+  user_count: number;
+}

test/sticker.spec.ts

@@ -0,0 +1,105 @@
+import MockAdapter from 'axios-mock-adapter';
+import { assert } from 'chai';
+import { describe, it } from 'mocha';
+
+import TikTokAPI, { GetStickersResponse } from '../src';
+import {
+  loadTestData,
+  mockConfig,
+  mockParams,
+} from './util';
+
+describe('#getSticker()', () => {
+  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/detail/\?.*'))
+      .reply(200, loadTestData('getSticker.json'), {});
+
+    const res = await api.getSticker('100000');
+    const expected: GetStickersResponse = {
+      extra: {
+        now: 1000000000000,
+      },
+      sticker_infos: [
+        {
+          children: [],
+          desc: '',
+          effect_id: '100000',
+          icon_url: {
+            url_list: [
+              'http://sf-tk-sg.ibytedtos.com/obj/ies.fe.effect.alisg/111111',
+            ],
+          },
+          id: '100000',
+          is_favorite: false,
+          name: 'sticker1',
+          owner_id: '',
+          owner_nickname: 'Effect Assistant',
+          tags: [],
+          user_count: 10000,
+        },
+      ],
+      status_code: 0,
+    };
+    assert.deepStrictEqual(res.data, expected);
+  });
+});
+
+describe('#getStickers()', () => {
+  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/detail/\?.*'))
+      .reply(200, loadTestData('getStickers.json'), {});
+
+    const res = await api.getStickers(['100000', '100001']);
+    const expected: GetStickersResponse = {
+      extra: {
+        now: 1000000000000,
+      },
+      sticker_infos: [
+        {
+          children: [],
+          desc: '',
+          effect_id: '100000',
+          icon_url: {
+            url_list: [
+              'http://sf-tk-sg.ibytedtos.com/obj/ies.fe.effect.alisg/111111',
+            ],
+          },
+          id: '100000',
+          is_favorite: false,
+          name: 'sticker1',
+          owner_id: '',
+          owner_nickname: 'Effect Assistant',
+          tags: [],
+          user_count: 10000,
+        },
+        {
+          children: [],
+          desc: '',
+          effect_id: '100001',
+          icon_url: {
+            url_list: [
+              'http://sf-tk-sg.ibytedtos.com/obj/ies.fe.effect.alisg/222222',
+            ],
+          },
+          id: '100001',
+          is_favorite: false,
+          name: 'sticker2',
+          owner_id: '',
+          owner_nickname: 'Effect Assistant',
+          tags: [],
+          user_count: 10001,
+        },
+      ],
+      status_code: 0,
+    };
+    assert.deepStrictEqual(res.data, expected);
+  });
+});

test/testdata/getSticker.json

@@ -0,0 +1,25 @@
+{
+  "extra": {
+    "now": 1000000000000
+  },
+  "sticker_infos": [
+    {
+      "children": [],
+      "desc": "",
+      "effect_id": "100000",
+      "icon_url": {
+        "url_list": [
+          "http://sf-tk-sg.ibytedtos.com/obj/ies.fe.effect.alisg/111111"
+        ]
+      },
+      "id": "100000",
+      "is_favorite": false,
+      "name": "sticker1",
+      "owner_id": "",
+      "owner_nickname": "Effect Assistant",
+      "tags": [],
+      "user_count": 10000
+    }
+  ],
+  "status_code": 0
+}

test/testdata/getStickers.json

@@ -0,0 +1,42 @@
+{
+  "extra": {
+    "now": 1000000000000
+  },
+  "sticker_infos": [
+    {
+      "children": [],
+      "desc": "",
+      "effect_id": "100000",
+      "icon_url": {
+        "url_list": [
+          "http://sf-tk-sg.ibytedtos.com/obj/ies.fe.effect.alisg/111111"
+        ]
+      },
+      "id": "100000",
+      "is_favorite": false,
+      "name": "sticker1",
+      "owner_id": "",
+      "owner_nickname": "Effect Assistant",
+      "tags": [],
+      "user_count": 10000
+    },
+    {
+      "children": [],
+      "desc": "",
+      "effect_id": "100001",
+      "icon_url": {
+        "url_list": [
+          "http://sf-tk-sg.ibytedtos.com/obj/ies.fe.effect.alisg/222222"
+        ]
+      },
+      "id": "100001",
+      "is_favorite": false,
+      "name": "sticker2",
+      "owner_id": "",
+      "owner_nickname": "Effect Assistant",
+      "tags": [],
+      "user_count": 10001
+    }
+  ],
+  "status_code": 0
+}