untiktok-api 1.0.0

package/dist/api/user.js

@@ -0,0 +1,498 @@
+"use strict";
+// ============================================================
+// api/user.ts
+// Mirrors TikTokApi/api/user.py
+// ============================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.User = void 0;
+const exceptions_1 = require("../exceptions");
+class User {
+    constructor(parent, { username, userId, secUid, data } = {}) {
+        this.parent = parent;
+        this._updateIdSecUidUsername(userId, secUid, username);
+        if (data) {
+            this.asDict = data;
+            this._extractFromData();
+        }
+    }
+    /**
+     * 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() {
+        return this.roomId !== null;
+    }
+    /**
+     * Returns the roomId of the user if they are currently live on TikTok.
+     * Returns null if they are not live.
+     */
+    get roomId() {
+        const data = this.asDict ?? {};
+        // Check inside userInfo.user
+        if (data["userInfo"]) {
+            const user = data["userInfo"]["user"];
+            if (user) {
+                if (user["roomId"] && user["roomId"] !== "0" && user["roomId"] !== 0) {
+                    return String(user["roomId"]);
+                }
+                if (user["room_id"] && user["room_id"] !== "0" && user["room_id"] !== 0) {
+                    return String(user["room_id"]);
+                }
+            }
+        }
+        // Check root level
+        if (data["roomId"] && data["roomId"] !== "0" && data["roomId"] !== 0) {
+            return String(data["roomId"]);
+        }
+        if (data["room_id"] && data["room_id"] !== "0" && data["room_id"] !== 0) {
+            return String(data["room_id"]);
+        }
+        // Check if roomData exists (fallback)
+        if (data["roomData"] || data["room_data"]) {
+            return "unknown_room_id";
+        }
+        return null;
+    }
+    /** Gets the user's display name */
+    get nickname() {
+        return this._extractUserInfoValue("nickname");
+    }
+    /** Gets the user's bio / signature */
+    get signature() {
+        return this._extractUserInfoValue("signature");
+    }
+    /** Gets whether the user is a verified account */
+    get verified() {
+        return Boolean(this._extractUserInfoValue("verified"));
+    }
+    /** Gets whether the user has a private account */
+    get isPrivate() {
+        return Boolean(this._extractUserInfoValue("privateAccount"));
+    }
+    /** Gets the user's follower count */
+    get followers() {
+        return this._extractUserStatsValue("followerCount") || 0;
+    }
+    /** Gets the user's following count */
+    get following() {
+        return this._extractUserStatsValue("followingCount") || 0;
+    }
+    /** Gets the user's total likes (hearts) */
+    get likes() {
+        return this._extractUserStatsValue("heartCount") || 0;
+    }
+    /** Gets the user's total video count */
+    get videoCount() {
+        return this._extractUserStatsValue("videoCount") || 0;
+    }
+    /** Gets the user's link in bio */
+    get bioLink() {
+        const bioLinkObj = this._extractUserInfoValue("bioLink");
+        return bioLinkObj?.link ?? null;
+    }
+    /** Gets the user's profile picture URL (largest available) */
+    get avatar() {
+        return this._extractUserInfoValue("avatarLarger") ||
+            this._extractUserInfoValue("avatarMedium") ||
+            this._extractUserInfoValue("avatarThumb") || null;
+    }
+    _extractUserInfoValue(key) {
+        const data = this.asDict ?? {};
+        if (data["userInfo"]) {
+            const user = data["userInfo"]["user"];
+            if (user && user[key] !== undefined)
+                return user[key];
+        }
+        return data[key] ?? null;
+    }
+    _extractUserStatsValue(key) {
+        const data = this.asDict ?? {};
+        if (data["userInfo"]) {
+            const stats = data["userInfo"]["stats"];
+            if (stats && stats[key] !== undefined)
+                return stats[key];
+        }
+        if (data["stats"]) {
+            const stats = data["stats"];
+            if (stats[key] !== undefined)
+                return stats[key];
+        }
+        return data[key] ?? null;
+    }
+    /**
+     * Returns a dictionary of information associated with this User.
+     *
+     * @example
+     * ```ts
+     * const userData = await api.user({ username: 'therock' }).info();
+     * ```
+     */
+    async info(kwargs = {}) {
+        const username = this.username;
+        if (!username) {
+            throw new TypeError("You must provide the username when creating this class to use this method.");
+        }
+        const urlParams = {
+            secUid: this.secUid ?? "",
+            uniqueId: username,
+            msToken: kwargs.msToken,
+        };
+        const resp = await this.parent.makeRequest({
+            url: "https://www.tiktok.com/api/user/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 a user's playlists.
+     *
+     * @example
+     * ```ts
+     * for await (const playlist of api.user({ username: 'therock' }).playlists()) {
+     *   console.log(playlist.name);
+     * }
+     * ```
+     */
+    async *playlists(count = 20, cursor = 0, kwargs = {}) {
+        if (!this.secUid) {
+            await this.info(kwargs);
+        }
+        let found = 0;
+        while (found < count) {
+            const params = {
+                secUid: this.secUid,
+                count: Math.min(count, 30),
+                cursor,
+            };
+            const resp = await this.parent.makeRequest({
+                url: "https://www.tiktok.com/api/user/playlist",
+                params,
+                headers: kwargs.headers,
+                sessionIndex: kwargs.sessionIndex,
+            });
+            if (resp == null) {
+                throw new exceptions_1.InvalidResponseException(resp, "TikTok returned an invalid response.");
+            }
+            const playList = resp["playList"] ?? [];
+            for (const pl of playList) {
+                yield this.parent.playlist({ data: pl });
+                found++;
+            }
+            if (!resp["hasMore"])
+                return;
+            cursor = resp["cursor"];
+        }
+    }
+    /**
+     * Returns a user's videos.
+     *
+     * @example
+     * ```ts
+     * for await (const video of api.user({ username: 'davidteathercodes' }).videos()) {
+     *   console.log(video.id);
+     * }
+     * ```
+     */
+    async *videos(count = 30, cursor = 0, kwargs = {}) {
+        if (!this.secUid) {
+            await this.info(kwargs);
+        }
+        let found = 0;
+        while (found < count) {
+            const params = {
+                secUid: this.secUid,
+                count: 30,
+                cursor,
+            };
+            const resp = await this.parent.makeRequest({
+                url: "https://www.tiktok.com/api/post/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"];
+        }
+    }
+    /**
+     * Returns a user's pinned videos.
+     *
+     * @example
+     * ```ts
+     * for await (const video of api.user({ username: 'davidteathercodes' }).pinned()) {
+     *   console.log(video.id);
+     * }
+     * ```
+     */
+    async *pinned(count = 3, kwargs = {}) {
+        // Pinned videos are always sent at the top of the videos feed
+        // We fetch a batch of videos and explicitly filter for pinned flags
+        let found = 0;
+        // We only need to check the first few videos since pinned are always at top
+        for await (const video of this.videos(10, 0, kwargs)) {
+            const data = video.asDict ?? {};
+            const isPinned = data["isPinned"] === true ||
+                data["is_pinned"] === true ||
+                data["isTop"] === true ||
+                data["is_top"] === true ||
+                data["isTopItem"] === true ||
+                data["is_top_item"] === true;
+            if (isPinned) {
+                yield video;
+                found++;
+                if (found >= count)
+                    break;
+            }
+        }
+    }
+    /**
+     * Returns a user's liked posts (if public).
+     *
+     * @example
+     * ```ts
+     * for await (const like of api.user({ username: 'davidteathercodes' }).liked()) {
+     *   console.log(like.id);
+     * }
+     * ```
+     */
+    async *liked(count = 30, cursor = 0, kwargs = {}) {
+        if (!this.secUid) {
+            await this.info(kwargs);
+        }
+        let found = 0;
+        while (found < count) {
+            const params = {
+                secUid: this.secUid,
+                count: 30,
+                cursor,
+            };
+            const resp = await this.parent.makeRequest({
+                url: "https://www.tiktok.com/api/favorite/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"];
+        }
+    }
+    /**
+     * 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);
+     * }
+     * ```
+     */
+    async *reposts(count = 30, cursor = 0, kwargs = {}) {
+        if (!this.secUid) {
+            await this.info(kwargs);
+        }
+        // "well now you can stalk your crush repost without knowing" - Al Ghozali Ramadhan
+        let found = 0;
+        while (found < count) {
+            const params = {
+                secUid: this.secUid,
+                count: 30,
+                cursor,
+            };
+            const resp = await this.parent.makeRequest({
+                url: "https://www.tiktok.com/api/repost/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"];
+        }
+    }
+    /**
+     * 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);
+     * }
+     * ```
+     */
+    async *favorited(count = 30, cursor = 0, kwargs = {}) {
+        if (!this.secUid) {
+            await this.info(kwargs);
+        }
+        let found = 0;
+        while (found < count) {
+            const params = {
+                secUid: this.secUid,
+                count: 30,
+                cursor,
+            };
+            const resp = await this.parent.makeRequest({
+                url: "https://www.tiktok.com/api/user/collect/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"];
+        }
+    }
+    /**
+     * 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);
+     * }
+     * ```
+     */
+    async *followersList(count = 30, cursor = 0, kwargs = {}) {
+        if (!this.secUid) {
+            await this.info(kwargs);
+        }
+        let found = 0;
+        while (found < count) {
+            const params = {
+                secUid: this.secUid,
+                count: 30,
+                minCursor: cursor,
+                maxCursor: cursor,
+            };
+            const resp = await this.parent.makeRequest({
+                url: "https://www.tiktok.com/api/user/list/",
+                params,
+                headers: kwargs.headers,
+                sessionIndex: kwargs.sessionIndex,
+            });
+            if (resp == null) {
+                throw new exceptions_1.InvalidResponseException(resp, "TikTok returned an invalid response.");
+            }
+            const userList = resp["userList"] ?? [];
+            for (const item of userList) {
+                yield this.parent.user({ data: item });
+                found++;
+            }
+            if (!resp["hasMore"])
+                return;
+            cursor = resp["minCursor"] || resp["maxCursor"];
+        }
+    }
+    /**
+     * 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);
+     * }
+     * ```
+     */
+    async *followingList(count = 30, cursor = 0, kwargs = {}) {
+        if (!this.secUid) {
+            await this.info(kwargs);
+        }
+        let found = 0;
+        while (found < count) {
+            const params = {
+                secUid: this.secUid,
+                count: 30,
+                minCursor: cursor,
+                maxCursor: cursor,
+            };
+            const resp = await this.parent.makeRequest({
+                url: "https://www.tiktok.com/api/user/following/",
+                params,
+                headers: kwargs.headers,
+                sessionIndex: kwargs.sessionIndex,
+            });
+            if (resp == null) {
+                throw new exceptions_1.InvalidResponseException(resp, "TikTok returned an invalid response.");
+            }
+            const userList = resp["userList"] ?? [];
+            for (const item of userList) {
+                yield this.parent.user({ data: item });
+                found++;
+            }
+            if (!resp["hasMore"])
+                return;
+            cursor = resp["minCursor"] || resp["maxCursor"];
+        }
+    }
+    _extractFromData() {
+        const data = this.asDict ?? {};
+        const keys = Object.keys(data);
+        if (keys.includes("userInfo")) {
+            const userInfo = data["userInfo"]["user"];
+            this._updateIdSecUidUsername(userInfo["id"], userInfo["secUid"], userInfo["uniqueId"]);
+        }
+        else {
+            this._updateIdSecUidUsername(data["id"], data["secUid"], data["uniqueId"]);
+        }
+        if (!this.username || !this.userId || !this.secUid) {
+            this.parent.logger.error(`Failed to create User with data: ${JSON.stringify(data)}`);
+        }
+    }
+    _updateIdSecUidUsername(id, secUid, username) {
+        if (id != null)
+            this.userId = id;
+        if (secUid != null)
+            this.secUid = secUid;
+        if (username != null)
+            this.username = username;
+    }
+    toString() {
+        return `TikTokApi.user(username='${this.username}', user_id='${this.userId}', sec_uid='${this.secUid}')`;
+    }
+}
+exports.User = User;

package/dist/api/video.d.ts

@@ -0,0 +1,119 @@
+import type { TikTokApi } from "../tiktok";
+import type { User } from "./user";
+import type { Sound } from "./sound";
+import type { Hashtag } from "./hashtag";
+import type { Comment } from "./comment";
+export interface VideoOptions {
+    id?: string | null;
+    url?: string | null;
+    data?: Record<string, unknown> | null;
+    sessionIndex?: number;
+    proxy?: string | null;
+}
+export declare class Video {
+    /** Static reference to the parent TikTokApi instance */
+    parent: TikTokApi;
+    /** TikTok's ID of the Video */
+    id?: string;
+    /** The URL of the Video */
+    url?: string;
+    /** The creation time of the Video */
+    createTime?: Date;
+    /** TikTok's stats for the Video */
+    stats?: Record<string, unknown>;
+    /** The User who created the Video */
+    author?: User;
+    /** The Sound associated with the Video */
+    sound?: Sound;
+    /** A list of Hashtags on the Video */
+    hashtags?: Hashtag[];
+    /** The raw data associated with this Video */
+    asDict?: Record<string, unknown>;
+    /** Gets the description/caption of the video */
+    get description(): string | null;
+    /** Gets the play/view count of the video */
+    get plays(): number;
+    /** Gets the digg/like count of the video */
+    get likes(): number;
+    /** Gets the comment count of the video */
+    get commentsCount(): number;
+    /** Gets the share count of the video */
+    get shares(): number;
+    /** Gets the collect/save count of the video */
+    get saves(): number;
+    /** Gets whether the video is pinned by the creator */
+    get isPinned(): boolean;
+    constructor(parent: TikTokApi, { id, url, data, sessionIndex, proxy }?: VideoOptions);
+    /**
+     * Async factory that follows redirects to resolve the video ID from a short URL.
+     * Use this instead of `new Video({ url })` when you have a short/redirect URL.
+     */
+    static fromUrl(parent: TikTokApi, url: string, kwargs?: {
+        sessionIndex?: number;
+        proxy?: string;
+    }): Promise<Video>;
+    /**
+     * Returns a dictionary of all data associated with a TikTok Video.
+     * Note: This is slow since it requires an HTTP request.
+     *
+     * Python uses `requests.get`; TS uses `axios.get` (equivalent sync-style).
+     *
+     * @example
+     * ```ts
+     * const info = await api.video({ url: 'https://www.tiktok.com/@.../video/...' }).info();
+     * ```
+     */
+    info(kwargs?: {
+        headers?: Record<string, string>;
+        sessionIndex?: number;
+        proxy?: string;
+    }): Promise<Record<string, unknown>>;
+    /**
+     * Returns the raw bytes of a TikTok Video.
+     *
+     * Python uses `requests.get` / `httpx.AsyncClient` for streaming.
+     * TS uses `axios` equivalents.
+     *
+     * @example
+     * ```ts
+     * const buf = await video.bytes() as Buffer;
+     * fs.writeFileSync('video.mp4', buf);
+     *
+     * // Streaming
+     * for await (const chunk of await video.bytes({ stream: true }) as AsyncGenerator<Buffer>) { ... }
+     * ```
+     */
+    bytes(options?: {
+        stream?: boolean;
+    } & Record<string, unknown>): Promise<Buffer | AsyncGenerator<Buffer>>;
+    /**
+     * Returns the comments of a TikTok Video.
+     *
+     * Python key: `has_more` (snake_case) — preserved in TS.
+     *
+     * @example
+     * ```ts
+     * for await (const comment of video.comments(20)) { ... }
+     * ```
+     */
+    comments(count?: number, cursor?: number, kwargs?: {
+        headers?: Record<string, string>;
+        sessionIndex?: number;
+    }): AsyncGenerator<Comment>;
+    /**
+     * Returns related videos of a TikTok Video.
+     * Note: Python's related_videos does NOT increment `found` after the inner loop — bug or intentional.
+     * We preserve that exact behaviour (no double-increment).
+     *
+     * @example
+     * ```ts
+     * for await (const rel of video.relatedVideos(30)) { ... }
+     * ```
+     */
+    relatedVideos(count?: number, cursor?: number, kwargs?: {
+        headers?: Record<string, string>;
+        sessionIndex?: number;
+    }): AsyncGenerator<Video>;
+    private _extractFromData;
+    toString(): string;
+}