@innovatespace/tiktok

v0.0.1

Published

a year ago

Tiktok SDK Wrapper for Node.js

Downloads

0High
0Medium
0Low

sleez007

tiktok sdk wrapper nodejs NestJS NextJs

TikTok Library for Node.js and SSR Frameworks

A Node.js client library that wraps the TikTok API. Current implementation covers login with TikTok, Display API, and Content Publish API.

Prerequisites

You need to create a TikTok Developer Account to get your client ID and secret keys. Please complete the following checklist before proceeding with implementation:

If you plan on using the Content Publish PULL_FROM_URL API (see documentation), ensure you complete domain verification and that your upload URLs contain the domain specified on the dashboard. Also, link the TikTok account you plan to use for testing to the developer dashboard (see instructions).
If you plan on using the login functionality, add your callback URL in the dashboard (see instructions).

Installation

npm install @innovatespace/tiktok

OAuth Usage

Instantiating the OAuthTicTok Class

//ESM Import
import { OAuthTicTok } from '@innovatespace/tiktok';

// CommonJS Import
const { OAuthTicTok } = require('@innovatespace/tiktok');

const oauth = new OAuthTicTok('your-client-id', 'your-client-secret');

Get Redirect URI

const data = await oauth.getRedirectUri({
  scope: [
    'user.info.basic',
    'user.info.profile',
    'user.info.stats',
    'video.list',
    'video.publish',
    'video.upload',
  ], // You can also use comma-separated string format: 'user.info.basic,user.info.profile,user.info.stats,video.list,video.publish,video.upload'
  redirect_uri: 'your-redirect-uri',
  state: 'csrf_token',
  code_challenge_method: 'sha256', // Your preferred encryption method, defaults to sha256
});

console.log(data);

// Response structure:
// {
//    "url": "url_to_redirect_to",
//    "verifier": "challenge_verifier",
//    "code_challenge": "code_challenge" // Not required, but useful for logging
// }

Exchange Code for Token

// This method is used when TikTok triggers your callback URL with the code for the logged-in user.
// Pass that code and CSRF token to get the user session tokens (access token, refresh token, and expiry time)
const data = await oauth.exchangeCodeForToken({
  code: 'your-code',
  verifier: 'CSRF-TOKEN',
});

console.log(data);

// data is:
// {
//    "access_token": "access_token",
//    "refresh_token": "refresh_token",
//    "token_type": "Bearer",
//    "expires_in": "expires_in" // access token expiry time in seconds. usually an hour
//    "scope": "scope" // scope covered by the access token i.e 'user.info.basic,user.info.profile,user.info.stats,video.list,video.publish,video.upload',
//    "open_id": "open_id", // user id
//    "refresh_expires_in": "refresh_expires_in" // refresh token expiry time in seconds usually 30 days
// }

Revoke Token

// This method is used to revoke the access and refresh tokens
const data = await oauth.revokeToken({
  token: 'access-token',
});

console.log(data);

// data is:
// {
//     "message": "Token revoked successfully"
// }

Refresh Token

// This method is used to refresh the access token
const data = await oauth.refreshToken({
  token: 'refresh-token',
});

console.log(data);

// data is:
// {
//    "access_token": "access_token",
//    "refresh_token": "refresh_token",
//    "token_type": "Bearer",
//    "expires_in": "expires_in" // access token expiry time in seconds. usually an hour
//    "scope": "scope" // scope covered by the access token i.e 'user.info.basic,user.info.profile,user.info.stats,video.list,video.publish,video.upload',
//    "open_id": "open_id", // user id
//    "refresh_expires_in": "refresh_expires_in" // refresh token expiry time in seconds usually 30 days
// }

Display API Usage

Instantiating the DisplayTicTok Class

//ESM Import
import { DisplayTicTok } from '@innovatespace/tiktok';

// CommonJS Import
const { DisplayTicTok } = require('@innovatespace/tiktok');

const display = new DisplayTicTok('your-access-token');

Get User Data

// This method is used to get the user data
// Please pass only the fields you are interested in and also only the one covered by your token scope
import { fieldOption } from '@innovatespace/tiktok';
const fields: fieldOption[] = ['open_id', 'union_id', 'avatar_url']; // Pass the fields you are interested in
const data = await display.userInfo(fields);

console.log(data);

// data is:
// {
//     "data": {
//         "user": {
//             "open_id": "open_id",
//             "avatar_url": "avatar_url",
//             "union_id": "union_id",
//         }
//     },
//     "error": {
//         "code": "ok",
//         "message": "",
//         "log_id": "log_id"
//     }
// }

List Videos

// This method is used to list user videos
import { VideoFieldOption } from '@innovatespace/tiktok';
const fields: VideoFieldOption[] = ['id', 'title']; // Pass the fields you are interested in. see more https://developers.tiktok.com/doc/tiktok-api-v2-video-list?enter_method=left_navigation

const filter = {
  filters: {
    max_count: 6, // Pagination size you need
    cursor: 'cursor_id', // Optional
  },
};
const data = await display.listVideo(filter, fields);

console.log(data);

// data is:
// {
//     "data": {
//         "videos": [
//             {
//                 "id": "video_id",
//                 "title": "video_title",
//             }
//         ]
//     },
//     "error": {
//         "code": "ok",
//         "message": "",
//         "log_id": "log_id"
//     }
// }

Query Videos

// This method is used to query user videos
import { VideoFieldOption } from '@innovatespace/tiktok';
const fields: VideoFieldOption[] = ['id', 'title']; // Pass the fields you are interested in. see more https://developers.tiktok.com/doc/tiktok-api-v2-video-query?enter_method=left_navigation

const filter = {
  filters: {
    video_ids: ['video_id_1', 'video_id_2'],
  },
};
const data = await display.queryVideo(filter, fields);

console.log(data);

// data is:
// {
//     "data": {
//         "videos": [
//             {
//                 "id": "video_id",
//                 "title": "video_title",
//             }
//         ]
//     },
//     "error": {
//         "code": "ok",
//         "message": "",
//         "log_id": "log_id"
//     }
// }

Content Publish API Usage

Instantiating the ContentPublishTicTok Class

//ESM Import
import { ContentPublishTicTok } from '@innovatespace/tiktok';

// CommonJS Import
const { ContentPublishTicTok } = require('@innovatespace/tiktok');

const content = new ContentPublishTicTok('your-access-token');

Query Creator Info

const data = await content.queryCreatorInfo();

console.log(data);

// data is:
// {
//    "data":{
//       "creator_avatar_url": "https://lf16-tt4d.tiktokcdn.com/obj/tiktok-open-platform/8d5740ac3844be417beeacd0df75aef1",
//       "creator_username": "tiktok",
//       "creator_nickname": "TikTok Official",
//       "privacy_level_options": ["PUBLIC_TO_EVERYONE", "MUTUAL_FOLLOW_FRIENDS", "SELF_ONLY"],
//       "comment_disabled": false,
//       "duet_disabled": false,
//       "stitch_disabled": true,
//       "max_video_post_duration_sec": 300
//    },
//     "error": {
//          "code": "ok",
//          "message": "",
//          "log_id": "202210112248442CB9319E1FB30C1073F3"
//      }
// }

Publish Image Content

const data = await content.publishImageContent({
  post_info: {
    title: 'Hello World',
    description: 'Hello World',
    privacy_level: 'PUBLIC_TO_EVERYONE',
    disable_comment: false,
    auto_add_music: false,
    brand_content_toggle: false,
    brand_organic_toggle: false,
  },
  source_info: {
    source: 'PULL_FROM_URL',
    photo_cover_index: 0,
    photo_images: ['https://example.com/image.jpg'],
  },
  post_mode: 'DIRECT_POST',
  media_type: 'PHOTO',
});

console.log(data);

// data is:
// {
//     "data": {
//         "publish_id": "p_pub_url~v2.123456789"
//     },
//     "error": {
//          "code": "ok",
//          "message": "",
//          "log_id": "202210112248442CB9319E1FB30C1073F3"
//      }
// }

Publish Video Content via PULL_FROM_URL

const data = await content.publishVideoPullFromUrlContent({
  post_info: {
    title: 'Hello World',
    privacy_level: 'PUBLIC_TO_EVERYONE', //see https://developers.tiktok.com/doc/content-posting-api-reference-direct-post?enter_method=left_navigation
    disable_duet: false,
    disable_comment: false,
    disable_stitch: false,
    video_cover_timestamp_ms: 0,
    brand_content_toggle: false,
    brand_organic_toggle: false,
    is_aigc: false,
  },
  source_info: {
    source: 'PULL_FROM_URL',
    video_url: 'https://example.com/video.mp4',
  },
});

console.log(data);

// data is:
// {
//     "data": {
//         "publish_id": "p_pub_url~v2.123456789"
//     },
//     "error": {
//          "code": "ok",
//          "message": "",
//          "log_id": "202210112248442CB9319E1FB30C1073F3"
//      }
// }

Publish Video Content via FILE_UPLOAD

const payload: UploadPayload = {
  uploadUrl: 'upload_url', // URL retrieved from the post publish endpoint, see https://developers.tiktok.com/doc/content-posting-api-reference-direct-post?enter_method=left_navigation
  buffer: Buffer,
  mimeType: 'video/mp4',
  chunks: Chunk[] // Optional: this will be recalculated from the buffer if omitted
}
const data = await content.uploadVideoToTikTokServer(payload);

console.log(data);

// data is:
// {
//     uploads: {
//         message: string; // Message per chunk uploaded. This is computed based on the size of the uploaded file and number of chunks generated following TikTok rules
//                          // See https://developers.tiktok.com/doc/content-posting-api-media-transfer-guide?enter_method=left_navigation
//     }[];
//     chunks: number;
// }

Publish Video Content via Publish and Upload with Ease (Recommended)

This method is a wrapper around the publish and upload video methods. It handles the entire upload process for you, so you can publish and upload your file in one go.

const payload: PublishUploadParam = {
  post_info: {
    title: 'Hello World',
    privacy_level: 'PUBLIC_TO_EVERYONE', //see https://developers.tiktok.com/doc/content-posting-api-reference-direct-post?enter_method=left_navigation
    disable_duet: false,
    disable_comment: false,
    disable_stitch: false,
    video_cover_timestamp_ms: 0,
    brand_content_toggle: false,
    brand_organic_toggle: false,
    is_aigc: false,
  },
  buffer: Buffer,
  mimeType: 'video/mp4',
};
const data = await content.publishAndUploadVideo(payload);

console.log(data);

// data is:
// {
//     publishResponse: {
//         data: {
//             publish_id: string;
//             upload_url?: string;
//         };
//         error: {
//             "code": "ok",
//             "message": "",
//             "log_id":"202210112248442CB9319E1FB30C1073F3"
//         }
//     },
//     uploads: {
//         message: string;
//     }[];
// }

Publish Video Via File Upload

const payload: PublishUploadParam = {
  post_info: {
    title: 'Hello World',
    privacy_level: 'PUBLIC_TO_EVERYONE', //see https://developers.tiktok.com/doc/content-posting-api-reference-direct-post?enter_method=left_navigation
    disable_duet: false,
    disable_comment: false,
    disable_stitch: false,
    video_cover_timestamp_ms: 0,
    brand_content_toggle: false,
    brand_organic_toggle: false,
    is_aigc: false,
  },
  buffer: Buffer,
  mimeType: 'video/mp4',
};
const data = await content.publishVideoFileUploadContent(payload);

console.log(data);

// data is:
// {
//     data: {
//         publish_id: string;
//         upload_url?: string;
//     };
//     error: ContentError;
//     chunks: Chunk[];
//     mimeType: string;
// }

Development

Building

nx build tiktok

Running Unit Tests

nx test tiktok

Tests are executed using Jest.

Contributing

Please read our contributing guide to learn how to contribute to this project.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Authors

Kingsley Etoka

Acknowledgments

TikTok API Documentation