untiktok-api 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2019 David Teather
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2019 David Teather
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,80 @@
+# UnTikTok-Api
+
+> An unofficial TikTok API wrapper in TypeScript, originally ported from the [TikTok-Api](https://github.com/davidteather/TikTok-Api) Python library. 
+> 
+> **Disclaimer:** This project is not affiliated with, endorsed by, or connected to TikTok, ByteDance, or the original author of the Python TikTok-Api. It is an independent, open-source TypeScript port designed for integration into Node.js applications and AI tools.
+
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.x-blue?logo=typescript)](https://www.typescriptlang.org/)
+[![Playwright](https://img.shields.io/badge/Playwright-1.44+-green?logo=playwright)](https://playwright.dev/)
+[![Node.js](https://img.shields.io/badge/Node.js-18+-brightgreen?logo=node.js)](https://nodejs.org/)
+
+---
+
+## Table of Contents
+
+- [Features](#features)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [API Reference](#api-reference)
+- [Examples](#examples)
+- [Common Issues](#common-issues)
+
+---
+
+## Features
+
+This API allows you to extract and automate interactions with TikTok data without requiring an official developer API key. It achieves this by using Playwright and stealth scripts to interface directly with TikTok's web endpoints.
+
+**Capabilities include:**
+- **Trending Feeds:** Fetch the most viral and trending videos on the platform.
+- **User Profiles:** Retrieve a user's uploaded videos, liked videos, **favorited videos**, **reposted videos**, **pinned videos**, **followers/following lists**, profile information, and **live stream status**.
+- **Hashtags:** Fetch videos under specific hashtags.
+- **Search:** Search for specific users or videos by keyword.
+- **Comments:** Extract comments and replies from specific videos, including support for **TikTok Stickers**.
+- **Sounds/Music:** Retrieve videos associated with a specific audio track or sound.
+- **Downloads:** Download raw video bytes (without watermarks) and audio streams directly.
+
+---
+
+## Installation
+
+First, clone the repository and navigate into the project directory:
+```bash
+git clone https://github.com/AlGhozaliRamadhan/UnTikTok-Api.git
+cd UnTikTok-Api
+npm install
+npx playwright install chromium
+```
+
+TypeScript check (no emit):
+```bash
+npm run typecheck
+```
+
+Build to `dist/`:
+```bash
+npm run build
+```
+
+---
+
+## Quick Start
+Looking to get started immediately? Check out the [Quick Start Guide](./docs/quick_start.md).
+
+---
+
+## API Reference
+For a full list of classes, methods, and constructor options, check out the [API Reference](./docs/api_reference.md).
+
+---
+
+## Examples & Guides
+
+For detailed examples and tutorials on how to use specific features, check out the dedicated guides in the `docs/` folder:
+
+- [Trending Videos](./docs/trending.md)
+- [User Data (Videos, Likes, Reposts) 🆕](./docs/user.md)
+- [Hashtag Videos](./docs/hashtag.md)
+- [Search Users](./docs/search.md)
+- [Download Videos](./docs/download.md)
+- [Session Caching (Bot evasion)](./docs/session_caching.md)

package/dist/api/comment.d.ts

@@ -0,0 +1,42 @@
+import type { TikTokApi } from "../tiktok";
+import type { User } from "./user";
+export declare class Comment {
+    /** Static reference to the parent TikTokApi instance */
+    parent: TikTokApi;
+    /** The id of the comment */
+    id: string;
+    /** The author of the comment */
+    author: User;
+    /** The text content of the comment */
+    text: string;
+    /** The number of likes on the comment */
+    likesCount: number;
+    /** The raw data associated with this comment */
+    asDict: Record<string, unknown>;
+    constructor(parent: TikTokApi, data?: Record<string, unknown>);
+    private _extractFromData;
+    /**
+     * Returns whether this comment contains a TikTok sticker.
+     * Note: The sticker image URL is not retrievable via this endpoint.
+     */
+    get isSticker(): boolean;
+    /**
+     * Returns the comment text with the "[Sticker]" placeholder stripped.
+     */
+    get stickerText(): string;
+    /**
+     * Returns reply comments for this comment.
+     *
+     * @example
+     * ```ts
+     * for await (const reply of comment.replies()) {
+     *   console.log(reply.text);
+     * }
+     * ```
+     */
+    replies(count?: number, cursor?: number, kwargs?: {
+        headers?: Record<string, string>;
+        sessionIndex?: number;
+    }): AsyncGenerator<Comment>;
+    toString(): string;
+}

package/dist/api/comment.js

@@ -0,0 +1,84 @@
+"use strict";
+// ============================================================
+// api/comment.ts
+// Mirrors TikTokApi/api/comment.py
+// ============================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Comment = void 0;
+const exceptions_1 = require("../exceptions");
+class Comment {
+    constructor(parent, data) {
+        this.parent = parent;
+        this.asDict = data ?? {};
+        if (data) {
+            this._extractFromData();
+        }
+    }
+    _extractFromData() {
+        const data = this.asDict;
+        this.id = data["cid"];
+        this.text = data["text"];
+        const usr = data["user"];
+        this.author = this.parent.user({
+            userId: usr["uid"],
+            username: usr["unique_id"],
+            secUid: usr["sec_uid"],
+        });
+        this.likesCount = data["digg_count"];
+    }
+    /**
+     * Returns whether this comment contains a TikTok sticker.
+     * Note: The sticker image URL is not retrievable via this endpoint.
+     */
+    get isSticker() {
+        return (this.text || "").includes("[Sticker]");
+    }
+    /**
+     * Returns the comment text with the "[Sticker]" placeholder stripped.
+     */
+    get stickerText() {
+        return (this.text || "").replace(/\[Sticker\]/g, "").trim();
+    }
+    /**
+     * Returns reply comments for this comment.
+     *
+     * @example
+     * ```ts
+     * for await (const reply of comment.replies()) {
+     *   console.log(reply.text);
+     * }
+     * ```
+     */
+    async *replies(count = 20, cursor = 0, kwargs = {}) {
+        let found = 0;
+        while (found < count) {
+            const params = {
+                count: 20,
+                cursor,
+                item_id: this.author.userId,
+                comment_id: this.id,
+            };
+            const resp = await this.parent.makeRequest({
+                url: "https://www.tiktok.com/api/comment/list/reply/",
+                params,
+                headers: kwargs.headers,
+                sessionIndex: kwargs.sessionIndex,
+            });
+            if (resp == null) {
+                throw new exceptions_1.InvalidResponseException(resp, "TikTok returned an invalid response.");
+            }
+            const comments = resp["comments"] ?? [];
+            for (const comment of comments) {
+                yield this.parent.comment({ data: comment });
+                found++;
+            }
+            if (!resp["has_more"])
+                return;
+            cursor = resp["cursor"];
+        }
+    }
+    toString() {
+        return `TikTokApi.comment(comment_id='${this.id}', text='${this.text}')`;
+    }
+}
+exports.Comment = Comment;

package/dist/api/hashtag.d.ts

@@ -0,0 +1,52 @@
+import type { TikTokApi } from "../tiktok";
+import type { Video } from "./video";
+export interface HashtagOptions {
+    name?: string | null;
+    id?: string | null;
+    data?: Record<string, unknown> | null;
+}
+export declare class Hashtag {
+    /** Static reference to the parent TikTokApi instance */
+    parent: TikTokApi;
+    /** The ID of the hashtag */
+    id?: string;
+    /** The name of the hashtag (without #) */
+    name?: string;
+    /** The raw data associated with this hashtag */
+    asDict?: Record<string, unknown>;
+    /** Additional split name if available */
+    splitName?: string;
+    /** Stats if available */
+    stats?: Record<string, unknown>;
+    constructor(parent: TikTokApi, { name, id, data }?: HashtagOptions);
+    /**
+     * Returns all information sent by TikTok related to this hashtag.
+     *
+     * @example
+     * ```ts
+     * const hashtag = api.hashtag({ name: 'funny' });
+     * const hashtagData = await hashtag.info();
+     * ```
+     */
+    info(kwargs?: {
+        msToken?: string;
+        headers?: Record<string, string>;
+        sessionIndex?: number;
+    }): Promise<Record<string, unknown>>;
+    /**
+     * Returns TikTok videos with this hashtag.
+     *
+     * @example
+     * ```ts
+     * for await (const video of api.hashtag({ name: 'funny' }).videos()) {
+     *   console.log(video.id);
+     * }
+     * ```
+     */
+    videos(count?: number, cursor?: number, kwargs?: {
+        headers?: Record<string, string>;
+        sessionIndex?: number;
+    }): AsyncGenerator<Video>;
+    private _extractFromData;
+    toString(): string;
+}

package/dist/api/hashtag.js

@@ -0,0 +1,118 @@
+"use strict";
+// ============================================================
+// api/hashtag.ts
+// Mirrors TikTokApi/api/hashtag.py
+// ============================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Hashtag = void 0;
+const exceptions_1 = require("../exceptions");
+class Hashtag {
+    constructor(parent, { name, id, data } = {}) {
+        this.parent = parent;
+        if (name != null)
+            this.name = name;
+        if (id != null)
+            this.id = id;
+        if (data) {
+            this.asDict = data;
+            this._extractFromData();
+        }
+    }
+    /**
+     * Returns all information sent by TikTok related to this hashtag.
+     *
+     * @example
+     * ```ts
+     * const hashtag = api.hashtag({ name: 'funny' });
+     * const hashtagData = await hashtag.info();
+     * ```
+     */
+    async info(kwargs = {}) {
+        if (!this.name) {
+            throw new TypeError("You must provide the name when creating this class to use this method.");
+        }
+        const urlParams = {
+            challengeName: this.name,
+            msToken: kwargs.msToken,
+        };
+        const resp = await this.parent.makeRequest({
+            url: "https://www.tiktok.com/api/challenge/detail/",
+            params: urlParams,
+            headers: kwargs.headers,
+            sessionIndex: kwargs.sessionIndex,
+        });
+        if (resp == null) {
+            throw new exceptions_1.InvalidResponseException(resp, "TikTok returned an invalid response.");
+        }
+        this.asDict = resp;
+        this._extractFromData();
+        return resp;
+    }
+    /**
+     * Returns TikTok videos with this hashtag.
+     *
+     * @example
+     * ```ts
+     * for await (const video of api.hashtag({ name: 'funny' }).videos()) {
+     *   console.log(video.id);
+     * }
+     * ```
+     */
+    async *videos(count = 30, cursor = 0, kwargs = {}) {
+        if (!this.id) {
+            await this.info(kwargs);
+        }
+        let found = 0;
+        while (found < count) {
+            const params = {
+                challengeID: this.id,
+                count: 30,
+                cursor,
+            };
+            const resp = await this.parent.makeRequest({
+                url: "https://www.tiktok.com/api/challenge/item_list/",
+                params,
+                headers: kwargs.headers,
+                sessionIndex: kwargs.sessionIndex,
+            });
+            if (resp == null) {
+                throw new exceptions_1.InvalidResponseException(resp, "TikTok returned an invalid response.");
+            }
+            const itemList = resp["itemList"] ?? [];
+            for (const item of itemList) {
+                yield this.parent.video({ data: item });
+                found++;
+            }
+            if (!resp["hasMore"])
+                return;
+            cursor = resp["cursor"];
+        }
+    }
+    _extractFromData() {
+        const data = this.asDict ?? {};
+        const keys = Object.keys(data);
+        if (keys.includes("title")) {
+            this.id = data["id"];
+            this.name = data["title"];
+        }
+        if (keys.includes("challengeInfo")) {
+            const challengeInfo = data["challengeInfo"];
+            if (challengeInfo["challenge"]) {
+                const challenge = challengeInfo["challenge"];
+                this.id = challenge["id"];
+                this.name = challenge["title"];
+                this.splitName = challenge["splitTitle"];
+            }
+            if (challengeInfo["stats"]) {
+                this.stats = challengeInfo["stats"];
+            }
+        }
+        if (!this.id || !this.name) {
+            this.parent.logger.error(`Failed to create Hashtag with data: ${JSON.stringify(data)}`);
+        }
+    }
+    toString() {
+        return `TikTokApi.hashtag(id='${this.id}', name='${this.name}')`;
+    }
+}
+exports.Hashtag = Hashtag;

package/dist/api/playlist.d.ts

@@ -0,0 +1,53 @@
+import type { TikTokApi } from "../tiktok";
+import type { Video } from "./video";
+import type { User } from "./user";
+export interface PlaylistOptions {
+    id?: string | null;
+    data?: Record<string, unknown> | null;
+}
+export declare class Playlist {
+    /** Static reference to the parent TikTokApi instance */
+    parent: TikTokApi;
+    /** The ID of the playlist */
+    id?: string;
+    /** The name of the playlist */
+    name?: string;
+    /** The video count of the playlist */
+    videoCount?: number;
+    /** The creator of the playlist */
+    creator?: User;
+    /** The cover URL of the playlist */
+    coverUrl?: string;
+    /** The raw data associated with this playlist */
+    asDict?: Record<string, unknown>;
+    constructor(parent: TikTokApi, { id, data }?: PlaylistOptions);
+    /**
+     * Returns information associated with this Playlist.
+     *
+     * @example
+     * ```ts
+     * const info = await api.playlist({ id: '7426714779919797038' }).info();
+     * ```
+     */
+    info(kwargs?: {
+        msToken?: string;
+        headers?: Record<string, string>;
+        sessionIndex?: number;
+    }): Promise<Record<string, unknown>>;
+    /**
+     * Returns videos in this playlist.
+     *
+     * @example
+     * ```ts
+     * for await (const video of api.playlist({ id: '7426714779919797038' }).videos()) {
+     *   console.log(video.id);
+     * }
+     * ```
+     */
+    videos(count?: number, cursor?: number, kwargs?: {
+        headers?: Record<string, string>;
+        sessionIndex?: number;
+    }): AsyncGenerator<Video>;
+    private _extractFromData;
+    toString(): string;
+}

package/dist/api/playlist.js

@@ -0,0 +1,112 @@
+"use strict";
+// ============================================================
+// api/playlist.ts
+// Mirrors TikTokApi/api/playlist.py
+// ============================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Playlist = void 0;
+const exceptions_1 = require("../exceptions");
+class Playlist {
+    constructor(parent, { id, data } = {}) {
+        this.parent = parent;
+        if (!id && !data?.["id"]) {
+            throw new TypeError("You must provide id parameter.");
+        }
+        this.id = id ?? undefined;
+        if (data) {
+            this.asDict = data;
+            this._extractFromData();
+        }
+    }
+    /**
+     * Returns information associated with this Playlist.
+     *
+     * @example
+     * ```ts
+     * const info = await api.playlist({ id: '7426714779919797038' }).info();
+     * ```
+     */
+    async info(kwargs = {}) {
+        const id = this.id;
+        if (!id) {
+            throw new TypeError("You must provide the playlist id when creating this class to use this method.");
+        }
+        const urlParams = {
+            mixId: id,
+            msToken: kwargs.msToken,
+        };
+        const resp = await this.parent.makeRequest({
+            url: "https://www.tiktok.com/api/mix/detail/",
+            params: urlParams,
+            headers: kwargs.headers,
+            sessionIndex: kwargs.sessionIndex,
+        });
+        if (resp == null) {
+            throw new exceptions_1.InvalidResponseException(resp, "TikTok returned an invalid response.");
+        }
+        this.asDict = resp["mixInfo"];
+        this._extractFromData();
+        return resp;
+    }
+    /**
+     * Returns videos in this playlist.
+     *
+     * @example
+     * ```ts
+     * for await (const video of api.playlist({ id: '7426714779919797038' }).videos()) {
+     *   console.log(video.id);
+     * }
+     * ```
+     */
+    async *videos(count = 30, cursor = 0, kwargs = {}) {
+        if (!this.id) {
+            await this.info(kwargs);
+        }
+        let found = 0;
+        while (found < count) {
+            const params = {
+                mixId: this.id,
+                count: Math.min(count, 30),
+                cursor,
+            };
+            const resp = await this.parent.makeRequest({
+                url: "https://www.tiktok.com/api/mix/item_list/",
+                params,
+                headers: kwargs.headers,
+                sessionIndex: kwargs.sessionIndex,
+            });
+            if (resp == null) {
+                throw new exceptions_1.InvalidResponseException(resp, "TikTok returned an invalid response.");
+            }
+            const itemList = resp["itemList"] ?? [];
+            for (const item of itemList) {
+                yield this.parent.video({ data: item });
+                found++;
+            }
+            if (!resp["hasMore"])
+                return;
+            cursor = resp["cursor"];
+        }
+    }
+    _extractFromData() {
+        let data = this.asDict ?? {};
+        if ("mixInfo" in data) {
+            data = data["mixInfo"];
+        }
+        this.id = data["id"] ?? data["mixId"];
+        this.name = data["name"] ?? data["mixName"];
+        this.videoCount = data["videoCount"];
+        const creatorData = data["creator"];
+        if (creatorData) {
+            this.creator = this.parent.user({ data: creatorData });
+        }
+        this.coverUrl = data["cover"];
+        if (!this.id || !this.name) {
+            this.parent.logger.error(`Failed to create Playlist with data: ${JSON.stringify(data)}`);
+        }
+    }
+    toString() {
+        return `TikTokApi.playlist(id='${this.id}')`;
+    }
+}
+exports.Playlist = Playlist;

package/dist/api/search.d.ts

@@ -0,0 +1,38 @@
+import type { TikTokApi } from "../tiktok";
+import type { User } from "./user";
+import type { Video } from "./video";
+export declare class Search {
+    /** Static reference to the parent TikTokApi instance */
+    parent: TikTokApi;
+    constructor(parent: TikTokApi);
+    /**
+     * Searches for users.
+     *
+     * Note: Your ms_token must have been used for a TikTok search already.
+     *
+     * @example
+     * ```ts
+     * for await (const user of api.search.users('david teather')) {
+     *   console.log(user.username);
+     * }
+     * ```
+     */
+    users(searchTerm: string, count?: number, cursor?: number, kwargs?: {
+        headers?: Record<string, string>;
+        sessionIndex?: number;
+    }): AsyncGenerator<User>;
+    /**
+     * Searches for a specific type of object.
+     *
+     * @example
+     * ```ts
+     * for await (const user of api.search.searchType('david teather', 'user')) {
+     *   console.log(user);
+     * }
+     * ```
+     */
+    searchType(searchTerm: string, objType: "user" | "item", count?: number, cursor?: number, kwargs?: {
+        headers?: Record<string, string>;
+        sessionIndex?: number;
+    }): AsyncGenerator<User | Video>;
+}