untiktok-api 1.0.0

package/dist/api/search.js

@@ -0,0 +1,98 @@
+"use strict";
+// ============================================================
+// api/search.ts
+// Mirrors TikTokApi/api/search.py
+// ============================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Search = void 0;
+const exceptions_1 = require("../exceptions");
+class Search {
+    constructor(parent) {
+        this.parent = parent;
+    }
+    /**
+     * 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);
+     * }
+     * ```
+     */
+    async *users(searchTerm, count = 10, cursor = 0, kwargs = {}) {
+        for await (const user of this.searchType(searchTerm, "user", count, cursor, kwargs)) {
+            yield user;
+        }
+    }
+    /**
+     * Searches for a specific type of object.
+     *
+     * @example
+     * ```ts
+     * for await (const user of api.search.searchType('david teather', 'user')) {
+     *   console.log(user);
+     * }
+     * ```
+     */
+    async *searchType(searchTerm, objType, count = 10, cursor = 0, kwargs = {}) {
+        let found = 0;
+        let searchId = "";
+        while (found < count) {
+            const params = {
+                keyword: searchTerm,
+                cursor,
+                from_page: "search",
+                web_search_code: JSON.stringify({
+                    tiktok: {
+                        client_params_x: {
+                            search_engine: {
+                                ies_mt_user_live_video_card_use_libra: 1,
+                                mt_search_general_user_live_card: 1,
+                            },
+                        },
+                        search_server: {},
+                    },
+                }),
+            };
+            if (searchId) {
+                params["search_id"] = searchId;
+            }
+            const resp = await this.parent.makeRequest({
+                url: `https://www.tiktok.com/api/search/${objType}/full/`,
+                params,
+                headers: kwargs.headers,
+                sessionIndex: kwargs.sessionIndex,
+            });
+            if (resp == null) {
+                throw new exceptions_1.InvalidResponseException(resp, "TikTok returned an invalid response.");
+            }
+            if (objType === "user") {
+                const userList = resp["user_list"] ?? [];
+                for (const user of userList) {
+                    const userInfo = user["user_info"];
+                    yield this.parent.user({
+                        secUid: userInfo["sec_uid"],
+                        userId: userInfo["user_id"],
+                        username: userInfo["unique_id"],
+                    });
+                    found++;
+                }
+            }
+            else if (objType === "item") {
+                const itemList = resp["item_list"] ?? [];
+                for (const item of itemList) {
+                    yield this.parent.video({ data: item });
+                    found++;
+                }
+            }
+            if (!resp["has_more"])
+                return;
+            cursor = resp["cursor"];
+            searchId = resp["rid"] ?? "";
+        }
+    }
+}
+exports.Search = Search;

package/dist/api/sound.d.ts

@@ -0,0 +1,57 @@
+import type { TikTokApi } from "../tiktok";
+import type { User } from "./user";
+import type { Video } from "./video";
+export interface SoundOptions {
+    id?: string | null;
+    data?: Record<string, unknown> | null;
+}
+export declare class Sound {
+    /** Static reference to the parent TikTokApi instance */
+    parent: TikTokApi;
+    /** TikTok's ID for the sound */
+    id?: string;
+    /** The title of the song */
+    title?: string;
+    /** The author of the song */
+    author?: User;
+    /** Duration in seconds */
+    duration?: number;
+    /** Whether the song is original */
+    original?: boolean;
+    /** Play URL */
+    playUrl?: string;
+    /** Cover URL (large) */
+    coverLarge?: string;
+    /** The raw data */
+    asDict?: Record<string, unknown>;
+    constructor(parent: TikTokApi, { id, data }?: SoundOptions);
+    /**
+     * Returns all information sent by TikTok related to this sound.
+     *
+     * @example
+     * ```ts
+     * const soundInfo = await api.sound({ id: '7016547803243022337' }).info();
+     * ```
+     */
+    info(kwargs?: {
+        msToken?: string;
+        headers?: Record<string, string>;
+        sessionIndex?: number;
+    }): Promise<Record<string, unknown>>;
+    /**
+     * Returns videos created with this sound.
+     *
+     * @example
+     * ```ts
+     * for await (const video of api.sound({ id: '7016547803243022337' }).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/sound.js

@@ -0,0 +1,133 @@
+"use strict";
+// ============================================================
+// api/sound.ts
+// Mirrors TikTokApi/api/sound.py
+// ============================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Sound = void 0;
+const exceptions_1 = require("../exceptions");
+class Sound {
+    constructor(parent, { id, data } = {}) {
+        this.parent = parent;
+        if (data) {
+            this.asDict = data;
+            this._extractFromData();
+        }
+        else if (id == null) {
+            throw new TypeError("You must provide id parameter.");
+        }
+        else {
+            this.id = id;
+        }
+    }
+    /**
+     * Returns all information sent by TikTok related to this sound.
+     *
+     * @example
+     * ```ts
+     * const soundInfo = await api.sound({ id: '7016547803243022337' }).info();
+     * ```
+     */
+    async info(kwargs = {}) {
+        const id = this.id;
+        if (!id) {
+            throw new TypeError("You must provide the id when creating this class to use this method.");
+        }
+        const urlParams = {
+            msToken: kwargs.msToken,
+            musicId: id,
+        };
+        const resp = await this.parent.makeRequest({
+            url: "https://www.tiktok.com/api/music/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 videos created with this sound.
+     *
+     * @example
+     * ```ts
+     * for await (const video of api.sound({ id: '7016547803243022337' }).videos()) {
+     *   console.log(video.id);
+     * }
+     * ```
+     */
+    async *videos(count = 30, cursor = 0, kwargs = {}) {
+        const id = this.id;
+        if (!id) {
+            throw new TypeError("You must provide the id when creating this class to use this method.");
+        }
+        let found = 0;
+        while (found < count) {
+            const params = {
+                musicID: id,
+                count: 30,
+                cursor,
+            };
+            const resp = await this.parent.makeRequest({
+                url: "https://www.tiktok.com/api/music/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("musicInfo")) {
+            const musicInfo = data["musicInfo"];
+            const author = musicInfo["author"];
+            if (typeof author === "object" && author !== null) {
+                this.author = this.parent.user({ data: author });
+            }
+            else if (typeof author === "string") {
+                this.author = this.parent.user({ username: author });
+            }
+            const music = musicInfo["music"];
+            if (music) {
+                this.title = music["title"];
+                this.id = music["id"];
+                this.original = music["original"];
+                this.playUrl = music["playUrl"];
+                this.coverLarge = music["coverLarge"];
+                this.duration = music["duration"];
+            }
+        }
+        if (keys.includes("music")) {
+            const music = data["music"];
+            this.title = music["title"];
+            this.id = music["id"];
+            this.original = music["original"];
+            this.playUrl = music["playUrl"];
+            this.coverLarge = music["coverLarge"];
+            this.duration = music["duration"];
+        }
+        if (!this.id) {
+            this.parent.logger.error(`Failed to create Sound with data: ${JSON.stringify(data)}`);
+        }
+    }
+    toString() {
+        return `TikTokApi.sound(id='${this.id}')`;
+    }
+}
+exports.Sound = Sound;

package/dist/api/trending.d.ts

@@ -0,0 +1,21 @@
+import type { TikTokApi } from "../tiktok";
+import type { Video } from "./video";
+export declare class Trending {
+    /** Static reference to the parent TikTokApi instance */
+    parent: TikTokApi;
+    constructor(parent: TikTokApi);
+    /**
+     * Returns Videos that are trending on TikTok.
+     *
+     * @example
+     * ```ts
+     * for await (const video of api.trending.videos()) {
+     *   console.log(video.id);
+     * }
+     * ```
+     */
+    videos(count?: number, kwargs?: {
+        headers?: Record<string, string>;
+        sessionIndex?: number;
+    }): AsyncGenerator<Video>;
+}

package/dist/api/trending.js

@@ -0,0 +1,52 @@
+"use strict";
+// ============================================================
+// api/trending.ts
+// Mirrors TikTokApi/api/trending.py
+// ============================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Trending = void 0;
+const exceptions_1 = require("../exceptions");
+class Trending {
+    constructor(parent) {
+        this.parent = parent;
+    }
+    /**
+     * Returns Videos that are trending on TikTok.
+     *
+     * @example
+     * ```ts
+     * for await (const video of api.trending.videos()) {
+     *   console.log(video.id);
+     * }
+     * ```
+     */
+    async *videos(count = 30, kwargs = {}) {
+        let found = 0;
+        while (found < count) {
+            const batchSize = Math.min(count - found, 30);
+            const params = {
+                from_page: "fyp",
+                count: batchSize,
+            };
+            const resp = await this.parent.makeRequest({
+                url: "https://www.tiktok.com/api/recommend/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"] ?? [];
+            if (itemList.length === 0)
+                return; // If no items returned, stop to avoid infinite loop
+            for (const item of itemList) {
+                yield this.parent.video({ data: item });
+                found++;
+            }
+            if (!resp["hasMore"])
+                return;
+        }
+    }
+}
+exports.Trending = Trending;

package/dist/api/user.d.ts

@@ -0,0 +1,187 @@
+import type { TikTokApi } from "../tiktok";
+import type { Video } from "./video";
+import type { Playlist } from "./playlist";
+export interface UserOptions {
+    username?: string | null;
+    userId?: string | null;
+    secUid?: string | null;
+    data?: Record<string, unknown> | null;
+}
+export declare class User {
+    /** Static reference to the parent TikTokApi instance */
+    parent: TikTokApi;
+    /** The ID of the user */
+    userId?: string;
+    /** The secondary UID of the user */
+    secUid?: string;
+    /** The username of the user */
+    username?: string;
+    /** The raw data associated with this user */
+    asDict?: Record<string, unknown>;
+    constructor(parent: TikTokApi, { username, userId, secUid, data }?: UserOptions);
+    /**
+     * Returns whether the user is currently live on TikTok.
+     * Based on the presence of a non-zero roomId in the user info data.
+     */
+    get isLive(): boolean;
+    /**
+     * Returns the roomId of the user if they are currently live on TikTok.
+     * Returns null if they are not live.
+     */
+    get roomId(): string | null;
+    /** Gets the user's display name */
+    get nickname(): string | null;
+    /** Gets the user's bio / signature */
+    get signature(): string | null;
+    /** Gets whether the user is a verified account */
+    get verified(): boolean;
+    /** Gets whether the user has a private account */
+    get isPrivate(): boolean;
+    /** Gets the user's follower count */
+    get followers(): number;
+    /** Gets the user's following count */
+    get following(): number;
+    /** Gets the user's total likes (hearts) */
+    get likes(): number;
+    /** Gets the user's total video count */
+    get videoCount(): number;
+    /** Gets the user's link in bio */
+    get bioLink(): string | null;
+    /** Gets the user's profile picture URL (largest available) */
+    get avatar(): string | null;
+    private _extractUserInfoValue;
+    private _extractUserStatsValue;
+    /**
+     * Returns a dictionary of information associated with this User.
+     *
+     * @example
+     * ```ts
+     * const userData = await api.user({ username: 'therock' }).info();
+     * ```
+     */
+    info(kwargs?: {
+        msToken?: string;
+        headers?: Record<string, string>;
+        sessionIndex?: number;
+    }): Promise<Record<string, unknown>>;
+    /**
+     * Returns a user's playlists.
+     *
+     * @example
+     * ```ts
+     * for await (const playlist of api.user({ username: 'therock' }).playlists()) {
+     *   console.log(playlist.name);
+     * }
+     * ```
+     */
+    playlists(count?: number, cursor?: number, kwargs?: {
+        headers?: Record<string, string>;
+        sessionIndex?: number;
+    }): AsyncGenerator<Playlist>;
+    /**
+     * Returns a user's videos.
+     *
+     * @example
+     * ```ts
+     * for await (const video of api.user({ username: 'davidteathercodes' }).videos()) {
+     *   console.log(video.id);
+     * }
+     * ```
+     */
+    videos(count?: number, cursor?: number, kwargs?: {
+        headers?: Record<string, string>;
+        sessionIndex?: number;
+    }): AsyncGenerator<Video>;
+    /**
+     * Returns a user's pinned videos.
+     *
+     * @example
+     * ```ts
+     * for await (const video of api.user({ username: 'davidteathercodes' }).pinned()) {
+     *   console.log(video.id);
+     * }
+     * ```
+     */
+    pinned(count?: number, kwargs?: {
+        headers?: Record<string, string>;
+        sessionIndex?: number;
+    }): AsyncGenerator<Video>;
+    /**
+     * Returns a user's liked posts (if public).
+     *
+     * @example
+     * ```ts
+     * for await (const like of api.user({ username: 'davidteathercodes' }).liked()) {
+     *   console.log(like.id);
+     * }
+     * ```
+     */
+    liked(count?: number, cursor?: number, kwargs?: {
+        headers?: Record<string, string>;
+        sessionIndex?: number;
+    }): AsyncGenerator<Video>;
+    /**
+     * Returns a user's reposted videos (if available).
+     * Note: TikTok might restrict visibility based on authentication or region.
+     *
+     * @example
+     * ```ts
+     * for await (const repost of api.user({ username: 'davidteathercodes' }).reposts()) {
+     *   console.log(repost.id);
+     * }
+     * ```
+     */
+    reposts(count?: number, cursor?: number, kwargs?: {
+        headers?: Record<string, string>;
+        sessionIndex?: number;
+    }): AsyncGenerator<Video>;
+    /**
+     * Returns a user's favorited/bookmarked videos (Collections).
+     * Note: This relies entirely on the user's privacy settings.
+     *
+     * @example
+     * ```ts
+     * for await (const fav of api.user({ username: 'davidteathercodes' }).favorited()) {
+     *   console.log(fav.id);
+     * }
+     * ```
+     */
+    favorited(count?: number, cursor?: number, kwargs?: {
+        headers?: Record<string, string>;
+        sessionIndex?: number;
+    }): AsyncGenerator<Video>;
+    /**
+     * Returns a user's followers list.
+     * Note: This endpoint is heavily guarded and usually requires a logged-in session (cookies).
+     * It may also quickly return errors or bot challenges.
+     *
+     * @example
+     * ```ts
+     * for await (const follower of api.user({ username: 'davidteathercodes' }).followersList()) {
+     *   console.log(follower.username);
+     * }
+     * ```
+     */
+    followersList(count?: number, cursor?: number, kwargs?: {
+        headers?: Record<string, string>;
+        sessionIndex?: number;
+    }): AsyncGenerator<User>;
+    /**
+     * Returns a user's following list.
+     * Note: Like followers, this is heavily guarded and requires authentication.
+     *
+     * @example
+     * ```ts
+     * for await (const following of api.user({ username: 'davidteathercodes' }).followingList()) {
+     *   console.log(following.username);
+     * }
+     * ```
+     */
+    followingList(count?: number, cursor?: number, kwargs?: {
+        headers?: Record<string, string>;
+        sessionIndex?: number;
+    }): AsyncGenerator<User>;
+    private _extractFromData;
+    private _updateIdSecUidUsername;
+    toString(): string;
+}